sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests 2 Actions 1 Packages Projects Releases Wiki Activity
Files
9727bf98d939f067179398ecf6dc0b016aa06f13
sanguo_moziplus_v2/docs/design/13-toolchain-and-dev-workflow.md
T

3290 lines
136 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 三国团队工具链与开发流程设计
> **状态**: v3.3 — #19 上下文四层改造合并 + CI 修复 + A13 修订
> **作者**: 庞统（副军师）🐦
> **评审**: 司马懿（仲达）🗡️
> **日期**: 2026-06-06
> **v0.4 变更**: 主公 6 条反馈（需求review前置、E2E用户触发、测试分工、审查默认司马懿、项目维度组织、分支保护说明）
> **v0.5 变更**: E2E 改为自动跑（CI隔离环境不污染生产）、三环境架构、schema变更检查确认、分支保护确认开启
> **v0.6 变更**: Agent spawn 走生产 openclaw（不隔离）、程序逻辑走 CI 隔离环境、路径硬编码修复清单
> **定位**: 普适工具链和开发流程，适用于三国团队所有项目，与 moziplus 2.0 解耦
---
## §1. 设计原则
| # | 原则 | 说明 |
|---|------|------|
| 1 | **声明式 + 代码执行分离** | 规则声明在配置中，执行由框架代码保证，不依赖 Agent 自觉（来源: moziplus-quality-governance） |
| 2 | **能自动就自动** | CI/CD/部署能自动触发就不手动，人只做决策和审查 |
| 3 | **Skill 固化流程** | 所有流程通过 Skill（提示词）固化，不靠口头约定 |
| 4 | **分级治理** | 按风险级别选择流程严格度，不搞一刀切（来源: quality-gate-patterns） |
| 5 | **验证才算完** | Agent 说"完成"不算，CI 通过 + 产出物存在才算（来源: 幻觉门控） |
| 6 | **每个项目自带部署** | 部署脚本归项目管，工具链负责触发和验证，不替项目做部署决策 |
| 7 | **需求/问题必须经过 Review** | 所有需求和问题提交前必须经过 Review，不直接进入开发 |
| 8 | **项目维度组织** | 所有内容（Issue、CI、部署、Skill 配置）以项目为单位组织，支持多项目并行 |
---
## §2. 基础设施层
### 2.1 代码托管：Gitea（唯一）
| 项 | 配置 |
|----|------|
| 地址 | `http://192.168.2.154:3000` |
| 版本 | v1.26.2（2026-06-11 从 v1.23.4 升级） |
| 认证 | HTTP + token；admin 账号（姜维持有） |
| 权限 | 姜维持有 admin 权限（启用 Actions、分支保护、org webhook 等） |
| 数据库 | SQLite3 |
| 部署方式 | Docker（NAS 群晖），数据卷 `/volume2/@docker/volumes/gitea-data/_data` |
### 2.2 CI/CD：Gitea Actions
| 项 | 配置 |
|----|------|
| Runner | Mac mini 裸机，gitea-runner v1.0.8（通过 PM2 管理 `sanguo-act-runner`） |
| 配置文件 | `.gitea/workflows/*.yml`，每个项目自管 |
| 语法 | 兼容 GitHub Actions（v1.26.2 已验证支持 concurrency groups） |
| 触发 | push / PR / tag / workflow_dispatch |
| v1.26 新增 | concurrency groups、re-run failed jobs、可配置 GITEA_TOKEN 权限 |
| 仍不支持 | `failure()`、`continue-on-error`、`timeout-minutes` |
### 2.4 Gitea 基础设施 Setup 记录（2026-06-11 姜维）
> 以下为 Gitea 从 v1.23.4 升级到 v1.26.2 的完整操作记录，作为未来参考。
#### 2.4.1 升级 v1.23.4 → v1.26.2
**升级原因**：v1.23.4 不支持 concurrency groups，导致双倍触发问题无根因解法。
**升级步骤**：
1. 备份：`docker exec sanguo_gitea gitea dump -c /data/gitea/conf/app.ini -f /data/gitea/gitea-backup-pre-v126.zip`（765MB）
2. 拉取镜像：Mac 上 skopeo 下载 → python docker SDK 远程 load（群晖 Docker Hub 太慢）
3. 停止旧容器 + rename 保留回滚
4. 启动新容器（数据库自动迁移 Migration[312]→[326]，含 concurrency #323）
5. 验证：API + Web UI + 仓库数据 + 用户数据
**踩坑：群晖内核 3.10 + git 2.52 不兼容**：
- 根因：git 2.52 使用 `getrandom(2)` syscall，群晖内核 3.10.108 不支持（3.17 才加入）
- 症状：`git push` 报 `unable to create temporary file: Function not implemented`
- 修复：entrypoint 脚本在容器启动时自动从本地缓存降级 git 到 2.45.4
- 持久化：`/data/entrypoint-wrapper.sh` + `/data/git-2.45.4-r0.apk` 在数据卷里，容器重建不丢失
- 群晖内核**无法通过 DSM 升级**，内核版本跟硬件型号绑定
**完整重建命令**：
```bash
docker -H tcp://192.168.2.154:2375 run -d \
--name sanguo_gitea \
--restart=always \
-p 3000:3000 \
-p 2221:22 \
-v /volume2/@docker/volumes/gitea-data/_data:/data \
-e GITEA__database__DB_TYPE=sqlite3 \
-e GITEA__database__PATH=/data/gitea/gitea.db \
-e GITEA__server__ROOT_URL=http://192.168.2.154:3000/ \
--entrypoint /bin/sh \
gitea/gitea:1.26.2 \
-c '/data/entrypoint-wrapper.sh'
```
#### 2.4.2 act_runner 升级 v0.2.11 → v1.0.8
**升级原因**：v0.2.11 的 multi-step job 执行有 bug，Setup Python 和 Lint step 被跳过。
**升级步骤**：
1. 下载 `gitea-runner-1.0.8-darwin-arm64`（从 gitea.com releases）
2. `codesign --force --sign -` 重签（macOS Gatekeeper 会 SIGKILL 未签名的二进制）
3. 替换 `/Users/chufeng/bin/act_runner`
4. PM2 restart `sanguo-act-runner`
**注意**：act_runner 通过 **PM2** 管理（`sanguo-act-runner`），不是 launchd。launchd plist 仅为备份。
**PM2 常用命令**：
```bash
pm2 restart sanguo-act-runner # 重启
pm2 logs sanguo-act-runner # 查看日志
pm2 show sanguo-act-runner # 详情
```
#### 2.4.3 CI Workflow 配置
**三个 workflow 文件**：
| 文件 | 触发 | concurrency | 说明 |
|------|------|-------------|------|
| `ci.yml` | `pull_request` | `group: ci-${{ gitea.ref }}, cancel-in-progress: true` | 同一 PR 新 push 自动取消旧 run |
| `deploy.yml` | `push to main` | `group: deploy-${{ gitea.ref }}, cancel-in-progress: false` | 部署排队不取消 |
| `e2e.yml` | `workflow_dispatch` | `group: e2e-${{ gitea.ref }}, cancel-in-progress: true` | 手动触发 |
**Branch Protection（main 分支）**：
- 禁止直接 push
- status check：`CI / lint (pull_request)` 必须通过
- 至少 1 人 Review
**⚠️ 踩坑**：v1.26 上报的 commit status context 格式变了：
- 旧格式：`lint`
- 新格式：`CI / lint (pull_request)`
- branch protection 必须用新格式匹配，否则 merge 报 "Not all required status checks successful"
#### 2.4.4 Org Webhook 配置
- **对象**：Gitea 组织 `sanguo` webhook id=28
- **URL**：`http://192.168.2.153:8083/webhook/gitea`
- **事件**：16 个（push/issues/PR/PR review 等）
**⚠️ 踩坑**：Gitea v1.26 的 PATCH hooks API，只传 `{"active": true}` 会把 events 重置为 `["push"]`。**必须每次 PATCH 都带上完整的 events 列表。**
**临时措施（已恢复）**：2026-06-10 曾临时关闭 webhook（CI 错误大爆炸期间），2026-06-11 已恢复。
#### 2.4.5 凭据管理
| 凭据 | 用途 | 持有者 |
|------|------|--------|
| Gitea admin:cf7561523 | 仓库管理、branch protection、org webhook | 姜维 |
| Gitea PAT (jiangwei-infra) | API 操作、git clone/push | 姜维 |
| Gitea PAT (cfdaily) | CI workflow 中的 git 操作 | CI secrets |
#### 2.4.6 备份与回滚
| 项目 | 路径 | 说明 |
|------|------|------|
| Gitea 数据库备份 | `/data/gitea/gitea-backup-pre-v126.zip` | 升级前 dump |
| 旧容器 | 已清理 | 升级验证通过后 `docker rm` |
| 变更记录 | `~/.openclaw/workspace-jiangwei/changes/gitea-emergency-2026-06-10.md` | 完整操作日志 |
| 环境 | 位置 | 说明 |
|------|------|------|
| Mac mini 本机 | `~/.sanguo_projects/<project>/` | 主力开发和运行环境 |
| NAS Docker | `192.168.2.154` | 部分服务（Gitea、回测等） |
#### 2.4.7 Gitea 迁移验证记录（2026-06-11 司马懿）
> 验证 Gitea 从 gitee 迁移完成后的状态。所有验证在 2026-06-11 完成。
**仓库迁移状态**：
| 项目 | Gitea 仓库 | 开发目录 | 远程地址 | gitee 残留 |
|------|-----------|---------|---------|----------|
| sanguo_moziplus_v2 | `sanguo/sanguo_moziplus_v2` | `~/.openclaw/sanguo_projects/sanguo_moziplus_v2/` | `http://192.168.2.154:3000/sanguo/sanguo_moziplus_v2.git` | ✅ 无 |
| sanguo_quant_live | `sanguo/sanguo_quant_live` | `~/.openclaw/sanguo_projects/sanguo_quant_live/` | `http://192.168.2.154:3000/sanguo/sanguo_quant_live.git` | ✅ 无 |
| sanguo_vnpy | `sanguo/sanguo_vnpy` | `~/.openclaw/sanguo_projects/sanguo_vnpy/` | `http://192.168.2.154:3000/sanguo/sanguo_vnpy.git` | ✅ 无 |
**验证方法**：在 3 个开发目录分别执行 `git remote -v`，确认 origin 指向 gitea 且无 gitee remote。
**CI 管道验证**：
| 验证项 | 结果 | 备注 |
|--------|------|------|
| PR #33 Lint 修复 CI 通过 | ✅ | flake8 全通过 |
| CD pipeline (deploy.yml) 合并 | ✅ | 含 CI + deploy + notify-deploy-failure 三个 job |
| Branch protection 生效 | ✅ | main 分支需 CI 通过 + 1 人 Review 才能合并 |
| Gitea squash merge 兼容 | ✅ | `merge_commit_sha` 在 squash merge 下仍等于 gitea.sha |
**工具链事件中枢验证**：
| Webhook → Mail 流 | 验证结果 |
|-------------------|--------|
| PR opened → Review 请求 Mail | ✅ 司马懿收到 PR #30-#35 的 Review 请求 |
| PR review → 结果 Mail | ✅ 张飞/庞统收到 Review 结果通知 |
| Issue assigned → 指派 Mail | ✅ （E2E 验证通过） |
| CI 失败评论 → 通知 Mail | ✅ （E2E 验证通过） |
| PR synchronize → reviewer 重审 Mail | ✅ 新增（§23） |
| Review COMMENTED → PR 作者通知 | ✅ 新增（§23） |
**Agent Gitea 凭据**（各 Agent 自行持有 PAT）：
| Agent | Gitea 用户名 | PAT 用途 |
|-------|-------------|--------:|
| simayi-challenger | simayi-challenger | PR Review 提交 |
| pangtong-fujunshi | pangtong-fujunshi | PR 创建/合并、代码 push |
| jiangwei-infra | jiangwei-infra | 基础设施配置（admin 级操作） |
---
## §3. 分支策略
### 3.1 采用 Trunk-Based Development（简化版）
选 Trunk-Based 而非 Git Flow 的理由：
- **团队小**（<10 人），不需要复杂的 release 分支
- **AI Agent 参与编码**，Agent 在短生命周期 feature 分支上工作，完成后快速合并
- **CI 是安全网**，main 分支始终可部署，feature 分支通过 CI 才能合并
前提条件：**Agent 必须知道当前所在分支**。git-workflow Skill 需注入 `git branch --show-current` 到 Agent 上下文（仲达 Q1 补充）。
### 3.2 分支规则
| 分支类型 | 命名 | 生命周期 | 合并方式 | 适用场景 |
|---------|------|---------|---------|---------|
| `main` | `main` | 永久 | — | 始终可部署 |
| feature | `feat/<issue-N>-<简述>` | <3天 | PR → CI → Review → merge | 新功能 |
| bugfix | `fix/<issue-N>-<简述>` | <1天 | PR → CI → merge | Bug 修复 |
| hotfix | `hotfix/<简述>` | <2小时 | 直接 push main + CI + 自动回滚 | 紧急修复 |
### 3.3 分支保护规则
- `main` 分支：
- 不允许直接 push（hotfix 除外）
- PR 必须通过 CI（至少 unit + integration tests）
- PR 必须至少 1 人 Review（人或 Agent）
- **hotfix 直接 push main 后必须触发 CI**（至少 lint + unit），CI 失败则自动 revert（M1 修订）
- feature/bugfix 分支：
- 无保护，自由 push
- 合并前必须 CI 通过
### 3.4 Commit 规范
```
<type>(<scope>): <subject>
<body>
```
| type | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `refactor` | 重构（不改行为） |
| `test` | 测试相关 |
| `docs` | 文档 |
| `chore` | 构建/工具/配置 |
---
## §4. 问题管理
### 4.1 问题来源
| 来源 | 入口 | 处理方式 |
|------|------|---------|
| 主公口头 | 庞统记录，**经 Review 后** | 创建 Gitea Issue |
| 司马懿 Review | Review 意见 | 创建 Gitea Issue，关联 PR |
| 自动化测试失败 | CI 报告 | 自动评论到已有 Issue，或手动创建 |
| 用户测试反馈 | 人工报告 | 创建 Gitea Issue |
| Agent 运行发现 | Agent 日志，**经 Review 后** | 创建 Gitea Issue |
### 4.2 Issue 标签体系
| 标签 | 颜色 | 说明 |
|------|------|------|
| `bug` | 红 | 功能异常 |
| `feature` | 蓝 | 新功能需求 |
| `improvement` | 绿 | 改进优化 |
| `security` | 橙 | 安全相关 |
| `risk:high/standard/low` | 分级色 | 风险级别（见 §6.1 判定规则） |
| `priority:high/medium/low` | 黄/灰 | 优先级 |
| `blocked` | 紫 | 阻塞中 |
### 4.3 需求/问题 Review 前置
所有需求和问题在进入开发之前必须经过 Review：
| 类型 | Review 者 | 目的 |
|------|-----------|------|
| 新需求 | 庞统（方案合理性）+ 司马懿（技术可行性） | 确认需求清晰、可行、值得做 |
| Bug/问题 | 司马懿（确认根因）或庞统（确认优先级） | 确认是真 bug、不是误报，根因明确 |
| Agent 发现的问题 | 庞统（确认有效性） | 过滤误报 |
未经过 Review 的 Issue 不进入开发流程。
### 4.4 Issue 状态流转
```
Open → In Progress → Review → Closed
↑ ↓
└──── Reopened ←───────────────────┘
```
---
## §5. CI/CD 管道设计
### 5.1 通用 CI 流程（所有项目共享骨架）
每个项目在 `.gitea/workflows/ci.yml` 自定义具体步骤，但遵循统一骨架。
> **注**：Gitea Actions v1.26.2 不支持 `paths` 过滤触发条件。通过路径判断放在 job 级别的 `if` 条件中，使用确定支持的语法。（M4 修订）
```yaml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
# Job 1: 后端测试
backend:
# 只在有 Python 代码变更时跑
runs-on: [self-hosted, mac-mini]
steps:
- uses: actions/checkout@v4
- name: Setup Python
run: |
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
- name: Lint
run: .venv/bin/ruff check src/
- name: Unit Tests
run: .venv/bin/pytest tests/unit/ -m "not e2e" --tb=short
- name: Integration Tests
run: .venv/bin/pytest tests/integration/ --tb=short
- name: Coverage Report
run: .venv/bin/pytest --cov=src --cov-report=term-missing
# Job 2: 前端构建
frontend:
# 只在有前端目录时跑
runs-on: [self-hosted, mac-mini]
steps:
- uses: actions/checkout@v4
- name: Install & Build
run: |
cd src/frontend
npm ci
npm run build
- name: Type Check
run: cd src/frontend && npx tsc --noEmit
```
**实际使用时**：每个项目根据实际情况删减 job。没有前端的删 frontend job，没有 Python 的删 backend job。
### 5.2 CI 门控级别
| 级别 | 触发条件 | 跑什么 | 阻断行为 |
|------|---------|--------|---------|
| **快速** | feature 分支 push | lint + unit tests | **软阻断**：失败标红，创建 PR 时如果最近一次 CI 失败则不允许进入 Review（S2 修订） |
| **标准** | PR 到 main | lint + unit + integration + coverage | 阻断 merge |
| **完整** | tag / main push | 标准 + build（E2E 仅 tag 触发） | 阻断部署 |
| **手动** | 手动触发 | 完整 + 特定检查 | 按需 |
### 5.3 覆盖率渐进策略（仲达 Q3 补充）
当前多数项目从未跑过覆盖率，直接设阈值不现实。分三阶段：
| 阶段 | 时间 | 覆盖率策略 | 说明 |
|------|------|-----------|------|
| **P1** | 启用后 2 周 | 只报告不阻断 | 先拿基线数据 |
| **P2** | 启用后 1 月 | 40% 阈值，低于警告不阻断 | 逐步提升 |
| **P3** | 启用后 2 月+ | 60% 阈值，低于阻断 | 正式生效 |
### 5.4 CI 结果反馈
- ✅ 通过 → PR 可合并
- ❌ 失败 → PR 阻断，自动评论失败信息
- 覆盖率低于阈值 → P1 只报告，P2 警告，P3 阻断
---
## §6. 代码审查流程
### 6.1 风险级别判定规则（M2 修订）
风险级别不由改动者自评，按以下规则自动判定 + 非改动者确认：
**自动判定规则**（在 CI 或 PR 模板中检查）：
| 规则 | 级别 | 触发条件 |
|------|------|---------|
| 涉及核心模块 | **高** | 改动文件匹配 `**/spawner*`、`**/ticker*`、`**/dispatcher*`、`**/router*`、`**/guardrails*`、`**/strategy*`、`**/risk*` |
| 涉及资金/安全 | **高** | 改动包含交易逻辑、风控规则、密钥管理、资金操作 |
| 数据库 schema 变更 | **高** | 改动匹配 `**/migrations/**`、`**/schema*`、`**/models.py` 中的表定义 |
| 常规功能开发 | **标准** | 不匹配高风险规则的 src/ 下改动 |
| 文档/测试/配置 | **低** | 改动仅在 `docs/`、`tests/`、`*.md`、`*.yaml`（非 guardrails） |
**确认机制**：
1. PR 创建时自动标注风险级别（基于 git diff 文件路径）
2. 审查者（或庞统）确认或升级——**只能升级不能降级**
3. 改动者可以申请升级（但不能申请降级）
### 6.2 审查方式（按风险分级）
| 风险级别 | 审查方式 | 审查者 |
|---------|---------|--------|
| **高** | 固定 Review（必须） | 司马懿（专职） |
| **标准** | 固定 Review（必须） | 司马懿（默认审查者） |
| **低** | 简化走查 | 司马懿（快速确认）+ CI 通过 |
**例外**：司马懿自己的改动 → 庞统交叉审查。
> 所有级别的代码审查默认由司马懿执行。只有司马懿作为改动者时，才由庞统进行交叉审查。不再按改动领域分配审查者——简化流程，减少协调成本。
### 6.3 审查者分配规则
| 改动者 | 审查者 |
|--------|--------|
| 张飞 / 姜维 / 关羽 / 赵云 / 庞统 | 司马懿（默认） |
| 司马懿 | 庞统（交叉审查） |
### 6.4 审查清单（Skill 固化）
审查清单通过 Skill 提示词固化，不依赖审查者自觉。**基础清单 + 项目类型变体**：
**基础清单（所有项目通用）**：
```
1. 正确性
- [ ] 代码逻辑正确，无死循环/空指针/边界遗漏
- [ ] 异常处理完整（网络超时、文件不存在、参数非法）
- [ ] 改动范围和 Issue/需求描述一致（不多不少）
2. 一致性
- [ ] 命名规范统一（变量/函数/文件）
- [ ] 和已有代码风格一致
3. 安全性
- [ ] 无硬编码密钥/密码/Token
- [ ] 用户输入有校验
- [ ] 文件操作有路径校验
4. 可维护性
- [ ] 复杂逻辑有注释（为什么，不是做什么）
- [ ] 无重复代码（DRY）
- [ ] 关键参数可配置，无魔法数字
5. 测试覆盖
- [ ] 新功能有对应测试
- [ ] Bug 修复有回归测试
- [ ] CI 通过
结论：通过 / 不通过（附具体行号和修改方向）
```
**量化策略项目变体**（追加项）：
```
6. 量化策略专项
- [ ] 止损逻辑完整（触发条件、执行路径、异常兜底）
- [ ] 仓位计算正确（滑点、手续费已计入）
- [ ] 回测参数和实盘参数分离
```
### 6.5 审查时效
| 改动大小 | 期望审查时间 |
|---------|-------------|
| < 100 行 | 2 小时内 |
| 100-500 行 | 半天内 |
| > 500 行 | 1 天内 |
---
## §7. 部署流程
### 7.1 部署触发
| 触发方式 | 适用场景 | 流程 |
|---------|---------|------|
| **自动**（tag 触发） | 正式发布 | 打 tag → CI 完整跑（含 E2E）→ 自动执行 deploy 脚本 → 健康检查 |
| **自动**（main push） | 日常迭代 | push main → CI 标准跑 → 自动执行 deploy 脚本 → 健康检查 |
| **手动** | 紧急/调试 | 手动执行项目 deploy 脚本 |
### 7.2 项目部署脚本规范
每个项目必须提供 `scripts/deploy.sh`，接口统一：
```bash
#!/usr/bin/env bash
# deploy.sh — 项目部署脚本
#
# 必须支持的参数：
# --source=DIR 源码目录（CI 自动传入：源码 checkout 路径）
# --target=DIR 安装目标目录（CI 自动传入：安装路径）
# --skip-build 跳过构建步骤
# --health-check 部署后执行健康检查
# --version 输出当前部署版本（tag + commit hash + 部署时间）
# --rollback 回滚到上一个已记录的部署版本
#
# 必须维护的文件：
# data/deploy-history.jsonl — 最近 10 个部署版本记录
# 每行: {"tag":"v1.2.3","commit":"abc123","timestamp":"2026-06-06T12:00:00+08:00","status":"success"}
#
# 必须返回：
# 0 = 成功
# 非0 = 失败（stderr 输出原因）
```
### 7.3 自动部署 Workflow
```yaml
# .gitea/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
tags: ['v*']
jobs:
deploy:
needs: [ci] # 依赖 CI 通过
runs-on: [self-hosted, mac-mini]
steps:
- uses: actions/checkout@v4
- name: Record current version
run: bash scripts/deploy.sh --version
- name: Deploy
run: bash scripts/deploy.sh --source="$GITHUB_WORKSPACE" --health-check
- name: Rollback on failure
if: failure()
run: bash scripts/deploy.sh --rollback
```
### 7.4 健康检查
每个项目的 deploy 脚本必须包含健康检查：
- HTTP 服务：`curl -sf http://localhost:<port>/api/health`
- 数据服务：数据连通性检查
- 定时任务：PM2 状态检查
### 7.5 回滚策略（M3 修订）
**版本记录**：
- 每次 deploy 成功后，记录 tag + commit + 时间戳到 `data/deploy-history.jsonl`（保留最近 10 条）
- `--version` 读取最后一行输出当前版本
- `--rollback` 读取倒数第二行，checkout 对应 commit，重新 deploy
**回滚流程**：
1. `deploy.sh --rollback` 读取上一个成功版本
2. `git checkout <previous-commit>`
3. 重新执行 deploy（不含 rollback）
4. 健康检查
**已知限制**：
- revert 可能产生合并冲突 → 部署失败时人工介入
- 数据库变更回滚需人工介入 → schema 变更必须向前兼容（只加字段不删/不改），违反此规范由 CI 检查拦截（或人工 Review 拦截）
---
## §8. 验证流程集成
### 8.1 验证来源和层级
| 验证来源 | 层级 | 触发时机 | 自动化程度 |
|---------|------|---------|-----------|
| **Lint** | 机械 | 每次 push | 100% 自动 |
| **单元测试** | 机械 | 每次 push | 100% 自动 |
| **集成测试** | 语义 | PR 到 main | 100% 自动 |
| **覆盖率** | 语义 | PR 到 main | 渐进自动（见 §5.3） |
| **Code Review** | 共识 | PR 到 main | 人工（Skill 辅助） |
| **E2E 测试** | 共识 | PR 到 main 时自动跑（CI 隔离环境）+ 手动触发 | 自动+手动 |
| **用户测试** | 共识 | 部署后 | 手动 |
### 8.2 三阶段门控（来源: quality-gate-patterns）
```
机械门控 (CI 快速) → 语义门控 (CI 标准 + Review) → 共识门控 (E2E + 用户验证)
零成本 中等成本 高成本
语法/lint/编译 API 契约/业务逻辑 端到端/用户体验
```
- 快速门控是**开发期辅助反馈**，不替代标准门控
- **PR 合入必须经过标准门控（机械 + 语义）**，这个顺序不可跳过（S3 修订）
- 机械失败 → 立即阻断，不看 Review
- 语义失败 → 可以 Review 但不能合并
- E2E 在 CI 隔离环境中自动跑，不污染生产环境（见 §8.5）。也可手动触发。
### 8.3 测试失败 → Issue 关联
- CI 失败时，如果已有 Issue → 自动评论失败信息
- CI 失败时，如果无 Issue → 不自动创建（避免 Issue 爆炸），由改动者手动创建
### 8.4 机械门控前提条件（仲达 Q6 补充）
P1 必须先配好以下工具，否则机械门控跑不起来：
| 工具 | 用途 | 安装 |
|------|------|------|
| `ruff` | Python lint + format | `pip install ruff` |
| `pytest-cov` | 覆盖率 | `pip install pytest-cov` |
| `act-runner` | CI 执行器 | 下载 Go 二进制 |
### 8.5 CI 隔离测试环境（E2E 安全运行）
E2E 自动跑的核心前提：**不污染生产环境**。通过 CI 隔离环境实现：
```
CI 临时测试环境（每次 CI 自动创建）
├─ 独立 venv（每次 CI 新建）
├─ 临时 SQLite（tmpdir，跑完销毁）
├─ 临时端口（8084，不和生产 8083 冲突）
├─ 启动 FastAPI 服务 → 跑 E2E → 关闭
└─ 跑完整个 tmpdir 删除，不留痕迹
生产环境（~/.sanguo_projects/）完全不受影响
```
**效果**：E2E 可以在每次 PR 到 main 时自动跑，无需担心污染生产数据或影响生产服务。
#### 隔离边界：程序逻辑 vs Agent 交互
| 层面 | 隔离方式 | 说明 |
|------|---------|------|
| **程序逻辑**（FastAPI + Daemon + SQLite） | ✅ 完全隔离 | 独立 venv + 临时数据库 + 临时端口 | — |
| **Agent spawn**（openclaw agent） | ❌ 走生产 openclaw | openclaw 是全局单例，无法隔离 | 测试 case 用 UUID 前缀标识 + Agent 回写地址指向 8084 临时端口 |
Agent spawn 走生产 openclaw 的决策理由：
1. openclaw 是全局单例（`~/.openclaw/` 只有一份），Agent 配置和 workspace 全局共享
2. 测试 case 会标识测试上下文，Agent 记忆混淆风险低
3. 完全隔离需要在 Docker 中跑独立 openclaw，维护成本不值得
4. Agent 的 API 回写地址由 spawn message 传入，指向 CI 临时服务的端口 8084
#### 路径硬编码修复清单
当前代码有 6 处硬编码绝对路径，需改为环境变量可配置（P1 必须完成）：
| 位置 | 硬编码路径 | 改法 | 现状 | 行数 |
|------|-----------|------|------|------|
| `utils.py` | 数据根目录 | `BLACKBOARD_ROOT` 环境变量 | ✅ 已支持 | 1 |
| `bootstrap.py:42` | Skill 加载路径 | `MOZI_SKILL_PATH` 环境变量 | ✅ 已支持 | 1 |
| `registry.py:264` | 项目扫描目录 `~/.openclaw/sanguo_projects` | 加 `SANGUO_PROJECTS_DIR` | ❌ 硬编码 | 1 |
| `spawner.py:1177,1261` | `~/.openclaw/agents/<id>/sessions.json` | 加 `OPENCLAW_HOME` | ❌ 硬编码 | 2 |
| `blackboard_routes.py:161` | `~/.openclaw/openclaw.json` | 从 `OPENCLAW_HOME` 读 | ❌ 硬编码 | 1 |
共计 6 处（2 已支持、4 待修）。
#### 环境总结
| 环境 | 位置 | 用途 | 生命周期 |
|------|------|------|---------|
| 开发 | `~/.openclaw/sanguo_projects/` | 改代码、本地调试 | 常驻 |
| CI 测试 | CI runner 临时目录 | lint/unit/integration/E2E | CI 跑完即销毁 |
| 生产 | `~/.sanguo_projects/` | 正式运行服务 | 常驻 |
**schema 变更检查**（可选）：CI 中加一步对比数据库 schema 变更，检测破坏性操作（删字段/改类型）。检测到则提 Issue 人工确认。可通过配置开关强制绕过。
---
## §9. 完整开发流程（端到端）
### 9.0 全局工作流串联图
以下是把所有关键环节串起来的完整链路。三个场景（新功能/Bug修复/Hotfix）共享大部分节点，差异在分支。
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 问题/需求入口 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 主公口头 │ │ CI 失败 │ │ 司马懿 │ │ 运行时 │ │
│ │ /需求文档 │ │ 自动报告 │ │ Review │ │ Agent发现 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────────┴──────────────┴──────────────┘ │
│ ↓ │
│ ┌─────────────────────┐ │
│ │ 需求/问题 Review │ ← §4.3 │
│ │ │ │
│ │ 需求: 庞统(方案) │ │
│ │ + 司马懿(可行) │ │
│ │ Bug: 司马懿(确认根因)│ │
│ │ Agent发现: 庞统(过滤)│ │
│ └──────────┬──────────┘ │
│ ↓ 通过 │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ 创建 Gitea Issue #N │ │
│ │ 标签: bug/feature/improvement + risk:high/standard/low │ │
│ │ 关联: PR / 复现步骤 / 根因分析 │ │
│ └──────────────────────────┬────────────────────────────────┘ │
│ ↓ │
│ ┌──── 场景分流 ────┐ │
│ ↓ ↓ │
│ ┌─── Hotfix ───┐ ┌── 标准流程 ──┐ │
│ │ │ │ │ │
│ │ 直接 main │ │ 分支开发 │ │
│ │ │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ ↓ ↓ │
└─────────────────────────────────────────────────────────────────────────┘
=== 标准流程（新功能 / Bug修复）===
┌─────────────────────────────────────────────┐
│ Step 1: 分支创建 │
│ git checkout -b feat/issue-N-xxx │
│ 或 git checkout -b fix/issue-N-xxx │
│ 角色Agent: 开发者（张飞/姜维/关羽/赵云） │
│ Skill: git-workflow │
│ 输入: Issue #N │
│ 输出: feature/bugfix 分支 │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 2: 编码 + 自测 │
│ 编码 → 本地 pytest → commit │
│ 角色Agent: 开发者 │
│ Skill: 按任务类型（无专门编码skill） │
│ 输入: 分支 + Issue 需求 │
│ 输出: 代码改动 + UT │
│ 约束: Bug修复必须加回归测试 │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 3: push → CI 快速门控（每次push） │
│ Lint + Unit Tests │
│ 工具: Gitea Actions │
│ 输入: feature 分支 push │
│ 输出: ✅通过 / ❌失败标红 │
│ 阻断: 软阻断（失败不阻止开发，但阻止PR进入Review）│
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 4: 创建 PR │
│ git push origin → Gitea 创建 PR │
│ 自动: 风险级别标注（按改动文件路径） │
│ 工具: Gitea PR │
│ 输入: feature 分支 + CI 快速门控结果 │
│ 输出: PR + 风险标签 │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 5: CI 标准门控（PR到main时） │
│ Lint + Unit + Integration + Coverage │
│ 环境: CI 隔离临时环境 │
│ 工具: Gitea Actions + pytest-cov + ruff │
│ 输入: PR diff │
│ 输出: ✅通过 / ❌阻断merge │
│ 阻断: 硬阻断（CI不过不许merge） │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 6: 代码审查 │
│ 审查者确认风险级别（只升不降） │
│ 默认审查者: 司马懿（所有级别） │
│ 例外: 司马懿的改动 → 庞统交叉审查 │
│ Skill: code-review │
│ 输入: PR + CI 结果 + 风险级别 │
│ 输出: 通过 / 不通过（附行号+修改方向） │
│ 不通过 → 回到 Step 2 │
└──────────────────┬──────────────────────────┘
↓ 通过
┌─────────────────────────────────────────────┐
│ Step 7: Merge → CI 完整门控 │
│ merge到main → 自动触发 │
│ 标准 CI + deploy workflow │
│ 触发: Gitea branch protection（CI+Review通过才许merge）│
│ 输入: main 分支 │
│ 输出: merge commit + CI 结果 │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 8: 自动部署 │
│ deploy.sh --source=... --health-check │
│ 记录版本到 deploy-history.jsonl │
│ 角色Agent: 姜维（deploy.sh由项目维护） │
│ Skill: ci-cd-ops │
│ 输入: main 分支代码 │
│ 输出: 部署结果 + 版本记录 │
│ 失败: 自动回滚（deploy.sh --rollback） │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 9: E2E 验证（CI 隔离环境自动跑） │
│ 临时venv + 临时SQLite + 临时端口8084 │
│ Agent spawn 走生产 openclaw（不隔离） │
│ 角色: 司马懿写E2E用例，CI自动跑 │
│ Skill: testing-workflow │
│ 输入: 部署后的代码 │
│ 输出: E2E 结果 │
│ 阻断: 初期不阻断，成熟后可阻断 │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step 10: Issue 关闭 │
│ 部署成功 + 验证通过 → 关闭 Issue #N │
│ 发现新问题 → 新开 Issue → 回到入口 Review │
└─────────────────────────────────────────────┘
=== Hotfix 分支流程 ===
┌─────────────────────────────────────────────┐
│ Step H1: 确认 hotfix │
│ 庞统或主公确认（线上故障、核心功能受影响） │
│ Skill: hotfix-workflow │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step H2: 直接 push main │
│ 修改 → commit → push main │
│ CI 必须触发（lint + unit），不可跳过 │
│ CI 失败 → 自动 revert → 人工介入 │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step H3: 自动部署（同标准 Step 8） │
│ E2E 验证（同标准 Step 9） │
└──────────────────┬──────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ Step H4: 24h 内复盘（必须） │
│ 补 Gitea Issue（根因 + hotfix 内容） │
│ 司马懿 Review（事后审查代码质量） │
│ 复盘记录（为什么需要 hotfix、如何避免） │
│ 超时 → 下次 hotfix 权限暂停 │
└─────────────────────────────────────────────┘
```
#### 衔接机制：每一步怎么触发下一步
上图只画了"谁做什么"，这里补清楚**步骤之间靠什么机制衔接**。
| 衔接点 | 触发方式 | 通知方式 | 技术实现 |
|--------|---------|---------|----------|
| 问题入口 → 问题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 Status Check 内置） | Gitea Actions `on: push` |
| CI 快速门控 → PR创建 | 开发者主动（认为代码写完） | 无自动通知 | 开发者在 Gitea Web UI 或 git push + 浏览器创建 PR |
| PR创建 → CI 标准门控 | **PR 创建/更新自动触发** | CI 结果自动评论到 PR | Gitea Actions `on: pull_request` |
| CI 标准门控 → 代码审查 | **CI 通过后 daemon Webhook 转发 Mail 给审查者** | Mail 通知司马懿 Review | Gitea Webhook `pull_request` → daemon Webhook 模块 → Mail API |
| 代码审查 → 修改（不通过） | 审查者提交 Review 意见 | daemon Webhook 转发 Mail 通知改动者（附 Review 摘要） | Gitea Webhook `pull_request_review` → daemon Webhook 模块 → Mail API |
| 代码审查 → Merge（通过） | **审查者点 Approve** | daemon Webhook 转发 Mail 通知改动者 merge | Gitea Webhook `pull_request_review` → daemon Webhook 模块 → Mail API |
| Merge → 部署 | **merge 到 main 自动触发** | Mail 通知 PR 作者合并完成（PR #38） | 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 失败自动评论** → daemon Webhook 转发 Mail 通知改动者 | 评论到关联 Issue + Mail 推送 Agent | Gitea Actions `if: failure()` 写 PR评论 → daemon Webhook 监听 `issue_comment` → Mail |
| 部署失败 → 自动回滚 | **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。Agent 不会自己去看 Gitea PR 评论，所以所有需要 Agent 行动的情况都通过 Mail 推送：
- 需求Review完成 → Mail 通知开发者开始
- Bug确认 → Mail 通知改动者（含根因）
- Hotfix确认 → Mail 通知执行者
- CI 失败 → CI workflow 写 PR 评论 → daemon Webhook 模块转发 Mail 通知改动者 Agent
- 审查不通过 → Mail 通知改动者（附 Review 摘要）
- 部署失败回滚 → 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 Status Check（PR页面）+ daemon Webhook 转发 Mail（Agent通知） | Status Check 给人看，Mail 给 Agent 推送 |
| Review 请求 | daemon Webhook 转发 Mail | Gitea Webhook 触发 → daemon 翻译成 Mail 给司马懿 |
| Review 意见（不通过/通过） | daemon Webhook 转发 Mail | Gitea Webhook 触发 → daemon 翻译成 Mail 给改动者 |
| CI 失败 | CI workflow 写 PR评论 → daemon Webhook 转发 Mail | CI 写评论是给所有人看，Webhook → Mail 给 Agent 推送 |
| 跨Agent协作请求 | Mail | Gitea 不支持跨 Agent 私信 |
### 9.0.1 通知模板（工具链通用版）
以下为 §9.0 衔接机制中用到的通用通知模板。§15.5 中还定义了更详细的流程强约束 Mail 模板（含完整流程步骤和 Gitea API 调用指令）。
所有自动化通知统一格式，确保 Agent 收到后能直接行动。
**模板 1：任务指派（庞统 → 开发者）**
```
From: pangtong-fujunshi
To: {被指派者}
Title: 任务指派: Issue #{N} - {Issue 标题}
Text:
{Issue 标题}
Issue: http://192.168.2.154:3000/{repo}/issues/{N}
分支: feat/issue-{N}-{简述}
风险级别: {high/standard/low}
要点:
- {需求要点1}
- {需求要点2}
验收标准:
- {验收标准1}
- {验收标准2}
```
**模板 2：CI 失败通知（CI workflow → 改动者）**
```
From: daemon-webhook
To: {PR 作者}
Title: CI 失败: PR #{N} - {PR 标题}
Text:
PR #{N} CI 未通过。
PR: http://192.168.2.154:3000/{repo}/pulls/{N}
失败测试:
- {test_path}::{test_name} FAILED
- {test_path}::{test_name} FAILED
失败 step: {step_name}
错误摘要: {error_output_tail_20_lines}
请修复后重新 push。
```
**模板 3：Review 不通过通知（审查者 → 改动者）**
```
From: {审查者}
To: {改动者}
Title: Review 不通过: PR #{N} - {PR 标题}
Text:
PR #{N} 审查未通过。
PR: http://192.168.2.154:3000/{repo}/pulls/{N}
风险级别: {confirmed_level}
审查意见:
1. [{文件}:{行号}] {问题描述} → {修改方向}
2. [{文件}:{行号}] {问题描述} → {修改方向}
必须全部修改后重新 push。
```
**模板 4：部署失败回滚通知（CI workflow → 庞统/姜维）**
```
From: daemon-webhook
To: pangtong-fujunshi, jiangwei-infra
Title: 部署失败已回滚: {repo} {commit_hash}
Text:
{repo} 部署失败，已自动回滚到上一版本。
触发 commit: {commit_hash}
部署脚本: scripts/deploy.sh
失败原因: {deploy_stderr_tail}
当前版本: {previous_version}
请人工介入排查。
```
**模板 5：Bug 确认通知（司马懿 → 改动者）**
```
From: simayi-challenger
To: {改动者}
Title: Bug 确认: Issue #{N} - {Issue 标题}
Text:
根因: {根因描述}
复现步骤: {steps}
影响范围: {scope}
风险级别: {level}
Issue: http://192.168.2.154:3000/{repo}/issues/{N}
分支: fix/issue-{N}-{简述}
请修复并添加回归测试。
```
### 9.1 场景 A：新功能开发
```
1. 问题入口
└─ 主公口头 / 需求文档
└─ 庞统梳理需求方案 → 司马懿确认技术可行性
└─ Review 通过后 → 庞统创建 Gitea Issue #N
2. 分支创建
└─ git checkout -b feat/issue-N-xxx
└─ Agent 或人工编码（git-workflow Skill 注入分支信息到 Agent 上下文）
3. 开发过程中
└─ 每个 commit → push → CI 快速门控（lint + unit）
└─ CI 失败 → 标红但不阻断开发 → 修好再 push
4. 开发完成
└─ git push origin feat/issue-N-xxx
└─ 创建 PR → 自动标注风险级别（基于改动文件路径）
└─ CI 标准门控（lint + unit + integration + coverage）
5. 审查
└─ CI 通过后进入审查
└─ 审查者确认风险级别（只升不降）
└─ 司马懿审查（所有级别默认）
└─ 如果改动者是司马懿 → 庞统交叉审查
└─ 审查不通过 → 修改 → push → CI → 再审
└─ 审查通过 → merge
6. 部署
└─ merge 到 main → 自动触发 CI + deploy workflow
└─ deploy.sh 执行 → 记录版本 → 健康检查
└─ 部署成功 → Issue #N 关闭
└─ 部署失败 → 自动回滚 → 人工介入
7. 验证
└─ CI 隔离环境中自动跑 E2E（不污染生产）
└─ 用户测试（手动）
└─ 发现问题 → 新开 Issue（经 Review 后再开发）
```
### 9.2 场景 B：Bug 修复
```
1. 问题入口
└─ CI 失败 / 司马懿 Review / 运行时发现
└─ 司马懿确认根因（是真 bug 不是误报）
└─ 创建 Gitea Issue #N，标注 bug + 风险级别
2. 根因定位（bugfix-workflow Skill）
└─ 调查根因（不猜，看日志/复现）
└─ 在 Issue 中记录根因
3. 修复
└─ git checkout -b fix/issue-N-xxx
└─ 修改代码 + 添加回归测试（必须）
└─ push → PR → CI → Review
4. 合并+部署
└─ merge → auto deploy → 健康检查
└─ Issue #N 关闭
5. 验证
└─ 确认原 bug 不再复现
```
### 9.3 场景 C：紧急修复（hotfix）（M1/S5 修订）
```
1. 判断是否需要 hotfix
└─ 标准：线上故障影响核心功能，等 PR 流程代价过高
└─ 庞统或主公确认
2. 直接在 main 上修
└─ git commit → push main
└─ CI 必须触发（lint + unit），不可跳过
└─ auto deploy → 健康检查
└─ CI 失败 → 自动 revert → 人工介入
3. 事后复盘（hotfix-workflow Skill）
└─ 24 小时内必须完成：
├─ 补 Gitea Issue（记录根因 + hotfix 内容）
├─ 司马懿 Review（事后审查代码质量）
└─ 复盘记录（为什么需要 hotfix、如何避免）
└─ 超时未复盘 → 下次 hotfix 权限暂停
4. E2E 验证
└─ CI 隔离环境中自动跑 E2E 确认 hotfix 有效
```
---
## §10. Skill 清单（流程固化）（S4 修订）
以下流程通过 Skill 固化到对应 Agent：
| Skill 名 | 固化什么 | 适用 Agent |
|----------|---------|-----------|
| `git-workflow` | 分支创建/命名/合并规范、commit 规范、PR 创建流程、**当前分支注入上下文** | 所有编码 Agent |
| `code-review` | 风险级别判定规则、审查清单（基础+项目变体）、审查标准、结论格式 | 司马懿（默认审查者）、庞统（交叉审查） |
| `ci-cd-ops` | CI 配置规范、deploy 脚本规范、健康检查标准、版本记录规范 | 姜维（平台）、所有项目维护者 |
| `bugfix-workflow` | 根因定位流程、回归测试要求、Issue 关联 | 所有编码 Agent |
| `hotfix-workflow` | hotfix 判断标准、直接 push main 流程、CI 必跑、24h 复盘要求 | 庞统（协调）、张飞、姜维 |
| `testing-workflow` | 测试分工规范、什么时候跑什么测试、测试数据隔离 | 所有 Agent |
| `release-workflow` | tag 规范、changelog、发布流程、数据库 schema 变更向前兼容规范 | 庞统（协调） |
### 测试分工规范（testing-workflow Skill 内）
| 测试类型 | 谁写 | 谁跑 |
|---------|------|------|
| **单元测试（UT）** | 开发者自己（张飞/姜维/关羽/赵云等） | CI 自动 + 开发者本地 |
| **功能测试** | 司马懿（专职） | CI 自动 |
| **集成测试** | 司马懿（专职） | CI 自动 |
| **E2E 测试** | 司马懿（专职） | CI 自动（隔离环境）+ 手动触发 |
| **测试脚本/工具** | 司马懿 + 赵云（数据相关） | 按需 |
> 所有人都能写代码和写 UT。但功能测试、集成测试、E2E 由司马懿专职编写和维护——确保测试视角独立于开发视角。
---
## §11. 实施路线
| 阶段 | 内容 | 前置条件 | 耗时 |
|------|------|---------|------|
| **P0: 基础启用** | Gitea admin 开启 Actions + 部署 act-runner（Mac mini 裸机） | 主公操作 NAS | 30 分钟 |
| **P1: CI 骨架** | 模板 CI workflow + pytest-cov + ruff + 覆盖率基线测量 | P0 | 1 天 |
| **P2: 流程 Skill** | 7 个 Skill 编写（见 §10） | 无 | 2-3 天 |
| **P3: 自动部署** | 部署 workflow + 项目 deploy.sh 规范化 + 版本记录 | P1 | 1-2 天 |
| **P4: 渐进收紧** | 覆盖率阈值 P1→P2→P3、E2E 集成 | P1-P3 | 按需 |
**P1 必须先就位的工具**（否则机械门控跑不起来）：
- `ruff`（lint）
- `pytest-cov`（覆盖率）
- `act-runner`（CI 执行器）
---
## §12. 评审记录
### v0.1 → v0.2 修订清单
| 编号 | 类型 | 问题 | 修订内容 |
|------|------|------|---------|
| M1 | 必须修 | hotfix 安全网不足 | §3.3 明确 hotfix push main 后 CI 必跑，失败自动 revert；§9.3 统一流程 |
| M2 | 必须修 | 风险级别谁来定 | §6.1 新增自动判定规则（按文件路径）+ 非改动者确认机制（只升不降） |
| M3 | 必须修 | 回滚策略过于简单 | §7.2 新增 `--version` 参数和 deploy-history.jsonl；§7.5 重写回滚策略 |
| M4 | 必须修 | CI 语法问题 | §5.1 删除 `hasPython()`/`hasFrontend()` 伪函数，改为每个项目按需删减 job |
| S1 | 建议改 | 轮查配对不合理 | §6.3 改为按改动领域分配，不再固定轮转 |
| S2 | 建议改 | 快速门控"不阻断"是噪音 | §5.2 改为"软阻断"，PR 进入 Review 前检查最近 CI 状态 |
| S3 | 建议改 | 三阶段门控说明不清 | §8.2 补充：快速门控是开发辅助，PR 合入必须标准门控 |
| S4 | 建议改 | Skill 遗漏 | §10 增加 testing-workflow、hotfix-workflow、release-workflow（含 schema 变更） |
| S5 | 建议改 | hotfix 复盘无时限 | §9.3 加 24 小时复盘约束，超时暂停 hotfix 权限 |
| Q1 | 评审回答 | Trunk-Based 够用吗 | §3.1 补充前提：Agent 必须知道当前分支，git-workflow Skill 注入 |
| Q3 | 评审回答 | 覆盖率基线缺失 | §5.3 新增渐进策略（P1 只报告 → P2 40% → P3 60%） |
| Q6 | 评审回答 | 机械门控前提未就绪 | §8.4 新增工具清单，§11 标注 P1 必须先就位 |
### v0.3 → v0.4 修订清单（主公审阅反馈）
| 编号 | 反馈 | 修订内容 |
|------|------|---------|
| F1 | 需求/问题必须经 Review | §1 新增原则 7；§4.3 新增需求 Review 前置规则；§9.1 场景 A 加入 Review 步骤 |
| F2 | E2E 仅用户触发 | §8.1 E2E 改为“仅用户手动触发”；§8.2 门控说明移除 E2E 自动跑；§9.1/9.3 验证步骤更新 |
| F3 | 编码/测试人人能做，功能/集成/E2E 司马懿专职 | §10 新增测试分工规范表 |
| F4 | 审查默认司马懿 | §6.2 简化为司马懿统一审查，仅司马懿自身改动由庞统交叉审查 |
| F5 | 以项目为单位组织 | §1 新增原则 8；Issue 标签体系含项目维度 |
| F6 | 姜维持有 Gitea admin | §2.1 权限更新 |
| F7 | 分支保护含义说明 | §3.3 补充分支保护规则说明 |
| F8 | schema 变更能自动化就自动化 | 保留在 release-workflow，CI check + Issue 兜底 |
### v0.4 → v0.5 修订清单（主公二次审阅）
| 编号 | 反馈 | 修订内容 |
|------|------|----------|
| G1 | E2E 不自动跑是因为怕污染生产，不是不需要 | §8.5 新增 CI 隔离测试环境，E2E 改为自动跑（临时 venv + 临时 SQLite + 临时端口） |
| G2 | 三套环境是否有必要 | §8.5 环境总结表：开发/CI临时/生产，不需要常驻测试环境 |
| G3 | schema 变更检查可以，可选+开关 | §8.5 补充 schema 检查说明：可选 + 配置开关强制绕过 |
| G4 | 分支保护确认开启 | §14 更新为已确认 |
| G5 | E2E 触发方式 | §8.1 更新：CI 自动 + 手动触发 |
### v0.5 → v0.6 修订清单（主公三次审阅）
| 编号 | 反馈 | 修订内容 |
|------|------|----------|
| H1 | Agent spawn 走生产 openclaw，不隔离 | §8.5 新增隔离边界表：程序逻辑隔离 vs Agent 走生产 |
| H2 | 路径硬编码问题 | §8.5 新增路径硬编码修复清单（6 处，2 处已支持、4 处待修） |
### v0.6 → v1.0 定稿（司马懿终审通过）
- 隔离边界表增加"缓解措施"列（仲达建议）
- 路径硬编码清单增加"行数"列（仲达建议）
- 状态标记为 v1.0 定稿
### v1.0 → v1.1（主公要求：补全局工作流串联图）
- §9.0 新增全局工作流串联图：从问题入口到部署上线的完整链路
- 每个节点标注：谁做、用什么工具、什么Skill、输入输出
- 标准流程 10 步 + Hotfix 分支 4 步
- 新增工具链衔接总览表
- 新增衔接机制详解：每一步怎么触发下一步、靠什么技术、怎么通知
- §9.0.1 新增 5 个通知模板（任务指派/CI失败/Review不通过/部署回滚/Bug确认）
- 修正：Agent 不看 Gitea PR 评论，所有需 Agent 行动的场景都走 Mail 推送
### v1.2 → v2.0（串联架构重构）
- §15 新增完整串联架构：Gitea 自动化 + Daemon Webhook 模块 + Mail 执行层
- 核心变更：ci-notifier 取消，Webhook 转发集成到 daemon
- 新增：超时检测（三级处置）+ 失败处置（走 Issue 流程）
- 新增：Mail 模板（流程强约束固化）
- 新增：Skill vs Mail 边界明确
- 新增：Agent ID ↔ Git 用户名映射
- §9.0 衔接机制表更新：所有 ci-notifier 引用替换为 daemon Webhook 模块
- §9.0.1 通知模板 From 字段更新：ci-notifier → daemon-webhook
### v2.0 司马懿终审修订
| 编号 | 类型 | 问题 | 修订内容 |
|------|------|------|----------|
| M1 | 必须修 | 超时阈值统一 4h 不合理 | §15.4 改为从 Mail metadata 读取个性化 deadline，三级处置按超时程度而非绝对时间 |
| S1 | 建议 | Webhook 代码缺少映射步骤 | §15.3 代码示例加 to_agent_id() 映射函数，所有 send_mail 调用都经映射 |
| S2 | 建议 | Webhook 缺签名验证 | §15.3 代码示例加 X-Gitea-Signature HMAC 验证 |
| S3 | 建议 | 缺 Bug 确认模板 | §15.5 新增模板 6（Bug 确认通知） |
- §14 待讨论更新：已确认事项标记，新增 Webhook 模块待讨论项
### v2.0 实施记录（2026-06-06）
| # | 实施项 | 状态 | 备注 |
|---|--------|------|------|
| 1 | Gitea Actions 能力调研 | ✅ | docs/research/gitea-actions-research.md |
| 2 | Mail API 回复能力调研 | ✅ | docs/research/mail-reply-research.md |
| 3 | 路径硬编码修复 | ✅ | 4处改为环境变量，411 tests passed |
| 4 | CI workflow 编写 | ✅ | ci.yml + deploy.yml + e2e.yml |
| 5 | Skill 文件编写 | ✅ | 7个共通技能 |
| 6 | Gitea 仓库创建 | ✅ | sanguo/moziplus-v2（姜维） |
| 7 | act-runner 部署 | ✅ | arm64 裸机 + LaunchAgent（姜维） |
| 8 | 分支保护配置 | ✅ | main: CI通过+1人Review+禁止force push（姜维） |
| 9 | Webhook 配置 | ✅ | 已配未启用（等 daemon 集成）（姜维） |
| 10 | CI Secret 配置 | ✅ | CI_TOKEN（注意：Gitea 保留 GITEA_* 前缀） |
| 11 | Workflow 变量前缀验证 | ✅ | gitea.* 正确，无需修改 |
| 12 | Mail 模板验证 | ✅ | 5项能力全验证通过 |
| 13 | PR #1 创建 | ✅ | feat/initial-setup → main |
| 14 | 开发→安装目录同步 | ✅ | diff 确认一致 |
| - | Webhook daemon 集成 | ⏳ | 需改 daemon 代码，暂不做 |
| - | Mail 模板自动发送（Webhook 触发） | ⏳ | 依赖 Webhook daemon 集成 |
| - | act-runner LaunchAgent 网络就绪优化 | ⏳ | 偶尔 gRPC 连接失败 |
| - | Gitea 升级到 v1.24+ | 💡 | 建议，非必须 |
---
## §13. 项目维度组织
### 13.1 多项目并行
所有内容以项目为单位组织：
| 维度 | 按项目组织 |
|------|------------|
| **代码仓库** | Gitea 上每个项目一个 repo |
| **Issue** | 每个项目的 Issue 独立管理 |
| **CI/CD** | 每个项目自管 `.gitea/workflows/` |
| **部署脚本** | 每个项目自管 `scripts/deploy.sh` |
| **测试** | 每个项目自管 `tests/` 目录 |
| **Skill 配置** | 通用 Skill 共享，项目特定 Skill 放项目仓库 |
特殊：`_general` 项目用于跨项目的通用任务（如工具链基础设施维护）。
---
## §14. 待讨论
1. **Gitea admin 权限**：姜维持有 admin 权限，可负责启用 Actions、配置分支保护等
2. **分支保护**：已确认开启——PR 必须 CI 通过 + 至少 1 人 Review 才能合并到 main
3. **数据库 schema 变更检查**：CI 自动检测破坏性变更（可选，有开关可强制绕过），检测不到的提 Issue 人工干预 — **已确认**
4. **环境架构**：三环境（开发/CI临时/生产），CI 临时环境支持 E2E 自动跑不污染生产 — **已确认**
5. **Webhook 转发模块集成到 daemon**：已确认方向，具体实现待设计（见 §15）
---
## §15. 串联架构
> §15 是 v2.0 的核心新增章节，定义工具链三层串联架构：Gitea 自动化 + Daemon Webhook 模块 + Mail 执行层。
> 此架构取消了之前的 ci-notifier 虚拟角色概念，所有事件流转通过三层清晰分工完成。
### §15.1 串联架构总览
三层架构图：
```
Layer 1: Gitea 自动化（流程引擎）
- Actions: push → CI, PR → CI, merge → deploy
- Status Check: CI 结果自动显示在 PR
- Branch Protection: CI通过+Review通过才许merge
- CI workflow 内可调 Gitea API 写 PR 评论
Layer 2: Daemon 流程编排（转发+监控）
- Webhook 接收模块：监听 /webhook 端点
- 简单事件：Webhook → 解析 → 直接发 Mail
- 复杂事件：Webhook → 解析 → spawn 庞统作为任务节点
- 超时检测：在 ticker 中扫描未回复 Mail
- 失败处置：轻度重发提醒，中度 spawn 庞统，严重创建 Issue
Layer 3: Mail 执行层（Agent 接口）
- Mail = 流程指令 + 回复确认 + 时限
- Agent 收到 Mail 后行动，完成后回复确认
- Mail 线程 = Issue 生命周期可追溯
- 流程强约束固化在 Mail 模板中
```
核心原则：
1. **Gitea 是流程引擎**——所有状态流转靠 Gitea 自己（Actions + Status Check + Branch Protection）
2. **Webhook → Mail 转发集成在 daemon 里**——状态共享，可直接触发下一步
3. **Mail 是 Agent 接口**——Agent 不看 Gitea UI，所有需 Agent 行动的事件通过 Mail 推送
4. **简单事件 daemon 直接处理，复杂事件（多 Agent 协作）spawn 庞统作为协调节点**
5. **没有 ci-notifier**——不需要虚拟角色，Gitea 是流程引擎，daemon 是翻译器+监控器
### §15.2 Gitea Webhook 能力清单
| 事件类型 | 触发时机 | Payload 关键字段 | 工具链用途 |
|---------|---------|----------------|-----------|
| `push` | 代码推送 | commit hash, 分支, 作者 | 不需要转发（Actions 自动处理） |
| `pull_request` (opened) | PR 创建 | PR ID, 标题, 分支, 作者 | → Mail 通知司马懿 Review |
| `pull_request_review` (submitted) | Review 提交 | PR ID, 审查者, 结论(APPROVE/REQUEST_CHANGES), 评论 | → Mail 通知张飞 Review 结果 |
| `pull_request` (closed/merged) | PR 合并 | PR ID, 合并 commit | Mail 通知 PR 作者合并完成（PR #38 恢复） |
| `issue_comment` | PR/Issue 评论 | 评论者, 内容 | CI workflow 写的失败评论 → 转发 Mail |
| `issues` (opened+assigned) | Issue 创建/指派 | Issue ID, 标题, 被指派人 | → Mail 通知开发者 |
| `release` | Release 创建 | tag, 名称 | 触发完整 CI+部署 |
> **说明**：Webhook 是单向 POST，Gitea 发完不管。需要在 daemon 里实现 `/webhook` 端点接收。
### §15.3 Daemon Webhook 模块设计
在 daemon 中新增一个 Webhook 接收模块（FastAPI 路由）：
```python
# src/api/webhook_routes.py
@router.post("/webhook/gitea")
async def handle_gitea_webhook(event: dict, x_gitea_event: str = Header(...), x_gitea_signature: str = Header(None)):
"""接收 Gitea Webhook，翻译成 Mail 或 spawn 庞统"""
# 签名验证（防止伪造）
if x_gitea_signature and WEBHOOK_SECRET:
expected = hmac.new(WEBHOOK_SECRET, json.dumps(event).encode(), sha256).hexdigest()
if not hmac.compare_digest(expected, x_gitea_signature):
raise HTTPException(403, "Invalid webhook signature")
# Git 用户名 → Agent ID 映射
def to_agent_id(git_username: str) -> str:
return GIT_TO_AGENT.get(git_username, git_username)
if x_gitea_event == "pull_request":
action = event["action"]
if action == "opened":
pr_author = to_agent_id(event["pull_request"]["user"]["login"])
await send_mail(to="simayi-challenger", title=f"Review 请求: PR #{event['number']}", ...)
elif action == "closed" and event["pull_request"]["merged"]:
# PR #38: 通知 PR 作者合并完成
await _handle_pr_closed(event)
elif x_gitea_event == "pull_request_review":
state = event["review"]["state"]
if state == "APPROVED":
pr_author = to_agent_id(event["pull_request"]["user"]["login"])
await send_mail(to=pr_author,
title=f"Review 通过: PR #{event['number']}，请 merge", ...)
elif state == "REQUEST_CHANGES":
pr_author = to_agent_id(event["pull_request"]["user"]["login"])
await send_mail(to=pr_author,
title=f"Review 不通过: PR #{event['number']}", ...)
elif x_gitea_event == "issue_comment":
# CI 自动写的失败评论 → 转发给相关 Agent
if "CI 失败" in event["comment"]["body"]:
commenter = to_agent_id(event["sender"]["login"])
await send_mail(to=commenter,
title=f"CI 失败: PR #{event['number']}", ...)
elif x_gitea_event == "issues":
if event["action"] == "assigned":
assignee = to_agent_id(event["assignee"]["login"])
await send_mail(to=assignee,
title=f"任务指派: Issue #{event['number']}", ...)
```
关键设计：
- 模块部署在 daemon 的 FastAPI 里（已有服务，只加路由）
- 和 Mail API 共享 SQLite（直接调内部函数，不经过 HTTP）
- 简单事件（CI失败通知、Review通知、任务指派）直接发 Mail
- 复杂事件（部署失败、架构级 Review 问题）spawn 庞统
### §15.4 回复驱动与超时处置
> daemon ticker 中新增两个定时扫描任务，**回复驱动是主路径，超时检测是兜底**。
**主路径：回复驱动（Agent 回复 Mail 后，daemon 根据结果触发下一步）**
```python
# daemon ticker 每小时跑一次
async def process_flow():
# 路径1：扫描新回复，驱动下一步（主路径）
await check_replies()
# 路径2：扫描超时未回复，兜底处置
await check_stale_flows()
async def check_replies():
"""扫描 Mail 回复，根据结果触发下一步"""
# 查所有有新回复的 Mail（回复在上一轮扫描之后）
replied_mails = queries.find_recently_replied(since=last_scan)
for mail in replied_mails:
reply = get_reply(mail.id)
if is_success_reply(reply):
# 成功 → 记录闭环，不触发动作
# 原因：Gitea 自动化（Actions + Webhook）会自动推动下一步
# 例：张飞回复"已创建PR" → Gitea Webhook 自动通知司马懿 Review
# 例：张飞回复"已merge" → Gitea Actions 自动触发 deploy
log.info(f"Mail {mail.id} 已成功闭环: {reply.text[:100]}")
elif is_failure_reply(reply):
# 失败 → 创建 Issue 走正式流程
await create_issue(
title=f"执行失败: {mail.title}",
labels=["bug"],
body=f"原指令: {mail.text}\n\n失败原因: {reply.text}"
)
# 通知庞统
await send_mail(to="pangtong-fujunshi",
title=f"执行失败已创建 Issue: {mail.title}", ...)
elif is_help_reply(reply):
# 需协助 → spawn 庞统协调
await spawn_agent("pangtong-fujunshi",
f"Agent {reply.from} 执行 '{mail.title}' 遇到困难，请求协助。详情: {reply.text}")
```
**兜底路径：超时检测（Agent 没回复时的处置）**
```python
async def check_stale_flows():
"""扫描超时未回复的 Mail，按个性化 deadline 判断"""
pending_mails = queries.find_pending_requests()
for mail in pending_mails:
deadline_hours = mail.meta.get("deadline_hours", 8) # 默认 8 小时
hours_elapsed = (now() - mail.created_at).total_seconds() / 3600
if hours_elapsed < deadline_hours:
continue # 未超时，跳过
hours_overdue = hours_elapsed - deadline_hours
if hours_overdue < 4:
# 轻度：重发 Mail 提醒
await send_mail(to=mail.to, title=f"提醒: {mail.title}",
text=f"此任务已超时 {hours_overdue:.0f} 小时，请尽快处理。")
elif hours_overdue < 16:
# 中度：spawn 庞统介入
await spawn_agent("pangtong-fujunshi",
f"流程卡住: Mail {mail.id} '{mail.title}' 超时 {hours_overdue:.0f} 小时未回复。请介入协调。")
else:
# 严重：创建 Issue + 通知庞统
await create_issue(title=f"流程严重超时: {mail.title}", labels=["blocked", "priority:high"])
await send_mail(to="pangtong-fujunshi",
title=f"严重超时: {mail.title}，已创建 Issue", ...)
```
**失败处置原则**：
- 所有失败 → Issue 走正式流程，不私下通知 Agent 悄悄解决
- CI 失败 → CI workflow 写 PR 评论 → Webhook → Mail 通知 → Agent 修 → 走标准 PR 流程
- 部署失败回滚 → CI workflow 创建 Issue（priority:high） → 走标准 Bug 修复流程
- 超时未响应 → 三级处置（提醒→庞统介入→Issue+通知主公）
**断点续传**：
- 每个环节的状态都在 Gitea 上（PR 状态、CI 结果、Review 状态）
- Mail 线程提供完整的可追溯记录
- 回复驱动确保正常流程自动推进，超时检测确保异常被捕获
- 流程卡住时，庞统可以根据 Mail 线程 + Gitea 状态快速定位断点并继续
### §15.5 Mail 模板（流程强约束固化）
> **注意**：Mail 模板里固化的是**流程强约束**——这个工作链特有的一步步怎么做。
> 共通技能（git 操作、审查清单等）放在 Skill 里（见 §10）。
**模板 1：任务指派（庞统/daemon → 开发者）**
```
Title: 任务指派: Issue #{N} - {标题}
Text:
Issue: {url}
分支: {branch_name}
风险级别: {level}
验收标准: {criteria}
流程：
1. 创建分支 {branch_name}
2. 编码 + 写 UT
3. push → 等 CI（CI 会自动跑）
4. CI 通过后创建 PR（Gitea API: POST /repos/{owner}/{repo}/pulls）
5. 等 Review（司马懿会自动收到通知）
6. Review 通过后 merge PR
如果 CI 失败：修复后重新 push，回到步骤 3
如果 Review 不通过：按意见修改后重新 push，回到步骤 3
完成后回复此 Mail 确认。
时限：{deadline}
```
**模板 2：Review 请求（Webhook → 司马懿）**
```
Title: Review 请求: PR #{N}
Text:
PR: {url}
标题: {title}
风险级别: {level}
改动文件: {file_list}
流程：
1. 读取 PR diff（Gitea API: GET /repos/{owner}/{repo}/pulls/{N}.diff）
2. 按审查清单审查（参考 code-review Skill）
3. 提交 Review（Gitea API: POST /repos/{owner}/{repo}/pulls/{N}/reviews）
- APPROVE 或 REQUEST_CHANGES
4. 提交后张飞会自动收到通知
完成后回复此 Mail 确认。
时限：{deadline}
```
**模板 3：Review 结果通知（Webhook → 张飞）**
```
Title: Review {result}: PR #{N}
Text:
PR: {url}
结果: {APPROVED / REQUEST_CHANGES}
审查意见: {review_body}
{如果通过}:
流程：merge PR（Gitea API: POST /repos/{owner}/{repo}/pulls/{N}/merge）
{如果不通过}:
流程：
1. 按审查意见修改代码
2. push → CI 自动跑
3. CI 通过后等重新 Review
完成后回复此 Mail 确认。
```
**模板 4：CI 失败通知（Webhook from issue_comment → 张飞）**
```
Title: CI 失败: PR #{N}
Text:
PR: {url}
失败测试: {failed_tests}
错误摘要: {error_summary}
流程：
1. 查看完整 CI 日志（PR 页面）
2. 修复失败的测试
3. push → CI 自动重跑
完成后回复此 Mail 确认。
```
**模板 5：部署失败通知（→ 庞统，复杂事件 spawn）**
```
Title: 部署失败已回滚: {repo}
Text:
仓库: {repo}
触发 commit: {sha}
失败原因: {error}
已自动回滚到: {previous_version}
已自动创建 Issue #{M}。
请协调排查。
```
**模板 6：Bug 确认通知（司马懿 → 改动者）**
```
Title: Bug 确认: Issue #{N} - {标题}
Text:
Issue: {url}
根因: {根因描述}
复现步骤: {steps}
影响范围: {scope}
风险级别: {level}
分支: fix/issue-{N}-{简述}
流程：
1. 创建分支 fix/issue-{N}-{简述}
2. 修复 bug + 写回归测试
3. push → CI 自动跑
4. CI 通过后创建 PR
5. 等 Review
完成后回复此 Mail 确认。
时限：{deadline}
```
### §15.6 Skill vs Mail 边界
| 维度 | Mail 模板 | Skill |
|------|----------|-------|
| 作用域 | 工具链流程特有 | 全局，所有项目通用 |
| 强制度 | 强约束，Agent 必须按流程走 | 按需加载，提升质量 |
| 内容 | 流程步骤+Gitea API 调用指令 | 共通技能（审查清单、git规范等） |
| 示例 | "CI失败→修→push→等CI→等Review" | "怎么写好 UT"、"审查清单" |
| 没有 Skill 能否运转 | ✅ 能（流程不会断） | 只是质量没那么高 |
**原则：没有 Skill，流程还能运转。有了 Skill，流程运转得更好。**
Skill 只放共通的、所有项目都能用的技能：
- `git-workflow`：分支命名、commit 规范（所有项目通用）
- `code-review`：审查清单（所有项目通用）
- `testing-workflow`：测试规范（所有项目通用）
- `bugfix-workflow`：根因定位方法（所有项目通用）
工具链特有的流程（"CI 失败后怎么做"、"Review 通过后怎么做"）全部固化在 Mail 模板里。
### §15.7 Agent ID = Git 用户名（已确认一致）
姜维确认（2026-06-07）：Gitea 注册用户名就是完整 Agent ID，短名用户已删除。
| Agent ID（= Git 用户名） |
|-------------------------|
| pangtong-fujunshi |
| simayi-challenger |
| zhangfei-dev |
| guanyu-dev |
| zhaoyun-data |
| jiangwei-infra |
不需要映射表，`to_agent_id()` 直用。
---
## §16. 事件中枢详细设计
> §16 是对 §15 串联架构的落地设计补充，定义事件中枢的具体实现方案。
> 版本: v1.0-draft | 日期: 2026-06-07 | 状态: 待评审
### §16.0. 讨论纪要
本节记录设计过程中的关键讨论，供未来回溯。
### 两条线的定位（主公决策）
| 线 | 方向 | 机制 | 定位 |
|----|------|------|------|
| **出线** | Agent → Gitea | Agent 直接操作 Gitea，完成后发 Mail 通知下一个 Agent | Gitea = 黑板，Mail = 触发器 |
| **入线** | 外部 → Agent | 外部事件（CI/部署/Webhook）→ 事件中枢 → Mail → Agent | 事件中枢 = 入口 |
**原则 1**：Agent 之间的协作不走事件中枢。中枢只处理"外部 → Agent"。
**原则 2**：所有工具链留痕在 Gitea，Mail 是辅助推送。即使 Mail 失败，Agent 可主动查 Gitea 恢复上下文。
**原则 3**：工具链反馈 Agent 的通知统一走事件中枢，避免散乱。
### 关键决策记录
| # | 决策 | 理由 |
|---|------|------|
| D1 | 不做第三种 task 类型 | 中枢产出就是 Mail（from=system, type=inform），模板填充 description，投递复用 spawner。区别只在内容（模板化）和元数据（结构化），不需要新的数据结构 |
| D2 | 提示词独立模板文件 | 模板和代码分离，改文案不改代码，可审查可扩展 |
| D3 | 中枢是 daemon 内模块 | 要访问 Blackboard 创建 Task，共享进程。用独立路由模块（`toolchain_routes.py`）保持职责清晰 |
| D4 | 同步处理 | 事件处理很轻（解析+模板填充+创建Task），远在 Gitea 5秒超时内。复杂事件未来用 asyncio.create_task |
| D5 | Agent ID = Gitea 用户名，直用 | 姜维确认：Gitea 注册用户名就是完整 Agent ID（zhangfei-dev / simayi-challenger 等），短名已删除。`to_agent_id()` 直用，不需要映射表 |
| D6 | CI/部署通知也走事件中枢 | 统一入口，不走 workflow 直接调 Mail API。CI workflow 写 PR comment → Gitea 触发 issue_comment Webhook → 中枢处理 |
---
### §16.1. 定位与边界
### 1.1 是什么
事件中枢是 daemon 内的一个路由模块，负责将**外部工具链事件**翻译成 Mail 通知推送给 Agent。
### 1.2 不是什么
- 不是消息队列
- 不是 Agent 间通信通道（Agent 间协作走 Mail，不经过中枢）
- 不是编排引擎（任务编排由 dispatcher + spawner 负责）
- 不负责 Agent 回复 Mail 后的流程驱动（由 daemon ticker 的回复驱动机制负责，见 §15.4）
### 1.3 两条线
```
出线（Agent → 工具链）：
Agent 直接操作 Gitea（创建 Issue/PR/Review 等）
→ 完成后发 Mail 通知下一个 Agent
→ 下一个 Agent 去读 Gitea 继续干活
入线（工具链 → Agent）：
外部事件（CI 结果/部署结果/Webhook 事件）
→ 事件中枢
→ 模板化 Mail
→ Agent 收到通知，去 Gitea 查看详情并行动
```
### 1.4 数据流
```
外部事件源 事件中枢 Agent
───────── ────── ──────
Gitea Webhook ─────┐
│
CI workflow ───────┤ toolchain_routes.py Mail Task
(PR comment) ────┤ ┌─────────────────┐ (from: system)
├──→│ 1. 接收事件 │ │
Deploy workflow ──┤ │ 2. 验签/过滤 │ ↓
(PR comment) ────┤ │ 3. 幂等检查 │ dispatcher
│ │ 4. 选模板+填充 │ │
daemon 内部 ───────┘ │ 5. 创建 Mail │ ↓
(预留接口) └─────────────────┘ spawner 投递
```
---
### §16.2. 事件分类与处理
### 2.1 事件来源
| 来源 | 触发方式 | 事件类型 |
|------|---------|---------|
| Gitea Webhook | Gitea 主动 POST | PR opened, Review submitted, Issue assigned, issue_comment |
| CI workflow | CI 写 PR comment → 触发 issue_comment Webhook | CI 失败 |
| Deploy workflow | Deploy 创建 Issue → 触发 issues Webhook | 部署失败 |
| daemon 内部 | 内部函数调用 | 预留，当前不走中枢 |
### 2.2 事件处理矩阵
| 事件 | 来源 | 通知谁 | 模板 | 关键信息 |
|------|------|--------|------|---------|
| `pull_request` opened | Gitea Webhook | 司马懿（Review） | `review_request.md` | PR号、标题、作者、分支、文件列表、风险级别 |
| `pull_request_review` submitted | Gitea Webhook | PR 作者 | `review_result.md` | PR号、审查结论、评论、审查者 |
| `issues` assigned | Gitea Webhook | 被指派人 | `issue_assigned.md` | Issue号、标题、标签、描述、分支名建议 |
| `issue_comment` (CI失败) | CI workflow → Webhook | PR 作者 | `ci_failure.md` | PR号、分支、失败步骤、错误摘要 |
| ~~部署成功~~ | ~~不需要通知~~ | ~~流程自动闭环~~ | ~~—~~ | ~~Gitea Issue 自动关闭~~ |
| `issues` created (标题匹配 🔴 部署失败) | Deploy workflow → Webhook | 姜维 + 庞统 | `deploy_failure.md` | 仓库、commit、失败原因 |
### 2.3 事件过滤规则
不是所有事件都需要处理：
| 规则 | 说明 |
|------|------|
| 只处理白名单内的事件类型 | 未知的忽略 + 日志 |
| issue_comment 需判断来源 | 只处理 CI workflow 写的评论（按特定前缀匹配：`❌ **CI 失败**` 或统一后的 `[CI]` 前缀） |
| PR 作者/审查者必须是已知 Agent | 未知的忽略 + 日志 |
| 幂等：同一事件不重复创建 Mail | 双重去重：① delivery UUID（`{event}-{delivery}`）标准幂等；② review 事件 payload 内容去重（`{event}:{pr_num}:{sender}:{sha256(body_or_content)[:16]}`），防御同一 review 被不同来源重复提交（2026-06-09 新增） |
---
### §16.3. 模板系统
### 3.1 模板文件组织
```
templates/toolchain/
├── review_request.md # PR opened → 司马懿 Review
├── review_result.md # Review submitted → PR 作者
├── issue_assigned.md # Issue assigned → 开发者
├── ci_failure.md # CI 失败 → PR 作者
└── deploy_failure.md # 部署失败 → 庞统+姜维
```
### 3.2 模板格式
模板使用 `{variable}` 占位符，中枢填充后生成 Mail description。
**示例：`review_request.md`**
```markdown
PR Review 请求
PR: http://192.168.2.154:3000/{repo}/pulls/{pr_number}
标题: {pr_title}
作者: {pr_author}
分支: {branch}
风险级别: {risk_level}
改动文件:
{file_list}
流程：
1. 读取 PR diff（Gitea API: GET /repos/{repo}/pulls/{pr_number}.diff）
2. 按审查清单审查（参考 code-review Skill）
3. 提交 Review（Gitea API: POST /repos/{repo}/pulls/{pr_number}/reviews）
4. 提交后改动者会自动收到通知
完成后回复此 Mail 确认。
```
### 3.3 模板变量提取
| 变量 | 来源 | 提取方式 |
|------|------|---------|
| `pr_number` | Webhook payload | `event["pull_request"]["number"]` |
| `pr_title` | Webhook payload | `event["pull_request"]["title"]` |
| `pr_author` | Webhook payload | `to_agent_id(event["pull_request"]["user"]["login"])` |
| `branch` | Webhook payload | `event["pull_request"]["head"]["ref"]` |
| `file_list` | Webhook payload | `event["pull_request"]["changed_files"]` 或需要额外 API 调用 |
| `risk_level` | daemon 计算 | 按文件路径规则匹配（见 §3.4） |
| `repo` | Webhook payload | 从 `event["repository"]["full_name"]` 提取 |
### 3.4 风险级别自动判定（简化版）
按改动文件路径匹配规则：
```python
from pathlib import PurePath
# 高风险文件路径模式（使用 pathlib.PurePath.match，支持 ** 递归）
HIGH_PATTERNS = ["**/spawner*", "**/ticker*", "**/dispatcher*",
"**/router*", "**/guardrails*", "**/strategy*", "**/risk*"]
def calc_risk_level(changed_files: list[str]) -> str:
for f in changed_files:
for pattern in HIGH_PATTERNS:
if PurePath(f).match(pattern):
return "high"
return "standard"
```
---
### §16.4. 技术设计
### 4.1 模块结构
```
src/config/
└── agents.py # Agent ID 统一注册表
src/api/
├── toolchain_routes.py # 事件中枢路由（~250行）
├── mail_routes.py # 现有 Mail API
└── ...
src/daemon/
├── toolchain_templates.py # 模板加载+填充（~80行）
├── mail_notify.py # 现有 Mail 失败通知
└── ...
templates/toolchain/
├── review_request.md
├── review_result.md
├── issue_assigned.md
├── ci_failure.md
└── deploy_failure.md
```
### 4.2 toolchain_routes.py 接口设计
```python
# src/api/toolchain_routes.py
import asyncio
from fastapi import APIRouter, Request, Response
from src.config.agents import AGENT_IDS
from src.daemon.toolchain_templates import TemplateEngine
router = APIRouter()
engine = TemplateEngine()
GITEA_WEBHOOK_SECRET = os.environ.get("GITEA_WEBHOOK_SECRET", "")
_idempotency_lock = asyncio.Lock()
@router.post("/webhook/gitea")
async def gitea_webhook(
request: Request,
x_gitea_event: str = Header(...),
x_gitea_signature: str = Header(None),
x_gitea_delivery: str = Header(None),
):
"""接收 Gitea Webhook，翻译成 Mail"""
body = await request.body()
# 1. 签名验证（HMAC-SHA256，Gitea 1.23.4 已确认）
if GITEA_WEBHOOK_SECRET:
expected = hmac.new(GITEA_WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, (x_gitea_signature or "")):
return Response(status_code=403, content="signature verification failed")
event = json.loads(body)
# 2. 幂等检查（asyncio.Lock 防并发竞态）
if x_gitea_event and x_gitea_delivery:
async with _idempotency_lock:
if _is_duplicate(x_gitea_event, x_gitea_delivery):
return Response(status_code=200, content="duplicate")
# 3. 路由到对应处理器
handler = HANDLERS.get(x_gitea_event)
if not handler:
return Response(status_code=200, content="ignored")
# 4. 处理事件 → 创建 Mail
try:
result = await handler(engine, event)
return Response(status_code=200)
except Exception as e:
logger.exception("Failed to handle %s event", x_gitea_event)
return Response(status_code=500, content=str(e))
```
### 4.3 事件处理器
每个事件类型一个处理函数，职责：解析 payload → 选模板 → 填充 → 创建 Mail Task。
```python
async def handle_issues(engine: TemplateEngine, event: dict) -> str:
"""issues 事件分发：assigned → 通知被指派人；opened + 标题匹配 → 部署失败通知"""
action = event.get("action")
if action == "assigned":
return await _handle_issue_assigned(engine, event)
if action == "opened":
title = event.get("issue", {}).get("title", "")
if "部署失败" in title:
return await _handle_deploy_failure(engine, event)
return None # 忽略其他 action
async def handle_pull_request(engine: TemplateEngine, event: dict) -> str:
"""pull_request 事件分发：只处理 opened，忽略 synchronized/closed/reopened"""
if event.get("action") != "opened":
return None
return await _handle_pr_opened(engine, event)
async def _handle_pr_opened(engine: TemplateEngine, event: dict) -> str:
"""PR opened → Review 请求给司马懿"""
pr = event["pull_request"]
# 提取变量
variables = {
"pr_number": pr["number"],
"pr_title": pr["title"],
"pr_author": to_agent_id(pr["user"]["login"]),
"branch": pr["head"]["ref"],
"repo": event["repository"]["full_name"],
"risk_level": calc_risk_level(get_changed_files(pr)),
"file_list": format_file_list(get_changed_files(pr)),
}
# 填充模板
text = engine.render("review_request.md", variables)
# 创建 Mail Task
meta = {
"source": "toolchain",
"webhook_event": "pull_request_opened",
"pr_number": pr["number"],
"repo": variables["repo"],
}
return create_mail_task(
to="simayi-challenger",
title=f"Review 请求: PR #{pr['number']} {pr['title']}",
text=text,
meta=meta,
)
async def handle_review_submitted(engine: TemplateEngine, event: dict) -> str:
"""Review submitted → 结果通知 PR 作者"""
review = event["review"]
pr = event["pull_request"]
pr_author = to_agent_id(pr["user"]["login"])
state = review["state"] # APPROVED / REQUEST_CHANGES / COMMENTED
if state == "COMMENTED":
return None # 普通评论不通知
variables = {
"pr_number": pr["number"],
"pr_title": pr["title"],
"result": "通过" if state == "APPROVED" else "不通过",
"reviewer": to_agent_id(review["user"]["login"]),
"review_body": review["body"] or "无",
"repo": event["repository"]["full_name"],
}
template = "review_result.md"
text = engine.render(template, variables)
return create_mail_task(
to=pr_author,
title=f"Review {variables['result']}: PR #{pr['number']}",
text=text,
meta={"source": "toolchain", "webhook_event": "review_submitted", "pr_number": pr["number"]},
)
async def handle_issue_comment(engine: TemplateEngine, event: dict) -> str:
"""issue_comment → 判断来源，路由到 CI/部署通知"""
comment_body = event["comment"]["body"]
# 匹配 CI workflow 写的失败评论（当前格式: "❌ **CI 失败**"，未来统一为 "[CI]"）
if "[CI]" in comment_body or "CI 失败" in comment_body:
return await handle_ci_comment(engine, event)
# 部署失败当前走创建 Issue（不走 PR comment），见 §16.8 #6
return None
return None # 非 CI/部署评论不处理
# HANDLERS 注册表
HANDLERS = {
"pull_request": handle_pull_request, # 只处理 opened
"pull_request_review": handle_review_submitted,
"issues": handle_issues, # 处理 assigned + opened(部署失败)
"issue_comment": handle_issue_comment, # 只处理 CI 失败评论
}
```
### 4.4 共用函数
```python
def to_agent_id(gitea_username: str) -> str:
"""Gitea 用户名 → Agent ID。已确认一致，直用。"""
return gitea_username
def create_mail_task(to: str, title: str, text: str, meta: dict) -> str:
"""创建 Mail Task（from=system, type=inform）
复用 mail_notify.py 的模式：直接通过 Blackboard 创建 Task。
"""
# 从 mail_routes.py 提取共用逻辑，或直接复用 mail_notify 的方式
...
def is_duplicate(event_key: str) -> bool:
"""幂等检查：同一事件不重复创建 Mail
存储在 SQLite events 表，daemon 重启后仍有效。
保留最近 7 天记录，ticker 定期清理过期记录。
"""
...
def calc_risk_level(files: list[str]) -> str:
"""按文件路径规则判定风险级别"""
...
def get_changed_files(pr: dict) -> list[str]:
"""从 PR payload 提取改动文件列表
payload 只有 changed_files 数量，需要额外调用 Gitea API:
GET /repos/{owner}/{repo}/pulls/{number}/files
"""
...
```
### 4.5 模板引擎
```python
# src/daemon/toolchain_templates.py
from pathlib import Path
import string
TEMPLATE_DIR = Path(__file__).parent.parent.parent / "templates" / "toolchain"
class TemplateEngine:
def __init__(self, template_dir: Path = TEMPLATE_DIR):
self.template_dir = template_dir
self._cache = {}
def render(self, template_name: str, variables: dict) -> str:
"""加载模板文件并填充变量"""
if template_name not in self._cache:
path = self.template_dir / template_name
self._cache[template_name] = path.read_text()
template = self._cache[template_name]
return template.format_map(defaultdict(str, variables))
```
---
### §16.5. 错误处理
| 场景 | 处理 | HTTP 返回 |
|------|------|----------|
| 签名验证失败 | 日志 warning | 403 |
| payload 解析失败 | 日志 error | 200（不触发 Gitea 重试） |
| 未知事件类型 | 忽略 + 日志 info | 200 |
| 幂等检测到重复 | 忽略 + 日志 info | 200 |
| 未知 Agent（不在映射表） | 忽略 + 日志 warning | 200 |
| PR 文件获取失败（3次重试后） | 降级为 risk_level=standard + 错误信息写入 Mail 正文 | 200（handler 内部处理） |
| 模板填充失败 | 日志 error | 500（触发 Gitea 重试） |
| Mail 创建失败 | 日志 error | 500（触发 Gitea 重试） |
**原则**：
- daemon 自身能处理的错误（格式、过滤、幂等）→ 返回 200，不让 Gitea 无意义重试
- daemon 处理不了的错误（数据库、内部异常）→ 返回 500，让 Gitea 重试
---
### §16.6. CI/Deploy Workflow 配合
### 6.1 CI 失败通知
CI workflow 已有 `notify-on-failure` job（ci.yml），当前格式：
```
❌ **CI 失败**
请检查 CI 日志并修复。
触发 commit: `abc1234`
```
**需要修改**：将 comment 前缀统一为 `[CI]`，方便中枢匹配：
```yaml
# .gitea/workflows/ci.yml — notify-on-failure job
-d "{\"body\": \"❌ **CI 失败**\\n\\n请检查 CI 日志并修复。\"}"
+d "{\"body\": \"[CI] 失败\\n\\n分支: ${{ gitea.ref_name }}\\n触发 commit: \\`${{ gitea.sha }}\\`\\n请检查日志并修复。\"}"
```
### 6.2 Deploy 结果通知
同理，deploy workflow 成功/失败时写 comment：
```yaml
# .gitea/workflows/deploy.yml
- name: Report success
if: success()
run: |
curl -s -X POST \
"http://192.168.2.154:3000/api/v1/repos/{owner}/{repo}/issues/{pr_number}/comments" \
-H "Authorization: token ${{ secrets.CI_TOKEN }}" \
-d "{\"body\": \"[Deploy:成功] 版本: $(bash scripts/deploy.sh --version)\\n请确认后关闭 Issue.\"}"
- name: Report failure
if: failure()
run: |
curl -s -X POST \
"http://192.168.2.154:3000/api/v1/repos/{owner}/{repo}/issues/{pr_number}/comments" \
-H "Authorization: token ${{ secrets.CI_TOKEN }}" \
-d "{\"body\": \"[Deploy:失败] 已回滚到上一版本。原因: ...\"}"
```
---
### §16.7. 配置
| 环境变量 | 用途 | 默认值 |
|---------|------|--------|
| `GITEA_WEBHOOK_SECRET` | Webhook HMAC 签名密钥（可选） | 空（跳过验签） |
| `BLACKBOARD_ROOT` | Blackboard 数据根目录（已有） | `~/.sanguo_projects/sanguo_moziplus_v2/data` |
| `TOOLCHAIN_TEMPLATES_DIR` | 模板文件目录（可选） | `templates/toolchain/` |
---
### §16.8. 待确认项
| # | 项 | 状态 | 结论 |
|---|------|------|------|
| 1 | Agent Gitea 用户名映射 | ✅ 姜维已确认 | 一致（用户名就是完整 Agent ID），直用，不需要映射表 |
| 2 | Gitea Webhook secret | ✅ 已配置 | 组织级 webhook secret = `22760993dff898a190731da43aa8d964`，daemon `GITEA_WEBHOOK_SECRET` 同步 |
| 3 | CI workflow PR comment | ✅ 已有 | ci.yml 已有 notify-on-failure job 写 PR comment，格式为 `❌ **CI 失败**...`，需改为 `[CI]` 前缀 |
| 4 | `from=system` 走内部函数 | ✅ 已确定 | 走内部函数（和 mail_notify.py 一致），不走 HTTP API |
| 5 | PR changed_files | ✅ 已实现 | `_fetch_pr_files()` 调用 Gitea API，3 次重试 + 失败信息写入 Mail正文 |
| 6 | Deploy workflow 通知方式 | ✅ 已确认 | 当前创建 Issue（非 PR comment）。部署通知走 `issues` Webhook（issue created）而非 `issue_comment` |
| 7 | 签名算法 | ✅ 已确认 | Gitea 使用 HMAC-SHA256，代码注释已补 |
| 8 | Webhook 作用范围 | ✅ 组织级 | Gitea 组织级 webhook（Hook ID=28），覆盖 sanguo 下所有仓库，新增仓库自动覆盖 |
| 9 | ALLOWED_HOST_LIST | ✅ 已修复 | Gitea 容器配置 `192.168.2.153, 127.0.0.1, localhost, 172.17.0.0/16, 192.168.2.0/24` |
| 10 | Gitea review payload 格式 | ✅ 姜维调研确认（2026-06-08） | Gitea v1.23.4 review payload 只有 `type` + `content`，没有 `state`/`body`/`user`，这不是 org vs repo 差异而是 Gitea 设计。v1.24.0 格式不变。双格式兼容是防御性编码，保持现状 |
| 11 | Spawner compact 检测窗口 | ✅ 已修复 | 窗口 300s→900s，尾部读取 50KB→1MB。实测长对话中 compact 记录被推出窗口导致漏检 |
| 12 | inform 类型 Mail crash 误标 done | ✅ 已修复 | `_mail_auto_complete` 增加 outcome 感知，inform 用白名单（completed/claimed/no_reply）控制 done 标记。spawner crash cooldown 300s→60s |
---
### §16.9. 实施计划
| 步骤 | 内容 | 依赖 |
|------|------|------|
| 1 | `toolchain_routes.py` 骨架 + Gitea Webhook 接收 + 签名验证 | 无 |
| 2 | `toolchain_templates.py` 模板引擎 | 无 |
| 3 | 5 个模板文件 | 步骤 2 |
| 4 | 4 个事件处理器（PR/Review/Issue/Comment） | 步骤 1+3 |
| 5 | 幂等检查（SQLite events 表，保留 7 天） | 步骤 1 |
| 6 | `create_mail_task` 共用函数（从 mail_routes.py 提取） | 无 |
| 7 | CI/Deploy workflow 加 comment step | 步骤 1+4 |
| 8 | Gitea Webhook 启用 + 测试 | 姜维 |
| 9 | 端到端测试 | 步骤 1-8 |
### 9.1 改动量估算
| 文件 | 行数 | 类型 |
|------|------|------|
| `src/api/toolchain_routes.py` | ~200 | 新增 |
| `src/daemon/toolchain_templates.py` | ~60 | 新增 |
| `templates/toolchain/*.md` | ~170（5个文件） | 新增 |
| `src/api/mail_routes.py` | ~20 | 修改（提取共用函数） |
| `.gitea/workflows/ci.yml` | ~15 | 修改（加 comment step） |
| `.gitea/workflows/deploy.yml` | ~15 | 修改（加 comment step） |
| **总计** | **~480** | |
---
### §16.10. 评审检查清单
- [ ] §0 讨论纪要是否准确反映了决策过程
- [ ] §1 两条线的边界是否清晰（出线不走中枢，入线统一走中枢）
- [ ] §2 事件矩阵是否有遗漏
- [ ] §3 模板内容是否完整，变量提取是否正确
- [ ] §4 接口设计是否合理，共用函数提取是否恰当
- [ ] §5 错误处理策略是否完备
- [ ] §6 CI/Deploy workflow 配合方案是否可行
- [ ] §8 待确认项是否完整
- [ ] §9 实施步骤是否合理
### v2.0 → v2.1 变更（事件中枢落地设计）
| 编号 | 变更内容 |
|------|---------|
| §16 | 新增事件中枢详细设计（§16.0-§16.10），基于 §15 串联架构 v2.0 的落地细节 |
### v2.1 → v2.2 变更（事件中枢完善 + E2E 验证通过）
| 编号 | 变更内容 |
|------|---------|
| §16.8 | #2 更新：组织级 webhook 已配置（Hook ID=28）+ secret 生效；#5 更新：PR 文件获取已实现 3 次重试；新增 #8（组织级覆盖）和 #9（ALLOWED_HOST_LIST 修复） |
| §16.4 | 技术设计更新：幂等检查加 `asyncio.Lock` 防并发竞态（T-02）；Agent ID 提取到 `config/agents.py` 统一管理（T-04）；`_fetch_pr_files` 返回 `Tuple[List[str], str]`，3 次重试 + 失败信息写入 Mail（T-05） |
| §16.5 | 错误处理更新：PR 文件获取失败不再静默，3 次重试后错误信息写入 Mail 正文 |
| 全局 | 广播风暴 bug 修复：`mail_notify.py` 校验 Agent ID，非有效 Agent（如 system）路由给庞统 |
| E2E | S22 模拟测试 13/13 通过；S23 真实 Gitea Webhook 8/8 通过；组织级 webhook 跨仓库投递 + 签名验证通过 |
### v2.2 → v3.0 变更（合并 §14 工具链 Skill + 自动部署）
| 编号 | 变更内容 |
|------|----------|
| §17 | 新增：原 `14-toolchain-skill-and-deploy.md` v1.1 全文合并为 §17「工具链落地设计」 |
| §17.1 | 目标：L1 TOOLS.md + L2 Skill 升级 + deploy.sh + 端到端验证 |
| §17.2 | 知识体系四层定位（L1 操作手段 + L2 流程规范） |
| §17.3 | L1 TOOLS.md：按 6 个角色定制 Gitea API 操作模板 |
| §17.4 | L2 Skill 升级：7 个现有 Skill 对齐事件中枢 + CI |
| §17.5 | deploy.sh + deploy.yml 统一接口（rsync + pm2 + health check + rollback） |
| §17.6 | 端到端验证：S1-S6 六个场景 |
| §17.7 | 覆盖率渐进策略（P1 只报告 → P2 40% → P3 60%） |
| §17.8 | 前端展示：Gitea 自带 CI 管理界面 |
| §17.9 | 实施路线（P1→P4） |
| §17.10 | 前置条件 Checklist（6 项） |
| §17.11 | 评审记录（M1/M2 修正 + S1-S4 采纳） |
---
## §17. 工具链落地设计（原 §14 合并）
> **来源**: 原 `14-toolchain-skill-and-deploy.md` v1.1（仲达评审 M1/M2 修正 + S1-S4 采纳）
> **合并日期**: 2026-06-08
> **定位**: 工具链从"设计完成"到"正式投入使用"的落地设计
---
### §17.1. 目标
把工具链从设计态推进到可使用态：
1. **L1 TOOLS.md**：每个 Agent 的 TOOLS.md 加入 Gitea API 操作模板，收到 Mail 后开箱即用
2. **L2 Skill 升级**：7 个现有 Skill 对齐事件中枢 + CI 实际运行
3. **deploy.sh + deploy.yml**：补完自动部署的实际脚本
4. **端到端验证**：用 sanguo/moziplus-v2 实验项目验证全链路
---
### §17.2. 知识体系四层定位
> 来源: `architecture-v3.0.md` §10 BootstrapBuilder
| 层 | 定位 | 载体 | Token | 工具链职责 |
|----|------|------|-------|-----------|
| **L0** | 铁律层 | AGENTS.md / MEMORY.md | ~500 | 不涉及 |
| **L1** | 角色层 | SOUL.md + **TOOLS.md** | ~2000 | **Gitea API 操作模板**（Agent 自带，开箱即用） |
| **L2** | 引擎注入 | BootstrapBuilder 注入 Skill 全文 | ~1500 | **7 个 Skill v2**（流程规范，Daemon 确定性注入） |
| **L3** | 被动参考 | Skill description，Agent 按需加载 | 按需 | 复用 L2 Skill，不新建 |
**核心原则**：
- L1 给操作手段（"怎么做"）：curl 命令模板、参数说明
- L2 给流程规范（"什么时候做什么"）：审查清单、分支规范、测试策略
- L3 是 L2 的被动触发版本，不需要单独维护
---
### §17.3. L1：TOOLS.md Gitea 操作模板
#### §17.3.1 设计原则
1. **开箱即用**：收到 Mail 后直接复制粘贴 curl 命令即可执行，不需要查文档
2. **按角色定制**：不是每个 Agent 都需要全套 API，只给该角色需要的
3. **统一格式**：所有模板使用相同的环境变量约定
#### §17.3.2 公共变量约定
每个 Agent 的 TOOLS.md 头部加入：
```markdown
## Gitea 工具链
- **地址**: http://192.168.2.154:3000
- **组织**: sanguo
- **认证**: `Authorization: token $GITEA_TOKEN`（各 Agent 使用自己的 token）
- **CI 管理界面**: http://192.168.2.154:3000/sanguo/{repo}/actions
```
#### §17.3.3 按角色模板
##### A. 开发者（张飞/关羽/赵云）— PR 创建 + Merge
```markdown
### 创建 PR
```bash
curl -X POST "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"head": "{branch}",
"base": "main",
"title": "{标题}"
}'
# 返回 .number 即 PR 号
```
### 查看 PR diff
```bash
curl "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls/{pr_number}.diff" \
-H "Authorization: token $GITEA_TOKEN"
```
### Merge PR（Review 通过后）
```bash
curl -X POST "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls/{pr_number}/merge" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"Do": "merge", "merge_title_field": "Merge PR #{pr_number}"}'
```
### 查看 CI 状态
```bash
curl "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/commits/{sha}/status" \
-H "Authorization: token $GITEA_TOKEN"
# .state = "success" | "pending" | "failure" | "error"
```
```
##### B. 审查者（司马懿）— Review 操作
```markdown
### 读取 PR diff
```bash
curl "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls/{pr_number}.diff" \
-H "Authorization: token $GITEA_TOKEN"
```
### 查看 PR 改动文件列表
```bash
curl "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls/{pr_number}/files" \
-H "Authorization: token $GITEA_TOKEN"
# 每个文件有 .filename, .additions, .deletions, .changes
```
### 提交 Review
```bash
curl -X POST "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls/{pr_number}/reviews" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "{审查意见}",
"event": "APPROVED"
}'
# event 可选: APPROVED | REQUEST_CHANGES | COMMENT
# ⚠️ 注意：是 APPROVED（过去式），不是 APPROVE
```
### 风险级别判定（自动 + 确认）
规则见 code-review Skill。改动者不能降级，只能维持或升级。
```
##### C. 协调者（庞统）— 全套管理
```markdown
### 创建 Issue + 指派
```bash
curl -X POST "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/issues" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "{标题}",
"body": "{描述}",
"assignees": ["{agent_id}"],
"labels": [1, 2]
}'
# labels 需用数字 ID，先 GET /repos/{owner}/{repo}/labels 查询
```
### 查询仓库 Labels
```bash
curl "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/labels" \
-H "Authorization: token $GITEA_TOKEN"
```
### 查询 PR 列表
```bash
curl "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/pulls?state=open" \
-H "Authorization: token $GITEA_TOKEN"
```
### 创建 Release
```bash
curl -X POST "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/releases" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tag_name": "v{version}",
"name": "v{version}",
"body": "{changelog}",
"target_commitish": "main"
}'
```
### 关闭 Issue
```bash
curl -X PATCH "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/issues/{issue_number}" \
-H "Authorization: token $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"state": "closed"}'
```
```
##### D. 平台运维（姜维）— deploy + runner 管理
在开发者模板基础上追加：
```markdown
### 触发手动部署（需要 push 到 main 或手动 re-run）
```bash
# Re-run 最近一次 workflow
curl -X POST "http://192.168.2.154:3000/api/v1/repos/sanguo/{repo}/actions/runs/{run_id}/rerun" \
-H "Authorization: token $GITEA_TOKEN"
```
### 查看 deploy-history
```bash
cat ~/.sanguo_projects/{project}/data/deploy-history.jsonl
```
### deploy.sh 规范
见 §17.5 deploy.sh 设计。所有项目必须遵循统一接口。
```
#### §17.3.4 实施清单
| Agent | TOOLS.md 新增 | 预计行数 |
|-------|--------------|---------|
| zhangfei-dev | 开发者模板（PR/Merge/CI状态） | ~30 行 |
| guanyu-dev | 开发者模板 | ~30 行 |
| zhaoyun-data | 开发者模板 | ~30 行 |
| simayi-challenger | 审查者模板（diff/review/风险判定） | ~40 行 |
| pangtong-fujunshi | 协调者模板（全套管理） | ~50 行 |
| jiangwei-infra | 开发者 + 平台运维模板 | ~45 行 |
---
### §17.4. L2：Skill 升级到 v2
#### §17.4.1 升级原则
1. **不重写已有内容**，在现有 Skill 基础上追加/修改
2. **对齐事件中枢**：每个 Skill 说明在事件中枢链路中的位置
3. **对齐 CI 实际运行**：ci.yml/deploy.yml 已有实际配置，Skill 要反映真实情况
4. **对齐 Gitea v1.23.4 限制**：不支持 failure()、concurrency、permissions 等
#### §17.4.2 升级内容
##### git-workflow（小改动）
| 改动 | 说明 |
|------|------|
| 追加"事件中枢集成"节 | PR 创建 → Gitea Webhook → 中枢通知司马懿 → Review → 中枢通知作者 → Merge → deploy.yml 自动触发 |
| 追加"CI 自动触发"说明 | push 非 main 分支自动触发 ci.yml；push main 自动触发 deploy.yml |
| 追加"分支感知"强化 | Agent spawn 后必须 `git branch --show-current`，确认分支正确 |
##### code-review（中等改动）
| 改动 | 说明 |
|------|------|
| 追加"事件中枢触发"节 | 收到 Mail → 读 PR diff → 审查 → 提交 Review → Webhook 自动通知作者 |
| 更新风险判定规则 | 对齐 §6.1 实际规则（按文件路径自动判定 + 只升不降） |
| 追加 Gitea Review API 操作 | curl 模板（和 L1 TOOLS.md 一致，这里放流程说明） |
| 追加审查结论格式 | APPROVE / REQUEST_CHANGES 的标准格式 |
##### testing-workflow（小改动）
| 改动 | 说明 |
|------|------|
| 追加"CI 集成"节 | UT 在 CI 自动跑（ci.yml test job）、coverage 在 deploy.yml ci job 跑 |
| 追加"E2E 触发方式" | 通过 e2e.yml 手动触发或 `RUN_INTEGRATION=1 pytest` 本地跑 |
| 追加"测试数据隔离" | CI 使用临时 venv + 临时 SQLite + 临时端口 |
| 追加"广播风暴禁止" | **禁止在 daemon 运行时跑含创建项目/Task/Mail 的测试**，否则会触发 Agent spawn 导致广播风暴。E2E 测试必须在 CI 隔离环境或 daemon 停止后跑 |
##### bugfix-workflow（小改动）
| 改动 | 说明 |
|------|------|
| 追加"事件中枢链路"节 | Bug Issue 创建/指派 → 中枢发 Mail → 修复 → PR → CI → Review → merge |
| 追加"CI 验证"步骤 | 修复后必须等 CI 通过再创建 PR |
##### hotfix-workflow（小改动）
| 改动 | 说明 |
|------|------|
| 追加"CI 自动跑"说明 | hotfix push main → deploy.yml 自动跑 CI + 部署 |
| 追加"失败自动创建 Issue" | deploy.yml notify-on-failure 已实现 |
| 更新 24h 复盘流程 | 复盘结论写到 Issue 评论中 |
##### ci-cd-ops（重写）
| 改动 | 说明 |
|------|------|
| 重写为 v2 | 对齐实际 ci.yml/deploy.yml 结构 |
| 新增 Gitea v1.23.4 限制清单 | 不支持 failure()/concurrency/permissions 等，workaround 方案 |
| 新增覆盖率渐进策略 | P1 只报告 → P2 40% 阈值 → P3 60% 阈值 |
| 新增 deploy.sh 规范 | 统一接口：--version / --source / --target / --health-check / --rollback |
| 新增 CI secret 配置 | CI_TOKEN 作为 repository secret 配置 |
##### release-workflow（中等改动）
| 改动 | 说明 |
|------|------|
| 追加"自动部署触发" | tag 创建 → deploy.yml 自动触发 |
| 追加 deploy-history.jsonl 规范 | 每次 deploy 记录 tag + commit + 时间戳 |
| 更新 schema 变更规范 | 向前兼容 Checklist（加列不加删、默认值、迁移脚本） |
#### §17.4.3 不新建 Skill
现有 7 个 Skill 覆盖所有工具链流程。不需要为事件中枢、CI 操作新建 Skill——这些流程固化在 Mail 模板（§16.4.3）中，Skill 只提供共识功能。
#### §17.4.4 实施清单
| Skill | 改动级别 | 预计改动行数 |
|-------|---------|------------|
| git-workflow | 小 | +15 行 |
| code-review | 中 | +40 行 |
| testing-workflow | 小 | +25 行（含广播风暴禁止约束） |
| bugfix-workflow | 小 | +15 行 |
| hotfix-workflow | 小 | +15 行 |
| ci-cd-ops | 重写 | ~120 行（原 114 行） |
| release-workflow | 中 | +30 行 |
---
### §17.5. deploy.sh + deploy.yml 补完
#### §17.5.1 deploy.sh 统一接口
每个项目的 `scripts/deploy.sh` 必须遵循以下接口：
```bash
#!/bin/bash
# scripts/deploy.sh — 项目部署脚本
# 用法:
# bash scripts/deploy.sh --version # 显示当前版本
# bash scripts/deploy.sh --source=DIR --target=DIR --health-check # 部署
# bash scripts/deploy.sh --rollback # 回滚到上一版本
set -euo pipefail
SOURCE_DIR=""
TARGET_DIR=""
HEALTH_CHECK=false
ACTION="deploy"
for arg in "$@"; do
case $arg in
--version) ACTION="version" ;;
--source=*) SOURCE_DIR="${arg#*=}" ;;
--target=*) TARGET_DIR="${arg#*=}" ;;
--health-check) HEALTH_CHECK=true ;;
--rollback) ACTION="rollback" ;;
esac
done
PROJECT_NAME="{project_name}"
DEPLOY_HISTORY="${TARGET_DIR}/data/deploy-history.jsonl"
version() {
echo "${PROJECT_NAME} deploy version: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
deploy() {
echo "=== Deploying ${PROJECT_NAME} ==="
echo "Source: ${SOURCE_DIR}"
echo "Target: ${TARGET_DIR}"
# 1. 同步文件（排除不需要部署的）
# ⚠️ --delete 会删除目标中源没有的文件，必须排除 data/（生产数据）
rsync -av --delete \
--exclude='.git' \
--exclude='__pycache__' \
--exclude='.venv' \
--exclude='data' \
--exclude='tests' \
--exclude='docs' \
--exclude='.gitea' \
--exclude='node_modules' \
"${SOURCE_DIR}/" "${TARGET_DIR}/"
# 2. 安装依赖
if [ -f "${TARGET_DIR}/pyproject.toml" ]; then
cd "${TARGET_DIR}"
python3 -m venv .venv
.venv/bin/pip install --quiet -e ".[dev]" 2>/dev/null || \
.venv/bin/pip install --quiet -e . 2>/dev/null || true
fi
# 3. 重启服务
if command -v pm2 &>/dev/null; then
pm2 restart ${PROJECT_NAME} 2>/dev/null || true
fi
# 4. 健康检查
if [ "$HEALTH_CHECK" = true ]; then
sleep 3
curl -sf http://localhost:8083/api/health && echo " ✓" || {
echo " ✗ Health check failed!"
exit 1
}
fi
# 5. 记录版本（rollback 时可通过 DEPLOY_OVERRIDE_COMMIT 覆盖）
local commit_hash
if [ -n "${DEPLOY_OVERRIDE_COMMIT:-}" ]; then
commit_hash="${DEPLOY_OVERRIDE_COMMIT}"
else
commit_hash=$(cd "${SOURCE_DIR}" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
fi
local timestamp
timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
echo "{\"timestamp\": \"${timestamp}\", \"commit\": \"${commit_hash}\", \"source\": \"${SOURCE_DIR}\"}" >> "${DEPLOY_HISTORY}"
# 保留最近 10 条
tail -10 "${DEPLOY_HISTORY}" > "${DEPLOY_HISTORY}.tmp" && mv "${DEPLOY_HISTORY}.tmp" "${DEPLOY_HISTORY}"
echo "=== Deploy complete: ${commit_hash} at ${timestamp} ==="
}
rollback() {
if [ ! -f "${DEPLOY_HISTORY}" ]; then
echo "No deploy history, cannot rollback"
exit 1
fi
# 读取倒数第二行的 commit（不依赖 SOURCE_DIR 的 git 状态）
local prev_line
prev_line=$(tail -2 "${DEPLOY_HISTORY}" | head -1)
local prev_commit
local prev_source
prev_commit=$(echo "${prev_line}" | python3 -c "import sys,json; print(json.load(sys.stdin)['commit'])" 2>/dev/null)
prev_source=$(echo "${prev_line}" | python3 -c "import sys,json; print(json.load(sys.stdin).get('source',''))" 2>/dev/null)
if [ -z "${prev_commit}" ] || [ "${prev_commit}" = "unknown" ]; then
echo "Cannot determine previous version"
exit 1
fi
echo "=== Rolling back to ${prev_commit} ==="
# checkout 到指定 commit，部署，然后回到 main
cd "${SOURCE_DIR}"
local current_branch
current_branch=$(git branch --show-current)
git checkout "${prev_commit}"
# 部署时明确传 commit hash，不依赖 HEAD
DEPLOY_OVERRIDE_COMMIT="${prev_commit}" deploy
git checkout "${current_branch:-main}"
}
case $ACTION in
version) version ;;
deploy) deploy ;;
rollback) rollback ;;
esac
```
#### §17.5.2 deploy.yml 更新
替换当前 placeholder：
```yaml
deploy:
runs-on: macos-arm64
needs: ci
steps:
- uses: actions/checkout@v4
- name: Deploy
env:
CI_TOKEN: ${{ secrets.CI_TOKEN }}
run: |
bash scripts/deploy.sh --source="$GITHUB_WORKSPACE" \
--target="$HOME/.sanguo_projects/sanguo_moziplus_v2" \
--health-check
- name: Rollback on failure
if: always()
env:
CI_TOKEN: ${{ secrets.CI_TOKEN }}
run: |
STATUS=$(curl -sf \
-H "Authorization: token $CI_TOKEN" \
"${{ gitea.api_url }}/repos/${{ gitea.repository }}/commits/${{ gitea.sha }}/status" \
| python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))" 2>/dev/null || echo "")
if [ "$STATUS" != "success" ]; then
echo "Deploy failed, rolling back..."
bash scripts/deploy.sh --rollback || echo "Rollback failed, manual intervention needed"
fi
```
#### §17.5.3 实施清单
| # | 内容 | 文件 | 说明 |
|---|------|------|------|
| D1 | 创建 deploy.sh | moziplus-v2 `scripts/deploy.sh` | 从模板创建，项目名填 sanguo_moziplus_v2 |
| D2 | 更新 deploy.yml | moziplus-v2 `.gitea/workflows/deploy.yml` | 替换 placeholder |
| D3 | 同步到 Gitea | push 到 moziplus-v2 | 触发 CI 验证 |
---
### §17.6. 端到端验证：sanguo/moziplus-v2 实验项目
#### §17.6.1 为什么用实验项目
- moziplus-v2 主项目已有正式数据（黑板项目、Mail、Task），不适合做破坏性验证
- sanguo/moziplus-v2 当前是空项目（只有 README.md + .gitea/workflows），可以随意实验
#### §17.6.2 验证场景
| 场景 | 操作 | 预期结果 |
|------|------|---------|
| **S1: CI 触发** | push 分支到实验项目 | ci.yml 自动跑 lint + test |
| **S2: PR Review 流程** | 创建 PR → 中枢 Mail → 司马懿 Review → 中枢通知作者 | 全链路 Mail 通知 |
| **S3: CI 失败通知** | push 含 lint 错误的代码 | ci.yml 失败 → 写 PR 评论 → 中枢发 Mail |
| **S4: 部署流程** | merge PR → push main | deploy.yml 自动跑 + 部署 + 健康检查 |
| **S5: Issue 指派** | 创建 Issue 并指派 | 中枢发 Mail 给被指派人 |
| **S6: 幂等验证** | 重复触发同一 delivery_id Webhook | 第二次返回 200 duplicate，不创建重复 Mail |
#### §17.6.4 P3 端到端验证结果（2026-06-08）
| 场景 | 结果 | 说明 |
|------|------|------|
| **S1: CI 触发** | ✅ | push test/p3-e2e-s1 → ci.yml 触发。首次因 act-runner 离线未触发，姜维修复后积压任务自动执行 |
| **S2: PR Review 流程** | ✅ | PR opened → 中枢发 Review 请求 Mail 给 simayi-challenger ✅。Review APPROVED → 中枢发 Mail 给 PR 作者 ✅（Gitea 1.23.4 支持此 webhook） |
| **S3: CI 失败通知** | ✅ | [CI] 评论 → 中枢发 Mail 给 PR作者 ✅ |
| **S4: 部署流程** | ⏭️ 跳过 | 依赖 CI 先跑通，未单独验证 |
| **S5: Issue 指派** | ✅ | Issue 指派 zhangfei-dev → 收到 Mail ✅ |
| **S6: 幂等验证** | ✅ | 同 delivery_id 第二次返回 `duplicate`，不创建重复 Mail ✅ |
##### 调研发现
**发现 1：Gitea Review API event 枚举值**
Gitea ReviewStateType 枚举值应为 `APPROVED`（不是 `APPROVE`）。使用错误的枚举值会创建 PENDING review，且 PENDING 不触发 webhook 通知。
- 正确：`{"event": "APPROVED"}`
- 错误：`{"event": "APPROVE"}` → 创建 PENDING review，webhook 不触发
已修正：TOOLS.md 模板 + code-review Skill 中的 event 值。
**发现 2：Gitea 1.23.4 支持 PullRequestReview webhook**
之前误判为"不支持"，实际原因同发现 1——错误的枚举值创建了 PENDING review，PENDING 不在 webhook switch 分支中导致报 "Unsupported review webhook type"。使用正确的 APPROVED event 后 webhook 正常触发。
daemon webhook handler 已正确覆盖：
- `pull_request_review` 事件 → `_handle_pull_request_review()`
- 只处理 APPROVED / REQUEST_CHANGES，跳过 COMMENTED 和 PENDING
- 通知对象：PR 作者
**发现 3：act-runner 进程管理**
act-runner 未纳入进程管理，崩溃后不会自恢复。姜维已修复：
- 纳入 PM2 托管（进程名：sanguo-act-runner，id=44）
- 启动命令：`pm2 start ~/bin/act_runner --name sanguo-act-runner --cwd ~/.config/act-runner/ -- daemon --config ~/.config/act-runner/config.yaml`
- 崩溃自动重启 ✅
- 开机自启：依赖 pm2 startup（需 sudo 配置 launchd）
#### §17.6.3 实验项目 CI 配置
从 moziplus-v2 的 ci.yml 精简，实验项目只需要基本验证：
```yaml
name: CI
on:
push:
branches: ['**', '!main']
pull_request:
types: [opened, synchronize]
jobs:
lint:
runs-on: macos-arm64
steps:
- uses: actions/checkout@v4
- run: echo "lint placeholder"
test:
runs-on: macos-arm64
needs: lint
steps:
- uses: actions/checkout@v4
- run: echo "test placeholder"
```
> **注意**：主项目 ci.yml/deploy.yml 的 runs-on 已从 `ubuntu-latest` 改为 `macos-arm64`，对齐 act-runner 实际 label。deploy.yml 的 placeholder 也已替换为实际 deploy.sh 命令。
---
### §17.7. 覆盖率渐进策略
#### §17.7.1 P1 阶段（启用后 2 周）— 只报告不阻断
**零改动**。当前 deploy.yml 的 ci job 已包含 `--cov=src --cov-report=term-missing`（push main 时自动跑）。
注意：ci.yml（非 main 分支）没有 coverage 配置——快速门控不需要覆盖率，这是有意为之。
收集基线数据后决定 P2 阈值。
#### §17.7.2 后续阶段（仅设计，暂不实施）
| 阶段 | 时间 | 策略 | 触发方式 |
|------|------|------|---------|
| P2 | 启用后 1 月 | 40% 阈值，低于警告不阻断 | ci.yml 加 coverage threshold check |
| P3 | 启用后 2 月+ | 60% 阈值，低于阻断 | ci.yml 加 `exit 1` |
---
### §17.8. 前端展示
#### §17.8.1 Gitea 自带管理界面
Gitea v1.23.4 自带完整的 CI 管理界面：
| 功能 | URL |
|------|-----|
| CI Runs 列表 | `http://192.168.2.154:3000/sanguo/{repo}/actions` |
| 单次 Run 日志 | `http://192.168.2.154:3000/sanguo/{repo}/actions/runs/{id}` |
| PR CI Status | PR 页面自动显示 CI 状态徽章 |
| Webhook 管理 | 仓库 Settings → Webhooks |
**不需要自己做 CI 前端。**
#### §17.8.2 moziplus v2 前端展示
工具链事件的 Mail 通知已在 moziplus v2 前端展示（Mail 列表页）。
如果未来要加，唯一值得做的是：在 moziplus 前端加一个「工具链状态」面板，聚合展示各仓库最近 CI 状态。这是 P4，不阻塞使用。
---
### §17.9. 实施路线
| 优先级 | 内容 | 耗时 | 前置 |
|--------|------|------|------|
| **P1** | L1 TOOLS.md（6 个 Agent） | 2h | 无 |
| **P1** | L2 Skill 升级（7 个） | 1d | 无 |
| **P2** | deploy.sh + deploy.yml | 2h | P1 Skill 升级（ci-cd-ops 定义了 deploy.sh 规范） |
| **P3** | sanguo/moziplus-v2 端到端验证 | 2h | P1 + P2 |
| **P4** | 前端工具链状态面板 | 按需 | 不阻塞 |
---
### §17.10. 前置条件 Checklist
工具链投入使用前必须确认：
| # | 条件 | 状态 | 谁确认 |
|---|------|------|--------|
| 1 | act-runner 已注册且 label = `macos-arm64` | ✅ PM2 托管（sanguo-act-runner, id=44），崩溃自动重启 | 姜维确认 |
| 2 | Gitea repository secrets 已配置（CI_TOKEN） | ✅ 姜维确认（sanguo/moziplus-v2 已配 CI_TOKEN） | 姜维 |
| 3 | Gitea 组织级 Webhook 已启用（Hook ID=28） | ✅ 已确认 | 已确认 |
| 4 | 各 Agent 的 GITEA_TOKEN 环境变量 | ✅ 已写入各 Agent TOOLS.md，姜维确认 token 记录存在 | 庞统+姜维 |
| 5 | main 分支保护规则（Review 才能 merge） | ✅ 姜维已配置（moziplus-v2 + sanguo_moziplus_v2，需1个approve） | 姜维 |
| 6 | 禁止在 daemon 运行时跑全量 E2E | ✅ 已警告司马懿 | 已确认 |
> 第 5 点很关键——如果 main 分支没有保护规则，开发者可以直接 push main 跳过 Review。
> act-runner 已于 2026-06-08 纳入 PM2 托管（姜维），崩溃自动重启 + pm2 save 已保存。开机自启依赖 pm2 startup（需 sudo 配置 launchd），P4 完成。
---
### §17.11. 评审记录（原 §14 评审）
#### v1.0 → v1.1 修订清单（仲达评审）
| 编号 | 类型 | 问题 | 修订内容 |
|------|------|------|----------|
| M1 | 必须修 | rsync --delete 会删 data/ | §17.5.1 --exclude 加 `data` + `node_modules` |
| M2 | 必须修 | runs-on 与实际环境不一致 | 实际 ci.yml/deploy.yml 已用 `macos-arm64`，CI 已跑通，属仲达误判。文档 §17.6.3 已明确说明 |
| S1 | 建议 | rollback commit 获取有竞态 | §17.5.1 rollback 改用 DEPLOY_OVERRIDE_COMMIT 显式传递，不依赖 git HEAD |
| S2 | 建议 | pip install 缺 lock file | 采纳但 P3，当前单一部署环境风险低 |
| S3 | 建议 | 缺前置条件 checklist | 新增 §17.10 前置条件 Checklist |
| S4 | 建议 | 验证场景补 S6 幂等 | §17.6.2 新增 S6 幂等验证场景 |
| — | 评审 | 庞统模板缺关闭 Issue curl | §17.3.3 C 节补关闭 Issue 模板 |
| — | 评审 | testing-workflow 加广播风暴禁止 | §17.4.2 testing-workflow 补充约束 |
| — | 评审 | ci-cd-ops 行数估算措辞 | 修正：重写后预计 ~120 行（原 114 行） |
| — | 评审 | 覆盖率 P1 前提需确认 | §17.7.1 明确指出 deploy.yml 已有 coverage，ci.yml 有意不加 |
---
### v3.0 → v3.1 变更（P3 端到端验证 + 调研结论）
| 编号 | 变更内容 |
|------|----------|
| §17.3.3 | Review API event 枚举值修正：APPROVE → APPROVED |
| §17.6.3 | 注意更新：runs-on 已改为 macos-arm64，placeholder 已替换 |
| §17.6.4 | 新增 P3 端到端验证结果（S1-S6 逐项） |
| §17.6.4 | 新增调研发现：Review API 枚举值、PullRequestReview webhook 支持、act-runner PM2 托管 |
| §17.10 | #1 状态更新：act-runner 已纳入 PM2 托管 |
### v3.1 → v3.2 变更（工具链修复 + Mail 投递 bug 修复）
| 编号 | 变更内容 |
|------|----------|
| §16.4 | Review handler 双格式兼容：HANDLERS 注册表同时注册 `pull_request_review` / `pull_request_approved` 等多种事件名；`_handle_pull_request_review` 兼容 repo webhook（review.state/body/user）和 org webhook（review.type/content/sender）两种 payload 格式 |
| §16.8 #10 | Gitea v1.23.4 review payload 调研结论（姜维 2026-06-08）：Gitea v1.23.4 review payload 只有 `type` + `content`，没有 `state`/`body`/`user`，这不是 org vs repo 差异而是 Gitea 设计。v1.24.0 格式不变。双格式兼容是防御性编码，保持现状 |
| §16.8 #11 | Spawner compact 检测窗口修复：窗口 300s→900s，尾部读取 50KB→1MB。实测长对话中 compact 记录被推出窗口导致漏检 |
| §16.8 #12 | inform 类型 Mail crash 误标 done bug 修复：`_mail_auto_complete` 增加 outcome 感知，inform 用白名单（completed/claimed/no_reply）控制 done 标记。spawner crash cooldown 300s→60s |
---
### 一、问题诊断
#### 1.1 E2E 真实场景测试暴露的三个断层
主公在 moziplus-v2 仓库创建了 Issue #32（添加 /api/stats 端点），指派张飞。链条在第一步就断了。
| 断层 | 现象 | 根因 |
|------|------|------|
| **Agent 不知道该做什么** | 张飞收到 Issue 指派 Mail，回复"已阅"就结束了 | Mail 模板（issue_assigned.md）5 行信息，无流程引导；spawn prompt 说"已阅即可" |
| **Agent 去错了仓库** | 张飞去读了 sanguo_moziplus_v2 平台代码，而不是空的实验仓库 moziplus-v2 | Mail 模板没有仓库 clone URL，张飞凭习惯去了开发目录 |
| **Agent 在 Control UI 提问** | 张飞遇到问题直接在 Control UI 问主公，没有去 Gitea Issue 评论 | 没有任何地方引导"有疑问去 Gitea Issue 评论" |
| **Agent 不知道怎么协作** | 张飞判断任务需要澄清，但不知道该怎么请求澄清 | 没有"做不了→在 Issue 评论 / Mail 庞统"的回退路径 |
| **跨 Agent @mention 无法通知** | 张飞在 Issue 评论 @赵云，赵云收不到通知 | issue_comment handler 只处理 [CI] 评论，@mention 被忽略 |
#### 1.2 根因：工具链在四层架构中的断层
| 层 | 应该有 | 实际有 | Gap |
|---|---|---|---|
| **L0 铁律** | — | — | 无需改动 |
| **L1 角色** | 工具链协作行为规范（所有 Agent 共享） | 无 | AGENTS.md 没有工具链相关内容 |
| **L2 引擎注入** | 事件上下文（仓库 clone URL、Gitea API、Issue/PR 详情） | Mail 模板只有 5 行摘要 | 缺仓库信息和流程引导 |
| **L3 被动参考** | 技术细节（分支命名、commit 规范、PR 创建方式） | git-workflow 等 Skill 已存在但没人触发 | Agent 不知道该加载哪个 Skill |
---
### 二、改造方案：四层归属
#### 2.1 分层原则
| 层 | 放什么 | 不放什么 | 理由 |
|---|---|---|---|
| **L0** | 不放 | — | 工具链不是安全底线 |
| **L1** | 协作行为规范：收到什么通知该做什么、遇到问题怎么办 | 技术细节（分支命名、commit 格式） | 行为规范是团队常识，每个 Agent 都要知道 |
| **L2** | 事件上下文：仓库 clone URL、Gitea API URL、Issue/PR 链接、动态信息 | 固定的协作流程 | 动态信息每次不同，由 Mail 模板 + spawn 时注入 |
| **L3** | 技术细节：git-workflow、code-review 等 Skill 全文 | — | 按需加载，Agent 知道"我要提 PR"后自己读 |
#### 2.2 各层具体内容
##### L1：AGENTS.md 加工具链协作行为段（所有 Agent 统一）
```markdown
## 工具链协作（Gitea）
收到 Gitea 事件通知（Issue 指派、Review 请求、CI 失败等）时，按以下流程操作：
### 基本流程
- **Issue 指派** → clone 仓库 → 开分支 → 编码 → 提 PR（参考 git-workflow Skill）
- **Review 请求** → 读 PR diff（Gitea API）→ 提交 Review（参考 code-review Skill）
- **Review 通过** → 等 merge
- **Review 驳回** → 看 review body → 修代码 → 重新 push
- **CI 失败** → 看错误摘要 → 修代码 → push（自动重触发 CI）
- **部署失败** → 查 deploy 日志 → 修复
### 协作规则
- **有疑问？** 在 Gitea Issue 下评论，不要在 Control UI 或 Mail 里问
- **需要别人帮忙？** 在 Issue 评论中 @mention 对应 Agent（如 @zhaoyun-data）
- **做不了？** 回复 Mail 说明原因和建议的接手人
- **获取完整上下文** → 用 Gitea API 拉取 Issue 详情和评论，不要只看 Mail 里的快照
### Gitea API 速查
> 其中 `{owner}/{repo}` 替换为实际仓库，如 `sanguo/sanguo_moziplus_v2`
- Issue 详情: GET /api/v1/repos/{owner}/{repo}/issues/{number}
- Issue 评论: GET /api/v1/repos/{owner}/{repo}/issues/{number}/comments
- PR diff: GET /api/v1/repos/{owner}/{repo}/pulls/{number}.diff
- 提交 Review: POST /api/v1/repos/{owner}/{repo}/pulls/{number}/reviews
```
**改动范围**：6 个 Agent 的 AGENTS.md 各加一段（内容统一）。
##### L2：Mail 模板精简 + 事件上下文注入
**原则**：模板只放摘要 + 链接 + 仓库信息，不写固定步骤（步骤在 L1）。
**issue_assigned.md** 改为：
```markdown
Issue 指派
Issue: {issue_url}
标题: {issue_title}
标签: {labels}
📋 获取完整上下文（先读再动手）：
- Issue 详情: GET {gitea_api}/repos/{repo}/issues/{issue_number}
- Issue 评论: GET {gitea_api}/repos/{repo}/issues/{issue_number}/comments
仓库: {repo_clone_url}
建议分支: feat/issue-{issue_number}-{brief}
```
**review_request.md** 改为：
```markdown
PR Review 请求
PR: {pr_url}
标题: {pr_title}
作者: {pr_author}
分支: {branch}
风险级别: {risk_level}
📋 获取完整上下文：
- PR diff: GET {gitea_api}/repos/{repo}/pulls/{pr_number}.diff
- PR 文件列表: GET {gitea_api}/repos/{repo}/pulls/{pr_number}/files
```
**review_result.md** 改为：
```markdown
Review {result}
PR: {pr_url}
标题: {pr_title}
审查者: {reviewer}
{review_body}
```
**ci_failure.md** 改为：
```markdown
CI 失败
Issue: {issue_url}
分支: {branch}
错误摘要:
{error_summary}
📋 CI 日志: {gitea_url}/{repo}/actions
修复后 push 会自动重触发 CI。
```
**deploy_failure.md** 改为：
```markdown
部署失败
仓库: {repo}
Commit: {commit_sha}
📋 排查步骤:
- CI 日志: {gitea_url}/{repo}/actions
- 服务器: pm2 logs {service_name}
```
**L2 代码改动**（`toolchain_routes.py`）：
1. 从 Webhook payload 的 `repository` 对象提取 `clone_url` 和 `html_url`
2. `render_template()` 传入新变量：`gitea_api`、`gitea_url`、`repo_clone_url`
3. 所有模板变量统一补齐
##### L3：Skill 按需加载（不改 Skill 本身）
git-workflow、code-review 等 Skill 保持不变。
L1 的协作行为段里会引用 Skill 名称（"参考 git-workflow Skill"），Agent 收到 Mail 后根据 L1 的引导自主加载对应 Skill。
**不改 Skill 路由机制**——靠 L1 的文案触发 Agent 的 Skill 路由器匹配。
---
### 三、新增功能：issue_comment @mention 通知
#### 3.1 设计
当前 `_handle_issue_comment` 只处理 `[CI]` 前缀评论。扩展为：
```
issue_comment 事件
├── 含 [CI] / CI 失败 → 原有 CI 失败通知逻辑
└── 含 @username → 解析 @mention → Mail 通知被 @的 Agent
```
#### 3.2 实现
**`toolchain_routes.py` 新增 `_handle_issue_comment_mention()`**：
```python
AGENT_IDS = {
"zhangfei-dev", "guanyu-dev", "zhaoyun-data",
"jiangwei-infra", "simayi-challenger", "pangtong-fujunshi",
}
# 前缀映射：@张飞 → zhangfei-dev
# 中文名映射：Agent 在 Gitea Issue 评论中可能用中文名 @mention
# 英文短名映射：Agent 可能用不带 -dev/-infra 后缀的短名
AGENT_ALIAS = {
"张飞": "zhangfei-dev",
"关羽": "guanyu-dev",
"赵云": "zhaoyun-data",
"姜维": "jiangwei-infra",
"司马懿": "simayi-challenger",
"庞统": "pangtong-fujunshi",
"pangtong": "pangtong-fujunshi",
"simayi": "simayi-challenger",
"zhangfei": "zhangfei-dev",
"guanyu": "guanyu-dev",
"zhaoyun": "zhaoyun-data",
"jiangwei": "jiangwei-infra",
}
def extract_mentions(body: str, sender: str) -> list[str]:
"""从评论 body 中提取 @mention 的 Agent ID"""
candidates = re.findall(r"@([a-zA-Z\u4e00-\u9fa5][a-zA-Z0-9\u4e00-\u9fff-]*)", body)
result = set()
for c in candidates:
# 精确匹配
if c in AGENT_IDS:
result.add(c)
# 前缀/别名匹配
elif c in AGENT_ALIAS:
result.add(AGENT_ALIAS[c])
else:
# 前缀模糊匹配：@zhangfei → zhangfei-dev
for aid in AGENT_IDS:
if aid.startswith(c):
result.add(aid)
break
# 过滤掉评论者自己
result.discard(sender)
return list(result)
```
**新增 mention 通知模板** `templates/toolchain/mention.md`：
```markdown
你在 Issue 中被 @mention
Issue: {issue_url}
评论者: {commenter}
评论内容:
{comment_body}
📋 获取完整上下文：
- Issue 详情: GET {gitea_api}/repos/{repo}/issues/{issue_number}
- Issue 评论: GET {gitea_api}/repos/{repo}/issues/{issue_number}/comments
```
**改动 `_handle_issue_comment`**：
```python
async def _handle_issue_comment(payload):
comment = payload.get("comment", {})
body = comment.get("body", "")
sender = comment.get("user", {}).get("login", "")
repo = _repo_fullname(payload)
issue = payload.get("issue", {})
# 原有 CI 失败逻辑（不变）
if "[CI]" in body or "CI 失败" in body:
# ... 原有逻辑 ...
# 新增：@mention 通知
mentions = extract_mentions(body, sender)
if mentions:
issue_number = issue.get("number", 0)
issue_title = issue.get("title", "")
text = render_template("mention", {
"repo": repo,
"issue_number": str(issue_number),
"issue_url": issue.get("html_url", ""),
"commenter": sender,
"comment_body": body[:500],
"gitea_api": "http://192.168.2.154:3000/api/v1",
})
title = f"@mention: {issue_title} ({repo}#{issue_number})"
for agent_id in mentions:
_send_mail(agent_id, title, text)
```
#### 3.3 去重
- 同一条评论 @多人：每人一封 Mail（不同 to，内容相同）
- 同一事件 org webhook + repo webhook 双触发：现有 delivery UUID 去重机制覆盖
- 同一人被 @多次：`extract_mentions` 返回 set，自动去重
---
### 四、Mail Spawn Prompt 改造
#### 4.1 问题
当前工具链 Mail 走 Mail 通道，spawn prompt 是：
```
你收到一封飞鸽传书(纯通知)。
发件者: system
主题: Issue 指派: xxx
内容: [工具链模板]
已阅即可。
```
"已阅即可"直接让 Agent 不做事。
#### 4.2 方案
**不改 MAIL_INFORM_TEMPLATE / MAIL_REQUEST_TEMPLATE 本身**（那是 Mail 系统通用的）。
改为：**工具链 Mail 使用 `type=request`（而不是默认的 inform）**。
在 `_send_mail()` 中，工具链事件创建的 Mail 默认 `performative=request`，这样 Agent 收到时走 `MAIL_REQUEST_TEMPLATE`，知道需要处理。
具体改动在 `_send_mail()` 函数或其调用处：工具链路由调用 `_send_mail` 时传入 `performative="request"`。
**⚠️ 验证要点**：改为 request 后，Agent spawn prompt 变为 "请处理以下请求"，需确认：
1. Agent 不再把工具链 Mail 当纯通知忽略
2. Agent 能正确处理「已阅型」工具链事件（如 CI 失败通知——不需要回复，但需要知道）
3. 对已关闭 PR/Issue 的延迟通知，Agent 不会尝试去处理
验证方法：部署后发一条 Issue 指派 Mail，观察 Agent 行为是否符合预期。
---
### 五、完整改动清单
| # | 改什么 | 改动内容 | 层 | 风险 |
|---|--------|---------|---|------|
| 1 | 6 个 Agent 的 `AGENTS.md` | 加"工具链协作"段（内容统一） | L1 | 低（纯追加） |
| 2 | `templates/toolchain/issue_assigned.md` | 精简 + 加仓库上下文 + Gitea API 引导 | L2 | 低 |
| 3 | `templates/toolchain/review_request.md` | 精简 + 加 Gitea API 引导 | L2 | 低 |
| 4 | `templates/toolchain/review_result.md` | 精简 | L2 | 低 |
| 5 | `templates/toolchain/ci_failure.md` | 精简 + 加 CI 日志链接 | L2 | 低 |
| 6 | `templates/toolchain/deploy_failure.md` | 精简 + 加排查步骤 | L2 | 低 |
| 7 | **新建** `templates/toolchain/mention.md` | @mention 通知模板 | L2 | 低 |
| 8 | `src/api/toolchain_routes.py` | 提取 clone_url/html_url 传入模板；issue_comment 增加 @mention 解析；工具链 Mail 改为 request 类型 | L2 | 中 |
| 9 | 不改 | git-workflow 等 Skill 保持不变 | L3 | — |
| 10 | 不改 | daemon 核心逻辑、BootstrapBuilder、Skill 路由 | — | — |
---
### 六、验证方案
#### 6.1 单元验证
| 验证点 | 方法 |
|--------|------|
| `extract_mentions()` 提取 `@zhangfei-dev` | unit test |
| `extract_mentions()` 别名匹配 `@张飞` → zhangfei-dev | unit test |
| `extract_mentions()` 前缀匹配 `@zhangfei` → zhangfei-dev | unit test |
| `extract_mentions()` 过滤自己 | unit test |
| 模板渲染新变量不报错 | unit test |
#### 6.2 真实场景 E2E 验证
重复 Issue #32 的场景：
1. 创建 Issue 指派张飞
2. **验证**：张飞收到的 Mail 含 clone URL + Gitea API 引导
3. **验证**：张飞 spawn 后知道该做什么（L1 AGENTS.md 有流程引导）
4. **验证**：张飞有疑问时去 Gitea Issue 评论（而不是 Control UI）
5. 在 Issue 评论 @赵云
6. **验证**：赵云收到 @mention Mail
---
### 七、不做的事（标记为后续）
| 标记 | 描述 | 原因 |
|------|------|------|
| 后续-1 | Agent 离开工具链讨论后，是否有意识回到工具链 | 需要更多真实场景观察 |
| 后续-2 | 工具链使用标准在所有 Agent 间的一致性验证 | L1 统一段落是第一步，需要 E2E 验证 |
| 后续-3 | Mail 通道接入 BootstrapBuilder L2 注入 | 改动大，当前方案（L1 统一段落 + 模板引导）够用 |
| 后续-4 | Skill 路由器自动触发（引擎注入） | 改动 daemon 核心，当前靠 L1 文案触发 |
---
### 八、变更记录
| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-06-09 | v1.0 | 初版：E2E 真实场景暴露问题 → 四层改造方案 + @mention 通知 + Mail type 改造 |
Reference in New Issue View Git Blame Copy Permalink