auto-sync: 2026-06-06 08:59:29

2026-06-06 08:59:29 +08:00
parent 752123d60b
commit 406f437703
1 changed files with 460 additions and 0 deletions
@@ -0,0 +1,460 @@
+# 工具链端到端模拟报告
+
+> 模拟目的：用真实场景走一遍完整流程，暴露设计文档中"语义通但实操不通"的问题
+> 作者：庞统（副军师）🐦
+> 日期：2026-06-06
+
+---
+
+## 模拟场景
+
+**需求**：moziplus v2 的 blackboard API 缺少批量获取任务状态的接口，导致前端轮询效率低。
+
+**涉及角色**：庞统（协调）、张飞（编码）、司马懿（审查+测试）
+
+---
+
+## Step 0: 问题发现 → 需求 Review
+
+### 发生了什么
+主公在 webchat 跟庞统说："前端轮询太频繁了，API 效率低，加个批量接口。"
+
+### 庞统做了什么
+1. 梳理需求：前端需要一次请求获取多个任务状态，减少轮询次数
+2. 分析技术方案：在 `/api/projects/{pid}/tasks` 加 `?ids=id1,id2,id3` 查询参数
+3. Mail 通知司马懿确认技术可行性
+
+### 实际串联方式
+
+```
+主公 → webchat → 庞统
+庞统 → Mail API → 司马懿
+  POST /api/mail {
+    from: "pangtong-fujunshi",
+    to: "simayi-challenger",
+    title: "需求确认: 批量获取任务状态接口",
+    text: "方案: GET /tasks?ids=id1,id2,id3 返回 {id: status}。可行吗？"
+  }
+```
+
+司马懿回复 Mail 确认可行。
+
+### ⚠️ 暴露的问题
+
+**P1: Gitea Issue 是谁创建的？怎么创建的？**
+
+设计文档写"庞统创建 Gitea Issue"，但：
+- 庞统是 openclaw agent，能调 Gitea API 吗？**不能**——openclaw 没有 Gitea API 工具
+- 当前只能用 exec curl 调 Gitea API，但 Gitea token 从哪来？**未配置**
+- 或者人工在 Gitea Web UI 上创建？那就不算自动化
+
+**解法选项**：
+- A. CI workflow 里用 Gitea token，庞统通过 exec curl 调（需要配 token）
+- B. 写一个 MCP 工具封装 Gitea API（一劳永逸，但开发量大）
+- C. 人工在 Web UI 创建（最简单，但不自动化）
+
+**P2: Review 通过与否的状态怎么记录？**
+
+当前靠 Mail 往返——庞统发 Mail，司马懿回 Mail。但 Mail 没有"通过/不通过"的结构化状态，只是文本。如果需求变了，没有可追溯的记录。
+
+**解法选项**：
+- A. 在 Gitea Issue 的描述里记录 Review 结果（Issue 本身就是记录）
+- B. 用 Gitea Issue Comment 记录 Review 过程（和 PR Review 一样）
+
+---
+
+## Step 1: Issue 创建 → 分支创建
+
+### 假设 Issue 已创建（#42）
+
+### 谁创建分支？
+
+设计文档写"开发者创建分支"。但：
+- 张飞是 openclaw agent，被庞统通过 Mail 通知后，张飞怎么知道要做什么？
+- 张飞收到 Mail 后，自己 git checkout -b？还是要有人触发张飞？
+
+### 实际串联方式（两种可能）
+
+**方式 A：庞统 spawn 张飞**
+
+```
+庞统收到司马懿确认 Mail → 庞统 spawn 张飞
+  sessions_spawn {
+    task: "实现 Gitea Issue #42: 批量获取任务状态接口。
+           分支: feat/issue-42-batch-task-status
+           方案: GET /api/projects/{pid}/tasks?ids=id1,id2,id3
+           验收: 测试通过 + CI 通过",
+    taskName: "issue-42-batch-status"
+  }
+```
+
+张飞 spawn 后自带上下文（task 描述），可以直接开始工作。
+
+**方式 B：张飞自己启动**
+
+张飞自己有个 main session，收到 Mail 后读取 Mail 内容，自己决定开始工作。
+
+### ⚠️ 暴露的问题
+
+**P3: Agent 怎么被触发开始工作？**
+
+设计文档没说清楚 Agent 工作的触发方式。有两种模式：
+
+1. **被动模式（被 spawn）**：庞统用 sessions_spawn 创建子 Agent，任务自包含。这是 moziplus v2 现有的编排方式
+2. **主动模式（自己读 Mail）**：Agent 有常驻 main session，收到 Mail 后自己决定做什么。这是三国团队实际的运行方式（每个 Agent 有自己的 openclaw main session）
+
+**实际是主动模式**——张飞收到 Mail 后自己去读 Issue、创建分支、开始编码。
+
+**但这带来一个问题**：张飞怎么读 Gitea Issue？exec curl 调 Gitea API？那又要 token。
+
+**P4: Agent 的 git 操作权限**
+
+张飞要 push 代码到 Gitea，需要：
+1. Gitea 账号（token）
+2. git remote 配置正确
+3. git credential 配置
+
+当前所有项目的 git remote 指向 gitee 或 NAS Gitea。如果统一用 Gitea，每个 Agent 的 git config 需要配好 token。
+
+---
+
+## Step 2: 编码 → CI 快速门控
+
+### 张飞编码过程
+
+```
+张飞在 main session 中：
+1. git checkout -b feat/issue-42-batch-task-status
+2. 编辑 src/api/task_routes.py — 添加 ?ids= 查询参数
+3. 编辑 tests/unit/test_task_routes.py — 写 UT
+4. git commit -m "feat(tasks): add batch status query by ids"
+5. git push origin feat/issue-42-batch-task-status
+```
+
+### CI 自动触发
+
+```
+Gitea 收到 push → Gitea Actions 自动触发 ci.yml
+  → on: push (匹配所有分支)
+  → 跑 lint + unit tests
+  → 结果显示在 commit status（绿勾/红叉）
+```
+
+### ⚠️ 暴露的问题
+
+**P5: Gitea Actions 还没启用！**
+
+整个 CI 链路的起点是 Gitea Actions。但当前：
+- Gitea v1.23.4 的 Actions 功能需要 admin 在 `app.ini` 里启用
+- act-runner 还没安装
+- CI workflow 文件（`.gitea/workflows/ci.yml`）还没写
+
+**P6: Agent 怎么知道 CI 结果？**
+
+张飞 push 后，CI 在后台跑。张飞怎么知道结果？
+
+- Gitea Status Check 是给人看的（Web UI）
+- Agent 不会自己去看 Gitea Web UI
+- 需要 CI 跑完后通过某种机制通知 Agent
+
+**设计文档写的"CI 失败 → Mail 通知改动者"是对的**，但具体怎么做？
+
+```yaml
+# .gitea/workflows/ci.yml 中需要加的 step
+- name: Notify on failure
+  if: failure()
+  run: |
+    curl -X POST http://localhost:8083/api/mail \
+      -H "Content-Type: application/json" \
+      -d "{
+        \"from\": \"ci-notifier\",
+        \"to\": \"${{ env.GIT_AUTHOR_NAME }}\",
+        \"title\": \"CI 失败: ${{ github.ref_name }}\",
+        \"text\": \"CI 在分支 ${{ github.ref_name }} 上失败。请检查。分支: feat/issue-42-batch-task-status\"
+      }"
+```
+
+**但这里有问题**：`${{ env.GIT_AUTHOR_NAME }}` 是 git 用户名（比如 "Zhang Fei"），不是 openclaw agent ID（"zhangfei-dev"）。需要一个映射。
+
+---
+
+## Step 3: PR 创建 → CI 标准门控
+
+### 张飞创建 PR
+
+张飞 push 完，觉得代码写好了，创建 PR：
+
+```
+张飞 exec: curl -X POST http://192.168.2.154:3000/api/v1/repos/{owner}/{repo}/pulls \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{
+    "title": "feat(tasks): add batch status query by ids",
+    "body": "Closes #42\n\n## Changes\n- Added ?ids= query param to GET /tasks\n- Returns {id: status} map\n- UT added",
+    "head": "feat/issue-42-batch-task-status",
+    "base": "main"
+  }'
+```
+
+### CI 标准门控自动触发
+
+```
+PR 创建 → Gitea Actions on: pull_request 自动触发
+  → 跑完整 CI（lint + unit + integration + coverage）
+  → 结果显示在 PR 页面
+```
+
+### ⚠️ 暴露的问题
+
+**P7: PR 创建是手动的还是自动的？**
+
+设计文档写"开发者创建 PR"。但实际上：
+- Agent 要用 exec curl 调 Gitea API 创建 PR（又要 token）
+- 或者人工在 Gitea Web UI 上创建（不自动化）
+- **没有"push 完自动创建 PR"的机制**——这和 GitHub 的"push 后自动创建 draft PR"不同
+
+**P8: 风险级别自动标注怎么实现？**
+
+设计文档写"自动标注风险级别（基于改动文件路径）"。但：
+- Gitea 没有内置这个功能
+- 需要自己实现：一个 GitHub Action（Gitea Action）在 PR 创建时分析 diff，打标签
+- 或者靠 git-workflow Skill 注入——Agent 创建 PR 时自己标注
+
+**实际最简方案**：git-workflow Skill 里写规则，Agent 创建 PR 时在 body 里标注风险级别，审查者确认。
+
+**P9: Agent 怎么知道 CI 标准门控通过了？**
+
+同样的问题——Agent 不会自己去看 PR 页面。需要通知。
+
+方案同 P6：CI 通过/失败都发 Mail 通知。
+
+---
+
+## Step 4: 代码审查
+
+### CI 通过后进入审查
+
+设计文档写"CI 通过后 Gitea 自动通知审查者"。
+
+### 实际怎么通知司马懿？
+
+**Gitea 内置通知**：Gitea 在 PR 上指定 Reviewer 时，会给该用户发站内通知。但司马懿是 openclaw agent，不看 Gitea 站内通知。
+
+**必须走 Mail**：
+
+```yaml
+# .gitea/workflows/ci.yml 中加的 step
+- name: Request review
+  if: success()
+  run: |
+    curl -X POST http://localhost:8083/api/mail \
+      -H "Content-Type: application/json" \
+      -d "{
+        \"from\": \"ci-notifier\",
+        \"to\": \"simayi-challenger\",
+        \"title\": \"Review 请求: PR #42\",
+        \"text\": \"CI 通过。PR #42 feat(tasks): batch status query。请在 Gitea Review。\"
+      }"
+```
+
+### 司马懿审查
+
+司马懿收到 Mail → 在 Gitea Web UI 上 Review → Approve 或 Request Changes。
+
+### ⚠️ 暴露的问题
+
+**P10: 司马懿怎么做 Code Review？**
+
+司马懿是 openclaw agent。两种方式：
+
+1. **司马懿在 Gitea Web UI 上 Review**（人工模式）：不是自动化的——需要有人在司马懿的 session 里手动操作
+2. **司马懿通过 Gitea API Review**：司马懿用 exec curl 调 Gitea API 读取 PR diff，然后用 code-review Skill 分析，最后调 Gitea API 提交 Review 意见
+
+方式 2 才是自动化的，但需要 Gitea token + code-review Skill 里写明 Gitea API 调用方式。
+
+**P11: Review 不通过怎么通知张飞？**
+
+张飞不会自己去看 Gitea PR 评论。必须走 Mail：
+
+```
+司马懿 Review 不通过 →
+  exec: curl POST /api/mail {
+    from: "simayi-challenger",
+    to: "zhangfei-dev",
+    title: "Review 不通过: PR #42",
+    text: "...审查意见..."
+  }
+```
+
+**但谁来触发这个 Mail？** 司马懿的 code-review Skill 应该指导他在 Review 完成后自动发 Mail。
+
+---
+
+## Step 5: Merge → 部署
+
+### 审查通过 + CI 通过 → Merge
+
+Gitea branch protection 确保 CI 通过 + Review Approve 后才能 merge。
+
+### 谁点 Merge？
+
+1. **张飞自己**（在确认 Review 通过后）：exec curl 调 Gitea API merge PR
+2. **庞统**（作为协调者确认后）
+3. **自动**（CI 通过 + Review 通过后自动 merge）
+
+**推荐张飞自己 merge**——他是最清楚代码是否完成的人。git-workflow Skill 指导他在 Review 通过后调 API merge。
+
+### Merge 后自动部署
+
+```
+Merge → Gitea Actions on: push: branches: [main] 自动触发 deploy workflow
+  → deploy.sh --source=... --health-check
+  → 记录版本到 deploy-history.jsonl
+  → 健康检查
+  → 失败: deploy.sh --rollback + Mail 通知庞统/姜维
+```
+
+### ⚠️ 暴露的问题
+
+**P12: deploy workflow 还没写**
+
+deploy.yml 和 deploy.sh 都还没写。每个项目需要：
+1. 编写 `.gitea/workflows/deploy.yml`
+2. 编写 `scripts/deploy.sh`（含 --version、--rollback、--health-check）
+3. 配置 deploy-history.jsonl 的路径
+
+**P13: 部署成功的通知**
+
+部署成功后，应该通知庞统关闭 Issue。但谁触发？
+
+```yaml
+- name: Notify deployment success
+  if: success()
+  run: |
+    curl -X POST http://localhost:8083/api/mail \
+      -H "Content-Type: application/json" \
+      -d "{
+        \"from\": \"ci-notifier\",
+        \"to\": \"pangtong-fujunshi\",
+        \"title\": \"部署成功: {repo} {version}\",
+        \"text\": \"PR #42 已部署。请确认后关闭 Issue #42。\"
+      }"
+```
+
+---
+
+## Step 6: Issue 关闭
+
+### 庞统收到部署成功通知
+
+庞统 exec curl 调 Gitea API 关闭 Issue：
+
+```
+curl -X PATCH http://192.168.2.154:3000/api/v1/repos/{owner}/{repo}/issues/42 \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state": "closed"}'
+```
+
+---
+
+## 汇总：暴露的问题清单
+
+| 编号 | 问题 | 严重度 | 解法 |
+|------|------|--------|------|
+| **P1** | Agent 没有 Gitea API 工具，只能 exec curl | 高 | 配置 Gitea token + 在 Skill 中固化 curl 调用方式 |
+| **P2** | 需求 Review 没有结构化记录 | 中 | Review 结果记录在 Gitea Issue Comment 中 |
+| **P3** | Agent 工作触发方式不明确 | 高 | **主动模式**：Agent 收到 Mail 后自主行动。Skill 中固化"收到 Mail 后做什么" |
+| **P4** | Agent 的 git/Gitea 权限未配置 | 高 | 每个 Agent 的 git credential 配好 Gitea token |
+| **P5** | Gitea Actions 未启用 | 高 | 姜维 P0 操作 |
+| **P6** | Agent 不知道 CI 结果 | 高 | CI workflow 中加 Mail 通知 step（需要 git 用户名→Agent ID 映射） |
+| **P7** | PR 创建需要 exec curl | 中 | git-workflow Skill 固化 PR 创建的 curl 命令 |
+| **P8** | 风险级别自动标注没有实现 | 低 | 初期靠 Agent 在 PR body 中手动标注，后期可写 Action 自动化 |
+| **P9** | Agent 不知道 CI 标准门控结果 | 高 | 同 P6 |
+| **P10** | 司马懿通过 Gitea API Review | 中 | code-review Skill 固化 Gitea Review API 调用方式 |
+| **P11** | Review 不通过需要 Mail 通知 | 中 | code-review Skill 指导 Review 完成后发 Mail |
+| **P12** | deploy workflow 和 deploy.sh 未写 | 高 | P1 实施时编写 |
+| **P13** | 部署成功后通知关闭 Issue | 中 | deploy workflow 中加 Mail 通知 step |
+
+---
+
+## 关键发现：串联的核心瓶颈
+
+### 1. 通知是串联的生命线
+
+整个流程能跑起来，**核心依赖 Mail 通知在每个环节之间传递信息**。
+
+```
+庞统 → Mail → 司马懿（需求 Review）
+庞统 → Mail → 张飞（任务指派）
+CI → Mail → 张飞（CI 结果）
+CI → Mail → 司马懿（Review 请求）
+司马懿 → Mail → 张飞（Review 不通过）
+CI → Mail → 庞统（部署成功）
+```
+
+**6 个 Mail 通知点**，缺一个流程就断了。
+
+### 2. 所有 Gitea 操作都靠 exec curl
+
+Agent 没有 Gitea MCP 工具。所有 Gitea 操作（创建 Issue、创建 PR、提交 Review、Merge PR、关闭 Issue）都是 exec curl 调 Gitea API。
+
+**这要求**：
+- Gitea token 配好（每个 Agent 的环境变量）
+- Skill 中固化每个操作的 curl 命令模板
+- Agent 知道仓库 owner、repo name 等信息
+
+### 3. Agent ID ↔ Git 用户名映射
+
+CI workflow 中 `GIT_AUTHOR_NAME` 是 git 用户名，Mail API 需要 agent ID。需要一个映射表：
+
+| Git 用户名 | Agent ID |
+|-----------|----------|
+| Zhang Fei | zhangfei-dev |
+| Jiang Wei | jiangwei-infra |
+| Sima Yi | simayi-challenger |
+| Pang Tong | pangtong-fujunshi |
+
+### 4. 全自动化的最低要求
+
+要让流程真正全自动跑起来，P0 必须就位：
+
+| 项 | 为什么必须 |
+|----|-----------|
+| Gitea Actions 启用 | CI 根本跑不起来 |
+| act-runner 安装 | CI 没执行器 |
+| Gitea token 配置 | Agent 无法操作 Gitea |
+| ci.yml 编写 | CI 没有流程定义 |
+| Mail 通知 steps | Agent 不知道 CI 结果 |
+| git-workflow Skill | Agent 不知道怎么操作 Gitea |
+
+---
+
+## 真正的全自动化流程（理想态）
+
+如果所有基础设施就位，全自动化流程长这样：
+
+```
+1. 主公提需求 → 庞统收到 → 自动梳理方案
+2. 庞统 Mail → 司马懿 → 司马懿 Mail 回复确认
+3. 庞统 exec curl 创建 Issue → 庞统 Mail → 张飞
+4. 张飞收到 Mail → git checkout -b → 编码 → git push
+5. push 自动触发 CI（Gitea Actions）→ CI 跑 lint+unit
+6. CI 完成 → Mail 通知张飞结果
+7. 张飞 exec curl 创建 PR → CI 自动触发标准门控
+8. CI 通过 → Mail 通知司马懿 Review
+9. 司马懿 exec curl 读 diff → Skill 审查 → exec curl 提交 Review
+10. Review 通过 → Mail 通知张飞 → 张飞 exec curl merge
+11. Merge 自动触发 deploy workflow → deploy.sh 跑 → 健康检查
+12. 部署成功 → Mail 通知庞统 → 庞统 exec curl 关闭 Issue
+```
+
+**每一步都是自动的，没有人工干预。** 串联机制就是 Gitea Actions 自动触发 + Mail 通知驱动 Agent 行动。
+
+---
+
+## 设计文档需要补充的内容
+
+1. **Mail 通知是串联的核心机制**——需要在 §9 中明确，不只是"通知方式"而是"流程驱动力"
+2. **所有 Gitea 操作都是 exec curl**——需要在 Skill 中固化 curl 模板
+3. **Gitea token 配置**——P0 必须项
+4. **Agent ID ↔ Git 用户名映射表**——CI workflow 需要
+5. **每个环节的 Mail 触发点**——需要在 workflow yml 和 Skill 中固化