6.0 KiB
6.0 KiB
阶段 ⑤ 实现（Implementation）
定义：小步、可验证、范围受控地把设计变成代码。实现期的核心不是"写得多"，而是每一步都有验证、每个改动都可追溯到请求、不越界、不留孤儿。 输入：① 规格 + ② 架构 + ③ 详细设计（+ ④ UI Spec）。 输出：代码 + colocated 测试 + 变更同步（文档/契约）。 进入下一阶段（⑥ 验证与质量门）：编码规则满足、自测通过、变更矩阵已同步。
1. 要求（Requirements）
1.1 进入条件
- 规格完备性门、架构/详细设计决策均已定案（小改动走轻量路径也必须有范围 + 验收标准）。
- 涉及 UI 的改动已有 ④ 的表面规格与 token。
1.2 完成条件（DoD）
- 每个提交只做一件事（Conventional Commits），变更可逐行追溯到请求范围
- 新行为有 colocated 测试（与源码同目录
*.test.ts，vitest；E2E 在e2e/，playwright。本仓测试体系见docs/architecture/testing-architecture.md） - 无未使用 import/变量/函数（由本次改动产生的孤儿已清理；存量死代码只提不改，G-4）
- 变更矩阵已同步（见 §3.3）：契约、文档、i18n、迁移、架构图
- 本阶段自测（lint/typecheck/相关单测）全绿
2. 规则（Rules）
2.1 编码行为
| 编号 | 规则 |
|---|---|
| R-5.1 | 想清楚再写：假设显式化；多种解释并存时先摆出来，不静默选择；不确定就停，说出困惑点，问。 |
| R-5.2 | 最小代码：解决当前问题的代码，不做投机抽象/灵活配置/为不可能场景写错误处理；200 行能解决的不要写 500 行。 |
| R-5.3 | 外科手术式改动：只碰必须碰的；不顺手"改进"相邻代码/注释/格式；不重构没坏的东西；风格跟随现有代码。 |
| R-5.4 | 规模红线：新文件 ≤500 行；既有大文件只减不增；新增依赖必须先评估体积与必要性（依赖红线见仓库约定）。 |
| R-5.5 | 状态持久化白名单：新增受管写入路径须进白名单并说明；禁止绕过既有持久化/校验路径自行写文件。 |
| R-5.6 | 小步提交：一个提交一个意图；变更混杂时先拆分再提交（见 skills/builtin/dk-commit 的提交规范）。 |
2.2 安全与副作用（实现期强制）
| 编号 | 规则 |
|---|---|
| R-5.7 | 所有副作用入口（文件写、命令执行、外发请求、硬件写、IPC）走统一受控路径，禁止平行执行路径。 |
| R-5.8 | 项目目录写入/命令必须有归属校验 + 审计；凭据/配置保护区一律拒绝。 |
| R-5.9 | 日志/输出禁止出现凭据任何片段（脱敏）；禁止 nodeIntegration: true、禁止绕过 preload/安全边界暴露主机能力。 |
| R-5.10 | 高危动作（删除、生产数据、外发、发布）默认拒绝或显式审批，先于副作用发生，且留审计（详见 07-delivery.md）。 |
2.3 契约与同步
| 编号 | 规则 |
|---|---|
| R-5.11 | 跨进程/跨模块契约只在共享层一处定义（G-1），实现只落契约不发明契约。 |
| R-5.12 | 每个对外接口入参显式校验（继承 R-3.2）。 |
| R-5.13 | 实现点 ↔ 规格 id（BR/E/AC）双向可追溯：改一个行为必须同步它的验收/异常/契约。 |
3. 输出规范
3.1 交付物
- 源码改动（每行可追溯）
- colocated 测试（新行为 + 修复回归）
- 变更同步产物（契约/迁移/文档/i18n）
3.2 提交规范（本仓沿用 AGENTS.md 规则 6 + Conventional Commits；生成建议见 skills/builtin/dk-commit）
<type>(<scope>): <subject> # subject 简洁中文，≤50 字
# 正文：英文完整内容 + `---` 分隔 + 中文完整内容
# （不复述 diff；主分支是 build）
type: feat | fix | docs | refactor | test | chore | build
3.3 变更矩阵（改了什么，必须同步什么）
| 变更 | 必须同步 |
|---|---|
| 跨进程契约 / IPC 通道 / 接口 | packages/api/src/contracts.ts（唯一入口）+ docs/api/ipc-api-reference.md + preload/handler 对齐（src/main/ipc-alignment.test.ts 拦截） |
| 模块增删 / 职责变化 | docs/architecture/codemap.md（头部统计跑 node scripts/repo-stats.mjs，docs-baseline.test.ts 拦截）+ 架构文档 |
| 数据结构 / 迁移 | 迁移文件（只追加，packages/agent-sdk/src/state/migrations.ts）+ docs/architecture/data-model.md |
| UI 文案 / 状态机 / 组件 | i18n key（packages/web-ui/src/i18n/messages.ts）+ 视觉 token（packages/web-ui/src/theme/tokens.css）+ 表面规格 |
| 主链路 / 安全边界 | docs/architecture/flows.md + 相关安全测试（tool-policy/tool-gate/redact） |
| E2E 行为 / 运行方式 | E2E 测试与自动化文档（docs/e2e/e2e-architecture-and-automation.md）+ playwright |
| 宿主形态 / 接入方式 | docs/architecture/host-modes.md |
4. 反模式（实现期高频错误，摘自 Karpathy 准则）
- 先写后想：不问假设、隐藏困惑、静默选一种解释。
- 过度设计：为单次使用写抽象、为没要求的场景加"灵活性"。
- 顺手重构：改 bug 时顺带"美化"周边代码 → diff 失控、评审失效。
- 无验证前进：写一大片再统一跑一次 → 失败定位成本爆炸。
- 留下孤儿：改动删掉了某函数/变量/import 却不清理由本次改动产生的悬空引用。
5. 轻量路径（小改动）
- 一行修复/文案：单提交 + 最小测试，直接走本阶段规则不产额外文档。
- 但 R-5.2~R-5.13 的安全/契约/同步规则对小改动同样强制。
6. 相关文档
- 编码前确认设计：阶段 ③ 03-detailed-design.md、阶段 ④ 04-ui-spec.md
- 自测通过后进入：阶段 ⑥ 06-validation.md
- 提交与审查技能：
skills/builtin/dk-commit、skills/builtin/dk-review