dev-iterate

迭代式产品开发

0. 参数解析

从用户指令中提取以下信息（若不明确，通过 AskUserQuestion 确认）：

• Feature 范围：用户可指定 backlog 中的 feature 编号列表，例如 "1, 2, 3"、"5, 8"、"S"（表示全部）。如果不指定，默认处理 backlog 中所有未完成的 feature。
• 起始阶段：可选 "dev"（从 Task A 开始）或 "test"（从 Task B 开始），默认从 Task A 开始。

0.1 Feature 范围解析规则

Backlog 定位：backlog 不一定有独立文件。按以下顺序查找：独立的 backlog.md；PRD.md 中的 backlog / feature list 章节；DESIGN.md 或 Dev Plan 中的 backlog / feature list 章节。找到后，按章节解析所有 feature 条目（以 ### 标题开头、含 [✅] 或 [ ] 状态标记的行）。 2. 为每个 feature 分配序号（按在文件中出现的顺序 1, 2, 3, ...）。 3. 根据用户指定的范围筛选：

• 用户指定编号（如 "2, 5, 7"）→ 只处理对应编号的 feature
• 用户说 "S" 或 "全部" → 处理所有 feature（含已完成的，但已完成的仅做确认不重做）
• 不指定 → 只处理标记为未完成（[ ]）的 feature

4. 按编号顺序依次处理，每个 feature 独立完成后再进入下一个。

硬规则：无论代码是否已存在、是否已提交，Task B（测试验证）和 §5（自检/提交/baglog 更新）都不得跳过。 backlog 中标记为 [ ] 的 feature，必须走完 Task A → Task B → §5 全流程（或根据 §1.1 状态验证从合适的阶段开始，但 Task B 和 §5 必须完整执行）。

开发工作原则（内嵌，贯穿全流程）

以下原则贯穿 Task A、Task B、自检和提交的每一个环节，无需额外调用，直接遵守。每开始一个新 feature 时从零重读，不依赖之前的记忆。

P0. 代码改动授权

未经用户同意，不能改动任何代码源文件和文档。

P1. 修改原则

任何修改必须基于对现状的充分理解，且在不破坏既有功能和接口契约的前提下进行；涉及破坏性变更时须在 PR/提交说明中显式标注 BREAKING。

P2. 充分理解现状

必须先看项目现在的代码和文档还有历史 change log，全面深刻地理解项目的需求、设计、测试和既往改动后，才能开始工作。对用户提出的需求，不停地向用户问问题来澄清需求，直到完全澄清和理解为止。

P2.5 调用方验证（从"实现方"思维转变为"调用方"思维）

根本问题：从"实现方"出发写代码，会导致写了函数没人调、写了配置没被读、迁移了新端没清理旧端。

每次实现功能后，必须回答三个问题：

1. 这个代码谁调用？
   • 写了函数/组件 → grep -r "函数名" --include="*.ts" --include="*.tsx" 验证是否被 import/call
   • 写了 API 端点 → 验证客户端是否有调用代码
   • 写了配置字段 → 验证是否有代码读取该配置
2. 调用链路从 UI 到后端完整吗？
   • 写了配置 UI → 配置存哪里？谁读取？读取后怎么用？端到端验证
   • 写了服务端功能 → 客户端怎么调？配置怎么传？参数怎么传？
   • 写了新的数据结构 → 哪些模块需要更新以适配？
3. 旧代码/旧配置还有谁在用？
   • 迁移功能后 → grep 旧函数名，确认无调用方后删除
   • 重构接口后 → 检查所有调用点是否已更新
   • 删除功能后 → 检查相关配置、类型定义、测试是否需要清理

检查时机：在 Task A 编码完成后、进入 Task B 测试前，执行调用方验证。

强制输出：

✅ P2.5 调用方验证 — [函数X有N个调用点 | API Y客户端已接入 | 旧代码Z已清理]

P3. 测试要求

新功能必须补充对应测试，沿用项目现有测试框架（如 test-e2e.mjs、test-filter.js 所用体系），按职责归类放入对应同体系测试文件；至少覆盖正常路径与关键边界，核心逻辑需有单元测试，跨模块流程需有集成/E2E 测试。

P4. 测试先行的实施流程

任何改动都须先设计测试方案再实施；提交前必须本地执行相关新测试，以及相应的既有测试，全部通过方可提交；失败用例不得通过 skip/注释绕过。改动完成后，先判断改动类型（见 §3.2 决策树），再确定需要运行的测试集：

