# v2.8 设计方向备忘

**日期**: 2026-05-27  
**作者**: 庞统  
**状态**: 持续讨论中，逐步完善  
**最后更新**: 2026-05-27 08:00（第二轮讨论结论更新）

---

## 一、核心方向：Daemon 退化 + Agent 进化

> **黑板是精髓，不是任何单个 Agent。** 所有 Agent 读黑板、想、行动、写回。Daemon 是投递员，不是决策者。

### 业界印证

| 系统 | 做法 | 关键点 |
|------|------|--------|
| **Claude Code Agent Teams** | Agent 自己 flock() claim 任务，Team Lead 只协调 | Agent 自己决定看什么、干什么 |
| **Hermes Kanban** | Agent 有 kanban_* 工具直接操作黑板 | 工具驱动，不是 prompt 指令驱动 |
| **PRD v3.0** | "黑板是唯一真相源，所有 Agent 读它、想、行动、写回结果" | 最激进：peer-to-peer 感知 |

### 当前 vs 未来

| 维度 | 当前（v2.7 实现） | 未来（AI Native） |
|------|------------------|-------------------|
| Daemon 角色 | 调度器 + 路由器 + 决策者 | 投递员 + 看护人 |
| Agent 角色 | 被动执行者（固定步骤 prompt） | 自主决策者（读黑板→想→干→写回） |
| 谁决定执行路径 | Daemon（if/else + YAML） | Agent（根据黑板信息自主判断） |
| Agent 间通信 | 无（Daemon 中央调度） | 黑板 comment + observation + @mention |

---

## 二、不做的事（明确排除）

### 1. 不做 Pipeline 框架

PipelineRouter / SingleStepPipeline / MultiStepPipeline / ParallelPipeline —— 不需要。

**原因**：各种执行模式（parallel/loop/saga/interactive）是执行路径的选择，不是代码层面的 Pipeline 类。Agent 自己根据黑板信息决定执行策略。

**已归档**：
- 调研报告：`docs/research/pipeline-architecture-research.md`
- Pipeline 设计 v1.0~v2.0：`docs/design/v2.8-pipeline-architecture.md`
- v2.8 task type 设计：`docs/design/v2.8-task-type-pipeline.md`

### 2. 不做黑板摘要注入

**原因**：Agent 已经有 API 能力读黑板全局状态。让 Agent 自己决定看什么，比系统预注入更 AI native。

**结论**：谁决定信息需求 = 谁在决策。注入方式是系统决定信息需求，Agent 自己读是 Agent 决定。后者更 AI native。

### 3. 不做 blackboard_* 工具封装（优先级低）

当前 curl + API 方式已经能用。工具封装是优化项（省 token、降出错率），不是必须项。

### 4. 不做 Skill 集群模板（和 Agent 自主决策矛盾）

知识管理体系 v1 设计里的 Skill 集群模板（feature-development / data-acquisition 等预设流程），和"Agent 自主决策"方向矛盾。Agent 应该自己根据黑板信息决定执行策略，不按预设模板走。

---

## 三、要做的事

### v2.8：Mail 独立（代码整理，不改功能）

Mail 是机械投递，不需要智能。当前 46 处 if/_mail 散落在三个文件（ticker 14 + dispatcher 23 + spawner 9），设计很差。

**做法**：
- 新建 `mail_handler.py`，集中 Mail 投递逻辑
- ticker/dispatcher/spawner 里的 Mail 方法标注废弃
- 不新建 Pipeline 框架，不搞 PipelineRouter
- 改动量：~100 行新建 + ~30 行调用替换

### v2.9：Prompt 进化（从固定步骤 → 自主决策）

**当前 prompt 的问题**：把 Agent 限制在固定步骤（标 working → 干活 → 写产出 → 标 review）。

**改 prompt 结构**：从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束 + 交接责任"：

