auto-sync: 2026-06-09 11:57:58

.gitea/workflows/ci.yml

@@ -23,7 +23,7 @@ on:
 jobs:
   # ── Job 1: Lint ──────────────────────────────────────
   lint:
-    runs-on: ubuntu-latest
+    runs-on: macos-arm64
     steps:
       - uses: actions/checkout@v4
 
@@ -38,7 +38,7 @@ jobs:
 
   # ── Job 2: Test ──────────────────────────────────────
   test:
-    runs-on: ubuntu-latest
+    runs-on: macos-arm64
     needs: lint
     steps:
       - uses: actions/checkout@v4
@@ -55,7 +55,7 @@ jobs:
   # ── Job 3: CI 失败通知 ───────────────────────────────
   # v1.23 不支持 failure()，用 always() + shell 检查 commit status 替代
   notify-on-failure:
-    runs-on: ubuntu-latest
+    runs-on: macos-arm64
     needs: [lint, test]
     if: always()
     steps:

.gitea/workflows/deploy.yml

@@ -6,7 +6,7 @@
 # Gitea v1.23.4 限制注意：
 #   - 不支持 failure() 表达式
 #   - 不支持 concurrency / permissions
-#   - 部署脚本占位，等姜维确认 act-runner 环境后再补具体命令
+#   - 部署脚本 scripts/deploy.sh，支持 --version/--rollback/--health-check
 
 name: Deploy
 
@@ -17,7 +17,7 @@ on:
 jobs:
   # ── Job 1: CI（main 分支跑完整测试）─────────────────
   ci:
-    runs-on: ubuntu-latest
+    runs-on: macos-arm64
     steps:
       - uses: actions/checkout@v4
 
@@ -36,42 +36,24 @@ jobs:
 
   # ── Job 2: 部署 ─────────────────────────────────────
   deploy:
-    runs-on: ubuntu-latest
+    runs-on: macos-arm64
     needs: ci
     steps:
       - uses: actions/checkout@v4
 
       - name: Record current version
         run: |
-          echo "Deploying commit: ${{ gitea.sha }}"
-          echo "Branch: ${{ gitea.ref }}"
-          echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
-          # TODO: bash scripts/deploy.sh --version
-          #       等姜维确认 act-runner 环境后再补
+          bash scripts/deploy.sh --version || echo "No deploy history yet"
 
       - name: Deploy
         run: |
-          echo "=== Deploy step (placeholder) ==="
-          echo "Source: ${{ gitea.workspace }}"
-          # TODO: 实际部署脚本
-          # bash scripts/deploy.sh --source="$GITHUB_WORKSPACE" --target="$HOME/.sanguo_projects/sanguo_moziplus_v2" --health-check
-          echo "Deploy placeholder completed."
+          bash scripts/deploy.sh --source="$GITHUB_WORKSPACE" --target="$HOME/.sanguo_projects/sanguo_moziplus_v2" --health-check
 
-      - name: Health check
-        run: |
-          echo "=== Health check ==="
-          # TODO: 等服务启动后做健康检查
-          # curl -sf http://localhost:8083/api/health || exit 1
-          echo "Health check placeholder passed."
-
-      # ── 失败时回滚 ────────────────────────────────
-      # v1.23 不支持 if: failure()
-      # 回滚逻辑改由 notify-on-failure job 检测 commit status 后通知人工介入
-      # 后续可升级到 v1.24+ 后改用 failure() 表达式
+      # 回滚由 notify-deploy-failure job 检测失败后通知人工介入
 
   # ── Job 3: 部署失败通知 ──────────────────────────────
   notify-deploy-failure:
-    runs-on: ubuntu-latest
+    runs-on: macos-arm64
     needs: [ci, deploy]
     if: always()
     steps:

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

@@ -1,6 +1,6 @@
 # 三国团队工具链与开发流程设计
 
-> **状态**: v2.1 — 事件中枢详细设计（§16 新增）
+> **状态**: v3.1 — P3 端到端验证通过 + 调研结论写入 + Review API 枚举值修正
 > **作者**: 庞统（副军师）🐦
 > **评审**: 司马懿（仲达）🗡️
 > **日期**: 2026-06-06
@@ -1590,7 +1590,7 @@ daemon 内部 ───────┘    │ 5. 创建 Mail    │
 | 只处理白名单内的事件类型 | 未知的忽略 + 日志 |
 | issue_comment 需判断来源 | 只处理 CI workflow 写的评论（按特定前缀匹配：`❌ **CI 失败**` 或统一后的 `[CI]` 前缀） |
 | PR 作者/审查者必须是已知 Agent | 未知的忽略 + 日志 |
-| 幂等：同一事件不重复创建 Mail | 按 `{x_gitea_event}-{x_gitea_delivery}` 去重（delivery ID 来自 `X-Gitea-Delivery` header） |
+| 幂等：同一事件不重复创建 Mail | 双重去重：① delivery UUID（`{event}-{delivery}`）标准幂等；② review 事件 payload 内容去重（`{event}:{pr_num}:{sender}:{sha256(body_or_content)[:16]}`），防御同一 review 被不同来源重复提交（2026-06-09 新增） |
 
 ---
 
@@ -1671,8 +1671,11 @@ def calc_risk_level(changed_files: list[str]) -> str:
 ### 4.1 模块结构
 
 ```
+src/config/
+└── agents.py              # Agent ID 统一注册表
+
 src/api/
-├── toolchain_routes.py    # 事件中枢路由（~150行）
+├── toolchain_routes.py    # 事件中枢路由（~250行）
 ├── mail_routes.py         # 现有 Mail API
 └── ...
 
@@ -1694,16 +1697,19 @@ templates/toolchain/
 ```python
 # src/api/toolchain_routes.py
 
