# NotificationCommand（通知指令）Requirements

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

---

## Version History

v0.1.0: 初稿，覆盖核心通知类型与调用行为（对应产品 v0.1.0）
v0.2.0: 新增自定义消息文本支持（对应产品 v1.1.0）

---

## Noun Definition

**通知指令（NotificationCommand）**：一次 `horn` 命令调用的完整执行单元。代表 agent 或用户触发的单条语音通知请求，包含通知类型、播报文本及执行结果。每次命令调用对应一个通知指令实例，执行完毕后即销毁，不持久化存储。

---

## Attributes

- **通知类型（Notification Type）**：
  - `type`：本次通知的类型，枚举值，决定默认播报文本
    - `verify`：验证安装，对应播报文本「Horn 已就绪，等待任务通知」，由裸命令 `horn` 触发
    - `start`：任务开始，对应播报文本「老板，我开始执行任务了」，由 `horn --start` 触发
    - `done`：任务完成，对应播报文本「老板，任务已完成」，由 `horn --done` 触发
    - `confirm`：需要确认，对应播报文本「老板，有事情需要你确认」，由 `horn --confirm` 触发

- **播报文本（Message）**：
  - `message`：实际传递给 TTS 引擎的文本内容，可为空（空时使用 `type` 对应的预设文本）
  - `resolved_text`：最终确定的播报文本，由系统在执行前解析得出（优先级：`message` 参数 > 配置文件预设文本 > 内置默认文本）

- **执行结果（Result）**：
  - `success`：布尔值，TTS 播报是否成功完成
  - `error_message`：失败时的错误描述，成功时为空；内容示例：「Windows SAPI 不可用」、「消息内容不能为空」

---

## Behaviors

### 1 解析（Resolve）

**触发条件**：用户或 agent 执行 `horn` 命令，携带零个或一个通知类型参数（`--start` / `--done` / `--confirm`），以及可选的 `--message` 参数。

**解析规则**：
1. 无任何参数 → `type = verify`
2. 有 `--start` → `type = start`
3. 有 `--done` → `type = done`
4. 有 `--confirm` → `type = confirm`
5. 有 `--message <text>` → `message = text`（需与通知类型参数组合使用，或单独使用）
6. 存在未定义的参数 → 解析失败，输出错误提示，退出码 1，不进入执行阶段

**冲突规则**：同时传入多个通知类型参数（如 `horn --start --done`）时，解析失败，向 stderr 输出「不能同时指定多个通知类型」，退出码 1。

### 2 执行（Execute）

**触发条件**：Resolve 阶段成功，`resolved_text` 已确定。

**执行逻辑**：
1. 调用 Windows SAPI TTS 引擎，将 `resolved_text` 转换为语音播报
2. 播报为同步阻塞操作，播报完成后进程退出
3. 播报成功 → `success = true`，进程退出码 0
4. SAPI 不可用或播报失败 → `success = false`，向 stderr 输出错误描述，退出码 1

**文本为空的处理**：若 `--message` 参数后跟空字符串或纯空白字符，则 `message` 视为未提供，回退使用 `type` 对应的预设文本；若 `type` 同时也为空（即不合法状态），则输出错误，退出码 1。

### 3 错误边界

- `horn` 命令执行时长不应超过 5 秒；若 TTS 引擎在 5 秒内未完成播报，强制终止并输出超时错误，退出码 1
- 任何情况下，`horn` 命令不得以静默方式失败（即失败时必须有 stderr 输出）
- 不支持并发执行（同时调用多个 `horn` 进程时，各进程独立运行，系统不做互斥处理）
