Merge PR #101: [moz] docs(§21): v2 补充 AI native 能力完整性

2026-06-20 11:17:00 +00:00
parent 6a73d6d6c7 b384433c80
commit 2e2edd2b00
1 changed files with 241 additions and 1 deletions
@@ -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. 不做的事

 | 不做 | 理由 |
 |------|------|