-from fastapi import APIRouter, Request, Header, HTTPException
+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 handle_gitea_webhook(
+async def gitea_webhook(
     request: Request,
     x_gitea_event: str = Header(...),
     x_gitea_signature: str = Header(None),
@@ -1713,32 +1719,32 @@ async def handle_gitea_webhook(
     
     body = await request.body()
     
-    # 1. 签名验证（可选，假设 Gitea 使用 HMAC-SHA256，需根据 Gitea 版本确认）
+    # 1. 签名验证（HMAC-SHA256，Gitea 1.23.4 已确认）
     if GITEA_WEBHOOK_SECRET:
-        expected = hmac.new(GITEA_WEBHOOK_SECRET.encode(), body, sha256).hexdigest()
+        expected = hmac.new(GITEA_WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
         if not hmac.compare_digest(expected, (x_gitea_signature or "")):
-            raise HTTPException(403, "Invalid signature")
+            return Response(status_code=403, content="signature verification failed")
     
     event = json.loads(body)
     
-    # 2. 幂等检查（delivery ID = X-Gitea-Delivery header，Gitea 全局唯一）
-    event_key = f"{x_gitea_event}-{x_gitea_delivery}"
-    if is_duplicate(event_key):
-        return {"status": "duplicate"}
+    # 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:
-        logger.info("Ignoring unhandled event: %s", x_gitea_event)
-        return {"status": "ignored"}
+        return Response(status_code=200, content="ignored")
     
     # 4. 处理事件 → 创建 Mail
     try:
         result = await handler(engine, event)
-        return {"status": "ok", "mail_id": result}
+        return Response(status_code=200)
     except Exception as e:
         logger.exception("Failed to handle %s event", x_gitea_event)
-        raise HTTPException(500, str(e))
+        return Response(status_code=500, content=str(e))
 ```
 
 ### 4.3 事件处理器
@@ -1923,6 +1929,7 @@ class TemplateEngine:
 | 未知事件类型 | 忽略 + 日志 info | 200 |
 | 幂等检测到重复 | 忽略 + 日志 info | 200 |
 | 未知 Agent（不在映射表） | 忽略 + 日志 warning | 200 |
+| PR 文件获取失败（3次重试后） | 降级为 risk_level=standard + 错误信息写入 Mail 正文 | 200（handler 内部处理） |
 | 模板填充失败 | 日志 error | 500（触发 Gitea 重试） |
 | Mail 创建失败 | 日志 error | 500（触发 Gitea 重试） |
 
@@ -1992,12 +1999,17 @@ CI workflow 已有 `notify-on-failure` job（ci.yml），当前格式：
 | # | 项 | 状态 | 结论 |
 |---|------|------|------|
 | 1 | Agent Gitea 用户名映射 | ✅ 姜维已确认 | 一致（用户名就是完整 Agent ID），直用，不需要映射表 |
-| 2 | Gitea Webhook secret | ✅ 姜维已确认 | 已配置，secret 有值，当前 active: false（实现后启用）。签名算法 HMAC-SHA256 |
+| 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 | ✅ 已确认 | payload 只有 changed_files 数量，文件列表需额外调用 `GET /repos/{owner}/{repo}/pulls/{number}/files` |
+| 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 |
 
 ---
 
@@ -2047,3 +2059,709 @@ CI workflow 已有 `notify-on-failure` job（ci.yml），当前格式：
 | 编号 | 变更内容 |
 |------|---------|
 | §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 |

docs/design/18-toolchain-e2e-test.md

@@ -0,0 +1,121 @@
+# §18. 工具链端到端验证测试
+
+> 日期：2026-06-09
+> 状态：已完成 ✅
+> 目标：用真实 Webhook 触发验证整条 Mail 通知链路
+
+## 前置确认
+
+- Gitea 用户名 ↔ Agent ID 映射：完全一致（admin, guanyu-dev, jiangwei-infra, pangtong-fujunshi, simayi-challenger, zhangfei-dev, zhaoyun-data）
+- Gitea 组织级 Webhook（Hook ID=28）：姜维确认最近 5 条投递全部 is_succeed=1
+- Daemon 在线：sanguo-moziplus-v2 运行中
+- 测试仓库：sanguo/moziplus-v2
+
+## 命名规范
+
+- Issue 标题：`[E2E-TEST] xxx`
+- PR 标题：`[E2E-TEST] xxx`
+- 分支名：`test/e2e-<timestamp>`
+
+## 验证步骤
+
+| 步骤 | 操作 | 触发事件 | 预期 Mail 通知 | 验证点 |
+|------|------|----------|---------------|--------|
+| 1 | 创建 Issue `[E2E-TEST] Issue指派测试`，assignee=zhangfei-dev | issues (assigned) | zhangfei-dev 收到 "Issue 指派" Mail | Mail to/模板正确 |
+| 2 | 开分支 `test/e2e-<ts>`，创建 PR `[E2E-TEST] Review请求测试` | pull_request (opened) | simayi-challenger 收到 "Review 请求" Mail | Mail to/风险级别/文件列表 |
+| 3 | PR Review APPROVED | pull_request_review (approved) | PR 作者(pangtong-fujunshi) 收到 "Review 通过 ✓" Mail | result=通过 ✓ |
+| 4 | PR Review REQUEST_CHANGES | pull_request_review (rejected) | PR 作者收到 "Review 驳回 ✗" Mail | result=驳回 ✗ |
+| 5 | Issue 上发评论 `[CI] CI 失败 — 分支: test/e2e-xxx, 错误: build timeout` | issue_comment | Issue 作者收到 "CI 失败" Mail | 模板含分支/错误摘要 |
+| 6 | 创建标题含"部署失败"的 Issue（无指派） | issues (opened) | jiangwei-infra + pangtong-fujunshi 各收到 "部署失败" Mail | 双收件人 |
+| 7 | 关闭步骤 1 的 Issue，再发 CI 失败评论 | issue_comment (closed issue) | 不产生 Mail（负面测试） | handler 跳过 closed |
+| 8 | 重发步骤 1 Webhook（相同 delivery ID） | 重复事件 | 不产生新 Mail（幂等测试） | 返回 duplicate |
+
+## 签名校验
+
+已测试（GITEA_WEBHOOK_SECRET 已配置且生效）：
+- ✅ 正确签名：请求正常处理
+- ✅ 无签名：返回 403 `signature verification failed`
+
+## Review 意见来源
+
+- 姜维（基础设施确认 + 边界验证建议）
+- 司马懿（遗漏点补充 + 命名规范 + 风险防范）
+
+---
+
+## 执行记录
+
+> 2026-06-09 00:40~00:50 CST
+
+### 步骤 1：Issue 指派 ✅
+- 操作：创建 Issue #22 `[E2E-TEST] Issue指派测试`，assignee=zhangfei-dev
+- Mail：`mail-1780936736480`，from=system, to=zhangfei-dev, title=`Issue 指派: [E2E-TEST] Issue指派测试`
+- 模板渲染正确（含 Issue 链接、标签、描述、建议分支名）
+
+### 步骤 2：PR Review 请求 ✅
+- 操作：创建分支 `test/e2e-1780936838`，创建 PR #23
+- Mail：`mail-1780936851715`，from=system, to=simayi-challenger
+- 模板含 PR 链接、标题、作者(pangtong-fujunshi)、分支、风险级别(standard)
+- 附带：CI 失败通知 `mail-1780936876572`（CI 自动触发，符合预期）
+
+### 步骤 3：Review APPROVED ✅
+- 操作：用 simayi-challenger token 提交 APPROVED review
+- Mail：`mail-1780936968411`，from=system, to=pangtong-fujunshi, title=`Review 通过 ✓`
+- 描述含审查者(simayi-challenger)、review body
+- ⚠️ 收到 2 封重复 Mail（org webhook + repo webhook 双触发）
+
+### 步骤 4：Review REQUEST_CHANGES ✅
+- 操作：用 simayi-challenger token 提交 REQUEST_CHANGES review
+- Mail：`mail-1780936972207`，from=system, to=pangtong-fujunshi, title=`Review 驳回 ✗`
+- ⚠️ 同上，收到 2 封重复 Mail
+
+### 步骤 5：CI 失败评论 ✅
+- 操作：在 Issue #22 发评论 `[CI] CI 失败 — 分支: test/e2e-1780936838, 错误: build timeout`
+- Mail：`mail-1780936994513`，from=system, to=pangtong-fujunshi, title=`CI 失败: sanguo/moziplus-v2#22`
+- 模板含分支提取和错误摘要
+
+### 步骤 6：部署失败 Issue ✅
+- 操作：创建 Issue #24 `[E2E-TEST] 部署失败: test deploy`（无指派）
+- Mail：`mail-1780936999660` to=jiangwei-infra, `mail-1780936999684` to=pangtong-fujunshi
+- 双收件人验证通过 ✅
+
+### 步骤 7：已关闭 Issue 负面测试 ✅
+- 操作：关闭 Issue #22 后发 `[CI] CI 失败 — 应被过滤`
+- 结果：未产生新 Mail ✅（只有步骤 5 的 1 封 CI Mail，步骤 7 的评论被正确过滤）
+
+### 步骤 8：幂等测试 ✅
+- 操作：构造带正确 HMAC-SHA256 签名的 Webhook，用同一 delivery ID `test-idempotency-002` 发两次
+- 第一次：返回 `ok`，产生 Mail ✅
+- 第二次：返回 `duplicate`，无新 Mail ✅
+- 额外验证：不带签名的请求返回 403 `signature verification failed`（签名校验正常工作）
+
+---
+
+## 汇总
+
+| 步骤 | 状态 | 备注 |
+|------|------|------|
+| 1. Issue 指派 | ✅ 通过 | Mail to/模板正确 |
+| 2. PR Review 请求 | ✅ 通过 | Mail to/风险级别/文件列表正确 |
+| 3. Review APPROVED | ✅ 通过 | E2E 测试中产生 2 封 Mail（根因已查明，非平台问题） |
+| 4. Review REQUEST_CHANGES | ✅ 通过 | 同上 |
+| 5. CI 失败评论 | ✅ 通过 | 分支提取正确 |
+| 6. 部署失败 Issue | ✅ 通过 | 双收件人验证通过 |
+| 7. 已关闭 Issue 过滤 | ✅ 通过 | 负面测试通过，无新 Mail |
+| 8. 幂等测试 | ✅ 通过 | 第二次返回 duplicate，无新 Mail；签名校验正常拦截无签名请求 |
+
+## 发现的问题
+
+### Review 事件双 Mail（已修复）
+- **现象**：E2E 测试步骤 3/4 中 Review 事件产生 2 封 Mail
+- **根因**（姜维深入调查确认）：E2E 测试中庞统手动用 simayi token 提交了 Review，同时 simayi agent 收到 Review 请求 Mail 后也自主提交了 Review。是两次独立的 API 调用，**不是 Gitea bug 或平台配置问题**
+  - 姜维控制实验：一次 review API 调用只产生 1 个 hook_task
+  - Gitea 路由日志确认两次 POST 间隔 7 秒，payload 有差异（review_comments、updated_at 不同）
+  - 之前的错误分析（"Gitea webhookNotifier + actionsNotifier 双投递"）已被推翻：actionsNotifier 走 handleWorkflows() 不创建 hook_task
+- **修复**：payload 内容去重作为防御性编程保留（`_is_duplicate` 新增内容去重 key = event + pr_num + sender + sha256(body_or_content)），司马懿 APPROVED
+- **验证**：PR #27 实测只产生 1 封 Mail ✅
+
+### 根因分析教训
+- 姜维第一次分析给出了错误根因（Gitea 双 notifier），第二次深入调查后自我纠正
+- 庞统把姜维的第一次结论当事实汇报给主公，没有标注"这是姜维的调查结论，尚未独立验证"
+- **改进**：SOUL.md 新增规则——推测 vs 事实显式标注、引用他人结论时标注来源、结论被推翻时及时更正

docs/design/19-toolchain-context-layers.md

@@ -0,0 +1,372 @@
+# #19 工具链事件中枢 — 上下文四层改造方案
+
+> 版本: v1.0
+> 日期: 2026-06-09
+> 作者: 庞统（副军师）
+> 状态: 待主公确认
+> 前置: #13 工具链与开发流程 §16, #05 上下文四层架构
+> 来源: E2E 真实场景测试暴露的三个断层
+
+---
+
+## 一、问题诊断
+
+### 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 速查
+- 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_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"`。
+
+---
+
+## 五、完整改动清单
+
+| # | 改什么 | 改动内容 | 层 | 风险 |
+|---|--------|---------|---|------|
+| 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 改造 |

docs/test-guide.md

@@ -11,9 +11,10 @@
 | 场景 | 命令 | 耗时 | 说明 |
 |------|------|------|------|
 | **改了某个模块** | `pytest tests/unit/test_spawner.py` | <5s | 只跑改动的模块对应的单元测试 |
-| **改了 API 层** | `pytest tests/integration/` | ~1min | 跑全部集成测试 |
-| **提交前快速验证** | `pytest -m "not e2e"` | ~2min | 不跑 E2E，验证不破坏现有功能 |
-| **部署前全量验证** | `RUN_INTEGRATION=1 pytest` | ~60min | 含 E2E，真实 Agent |
+| **改了 API 层** | `RUN_INTEGRATION=1 pytest tests/integration/` | ~1min | 跑全部集成测试 |
+| **提交前快速验证** | `pytest` | ~2min | 默认排除 integration 和 e2e |
+| **含集成测试** | `RUN_INTEGRATION=1 pytest` | ~5min | 包含 integration 测试 |
+| **部署前全量验证** | `RUN_INTEGRATION=1 pytest` | ~60min | 含 e2e，真实 Agent |
 | **只跑 E2E 场景** | `RUN_INTEGRATION=1 pytest tests/e2e/test_e2e_scenarios.py` | ~30min | 串行，一个跑完再下一个 |
 | **只跑 E2E 压力** | `RUN_INTEGRATION=1 pytest tests/e2e/test_e2e_stress.py` | ~10min | 并发测试 |
 
@@ -101,7 +102,7 @@ E2E（慢，真实 Agent）    → 验证完整链路，需要 RUN_INTEGRATION=1
 ## 关键规则
 
 1. **只有 E2E 会 spawn 真实 Agent**，单元和集成不会
-2. **不带 `RUN_INTEGRATION=1` 跑 `pytest` 是安全的**，E2E 全部 skip
+2. **直接跑 `pytest` 是安全的**，integration 和 e2e 全部被排除（需 `RUN_INTEGRATION=1` 才跑）
 3. **E2E 场景测试串行**，一个完成再下一个，失败要分析根因再继续
 4. **E2E 压力测试并行**，场景测试全通过后再跑
 5. **测试数据用 `e2e-` 前缀**，atexit 兜底清理，手动清理见上方

ecosystem.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  apps: [{
+    name: "sanguo-moziplus-v2",
+    script: "/usr/bin/python3",
+    args: "-m uvicorn src.main:app --host 0.0.0.0 --port 8083",
+    cwd: "/Users/chufeng/.sanguo_projects/sanguo_moziplus_v2",
+    env: {
+      GITEA_WEBHOOK_SECRET: "22760993dff898a190731da43aa8d964",
+      GITEA_TOKEN: "a6d596b826f4bfeaf983ef4d25ac25dab95bbc4e"
+    }
+  }]
+}

pyproject.toml

@@ -8,8 +8,10 @@ requires-python = ">=3.9"
 asyncio_mode = "auto"
 testpaths = ["tests"]
 markers = [
-    "integration: real agent tests (requires RUN_INTEGRATION=1)",
+    "integration: integration tests (requires RUN_INTEGRATION=1)",
+    "e2e: end-to-end tests with real daemon + Agent (requires RUN_INTEGRATION=1)",
 ]
+# Default deselection of integration/e2e handled in conftest.py pytest_collection_modifyitems
 
 [tool.pyright]
 venvPath = "."

scripts/deploy.sh

@@ -18,6 +18,8 @@ usage() {
   echo "  --source=DIR    源码目录 (default: 项目开发目录)"
   echo "  --target=DIR    安装目标目录 (default: ~/.sanguo_projects/sanguo_moziplus_v2)"
   echo "  --skip-build    跳过前端构建"
+  echo "  --version       显示当前部署版本"
+  echo "  --rollback      回滚到上一个部署版本"
   echo "  -h, --help      显示帮助"
   exit 0
 }
@@ -27,10 +29,59 @@ for arg in "$@"; do
     --source=*) SOURCE_DIR="${arg#*=}" ;;
     --target=*) TARGET_DIR="${arg#*=}" ;;
     --skip-build) SKIP_BUILD=true ;;
