# UI Structure

> Date: 2026/03/08
> Author: Horn Team
> Interface Type: CLI

---

> **说明**：Horn 是纯命令行工具，无图形界面。
> 本文档定义 CLI 的命令结构、终端输出格式，以及 Cursor Rules 配置文件的内容结构。
> "页面"对应不同命令调用场景下，用户在终端中看到的内容。

---

## Navigation Flow（命令执行路径）

```mermaid
flowchart TD
    A([用户 / agent 调用 horn 命令]) --> B{参数解析}

    B -- 无参数 --> C[执行验证播报\nhhorn]
    B -- --start --> D[执行任务开始播报\nhorn --start]
    B -- --done --> E[执行任务完成播报\nhorn --done]
    B -- --confirm --> F[执行需确认播报\nhorn --confirm]
    B -- --message text --> G[执行自定义文本播报\nhorn --message text]
    B -- 通知类型 + --message --> H[执行带自定义文本的类型播报\nhhorn --done --message 自定义内容]
    B -- 未知参数 / 多类型冲突 --> I[输出错误信息到 stderr]

    C --> J{TTS 播报}
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J

    J -- 成功，5秒内完成 --> K([进程正常退出，退出码 0])
    J -- 失败 / 超时 --> L([输出错误到 stderr，退出码 1])
    I --> L
```

---

## Page Details（命令场景详情）

### Scene 1：裸命令 - 验证安装

- **Entry**：用户安装 Horn 后，在终端直接执行 `horn`
- **Main Content Areas**：
  - 无 stdout 输出（纯语音，终端保持静默）
  - TTS 播报：「Horn 已就绪，等待任务通知」
- **Exit**：播报完成，进程退出，退出码 0；终端光标回到输入行

---

### Scene 2：任务开始通知

- **Entry**：agent 按 Cursor Rules 规范执行 `horn --start`
- **Main Content Areas**：
  - 无 stdout 输出
  - TTS 播报：「老板，我开始执行任务了」
- **Exit**：播报完成，进程退出，退出码 0

---

### Scene 3：任务完成通知

- **Entry**：agent 按 Cursor Rules 规范执行 `horn --done`
- **Main Content Areas**：
  - 无 stdout 输出
  - TTS 播报：「老板，任务已完成」
- **Exit**：播报完成，进程退出，退出码 0

---

### Scene 4：需要确认通知

- **Entry**：agent 按 Cursor Rules 规范执行 `horn --confirm`
- **Main Content Areas**：
  - 无 stdout 输出
  - TTS 播报：「老板，有事情需要你确认」
- **Exit**：播报完成，进程退出，退出码 0

---

### Scene 5：自定义消息播报（v1.1.0）

- **Entry**：agent 执行 `horn --done --message "登录模块重构完成"` 或 `horn --message "任意自定义内容"`
- **Main Content Areas**：
  - 无 stdout 输出
  - TTS 播报：传入的 message 文本内容
- **Exit**：播报完成，进程退出，退出码 0

---

### Scene 6：错误场景 - 参数非法

- **Entry**：用户或 agent 传入未定义参数（如 `horn --xxx`）或多个通知类型参数（如 `horn --start --done`）
- **Main Content Areas**：
  - **stdout**：无输出
  - **stderr**：输出对应错误提示（见下方格式规范）
  - 无任何 TTS 播报
- **Exit**：进程退出，退出码 1

---

### Scene 7：错误场景 - TTS 失败 / 超时

- **Entry**：命令参数合法，但 Windows SAPI 不可用或播报超过 5 秒未完成
- **Main Content Areas**：
  - **stdout**：无输出
  - **stderr**：输出对应错误提示（见下方格式规范）
  - 无任何 TTS 播报（或播报被强制终止）
- **Exit**：进程退出，退出码 1

---

## stderr 输出格式规范

> 所有错误信息统一输出到 stderr，格式为纯文本，无颜色、无特殊符号，便于 agent 客户端捕获和解析。

| 错误场景 | stderr 输出内容 |
|----------|----------------|
| 传入未知参数 | `[Horn] 未知参数，请使用 horn --start / --done / --confirm` |
| 同时传入多个通知类型 | `[Horn] 不能同时指定多个通知类型` |
| --message 内容为空 | `[Horn] 消息内容不能为空` |
| Windows SAPI 不可用 | `[Horn] TTS 引擎不可用，请检查 Windows 语音服务是否已启用` |
| 播报超时（超过 5 秒） | `[Horn] 播报超时，已强制终止` |
| 配置文件格式错误（v1.2.0） | `[Horn] 配置文件格式错误，路径：{path}，使用默认配置` |
| 配置文件无读取权限（v1.2.0） | `[Horn] 无法读取配置文件，路径：{path}，使用默认配置` |

---

## Cursor Rules 模板内容结构（v0.2.0）

> `horn.mdc` 是交付给用户的 Cursor Rules 配置文件，也是用户与 Horn 集成时唯一需要手动接触的"界面"。

- **文件名**：`horn.mdc`
- **放置路径**：用户项目的 `.cursor/rules/horn.mdc`，或 Cursor 全局 Rules 目录
- **内容结构**：
  - 规则说明注释：简要说明此 Rules 文件的用途
  - 任务开始触发规则：约定 agent 在接收新任务、开始执行前调用 `horn --start`
  - 任务完成触发规则：约定 agent 在完成全部任务输出后调用 `horn --done`
  - 需要确认触发规则：约定 agent 在遇到需要用户决策时调用 `horn --confirm` 并等待
  - 异常说明注释：说明 agent 无需处理 horn 的退出码，忽略即可
