[moz] docs(§21): v2 补充 AI native 能力完整性（§12-§17） #101
@@ -569,7 +569,247 @@ issue_closed 走 auto-pass（和 review_merged 一样），纯通知不需要 ag
|
||||
|
||||
---
|
||||
|
||||
## §12. 不做的事
|
||||
## §12. AI Native 能力完整性（v2 补充）
|
||||
|
||||
> 本节确保 Gitea 替代黑板后，PRD-v3.0 的 AI native 能力不降级。
|
||||
> 对照 §01 四相循环实现 + spawner.py / ticker.py / operations.py 的实际代码逐项检查。
|
||||
|
||||
### 12.1 完整能力对照表
|
||||
|
||||
| # | AI native 能力 | 黑板实现 | Gitea Issue 对应 | 保留？ | §21 补充 |
|
||||
|---|-------------|---------|-----------------|-------|---------|
|
||||
| 1 | **Discussion 讨论** | spawner DISCUSSION_PROMPT_TEMPLATE + spawn_type=discussion + ticker 广播 | parent Issue 创建后 ticker 广播 spawn discussion prompt；Issue comment 是讨论空间 | ✅ | §13 |
|
||||
| 2 | **Agent 自建 sub** | agent POST /tasks {parent_task, must_haves} | agent POST Gitea /issues {title: "[repo][sub][parent #N] ..."} + assign 自己 | ✅ | §14 |
|
||||
| 3 | **@mention 通知** | comment mentions 字段 → mention_queue → ticker 扫描 → spawn 被@者 | Gitea Issue/PR comment @ → webhook issue_comment → daemon 解析 @ → spawn | ✅ | §15 |
|
||||
| 4 | **Round review** | _check_round_complete → parent sub 全终态 → spawn 庞统三问 | daemon 扫 task_state parent 下所有 sub 终态 → spawn 庞统 review | ✅ | §16 |
|
||||
| 5 | **Retry 上下文** | retry_count 字段 + _build_retry_context | task_state.retry_count + retry prompt（不变） | ✅ | 不需额外 |
|
||||
| 6 | **Handoff comment** | comment_type=handoff + ≥50 字符 | Issue/PR comment（无 type 区分，但 Boids 行为准则约束 agent 写实质内容） | ✅ | §17 |
|
||||
| 7 | **Outputs 产出物** | outputs 表 {agent, type, content_path, summary} | 分支 commit（代码/文档）+ Issue comment（摘要） | ✅ | 不需额外 |
|
||||
| 8 | **Depends_on 前序** | tasks.depends_on 字段 + PriorOutputsSection | Issue body `Depends: #N` + daemon 解析注入 | ✅ | §17 |
|
||||
| 9 | **Boids 行为准则** | DISCUSSION_PROMPT 中的 4 条准则 | discussion prompt 不变（Boids 准则在 prompt 中，与存储介质无关） | ✅ | §13 |
|
||||
| 10 | **Agent 自主涌现** | 无 assignee 的 parent task → ticker 广播 → agent 自主讨论/创建 sub | 无 assignee 的 parent Issue → ticker 广播 discussion → agent 自建 sub Issue | ✅ | §13/§14 |
|
||||
| 11 | **Guardrail 安全红线** | dispatcher check_task → violations → block | 不变（guardrail 查 task_state，不依赖黑板） | ✅ | 不需额外 |
|
||||
| 12 | **Classify outcome** | spawner _classify_outcome → done/failed/pending | 不变（classify 逻辑在 daemon 内部） | ✅ | 不需额外 |
|
||||
| 13 | **Rebuttal** | review.py submit_rebuttal → @mention assignee + 回到 working | PR Review REQUEST_CHANGES → webhook → daemon 通知 agent | ✅ | 不需额外 |
|
||||
| 14 | **Checkpoints** | checkpoint_routes.py → approve/reject | PR Review（代码/方案审查统一走 PR Review） | ✅ | 不需额外 |
|
||||
|
||||
### 12.2 结论
|
||||
|
||||
**14 项 AI native 能力全部可保留。** 其中需要补充设计的是 5 项（§13-§17），其余沿用现有 daemon 逻辑不变。
|
||||
|
||||
---
|
||||
|
||||
## §13. Discussion 能力保留
|
||||
|
||||
### 13.1 设计
|
||||
|
||||
庞统创建 parent Issue（无 assignee）后，触发 discussion：
|
||||
|
||||
```
|
||||
庞统创建 parent Issue → webhook: issues/assigned（或 ticker 发现 pending 无 assignee）
|
||||
→ daemon 检测：无 assignee = 广播讨论
|
||||
→ ticker 广播 spawn 所有 agent（spawn_type=discussion）
|
||||
→ 每个 agent 收到 DISCUSSION_PROMPT_TEMPLATE
|
||||
```
|
||||
|
||||
agent 收到的 discussion prompt（与现有 spawner.py DISCUSSION_PROMPT_TEMPLATE 一致）：
|
||||
|
||||
```
|
||||
你被 spawn 来参与 Gitea Issue 讨论。这是一个四相循环的讨论环节。
|
||||
|
||||
## 你的任务
|
||||
{parent Issue body — goal}
|
||||
|
||||
## Issue API（Gitea）
|
||||
你可以随时：
|
||||
- 读 Issue 详情+comments：GET /repos/{repo}/issues/{N}
|
||||
- 写 comment：POST /repos/{repo}/issues/{N}/comments
|
||||
body: {"body": "内容(@agent-id 自动路由)"}
|
||||
- 创建 sub Issue：POST /repos/{repo}/issues
|
||||
title: "[repo][sub][parent #{N}] 任务名"
|
||||
body: "Parent: #{N}\n## 任务\n..."
|
||||
assignees: ["自己"]
|
||||
|
||||
## 行为准则
|
||||
1. 你是自主的。读 Issue、思考、行动，不要等指令。
|
||||
2. 不重复别人的工作。动手前先读 Issue comments 看谁在做什么（Separation）。
|
||||
3. 保持方向对齐。你的产出方向和 parent goal 对齐，不确定时 @pangtong-fujunshi（Alignment）。
|
||||
4. 产出可共享。产出写入 Issue comment，让其他人能看到你的成果（Cohesion）。
|
||||
5. 不越界。安全红线不要碰，超出能力的 @ 庞统升级（Boundary）。
|
||||
6. 随时讨论。执行过程中需要协作时 @ 对应 Agent，讨论是灵活的不是固定阶段的。
|
||||
|
||||
## 讨论完成后
|
||||
- 如果讨论收敛到可执行的任务，直接创建 sub Issue
|
||||
- 如果有分歧或不确定，在 Issue 上 comment @ 庞统裁决
|
||||
- 如果庞统在 parent Issue 中 @ 了你认领特定任务，优先响应
|
||||
```
|
||||
|
||||
**与现有实现差异**：API 从黑板 API（localhost:8083）改为 Gitea API。行为准则（Boids 四条）完全不变。
|
||||
|
||||
### 13.2 庞统初始引导
|
||||
|
||||
庞统创建 parent Issue 时，可以在 Issue body 或 comment 中 @ 特定 agent 引导认领：
|
||||
|
||||
```
|
||||
Issue body:
|
||||
## 任务
|
||||
做一个双均线量化策略...
|
||||
|
||||
## 建议分工
|
||||
@zhangfei-dev 你来认领策略编码
|
||||
@zhaoyun-data 你来认领数据准备
|
||||
其他需要补充的请大家自主认领
|
||||
```
|
||||
|
||||
但庞统不需要知道全部——关羽可能发现需要风控，自己创建 sub 去做。司马懿可能发现需要测试，自己创建 sub。**这是涌现，不是分配。**
|
||||
|
||||
---
|
||||
|
||||
## §14. Agent 自建 sub Issue 模式
|
||||
|
||||
### 14.1 设计
|
||||
|
||||
替代当前的 claim 竞争模式。每个 agent 自己创建 sub Issue + assign 自己。
|
||||
|
||||
**标题格式**：
|
||||
```
|
||||
[quant][sub][parent #100] 策略编码
|
||||
```
|
||||
- `[quant]` — 项目代号
|
||||
- `[sub]` — 标记为 sub Issue
|
||||
- `[parent #100]` — parent Issue 编号（Gitea 自动渲染 #100 为链接）
|
||||
- 后面是人类可读的任务描述
|
||||
|
||||
**Sub Issue body**：
|
||||
```markdown
|
||||
Parent: #100
|
||||
|
||||
## 任务
|
||||
从 parent Issue 继承的具体任务描述
|
||||
|
||||
## 验收标准
|
||||
...
|
||||
```
|
||||
|
||||
Gitea 的 Issue reference 功能会自动在 parent Issue #100 上显示 "Referenced by #101"。
|
||||
|
||||
### 14.2 不需要 claim 竞争
|
||||
|
||||
当前黑板的 claim 模式（CAS 原子操作）是为了防止两个 agent 认领同一个 task。
|
||||
|
||||
在 Gitea Issue 模式下，每个 agent 创建自己的 sub Issue——**不存在竞争**。各创建各的，各 assign 各的。
|
||||
|
||||
**重复不怕**：如果关羽和张飞创建了内容重叠的 sub Issue，庞统在 round review 时引导两人统一看法。这不是错误，是讨论的契机。**不做严谨工作流，做 AI 生态。**
|
||||
|
||||
### 14.3 daemon 内部 parent/sub 映射
|
||||
|
||||
daemon 维护 parent/sub 层级（用于 round review 检测）：
|
||||
|
||||
```sql
|
||||
-- task_state 表（§20 设计）
|
||||
CREATE TABLE task_state (
|
||||
issue_number INTEGER,
|
||||
repo TEXT,
|
||||
parent_issue INTEGER, -- 新增：parent Issue 编号
|
||||
status TEXT DEFAULT 'pending',
|
||||
...
|
||||
);
|
||||
```
|
||||
|
||||
daemon 监听 Issue 创建 webhook → 解析标题中的 `[parent #N]` → 记录 parent_issue。
|
||||
|
||||
⚠️ **需同步更新 §20 task_state DDL** 新增 `parent_issue INTEGER` 列。
|
||||
|
||||
---
|
||||
|
||||
## §15. @mention 通知迁移
|
||||
|
||||
### 15.1 当前实现
|
||||
|
||||
```
|
||||
agent 写 comment → mentions 字段 → mention_queue 表 → ticker 扫描 → spawn 被@者
|
||||
```
|
||||
|
||||
### 15.2 Gitea 迁移
|
||||
|
||||
```
|
||||
agent 写 Issue/PR comment → webhook: issue_comment/created → daemon 解析 @ → spawn 被@者
|
||||
```
|
||||
|
||||
**mention_queue 表保留**，但数据来源改为 webhook payload。daemon 收到 issue_comment webhook 后：
|
||||
1. 正则提取 comment body 中的 `@(
|
||||
[-
|
||||
]*)`
|
||||
2. 写入 mention_queue
|
||||
3. ticker 消费 mention_queue → spawn 被@者
|
||||
|
||||
复用现有 mention_utils.py 的 extract_mentions 逻辑（§25 已实现）。
|
||||
|
||||
---
|
||||
|
||||
## §16. Round Review 迁移
|
||||
|
||||
### 16.1 当前实现
|
||||
|
||||
ticker._check_round_complete：
|
||||
1. 扫描所有 parent task
|
||||
2. 检查 sub task 是否全部终态
|
||||
3. spawn 庞统 review（三问框架）
|
||||
|
||||
### 16.2 Gitea 迁移
|
||||
|
||||
ticker._check_round_complete 改为：
|
||||
1. 扫描 task_state 中 parent_issue IS NOT NULL（替代原 `SELECT DISTINCT parent_task FROM tasks`，语义不变——都是找有子任务的 parent）
|
||||
2. 找到所有 parent_issue 相同的 sub Issue
|
||||
3. 检查 sub Issue 是否全部终态（通过 task_state.status）
|
||||
4. 全部终态 → spawn 庞统 review
|
||||
|
||||
**庞统三问 prompt 不变**：
|
||||
```
|
||||
1. Goal 还清晰吗？（是否有 goal drift）
|
||||
2. 成果物覆盖 goal 了吗？（逐条检查验收标准）
|
||||
3. 下一轮需要做什么？（创建新 sub / 标记完成 / 调整方向）
|
||||
```
|
||||
|
||||
庞统通过 Gitea API 读 parent Issue body（goal）+ 所有 sub Issue 的 comments/outputs → 做评估。
|
||||
|
||||
---
|
||||
|
||||
## §17. 无缝接续机制完整迁移
|
||||
|
||||
### 17.1 handoff comment
|
||||
|
||||
当前：comment_type=handoff + ≥50 字符
|
||||
|
||||
Gitea：所有 Issue/PR comment 都是天然的 handoff。Boids 行为准则约束 agent 写实质内容。不强制 ≥50 字符——用 Boids 准则引导比硬阈值更 AI native。
|
||||
|
||||
### 17.2 depends_on 前序引用
|
||||
|
||||
当前：tasks.depends_on 字段 + PriorOutputsSection
|
||||
|
||||
Gitea：Issue body 中 `Depends: #N`。daemon 解析 → 读前序 Issue 的 comments（含 Action Report）→ 注入 prompt。
|
||||
|
||||
### 17.3 retry 上下文
|
||||
|
||||
current：retry_count 字段 + _build_retry_context
|
||||
|
||||
Gitea：task_state.retry_count（不变，daemon 内部）。retry prompt 中加入前序 Issue/PR 链接供 agent 参考。
|
||||
|
||||
### 17.4 状态转换流转
|
||||
|
||||
agent 完成后的状态转换（working → review → done）全部由 daemon 内部管理。agent 不需要手动 POST status。daemon 通过以下信号自动感知：
|
||||
|
||||
| 信号 | 来源 | 触发 |
|
||||
|------|------|------|
|
||||
| agent 创建 sub Issue | webhook: issues/opened | sub status=pending → dispatch |
|
||||
| agent 创建 PR | webhook: pull_request/opened | sub status → review |
|
||||
| PR Review 提交 | webhook: pull_request_review | review 结果 → done 或 back to working |
|
||||
| PR merge | webhook: pull_request/closed(merged) | sub status → done + Issue auto-close |
|
||||
| agent Issue comment | webhook: issue_comment/created | 检查是否为 Action Report → 终态检测 |
|
||||
|
||||
---
|
||||
|
||||
## §18. 不做的事
|
||||
|
||||
| 不做 | 理由 |
|
||||
|------|------|
|
||||
|
||||
Reference in New Issue
Block a user