auto-sync: 2026-05-27 09:08:55

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 知识层。