auto-sync: 2026-06-06 08:40:09

docs/design/13-toolchain-and-dev-workflow.md

@@ -510,6 +510,188 @@ Agent spawn 走生产 openclaw 的决策理由：
 
 ## §9. 完整开发流程（端到端）
 
+### 9.0 全局工作流串联图
+
+以下是把所有关键环节串起来的完整链路。三个场景（新功能/Bug修复/Hotfix）共享大部分节点，差异在分支。
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        问题/需求入口                                    │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
+│  │ 主公口头  │  │ CI 失败   │  │ 司马懿   │  │ 运行时   │               │
+│  │ /需求文档 │  │ 自动报告  │  │ Review   │  │ Agent发现 │               │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘               │
+│       └──────────────┴──────────────┴──────────────┘                    │
+│                              ↓                                         │
+│                   ┌─────────────────────┐                              │
+│                   │ 需求/问题 Review     │  ← §4.3                     │
+│                   │                     │                              │
+│                   │ 需求: 庞统(方案)     │                              │
+│                   │       + 司马懿(可行) │                              │
+│                   │ Bug: 司马懿(确认根因)│                              │
+│                   │ Agent发现: 庞统(过滤)│                              │
+│                   └──────────┬──────────┘                              │
+│                              ↓ 通过                                    │
+│  ┌───────────────────────────────────────────────────────────┐         │
+│  │              创建 Gitea Issue #N                          │         │
+│  │  标签: bug/feature/improvement + risk:high/standard/low   │         │
+│  │  关联: PR / 复现步骤 / 根因分析                            │         │
+│  └──────────────────────────┬────────────────────────────────┘         │
+│                             ↓                                          │
+│              ┌──── 场景分流 ────┐                                      │
+│              ↓                  ↓                                      │
+│     ┌─── Hotfix ───┐   ┌── 标准流程 ──┐                               │
+│     │              │   │              │                               │
+│     │ 直接 main    │   │ 分支开发     │                               │
+│     │              │   │              │                               │
+│     └──────┬───────┘   └──────┬───────┘                               │
+│            ↓                   ↓                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+
+=== 标准流程（新功能 / Bug修复）===
+
+  ┌─────────────────────────────────────────────┐
+  │ Step 1: 分支创建                             │
+  │   git checkout -b feat/issue-N-xxx           │
+  │   或 git checkout -b fix/issue-N-xxx         │
+  │   角色Agent: 开发者（张飞/姜维/关羽/赵云）    │
+  │   Skill: git-workflow                        │
+  │   输入: Issue #N                             │
+  │   输出: feature/bugfix 分支                  │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 2: 编码 + 自测                          │
+  │   编码 → 本地 pytest → commit                │
+  │   角色Agent: 开发者                          │
+  │   Skill: 按任务类型（无专门编码skill）        │
+  │   输入: 分支 + Issue 需求                    │
+  │   输出: 代码改动 + UT                        │
+  │   约束: Bug修复必须加回归测试                 │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 3: push → CI 快速门控（每次push）       │
+  │   Lint + Unit Tests                          │
+  │   工具: Gitea Actions                        │
+  │   输入: feature 分支 push                    │
+  │   输出: ✅通过 / ❌失败标红                   │
+  │   阻断: 软阻断（失败不阻止开发，但阻止PR进入Review）│
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 4: 创建 PR                              │
+  │   git push origin → Gitea 创建 PR            │
+  │   自动: 风险级别标注（按改动文件路径）         │
+  │   工具: Gitea PR                              │
+  │   输入: feature 分支 + CI 快速门控结果        │
+  │   输出: PR + 风险标签                         │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 5: CI 标准门控（PR到main时）            │
+  │   Lint + Unit + Integration + Coverage       │
+  │   环境: CI 隔离临时环境                       │
+  │   工具: Gitea Actions + pytest-cov + ruff    │
+  │   输入: PR diff                              │
+  │   输出: ✅通过 / ❌阻断merge                 │
+  │   阻断: 硬阻断（CI不过不许merge）             │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 6: 代码审查                             │
+  │   审查者确认风险级别（只升不降）              │
+  │   默认审查者: 司马懿（所有级别）              │
+  │   例外: 司马懿的改动 → 庞统交叉审查          │
+  │   Skill: code-review                         │
+  │   输入: PR + CI 结果 + 风险级别               │
+  │   输出: 通过 / 不通过（附行号+修改方向）      │
+  │   不通过 → 回到 Step 2                       │
+  └──────────────────┬──────────────────────────┘
+                     ↓ 通过
+  ┌─────────────────────────────────────────────┐
+  │ Step 7: Merge → CI 完整门控                   │
+  │   merge到main → 自动触发                     │
+  │   标准 CI + deploy workflow                   │
+  │   触发: Gitea branch protection（CI+Review通过才许merge）│
+  │   输入: main 分支                            │
+  │   输出: merge commit + CI 结果                │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 8: 自动部署                              │
+  │   deploy.sh --source=... --health-check      │
+  │   记录版本到 deploy-history.jsonl             │
+  │   角色Agent: 姜维（deploy.sh由项目维护）      │
+  │   Skill: ci-cd-ops                           │
+  │   输入: main 分支代码                         │
+  │   输出: 部署结果 + 版本记录                   │
+  │   失败: 自动回滚（deploy.sh --rollback）     │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 9: E2E 验证（CI 隔离环境自动跑）        │
+  │   临时venv + 临时SQLite + 临时端口8084        │
+  │   Agent spawn 走生产 openclaw（不隔离）      │
+  │   角色: 司马懿写E2E用例，CI自动跑             │
+  │   Skill: testing-workflow                    │
+  │   输入: 部署后的代码                          │
+  │   输出: E2E 结果                              │
+  │   阻断: 初期不阻断，成熟后可阻断              │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step 10: Issue 关闭                          │
+  │   部署成功 + 验证通过 → 关闭 Issue #N        │
+  │   发现新问题 → 新开 Issue → 回到入口 Review  │
+  └─────────────────────────────────────────────┘
+
+=== Hotfix 分支流程 ===
+
+  ┌─────────────────────────────────────────────┐
+  │ Step H1: 确认 hotfix                         │
+  │   庞统或主公确认（线上故障、核心功能受影响）  │
+  │   Skill: hotfix-workflow                     │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step H2: 直接 push main                      │
+  │   修改 → commit → push main                  │
+  │   CI 必须触发（lint + unit），不可跳过       │
+  │   CI 失败 → 自动 revert → 人工介入           │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step H3: 自动部署（同标准 Step 8）           │
+  │   E2E 验证（同标准 Step 9）                  │
+  └──────────────────┬──────────────────────────┘
+                     ↓
+  ┌─────────────────────────────────────────────┐
+  │ Step H4: 24h 内复盘（必须）                  │
+  │   补 Gitea Issue（根因 + hotfix 内容）       │
+  │   司马懿 Review（事后审查代码质量）          │
+  │   复盘记录（为什么需要 hotfix、如何避免）    │
+  │   超时 → 下次 hotfix 权限暂停               │
+  └─────────────────────────────────────────────┘
+```
+
+#### 工具链衔接总览
+
+| 环节 | 工具 | Agent/人 | Skill | 输入 | 输出 |
+|------|------|---------|-------|------|------|
+| 问题Review | Mail/口头 | 庞统+司马懿 | — | 问题描述 | 确认的需求/bug |
+| Issue创建 | Gitea Issues | 庞统/司马懿 | — | 确认的问题 | Issue #N + 标签 |
+| 分支创建 | git | 开发者 | git-workflow | Issue #N | feature/bugfix 分支 |
+| 编码+UT | 本地IDE | 开发者 | — | 分支+需求 | 代码+UT |
+| CI 快速门控 | Gitea Actions | 自动 | ci-cd-ops | push | lint+unit 结果 |
+| PR创建 | Gitea PR | 开发者 | git-workflow | 分支+CI结果 | PR+风险标签 |
+| CI 标准门控 | Gitea Actions | 自动 | ci-cd-ops | PR diff | 全套CI结果 |
+| 代码审查 | Gitea PR Review | 司马懿 | code-review | PR+CI结果 | 通过/不通过 |
+| Merge | Gitea（branch protection） | 自动 | — | Review通过+CI通过 | merge commit |
+| 部署 | deploy.sh | 自动 | ci-cd-ops | main代码 | 部署结果+版本 |
+| E2E验证 | pytest（CI隔离） | 司马懿写/CI跑 | testing-workflow | 部署代码 | E2E结果 |
+| Issue关闭 | Gitea Issues | 庞统/改动者 | — | 部署+验证通过 | Issue Closed |
+
 ### 9.1 场景 A：新功能开发
 
 ```
@@ -702,6 +884,13 @@ Agent spawn 走生产 openclaw 的决策理由：
 - 路径硬编码清单增加"行数"列（仲达建议）
 - 状态标记为 v1.0 定稿
 
+### v1.0 → v1.1（主公要求：补全局工作流串联图）
+
+- §9.0 新增全局工作流串联图：从问题入口到部署上线的完整链路
+- 每个节点标注：谁做、用什么工具、什么Skill、输入输出
+- 标准流程 10 步 + Hotfix 分支 4 步
+- 新增工具链衔接总览表
+
 ---
 
 ## §13. 项目维度组织