# Distill Kb

> 本地知识库（~/Documents/KnowledgeBase）自动维护、检索与汇总：增量扫描、AI按v2标准逐篇蒸馏（含失效传播与冲突标注）、BM25检索、按标签/实体汇总。维护或查询知识库、往库中放资料、要求汇总资料时使用。

- Skill: `aloasut/distill-kb` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add aloasut/distill-kb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aloasut/distill-kb/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: aloasut (https://skillmd.com/u/aloasut)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aloasut/distill-kb

---


# 本地知识库（Knowledge Base）

把 `~/Documents/KnowledgeBase/` 当作"资料级"知识库，复刻商业知识库三步模型：
**放入资料 → AI 逐篇蒸馏成检索笔记 → 提问时先检索笔记再作答/汇总**。
零向量库、零外部服务：目录 + sha256 增量状态 + Markdown 笔记 + BM25 + 标签索引。

## 布局

```
~/Documents/KnowledgeBase/          源资料（用户随意建目录；只读，绝不修改）
  .kb/notes/<源相对路径>.md          逐篇蒸馏笔记（镜像源目录）
  .kb/state.json                     增量状态（只经 kb.py 读写）
```

CLI：`python3 ~/.hermes/skills/note-taking/knowledge-base/scripts/kb.py <子命令>`
（KB_ROOT 环境变量可重定向库根目录。）

| 子命令 | 作用 |
|---|---|
| `scan` | 增量扫描：新增/变更(重蒸馏)/删除(连笔记一起删) |
| `todo [--cap N]` | 待蒸馏清单（按加入时间升序） |
| `notepath REL` | 源文件对应笔记的绝对路径 |
| `mark REL done\|failed\|pending [--title T] [--reason R]` | 标记蒸馏结果 |
| `search QUERY [--top N]` | BM25 检索：已蒸馏笔记优先，未蒸馏文本原文兜底 |
| `tags` | 全库 标签/实体/主题 聚合索引（含旧笔记缺字段警告） |
| `notes [--tag T] [--entity E] [--topic P]` | 按标签/实体/主题列笔记，按资料日期升序（汇总入口）；失效/冲突笔记带 ⚠/⚡ 标记 |
| `conflicts` | 冲突标注对 + 已失效笔记清单（汇总前必查） |
| `status` | 总览（含失败清单与知识一致性计数） |

## SOP-A：维护（入库/蒸馏，cron 与手动通用）

1. 用户放入新资料后（或收到"维护知识库"指令）：跑 `scan`。
2. `todo --cap 5` 取一批（每轮 ≤5 篇，控制 Token；失败的排最前重试）。
3. 对每篇：
   - 通读原文（`KB_ROOT/<rel>`）；非文本/损坏/超大读不动 → `mark REL failed --reason "..."`
   - **先检索既有笔记**（`search` 关键词 / `notes --tag`）：发现与已有笔记说法冲突 → 新旧笔记互相写 `conflicts_with`；发现新资料明确推翻旧结论 → 按硬规则做失效传播（改旧笔记）
   - 跨层互引：若主题在其他 skill/agentmemory 有配套条目（SOP、服务细节），笔记「细节补充」写明互引；本库存放依据与检索笔记，不复制 SOP 全文
   - 按"蒸馏笔记规范 v2"写笔记到 `notepath REL` 给出的路径
   - `mark REL done --title "<短标题>"`
4. 全部处理完再跑 `scan`（同步状态）和 `status`，报告新增/蒸馏/失败数。

### 蒸馏笔记规范 v2（为"检索 + 汇总"双目标设计）

笔记必须既是"能被独立检索命中的浓缩体"，又是"能跨笔记聚合成时间线/专题的结构化单元"：

```markdown
---
source: <源相对路径>
distilled_by: <你的agent名>
distilled_at: <YYYY-MM-DD>
type: 检索笔记
topic: <主题域，单值：投资/技术/会议/产品/研究/生活/其他>
source_type: <群聊|研报|会议|文档|网页|论文|随手记|报告>
date: <资料所述/发布日期 YYYY-MM-DD，未知用 scan 加入日期>
tags: [<3~8个检索词，必须含：主称、别称、英文名/代码/型号>]
entities: [<关键主体：公司/人物/产品，可空>]
superseded_by: <可选：被哪份资料（源路径）推翻后填写>
conflicts_with: [<可选：与本库哪些笔记说法冲突，写对方源路径，双向互写>]
---

# 蒸馏笔记：<短标题>

**一句话**：<全文最核心结论，一句话>

## 事实与观点
- [YYYY-MM-DD] 事实：<精确数字/命令/结论，数字绝不改写>
- [YYYY-MM-DD] 观点(<谁>)：<观点内容，标注是谁说的>
- [YYYY-MM-DD] 传闻/未验证：<...>（可信度低，须注明）
- [YYYY-MM-DD] 已失效(<失效日期>, 被<资料>推翻)：<原内容>（保留在案，现行结论勿引用）

## 问答锚点
- 问：<用户可能的原话提问>？→ <直接可用的答案>
- 问：…？→ …（3~6 条，覆盖原文主要问题域）

## 关键词
<逗号分隔，含同义词/别称/中英文/缩写——这是弥补关键词检索同义缺口的关键行>

## 细节补充
<数据、命令、步骤、引用来源；没有就写来源与日期>
```

**硬规则：**
- `tags` 必须写"别称桥"：正文说 CoWoS，tags 就要有「先进封装」；正文说 NVDA，tags 要有「英伟达」。同义改写检索全靠它。
- 事实与观点分条标注日期与发言人；数字、日期、型号逐字保留，禁止四舍五入或改写。
- **失效传播**（吸收 Lemmalog 撤回级联思想，手工版）：新资料明确推翻旧笔记结论时——
  1) 旧笔记 frontmatter 加 `superseded_by: <新资料源路径>`；
  2) 旧笔记被推翻的事实条目改写为 `已失效(<日期>, 被<新资料>推翻): 原内容`，**不删除**（历史演变要可追溯）；
  3) 新笔记正常蒸馏，新旧各自成立。