```markdown
# 你的身份
你是张飞，编码先锋。擅长快速实现策略代码、回测脚本。

# 你的任务
{task_title}: {task_description}
类型: {task_type} | 风险: {risk_level}
必要条件: {must_haves}

# 你能做什么
通过 API 操作黑板（{api_base}）:
- 读任何任务详情: GET /api/projects/{pid}/tasks/{id}?expand=all
- 读所有活跃任务: GET /api/projects/{pid}/tasks
- 写产出: POST /api/projects/{pid}/tasks/{id}/outputs
- 写评论: POST /api/projects/{pid}/tasks/{id}/comments
- 写观察/风险: POST /api/projects/{pid}/tasks/{id}/observations
- 更新状态: POST /api/projects/{pid}/tasks/{id}/status
- 创建子任务: POST /api/projects/{pid}/tasks

# 约束
- 完成后必须写产出 + 标 review
- 失败了标 failed 并写明原因
- 遇到阻塞标 blocked
- 涉及数据删除/实盘交易 → 标 waiting_human 等人确认
- {guardrail_rules}

# 交接责任
完成后必须写交接文档（handoff comment），写入黑板：
- 你做了什么决策、为什么这么做
- 遇到什么问题、怎么解决的  
- 给下一个 Agent 的建议和注意事项
POST /api/projects/{pid}/tasks/{id}/comments  {"comment_type": "handoff"}
⚠️ handoff 不超过 500 字，只写决策/权衡/坑/建议，不写实现细节
```

**不告诉它具体步骤，只告诉它目标、工具、约束。Agent 自己决定怎么干。**

### v2.9 的一部分：Agent 间上下文传递（Handoff 设计）

> 灵感来源：MattPocock Handoff Skill（`mattpocock-skills/skills/in-progress/handoff/`）

**当前问题**：Agent 间上下文传递是 Daemon 中央摘要式——信息逐层丢失：

| 环节 | 丢失什么 |
|------|---------|
| Daemon 提取 output.md 摘要 | Agent 的思考过程、设计权衡、遇到的问题 |
| 注入到下一个 Agent prompt | 只有 `depends_on_outputs` 的 summary，不是完整上下文 |
| 新 Agent 拿到的 | 冰冷摘要，不知道前因后果 |

**Handoff 思路**：让产出 Agent 主动写交接文档，下一个 Agent 自主从黑板读取。

| | 当前（Daemon 提取） | Handoff 思路 |
|---|---|---|
| 谁决定传什么 | Daemon（机械摘要） | Agent 自己（知道什么重要） |
| 传什么 | output.md 的 summary | 上下文文档（决策、权衡、坑、建议） |
| 写到哪 | prompt 注入 | 黑板 comment（type=handoff） |
| 下一个 Agent 怎么拿 | 被动接收注入 | 主动读黑板 |

**具体改动**：
1. **Prompt 约束新增**：完成任务后必须写 handoff comment（决策、问题、建议），不超过 500 字，只写决策/权衡/坑/建议，不写实现细节
2. **BootstrapBuilder 增强**：`_format_depends_on()` 不只读 output 摘要，还读 `comment_type=handoff`
3. **API 扩展**：`GET /comments` 需支持 `comment_type=handoff` 查询参数（当前可能不支持，需确认并补充）
4. **Review 检查**：task review 阶段检查是否有 handoff comment，没有则提醒 Agent 补充

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

**做法**：Daemon spawn 前用 wiki-query 的检索原语（第 1 级：grep index.md），把匹配到的 summary 注入 prompt。

```python
def _inject_wiki_knowledge(self, task, prompt):
    """spawn 前从 wiki-vault 检索相关知识，注入 summary"""
    vault_path = Path(self.config.get("wiki_vault_path", ""))
    if not vault_path.exists():
        return prompt
    
    keywords = self._extract_keywords(task.title + " " + (task.description or ""))
    related = []
    for kw in keywords[:3]:
        result = subprocess.run(
            ["rg", "-i", kw, str(vault_path / "index.md")],
            capture_output=True, text=True, timeout=3
        )
        for line in result.stdout.strip().split("\n")[:2]:
            if not line or "[[" not in line:
                continue
            if "—" in line:
                summary = line.split("—", 1)[1].strip()[:100]
                page_name = line.split("[[")[1].split("]]")[0].split("|")[0]
                related.append(f"- [[{page_name}]] — {summary}")
    
    if related:
        prompt += "\n\n## 相关知识（来自 LLM Wiki）\n" + "\n".join(related[:5])
        prompt += "\n（如需详细信息，用 exec rg 读取完整页面）"
    return prompt
```

