# Config（用户配置）Requirements

> 本文档定义系统中实体对象的属性与行为，直接指导代码开发工作。
> AI Agent 在协助开发时不得偏离本文档内容，偏离即视为错误。

> **适用版本**：本实体自产品 v1.2.0 起引入，v0.1.0 ～ v1.1.0 不存在此实体，使用内置默认值。

---

## Version History

v0.1.0: 初稿，定义配置文件结构与加载行为（对应产品 v1.2.0）

---

## Noun Definition

**用户配置（Config）**：用户通过 YAML 配置文件对 Horn 的行为进行自定义的配置集合。Config 在每次 `horn` 命令启动时被读取和加载，用于覆盖内置默认值；未配置的项保持内置默认值。Config 不持久化至数据库，仅从文件系统读取。

---

## Attributes

- **预设文本（Preset Messages）**：
  - `message_verify`：覆盖"验证安装"通知的播报文本，可为空（空时使用内置默认文本「Horn 已就绪，等待任务通知」）
  - `message_start`：覆盖"任务开始"通知的播报文本，可为空（空时使用内置默认文本「老板，我开始执行任务了」）
  - `message_done`：覆盖"任务完成"通知的播报文本，可为空（空时使用内置默认文本「老板，任务已完成」）
  - `message_confirm`：覆盖"需要确认"通知的播报文本，可为空（空时使用内置默认文本「老板，有事情需要你确认」）

- **TTS 参数（TTS Parameters）**：
  - `rate`：语速，整数，范围 -10 ～ 10，默认值 0（0 为系统默认语速）
  - `volume`：音量，整数，范围 0 ～ 100，默认值 100

- **元数据（Metadata）**：
  - `source_path`：配置文件的实际加载路径，仅运行时存在，用于日志和排查

---

## Behaviors

### 1 加载（Load）

**触发条件**：每次执行 `horn` 命令时，在 Resolve 阶段开始前，系统自动尝试加载配置文件。

**查找顺序**（按优先级从高到低）：
1. 当前工作目录下的 `horn.yaml`
2. 用户主目录下的 `~/.horn/config.yaml`
3. 均不存在 → 使用全部内置默认值，不报错，正常继续执行

**加载规则**：
- 找到文件后读取并解析 YAML；解析成功则用文件中的值覆盖对应的内置默认值
- 文件存在但 YAML 格式错误 → 向 stderr 输出「配置文件格式错误，路径：{source_path}，使用默认配置」，不中断程序，使用全部内置默认值继续执行
- 文件存在但无读取权限 → 向 stderr 输出「无法读取配置文件，路径：{source_path}，使用默认配置」，不中断程序，使用全部内置默认值继续执行

### 2 校验（Validate）

**触发条件**：Config 加载成功后，对各字段值进行合法性校验。

**校验规则**：
- `rate` 不在 -10 ～ 10 范围内 → 向 stderr 输出「rate 值超出范围（-10～10），已使用默认值 0」，将 `rate` 重置为 0，继续执行
- `volume` 不在 0 ～ 100 范围内 → 向 stderr 输出「volume 值超出范围（0～100），已使用默认值 100」，将 `volume` 重置为 100，继续执行
- 预设文本字段为非字符串类型 → 向 stderr 输出「{字段名} 类型错误，已使用默认文本」，将该字段重置为内置默认文本，继续执行
- 所有校验错误均为非致命错误，不中断程序执行

### 3 优先级合并（Merge）

**触发条件**：Config 校验完成后，与 NotificationCommand 的 Resolve 阶段协作，确定最终 `resolved_text`。

**优先级规则**（从高到低）：
1. 命令行 `--message` 参数传入的文本
2. Config 中对应 `type` 的预设文本（若已配置且非空）
3. 系统内置的默认文本

**说明**：Merge 行为不单独暴露为命令，是 NotificationCommand 执行链的内部步骤。
