cfdaily
e83ad1de73
- 层级命名统一到 #11 体系（L0/L1/L2/L3），不再自创命名 - L0: 新增 wiki 查询铁律（做方案前先查 + 查不到记 gap） - L1: TOOLS.md 速查表（已完成）+ SOUL.md Red Flags（待实现） - L2: 三种 handler（task/mail/toolchain）各注入 WikiGuideSection - L3: wiki-query Skill（已部署，待确认 extraDirs 递归） - 运维层: gap 闭环 cron job（已有，需完善）
308 lines
12 KiB
Markdown
308 lines
12 KiB
Markdown
# #16 知识注入设计
|
||
|
||
> 状态：v2 设计中
|
||
> 作者：庞统
|
||
> 日期：2026-06-13（v1），2026-06-14（v2 对齐 #11 四层架构）
|
||
> 评审：待司马懿评审
|
||
|
||
## 一、问题
|
||
|
||
### 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 在关键决策点查。
|
||
|
||
### 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 注入 + L1 SOUL.md 行为引导 |
|
||
| Red Flags 反合理化 | Superpowers | 知识查询 Red Flags 表（L1 SOUL.md） |
|
||
| 经验内化 | Hermes | 经验→wiki-vault→下次查询 |
|
||
| 渐进式披露 | Hermes | 先查 summary，按需读全文 |
|
||
|
||
## 三、设计决策（对齐 #11 四层架构）
|
||
|
||
> **层级体系严格对齐 [#11](./11-context-layers-redesign.md)**，不自创命名。
|
||
|
||
### 总览
|
||
|
||
| #11 层级 | 知识注入角色 | 本设计覆盖 | 注入方式 |
|
||
|----------|------------|-----------|---------|
|
||
| **L0 铁律层** | "做方案前先查 wiki-vault" | ✅ D16-1 | Hook 每轮强制注入 |
|
||
| **L1 角色层** | TOOLS.md 知识库速查表 + SOUL.md Red Flags | ✅ D16-2 | Workspace 文件自动注入 |
|
||
| **L2 引擎注入层** | 三种 handler 各注入 WikiGuideSection | ✅ D16-3 | PromptComposer 拼装 |
|
||
| **L3 被动参考层** | wiki-query Skill 按需触发 | ✅ D16-4 | extraDirs Description 匹配 |
|
||
| 运维层 | gap 闭环 cron job | ✅ D16-5 | 不属于上下文分层 |
|
||
|
||
### D16-1：L0 铁律层 — 新增一条 wiki 查询铁律
|
||
|
||
L0 只放跨系统通用的、不可绕过的行为底线。wiki 查询铁律和 GATE 门控同级。
|
||
|
||
**新增铁律**：
|
||
|
||
```
|
||
<wiki-rule>
|
||
做方案前先查 wiki-vault，有 1% 相关就要查。查不到记 knowledge-gaps.md。
|
||
</wiki-rule>
|
||
```
|
||
|
||
**注入方式**：和 `<gate-rules>` / `<delegation-rule>` 并列，Hook 每轮强制注入。
|
||
|
||
**覆盖范围**：所有 Agent、所有场景（不限于 moziplus spawn 的子任务）。
|
||
|
||
### D16-2：L1 角色层 — TOOLS.md + SOUL.md
|
||
|
||
#### TOOLS.md（✅ 已完成）
|
||
|
||
各 Agent workspace 的 TOOLS.md 中已有「LLM Wiki 知识库」段，包含：
|
||
|
||
- 速查表（场景 → 怎么做 → 什么时候用）
|
||
- 检索原则（index.md → summary → grep → 整页读取，从便宜到昂贵）
|
||
- 目录结构（wiki-vault / practices / concepts / skills / ...）
|
||
- 铁律（做方案前先查、查不到记 gap）
|
||
|
||
#### SOUL.md Red Flags
|
||
|
||
在各 Agent 的 SOUL.md 中加入知识查询 Red Flags 表（和 Superpowers 一致）：
|
||
|
||
| Agent 的想法 | 反驳 |
|
||
|---|---|
|
||
| "这个我以前做过" | 知识库可能已更新，查一下确认 |
|
||
| "先做再说" | 做方案前查实践比做错了返工便宜 |
|
||
| "这个领域我熟悉" | 熟悉≠知道最新实践，wiki-vault 持续更新 |
|
||
| "查知识库浪费时间" | 重复踩坑浪费的时间远大于查询时间 |
|
||
|
||
### D16-3：L2 引擎注入层 — 三种 handler 各注入 WikiGuideSection
|
||
|
||
L2 是 BootstrapBuilder/PromptComposer 动态拼装的 prompt 段。当前有三种 handler，各有自己的 PromptSection 实现：
|
||
|
||
#### 当前 handler 结构
|
||
|
||
| Handler | Sections（priority） | 有 wiki 引导？ |
|
||
|---------|---------------------|--------------|
|
||
| **TaskHandler** | Context(10) → Prior(20) → RoleSkill(30) → API(40) → Constraints(50) | ❌ |
|
||
| **MailHandler** | Context(10) → API(40) → Constraints(50) | ❌ |
|
||
| **ToolchainHandler** | Context(10) → API(40) → Constraints(50) | ❌ |
|
||
|
||
#### 新增 WikiGuideSection（priority=60，PRIORITY_EXTENSION）
|
||
|
||
创建一个**通用 PromptSection**，三种 handler 的 `get_sections()` 都注入：
|
||
|
||
```python
|
||
# 可放在 prompt_composer.py 或独立文件，三种 handler 共用
|
||
|
||
class WikiGuideSection:
|
||
"""知识查询引导段 — 引导 Agent 在关键决策点查 wiki-vault。"""
|
||
|
||
name: str = "wiki_guide"
|
||
priority: int = 60 # PRIORITY_EXTENSION
|
||
|
||
WIKI_GUIDE = (
|
||
"## 知识查询引导\n"
|
||
"涉及方案设计、编码实现、故障排查时，先查 wiki-vault 相关实践：\n"
|
||
"- 路径：/Volumes/KnowledgeBase/wiki-vault/\n"
|
||
"- 速查：index.md → grep 关键词 → summary 字段 → 按需读全文\n"
|
||
"- 查不到：在 _meta/knowledge-gaps.md 记录"
|
||
)
|
||
|
||
def render(self, context: PromptContext) -> str:
|
||
return self.WIKI_GUIDE
|
||
|
||
def should_include(self, context: PromptContext) -> bool:
|
||
return True
|
||
```
|
||
|
||
#### 三种 handler 改动
|
||
|
||
每种 handler 的 `get_sections()` 末尾加 `WikiGuideSection()`：
|
||
|
||
```python
|
||
# TaskHandler
|
||
def get_sections(self) -> list:
|
||
return [
|
||
TaskContextSection(),
|
||
PriorOutputsSection(),
|
||
RoleSkillSection(),
|
||
TaskApiSection(),
|
||
TaskConstraintsSection(),
|
||
WikiGuideSection(), # ← 新增
|
||
]
|
||
|
||
# MailHandler
|
||
def get_sections(self) -> list:
|
||
return [
|
||
MailContextSection(),
|
||
MailApiSection(),
|
||
MailConstraintsSection(),
|
||
WikiGuideSection(), # ← 新增
|
||
]
|
||
|
||
# ToolchainHandler
|
||
def get_sections(self) -> list:
|
||
return [
|
||
ToolchainContextSection(),
|
||
ToolchainApiSection(),
|
||
ToolchainConstraintsSection(),
|
||
WikiGuideSection(), # ← 新增
|
||
]
|
||
```
|
||
|
||
#### 为什么三种 handler 都需要
|
||
|
||
- **TaskHandler**：executor 做方案/编码，最需要查实践
|
||
- **ToolchainHandler**：CI 失败排查、部署问题，有相关运维实践可参考
|
||
- **MailHandler**：request 类型回复杂问题时也可能需要查已有经验
|
||
|
||
#### token 开销
|
||
|
||
WikiGuideSection 固定 ~60 字（~30 tokens），对 L2 预算影响可忽略。
|
||
|
||
### D16-4：L3 被动参考层 — wiki-query Skill
|
||
|
||
#### 现状
|
||
|
||
`wiki-query` Skill 已部署在 `~/.sanguo_projects/sanguo_mozi/skills/wiki/wiki-query/SKILL.md`，description 包含中文触发词：
|
||
|
||
> 调查、研究、分析、优秀实践、最佳实践、经验、怎么做X、有没有X的经验、以前怎么处理的
|
||
|
||
#### 触发机制
|
||
|
||
Agent 通过 extraDirs 加载 Skill header（name + description），按 Description 匹配自主 `read` 全文。这是标准 L3 行为，和 #11 设计一致。
|
||
|
||
#### 待确认：extraDirs 子目录递归
|
||
|
||
wiki-query 在 `skills/wiki/wiki-query/` 子目录下。需确认 moziplus spawn 子 agent 时 extraDirs 是否递归扫描子目录。如果不递归，需要：
|
||
- 方案 A：把 wiki-query 移到 `skills/` 顶层
|
||
- 方案 B：配置 extraDirs 包含 `skills/wiki/` 子目录
|
||
|
||
### D16-5：知识 gap 记录 + 定时任务（运维层）
|
||
|
||
> 不属于上下文分层体系，是独立的运维流程。
|
||
|
||
#### gap 记录机制（已有基础设施）
|
||
|
||
- **位置**：`/Volumes/KnowledgeBase/wiki-vault/_meta/knowledge-gaps.md`
|
||
- **格式**：`- [日期] Agent名查"主题" → 待处理`
|
||
- **已有 20+ 条历史记录**，处理后标注 `→ 已建立 ✅`
|
||
|
||
wiki-query Skill 的 Step 5 已内置 gap 记录逻辑。
|
||
|
||
#### 定时任务（已有 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-6：和 #11 各层关系总结
|
||
|
||
| #11 层级 | #11 原始定义 | 知识注入贡献 | 本设计 |
|
||
|---------|------------|------------|--------|
|
||
| L0 铁律 | GATE 门控 + Delegation + 安全底线 | wiki 查询铁律 | ✅ D16-1 |
|
||
| L1 角色 | SOUL.md + AGENTS.md + TOOLS.md + MEMORY.md | TOOLS.md 速查表 + SOUL.md Red Flags | ✅ D16-2 |
|
||
| L2 引擎 | 任务上下文 + 角色操作规范 + 硬约束 | WikiGuideSection 通用段 | ✅ D16-3 |
|
||
| L3 参考 | A/B/C/D 类 Skill，靠 Description 触发 | wiki-query Skill | ✅ D16-4 |
|
||
| 运维 | — | gap 闭环 cron job | ✅ D16-5 |
|
||
|
||
### D16-7：为什么不做 PromptComposer 自动注入知识全文
|
||
|
||
1. **token 浪费**：每次任务都注入可能不相关的知识
|
||
2. **覆盖范围有限**：只影响 moziplus 子任务 Agent
|
||
3. **Agent 主动查询更精准**：知道自己缺什么知识，按需查询
|
||
|
||
## 四、改动清单
|
||
|
||
### 4.1 已完成 ✅
|
||
|
||
| 改动 | 文件 | 层级 | 说明 |
|
||
|------|------|------|------|
|
||
| TOOLS.md 知识库段 | 各 Agent workspace TOOLS.md | L1 | 速查表 + 检索原则 + 目录结构 + 铁律 |
|
||
| wiki-query Skill 部署 | `skills/wiki/wiki-query/SKILL.md` | L3 | 中文触发词 + 渐进式检索协议 |
|
||
| knowledge-gaps.md | `_meta/knowledge-gaps.md` | 运维 | 已有 20+ 条记录 |
|
||
| wiki-daily-update cron | cron job | 运维 | 每天 04:00，需完善处理逻辑 |
|
||
| pangtong-vault-sync cron | cron job | 运维 | 每天 05:00 |
|
||
|
||
### 4.2 待实现
|
||
|
||
| 改动 | 文件 | 层级 | 说明 |
|
||
|------|------|------|------|
|
||
| L0 wiki 铁律 | Hook 注入配置（`prependContext`） | L0 | 新增 `<wiki-rule>` 段 |
|
||
| SOUL.md Red Flags | 各 Agent workspace SOUL.md | L1 | 知识查询 Red Flags 表 |
|
||
| WikiGuideSection | `prompt_composer.py` 或独立文件 | L2 | 通用 PromptSection，三种 handler 共用 |
|
||
| TaskHandler 注入 | `task_handler.py` `get_sections()` | L2 | 末尾加 `WikiGuideSection()` |
|
||
| MailHandler 注入 | `mail_handler.py` `get_sections()` | L2 | 末尾加 `WikiGuideSection()` |
|
||
| ToolchainHandler 注入 | `toolchain_handler.py` `get_sections()` | L2 | 末尾加 `WikiGuideSection()` |
|
||
| extraDirs 递归确认 | moziplus spawn 配置 | L3 | 确认 wiki-query 子目录可被发现 |
|
||
| wiki-daily-update 完善 | cron job 脚本 | 运维 | gap 处理 + jsonl 经验提取 |
|
||
|
||
### 4.3 不做
|
||
|
||
| 项目 | 原因 |
|
||
|------|------|
|
||
| PromptComposer 知识全文注入 | token 浪费，Agent 主动查询更精准 |
|
||
| experiences 表 | wiki-vault 已覆盖，不重复建设 |
|
||
| 新 Skill（除 wiki-query 外） | wiki-query 已有，不需要新的 |
|
||
|
||
## 五、风险
|
||
|
||
| 风险 | 概率 | 缓解 |
|
||
|------|------|------|
|
||
| Agent 不主动查 wiki | 中 | L0 铁律强制 + L2 引导 + L3 Description 触发，三层保障 |
|
||
| wiki-query 在子目录不被 extraDirs 发现 | 中 | 确认后决定移顶层或配置子目录 |
|
||
| wiki-daily-update gap 处理质量不够 | 低 | 人工审核 + 逐步完善 |
|
||
| WikiGuideSection 增加 token | 低 | 固定 ~30 tokens，影响可忽略 |
|