---
name: hotline-tdd
description: Use when implementing or fixing behavior in Hotline and you need to clarify acceptance criteria, choose the repository's real checks, or retry only the affected scope.
---

# Hotline TDD

## 目的

本 Skill 将 Hotline 的需求澄清、规格确认、TDD、最小范围重试和交付评审串成一个可验证流程。它补充 Superpowers 的 `test-driven-development`，不替代仓库根目录 `AGENTS.md` 中的规则。

**核心原则：** 每个新行为先用测试表达，再观察测试按预期失败；用最小实现让它通过，最后运行本仓库适用的交付检查。

## 适用范围

- 新功能、行为变更和 Bug 修复。
- 因测试失败而需要局部修复或重试的任务。
- 跨前后端或多阶段工作，需要把需求映射到测试和评审结果的任务。

纯文档修改按 `AGENTS.md` 核对路径、命令、端口、模块名称和验证命令；不要为纯文档内容伪造代码测试。

## 流程

### 1. 澄清需求

先阅读根目录 `AGENTS.md` 及相关子目录规则，再查看目标代码、现有测试和 Git 工作区状态。常规需求澄清和测试不得依赖读取 `.env`、真实数据库或凭据；只有任务明确要求诊断本地配置或数据时，才做最小只读检查，并确保真实值不出现在输出中。

把用户请求整理为可观察的验收条件，说明：

- 哪些输入会触发行为，以及预期输出或状态。
- 哪些现有行为必须保留。
- 哪些内容不在本次范围。
- 哪些失败可以局部重试，哪些变化会影响其他任务。

如果答案会改变外部接口、持久化格式、权限、安全行为或交付范围，先向用户确认。小而明确的改动可直接陈述假设并继续。不要在每个 RED/GREEN 循环都请求批准。

### 2. 确认规格和计划

为每项验收条件列出至少一个能验证它的行为测试，并标出实现文件与依赖关系。多步骤或跨模块任务使用 `brainstorming` 和 `writing-plans` 的流程；先让用户确认规格和计划，再实现。

一个测试应说明它捕捉哪种错误。优先检查真实行为，避免只断言源码文本、私有实现或 mock 调用次数。对本来就满足的行为，不要制造一个假的 RED。

### 3. 记录基线并保护现有改动

开始编辑前查看 `git status --short`，区分本任务新改动与用户已有改动。只编辑本任务需要修改的部分，不覆盖、删除或重置用户已有改动。

先运行与目标相关、已有的测试，记录其结果。区分这次引入的失败与基线已有失败。不要为了清理基线失败而扩大本次改动范围。

如果用户已有实现代码在测试之前存在：

- 保留该代码，先为目标行为补上测试。
- 若测试暴露缺陷，再由测试驱动最小修复。
- 若测试立即通过，说明行为已经存在；不要删除用户代码或改写测试来制造失败。

如果本任务中新写的实现先于测试，停止继续扩展；先为目标行为建立测试，再仅整理或重做本任务由 Agent 新增的实现。不得把用户已有改动当作需要删除的代码。

### 4. RED：运行一个聚焦测试

每次只处理一个行为：

1. 写出最小、名称清楚的测试。
2. 运行该测试或最小的现有测试入口。
3. 确认它因预期行为缺失而失败。

失败原因分类如下：

| 结果 | 处理 |
| --- | --- |
| 断言因目标功能缺失而失败 | 进入 GREEN。 |
| 导入、语法、测试数据或断言本身错误 | 修正测试或夹具，再运行同一测试。 |
| 外部服务、网络、凭据或环境不可用 | 不把它算作产品行为失败；隔离外部边界或报告阻塞。 |
| 与本次改动无关的基线失败 | 记录并保持本次范围；不要借机重构。 |

如果 RED 没有按预期失败，不要开始生产实现。

### 5. GREEN 和 REFACTOR

只写通过当前测试所需的最小实现，不顺手增加范围外功能。

先运行刚失败的同一测试，确认通过；随后只整理已覆盖的代码，并保持测试通过。对纯转发、常量或无独立行为的代码，不要机械地要求“一函数一测试”；测试要保护可观察行为。

### 6. 失败后最小范围重试

局部失败不等于重新执行完整工作流。保持已通过且不受影响的结果，只重试失败项及其必要依赖：