+    --version) ACTION=version ;;
+    --rollback) ACTION=rollback ;;
+    --health-check) ;; # 保留兼容，无额外操作
     -h|--help) usage ;;
   esac
 done
 
+ACTION="${ACTION:-deploy}"
+
+# ── 部署历史文件 ──
+HISTORY_FILE="$TARGET_DIR/data/deploy-history.jsonl"
+
+# ── version 分支 ──
+if [ "$ACTION" = "version" ]; then
+  if [ -f "$HISTORY_FILE" ]; then
+    LAST_COMMIT=$(tail -1 "$HISTORY_FILE" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("commit","unknown"))' 2>/dev/null || echo "unknown")
+    echo "$LAST_COMMIT"
+  else
+    echo "No deployment history found."
+  fi
+  exit 0
+fi
+
+# ── rollback 分支 ──
+if [ "$ACTION" = "rollback" ]; then
+  if [ ! -f "$HISTORY_FILE" ]; then
+    echo "❌ No deployment history, cannot rollback."
+    exit 1
+  fi
+  LINE_COUNT=$(wc -l < "$HISTORY_FILE")
+  if [ "$LINE_COUNT" -lt 2 ]; then
+    echo "❌ Not enough history for rollback (need at least 2 entries)."
+    exit 1
+  fi
+  ROLLBACK_COMMIT=$(tail -2 "$HISTORY_FILE" | head -1 | python3 -c 'import sys,json; print(json.load(sys.stdin).get("commit",""))' 2>/dev/null || echo "")
+  if [ -z "$ROLLBACK_COMMIT" ]; then
+    echo "❌ Could not parse previous commit from history."
+    exit 1
+  fi
+  echo "🔄 Rolling back to commit: $ROLLBACK_COMMIT"
+  # 保存当前分支/commit 以便恢复
+  CURRENT_REF=$(git -C "$SOURCE_DIR" rev-parse HEAD 2>/dev/null || echo "")
+  # checkout 到目标 commit
+  git -C "$SOURCE_DIR" checkout "$ROLLBACK_COMMIT" 2>/dev/null
+  # 使用 DEPLOY_OVERRIDE_COMMIT 显式传 commit hash
+  DEPLOY_OVERRIDE_COMMIT="$ROLLBACK_COMMIT" bash "$0" --source="$SOURCE_DIR" --target="$TARGET_DIR" --skip-build
+  # 恢复到原来的 commit
+  if [ -n "$CURRENT_REF" ]; then
+    git -C "$SOURCE_DIR" checkout "$CURRENT_REF" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
 echo "🚀 Deploying moziplus v2"
 echo "   Source: $SOURCE_DIR"
 echo "   Target: $TARGET_DIR"
