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）。

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）

<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、阶段 ④ 04-ui-spec.md
• 自测通过后进入：阶段 ⑥ 06-validation.md
• 提交与审查按根AGENTS和阶段⑥执行；本仓不依赖未安装的提交/评审技能。

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