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 通知改动者"是对的**，但具体怎么做？

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