From 0f00c05e2a719b455c58676ae4485989e7769cd0 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 27 May 2026 09:08:55 +0800 Subject: [PATCH] auto-sync: 2026-05-27 09:08:55 --- docs/design/v2.8-direction-notes.md | 69 +++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/design/v2.8-direction-notes.md b/docs/design/v2.8-direction-notes.md index 765a097..d52ca97 100644 --- a/docs/design/v2.8-direction-notes.md +++ b/docs/design/v2.8-direction-notes.md @@ -143,6 +143,75 @@ POST /api/projects/{pid}/tasks/{id}/comments {"comment_type": "handoff"} **对齐 PRD v3.0**：这就是 "B3 共享意识" 的具体实现路径——Agent 自己写交接 + 黑板作为共享空间。 +**⚠️ 重要发现：原始设计 architecture-v2.6 已有完整的 Handoff 设计** + +`architecture-v2.6.md` 中课题2 + 课题4 已设计了完整的 Handoff 体系，当前 v2.8 方向和原始设计完全对齐，没有冲突。已实现的部分： + +| 组件 | 原始设计状态 | 实现状态 | +|------|------------|----------| +| `comments` 表 `comment_type` 枚举含 `handoff` | ✅ 已设计 | ✅ 已实现（db.py） | +| `GET /comments?comment_type=handoff` API | ✅ 已设计 | ✅ 已实现（blackboard_routes.py） | +| `blackboard.py comment --type handoff` CLI | ✅ 已设计 | ✅ 已实现 | +| `handoff.schema.json`（completed + artifacts 必填） | ✅ 已设计 | ❌ 未实现 | +| `executor.md` 步骤5：写 Handoff Comment | ✅ 已设计 | ❌ 未实现（executor.md 不存在） | +| `executor.md` 前序信息：读 Handoff Comment | ✅ 已设计 | ❌ 未实现 | +| 三层约束体系（Schema 校验 + Skill 引导 + L1 截取） | ✅ 已设计 | ❌ 未实现 | + +**v2.8 vs 原始设计的差异**： + +| 维度 | 原始设计（v2.6 课题4） | v2.8 新方案 | +|------|----------------------|------------| +| Prompt 注入方式 | `executor.md` 模板（固定步骤） | 身份+能力+约束（自主决策） | +| Handoff 写入方式 | `blackboard.py CLI --handoff` + Schema 校验 | API 调用 + Prompt 约束 | +| Handoff 格式 | 结构化 JSON（completed + artifacts + remaining + next_steps） | 自由文本（决策/权衡/坑/建议），≤500 字 | +| 上下文传递 | Opal-Bridge Fidelity 三档（无损/摘要/混合） | LLM Wiki grep summary（第 1 级） | + +**关键差异**：原始设计用 Schema 强约束 handoff 格式（必填 completed + artifacts），v2.8 方向倾向于更灵活的自由文本。这两个可以合并——**保留 Schema 作为可选结构化字段，同时允许自由文本 body**。 + +### 司马懿评审问题的优秀实践参考 + +#### 问题 1：Agent 自主决策但不知道该干什么 + +**原始设计已覆盖**：architecture-v2.6 课题4 的四层上下文架构： +- L0 铁律（不变的安全红线） +- L1 角色身份（SOUL.md） +- L2 引擎注入（任务上下文 + API 列表 + 约束） +- L3 被动参考（Skill description + 知识注入） + +**v2.8 的做法**：把 L2 从固定步骤改为能力+约束声明。Agent 自己决定步骤，但 L0+L2 的约束保证它不会跑偏。 + +**验证方法**（司马懿建议）：v2.9 上线后跑 5 个测试 task，观察 Agent 行为。 + +#### 问题 2：Agent 偏离轨道（防偏离） + +**原始设计已覆盖**：architecture-v2.6 §防偏离三防线： +1. **每轮重新注入目标** → L2 引擎注入任务上下文 +2. **不信任 Agent 自述** → Output Guard + Scope Guard（L1 验证脚本 + L2 AI 审查） +3. **Runaway Guard** → tasks 表 `max_ticks` 字段（默认 100），超限自动暂停 + +**OpenAI Agents SDK 参考**（wiki-vault 已蒸馏）：Guardrail 分三层： +- 输入 Guardrail：便宜快速模型预检 +- 输出 Guardrail：最终产出检查 +- 工具 Guardrail：每次函数调用前后检查 + +**v2.8 对齐**：Daemon 侧的 guardrail 不随 Agent 自主度增加而削弱。Runaway Guard 在 v2.7 中未实现，v2.9 可以补上。 + +#### 问题 3：确保 Agent 写了 handoff + +**两个层面**： +1. **Prompt 约束**（软）：告诉 Agent 必须写 +2. **Review 检查**（硬）：review 流程中检查是否有 handoff comment +3. **Schema 校验**（原始设计）：`handoff.schema.json` 校验必填字段 + +**建议**：三层都用——Prompt 告诉它写，Schema 校验格式，Review 检查存在。 + +#### 问题 4：OpenAI Swarm / AutoGen / ReAct（司马懿建议补充调研） + +**当前结论**：这三个是次要参考，不影响核心方向。 +- **OpenAI Swarm**：已通过 openai-agents-sdk 调研覆盖（wiki-vault 有蒸馏）。Handoff vs Agents-as-Tools 的选择对我们有参考 +- **AutoGen**：多 Agent 对话协作，和我们的黑板模式不同方向（对话式 vs 黑板式） +- **ReAct**：思考-行动循环，和 v2.8 的 "Agent 自主读黑板→想→干→写回" 本质相同 + ### v2.9 的一部分：知识注入（复用 LLM Wiki） **不需要新建知识库。** LLM Wiki 已有 273 页 wiki-vault + 118 个 practices 页面，就是现成的 L3 知识层。