docs: 新增 #16 知识注入设计（三层触发机制）
This commit is contained in:
cfdaily
@@ -0,0 +1,181 @@
|
||||
# #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`
|
||||
|
||||
**格式**（已有）：
|
||||
```markdown
|
||||
- [日期] 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：和 #05 四层架构的关系
|
||||
|
||||
| 层级 | 知识注入角色 | 本文档覆盖 |
|
||||
|------|------------|-----------|
|
||||
| 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 已有，不需要新的 |
|
||||
Reference in New Issue
Block a user