108 lines
6.0 KiB
Markdown
108 lines
6.0 KiB
Markdown
# 阶段 ⑤ 实现（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](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`）
|
||
```text
|
||
<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](03-detailed-design.md)、阶段 ④ [04-ui-spec.md](04-ui-spec.md)
|
||
- 自测通过后进入：阶段 ⑥ [06-validation.md](06-validation.md)
|
||
- 提交与审查技能：`skills/builtin/dk-commit`、`skills/builtin/dk-review`
|