sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5ac943b4a9534cd17b316aad3d6cecd0bbbe9b9d
sanguo_moziplus_v2/docs/design/v2.8-direction-notes.md
T
cfdaily 5ac943b4a9 auto-sync: 2026-05-27 08:52:17
2026-05-27 08:52:17 +08:00

13 KiB
Raw Blame History

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}

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

不告诉它具体步骤，只告诉它目标、工具、约束。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（决策、问题、建议）
  2. BootstrapBuilder 增强：_format_depends_on() 不只读 output 摘要，还读 comment_type=handoff
  3. API 无需改动：当前 POST /comments 已支持 comment_type 字段

对齐 PRD v3.0：这就是 "B3 共享意识" 的具体实现路径——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 重写（身份+目标+能力+约束+交接责任） ~60 行 无
3 Handoff 上下文 bootstrap.py _format_depends_on() 增强：读取 handoff comment ~30 行 #2
4 知识注入 spawner.py 新增 _inject_wiki_knowledge() ~30 行 NAS 挂载路径修正
5 Bootstrap 增强 bootstrap.py 支持 wiki knowledge 层 ~20 行 #4

NAS 挂载路径问题

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

六、工具评估

在讨论过程中评估了以下工具对 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）

九、下一步

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