From 37c1b167a9b0b408d1f7ad8e71f8af32a6c7b6dd Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 6 Jun 2026 08:44:58 +0800 Subject: [PATCH] auto-sync: 2026-06-06 08:44:58 --- docs/design/13-toolchain-and-dev-workflow.md | 86 ++++++++++++++++---- 1 file changed, 71 insertions(+), 15 deletions(-) diff --git a/docs/design/13-toolchain-and-dev-workflow.md b/docs/design/13-toolchain-and-dev-workflow.md index 75f4cba..12bf97f 100644 --- a/docs/design/13-toolchain-and-dev-workflow.md +++ b/docs/design/13-toolchain-and-dev-workflow.md @@ -675,22 +675,77 @@ Agent spawn 走生产 openclaw 的决策理由： └─────────────────────────────────────────────┘ ``` -#### 工具链衔接总览 +#### 衔接机制：每一步怎么触发下一步 -| 环节 | 工具 | 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 | +上图只画了"谁做什么"，这里补清楚**步骤之间靠什么机制衔接**。 + +| 衔接点 | 触发方式 | 通知方式 | 技术实现 | +|--------|---------|---------|----------| +| 问题入口 → 问题Review | 庞统收到问题后主动发起 | Mail 通知司马懿（需求类）/ 司马懿自己提交（bug类） | Mail API POST `/api/mail` | +| 问题Review → Issue创建 | Review结论达成 | 庞统或司马懿创建 | Gitea API `POST /repos/{owner}/{repo}/issues` | +| Issue创建 → 分支创建 | 庞统指派任务给开发者 | Mail 通知被指派者，含 Issue #N + 分支名 | Mail API + Agent 读取 Issue | +| 分支创建 → 编码 | 开发者看到 Mail 后开始 | 无额外通知 | Agent 启动时 Skill 注入分支信息 | +| 编码 → CI 快速门控 | **git push 自动触发** | CI 结果自动评论到 commit | Gitea Actions webhook（内置） | +| CI 快速门控 → PR创建 | 开发者主动（认为代码写完） | 无自动通知 | 开发者在 Gitea Web UI 或 git push + 浏览器创建 PR | +| PR创建 → CI 标准门控 | **PR 创建/更新自动触发** | CI 结果自动评论到 PR | Gitea Actions `on: pull_request` | +| CI 标准门控 → 代码审查 | **CI 通过后 Gitea 自动通知审查者** | Gitea PR Review 请求通知 | Gitea branch protection + Reviewer 指定 | +| 代码审查 → 修改（不通过） | 审查者提交 Review 意见 | PR 评论通知改动者 | Gitea PR Review API | +| 代码审查 → Merge（通过） | **审查者点 Approve** | 无额外通知 | Gitea PR Review `APPROVE` | +| Merge → 部署 | **merge 到 main 自动触发** | 无需通知（自动化） | Gitea Actions `on: push: branches: [main]` | +| 部署 → E2E | **部署 job 成功后触发 E2E job** | E2E 结果评论到 merge commit | Gitea Actions `needs: [deploy]` | +| E2E/部署 → Issue关闭 | 庞统或改动者手动确认后关闭 | Issue 关闭通知关注者 | Gitea API `PATCH /repos/{owner}/{repo}/issues/{id}` state=closed | +| CI失败 → Issue评论 | **CI 失败自动评论** | 评论到关联 Issue | Gitea Actions `if: failure()` step | +| 部署失败 → 自动回滚 | **deploy.sh 失败自动执行** | 无需通知（自动化） | Gitea Actions `if: failure()` step 调 `deploy.sh --rollback` | + +#### 关键衔接机制详解 + +**1. Gitea Actions 自动触发（核心衔接）** + +整个 CI/CD 链路的自动化靠 Gitea Actions 的触发机制： + +``` +git push feature分支 + → Gitea Actions on: push 匹配 + → 跑 lint + unit（快速门控） + +创建 PR + → Gitea Actions on: pull_request 匹配 + → 跑 lint + unit + integration + coverage（标准门控） + → CI 结果自动出现在 PR 页面 + +Merge 到 main + → Gitea Actions on: push: branches: [main] 匹配 + → 跑 deploy workflow（含 deploy.sh + health check + E2E） + → 全自动，无需人干预 +``` + +触发链：push → CI → PR → CI → Review → merge → deploy+E2E，中间三个自动环节靠 Gitea Actions 的 `on` 触发器串联。 + +**2. Mail 通知（Agent 间协调）** + +CI/CD 之外的人工衔接靠 Mail： + +- 需求Review完成 → Mail 通知开发者开始 +- Bug确认 → Mail 通知改动者（含根因） +- Hotfix确认 → Mail 通知执行者 +- 审查不通过 → 已通过 Gitea PR 评论解决，Mail 不介入 + +**3. Gitea branch protection（硬门控）** + +确保流程不可跳过： +- `main` 分支设置：CI 必须通过 + 至少 1 人 Review Approve +- 效果：没有 CI 绿勾 + Review Approve，merge 按钮灰色不可点 +- 配置位置：Gitea → 仓库 Settings → Branches → Branch Protection + +**4. Agent 间通知机制总结** + +| 场景 | 通知方式 | 为什么不用另一种 | +|------|---------|----------------| +| 人→Agent任务指派 | Mail | Gitea Issue 不会主动通知 Agent，需要 Mail 推送 | +| CI 结果 | Gitea 自动评论 | 自动化，不需 Mail | +| Review 请求 | Gitea Reviewer 指定 | Gitea 内置通知 | +| Review 意见 | Gitea PR 评论 | 附带行号，Mail 不方便 | +| 跨Agent协作请求 | Mail | Gitea 不支持跨 Agent 私信 | ### 9.1 场景 A：新功能开发 @@ -890,6 +945,7 @@ Agent spawn 走生产 openclaw 的决策理由： - 每个节点标注：谁做、用什么工具、什么Skill、输入输出 - 标准流程 10 步 + Hotfix 分支 4 步 - 新增工具链衔接总览表 +- 新增衔接机制详解：每一步怎么触发下一步、靠什么技术、怎么通知 ---