auto-sync: 2026-06-06 08:44:58

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 步
 - 新增工具链衔接总览表
+- 新增衔接机制详解：每一步怎么触发下一步、靠什么技术、怎么通知
 
 ---