sanguo_moziplus_v2/docs/design/16-knowledge-injection.md

#16 知识注入设计

状态：设计中 作者：庞统 日期：2026-06-13 评审：待司马懿评审

一、问题

1.1 现状

Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已有知识库（wiki-vault）。导致：

1. 重复调研：赵云查过的数据清洗经验，张飞又从头调研一遍
2. 重复踩坑：wiki-vault 里已有"vnpy load_bar 需要显式指定 end=None"的实践，张飞还是踩了
3. 方案质量低：做方案时纯靠推理，不查已有的优秀实践
4. 知识 gap 无人管：查不到相关知识时没记录，下次还是查不到

1.2 根因

不是没有知识库（wiki-vault 有 50+ practices 页面），也不是没有检索能力（wiki-query Skill 已存在）。

根因是注入时机：Agent 不知道什么时候该查、没有强制机制让 Agent 在关键决策点查。

现有设计（#11 四层架构）把知识注入放在 L3-4（被动参考层），但没有定义"什么时候触发被动参考"。

1.3 目标

1. Agent 在关键决策点主动查询 wiki-vault
2. 查不到相关知识时自动记录 knowledge gap
3. 定时任务处理 gap + 总结经验，持续丰富 wiki-vault
4. 不增加 prompt token 负担（不自动注入知识全文，只引导查询）

二、调研

2.1 Superpowers：强制 Skill 检查（最有效）

核心设计：session-start hook 注入铁律级指令——

"If you think there is even a 1% chance a skill might apply, you ABSOLUTELY MUST invoke the skill. This is not negotiable."

配合 Red Flags 表防止 Agent 自合理化跳过：

Agent 的想法	Red Flag 驳回
"这个问题很简单"	简单问题也需要查实践
"我需要更多上下文"	Skill 检查在澄清问题之前
"先看看代码"	Skill 告诉你怎么看代码
"我记住了这个 Skill"	Skill 会更新，重新读

为什么有效：不靠 Agent "想起来"，靠铁律强制。Skill 触发在任何响应之前。

2.2 Hermes：经验闭环 + Session Search

经验闭环：完成复杂任务（5+ tool calls）→ 自动创建 Skill → 下次自然触发。

Session Search：系统提示注入——"当用户提及过去内容时，主动搜索而非要求用户重复"。

为什么有效：不是"知识查询"而是"行为内化"——经验变成 Skill，Skill 有 description 触发词。

2.3 结论

综合两个项目的优势：

设计点	来源	我们的做法
铁律级强制	Superpowers	L0 Hook + SOUL.md 双重注入
Red Flags 反合理化	Superpowers	知识查询 Red Flags 表
经验内化	Hermes	经验→wiki-vault→下次查询
渐进式披露	Hermes	先查 summary，按需读全文

三、设计决策

D16-1：三层触发机制（核心设计）

不是在引擎层面自动注入知识全文（token 浪费），而是通过三层机制让 Agent 主动查询：

层级	机制	内容	覆盖范围
L0 铁律	SOUL.md 行为引导	"做方案前先查 wiki-vault，有 1% 相关就要查"	所有 Agent、所有场景
L1 Skill 路由	wiki-query Skill description	触发词：调查、研究、分析、优秀实践、经验、怎么做X	Agent 匹配到触发词时
L2 知识 gap 闭环	定时任务	查不到→记 gap→每天处理→写入 wiki-vault	持续改进

为什么不做 PromptComposer 自动注入：

1. 自动注入 token 浪费（每次任务都注入可能不相关的知识）
2. 覆盖范围有限（只影响 moziplus 子任务 Agent）
3. Agent 主动查询更精准（知道自己缺什么知识）

D16-2：知识查询 Red Flags（防止跳过）

在 SOUL.md 中加入 Red Flags 表，和 Superpowers 一致：

Agent 的想法	反驳
"这个我以前做过"	知识库可能已更新，查一下确认
"先做再说"	做方案前查实践比做错了返工便宜
"这个领域我熟悉"	熟悉≠知道最新实践，wiki-vault 持续更新
"查知识库浪费时间"	重复踩坑浪费的时间远大于查询时间

D16-3：知识 gap 记录机制

触发：Agent 在 wiki-vault 中查不到相关知识时。

记录位置：/Volumes/KnowledgeBase/wiki-vault/_meta/knowledge-gaps.md

格式（已有）：

- [日期] Agent名查"主题" → 待处理

已有基础设施：

• knowledge-gaps.md 已存在，有 20+ 条历史记录
• 格式已定义，处理后会标注 → 已建立 ✅

D16-4：定时任务流程（已有 cron 基础）

任务	时间	内容	状态
wiki-daily-update	每天 04:00	处理 knowledge gaps + 当天经验总结 → 写入 wiki-vault	✅ 已有 cron，需完善
pangtong-vault-sync	每天 05:00	同步 wiki-vault 到 agent workspace	✅ 已有

wiki-daily-update 完善内容：

1. 读取 knowledge-gaps.md 中"待处理"条目
2. 对每个 gap：搜索 knowledge_base 是否有相关源码/文档 → 有则提炼写入 wiki-vault
3. 搜索最近一天的 jsonl 日志，提取有价值的经验
4. 新建或更新 wiki-vault 页面
5. 更新 knowledge-gaps.md（标记为"已建立 ✅"或"无KB内容，跳过"）

D16-5：wiki-vault 作为索引层

确认原则：wiki-vault 是索引层，不是详细内容存储。

• 查询先走 wiki-vault（practices/concepts/skills）
• 如果页面指向 knowledge_base 的详细内容，必须 follow 获取原文
• knowledge_base 的路径：/Volumes/KnowledgeBase/knowledge_base/

D16-6：和 #11 四层架构的关系

层级	知识注入角色	本文档覆盖
L0 铁律层	"做方案前先查 wiki-vault"	✅ D16-1 L0
L1 身份层	SOUL.md 中加入查询行为引导	✅ D16-1 L0 + D16-2
L2 引擎注入层	不做自动注入（Agent 主动查询更精准）	—
L3 被动参考层	wiki-query Skill 按需加载	✅ D16-1 L1
L4 检索层	wiki-vault grep/read + knowledge_base follow	✅ D16-5

和 #11 L3-4 的关系：#11 把知识注入放在 L3 被动参考层，本文档是 L3-4 的具体实现方案。

D16-7：和 topic6 经验沉淀的关系

	topic6（moziplus 内部）	本文档（知识注入）
范围	moziplus 引擎 spawn 的子任务	所有 Agent、所有场景
经验来源	黑板 decisions/reviews/comments	jsonl 日志 + knowledge gaps
载体	experiences 表（SQLite）	wiki-vault（Markdown）
关系	topic6 的经验最终汇入 wiki-vault	wiki-vault 是知识的 single source of truth

topic6 不急：因为 jsonl 日志中的经验也是知识来源之一，定时总结时会覆盖。topic6 可以在后续作为 moziplus 内部的额外经验来源。

四、改动清单

4.1 已完成 ✅

改动	文件	说明
TOOLS.md 更新	workspace-pangtong/TOOLS.md	新增「LLM Wiki 知识库」段：速查表、检索原则、铁律

4.2 待实现

改动	文件	说明
SOUL.md 行为引导	workspace-pangtong/SOUL.md	新增「知识查询」行为规则 + Red Flags
wiki-daily-update 完善	cron job	gap 处理 + 经验总结逻辑

4.3 不做

项目	原因
PromptComposer 知识注入	token 浪费，Agent 主动查询更精准
experiences 表	wiki-vault 已覆盖，不重复建设
新 Skill	wiki-query 已有，不需要新的