sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily 610bb8a3fb auto-sync: 2026-05-27 22:39:44

2026-05-27 22:39:44 +08:00

22 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"}
⚠️ 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 怎么拿	被动接收注入	主动读黑板

具体改动：

Prompt 约束新增：完成任务后必须写 handoff comment（决策、问题、建议），不超过 500 字，只写决策/权衡/坑/建议，不写实现细节
BootstrapBuilder 增强：_format_depends_on() 不只读 output 摘要，还读 comment_type=handoff
API 扩展：GET /comments 需支持 comment_type=handoff 查询参数（当前可能不支持，需确认并补充）
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 §防偏离三防线：

每轮重新注入目标 → L2 引擎注入任务上下文
不信任 Agent 自述 → Output Guard + Scope Guard（L1 验证脚本 + L2 AI 审查）
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

两个层面：

Prompt 约束（软）：告诉 Agent 必须写
Review 检查（硬）：review 流程中检查是否有 handoff comment
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。

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 + 推送机制

22 KiB Raw Blame History Unescape Escape