@@ -168,6 +219,25 @@ else
   echo "   Check: pm2 logs $PM2_NAME"
 fi
 
+# ── 记录部署历史 ──
+mkdir -p "$(dirname "$HISTORY_FILE")"
+if [ -n "${DEPLOY_OVERRIDE_COMMIT:-}" ]; then
+  DEPLOYED_COMMIT="$DEPLOY_OVERRIDE_COMMIT"
+else
+  DEPLOYED_COMMIT=$(git -C "$SOURCE_DIR" rev-parse --short HEAD 2>/dev/null || echo "unknown")
+fi
+DEPLOY_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+DEPLOY_SOURCE="${SOURCE_DIR}"
+HISTORY_ENTRY=$(printf '%s' '{"timestamp":"'$DEPLOY_TIMESTAMP'","commit":"'$DEPLOYED_COMMIT'","source":"'$DEPLOY_SOURCE'"}')
+echo "$HISTORY_ENTRY" >> "$HISTORY_FILE"
+# 保留最近 10 条
+if [ -f "$HISTORY_FILE" ]; then
+  TMPFILE=$(mktemp)
+  tail -10 "$HISTORY_FILE" > "$TMPFILE"
+  mv "$TMPFILE" "$HISTORY_FILE"
+fi
+echo "   Deploy history recorded ($DEPLOYED_COMMIT) ✅"
+
 # ── 完成 ──
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