• A/B 类（纯样式/纯 UI 交互）：禁止跑全量 E2E，输出手动验证步骤。
• C 类（前端逻辑）：只跑受影响的 E2E 子集，不得无脑全量。
• D 类（API/后端）：必须运行完整的 E2E 测试，确保 API 契约未被破坏。
• E 类（模板/Prompt）：必须运行模板相关的单元测试和 E2E 测试。

测试执行结果必须明确告知用户：通过了哪些测试，覆盖了什么范围。任何测试的"跳过"或"豁免"必须说明理由，不得以"构建成功"代替功能测试。

P5. 文档同步

任何涉及行为、接口、架构或使用方式的代码改动，必须同步更新 DESIGN.md 与 README.md 的相关小节；变更记录以 YYYY-MM-DD | 简述 | 影响范围 | 关联 commit 的条目形式追加到 DESIGN.md 的 Change Log 章节。纯注释、格式化、重命名等无行为变化的改动可豁免，但仍需在 commit message 中说明。

P6. 临时文件清理

调试/实验用的临时文件和脚本一律删除；临时安装的全局工具须卸载，临时的项目依赖从 package.json 中移除；不应提交的产物加入 .gitignore；交付前用 git status 核对工作区干净，仅保留与本次任务直接相关的改动。临时占用的资源（服务器、端口等）一律释放。涉及覆盖或删除用户文件/数据库/迁移脚本时，须先备份再操作。

P7. 优先级与冲突仲裁

原则冲突时按以下优先级处理（高→低），并在提交说明中注明所做的权衡：

1. 安全与数据完整性（不得造成数据丢失、密钥泄露、生产事故）
2. 正确性（既有与新增测试全部通过）
3. 文档与代码一致性（DESIGN.md / README.md 与实现同步）
4. 代码质量与可维护性（可读性、最小改动、遵循既有架构）
5. 交付时效

若时效与前四项冲突，不得通过跳过测试、删减测试、降级校验、注释掉失败断言等方式抢时间。正确做法：缩小本次改动范围、拆分为多个提交、或显式向用户请示延期。任何偏离该优先级的决定都必须先经用户确认。

P8. 禁止项（Hard Rules，违反即回滚）

• 禁止伪造或篡改测试结果（包括手动修改测试输出、伪造覆盖率数据、mock 掉本应真实验证的行为）。
• 禁止通过 skip、xit、it.only 永久屏蔽失败用例，或注释/删除失败用例来"让测试通过"；确需临时跳过必须在用例上方写明原因、关联 issue 编号，并同步告知用户。
• 禁止在存在静态代码检查 errors 的情况下提交代码。静态检查 errors（如 ESLint、Pylint、Clippy、go vet 等报错）必须零容忍，不得以"功能正常"、"测试通过"、"先提交再修"为由绕过。若某条规则确实不合理，应先在配置中正式禁用后再提交。
• 禁止未经用户显式确认执行破坏性 git 操作，包括但不限于：git push -f / --force-with-lease、git reset --hard、git clean -fdx、git rebase 已推送分支、删除分支/tag、重写历史（filter-branch、filter-repo）、git checkout -- . 覆盖未提交改动。
• 禁止私自引入新的运行时依赖、付费服务、外网调用、遥测上报；确需引入，先在沟通中说明用途、许可证、体积与替代方案，待用户批准。
• 禁止提交密钥、令牌、.env、个人隐私数据；发现历史中已混入须立即告警并走吊销流程，不自行 filter-branch。
• 禁止在未备份的前提下删除或覆盖用户文件、数据库、迁移脚本。

P9. 沟通纪律（先确认，后动手）

遇到以下情形必须先用一条简短消息向用户说明方案与风险，获得确认后再实施，不得"先做了再说"：

• 方案选型：在两种及以上实现路径、库/框架、架构模式之间抉择时。
• 接口变更：对外 API、CLI 参数、配置项、数据库 schema、文件格式的新增/修改/删除。
• 跨模块重构：影响 3 个及以上文件或跨越既有模块边界的重构。
• 新增依赖或基础设施：新包、新服务、新环境变量、新端口、新后台任务。
• 删除或大规模移动既有代码/文件/文档。
• 预计改动量超过约 200 行，或预计耗时超过单次任务合理范围。
• 任何本原则清单中标注"需用户确认"的操作。

确认消息应包含：①目标与动机；②候选方案对比（至少两个，含"不做"选项）；③推荐方案及理由；④影响范围与回滚方式。用户明确回复后方可进入实施；仅口头"继续"视为同意推荐方案，歧义时再次澄清。

P10. 完工自检

所有改动完成后，对照上述工作原则逐项做一次自检。

历史问题防护（从 422 个 commit 的 bug 模式提炼）

