qiaoqichao/mini-openclaw-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mini-openclaw-v2/docs/project-process/05-implementation.md
T
qiaoqichaoandClaude Code d56c699ce6 chore(v2): 从兴邦预审v2白名单抽取独立可运行基座 
按 docs/v2/05-implementation-plan.md §1 候选迁移表与 claude_use/T00 白名单，
从 55e2cdb 抽取 224 个文件（2.48 MB）到独立目录 F:/mini-OpenClaw-v2。

- 排除：凭据(.env/server-deploy.conf/旧DELIVERY.md)、运行数据(xingbang_data 等
  4 个 SQLite)、依赖(venv/node_modules 符号链接)、归档(_backup*/test-evidence/
  ori_file)、Office 临时文件
- 目标目录独立 git 仓库，初始恢复点；Gitea 远程与分支待 OQ-06 Q2 定案
- 未部署、未启动服务、未调用模型

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-29 12:58:26 +08:00

6.0 KiB
Raw Permalink Blame History

阶段 ⑤ 实现（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. 相关文档

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

Reference in New Issue View Git Blame Copy Permalink