Compare commits
14 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 cfdaily
|
4a4e99f738 | ||
|
cfdaily
|
1b0007f244 | ||
 pangtong-fujunshi
|
b953f6da02 | ||
|
cfdaily
|
cc974bf258 | ||
|
pangtong-fujunshi
|
42a28585b8 | ||
|
cfdaily
|
0e4d12898d | ||
|
cfdaily
|
86504faf1f | ||
|
cfdaily
|
2eba38a5a0 | ||
|
pangtong-fujunshi
|
b0b9a72445 | ||
|
cfdaily
|
1c6b66dc63 | ||
|
cfdaily
|
3fa6040b93 | ||
|
cfdaily
|
1485719b0e | ||
|
cfdaily
|
b00d43c8ac | ||
 jiangwei-infra
|
25e7d46328 |
@@ -1,6 +1,6 @@
|
||||
# 三国团队工具链与开发流程设计
|
||||
|
||||
> **状态**: v3.1 — P3 端到端验证通过 + 调研结论写入 + Review API 枚举值修正
|
||||
> **状态**: v3.3 — #19 上下文四层改造合并 + CI 修复 + A13 修订
|
||||
> **作者**: 庞统（副军师）🐦
|
||||
> **评审**: 司马懿（仲达）🗡️
|
||||
> **日期**: 2026-06-06
|
||||
@@ -2765,3 +2765,378 @@ Gitea v1.23.4 自带完整的 CI 管理界面：
|
||||
| §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 改造 |
|
||||
|
||||
|
||||
@@ -1,382 +0,0 @@
|
||||
# #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 速查
|
||||
> 其中 `{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 改造 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,179 @@
|
||||
"""base_task_handler.py — Task type handler 基类。
|
||||
|
||||
收敛合理的共性能力（crash rollback + verify + mark + notify），
|
||||
子类只实现差异点。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
from src.daemon.prompt_composer import PromptContext, PromptComposer, PromptSection
|
||||
from src.blackboard.db import get_connection
|
||||
|
||||
logger = logging.getLogger("moziplus-v2.handler")
|
||||
|
||||
|
||||
@dataclass
|
||||
class VerifyResult:
|
||||
"""验证结果"""
|
||||
passed: bool
|
||||
reason: str # "has_output" / "no_reply" / "no_signal" / ...
|
||||
evidence: str # "output_count=1, comment_count=0"
|
||||
can_retry: bool = True
|
||||
retry_count: int = 0
|
||||
|
||||
|
||||
class BaseTaskHandler:
|
||||
"""所有 task type handler 的基类。
|
||||
|
||||
职责：L2 引擎注入层的业务逻辑——prompt 构建、完成验证、状态标记。
|
||||
不管：进程生命周期、exit 分类、重试决策（这些归 spawner）。
|
||||
"""
|
||||
|
||||
# crash 类 outcome（进程级异常，需要 rollback）
|
||||
CRASH_OUTCOMES = frozenset({
|
||||
"crashed", "compact_failed", "process_crash",
|
||||
"session_stuck", "compact_hanging",
|
||||
})
|
||||
|
||||
task_type: str = ""
|
||||
virtual_project: Optional[str] = None
|
||||
|
||||
# === 子类必须实现 ===
|
||||
|
||||
def build_prompt(self, context: PromptContext) -> str:
|
||||
"""构建 L2 prompt（通过 PromptComposer 拼 section）。子类实现。"""
|
||||
raise NotImplementedError
|
||||
|
||||
def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
|
||||
"""验证任务完成质量。每个 handler 自己的验证逻辑。子类实现。"""
|
||||
raise NotImplementedError
|
||||
|
||||
def target_success_status(self) -> str:
|
||||
"""验证通过后的目标状态。task='review', mail/toolchain='done'"""
|
||||
return "review"
|
||||
|
||||
def get_sections(self) -> list[PromptSection]:
|
||||
"""返回此 handler 的 prompt section 列表。子类实现。"""
|
||||
return []
|
||||
|
||||
# === 基类提供统一流程 ===
|
||||
|
||||
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
|
||||
"""spawn 前业务准备。默认 True。
|
||||
mail/toolchain override 为 auto_working。"""
|
||||
return True
|
||||
|
||||
def post_complete(self, task_id: str, agent_id: str,
|
||||
outcome: str, db_path: Path) -> None:
|
||||
"""spawn 完成后的业务处理。统一 4 步流程：
|
||||
1. crash 处理 → rollback current_agent
|
||||
2. verify → 验证产出
|
||||
3. mark → 标目标状态
|
||||
4. notify → 失败时 on_failure
|
||||
"""
|
||||
# 1. crash 处理（基类提供，所有 handler 继承）
|
||||
if outcome in self.CRASH_OUTCOMES:
|
||||
self._rollback_current_agent(db_path, task_id, agent_id)
|
||||
return
|
||||
|
||||
# 2. verify
|
||||
result = self.verify_completion(task_id, db_path)
|
||||
|
||||
# 3. mark
|
||||
if result.passed:
|
||||
self._mark_task_status(db_path, task_id, self.target_success_status())
|
||||
logger.info("Task %s: verify passed (%s), marked %s",
|
||||
task_id, result.reason, self.target_success_status())
|
||||
else:
|
||||
# 4. notify
|
||||
self.on_failure(task_id, agent_id, db_path, result)
|
||||
|
||||
def on_failure(self, task_id: str, agent_id: str,
|
||||
db_path: Path, verify: VerifyResult) -> None:
|
||||
"""验证失败处理。默认：标 failed。子类可 override。"""
|
||||
self._mark_task_status(db_path, task_id, "failed")
|
||||
logger.info("Task %s: verify failed (%s), marked failed",
|
||||
task_id, verify.reason)
|
||||
|
||||
def check_completion(self, task_id: str, db_path: Path) -> bool:
|
||||
"""ticker 级别的完成检查。默认：False。"""
|
||||
return False
|
||||
|
||||
# === 内部工具方法 ===
|
||||
|
||||
def _rollback_current_agent(self, db_path: Path, task_id: str, agent_id: str) -> None:
|
||||
"""crash 后回退 current_agent → assignee，避免 exclude_current 卡死。
|
||||
从 dispatcher._rollback_current_agent 迁移。"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
conn.execute(
|
||||
"UPDATE tasks SET current_agent = "
|
||||
"(SELECT assignee FROM tasks WHERE id=?) "
|
||||
"WHERE id=? AND current_agent=?",
|
||||
(task_id, task_id, agent_id)
|
||||
)
|
||||
conn.commit()
|
||||
finally:
|
||||
conn.close()
|
||||
logger.info("Task %s: rolled back current_agent from %s to assignee",
|
||||
task_id, agent_id)
|
||||
except Exception as e:
|
||||
logger.warning("Task %s: failed to rollback current_agent: %s",
|
||||
task_id, e)
|
||||
|
||||
def _mark_task_status(self, db_path: Path, task_id: str, status: str) -> None:
|
||||
"""更新任务状态 + 写审计事件。
|
||||
从 dispatcher._mark_task_status 迁移。"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
conn.execute("BEGIN IMMEDIATE")
|
||||
old_row = conn.execute(
|
||||
"SELECT status FROM tasks WHERE id=?", (task_id,)
|
||||
).fetchone()
|
||||
old_status = old_row["status"] if old_row else "unknown"
|
||||
conn.execute(
|
||||
"UPDATE tasks SET status=?, updated_at=datetime('now') WHERE id=?",
|
||||
(status, task_id),
|
||||
)
|
||||
conn.execute(
|
||||
"INSERT INTO events (task_id, agent, event_type, payload) "
|
||||
"VALUES (?, 'handler', 'status_change', ?)",
|
||||
(task_id,
|
||||
f'{{"from": "{old_status}", "to": "{status}", '
|
||||
f'"source": "{self.task_type}_handler"}}'),
|
||||
)
|
||||
conn.commit()
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as e:
|
||||
logger.error("Task %s: mark status error: %s", task_id, e)
|
||||
|
||||
def _auto_mark_working(self, task_id: str, db_path: Path) -> bool:
|
||||
"""pending → working（mail/toolchain 通用）。"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
conn.execute("BEGIN IMMEDIATE")
|
||||
row = conn.execute(
|
||||
"SELECT status FROM tasks WHERE id=?", (task_id,)).fetchone()
|
||||
if not row or row["status"] not in ("pending", "claimed"):
|
||||
logger.warning("Task %s: cannot mark working (status=%s)",
|
||||
task_id, row["status"] if row else "not found")
|
||||
return False
|
||||
conn.execute(
|
||||
"UPDATE tasks SET status='working', updated_at=datetime('now') "
|
||||
"WHERE id=?", (task_id,))
|
||||
conn.commit()
|
||||
logger.info("Task %s: auto-marked working", task_id)
|
||||
return True
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as e:
|
||||
logger.error("Task %s: failed to mark working: %s", task_id, e)
|
||||
return False
|
||||
@@ -0,0 +1,206 @@
|
||||
"""mail_handler.py — Mail 任务 handler。
|
||||
|
||||
处理 Agent 间通信（飞鸽传书），含 inform 和 request 两种类型。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import Dict, Optional
|
||||
|
||||
from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
|
||||
from src.daemon.prompt_composer import PromptComposer, PromptContext
|
||||
from src.blackboard.db import get_connection
|
||||
|
||||
logger = logging.getLogger("moziplus-v2.handler.mail")
|
||||
|
||||
class MailHandler(BaseTaskHandler):
|
||||
"""Mail 任务 handler。"""
|
||||
|
||||
task_type = "mail"
|
||||
virtual_project = "_mail"
|
||||
|
||||
def target_success_status(self) -> str:
|
||||
return "done"
|
||||
|
||||
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
|
||||
"""auto_working：pending → working"""
|
||||
return self._auto_mark_working(task_id, db_path)
|
||||
|
||||
def build_prompt(self, context: PromptContext) -> str:
|
||||
"""通过 PromptComposer 拼装 3 个 section。"""
|
||||
composer = PromptComposer()
|
||||
composer.add_many(self.get_sections())
|
||||
return composer.compose(context)
|
||||
|
||||
def get_sections(self) -> list:
|
||||
return [MailContextSection(), MailApiSection(), MailConstraintsSection()]
|
||||
|
||||
def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
|
||||
"""Mail 完成验证：区分 inform/request。
|
||||
|
||||
- inform: 始终通过（通知已阅即 done，不需要检查产出）
|
||||
- request: 检查是否已回复
|
||||
"""
|
||||
performative = self._parse_performative(task_id, db_path)
|
||||
|
||||
if performative == "inform":
|
||||
return VerifyResult(True, "inform_auto", f"performative={performative}")
|
||||
|
||||
# request: 检查是否已回复
|
||||
has_reply = self._check_reply(task_id, db_path)
|
||||
if has_reply:
|
||||
return VerifyResult(True, "has_reply", f"performative={performative}")
|
||||
return VerifyResult(False, "no_reply", f"performative={performative}")
|
||||
|
||||
# post_complete 由基类 BaseTaskHandler 统一处理（crash→verify→mark→notify）
|
||||
# inform: verify 始终通过 → 基类 mark done ✅
|
||||
# request 有回复: verify 通过 → 基类 mark done ✅
|
||||
# request 无回复: verify 失败 → 基类调 on_failure ✅
|
||||
|
||||
def on_failure(self, task_id: str, agent_id: str,
|
||||
db_path: Path, verify: VerifyResult) -> None:
|
||||
"""request 验证失败 → 标 failed + 通知发件人"""
|
||||
self._mark_task_status(db_path, task_id, "failed")
|
||||
logger.info("Mail %s: request verify failed (%s), marked failed",
|
||||
task_id, verify.reason)
|
||||
|
||||
# 通知发件人
|
||||
try:
|
||||
from src.daemon.mail_notify import notify_mail_failed
|
||||
notify_mail_failed(db_path, task_id, "no_reply_found")
|
||||
except Exception as e:
|
||||
logger.warning("Mail %s: failed to send notification: %s", task_id, e)
|
||||
|
||||
# === 内部方法 ===
|
||||
|
||||
def _parse_performative(self, task_id: str, db_path: Path) -> str:
|
||||
"""解析 mail 类型（inform/request）"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
row = conn.execute(
|
||||
"SELECT must_haves FROM tasks WHERE id=?", (task_id,)
|
||||
).fetchone()
|
||||
if row and row["must_haves"]:
|
||||
meta = json.loads(row["must_haves"])
|
||||
return meta.get("performative", meta.get("type", "request"))
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception:
|
||||
pass
|
||||
return "request"
|
||||
|
||||
def _check_reply(self, task_id: str, db_path: Path) -> bool:
|
||||
"""检查是否已回复（从 dispatcher._mail_check_reply 迁移）"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
row = conn.execute(
|
||||
"SELECT COUNT(*) as cnt FROM comments "
|
||||
"WHERE task_id=? AND author != 'daemon' "
|
||||
"AND comment_type != 'system'",
|
||||
(task_id,)
|
||||
).fetchone()
|
||||
count = row["cnt"] if row else 0
|
||||
return count > 0
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as e:
|
||||
logger.error("Mail %s: check reply error: %s", task_id, e)
|
||||
return False
|
||||
|
||||
def check_completion(self, task_id: str, db_path: Path) -> bool:
|
||||
"""ticker 级别的完成检查：检查是否已回复"""
|
||||
return self._check_reply(task_id, db_path)
|
||||
|
||||
|
||||
# ===================================================================
|
||||
# Mail PromptSections
|
||||
# ===================================================================
|
||||
|
||||
class MailContextSection:
|
||||
"""邮件上下文段 — 发件人/收件人/主题/内容，区分 inform/request。"""
|
||||
|
||||
name: str = "mail_context"
|
||||
priority: int = 10
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
if context.mail_type == "inform":
|
||||
return self._render_inform(context)
|
||||
return self._render_request(context)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool: # noqa: ARG002
|
||||
return True
|
||||
|
||||
@staticmethod
|
||||
def _render_inform(context: PromptContext) -> str:
|
||||
return (
|
||||
f"你收到一封飞鸽传书(纯通知)。\n\n"
|
||||
f"发件者: {context.from_agent}\n"
|
||||
f"主题: {context.title}\n"
|
||||
f"内容: {context.description}\n\n"
|
||||
f"已阅即可。如需回复,用 in_reply_to 回复发件者(不需要填 to)。\n"
|
||||
f"⚠️ 不要执行任何状态转换命令。"
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _render_request(context: PromptContext) -> str:
|
||||
return (
|
||||
f"你收到一封飞鸽传书,需要你处理并回复。\n\n"
|
||||
f"发件者: {context.from_agent}\n"
|
||||
f"主题: {context.title}\n"
|
||||
f"内容: {context.description}\n\n"
|
||||
f"### 如何回复发件者\n\n"
|
||||
f'curl -s -X POST http://localhost:8083/api/mail \\\n'
|
||||
f" -H 'Content-Type: application/json' \\\n"
|
||||
f' -d \'{{"from": "{context.agent_id}", '
|
||||
f'"in_reply_to": "{context.task_id}", '
|
||||
f'"title": "回复: {context.title}", '
|
||||
f'"text": "你的回复内容"}}\'\n\n'
|
||||
f"⚠️ 不需要填 \"to\",系统自动回复给发件者。"
|
||||
)
|
||||
|
||||
|
||||
class MailApiSection:
|
||||
"""Mail API 操作指令段。"""
|
||||
|
||||
name: str = "mail_api"
|
||||
priority: int = 40
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
return (
|
||||
f"### 如何给其他人发新邮件\n\n"
|
||||
f'curl -s -X POST http://localhost:8083/api/mail \\\n'
|
||||
f" -H 'Content-Type: application/json' \\\n"
|
||||
f' -d \'{{"from": "{context.agent_id}", '
|
||||
f'"to": "对方agent-id", '
|
||||
f'"title": "标题", '
|
||||
f'"text": "正文", '
|
||||
f'"type": "inform"}}\'\n\n'
|
||||
f"⚠️ to 必须是有效的 agent id\n"
|
||||
f"⚠️ 纯通知用 type=inform,需要对方回复不填 type(默认 request)"
|
||||
)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return context.mail_type == "request"
|
||||
|
||||
|
||||
class MailConstraintsSection:
|
||||
"""Mail 硬约束段。"""
|
||||
|
||||
name: str = "mail_constraints"
|
||||
priority: int = 50
|
||||
|
||||
def render(self, context: PromptContext) -> str: # noqa: ARG002
|
||||
return (
|
||||
"## 硬约束\n\n"
|
||||
"1. ⚠️ 不要执行任何状态转换命令(标 working/done/review/failed 等),系统会自动处理。\n"
|
||||
"2. ⚠️ 不能给自己发邮件\n"
|
||||
"3. ⚠️ 发邮件时 to 必须是有效的 agent id\n"
|
||||
"4. ⚠️ 纯通知用 type=inform,需要对方回复不填 type(默认 request)"
|
||||
)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool: # noqa: ARG002
|
||||
return True
|
||||
@@ -0,0 +1,127 @@
|
||||
"""
|
||||
prompt_composer.py — PromptSection Protocol + PromptContext + PromptComposer
|
||||
|
||||
拼装器：有序管理 prompt 段落，按优先级排序后合并为最终 prompt。
|
||||
"""
|
||||
|
||||
import logging
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
|
||||
|
||||
logger = logging.getLogger("moziplus-v2.prompt_composer")
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Section 优先级范围约定
|
||||
# ---------------------------------------------------------------------------
|
||||
PRIORITY_CONTEXT = 10 # 任务上下文
|
||||
PRIORITY_PRIOR = 20 # 前序信息
|
||||
PRIORITY_ROLE = 30 # 角色规范
|
||||
PRIORITY_API = 40 # API 操作指令
|
||||
PRIORITY_CONSTRAINTS = 50 # 硬约束
|
||||
PRIORITY_EXTENSION = 60 # 扩展段
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# PromptSection Protocol
|
||||
# ---------------------------------------------------------------------------
|
||||
@runtime_checkable
|
||||
class PromptSection(Protocol):
|
||||
"""一个 prompt 段"""
|
||||
|
||||
name: str # 段名（去重用，同名覆盖）
|
||||
priority: int # 排序优先级（小数字=靠前）
|
||||
|
||||
def render(self, context: "PromptContext") -> str:
|
||||
"""渲染此段的文本内容。返回空字符串表示不注入。"""
|
||||
...
|
||||
|
||||
def should_include(self, context: "PromptContext") -> bool:
|
||||
"""是否注入此段（默认 True，条件段可覆盖）。"""
|
||||
...
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# PromptContext 数据对象
|
||||
# ---------------------------------------------------------------------------
|
||||
@dataclass
|
||||
class PromptContext:
|
||||
"""Prompt 渲染的统一上下文"""
|
||||
|
||||
task_id: str
|
||||
title: str
|
||||
description: str
|
||||
must_haves: str
|
||||
project_id: str
|
||||
agent_id: str
|
||||
|
||||
task: Optional[Dict] = None
|
||||
role: str = "executor"
|
||||
spawn_type: str = "executor"
|
||||
|
||||
# mail 专用
|
||||
from_agent: str = ""
|
||||
mail_type: str = "" # inform / request
|
||||
|
||||
# toolchain 专用
|
||||
event_type: str = "" # ci_failure / review_request / ...
|
||||
event_data: Dict = field(default_factory=dict)
|
||||
|
||||
# 前序产出
|
||||
depends_on_outputs: Optional[List] = None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# PromptComposer 拼装器
|
||||
# ---------------------------------------------------------------------------
|
||||
class PromptComposer:
|
||||
"""有序拼装 prompt sections"""
|
||||
|
||||
SEPARATOR = "\n\n---\n\n"
|
||||
TOKEN_BUDGET_WARN = 800 # token 预算警告阈值
|
||||
CHARS_PER_TOKEN = 3.5 # 估算比率
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._sections: List[PromptSection] = []
|
||||
|
||||
def add(self, section: PromptSection) -> None:
|
||||
"""添加一个 section（同名覆盖）"""
|
||||
self._sections = [s for s in self._sections if s.name != section.name]
|
||||
self._sections.append(section)
|
||||
|
||||
def add_many(self, sections: List[PromptSection]) -> None:
|
||||
"""批量添加"""
|
||||
for s in sections:
|
||||
self.add(s)
|
||||
|
||||
def compose(self, context: PromptContext) -> str:
|
||||
"""拼装最终 prompt
|
||||
|
||||
1. 过滤 should_include=False 的段
|
||||
2. 按 priority 排序
|
||||
3. 逐段 render
|
||||
4. 过滤空段
|
||||
5. 用分隔符连接
|
||||
6. Token 预算警告（不截断）
|
||||
"""
|
||||
active = [s for s in self._sections if s.should_include(context)]
|
||||
active.sort(key=lambda s: s.priority)
|
||||
|
||||
parts = [s.render(context) for s in active]
|
||||
parts = [p for p in parts if p.strip()]
|
||||
|
||||
result = self.SEPARATOR.join(parts)
|
||||
|
||||
# Token 估算
|
||||
tokens = max(1, int(len(result) / self.CHARS_PER_TOKEN))
|
||||
logger.debug(
|
||||
"Composed prompt from %d sections, %d tokens",
|
||||
len(parts), tokens,
|
||||
)
|
||||
|
||||
if tokens > self.TOKEN_BUDGET_WARN:
|
||||
logger.warning(
|
||||
"Prompt exceeds %d token budget: %d tokens (task_id=%s)",
|
||||
self.TOKEN_BUDGET_WARN, tokens, context.task_id,
|
||||
)
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,330 @@
|
||||
"""task_handler.py — 黑板任务 handler（task_type='task'）。
|
||||
|
||||
标准黑板任务：三信号验证 → review 状态。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional
|
||||
|
||||
from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
|
||||
from src.daemon.prompt_composer import PromptComposer, PromptContext
|
||||
from src.blackboard.db import get_connection
|
||||
|
||||
logger = logging.getLogger("moziplus-v2.handler")
|
||||
|
||||
TERMINAL_STATES = frozenset({"review", "done", "failed", "cancelled"})
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Role → Skill 映射（D8 决策：L2 只给索引+引导语，不注全文）
|
||||
# ---------------------------------------------------------------------------
|
||||
ROLE_SKILL_MAP: Dict[str, str] = {
|
||||
"executor": "blackboard-executor",
|
||||
"reviewer": "blackboard-reviewer",
|
||||
"reviewer-simayi": "blackboard-reviewer-simayi",
|
||||
"reviewer-pangtong": "blackboard-reviewer-pangtong",
|
||||
"planner": "blackboard-planner",
|
||||
"claim": "blackboard-claim",
|
||||
}
|
||||
|
||||
SKILL_BASE_PATH = "/Users/chufeng/.sanguo_projects/sanguo_mozi/skills"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# PromptSection 实现
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class TaskContextSection:
|
||||
"""段 1：任务上下文（title / desc / must_haves / status）。"""
|
||||
|
||||
name: str = "task_context"
|
||||
priority: int = 10
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
parts = ["## 任务上下文"]
|
||||
if context.task_id:
|
||||
parts.append(f"任务ID: {context.task_id}")
|
||||
if context.title:
|
||||
parts.append(f"标题: {context.title}")
|
||||
if context.description:
|
||||
parts.append(f"描述: {context.description}")
|
||||
if context.must_haves:
|
||||
parts.append(f"必须完成: {context.must_haves}")
|
||||
if context.task and context.task.get("status"):
|
||||
parts.append(f"当前状态: {context.task['status']}")
|
||||
return "\n".join(parts)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return bool(context.task_id or context.title)
|
||||
|
||||
|
||||
class PriorOutputsSection:
|
||||
"""段 2：前序产出摘要（depends_on 非空时注入）。"""
|
||||
|
||||
name: str = "prior_outputs"
|
||||
priority: int = 20
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
outputs = context.depends_on_outputs or []
|
||||
parts = ["## 前序产出"]
|
||||
for out in outputs:
|
||||
tid = out.get("task_id", "?")
|
||||
summary = out.get("summary", "无摘要")
|
||||
parts.append(f"- [{tid}] {summary}")
|
||||
return "\n".join(parts)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return bool(context.depends_on_outputs)
|
||||
|
||||
|
||||
class RoleSkillSection:
|
||||
"""段 3：角色 Skill 索引+引导语（D8 决策：不注全文）。"""
|
||||
|
||||
name: str = "role_skill"
|
||||
priority: int = 30
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
skill_name = ROLE_SKILL_MAP.get(context.role, "")
|
||||
lines = [
|
||||
"## 角色操作规范",
|
||||
f"你的角色：{context.role}",
|
||||
]
|
||||
if skill_name:
|
||||
lines.append(f"对应 Skill：{skill_name}")
|
||||
lines.append(
|
||||
f"请用 read 工具读取 {SKILL_BASE_PATH}/{skill_name}/SKILL.md "
|
||||
"获取完整操作规范。"
|
||||
)
|
||||
else:
|
||||
lines.append("无对应 Skill 文件，按通用规范执行。")
|
||||
return "\n".join(lines)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return True
|
||||
|
||||
|
||||
class TaskApiSection:
|
||||
"""段 4：API 操作指令。"""
|
||||
|
||||
name: str = "task_api"
|
||||
priority: int = 40
|
||||
|
||||
API_HOST = "localhost"
|
||||
API_PORT = 8083
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
pid = context.project_id
|
||||
tid = context.task_id
|
||||
aid = context.agent_id
|
||||
success_status = '"review"'
|
||||
base = f"http://{self.API_HOST}:{self.API_PORT}/api/projects/{pid}/tasks/{tid}"
|
||||
return (
|
||||
"## 操作指令\n"
|
||||
"### 状态回写\n"
|
||||
f"开始工作:\n"
|
||||
f'curl -X POST {base}/status \\\n'
|
||||
f' -H "Content-Type: application/json" \\\n'
|
||||
f' -d \'{{"status": "working", "agent": "{aid}"}}\'\n\n'
|
||||
"### 写入产出\n"
|
||||
f'curl -X POST {base}/outputs \\\n'
|
||||
f' -H "Content-Type: application/json" \\\n'
|
||||
f" -d '{{\"type\": \"text\", \"content\": \"<your output>\"}}'\n\n"
|
||||
"### 完成后\n"
|
||||
f"成功: status → {success_status} | 失败: status → \"failed\""
|
||||
)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return True
|
||||
|
||||
|
||||
class TaskConstraintsSection:
|
||||
"""段 5：硬约束。"""
|
||||
|
||||
name: str = "task_constraints"
|
||||
priority: int = 50
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
constraints = ["## 硬约束"]
|
||||
role = context.role
|
||||
if role == "executor":
|
||||
constraints.extend([
|
||||
"- 完成后必须标 review",
|
||||
"- 产出物不能为空（系统会验证）",
|
||||
"- handoff comment ≥ 50 字符",
|
||||
])
|
||||
elif role.startswith("reviewer"):
|
||||
constraints.extend([
|
||||
"- 审查结果必须明确 pass/fail",
|
||||
"- 评审意见须附证据（文件:行号）",
|
||||
])
|
||||
elif role == "planner":
|
||||
constraints.extend([
|
||||
"- 需求不清时提问，不要猜",
|
||||
"- 子任务必须有明确的终态定义",
|
||||
])
|
||||
else:
|
||||
constraints.append("- 按规范完成 assigned 任务")
|
||||
return "\n".join(constraints)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return True
|
||||
|
||||
|
||||
class TaskHandler(BaseTaskHandler):
|
||||
"""黑板标准任务 handler。
|
||||
|
||||
- verify: 三信号检查（output / comment / terminal status）
|
||||
- 成功 → review
|
||||
- 失败 → 保持 working，让 ticker 重试
|
||||
- review 完成 → 读取 verdict，approved 则 mark done
|
||||
"""
|
||||
|
||||
task_type: str = "task"
|
||||
virtual_project: Optional[str] = None
|
||||
|
||||
# === 子类实现 ===
|
||||
|
||||
def target_success_status(self) -> str:
|
||||
"""task 类型验证通过后进 review。"""
|
||||
return "review"
|
||||
|
||||
def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
|
||||
"""三信号验证：output / comment / terminal status。"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
# 信号 1：terminal status
|
||||
row = conn.execute(
|
||||
"SELECT status FROM tasks WHERE id=?", (task_id,)
|
||||
).fetchone()
|
||||
if not row:
|
||||
return VerifyResult(False, "not_found", "task not found",
|
||||
can_retry=False)
|
||||
status = row["status"]
|
||||
if status in TERMINAL_STATES:
|
||||
return VerifyResult(
|
||||
True, "terminal_status",
|
||||
f"status={status}", can_retry=False
|
||||
)
|
||||
|
||||
# 信号 2：outputs
|
||||
output_count = conn.execute(
|
||||
"SELECT COUNT(*) as cnt FROM outputs WHERE task_id=?",
|
||||
(task_id,)
|
||||
).fetchone()["cnt"]
|
||||
if output_count > 0:
|
||||
return VerifyResult(
|
||||
True, "has_output",
|
||||
f"output_count={output_count}"
|
||||
)
|
||||
|
||||
# 信号 3：非 system 且内容 >= 50 字的 comment
|
||||
comment_count = conn.execute(
|
||||
"SELECT COUNT(*) as cnt FROM comments "
|
||||
"WHERE task_id=? AND author != 'system' "
|
||||
"AND LENGTH(content) >= 50",
|
||||
(task_id,)
|
||||
).fetchone()["cnt"]
|
||||
if comment_count > 0:
|
||||
return VerifyResult(
|
||||
True, "has_comment",
|
||||
f"comment_count={comment_count}"
|
||||
)
|
||||
|
||||
# 无信号
|
||||
return VerifyResult(
|
||||
False, "no_signal",
|
||||
f"output=0, comment=0, status={status}"
|
||||
)
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as e:
|
||||
logger.error("Task %s: verify error: %s", task_id, e)
|
||||
return VerifyResult(False, "verify_error", str(e))
|
||||
|
||||
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
|
||||
"""task 类型不需要 pre_spawn 逻辑。"""
|
||||
return True
|
||||
|
||||
def get_sections(self) -> list:
|
||||
"""返回 5 个 PromptSection 实例。"""
|
||||
return [
|
||||
TaskContextSection(),
|
||||
PriorOutputsSection(),
|
||||
RoleSkillSection(),
|
||||
TaskApiSection(),
|
||||
TaskConstraintsSection(),
|
||||
]
|
||||
|
||||
def build_prompt(self, context: PromptContext) -> str:
|
||||
"""通过 PromptComposer 拼装 prompt sections。"""
|
||||
composer = PromptComposer()
|
||||
composer.add_many(self.get_sections())
|
||||
return composer.compose(context)
|
||||
|
||||
def on_failure(self, task_id: str, agent_id: str,
|
||||
db_path: Path, verify: VerifyResult) -> None:
|
||||
"""验证失败：不标 failed，保持 working 让 ticker 重试。"""
|
||||
logger.info(
|
||||
"Task %s: verify failed (%s, evidence=%s), leaving working for ticker retry",
|
||||
task_id, verify.reason, verify.evidence
|
||||
)
|
||||
|
||||
# === Review 流程 ===
|
||||
|
||||
def handle_review_complete(self, task_id: str, db_path: Path) -> None:
|
||||
"""Review 完成后处理：读取 verdict → approved 则 mark done，
|
||||
否则 @mention assignee via blackboard comment。"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
# 读取最新 review
|
||||
review_row = conn.execute(
|
||||
"SELECT verdict, reviewer, comment FROM reviews "
|
||||
"WHERE task_id=? ORDER BY created_at DESC LIMIT 1",
|
||||
(task_id,)
|
||||
).fetchone()
|
||||
|
||||
if not review_row:
|
||||
logger.warning("Task %s: no review found", task_id)
|
||||
return
|
||||
|
||||
verdict = review_row["verdict"]
|
||||
reviewer = review_row["reviewer"]
|
||||
review_comment = review_row["comment"] or ""
|
||||
|
||||
# 获取 assignee
|
||||
task_row = conn.execute(
|
||||
"SELECT assignee FROM tasks WHERE id=?", (task_id,)
|
||||
).fetchone()
|
||||
if not task_row:
|
||||
logger.warning("Task %s: task not found for review", task_id)
|
||||
return
|
||||
assignee = task_row["assignee"]
|
||||
|
||||
if verdict == "approved":
|
||||
self._mark_task_status(db_path, task_id, "done")
|
||||
logger.info("Task %s: review approved by %s, marked done",
|
||||
task_id, reviewer)
|
||||
else:
|
||||
# 非 approved：通过 blackboard comment @mention assignee
|
||||
conn.execute(
|
||||
"INSERT INTO comments (task_id, author, content) "
|
||||
"VALUES (?, 'system', ?)",
|
||||
(task_id,
|
||||
f"@{assignee} review 未通过 (verdict={verdict}, "
|
||||
f"reviewer={reviewer}): {review_comment}")
|
||||
)
|
||||
conn.commit()
|
||||
# 回到 working 让 assignee 重新处理
|
||||
self._mark_task_status(db_path, task_id, "working")
|
||||
logger.info(
|
||||
"Task %s: review not approved (%s by %s), "
|
||||
"@mentioned assignee %s, back to working",
|
||||
task_id, verdict, reviewer, assignee
|
||||
)
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as e:
|
||||
logger.error("Task %s: handle_review_complete error: %s", task_id, e)
|
||||
@@ -0,0 +1,102 @@
|
||||
"""
|
||||
task_type_registry.py — Task type handler Protocol + Registry.
|
||||
|
||||
启动时一次性加载 handler，运行时只读。
|
||||
零依赖：不导入项目内其他模块。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol, runtime_checkable
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from src.daemon.prompt_composer import PromptContext
|
||||
|
||||
logger = logging.getLogger("moziplus-v2.registry")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Protocol
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@runtime_checkable
|
||||
class TaskTypeHandler(Protocol):
|
||||
"""所有 task type handler 的统一接口。"""
|
||||
|
||||
# 属性（通过 __init__ 设置）
|
||||
task_type: str # 类型标识：'task' | 'mail' | 'toolchain'
|
||||
virtual_project: Optional[str] # 虚拟项目 ID，如 '_mail'、'_toolchain'。普通任务为 None
|
||||
|
||||
def build_prompt(self, context: "PromptContext") -> str:
|
||||
"""构建 Agent prompt（通过 PromptComposer 拼 section）。"""
|
||||
...
|
||||
|
||||
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
|
||||
"""spawn 前业务准备。默认 True，mail/toolchain override 为 auto_working。"""
|
||||
...
|
||||
|
||||
def post_complete(
|
||||
self,
|
||||
task_id: str,
|
||||
agent_id: str,
|
||||
outcome: str,
|
||||
db_path: Path,
|
||||
) -> None:
|
||||
"""spawn 完成后的业务处理。统一流程：crash→verify→mark→notify。"""
|
||||
...
|
||||
|
||||
def check_completion(self, task_id: str, db_path: Path) -> bool:
|
||||
"""ticker 级别的完成检查。"""
|
||||
...
|
||||
|
||||
def get_sections(self) -> list:
|
||||
"""返回此 handler 的 prompt section 列表。"""
|
||||
...
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Registry
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class TaskTypeRegistry:
|
||||
"""Task type handler 注册表。启动时一次性加载，运行时只读。"""
|
||||
|
||||
_handlers: Dict[str, TaskTypeHandler] = {}
|
||||
|
||||
@classmethod
|
||||
def register(cls, handler: TaskTypeHandler) -> None:
|
||||
"""注册一个 handler。启动时调用一次。"""
|
||||
if handler.task_type in cls._handlers:
|
||||
raise ValueError(f"Task type '{handler.task_type}' already registered")
|
||||
cls._handlers[handler.task_type] = handler
|
||||
vp = getattr(handler, "virtual_project", None)
|
||||
logger.info("Registered task type handler: %s (virtual_project=%s)", handler.task_type, vp)
|
||||
|
||||
@classmethod
|
||||
def get_by_project(cls, project_id: str) -> Optional[TaskTypeHandler]:
|
||||
"""通过 project_id 查找 handler（匹配 virtual_project）。"""
|
||||
for h in cls._handlers.values():
|
||||
if h.virtual_project == project_id:
|
||||
return h
|
||||
return None
|
||||
|
||||
@classmethod
|
||||
def get(cls, task_type: str) -> Optional[TaskTypeHandler]:
|
||||
"""通过 task_type 标识查找 handler。"""
|
||||
return cls._handlers.get(task_type)
|
||||
|
||||
@classmethod
|
||||
def virtual_projects(cls) -> list[str]:
|
||||
"""返回所有已注册的虚拟项目 ID（ticker 自动发现用）。"""
|
||||
return [
|
||||
h.virtual_project
|
||||
for h in cls._handlers.values()
|
||||
if h.virtual_project is not None
|
||||
]
|
||||
|
||||
@classmethod
|
||||
def clear(cls) -> None:
|
||||
"""清空注册表（仅测试用）。"""
|
||||
cls._handlers = {}
|
||||
@@ -0,0 +1,256 @@
|
||||
"""toolchain_handler.py — 工具链事件 handler。
|
||||
|
||||
处理 Gitea Webhook 事件（CI 失败、Review 请求、Issue 指派等）。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import urllib.request
|
||||
from pathlib import Path
|
||||
from typing import Dict
|
||||
|
||||
from src.daemon.base_task_handler import BaseTaskHandler, VerifyResult
|
||||
from src.daemon.prompt_composer import PromptComposer, PromptContext
|
||||
from src.daemon.toolchain_templates import render_template, _TEMPLATE_MAP
|
||||
from src.blackboard.db import get_connection
|
||||
|
||||
logger = logging.getLogger("moziplus-v2.handler.toolchain")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Toolchain PromptSections
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class ToolchainContextSection:
|
||||
"""事件类型 + 事件详情（priority=10）"""
|
||||
|
||||
name: str = "toolchain_context"
|
||||
priority: int = 10
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
event_type = context.event_type
|
||||
event_data: Dict = context.event_data or {}
|
||||
|
||||
if event_type in _TEMPLATE_MAP:
|
||||
# 使用模板引擎渲染已知事件
|
||||
variables = {k: str(v) for k, v in event_data.items()}
|
||||
return render_template(event_type, variables)
|
||||
|
||||
# fallback：通用事件描述
|
||||
lines = [f"## 工具链事件", f""]
|
||||
lines.append(f"- **事件类型**: {event_type or '未知'}")
|
||||
if event_data:
|
||||
lines.append(f"- **事件详情**:")
|
||||
for key, value in event_data.items():
|
||||
lines.append(f" - {key}: {value}")
|
||||
lines.append(f"")
|
||||
return "\n".join(lines)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return True
|
||||
|
||||
|
||||
class ToolchainApiSection:
|
||||
"""API 操作指令（priority=40），success_status=done"""
|
||||
|
||||
name: str = "toolchain_api"
|
||||
priority: int = 40
|
||||
|
||||
API_HOST = "localhost:8083"
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
lines = [
|
||||
"## API 操作指令",
|
||||
"",
|
||||
f"项目 ID: `{context.project_id}`",
|
||||
f"任务 ID: `{context.task_id}`",
|
||||
"",
|
||||
"### 完成后必须更新任务状态",
|
||||
"完成后务必通过以下命令将任务标记为 **done**：",
|
||||
"```bash",
|
||||
f'curl -s -X POST "http://{self.API_HOST}/api/projects/{context.project_id}/tasks/{context.task_id}/status" \\',
|
||||
' -H "Content-Type: application/json" \\',
|
||||
' -d \'{"status": "done"}\'',
|
||||
"```",
|
||||
"",
|
||||
"### 提交产出",
|
||||
"如有产出（如 review 结果、修复方案），提交到任务 outputs：",
|
||||
"```bash",
|
||||
f'curl -s -X POST "http://{self.API_HOST}/api/projects/{context.project_id}/tasks/{context.task_id}/outputs" \\',
|
||||
' -H "Content-Type: application/json" \\',
|
||||
' -d \'{"content": "<你的产出内容>", "type": "text"}\'',
|
||||
"```",
|
||||
"",
|
||||
]
|
||||
return "\n".join(lines)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return True
|
||||
|
||||
|
||||
class ToolchainConstraintsSection:
|
||||
"""硬约束（priority=50）"""
|
||||
|
||||
name: str = "toolchain_constraints"
|
||||
priority: int = 50
|
||||
|
||||
def render(self, context: PromptContext) -> str:
|
||||
lines = [
|
||||
"## 硬约束",
|
||||
"",
|
||||
"1. **必须标 done**：处理完成后必须通过 API 将任务状态更新为 `done`，否则视为未完成",
|
||||
"2. **产出不能为空**：必须提交有意义的产出（output 或 comment），不能只改状态",
|
||||
"3. **单一职责**：只处理本次事件相关的操作，不要越界执行无关任务",
|
||||
"4. **出错即报告**：如果无法处理（如权限不足、资源不存在），在 comment 中说明原因并标 done",
|
||||
"5. **不要创建新任务**：工具链事件只处理当前事件，不衍生新任务",
|
||||
"",
|
||||
]
|
||||
return "\n".join(lines)
|
||||
|
||||
def should_include(self, context: PromptContext) -> bool:
|
||||
return True
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# ToolchainHandler
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class ToolchainHandler(BaseTaskHandler):
|
||||
"""工具链事件 handler。"""
|
||||
|
||||
task_type = "toolchain"
|
||||
virtual_project = "_toolchain"
|
||||
|
||||
def target_success_status(self) -> str:
|
||||
return "done"
|
||||
|
||||
def pre_spawn(self, task_id: str, db_path: Path) -> bool:
|
||||
"""auto_working：pending → working"""
|
||||
return self._auto_mark_working(task_id, db_path)
|
||||
|
||||
def get_sections(self) -> list:
|
||||
"""返回 3 个 Toolchain PromptSection 实例"""
|
||||
return [
|
||||
ToolchainContextSection(),
|
||||
ToolchainApiSection(),
|
||||
ToolchainConstraintsSection(),
|
||||
]
|
||||
|
||||
def build_prompt(self, context: PromptContext) -> str:
|
||||
"""通过 PromptComposer 拼装 sections 为最终 prompt"""
|
||||
composer = PromptComposer()
|
||||
composer.add_many(self.get_sections())
|
||||
return composer.compose(context)
|
||||
|
||||
def verify_completion(self, task_id: str, db_path: Path) -> VerifyResult:
|
||||
"""检查行动输出（output 或 comment 有实质内容）"""
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
# 检查 output
|
||||
output_count = conn.execute(
|
||||
"SELECT COUNT(*) FROM outputs WHERE task_id=?", (task_id,)
|
||||
).fetchone()[0]
|
||||
if output_count > 0:
|
||||
return VerifyResult(True, "has_output", f"output_count={output_count}")
|
||||
|
||||
# 检查 comment（非系统、有实质内容）
|
||||
comment_count = conn.execute(
|
||||
"SELECT COUNT(*) FROM comments WHERE task_id=? "
|
||||
"AND author != 'system' AND LENGTH(content) >= 20",
|
||||
(task_id,)
|
||||
).fetchone()[0]
|
||||
if comment_count > 0:
|
||||
return VerifyResult(True, "has_comment", f"comment_count={comment_count}")
|
||||
|
||||
return VerifyResult(False, "no_action", "output=0, comment=0")
|
||||
finally:
|
||||
conn.close()
|
||||
except Exception as e:
|
||||
logger.error("Toolchain %s: verify error: %s", task_id, e)
|
||||
return VerifyResult(False, "verify_error", str(e))
|
||||
|
||||
def on_failure(self, task_id: str, agent_id: str,
|
||||
db_path: Path, verify: VerifyResult) -> None:
|
||||
"""验证失败 → 标 failed + Mail API 通知主公"""
|
||||
self._mark_task_status(db_path, task_id, "failed")
|
||||
logger.info("Toolchain %s: verify failed (%s), marked failed", task_id, verify.reason)
|
||||
|
||||
# 从 db 读取事件上下文
|
||||
event_type = ""
|
||||
event_data: Dict = {}
|
||||
try:
|
||||
conn = get_connection(db_path)
|
||||
row = conn.execute(
|
||||
"SELECT must_haves FROM tasks WHERE id=?", (task_id,)
|
||||
).fetchone()
|
||||
if row and row["must_haves"]:
|
||||
meta = json.loads(row["must_haves"])
|
||||
event_type = meta.get("event_type", "")
|
||||
raw = meta.get("event_data", "{}")
|
||||
event_data = json.loads(raw) if isinstance(raw, str) else raw
|
||||
conn.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
self._notify_via_mail_api(
|
||||
task_id, verify.reason, verify.evidence,
|
||||
event_type, event_data,
|
||||
)
|
||||
|
||||
def _notify_via_mail_api(
|
||||
self,
|
||||
task_id: str,
|
||||
reason: str,
|
||||
evidence: str,
|
||||
event_type: str,
|
||||
event_data: Dict,
|
||||
) -> None:
|
||||
"""通过 Mail API 发送丰富的失败通知给主公。"""
|
||||
# 构建行动指引
|
||||
action_hint = "请检查黑板任务并手动处理。"
|
||||
et_lower = event_type.lower()
|
||||
if "ci" in et_lower or "deploy" in et_lower:
|
||||
action_hint = "建议创建任务派给 jiangwei-infra 检查 CI/部署问题。"
|
||||
elif "review" in et_lower:
|
||||
action_hint = "建议查看 PR review 状态，必要时通知相关开发者。"
|
||||
elif "issue" in et_lower:
|
||||
action_hint = "建议创建任务派给对应开发者处理 Issue。"
|
||||
|
||||
# 构建事件详情
|
||||
event_details = ""
|
||||
if event_data:
|
||||
event_details = "\n".join(
|
||||
f" - {k}: {v}" for k, v in event_data.items()
|
||||
)
|
||||
|
||||
title = f"[toolchain-handler] 工具链事件处理失败: {task_id}"
|
||||
text = (
|
||||
f"任务 {task_id} 验证失败\n\n"
|
||||
f"事件类型: {event_type or '未知'}\n"
|
||||
f"事件详情:\n{event_details or ' (无)'}\n\n"
|
||||
f"失败原因: {reason}\n"
|
||||
f"证据: {evidence}\n\n"
|
||||
f"黑板任务: http://localhost:8083/ → 项目 _toolchain → 任务 {task_id}\n\n"
|
||||
f"行动指引: {action_hint}"
|
||||
)
|
||||
|
||||
payload = json.dumps({
|
||||
"from": "daemon",
|
||||
"to": "pangtong-fujunshi",
|
||||
"title": title,
|
||||
"text": text,
|
||||
"type": "inform",
|
||||
}, ensure_ascii=False).encode("utf-8")
|
||||
|
||||
try:
|
||||
req = urllib.request.Request(
|
||||
"http://localhost:8083/api/mail",
|
||||
data=payload,
|
||||
headers={"Content-Type": "application/json"},
|
||||
)
|
||||
urllib.request.urlopen(req, timeout=5)
|
||||
logger.info("Toolchain %s: sent failure notification via Mail API", task_id)
|
||||
except Exception as e:
|
||||
logger.warning("Toolchain %s: failed to notify via Mail API: %s", task_id, e)
|
||||
Reference in New Issue
Block a user