以下规则基于项目历史中反复出现的问题，在编码阶段主动遵守，避免重复踩坑。

HIST-1: 持久化完整性

问题: 新增 Zustand action 时只改内存状态，忘记写入 IndexedDB，导致刷新后数据丢失（18+ commits）。

规则:

• 新增/修改 store action 时，必须同时添加 IDB 写入调用
• 读取设置时，使用展开运算符保留所有字段，避免覆盖用户配置
• 验证方法: 清除浏览器数据后刷新页面，确认功能正常

HIST-2: JSON 解析防护

问题: AI 返回的 JSON 格式不正确或解析失败，导致页面空白（20+ commits）。

规则:

• 所有 JSON.parse() 必须有 try-catch，包括从 localStorage/IDB/外部 API 读取的数据
• AI 响应的 prompt 必须包含 JSON schema 约束
• 验证方法: grep -n "JSON.parse" --include="*.ts" --include="*.tsx" 扫描无防护的调用

HIST-3: 组件卸载保护

问题: AI 请求在飞行中时用户导航离开，请求完成后 setState 导致内存泄漏（13+ commits）。

规则:

• 所有发起异步操作的组件必须实现 isMountedRef + AbortController
• 服务端必须监听客户端断连，abort 进行中的 AI 调用
• 验证方法: 检查组件是否有 isMountedRef 和 useEffect cleanup

HIST-4: null/undefined 防护

问题: 访问 AI 返回数据的嵌套属性时崩溃（8+ commits）。

规则:

• AI 返回的可选字段在 .map()、.length、[index] 访问前必须检查
• 使用可选链 ?. + 空值合并 ??
• 验证方法: grep -n "!\." --include="*.ts" --include="*.tsx" 扫描非空断言

HIST-5: 生产环境代码清洁

问题: console.log 残留、DEBUG 标志硬编码为 true，泄露敏感信息（10+ commits）。

规则:

• 使用项目的 logger（如 createLogger）而非 console.log
• DEBUG 标志必须使用 import.meta.env.DEV 或环境变量控制
• 提交前: grep -rn "console.log" src/ 扫描残留

HIST-6: React Key 稳定性

问题: key 中包含 index 或用户可编辑字段，导致组件重挂载（6+ commits）。

规则:

• 禁止在可删除/可排序列表中使用 key={index}
• 禁止在 key 中包含用户可编辑的字段
• 优先使用稳定 ID（如 item.id）

HIST-7: useEffect 依赖稳定性

问题: 每次渲染创建新引用传入 useEffect 依赖，导致无限循环（5+ commits）。

规则:

• 禁止在依赖中使用 .filter()、.map() 等每次创建新引用的表达式
• 使用 useMemo 稳定派生数据的引用
• 验证方法: 检查依赖数组中的变量是否在每次渲染时都是新引用

数据持久化与数据库 Schema 变更规则

涉及 IndexedDB、localStorage、SQLite 等本地持久化方案的改动，附加遵守以下规则：

DB-1: Schema 变更必须增量升级

• 每次新增/修改 store 或索引时，必须增加 DB_VERSION 号
• upgrade 回调中必须使用 oldVersion 参数实现增量升级（if (oldVersion < N)），不得仅用 if (!db.objectStoreNames.contains("xxx")) 模式 — 旧模式只处理"新用户"场景，不处理"旧用户升级"场景
• 禁止在 upgrade 回调中创建新事务；所有 schema 变更必须在同一个事务内完成（数据库原生限制）
• 禁止给已存在的 store 添加新索引，必须 deleteObjectStore 后 createObjectStore 重建
• 删除已存在的 store 前，必须考虑数据迁移策略（备份→删除→重建→恢复）

DB-2: 持久化相关修复必须验证

• 检查 Repo/Services 文件的 CRUD 操作是否正确调用持久化层
• 检查 store 定义和索引是否完整
• 检查 UI 组件是否在加载时从持久化层读取历史数据
• 必须在不清楚浏览器数据（IndexedDB/Cookie/localStorage）的情况下刷新页面，验证功能正常

DB-3: 升级场景测试

