mini-openclaw/docs/project-process/05-implementation.md

# 阶段 ⑤ 实现（Implementation）

> **定义**：小步、可验证、范围受控地把设计变成代码。实现期的核心不是"写得多"，而是**每一步都有验证、每个改动都可追溯到请求、不越界、不留孤儿**。
> **输入**：① 规格 + ② 架构 + ③ 详细设计（+ ④ UI Spec）。
> **输出**：代码 + colocated 测试 + 变更同步（文档/契约）。
> **进入下一阶段（⑥ 验证与质量门）**：编码规则满足、自测通过、变更矩阵已同步。

---

## 1. 要求（Requirements）

### 1.1 进入条件
- 规格完备性门、架构/详细设计决策均已定案（小改动走轻量路径也必须有范围 + 验收标准）。
- 涉及 UI 的改动已有 ④ 的表面规格与 token。

### 1.2 完成条件（DoD）
- [ ] 每个提交只做一件事（Conventional Commits），变更可逐行追溯到请求范围
- [ ] 行为新增/修改有对应backend/test_*.py或适用前端行为测试；保留现有scripts/test_*.cjs守卫并明确其覆盖边界；不虚构已存在的E2E套件
- [ ] 无未使用 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 | **小步提交**：一个提交一个意图；变更混杂时先拆分再提交（类型前缀+中文一句话，提交前自查diff）。 |

### 2.2 安全与副作用（实现期强制）

| 编号 | 规则 |
|---|---|
| R-5.7 | 所有副作用入口（文件写、命令执行、外发请求、数据导出、API）走统一受控路径，禁止平行执行路径。 |
| R-5.8 | 项目目录写入/命令必须有归属校验 + 审计；凭据/配置保护区一律拒绝。 |
| R-5.9 | 日志/输出不得含凭据；浏览器不能持有模型Key或数据库口令，业务预审不得继承通用聊天的终端/任意文件权限；材料指令不得扩大工具集合。 |
| 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 + Conventional Commits）
```text
<type>(<scope>): <subject>        # subject 简洁中文，≤50 字
                                   # 必要正文说明验证与限制，不要求双语
                                   # 默认分支目前为Gitea main，操作前核对
type: feat | fix | docs | refactor | test | chore | build
```

### 3.3 变更矩阵（改了什么，必须同步什么）

| 变更 | 必须同步 |
|---|---|
| API / SSE / 共享契约 | backend/contracts或明确的API模型owner + 前端调用方/同源代理 + 接口设计 + 契约测试 |
| 模块增删 / 职责变化 | 实际调用关系 + docs/v2/02-architecture.md或对应架构文档，已实现与提案分开 |
| 数据结构 / 迁移 | 追加带守卫的迁移 + 数据契约 + 幂等/版本兼容测试，旧表和生产数据保留 |
| UI 文案 / 状态机 / 组件 | 文案与错误映射 + 实际CSS来源/视觉契约 + 表面规格 + UI测试 |
| 主链路 / 安全边界 | 运行/经验/模型出口设计 + 权限、注入、跨域、证据与模拟隔离测试 |
| E2E 行为 / 运行方式 | 实际浏览器测试入口和前后端启动说明；静态正则检查不能替代E2E |
| 部署 / 数据源接入 | Compose与环境模板 + 部署文档 + config验证；真实数据出口另验 |

---

## 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)
- 提交与审查按根AGENTS和阶段⑥执行；本仓不依赖未安装的提交/评审技能。

变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。