- **冲突标注**（吸收 Lemmalog 矛盾候选思想）：双方说法不同但都未被推翻（如群聊 vs 研报的口径差异）→ 两篇笔记 frontmatter **互相**写 `conflicts_with: [对方源路径]`，并在各自细节补充保留文字说明。
- 原文更新后状态自动回 pending，须重蒸馏（笔记直接覆写，frontmatter 的 distilled_at 更新）。
- 大文件（>100KB）：优先蒸馏可检索的结论与问答锚点，细节注明"详见原文"。
- 来源自包含：微信文章、群聊、网页等链接易失效/被删。Agent 自己整理研究落库时，关键数据、命令、结论必须直接写进源文档，URL 仅作溯源，保证链接失效后资料仍有完整价值。

### 非文本资料

- PDF/Word：先用 Hermes `read_file`（自动提取文本层）拿到文本再蒸馏。
- 扫描件/图片/无文本层：`mark REL failed --reason "无文本层，需 OCR"`，并在报告里建议用 PaddleOCR 处理后重放。

## SOP-B：检索（聊天时自动参考）

1. 用户提问涉及库里资料时，先 `search "<提问关键词>" --top 8`。
2. 读命中的笔记（必要时顺着 `source` 回读原文片段），把命中片段作为依据作答，并注明来源路径。
3. 检索无命中 ≠ 没有答案：换标签查 `tags`/`notes`；再无 → 提示用户可把相关资料放入库中。
4. `status` 可随时报家底（几篇、蒸馏进度、失败清单）。

## SOP-C：汇总（"把我发的资料整理一下"）

1. 先跑 `conflicts` 拉全库冲突对与失效清单；用 `notes --tag <X>`（或 `--entity`/`--topic`）按主题拉出全部相关笔记（按资料日期升序）。
2. 逐篇读"事实与观点"条目，合成时间线或专题摘要：
   - 每条标注日期与来源类型（群聊/研报/会议…），观点注明是谁说的；
   - **被 superseded 的失效事实不再作为现行结论**，但可进"历史演变"叙述并标注失效；现行结论只用未失效事实；
   - 数字逐字保留；`conflicts_with` 命中的说法**并列展示并标注冲突**，不擅自裁决；
   - 传闻与已验证事实分开，不混写。
3. 结尾列来源文件清单（`.kb/notes/...` ↔ 源路径）。
4. 用户要落盘时，把汇总写入源库（如 `汇总/<主题>_截至<日期>.md`）——它本身也是一份新资料，scan 后可再蒸馏成"二级笔记"。

## 自动维护

夜间 cron 任务 `knowledge-base-nightly`（每天 03:30，deliver local 静默）：
scan → 按 SOP-A 蒸馏一批（≤5 篇，自动采用本文件的最新规范）→ status 简报。手动维护与它遵循同一 SOP。

## 与 Hermes 知识分层的关系

- 本库 = **资料级**知识（文档、调研、报告原文+笔记）。
- 结论性约定 → memory；流程 SOP → skill；项目细节 → agentmemory；会话历史 → session_search。
- 同一知识不要重复存放：定了结论就只留约定，原始依据留本库。

## 验证

改动 kb.py 或 SOP 后必须端到端跑一遍：scan → todo → 按 v2 蒸馏 1 篇 → mark done →
search 命中且排序第一 → `notes --tag` 能聚合 → `tags` 索引正确 → `conflicts` 能枚举
（含至少一条冲突或失效验证）。检索或聚合不命中即视为不合格。压力测试用例记录见 agentmemory（沙箱 KB_ROOT 重定向法）。