• 必须编写"从旧版本 schema 升级"的集成测试，模拟用户保留旧数据、从旧版本升级的真实场景
• 测试不能只在"干净"的新用户环境中运行（空数据库），必须覆盖保留旧数据的升级路径
• 增加 IndexedDB Schema 版本验证日志（console.log(\[IndexedDB] Upgrading from v${oldVersion} to v${newVersion}`)`），便于排查生产环境升级问题

1. 前置准备

每开始一个新 feature 前，完整阅读以下文件（从零独立阅读，不依赖之前的记忆）：

0. PRD.md — 产品需求文档（产品需求、背景、成功标准）
1. DESIGN.md — 项目设计文档（产品需求、架构、接口定义）
2. Implementation_plan.md或'Dev Plan.md'或类似名字的文档 — 详细开发计划文档（feature 描述、改动范围、验证方式，backlog）
3. Backlog（可能在独立的 backlog.md，也可能在 PRD/Design/Dev Plan 的 backlog 章节中）— 功能 backlog（feature 描述、改动范围、验证方式）
4. CLAUDE.md（若存在）— 项目级工作规范
5. 当前 feature 对应的源码文件 — 根据 backlog 中"改动范围"列出的文件
6. git log / 历史 Change Log — 查看最近的提交历史和 DESIGN.md 中的 Change Log，了解既往改动脉络，避免重复劳动或踩旧坑

确保充分理解：这个 feature 要做什么、改动哪些文件、怎么验证、和其他 feature 有没有依赖。

1.1 Feature 状态验证

进入 Task A 前，验证该 feature 的实际状态：

1. git log --oneline 检查是否有相关 commit
2. 检查源码文件是否已包含该 feature 的实现

根据验证结果决定起始阶段：

• 代码不存在 → 从 Task A（开发）开始
• 代码已存在但未提交/未测试 → 从 Task B（测试）开始，跳过 Task A
• 代码已存在且已提交，但 backlog 标记为 [ ] → 从 Task B 开始，补走 §5 全流程

无论哪种情况，Task B 和 §5 都必须完整执行，不得跳过。

强制输出：

§1.1 Feature "<name>" 状态验证 — [代码不存在→从 Task A | 代码存在未测试→从 Task B | 代码已提交→补走 §5]

未输出此声明而直接进入 Task A 或 Task B，视为流程违规。

2. Task A：设计与开发

对当前 feature 进行全面、深入的设计与开发。

2.1 工作内容

1. 独立验证前置依赖：从零检查该功能依赖的前置 feature 是否已正确完成（不信任之前的确认记录，实际运行验证）。（P2）
2. 需求分析：基于 PRD/Design Doc/Dev Plan 和 backlog 中该 feature 的描述，确认功能需求和验收标准。对需求有疑问时不停追问用户直到澄清。（P2）
3. 架构设计：确定改动哪些文件、什么接口、什么数据流。若有多种实现路径，简要对比后选最优方案。涉及方案选型、接口变更、跨模块重构、新增依赖、大改动（>200行）时必须先询问用户确认再动手。（P9）
4. 编码实现：编写/修改代码，遵循项目既有架构和代码风格。不破坏既有功能和接口契约（P1）。禁止私自引入新依赖（P8）。禁止提交密钥/令牌（P8）。
   • 工具验证：每次使用修改工具（replace_in_file、write_to_file 等）后，必须用 git diff <file> 或 read_file 验证实际文件内容。不信任工具的返回结果 — 工具可能返回虚假的成功信息（如显示 +++++++ REPLACE 标记而非实际写入内容）。
   • 静态检查实时遵守：编写代码时必须遵循项目静态代码检查工具的规则。根据项目使用的工具，常见修复方式：
     • ESLint (JS/TS)：
       • 未使用变量/参数：加 _ 前缀或删除
       • React Hook 依赖缺失：补充缺失的依赖项或使用 // eslint-disable-next-line <rule> 并注明原因
       • 未转义引号：使用 " 或模板字符串
     • Pylint/Flake8/Ruff (Python)：
       • 未使用变量：加 _ 前缀或删除
       • 导入未使用：删除未使用的 import
     • Clippy (Rust)：
       • 未使用变量：加 _ 前缀
       • unwrap 使用：改用 expect 或 ? 操作符
     • go vet (Go)：
       • 未使用变量：使用 _ 赋值或删除
     • 通用原则：空 catch 块、空函数体等应添加注释说明为何为空
   • 编码阶段自检：每次完成一个文件的修改后，可运行项目的静态检查命令（如 npm run lint、cargo clippy、ruff check 等）检查该文件。发现问题立即修复，不要积累到最后。
5. 自测验证：按照 backlog 中的"验证方式"做基本自测，确保功能基本可用。
6. 自查：实现完成后，对照 Definition of Done 逐项自查是否全部满足。（P10）

分析阶段不要停下来请示用户，持续分析直到得出结论，除非遇到 P9 列出的确认场景（方案选型、接口变更、跨模块重构、新增依赖、大改动）。P2"充分理解现状"是指自己主动多看代码和文档，不是反复向用户确认。

2.2 何时询问用户

通过 AskUserQuestion 询问用户的场景：

• 功能需求存在歧义，不同实现方案会导致不同的产品行为。
• 需要在多个产品行为之间做选择（如 UI 交互方式、默认值、边界行为）。
• 发现 backlog 描述与 Design Doc 不一致，需要确认哪个是正确的。
• 方案选型、接口变更、跨模块重构、新增依赖、大改动等（P9 所列场景）。

不要询问用户的事项：

• 技术实现细节（用什么算法、哪个库、代码怎么组织）。
• 纯代码层面的重构、优化、命名。
• 测试策略的技术选择。

2.3 完成交付

开发完成后：

1. 确认所有改动文件已保存。
2. 清理所有临时文件（P6）。
3. 向 Task B 交付：列出本次改动的文件清单、改动摘要、以及 backlog 中的验证方式。
4. 必须输出以下声明后方可进入 Task B：

   ✅ Task A 完成 — 进入 Task B 测试验证

   此时禁止读取下一个 feature 的任何文件或开始任何分析。 未输出此声明而直接进入下一个 feature，视为流程违规。
5. 进入 Task B。不得跳过 Task B，Task A 内的自测（mock 测试、inline 验证）不替代 Task B 的独立测试。

3. Task B：测试设计与执行

对 Task A 交付的 feature 进行全面深入的测试。

3.1 测试设计

1. 独立审查：从零阅读 backlog 中该 feature 的描述和验证方式，不依赖 Task A 的改动摘要来推断应该测什么。（P2）
2. 测试方案：先设计测试方案再开始测试执行（P4）。新功能必须补充对应测试，沿用项目现有测试框架（P3）。覆盖以下维度：
   • 单元测试：纯函数、reducer、工具函数、schema 验证
   • 集成测试：模块间交互、pipeline、gateway、repository 层
   • E2E 测试：用户交互流程、UI 组件、路由跳转
   • 系统测试：完整业务场景端到端
   • 边界/异常测试：边界值、非法输入、网络异常、并发场景
   • 安全测试：Mock 零外发、API Key 零明文等
   • 升级兼容性测试：涉及数据库 Schema 变更时，必须编写"从旧版本升级"的集成测试，模拟用户保留旧数据从旧版本升级到新版本的真实场景（DB-3）。测试不能只在"干净"的空数据库环境中运行。
3. 测试类型：根据项目现有测试体系选择合适的测试方式：
   • 单元测试（若有对应框架）
   • 集成/E2E 测试（沿用项目现有测试框架，如 test-e2e.mjs）
   • 手动验证（对于 UI 交互类改动，给出明确的手动验证步骤）

3.2 测试执行

先判断改动类型，再决定测试动作。 对本次改动逐文件分类，取最严格的类别执行。

改动类型判断（决策树）

关键规则：

• A/B 类改动：禁止跑全量 E2E 测试（浪费 token 且无法验证 UI 交互）
• C 类改动：先 grep 测试文件找相关用例，只跑受影响的子集，不得无脑全量
• D/E 类改动：跑完整 E2E
• 混合改动：拆开分别处理，取最严格类别

各类别测试执行细则

A/B 类（纯样式 / 纯 UI 交互）— 禁止跑全量 E2E

不运行自动化 E2E 测试。必须输出：

### 测试报告
- **改动类型**：纯样式 / 纯 UI 交互
- **E2E 测试**：不适用（现有 E2E 测试不覆盖 UI 交互）
- **手动验证步骤**：
  1. [具体操作] → [预期结果]
  2. ...
- **现有测试覆盖范围**：[说明 E2E 测试覆盖了什么，为什么与本次改动无关]

C 类（前端逻辑）— 只跑受影响的 E2E 子集

1. 先 grep 测试文件，找到与本次改动相关的测试用例
2. 只运行这些相关用例，不跑全量
3. 若无法确定相关用例，说明原因后跑全量（但必须先尝试定位）

D 类（API/后端）— 跑完整 E2E

必须运行完整的 E2E 测试，确保 API 契约未被破坏。

E 类（模板/Prompt）— 跑模板相关单测 + E2E

必须运行模板相关的单元测试和 E2E 测试。

通用要求

运行所有可自动执行的测试（单元测试、E2E 测试）。对于需要手动验证的场景，给出详细的验证步骤和预期结果。记录每个测试用例的通过/失败状态。

3.3 测试报告

测试报告是强制输出，不按格式提交视为测试未完成。 格式如下：

## Feature: [feature 名称] — 测试报告

### 测试概要
- 测试用例总数：X
- 通过：Y | 失败：Z | 跳过：W（需说明原因）
- 测试覆盖范围：[列出覆盖的维度]

### 测试用例详情

#### TC-001: [用例名称] — ✅ 通过 / ❌ 失败
- **类型**：[正常路径 | 边界条件 | 错误处理 | 回归]
- **测试方式**：[自动化 | 手动]
- **步骤**：[具体操作]
- **预期结果**：[应该怎样]
- **实际结果**：[实际怎样]（仅失败时填写）
- **失败原因分析**：[仅失败时填写]

#### TC-002: ...

### 结论
- [全部通过 → 建议进入自检和提交]
- [存在失败 → 将报告交给 Task A 修复]

3.4 交付

• 全部通过：必须输出以下声明后方可进入 §5：

  ✅ Task B 全部通过 — 进入 §5 自检与提交流程

  未输出此声明而直接进入 §5 或下一个 feature，视为流程违规。
• 存在失败：需先自行调查失败原因，再决定处理方式：
  • 功能性失败（代码逻辑错误）→ 将测试报告交给 Task A 修复，循环继续
  • 环境依赖失败（VPN/网络/外部服务不可用）→ 必须自行调查确认（如 curl 验证目标地址可达性、DNS 解析、端口连通性），附上调查证据后暂停，请用户介入修复环境。判定为环境问题前需排除所有代码层面的可能
  • 任何情况不得以 mock 通过替代真实测试结果
  • 新一轮测试仍从零独立设计，不沿用上一轮的测试用例而不重新审视

3.5 测试后清理（强制执行）

测试可能启动了后台服务、占用端口、生成临时文件。进入下一步前必须清理：

• 检查本次测试是否启动了服务/端口/后台进程，若有则终止
• 检查是否有临时产物（临时脚本、测试输出文件等），若有则删除
• 验证清理完成（如端口已释放、进程已退出）

测试可能启动了后台服务、占用端口、生成临时文件。进入下一步前必须执行以下清理步骤：

1. 检查并终止测试相关进程（强制）：
   • 执行 ps aux | grep -E "vitest|jest|mocha|node.*test" | grep -v grep 检查残留测试进程
   • 若有残留进程，执行 pkill -f vitest / pkill -f jest 等终止
   • 再次执行检查命令确认进程已终止
2. 检查端口占用（如测试启动了本地服务）：
   • 执行 lsof -i :<端口> 检查端口是否已释放
   • 若端口被占用，找到进程 PID 并终止：kill -9 <PID>
3. 清理临时文件：
   • 检查本次测试是否生成了临时脚本、测试输出文件等
   • 若有则删除或加入 .gitignore
4. 执行 git status 确认工作区干净

强制输出：

✅ §3.5 测试后清理 完成 — [无残留进程 | 已终止 N 个残留进程: 列出进程名]

未输出此声明而直接进入 §4 或 §5，视为流程违规。

4. 交替循环

Task A 和 Task B 如此交替：

Task A（开发/修复）→ Task B（测试）→ Task A（修复）→ Task B（测试）→ ... → 全部通过

4.1 循环规则

• 最大轮次：10 轮（可由用户通过参数覆盖）。达到最大轮次仍未全过则暂停，请用户介入。
• 每一轮 Task A：收到 Task B 的失败报告后，先完整阅读报告，理解每个失败用例，然后修复。修复后自测一遍，再交给 Task B。
• 每一轮 Task B：从零独立审查，不因为上一轮某用例通过就跳过，仍要完整执行所有测试用例。
• 同一问题反复失败：如果同一个用例连续 3 轮失败，暂停循环，请用户确认是否需求本身有问题。
• 循环退出后必须进入 §5：测试全部通过后，必须输出以下声明后方可进入 §5：

  ✅ Task B 全部通过 — 进入 §5 自检与提交流程

  未输出此声明而直接进入下一个 feature，视为流程违规。§5 的每一步（自检→文档同步→pre-commit checklist→原则自检→commit & push→更新 backlog→gate check）都是强制的。
• §5 必须独立完成：每个 feature 的 §5 必须独立执行——独立 commit、独立 push、独立更新 backlog。禁止合并多个 feature 的 §5 到一次执行，禁止多个 feature 共用一个 commit。
• 禁止跨 feature 并行开发：Feature N 的 §5.x Gate Check 通过之前，禁止开始 Feature N+1 的任何步骤（包括 Task A 的代码阅读、需求分析）。违反此规则视为流程违规。

5. 自检与提交

当前 feature 测试全部通过后，必须逐步执行以下步骤，每步完成后输出强制确认标记，不得合并或跳过任何一步。

5.1 完工自检

对照上述 P0-P10 开发工作原则逐项自检：

1. 代码改动授权（P0）：所有改动是否经过用户确认（或属于用户已授权的功能范围）
2. 修改原则（P1）：是否破坏了既有功能和接口契约
3. 测试要求（P3）：新功能是否补充了对应测试
4. 文档同步（P5）：是否需要更新 DESIGN.md、README.md、Change Log
5. 临时文件清理（P6）（执行，非仅确认）：
   1. 列出本次任务中启动的所有后台服务/端口/进程，逐一终止
   2. 列出本次任务中生成的临时文件/脚本，逐一删除或加入 .gitignore
   3. 执行 git status，确认工作区仅包含本次 feature 相关改动
6. 安全与数据完整性（P7）：是否存在安全隐患

其余原则（P2 充分理解现状 / P4 测试先行 / P7 优先级仲裁 / P9 沟通纪律）见 §5.4 原则自检。

强制输出：自检完成后，输出一行：

✅ §5.1 完工自检 完成 — [逐项通过 | 有N项待修: 列出问题]

若有待修项，先修复后再输出确认。不得带着未修复的问题进入下一步。

5.2 文档同步

若改动涉及行为、接口、架构变更（P5）：

• 同步更新 DESIGN.md 与 README.md 相关章节
• 在 DESIGN.md 的 Change Log 追加条目：YYYY-MM-DD | 简述 | 影响范围 | 关联 commit

强制输出：

✅ §5.2 文档同步 完成 — [已更新 DESIGN.md/README.md | 无需更新，跳过]

5.3 14 条 Pre-commit Checklist

在 §5.1 和 §5.2 通过后，从零逐条执行以下 14 条检查：

⚠️ 硬性约束：第 1-2 条（类型安全、静态代码检查）为硬阻塞项。任一不通过，禁止提交，必须返回修复。不存在"先提交再修"的例外。

1. 类型安全：类型检查命令 exit 0，无类型错误（如 npm run typecheck、cargo check、mypy 等，根据项目类型选择）
2. 静态代码检查（🔴 硬阻塞）：
   • 执行项目的静态代码检查工具，必须 0 errors 才能继续
   • 发现项目使用的检查工具：ESLint (JS/TS)、Pylint/Flake8/Ruff (Python)、Clippy (Rust)、go vet (Go)、Checkstyle (Java) 等
   • warnings 可接受，但 errors 必须全部修复
   • 不得以任何理由绕过：包括但不限于"功能正常"、"测试通过"、"时间紧迫"、"只是小问题"
   • 若某条规则确实不合理，应先在配置中正式禁用后再提交，不得临时 ignore 或注释掉检查
3. 单元测试：npm test 全绿（或项目对应命令）
4. 集成测试：npm run test:integration 全绿（如适用）
5. E2E 测试：npm run test:e2e 全绿（如适用）
6. 评测集：npm run test:evaluation 全绿（如适用）
7. 开发者真实 AI Smoke：npm run test:ai-smoke 全绿（如适用）
8. Mock 零外发：不破坏 Mock 模式网络隔离
9. API Key 零明文落盘：grep 扫描确认
10. 法律结论零泄漏：grep 扫描确认
11. 依赖控制（P8）：未新增未经确认的运行时依赖
12. 文档同步（P5）：行为/接口变更已同步文档
13. 测试未跳过（P8）：grep 扫描确认无 .skip / .todo
14. 脚手架干净（P6）：git status 不含需忽略文件

强制输出：

✅ §5.3 Pre-commit Checklist 完成 — 14/14 通过 [ | 有N项未通过: 列出问题]

任一未通过 → 不得提交，返回 Task A 修复。

5.4 原则自检（P10）

• P0：所有代码改动已获用户授权
• P1：未破坏既有功能和接口契约
• P2：已充分理解现状后才动手
• P3：新功能已有对应测试覆盖
• P4：先设计测试方案再实施，已分析影响范围并运行对应测试
• P5：行为/接口/架构变更已同步文档
• P6：临时文件已清理，git status 干净
• P7：无原则冲突；如有，在提交说明中注明权衡
• P8：无伪造测试、无 skip 屏蔽、无破坏性 git 操作、无未经授权的新依赖、无密钥泄露、无未经备份的删除
• P9：需要确认的事项已事先征得用户同意

强制输出：

✅ §5.4 原则自检 完成 — P0-P10 全部通过 [ | 有N项待修: 列出问题]

任一未通过 → 不得提交，返回 Task A 修复。

5.5 Commit & Push（自动执行）

§5.1 ~ §5.4 全部通过后，自动执行 commit & push，无需用户确认（非正常停止条件触发时除外）。每个 feature 独立 commit，禁止合并多个 feature 的改动到一个 commit。

1. git status + git diff 分析变更
2. 起草提交信息（遵循项目历史风格），末尾按 commit skill 的 trailer 对照表和检测规则生成 Co-Authored-By trailer（读取 skill 目录 trailer-map.json（~/.ai-skills/commit/）；若工具或模型未命中，WebSearch 查邮箱后更新 map 和所有 SKILL.md 副本）
3. git add 相关文件（仅与当前功能相关的文件）
4. 执行 git commit 并附详细 body（变更摘要、测试结果、自检结果、原则权衡说明如有）
5. 执行 git push 推送到远程
6. 验证 push 成功：执行 git status，确认输出包含 Your branch is up to date with 'origin/main' 或 nothing to commit，且不含 ahead 字样。若仍显示 ahead，说明 push 未成功，必须排查原因（网络、认证、权限）并重试，不得跳过
7. commit 和 push 均验证通过后，方可进入下一步

强制输出：

✅ §5.5 Commit & Push 完成 — hash: <commit hash> | 已推送到 origin/main

必须包含实际的 commit hash（7 位短 hash）。若 commit 或 push 失败（含 push 未验证通过），不得输出此确认，必须先解决问题。

5.6 更新 Backlog

将该 feature 在 backlog 中的状态更新为已完成（[✅]）。

强制输出：

✅ §5.6 更新 Backlog 完成 — feature "<feature 名称>" 已标记 [✅]

5.x Gate Check（强制）

§5.6 完成后，执行 gate check 验证所有步骤均已正确完成：

1. 确认输出完整性：检查 §5.1 ~ §5.6 的 6 行确认输出是否全部存在
2. 验证 commit & push：
   • git log -1 --oneline 确认最新 commit 与 §5.5 输出的 hash 一致
   • git log --oneline 检查本次迭代的 commit 数量是否等于已处理的 feature 数量（每个 feature 必须有独立 commit）
   • git status 确认不含 ahead 字样（push 已成功）
3. 验证 backlog：读取 backlog 文件，确认该 feature 行包含 [✅] 标记。若 backlog 在 .gitignore 中，记录为"本地更新，未提交"，不视为失败

全部通过后输出：

✅ §5 Gate 通过 — 允许进入下一个 feature

任一检查失败，禁止进入 §6，必须先补齐缺失的步骤。

6. 进入下一个 Feature

当前 feature 完全结束后：

• 若还有未处理的 feature → 回到步骤 1，处理下一个 feature
• 若所有 feature 已处理完毕 → 进入 §8 最终清理

阻塞规则：以下任一条件不满足时，禁止进入下一个 feature 的任何步骤（包括 Task A 的代码阅读、需求分析）：

1. 上一个 feature 的 §5.1 ~ §5.6 的 6 行确认输出全部存在
2. 上一个 feature 有独立的 commit（git log -1 --oneline 确认最新 commit 与 §5.5 记录的 hash 一致）
3. 上一个 feature 的 backlog 已更新（该 feature 标记为 [✅]）

若条件不满足，必须立即停止并补齐缺失的步骤，不得"先继续做，后面再补"。

7. 非正常停止条件

以下情况暂停并请用户介入：

• 达到最大轮次仍未收敛
• 同一测试用例连续 3 轮失败
• 需要引入新的运行时依赖或付费服务（P8）
• 改动范围超出预期（影响 3+ 模块或 200+ 行），需用户确认是否拆分（P9）
• 发现 backlog 或 Design Doc 中的需求本身有矛盾，需要产品决策
• 任何原则清单中标注"需用户确认"的操作（P9）

8. 最终清理（全部 Feature 完成后）

所有 feature 处理完毕（或用户提前终止迭代）后，必须执行以下全局清理，不得跳过：

1. 释放所有端口与进程：检查本次会话中启动过的所有后台服务/端口/后台进程（不限于最后一个 feature），逐一终止并验证端口已释放（lsof -i :<port> 确认无占用）
2. 清理所有临时文件：删除本次会话中各 feature 产生的所有临时脚本、测试输出、调试文件等；执行 git status 确认工作区干净
3. 向用户报告完成状态：输出本次迭代的总览 — 共处理了多少个 feature、各自状态（通过/失败/跳过）、最终 commit hash、以及是否有遗留问题需要用户关注

强制输出：

✅ §8 最终清理 完成 — 端口已释放，工作区干净，共完成 N 个 feature