1. 找到第一个失败的断言或任务，并读完整错误信息。
2. 修改负责该行为的最小代码范围或测试夹具。
3. 重新运行该失败测试。
4. 只有当接口、共享状态或任务依赖确实变化时，才补跑直接依赖的测试。
5. 不重跑无关的已通过任务，不重新开始需求澄清或规格确认。

若失败说明验收条件不完整、需要改变用户可见行为或需要扩大数据/接口改动，暂停该分支并询问用户；不要自行改规格。

## Hotline 验证命令

命令和测试布局可能变化。实施前重新检查 `AGENTS.md`、`package.json`、`frontend/package.json` 和实际测试文件；不要照搬其他项目的 `pytest`、`npm test` 或 `cargo test` 命令。

| 改动范围 | 当前可用检查 | 说明 |
| --- | --- | --- |
| Python 后端 | `python -m compileall python_backend` | 语法与字节码编译检查；不会执行模块导入，也不等于行为测试。 |
| 技能中心 | `python skill-center/test_center.py` | 当前标准库 `unittest` 回归测试。根目录 `npm test` 也只调用此测试。 |
| Vue 前端 | `npm --prefix frontend run build` | 当前是构建检查；`frontend/package.json` 没有独立测试脚本。构建通过不能代替交互行为测试。 |
| 文档 | 按 `AGENTS.md` 核对路径、命令、端口和模块名 | 不为文档文字添加无意义的源码测试。 |

交付代码修改前按根目录 `AGENTS.md` 运行后端编译和技能中心测试；改动前端时再运行前端构建。纯文档修改按 `AGENTS.md` 仅核对文档一致性。若命令不可用，说明实际使用的等价命令和限制，不要声称检查通过。

新增测试时沿用仓库已有测试框架。当前后端依赖中没有声明 `pytest`，不要仅为运行一个测试而静默安装或引入新测试框架；若确实需要新框架，将其列入方案并说明影响。

## 外部服务与测试数据

- 测试不得依赖真实大模型、Tavily、MinerU、MySQL、Redis、MinIO 或 pgvector 服务。
- 使用临时目录、临时 SQLite 数据库和固定输入；将网络服务替身放在外部 I/O 边界。
- 常规自动化测试使用临时数据，不读取仓库已有运行数据。运行数据默认位于仓库根目录 `data/`；若配置指定了其他数据目录，也按同等敏感信息处理。
- 任务明确要求诊断本地运行数据时，只检查必要内容；不得把敏感值输出到消息、日志、测试夹具或可提交文件，也不得复制原始运行数据。
- 不把 `.env`、真实 API Key、密码、真实服务地址、用户文件或运行数据库复制到测试夹具、日志和报告中。

## 评审与完成条件

完成前核对：

- 每项验收条件都对应测试或明确说明无法自动测试的原因。
- 至少一个新增行为测试按预期经历 RED 和 GREEN；已有行为已满足时如实说明。
- 聚焦测试通过，项目规定的交付检查已运行并报告。
- 局部失败只重跑了失败范围和必要依赖，没有重置用户已有改动。
- 评审确认实现、测试、规格和数据边界相符。

跨模块、重要功能或合并前使用 `requesting-code-review` 请求独立评审；较小改动也要检查差异、错误路径和敏感数据风险。评审发现问题时只修复相关项，再重跑该项测试及必要依赖检查。

最终报告列出：实现内容、RED/GREEN 证据、实际运行的命令及结果、未运行或未通过的检查、评审发现及处理结果。不要把构建检查称作行为测试，也不要隐去基线失败。

## 常见误区

| 误区 | 正确做法 |
| --- | --- |
| “把所有检查每次都重跑最保险。” | 局部修复先重跑失败测试和直接依赖；交付前再运行项目规定的完整检查。 |
| “根目录有 `npm test`，它就是全项目测试。” | 它当前只运行技能中心测试；按改动范围选择实际检查。 |
| “前端 build 通过就证明交互正确。” | build 只证明产物能构建；交互行为需要行为测试或明确的人工验证记录。 |
| “要先看到 RED，就得删掉已有实现。” | 保留用户代码；对已有行为先写表征测试，缺陷再由测试驱动修复。 |
| “外部模型能连上才算测试。” | 把外部调用隔离在 I/O 边界，用固定替身验证本地逻辑。 |
| “测试失败了，整个计划从头再来。” | 保留有效结果，只重跑失败项及被它影响的依赖。 |
