From e83ad1de73e42c3bf0298b76c9f735a6cec72e5a Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sun, 14 Jun 2026 10:22:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20#16=20=E7=9F=A5=E8=AF=86=E6=B3=A8?= =?UTF-8?q?=E5=85=A5=E8=AE=BE=E8=AE=A1=20v2=20=E2=80=94=20=E5=AF=B9?= =?UTF-8?q?=E9=BD=90=20#11=20=E5=9B=9B=E5=B1=82=E6=9E=B6=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 层级命名统一到 #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（已有，需完善） --- docs/design/16-knowledge-injection.md | 258 +++++++++++++++++++------- 1 file changed, 192 insertions(+), 66 deletions(-) diff --git a/docs/design/16-knowledge-injection.md b/docs/design/16-knowledge-injection.md index 2e96024..fadf619 100644 --- a/docs/design/16-knowledge-injection.md +++ b/docs/design/16-knowledge-injection.md @@ -1,8 +1,8 @@ # #16 知识注入设计 -> 状态：设计中 +> 状态：v2 设计中 > 作者：庞统 -> 日期：2026-06-13 +> 日期：2026-06-13（v1），2026-06-14（v2 对齐 #11 四层架构） > 评审：待司马懿评审 ## 一、问题 @@ -22,8 +22,6 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已 **根因是注入时机**：Agent 不知道什么时候该查、没有强制机制让 Agent 在关键决策点查。 -现有设计（#11 四层架构）把知识注入放在 L3-4（被动参考层），但没有定义"什么时候触发被动参考"。 - ### 1.3 目标 1. Agent 在关键决策点**主动查询** wiki-vault @@ -64,31 +62,55 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已 | 设计点 | 来源 | 我们的做法 | |--------|------|-----------| -| 铁律级强制 | Superpowers | L0 Hook + SOUL.md 双重注入 | -| Red Flags 反合理化 | Superpowers | 知识查询 Red Flags 表 | +| 铁律级强制 | Superpowers | L0 Hook 注入 + L1 SOUL.md 行为引导 | +| Red Flags 反合理化 | Superpowers | 知识查询 Red Flags 表（L1 SOUL.md） | | 经验内化 | Hermes | 经验→wiki-vault→下次查询 | | 渐进式披露 | Hermes | 先查 summary，按需读全文 | -## 三、设计决策 +## 三、设计决策（对齐 #11 四层架构） -### D16-1：三层触发机制（核心设计） +> **层级体系严格对齐 [#11](./11-context-layers-redesign.md)**，不自创命名。 -不是在引擎层面自动注入知识全文（token 浪费），而是通过三层机制让 Agent **主动查询**： +### 总览 -| 层级 | 机制 | 内容 | 覆盖范围 | -|------|------|------|---------| -| **L0 铁律** | SOUL.md 行为引导 | "做方案前先查 wiki-vault，有 1% 相关就要查" | 所有 Agent、所有场景 | -| **L1 Skill 路由** | wiki-query Skill description | 触发词：调查、研究、分析、优秀实践、经验、怎么做X | Agent 匹配到触发词时 | -| **L2 知识 gap 闭环** | 定时任务 | 查不到→记 gap→每天处理→写入 wiki-vault | 持续改进 | +| #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 | 不属于上下文分层 | -**为什么不做 PromptComposer 自动注入**： -1. 自动注入 token 浪费（每次任务都注入可能不相关的知识） -2. 覆盖范围有限（只影响 moziplus 子任务 Agent） -3. Agent 主动查询更精准（知道自己缺什么知识） +### D16-1：L0 铁律层 — 新增一条 wiki 查询铁律 -### D16-2：知识查询 Red Flags（防止跳过） +L0 只放跨系统通用的、不可绕过的行为底线。wiki 查询铁律和 GATE 门控同级。 -在 SOUL.md 中加入 Red Flags 表，和 Superpowers 一致： +**新增铁律**： + +``` + +做方案前先查 wiki-vault，有 1% 相关就要查。查不到记 knowledge-gaps.md。 + +``` + +**注入方式**：和 `` / `` 并列，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 的想法 | 反驳 | |---|---| @@ -97,22 +119,122 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已 | "这个领域我熟悉" | 熟悉≠知道最新实践，wiki-vault 持续更新 | | "查知识库浪费时间" | 重复踩坑浪费的时间远大于查询时间 | -### D16-3：知识 gap 记录机制 +### D16-3：L2 引擎注入层 — 三种 handler 各注入 WikiGuideSection -**触发**：Agent 在 wiki-vault 中查不到相关知识时。 +L2 是 BootstrapBuilder/PromptComposer 动态拼装的 prompt 段。当前有三种 handler，各有自己的 PromptSection 实现： -**记录位置**：`/Volumes/KnowledgeBase/wiki-vault/_meta/knowledge-gaps.md` +#### 当前 handler 结构 -**格式**（已有）： -```markdown -- [日期] Agent名查"主题" → 待处理 +| 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 ``` -**已有基础设施**： -- knowledge-gaps.md 已存在，有 20+ 条历史记录 -- 格式已定义，处理后会标注 `→ 已建立 ✅` +#### 三种 handler 改动 -### D16-4：定时任务流程（已有 cron 基础） +每种 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 基础） | 任务 | 时间 | 内容 | 状态 | |------|------|------|------| @@ -126,56 +248,60 @@ Agent（庞统、司马懿、张飞等）在执行任务时，不主动查询已 4. 新建或更新 wiki-vault 页面 5. 更新 knowledge-gaps.md（标记为"已建立 ✅"或"无KB内容，跳过"） -### D16-5：wiki-vault 作为索引层 +### D16-6：和 #11 各层关系总结 -**确认原则**：wiki-vault 是索引层，不是详细内容存储。 +| #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 | -- 查询先走 wiki-vault（practices/concepts/skills） -- 如果页面指向 knowledge_base 的详细内容，**必须 follow** 获取原文 -- knowledge_base 的路径：`/Volumes/KnowledgeBase/knowledge_base/` +### D16-7：为什么不做 PromptComposer 自动注入知识全文 -### 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 内部的额外经验来源。 +1. **token 浪费**：每次任务都注入可能不相关的知识 +2. **覆盖范围有限**：只影响 moziplus 子任务 Agent +3. **Agent 主动查询更精准**：知道自己缺什么知识，按需查询 ## 四、改动清单 ### 4.1 已完成 ✅ -| 改动 | 文件 | 说明 | -|------|------|------| -| TOOLS.md 更新 | workspace-pangtong/TOOLS.md | 新增「LLM Wiki 知识库」段：速查表、检索原则、铁律 | +| 改动 | 文件 | 层级 | 说明 | +|------|------|------|------| +| 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 待实现 -| 改动 | 文件 | 说明 | -|------|------|------| -| SOUL.md 行为引导 | workspace-pangtong/SOUL.md | 新增「知识查询」行为规则 + Red Flags | -| wiki-daily-update 完善 | cron job | gap 处理 + 经验总结逻辑 | +| 改动 | 文件 | 层级 | 说明 | +|------|------|------|------| +| L0 wiki 铁律 | Hook 注入配置（`prependContext`） | L0 | 新增 `` 段 | +| 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 主动查询更精准 | +| PromptComposer 知识全文注入 | token 浪费，Agent 主动查询更精准 | | experiences 表 | wiki-vault 已覆盖，不重复建设 | -| 新 Skill | wiki-query 已有，不需要新的 | +| 新 Skill（除 wiki-query 外） | wiki-query 已有，不需要新的 | + +## 五、风险 + +| 风险 | 概率 | 缓解 | +|------|------|------| +| Agent 不主动查 wiki | 中 | L0 铁律强制 + L2 引导 + L3 Description 触发，三层保障 | +| wiki-query 在子目录不被 extraDirs 发现 | 中 | 确认后决定移顶层或配置子目录 | +| wiki-daily-update gap 处理质量不够 | 低 | 人工审核 + 逐步完善 | +| WikiGuideSection 增加 token | 低 | 固定 ~30 tokens，影响可忽略 |