src/api/toolchain_routes.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import hashlib
 import hmac
 import json
@@ -25,6 +26,7 @@ from fastapi import APIRouter, Header, Request, Response
 from src.blackboard.db import init_db
 from src.blackboard.models import Task
 from src.blackboard.operations import Blackboard
+from src.config.agents import AGENT_IDS
 from src.daemon.toolchain_templates import render_template
 from src.utils import get_data_root
 
@@ -41,19 +43,45 @@ router = APIRouter(tags=["toolchain"])
 _delivery_cache: Set[str] = set()
 _delivery_timestamps: List[Tuple[float, str]] = []
 _TTL_SECONDS = 7 * 24 * 3600
+_idempotency_lock = asyncio.Lock()
 
 
-def _is_duplicate(event: str, delivery: str) -> bool:
-    """检查 Webhook 是否重复投递，自动清理过期条目。"""
+def _is_duplicate(event: str, delivery: str, payload: Optional[Dict[str, Any]] = None) -> bool:
+    """检查 Webhook 是否重复投递，自动清理过期条目。
+
+    双重去重策略：
+    1. delivery UUID 去重（标准幂等）
+    2. payload 内容去重（应对 Gitea v1.23.4 的 webhookNotifier + actionsNotifier
+       对同一 review 生成不同 UUID 的双投递问题）
+    """
     now = time.time()
     # 清理过期条目
     while _delivery_timestamps and (now - _delivery_timestamps[0][0]) > _TTL_SECONDS:
         _, key = _delivery_timestamps.pop(0)
         _delivery_cache.discard(key)
 
+    # 检查 delivery UUID 去重
     key = f"{event}-{delivery}"
     if key in _delivery_cache:
         return True
