From 31028a7e6f5c4253483f42476557aa441dda4302 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 20 Jun 2026 18:53:31 +0800 Subject: [PATCH 1/3] =?UTF-8?q?[moz]=20docs(=C2=A721):=20v2=20=E8=A1=A5?= =?UTF-8?q?=E5=85=85=20=C2=A712-=C2=A717=20AI=20native=20=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=E5=AE=8C=E6=95=B4=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §12: 14 项 AI native 能力对照表（全部可保留） §13: Discussion 能力保留（DISCUSSION_PROMPT + Boids 四条不变） §14: Agent 自建 sub Issue 模式（标题 [repo][sub][parent #N]） - 替代 claim 竞争：各 agent 自建 sub + assign 自己 - 重复不怕：庞统 round review 引导统一 §15: @mention 通知迁移（mention_queue 数据源改为 webhook） §16: Round review 迁移（task_state parent_issue 映射） §17: 无缝接续完整迁移（handoff/depends_on/retry/状态转换） --- docs/design/21-unified-toolchain-design.md | 238 +++++++++++++++++++++ 1 file changed, 238 insertions(+) diff --git a/docs/design/21-unified-toolchain-design.md b/docs/design/21-unified-toolchain-design.md index 0d789ae..1f6af7e 100644 --- a/docs/design/21-unified-toolchain-design.md +++ b/docs/design/21-unified-toolchain-design.md @@ -577,4 +577,242 @@ issue_closed 走 auto-pass（和 review_merged 一样），纯通知不需要 ag | 不改 mail | mail 职责不变 | | 不改 dispatcher/ticker 核心逻辑 | 调度逻辑不变（§20 Phase 1 的 dispatcher SQL 迁移是前置工作） | | 不做前端改造 | 后续独立设计 | + +--- + +## §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。 + +--- + +## §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 非空的记录 +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 → 终态检测 | | 不改 experiences/checkpoints/decisions 表 | 执行面表保留在 daemon | From dceddeff45c786d672f1cc8140d032c1d9f8bbc6 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 20 Jun 2026 18:58:26 +0800 Subject: [PATCH 2/3] =?UTF-8?q?[moz]=20docs(=C2=A721):=20fix=20M1=20=C2=A7?= =?UTF-8?q?11/=C2=A712=20=E8=A1=A8=E6=A0=BC=E6=88=AA=E6=96=AD=20+=20?= =?UTF-8?q?=E9=87=8D=E7=BC=96=E5=8F=B7=20=C2=A718=20=E4=B8=8D=E5=81=9A?= =?UTF-8?q?=E7=9A=84=E4=BA=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/21-unified-toolchain-design.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/design/21-unified-toolchain-design.md b/docs/design/21-unified-toolchain-design.md index 1f6af7e..a4fb818 100644 --- a/docs/design/21-unified-toolchain-design.md +++ b/docs/design/21-unified-toolchain-design.md @@ -569,17 +569,6 @@ issue_closed 走 auto-pass（和 review_merged 一样），纯通知不需要 ag --- -## §12. 不做的事 - -| 不做 | 理由 | -|------|------| -| 不改 task handler | task 流程不变（§20 设计中的 task 逐步迁移到 Issue 是后续工作） | -| 不改 mail | mail 职责不变 | -| 不改 dispatcher/ticker 核心逻辑 | 调度逻辑不变（§20 Phase 1 的 dispatcher SQL 迁移是前置工作） | -| 不做前端改造 | 后续独立设计 | - ---- - ## §12. AI Native 能力完整性（v2 补充） > 本节确保 Gitea 替代黑板后，PRD-v3.0 的 AI native 能力不降级。 @@ -815,4 +804,15 @@ agent 完成后的状态转换（working → review → done）全部由 daemon | 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. 不做的事 + +| 不做 | 理由 | +|------|------| +| 不改 task handler | task 流程不变（§20 设计中的 task 逐步迁移到 Issue 是后续工作） | +| 不改 mail | mail 职责不变 | +| 不改 dispatcher/ticker 核心逻辑 | 调度逻辑不变（§20 Phase 1 的 dispatcher SQL 迁移是前置工作） | +| 不做前端改造 | 后续独立设计 | | 不改 experiences/checkpoints/decisions 表 | 执行面表保留在 daemon | From b384433c806cf460f36881979960705e32ca2a17 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 20 Jun 2026 18:59:18 +0800 Subject: [PATCH 3/3] =?UTF-8?q?[moz]=20docs(=C2=A721):=20fix=20=E5=A7=9C?= =?UTF-8?q?=E7=BB=B4=20S1=EF=BC=88=E5=90=8C=E6=AD=A5=20=C2=A720=20task=5Fs?= =?UTF-8?q?tate=20DDL=EF=BC=89+=20S2=EF=BC=88SQL=20=E8=AF=AD=E4=B9=89?= =?UTF-8?q?=E5=8F=98=E5=8C=96=E8=AF=B4=E6=98=8E=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/21-unified-toolchain-design.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/design/21-unified-toolchain-design.md b/docs/design/21-unified-toolchain-design.md index a4fb818..3da4e2a 100644 --- a/docs/design/21-unified-toolchain-design.md +++ b/docs/design/21-unified-toolchain-design.md @@ -718,6 +718,8 @@ CREATE TABLE task_state ( daemon 监听 Issue 创建 webhook → 解析标题中的 `[parent #N]` → 记录 parent_issue。 +⚠️ **需同步更新 §20 task_state DDL** 新增 `parent_issue INTEGER` 列。 + --- ## §15. @mention 通知迁移 @@ -757,7 +759,7 @@ ticker._check_round_complete： ### 16.2 Gitea 迁移 ticker._check_round_complete 改为： -1. 扫描 task_state 中 parent_issue 非空的记录 +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