技能知识库管家（Skill Knowledge Base Steward）
对标开源知识框架的本地技能知识资产管理器。核心理念同源：文档管线（解析→分块→索引）+ 混合检索（RRF 融合）+ 自动 Wiki（交叉链接+版本快照）+ 健康治理——全部本地化、零依赖（纯 Python 标准库），专为「几百个 SKILL.md 怎么管」而生。
一句话定位
把整个技能库变成一个可检索、可导航、可治理的迷你知识库——检索有引用、Wiki 有回滚、健康有台账。
适用场景
- 「我写过哪个技能讲 XX？」——几十个技能记不清时，混合检索秒回带引用
- 「技能库现在什么状态？」——健康体检：frontmatter 缺陷、重名、断链
- 「给技能库出一本能导航的手册」——自动 Wiki：分类树 + 实体页 + 相关技能互链
- 「改完一批技能后留个底」——Wiki 重新生成时旧版自动快照，可回滚
Agent 工作流（ReAct 式四工具循环）
本技能内置一个检索 Agent 循环。工具集对标知识框架的 Agent 预设（rag-qa 三件套）：
| 工具 | 本地命令 | 对应 | 用途 |
|---|---|---|---|
list_documents |
kn_index.py --stats / 读索引 stats |
列文档 | 看库内有多少技能、什么分类、索引多新 |
search_knowledge |
kn_search.py --q "..." |
检索 | 混合检索，返回带引用（路径+章节+行号）的分块 |
read_document |
直接 Read 命中的 SKILL.md（用引用行号定位） | 读文档 | 只读命中的技能全文或章节 |
health_check |
kn_health.py |
治理 | frontmatter 缺陷/重名/断链台账 |
循环规则（同 ReAct：先想，再行动，观察后决定下一步）：
- 收到问题 → 先
list_documents掌握库况（除非明确知道要查什么） search_knowledge检索 → 看引用，绝不凭记忆回答「有没有某技能」- 命中可疑或需要细节 →
read_document读原文核对 - 综合 → 回答必须带引用（技能名 + 文件路径 + 章节）；没有引用支撑的说法标「未检索到」
- 问到「库健康/重名/规范」→ 加跑
health_check，台账说话
快速上手
首次使用（或技能库变更后）——建索引：
python scripts/kn_index.py # 默认扫描 ~/.workbuddy/skills
python scripts/kn_index.py --root <技能目录> --kb <知识库目录>
检索：
python scripts/kn_search.py --q "口播 文案 时长" # 混合检索，带引用
python scripts/kn_search.py --q "frontmatter" --top 5 --json
生成 Wiki（分类树 + 技能页 + 互链，旧版自动快照）：
python scripts/kn_wiki.py # 输出到 <kb>/wiki/
健康体检：
python scripts/kn_health.py # 表格化台账（只读，不修改任何技能）
知识库落盘结构
<kb>/ # 默认 ~/.workbuddy/skill-kb/
index.json # 倒排索引（分块+词表+技能画像）
activity.jsonl # 活动流（追加式，best-effort）
wiki/
Home.md # 总览：统计 + 分类导航 + 最近变更
categories/<分类>.md # 分类页（分类路径最深 3 级）
pages/<slug>.md # 技能实体页（画像 + 章节 + 相关技能互链）
revisions/<slug>.v<N>.md # 版本快照（每 slug 上限 50，超出裁最旧）
核心规范速查
- 分块：标题分块（H1-H3 切分），块内 <30 字符并入前块——大块保上下文，小块利召回
- 检索：中文按 bigram 切词（与内嵌 SQLite 引擎同思路）；BM25 主体 + 元数据（名称/显示名/标签/分类）双路 → RRF（k=60）融合 → 章节标题命中加权重排
- 引用：每条命中给出
技能名｜章节｜文件路径:行号｜摘要，回答必须可溯源 - 快照：Wiki 页覆盖前先整份快照，版本号只增不减；回滚 = 用旧版内容生成新版本（回滚本身可回滚）
- 治理只读：健康检查绝不直接改技能文件——发现问题列清单，人工确认后再改（存档纪律：scan = read-only）
深入阅读
references/管线与架构.md—— 对标架构逐层映射（文档管线/检索/Agent/Wiki/治理五层）references/检索与打分手册.md—— BM25、RRF、重排的参数与调法references/治理与健康手册.md—— 体检规则清单与修复流程templates/知识库报告.md—— 交付用报告模板
维护
- 技能库大改（新增/重命名/批量更新）后重跑
kn_index.py+kn_wiki.py，一次全量刷新 - 索引是纯缓存，删了随时可重建；Wiki 快照才需要保