+
+    # 检查 payload 内容去重（review 事件：同一 PR + 同一用户 + 同一内容）
+    # 注意：Gitea webhookNotifier 用 review.body，actionsNotifier 用 review.content
+    # 所以去重 key 需要同时取两个字段，确保两种格式生成相同 key
+    if payload and "review" in event:
+        pr_num = payload.get("pull_request", {}).get("number")
+        sender = payload.get("sender", {}).get("login")
+        review = payload.get("review", {})
+        # 取 body 或 content，优先 body（webhookNotifier 格式）
+        content = review.get("body", "") or review.get("content", "")
+        content_hash = hashlib.sha256(content.encode()).hexdigest()[:16]
+        content_key = f"content:{event}:{pr_num}:{sender}:{content_hash}"
+        if content_key in _delivery_cache:
+            logger.info("Content-based duplicate detected: %s PR#%s by %s", event, pr_num, sender)
+            return True
+        _delivery_cache.add(content_key)
+        _delivery_timestamps.append((now, content_key))
+
     _delivery_cache.add(key)
     _delivery_timestamps.append((now, key))
     return False
@@ -86,31 +114,32 @@ _GITEA_TOKEN: str = os.environ.get("GITEA_TOKEN", "")
 _GITEA_BASE = "http://192.168.2.154:3000/api/v1"
 
 
-async def _fetch_pr_files(repo: str, pr_number: int) -> List[str]:
-    """通过 Gitea API 获取 PR changed files 列表。
-
-    Args:
-        repo: 仓库路径（如 "sanguo/sanguo_moziplus_v2"）
-        pr_number: PR 编号
+async def _fetch_pr_files(repo: str, pr_number: int) -> Tuple[List[str], str]:
+    """获取 PR 文件列表，含重试机制。
 
     Returns:
-        文件路径列表
+        (文件列表, 错误信息) — 成功时错误信息为空字符串
     """
     if not _GITEA_TOKEN:
-        logger.warning("GITEA_TOKEN not set, cannot fetch PR files")
-        return []
+        return [], "GITEA_TOKEN 未配置"
 
     url = f"{_GITEA_BASE}/repos/{repo}/pulls/{pr_number}/files"
     headers = {"Authorization": f"token {_GITEA_TOKEN}"}
-    try:
-        async with httpx.AsyncClient(timeout=5.0) as client:
-            resp = await client.get(url, headers=headers)
-            resp.raise_for_status()
-            files: List[Dict[str, Any]] = resp.json()
-            return [f.get("filename", "") for f in files]
-    except Exception:
-        logger.warning("Failed to fetch PR files: %s/pulls/%d", repo, pr_number, exc_info=True)
-        return []
+    last_error = ""
+    for attempt in range(3):
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                resp = await client.get(url, headers=headers)
+                resp.raise_for_status()
+                files: List[Dict[str, Any]] = resp.json()
+                return [f.get("filename", "") for f in files], ""
+        except Exception as e:
+            last_error = str(e)
+            if attempt < 2:
+                await asyncio.sleep(0.5 * (attempt + 1))
+                logger.warning("Retry %d/3 fetching PR files: %s/pulls/%d", attempt + 1, repo, pr_number)
+    logger.warning("Failed to fetch PR files after 3 retries: %s/pulls/%d - %s", repo, pr_number, last_error)
+    return [], f"获取文件列表失败（重试3次）: {last_error}"
 
 
 # ---------------------------------------------------------------------------
@@ -136,10 +165,7 @@ def _calc_risk_level(changed_files: List[str]) -> str:
 # Mail 创建
 # ---------------------------------------------------------------------------
 
-KNOWN_AGENTS = {
-    "pangtong-fujunshi", "simayi-challenger", "zhangfei-dev",
-    "guanyu-dev", "zhaoyun-data", "jiangwei-infra",
-}
+
 
 MAIL_PROJECT_ID = "_mail"
 
@@ -173,7 +199,7 @@ def _send_mail(
     Raises:
         Exception: 数据库写入失败
     """
-    if to_agent not in KNOWN_AGENTS:
+    if to_agent not in AGENT_IDS:
         logger.warning("Unknown agent: %s, skipping mail", to_agent)
         return ""
 
@@ -235,9 +261,12 @@ async def _handle_pull_request(payload: Dict[str, Any]) -> None:
     branch = pr.get("head", {}).get("ref", "unknown")
 
     # 获取改动文件列表
-    changed_files = await _fetch_pr_files(repo, pr_number)
+    changed_files, fetch_error = await _fetch_pr_files(repo, pr_number)
     risk_level = _calc_risk_level(changed_files)
