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

工具链端到端模拟报告

模拟目的：用真实场景走一遍完整流程，暴露设计文档中"语义通但实操不通"的问题 作者：庞统（副军师）🐦 日期：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 通知改动者"是对的，但具体怎么做？

# .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：

# .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。但谁触发？

- 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 中固化