sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily e83ad1de73

CI / lint (pull_request) Successful in 8s

Details

CI / test (pull_request) Successful in 28s

Details

CI / notify-on-failure (pull_request) Successful in 0s

Details

docs: #16 知识注入设计 v2 — 对齐 #11 四层架构

- 层级命名统一到 #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（已有，需完善）

2026-06-14 10:22:16 +08:00

12 KiB

Raw Blame History

#16 知识注入设计

状态：v2 设计中作者：庞统日期：2026-06-13（v1），2026-06-14（v2 对齐 #11 四层架构）评审：待司马懿评审

一、问题

1.1 现状

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

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

1.2 根因

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

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

1.3 目标

Agent 在关键决策点主动查询 wiki-vault
查不到相关知识时自动记录 knowledge gap
定时任务处理 gap + 总结经验，持续丰富 wiki-vault
不增加 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 层级	知识注入角色	本设计覆盖	注入方式
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() 都注入：

# 可放在 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()：

# 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 完善内容：

读取 knowledge-gaps.md 中"待处理"条目
对每个 gap：搜索 knowledge_base 是否有相关源码/文档 → 有则提炼写入 wiki-vault
搜索最近一天的 jsonl 日志，提取有价值的经验
新建或更新 wiki-vault 页面
更新 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 自动注入知识全文

token 浪费：每次任务都注入可能不相关的知识
覆盖范围有限：只影响 moziplus 子任务 Agent
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，影响可忽略

12 KiB Raw Blame History Unescape Escape

#16 知识注入设计

一、问题

1.1 现状

1.2 根因

1.3 目标

二、调研

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

2.2 Hermes：经验闭环 + Session Search

2.3 结论

三、设计决策（对齐 #11 四层架构）

总览

D16-1：L0 铁律层 — 新增一条 wiki 查询铁律

D16-2：L1 角色层 — TOOLS.md + SOUL.md

TOOLS.md（✅ 已完成）

SOUL.md Red Flags

D16-3：L2 引擎注入层 — 三种 handler 各注入 WikiGuideSection

当前 handler 结构

新增 WikiGuideSection（priority=60，PRIORITY_EXTENSION）

三种 handler 改动

为什么三种 handler 都需要

token 开销

D16-4：L3 被动参考层 — wiki-query Skill

现状

触发机制

待确认：extraDirs 子目录递归

D16-5：知识 gap 记录 + 定时任务（运维层）

gap 记录机制（已有基础设施）

定时任务（已有 cron 基础）

D16-6：和 #11 各层关系总结

D16-7：为什么不做 PromptComposer 自动注入知识全文

四、改动清单

4.1 已完成 ✅

4.2 待实现

4.3 不做

五、风险

12 KiB

Raw Blame History