-    file_list = "\n".join(f"- {f}" for f in changed_files) if changed_files else "(无法获取文件列表)"
+    if fetch_error:
+        file_list = f"⚠️ {fetch_error}"
+    else:
+        file_list = "\n".join(f"- {f}" for f in changed_files) if changed_files else "(无文件变更)"
 
     text = render_template("review_request", {
         "repo": repo,
@@ -254,7 +283,12 @@ async def _handle_pull_request(payload: Dict[str, Any]) -> None:
 
 
 async def _handle_pull_request_review(payload: Dict[str, Any]) -> None:
-    """处理 pull_request_review 事件：非 COMMENTED → 通知 PR 作者。"""
+    """处理 pull_request_review 事件：非 COMMENTED → 通知 PR 作者。
+
+    支持两种 payload 格式：
+    - repo webhook: review.state = "APPROVED" / "REQUEST_CHANGES"
+    - org webhook (Gitea v1.23.4): review.type = "pull_request_review_approved" / "pull_request_review_rejected"
+    """
     review = payload.get("review")
     if not review or not isinstance(review, dict):
         logger.warning("pull_request_review event missing review field, skipping")
@@ -263,7 +297,18 @@ async def _handle_pull_request_review(payload: Dict[str, Any]) -> None:
     if not pr or not isinstance(pr, dict):
         logger.warning("pull_request_review event missing pull_request field, skipping")
         return
+
+    # 兼容两种 payload 格式提取 state
     state = review.get("state", "")
+    if not state:
+        # org webhook 格式：review.type = "pull_request_review_approved"
+        review_type = review.get("type", "")
+        type_map = {
+            "pull_request_review_approved": "APPROVED",
+            "pull_request_review_rejected": "REQUEST_CHANGES",
+            "pull_request_review_comment": "COMMENTED",
+        }
+        state = type_map.get(review_type, "")
 
     # 只通知 APPROVED 和 REQUEST_CHANGES，跳过 COMMENTED 和其他状态
     if state == "COMMENTED":
@@ -273,8 +318,9 @@ async def _handle_pull_request_review(payload: Dict[str, Any]) -> None:
     pr_number = pr.get("number", 0)
     pr_title = pr.get("title", "")
     pr_author = pr.get("user", {}).get("login", "unknown")
-    reviewer = review.get("user", {}).get("login", "unknown")
-    review_body = review.get("body", "(无评论)")
+    # 兼容：org webhook 的 review 没有 user，从 sender 取
+    reviewer = review.get("user", {}).get("login", "") or payload.get("sender", {}).get("login", "unknown")
+    review_body = review.get("body", "") or review.get("content", "(无评论)")
 
     result_map = {"APPROVED": "通过 ✓", "REQUEST_CHANGES": "驳回 ✗"}
     if state not in result_map:
@@ -368,6 +414,12 @@ async def _handle_issue_comment(payload: Dict[str, Any]) -> None:
     if not issue or not isinstance(issue, dict):
         logger.warning("issue_comment event missing issue field, skipping")
         return
+
+    # 已关闭的 Issue/PR 不再发送 CI 失败通知
+    if issue.get("state") == "closed":
+        logger.debug("Skipping CI failure notification for closed issue #%s", issue.get("number"))
+        return
+
     repo = _repo_fullname(payload)
     issue_number = issue.get("number", 0)
 
@@ -397,6 +449,12 @@ async def _handle_issue_comment(payload: Dict[str, Any]) -> None:
 _EVENT_HANDLERS: Dict[str, Any] = {
     "pull_request": _handle_pull_request,
     "pull_request_review": _handle_pull_request_review,
+    "pull_request_review_approved": _handle_pull_request_review,
+    "pull_request_review_rejected": _handle_pull_request_review,
+    "pull_request_review_comment": _handle_pull_request_review,
+    # Gitea v1.23.4 实际发出的 review 子事件（无 _review_ 中间段）
+    "pull_request_approved": _handle_pull_request_review,
+    "pull_request_rejected": _handle_pull_request_review,
     "issues": _handle_issues,
     "issue_comment": _handle_issue_comment,
 }
@@ -426,25 +484,23 @@ async def gitea_webhook(
 
     # 1. 签名验证
     if not _verify_signature(body, x_gitea_signature):
-        logger.warning("Webhook signature verification failed (has_sig=%s, sig=%s, expected=%s)",
-                     bool(x_gitea_signature),
-                     x_gitea_signature[:16] if x_gitea_signature else "none",
-                     hmac.new(_WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()[:16])
+        logger.warning("Webhook signature verification failed")
         return Response(status_code=403, content="signature verification failed")
 
-    # 2. 幂等检查
-    if x_gitea_event and x_gitea_delivery:
-        if _is_duplicate(x_gitea_event, x_gitea_delivery):
-            logger.debug("Duplicate webhook: %s/%s", x_gitea_event, x_gitea_delivery)
-            return Response(status_code=200, content="duplicate")
-
-    # 3. 解析 payload
+    # 3. 解析 payload（提前解析，用于幂等检查）
     try:
         payload = await request.json()
     except Exception:
         logger.warning("Failed to parse webhook payload")
         return Response(status_code=200, content="invalid payload")
 
+    # 2. 幂等检查（需要在 payload 解析后，以支持内容去重）
+    if x_gitea_event and x_gitea_delivery:
+        async with _idempotency_lock:
+            if _is_duplicate(x_gitea_event, x_gitea_delivery, payload):
+                logger.debug("Duplicate webhook: %s/%s", x_gitea_event, x_gitea_delivery)
+                return Response(status_code=200, content="duplicate")
+
     # 4. 查找 handler
     handler = _EVENT_HANDLERS.get(x_gitea_event or "")
     if not handler:

src/config/agents.py

@@ -0,0 +1,9 @@
+"""Agent ID 统一注册表。所有模块引用此文件获取合法 Agent ID。"""
+AGENT_IDS = frozenset({
+    "pangtong-fujunshi",
+    "simayi-challenger",
+    "zhangfei-dev",
+    "guanyu-dev",
+    "zhaoyun-data",
+    "jiangwei-infra",
+})

src/daemon/dispatcher.py

@@ -218,7 +218,7 @@ class Dispatcher:
                     def _mail_on_complete(aid, outcome):
                         # 幻觉门控：检查是否有回复，自动标 done/failed
                         try:
-                            _dispatcher._mail_auto_complete(_task_id, aid, _mail_db, _must_haves)
+                            _dispatcher._mail_auto_complete(_task_id, aid, _mail_db, _must_haves, outcome=outcome)
                         except Exception as e:
                             logger.error("Mail %s: on_complete error: %s", _task_id, e)
                     on_complete = _mail_on_complete
@@ -576,7 +576,7 @@ class Dispatcher:
 
                     def _mail_oc_legacy(aid, outcome):
                         try:
-                            _disp._mail_auto_complete(_t_id, aid, _m_db, _m_mh)
+                            _disp._mail_auto_complete(_t_id, aid, _m_db, _m_mh, outcome=outcome)
                         except Exception as e:
                             logger.error("Mail %s: legacy on_complete error: %s", _t_id, e)
                     on_complete_legacy = _mail_oc_legacy
@@ -661,7 +661,7 @@ class Dispatcher:
             logger.error("Mail %s: failed to revert to pending: %s", task_id, e)
 
     def _mail_auto_complete(self, task_id: str, agent_id: str,
-                             db_path: Path, must_haves: str) -> None:
+                             db_path: Path, must_haves: str, outcome=None) -> None:
         """Mail 任务：on_complete 后自动标 done/failed（含幻觉门控）"""
         try:
             # 解析 performative
@@ -712,6 +712,14 @@ class Dispatcher:
                     logger.error("Mail %s: all 3 failed attempts failed, leaving for ticker", task_id)
                     return
 
+            # inform 类型：只对成功 outcome 标 done，失败 outcome 留 working 等 ticker 重投
+            # Task 路径不受此 bug 影响（走 _task_auto_complete 独立逻辑）
+            if performative == "inform":
+                INFORM_DONE_OUTCOMES = {"completed", "claimed", "no_reply"}
+                if outcome not in INFORM_DONE_OUTCOMES:
+                    logger.info("Mail %s: inform outcome=%s, skip auto-done", task_id, outcome)
+                    return
+
             # 标 done（重试 3 次）
             for attempt in range(3):
                 try:

src/daemon/mail_notify.py

@@ -10,14 +10,10 @@ from typing import Optional
 
 from src.blackboard.models import Task
 from src.blackboard.operations import Blackboard
+from src.config.agents import AGENT_IDS
 
 logger = logging.getLogger(__name__)
 
-# 有效 Agent ID 集合（用于校验通知目标）
-_VALID_AGENT_IDS = frozenset({
-    "pangtong-fujunshi", "simayi-challenger", "zhangfei-dev",
-    "guanyu-dev", "zhaoyun-data", "jiangwei-infra",
-})
 
 # 邮件通知正文模板（统一模板，包含所有可能的失败原因和建议）
 _NOTIFY_TEMPLATE = """你的邮件投递失败了。
@@ -76,7 +72,7 @@ def notify_mail_failed(db_path: Path, original_mail_id: str,
 
         # 发件人不是有效 Agent（如 system）→ 通知庞统代处理，不触发广播
         target_agent = from_agent
-        if from_agent not in _VALID_AGENT_IDS:
+        if from_agent not in AGENT_IDS:
             logger.warning("Mail %s: sender '%s' is not a valid agent, routing failure notice to pangtong-fujunshi",
                            original_mail_id, from_agent)
             target_agent = "pangtong-fujunshi"

src/daemon/spawner.py

@@ -848,10 +848,13 @@ curl -X POST http://{api_host}:{api_port}/api/projects/{project_id}/tasks/{task_
             #      A8(gateway_unreachable), A11(lock_conflict),
             #      A10(compact_failed), A12(agent_error)
             # v2.8.1 Fix-3a: crash 类 outcome 设 cooldown,给 agent session 恢复时间
-            if outcome in ("crashed", "compact_failed", "process_crash", "session_stuck",
+            if outcome == "crashed" and self.counter:
+                self.counter.set_cooldown(agent_id, seconds=60)
+                logger.info("Crash cooldown set for %s: 60s (outcome=%s)", agent_id, outcome)
+            elif outcome in ("compact_failed", "process_crash", "session_stuck",
                            "compact_hanging", "agent_error", "compact_interrupted") and self.counter:
                 self.counter.set_cooldown(agent_id, seconds=300)  # 5 分钟
-                logger.info("Crash/error cooldown set for %s: 300s (outcome=%s)", agent_id, outcome)
+                logger.info("Error cooldown set for %s: 300s (outcome=%s)", agent_id, outcome)
             # F1: 不可恢复 outcome → 立刻标 failed + 写黑板
             if outcome in ("auth_failed", "agent_error") and db_path and task_id:
                 logger.error("Task %s: unrecoverable outcome=%s, marking failed immediately", task_id, outcome)

src/main.py

@@ -268,6 +268,17 @@ app.include_router(sse_router)
 app.include_router(mail_router)
 app.include_router(toolchain_router)
 
+# ---------------------------------------------------------------------------
+# 健康检查端点
+# ---------------------------------------------------------------------------
+
+
+@app.get("/api/healthz")
+async def healthz():
+    """轻量级健康检查，无需认证"""
+    return {"status": "ok"}
+
+
 # ---------------------------------------------------------------------------
 # 兼容端点
 # ---------------------------------------------------------------------------

tests/conftest.py

@@ -55,6 +55,21 @@ def client_with_isolation(isolated_data_root):
 
 # ── E2E gate ──
 
+def pytest_collection_modifyitems(config, items):
+    if not os.environ.get("RUN_INTEGRATION"):
+        skip_reason = "needs RUN_INTEGRATION=1"
+        remaining = []
+        deselected = []
+        for item in items:
+            if "integration" in item.keywords or "e2e" in item.keywords:
+                deselected.append(item)
+            else:
+                remaining.append(item)
+        if deselected:
+            config.hook.pytest_deselected(items=deselected)
+            items[:] = remaining
+
+
 skip_no_integration = pytest.mark.skipif(
     not os.environ.get("RUN_INTEGRATION"),
     reason="Set RUN_INTEGRATION=1 to run E2E tests against real daemon",

webhook-test.md

@@ -1 +0,0 @@
-# Webhook test on sanguo_moziplus_v2