### v2.10+：Agent 进化

- Agent 自主 claim（从 Daemon 分配 → Agent 领活）
- Agent 间感知（comment + observation + @mention）
- Daemon 简化为纯投递员

---

## 四、关键洞察

### 1. 两层抽象：业务类型 vs 执行模式

| 层 | 定义 | 谁选 | 数量 | 例子 |
|----|------|------|------|------|
| **业务类型**（task_type） | 用户视角的"做什么" | 用户创建任务时选 | 无限扩展 | coding, review, data, deploy, research... |
| **执行模式** | 系统视角的"怎么跑" | Agent 自己决定 | 不需要预定义 | Agent 根据黑板信息自主判断 |

**业务类型无限扩展，执行模式不需要预定义。**

### 2. Agent 已经有黑板操作能力

API 已覆盖：读任务、写状态、写产出、写评论、写决策、写观察、创建任务、claim 任务。

**缺的不是工具，是 prompt 从"固定步骤"变成"自主决策"。**

### 3. 约束是硬的，执行是软的

| 类型 | 说明 | 实现方式 |
|------|------|---------|
| **硬约束** | guardrail 拦截、安全红线、审批要求 | Daemon 侧确定性代码 |
| **软执行** | 执行路径、步骤顺序、异常处理策略 | Agent 自主决策 |

### 4. 三个优秀实践的 prompt 结构对比

| 系统 | "能做什么"怎么表达 | "全局视角"怎么给 | 自主程度 |
|------|------------------|-----------------|---------|
| Claude Code | 工具列表（自动可用） | 文件系统自己读 | 高 |
| Hermes | kanban_* 工具集（环境变量激活） | kanban_show() 自己读 | 中 |
| 我们当前 | prompt 里写 curl 命令模板 | 不给全局 | 低 |

### 5. LLM Wiki 和知识管理的关系

| 知识管理体系 | 和本设计关系 | 说明 |
|------------|-------------|------|
| **LLM Wiki 三层架构** | ✅ 直接用 | 就是 L3 知识层，不需要另建 |
| **wiki-query skill** | ✅ 直接用 | 检索分级原语直接复用 |
| **wiki-ingest skill** | ✅ 后续用 | 新调研结果可以 ingest 进 wiki |
| **记忆分区（memory/ 四区）** | ⚠️ 正交 | Agent 自身记忆管理，和 prompt 进化独立 |
| **Skill 三级约束** | ⚠️ 正交 | 产出格式约束，和执行自主度独立 |
| **Skill 集群模板** | ❌ 不做 | 和 Agent 自主决策方向矛盾 |
| **四层加载机制** | ✅ 对齐 | ①固化=SOUL.md ②注册=SKILL.md ③注入=BootstrapBuilder ④检索=wiki-query |

---

## 五、具体改动清单

| # | 事项 | 改动文件 | 改动量 | 依赖 | 备注 |
|---|------|---------|--------|------|------|
| 1 | Mail 独立 | 新建 `mail_handler.py`，标注废弃 ticker/dispatcher/spawner | ~130 行 | 无 | |
| 2 | Prompt 进化 | `spawner.py` SPAWN_PROMPT_TEMPLATE 重写（身份+目标+能力+约束+交接责任） | ~60 行 | 无 | 替代原 executor.md 方案 |
| 3 | Handoff Schema | 新建 `schemas/handoff.schema.json`（原设计已完成，未实现） | ~20 行 | 无 | 原设计课题4 |
| 4 | Handoff 上下文 | `bootstrap.py` `_format_depends_on()` 增强：读取 handoff comment | ~30 行 | #2 | 原设计课题2 S-04 |
| 5 | Handoff API 确认 | `blackboard_routes.py` `GET /comments?comment_type=handoff` | 0 行 | 无 | ✅ 已实现，无需改动 |
| 6 | Review 检查 | review 流程增加 handoff 检查：无 handoff comment 则提醒 | ~20 行 | #2 | |
| 7 | Runaway Guard | `tasks` 表增加 `max_ticks` 字段 + Daemon tick 计数 + 超限暂停 | ~40 行 | 无 | 原设计 v2.6.9 未实现 |
| 8 | 知识注入 | `spawner.py` 新增 `_inject_wiki_knowledge()`（含 rg 检查 + grep fallback） | ~40 行 | NAS 挂载路径修正 | |
| 9 | Bootstrap 增强 | `bootstrap.py` `build()` 内部调用 wiki knowledge 层 | ~20 行 | #8 | |

