# Feature List

> Date: 2026/03/08
> Author: Horn Team

---

> **层级结构说明**：
> - **模块**：功能区域，描述该模块整体提供的能力
>   - **一级功能**：模块内的主要功能单元
>     - **二级功能**（最深层）：描述精确的交互/调用逻辑

---

## v0.1.0 — Windows CLI 核心播报能力

- **CLI 命令模块**：提供 `horn` 命令行入口，支持通过不同参数触发对应的中文语音播报
  - **验证播报**：用于确认 Horn 安装成功
    - **裸命令执行**：用户执行 `horn`（不带任何参数）时，调用 Windows SAPI TTS 播报「Horn 已就绪，等待任务通知」；播报完成后进程正常退出，退出码为 0；若 SAPI 不可用，向 stderr 输出错误信息，退出码为 1
  - **任务开始通知**：触发"任务开始"语音播报
    - **--start 参数**：用户或 agent 执行 `horn --start` 时，调用 Windows SAPI TTS 播报「老板，我开始执行任务了」；播报完成后进程正常退出，退出码为 0；若 SAPI 不可用，向 stderr 输出错误信息，退出码为 1
  - **任务完成通知**：触发"任务完成"语音播报
    - **--done 参数**：用户或 agent 执行 `horn --done` 时，调用 Windows SAPI TTS 播报「老板，任务已完成」；播报完成后进程正常退出，退出码为 0；若 SAPI 不可用，向 stderr 输出错误信息，退出码为 1
  - **需要确认通知**：触发"需要确认"语音播报
    - **--confirm 参数**：用户或 agent 执行 `horn --confirm` 时，调用 Windows SAPI TTS 播报「老板，有事情需要你确认」；播报完成后进程正常退出，退出码为 0；若 SAPI 不可用，向 stderr 输出错误信息，退出码为 1
  - **无效参数处理**：
    - **未知参数**：用户传入未定义的参数时，向 stderr 输出提示「未知参数，请使用 horn --start / --done / --confirm」，退出码为 1，不触发任何语音播报

---

## v0.2.0 — Cursor Rules 自动触发集成

- **Cursor Rules 模板模块**：提供可直接使用的 Cursor Rules 配置文件，无需开发者手动编写规则
  - **Rules 模板文件**：提供预编写好的 `.mdc` 规则文件（`horn.mdc`）
    - **任务开始触发规则**：规则内容约定 agent 在接收到新任务、开始执行前，必须调用 `horn --start`；规则以自然语言写成，agent 可理解并遵守
    - **任务完成触发规则**：规则内容约定 agent 在完成全部任务输出后，必须调用 `horn --done`；规则以自然语言写成
    - **需要确认触发规则**：规则内容约定 agent 在执行过程中遇到需要用户决策的节点时，必须调用 `horn --confirm` 再等待；规则以自然语言写成
  - **安装与配置说明**：
    - **放置路径说明**：README 中说明将 `horn.mdc` 复制到项目的 `.cursor/rules/` 目录或 Cursor 全局 Rules 目录；提供两种路径选项的适用场景说明（项目级 vs 全局）
    - **验证方法说明**：README 中说明如何通过下达一个简单测试任务来验证 Rules 是否生效，以及未生效时的常见原因排查步骤

---

## v1.0.0 — 文档完善与发布

- **文档模块**：提供完整的使用文档，覆盖安装、配置、验证、排查全流程
  - **README**：
    - **产品介绍**：一句话说明 Horn 是什么、解决什么问题
    - **快速开始**：3 步完成安装和配置（pip install → 复制 Rules → 验证）
    - **命令参数说明**：列举 `--start`、`--done`、`--confirm` 三个参数及其播报内容
    - **常见问题（FAQ）**：覆盖安装失败、无声音、Rules 不生效三类常见问题，每类提供 2～3 个排查步骤

---

## v1.1.0 — 动态消息文本支持

- **CLI 命令模块（扩展）**：在现有参数基础上新增 `--message` 参数，支持 agent 传入自定义播报文本
  - **--message 参数**：
    - **与通知类型参数组合使用**：agent 执行 `horn --done --message "登录模块重构完成"` 时，TTS 播报传入的 message 文本内容而非预设文本；message 为必填字符串，不得为空
    - **单独使用 --message**：用户执行 `horn --message "自定义内容"` 时，直接播报 message 文本；不需要同时传入通知类型参数
    - **message 为空时的处理**：若 `--message` 后未跟文本或文本为空字符串，向 stderr 输出「消息内容不能为空」，退出码为 1，不触发播报

---

## v1.2.0 — 配置文件支持

- **配置文件模块**：用户可通过 YAML 配置文件自定义预设文本和播报参数
  - **配置文件读取**：
    - **配置文件路径**：Horn 启动时按顺序查找配置文件：`./horn.yaml`（当前目录）→ `~/.horn/config.yaml`（用户目录）；找到第一个即使用，均不存在则使用内置默认值
  - **可配置项**：
    - **预设文本配置**：用户可在配置文件中覆盖 start / done / confirm 三种通知的播报文本
    - **语速配置**：用户可设置 TTS 语速（整数，范围 -10 ～ 10，默认 0）；超出范围时使用默认值并输出警告
    - **音量配置**：用户可设置 TTS 音量（整数，范围 0 ～ 100，默认 100）；超出范围时使用默认值并输出警告
    - **配置文件格式错误处理**：YAML 格式错误时向 stderr 输出「配置文件格式错误，使用默认配置」，不中断程序执行
