From 28309da988e0df1c49b9962348f0a3933f75b395 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 6 Jun 2026 08:40:09 +0800 Subject: [PATCH] auto-sync: 2026-06-06 08:40:09 --- docs/design/13-toolchain-and-dev-workflow.md | 189 +++++++++++++++++++ 1 file changed, 189 insertions(+) diff --git a/docs/design/13-toolchain-and-dev-workflow.md b/docs/design/13-toolchain-and-dev-workflow.md index f783ca4..cc89fa2 100644 --- a/docs/design/13-toolchain-and-dev-workflow.md +++ b/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. 项目维度组织