### NAS 挂载路径问题

当前 `~/.obsidian-wiki/config` 配的是 `/Volumes/KnowledgeBase/wiki-vault/`，实际挂载在 `/Volumes/KnowledgeBase-1/wiki-vault/`。需要修正。

### ripgrep 依赖

知识注入用 `rg` 命令 grep index.md。需要检查 macOS 是否安装了 ripgrep，未安装时 fallback 到系统 `grep`。

### 废弃标注方式

Mail 独立时，ticker/dispatcher/spawner 中旧方法标注 `# TODO: remove after v2.8 - use mail_handler instead`，方便后续清理。

### Agent 自主度验证

v2.9 上线后，跑 5 个测试 task，观察不同 Agent（张飞/关羽/赵云）接到新 Prompt 后是否按预期自主决策。

---

## 六、工具评估

在讨论过程中评估了以下工具对 L3 知识注入和黑板设计的价值：

| 工具 | 评估结论 | 说明 |
|------|---------|------|
| **CodeGraph** | ❌ 对 L3 无用 | 索引代码 AST（符号/调用链），和知识文档检索无关。将来对编码 Agent 工具增强有用，但不是 L3 知识注入 |
| **Understand Anything** | ⚠️ 间接有用 | `/understand-knowledge` 可视化 LLM Wiki 知识图谱，适合人工维护 wiki 时探索关联。不适合运行时注入 |
| **MattPocock Handoff** | ✅ 直接有用 | 核心理念：Agent 主动写交接文档传递上下文。已采纳为 v2.9 Handoff 上下文设计的灵感来源 |

---

## 七、调研产出归档

本次讨论过程中产出的调研报告（不再作为设计依据，但保留参考价值）：

| 文件 | 说明 |
|------|------|
| `docs/research/pipeline-architecture-research.md` | 28场景 + 8业界实践 + 6设计模式调研 |
| `docs/design/v2.8-pipeline-architecture.md` | Pipeline 架构设计 v1.0~v2.0（已废弃） |
| `docs/design/v2.8-task-type-pipeline.md` | Task Type Pipeline 设计（已废弃） |
| `docs/design/v2.7.2-pipeline-refactor.md` | v2.7.2 Pipeline 分离设计（部分已完成） |

---

## 八、参考文件

| 文件 | 说明 |
|------|------|
| PRD v3.0 | `docs/PRD-v3.0.md` |
| architecture-v2.6 | `docs/design/architecture-v2.6.md` |
| 知识管理方案简述 | `~/.openclaw/sanguo_projects/sanguo_moziplus/docs/research/knowledge-management-brief.md` |
| 知识管理完整设计 | `~/.openclaw/sanguo_projects/sanguo_moziplus/docs/research/knowledge-management-v2.2.md` |
| LLM Wiki Skill | `~/.sanguo_projects/sanguo_mozi/skills/wiki/llm-wiki/SKILL.md` |
| wiki-query Skill | `~/.sanguo_projects/sanguo_mozi/skills/wiki/wiki-query/SKILL.md` |
| Wiki Vault | `/Volumes/KnowledgeBase-1/wiki-vault/`（273 页，118 practices） |

---

## 九、PRD v3.0 对齐分析（2026-05-27 第三轮讨论）

### v3.0 四相循环

