sanguo_moziplus_v2/docs/design/v2.8-direction-notes.md

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 结构：从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束"：

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

# 你的任务
{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}

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

v2.9 的一部分：知识注入（复用 LLM Wiki）

不需要新建知识库。 LLM Wiki 已有 273 页 wiki-vault + 118 个 practices 页面，就是现成的 L3 知识层。

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

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 重写	~50 行	无
3	知识注入	spawner.py 新增 _inject_wiki_knowledge()	~30 行	NAS 挂载路径修正
4	Bootstrap 增强	bootstrap.py 支持 wiki knowledge 层	~20 行	#3

NAS 挂载路径问题

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

---

六、调研产出归档

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

文件	说明
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）

---

八、下一步

1. 🔜 Mail 独立（mail_handler.py）
2. 🔜 Prompt 进化（改 SPAWN_PROMPT_TEMPLATE）
3. 🔜 NAS 挂载路径修正
4. 🔜 知识注入（复用 LLM Wiki index.md 检索）
5. 🔜 Agent 进化（自主 claim + 间感知）
6. 🔜 Daemon 简化（退化为投递员）