| Phase | 谁参与 | AI 角色 | 当前实现状态 |
|-------|--------|---------|------------|
| Phase 1: 需求探索（苏格拉底对话） | 用户 + 庞统 | 帮用户发现需求 | ❌ 没有（用户直接创建任务） |
| Phase 2: 动态规划（AI 规划 + 挑战） | 庞统 + 司马懿 + 用户 | 规划者 + 质量守门人 | ❌ 没有（无活的执行方案） |
| Phase 3: 自主执行（Agent 协作群） | 所有 Agent + 庞统 | 执行者 + 指挥官 | ⚠️ 黑板 API 有，但 Agent 不主动读 |
| Phase 4: 主动汇报（AI 推送） | 庞统 → 用户 | 汇报者 | ❌ 没有 |

### v3.0 vs architecture-v2.6 的关键区别

| 维度 | v2.6（中间版本） | v3.0（AI Native） |
|------|-----------------|-------------------|
| 谁拆解任务 | 庞统拆解成子任务写黑板 | **庞统动态规划，活的执行方案** |
| 谁分配任务 | Daemon Router 按 task_type 匹配 | **庞统作为指挥官动态决定谁做** |
| Agent 角色 | 被动执行（领活→执行→写回） | **自主协作，主动发起协作** |
| 编排 | 确定性状态机 | **AI 感知全局→判断局势→决定下一步** |
| 庞统 | 交完 plan 退场 | **全程在线，持续指挥** |

### 对 executor.md 的影响

executor.md 应面向 **v3.0 目标**设计，在 **v2.7 实现**上工作：

- **流程步骤保留**（底层 ticker + dispatcher + spawner 短期不变）
- **步骤 2 从"理解任务"→"感知上下文"**：读黑板全局状态、读其他 Agent 产出、理解在协作中的位置
- **步骤 3 对齐 v3.0 自主协作**：不只是"执行任务"，而是主动发起协作、发现风险、甚至建议重新分配

### v2.8 的定位

v2.8 不是跳到 v3.0，而是在 v2.7 上**补齐关键缺失**，让 Agent 的行为模式从被动执行者朝自主协作者演进：

| v2.8 做什么 | 对齐 v3.0 哪个能力 |
|------------|-------------------|
| 新建 executor.md（感知上下文 + 自主执行） | Phase 3 自主协作 |
| 新建 reviewer.md（审查流程指引） | Phase 3 质量门禁 |
| handoff 注入（Agent 间传递上下文） | Phase 3 共享意识 |
| 知识注入（wiki summary） | Phase 3 能力增强 |

**v3.0 的 Phase 1（需求探索）和 Phase 2（动态规划）是更大的系统级改动，不在 v2.8 范围内。**

---

## 十、下一步

### v2.8 范围（Prompt 进化 + 补齐缺失）

| # | 事项 | 文件 | 对齐 v3.0 |
|---|------|------|----------|
| 1 | 新建 executor.md | `prompt_templates/executor.md` | Phase 3 自主协作 |
| 2 | 新建 reviewer.md | `prompt_templates/reviewer.md` | Phase 3 质量门禁 |
| 3 | 增强 `_build_api_section()` | `src/daemon/spawner.py` | Phase 3 共享意识 |
| 4 | 新建 handoff.schema.json | `schemas/handoff.schema.json` | Phase 3 共享意识 |
| 5 | 增强 `_format_depends_on()` 读 handoff | `src/daemon/bootstrap.py` | Phase 3 共享意识 |
| 6 | 知识注入 + 查询日志 | `spawner.py` + `bootstrap.py` | Phase 3 能力增强 |
| 7 | Mail 独立 | 新建 `mail_handler.py` | 代码整理 |
| 8 | review 前检查 output 非空 | `ticker.py` | Phase 3 质量门禁 |

### v3.0 后续（不在 v2.8 范围）

| Phase | 内容 | 前置条件 |
|-------|------|---------|
| Phase 1 | 需求探索（苏格拉底对话） | 庞统 Skill + 对话引擎 |
| Phase 2 | 动态规划（活的执行方案） | Phase 1 + 持续指挥 |
| Phase 3 完整 | 持续指挥官 + 自主 claim | Phase 2 + scope_declaration + Scope Guard |
| Phase 4 | 主动汇报（AI 推送） | Phase 3 + 推送机制 |