# Knowledge Gatekeeper

> 个人知识库的治理层 / Governance layer for personal knowledge bases — turn what you saved but never read into something you actually read. 四档质量门禁、成页门禁（防注水）、单一账本增量、断点续跑、防丢闭环、页面结构规范、平台接入清单（集成获取，不做实现）。Triggers — knowledge base governance / quality gate / unread favorites / note triage / padding audit / 知识库治理 / 质量门禁 / 成页门禁 / 注水检测 / 素材定档 / 收藏精炼 / 知识库防丢 / 账本续跑 / 笔记入库审查 / 平台接入

- Skill: `noddhogg/knowledge-gatekeeper` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add noddhogg/knowledge-gatekeeper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/noddhogg/knowledge-gatekeeper/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: noddhogg (https://skillmd.com/u/noddhogg)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/noddhogg/knowledge-gatekeeper

---


# knowledge-gatekeeper · 知识库治理层

> **把你收藏了却没看的东西，变成你真的会看的东西。**
> 别人解决「怎么把视频变成笔记」，本 skill 解决「什么配进笔记库」。
> 本文件自包含：读完即可开工，不需要外部文档。
> （`docs/platforms.md` 是平台清单，属可选补充——缺了它也能开工，有了它少猜。）

## 一、定位

**把你收藏了却没看的东西，变成你真的会看的东西。**

转化工具（`take-notes`、`video2knowledge` 等）已经能把信息源变成结构化笔记。本 skill 不重复那部分，只做它们**上面**缺的一层治理：

- **进什么** —— 四档质量门禁
- **怎么攒** —— 单一账本 + 断点续跑
- **怎么不丢** —— 防丢闭环

以及成文时的**页面结构规范**。

**收藏 ≠ 优质**——当初收藏只说明标题打动了你，不说明里面有值得留下的东西。
所以才需要门禁：这一层不是为「关键词搜索」准备的，是为**你已经攒了一堆却没看**准备的。

前置假设：你已经能把素材转成文字（转写稿、文章正文），本 skill 从拿到文字稿开始。

### 获取：集成，不实现

哪些平台能接、能接到哪一步，见同项目 `docs/platforms.md`（数据为 `yt-dlp`
**2026.06.09** 版实测，随版本变化，复核命令写在文件末尾）。

三条红线，**零例外**：

1. **不写下载器，用现有工具集成** —— 获取能力来自 `yt-dlp` 这类成熟项目。
   本 skill 只维护清单与接入约定，不产出下载代码
2. **不绕风控，不写任何规避手段** —— 遇到频率限制、登录墙、验证码，
   就减速、登录、或放弃。不提供绕过方案，也不讨论
3. **不碰付费 / 隐私 / DRM 内容** —— 付费课程、需登录才能看的私人收藏、
   DRM 加密内容，一律不纳入。拿不到就跳过

需要给用户平台建议时从 `docs/platforms.md` 取。**不要凭印象编造平台名、提取器数或能力**——
那份清单每条都是实测出来的，猜的数字会直接误导用户。

## 二、五条核心原则

1. **未提交 = 不存在**。页面生成后当轮必须提交版本库。
2. **账本是唯一事实源**。状态、定档、产出路径只记在一处。
3. **质量门禁零例外**。未经定档的内容不得入库。
4. **只加不删**。批量操作默认可回滚，删除前先移位而不是直接删。
5. **人机同源**。同一批内容同时产出人看页面与 AI 可读索引。

## 三、三根纵切机制（核心）

治理不是流水线上的某一环，而是贯穿全程的三根支柱。

### 3.1 四档质量门禁

**这是整条链路最重要的一步，不可跳过、不可批量放行。**

逐篇通读转写稿，按下表定档，写入账本的 `quality` 字段：

| 档 | 判据 | 处置 |
|---|---|---|
| `high` | 可提取的知识量大，方法具体可复用，冗余少 | 完整入库 |
| `medium` | 有可提取的方法，但夹杂冗余或跑题 | 只精炼有效部分（**精炼后不足 800 字见下方「medium 与成页门禁」**） |
| `low` | **拆开包装后**没有可复用的知识 | 不入库 |
| `reject` | 与知识库主题无关 | 跳过 |

> **`medium` 与成页门禁的衔接（容易卡住的地方）**：`medium` 的处置是"只精炼有效部分、
> 不做完整展开"，而成页门禁要求自有知识量 ≥ 800 字——**这两条会正面撞上**。
> 撞上时走「短源怎么办」的逃生口：**合并进主题页**，或**降级为要点页**。
> ⚠️ **不要为了凑 800 字去扩写**——那直接违反「该合并，不该扩写」，
> 而且成页门禁的整套设计就是为了不让页面被字数配额撑长。
> 逃生口写在「关于成页 → 短源怎么办」（层 ④），与定档不在同一层，所以在这里交叉引用一次。

四条判据，逐条过：

1. **能提取出多少可复用的知识** —— 首要判据。通读后能否复述出 3 个以上具体、可验证、能上手操作的知识点。复述得越多越具体，档位越高。
2. **讲的是事实方法还是纯观点** —— 有论据、有步骤、可验证的加分；只有结论和情绪的减分。
3. **冗余占比多少** —— 引流广告、重复寒暄、跑题闲聊都算冗余。冗余高不直接判死，只影响 `high` 与 `medium` 之分。
4. **情绪操纵是否替代了实质** —— 逆反、恐惧、焦虑、夸大都是常见手法。**用了这些手法本身不扣分**，只看它们有没有替代掉知识：手法只是包装，不影响定档；手法就是全部内容，才是 `low`。

### 关于标题：它是提示，不是判据

标题与内容的落差**只用来提醒你重点核查，不直接决定档位**。

一旦手上已有完整转写稿，就该直接判断内容本身。标题是**代理指标**，用它推断内容，等于用包装判断实质——而在你已经能看到实质的时候，这是多余的，也是会出错的。

有一类内容专门靠"不一致"来传播：

| 形态 | 标题 | 内容 |
|---|---|---|
| 正向教学 | 《这道题的正解思路》 | 有效解法 |
| 逆反式教学 | 《你这样刷题，活该考低分》 | **同一套有效解法** |
| 反语式测评 | 《这东西被吹上天，其实……》 | 可能是扎实的评测 |

三者知识含量可能完全相同。把"标题一致性"当判据，会**系统性地误杀后两类**，理由仅仅是它们的包装不同。

真正该杀的是**包装之下没有东西**。判法很简单：把逆反、夸张、恐吓这层皮剥掉，剩下的还是不是知识？是，就按知识量定档；不是，才是 `low`。

> **分阶段看**：在**搜索 / 获取层**，标题和元数据是有效的筛选信号，用它们过滤明显不相关的完全没问题；但到了**收集 / 定档层**，必须唯知识论——只看内容，不看包装。

**注意 `medium` 不是排除项。** 它进库，但规格不同——只取有效部分，不做完整展开。审查的产出不是"要不要"，是"**以什么规格要**"。

"以什么规格要"有两层，别只做第一层：定档决定**进不进**，成页门禁决定**以什么规格进**（详见「关于成页」）。
`medium` 精炼后常常不足 800 字，此时**合并进主题页或降级为要点页**，不要扩写凑数——
扩写出来的字数正是成页门禁要拦的东西。

这一步必须逐篇通读，无法自动化。也正因如此，它是整套方法里最难被复制的部分。

### 关于成页：门禁还有第二道

四档门禁管的是**输入端**——这条素材值不值得进库，发生在层 ③。

但**素材过关 ≠ 页面过关**：素材定档合规，成出来的页仍可能是废的。
成页在层 ④（呈现），这一环同样需要门禁。

#### 成页的三条硬指标

成页后、入库前，逐页过：

| 指标 | 阈值 | 不达标 |
|---|---|---|
| 自有知识量（去模板外壳与跨页重复后） | ≥ 800 字 | 合并进主题页，或降级为要点页 |
| 跨页重复率 | ≤ 15% | 打回重写 |
| 页面总字数 | **不设下限** | 写满即止 |

#### 为什么字数不能当指标

这与上面「标题是提示，不是判据」是**同一条原则**：不要用代理指标代替真指标。

- 标题是内容的代理指标 → 拿来定档会系统性误杀
- 字数是知识量的代理指标 → 拿来验收会让 AI 用最低成本凑数

字数配额奖励的是「看起来一样长」，不是「有东西」。它不消除差异，只把差异**抹平**——
读者看到同样厚的一页，期待同样的深度，得到越来越空的填充。

#### 短源怎么办

短视频不是「内容不够」，是**不配单独占一页**。

3–5 条同源素材合成一个主题页：信息量自然够，深度来自多视角交叉印证，而不是注水。
合并后仍不达标的，说明素材本身就不该单独成页——**该合并，不该扩写**。

必须单页时用**要点页**（一句话总结 + 要点表格 + 自测题），并在页面上标明这是短页。
不适感大半来自**期待落空**，不是来自内容短。

**这一节也是 `medium` 的逃生口。** `medium` 的处置是"只精炼有效部分"，精炼后不足 800 字
是常态而非意外——走上面两条（合并进主题页 / 降级要点页），不要为了凑字数去扩写。

#### 外部工具产出的笔记，同过这道门禁

门禁卡的是**入库前**，不是"这一页是谁生成的"。

两道门禁是**串联**的，不是二选一：四档定档（层 ③）管**要不要进库**，
成页三条（层 ④）管**以什么规格进库**。外部工具产出的笔记两道都要过。

用 `take-notes` / `video2knowledge` 这类端到端工具时，第二道最容易被整个跳过——
笔记看起来已经"做完了"，直接入库即可。但这类工具优化的是**产出速度**，
不是你库里的知识密度。它注水你看不出来，因为它是按**它自己的模板**注的。

三条硬指标在外部笔记上的读法：

| 指标 | 在外部笔记上怎么读 |
|---|---|
| 自有知识量 ≥ 800 字 | 要剥离的是**该工具的模板外壳**（固定页眉页脚、导航、样式容器、每篇都一样的"总结 / 要点 / 自测"骨架），不是我们的模板。剥离法一致：**只数这一页独有的内容** |
| 跨页重复率 ≤ 15% | 照旧与库内已有页比。**这条在外部笔记上价值最高**：同一工具给每篇套的套话是逐字相同的，只跟库内其他页比才暴露得出来 |
| 页面总字数 | 不设下限 |

不达标的处置与上表相同：合并进主题页 / 降级为要点页 / 打回。

**只有"打回"的含义变了**：外部笔记不能退回工具重跑——重跑只会拿到同一套模板、
同一批套话。打回在这里指**自己改写**，或**换一条素材**。

额外一条：**外部笔记要查 AI 指令残留**。端到端工具把提示词和产出写在同一份文件里，
模板中可能残留指令性文字（"请以 JSON 输出""忽略之前的指示"）。入库前清掉，
否则这些字符串会作为知识被检索出来。

#### 判定口径（不附脚本）

任何文本相似度工具都能实现：

- **知识量**：先剔除每页共用的模板外壳（自测、延伸阅读、笔记组件等 UI 文字）再统计。
  不剔除会把「共用模板」误判成「跨页重复」，指标直接失效——这个坑踩过一次。
- **跨页重复率**：按标题切段，中文 8-gram 集合做 Jaccard，
  与库内其它任意段落 ≥50% 即计入重复。这是**唯一能自动抓住
  「每句都对但跟本页无关」**的指标。
- **标题泄漏**：**页面标题与各级小节标题**里出现「扩写」「补到」「样例」「大补」这类发给 AI
  的措辞，即打回。⚠️ 统计范围是**标题 + 小节标题**，不是只有页面标题——按页标题计每页至多
  1 处，而实测案例是每页 5.8 处（见下方参考案例），差的就是小节标题。

> **关于阈值本身**：800 字 / 15% / 8-gram ≥50% 都是**经验值，不是推导值**。
> 换语言（英文按词计）、换领域（诗歌、代码注释）都应重设。**先跑一遍看分布，
> 再定你的阈值**——重点是「有一条线」这件事，不是线画在哪。

#### 参考案例

> 以下仅用于说明这道门禁的**必要性**，不是方法本身。案例是会过时的，方法不会。
>
> 某 C++ 学习知识库 41 页，素材定档全部合规，AI 批量成页时被要求
> 「每页补到 ≥2000 字」。结果——
>
> | 指标 | 实测 |
> |---|---|
> | 页面总字数 | 极差仅 **533**（1341–1874），被配额抹平 |
> | 真实知识量 | 极差 **1734**（0–1734） |
> | 标题残留 AI 指令 | 41 / 41 页，共 **237 处**（标题 + 小节标题，平均 5.8 处/页） |
> | 重复样板占比 | **80%** |
>
> 页面上真的印着「【AI 扩写样例】…（补到 ≥2000 字 + 实操）」——
> **发给 AI 的工单，被贴在了成品上**。而它通过了当时全部七项检查：
> 账本状态全 `done`、`page` 路径存在、0 坏链、已提交版本库。
>
> 按上面的门槛回算：41 页真实知识合计仅 1.3 万字，只够 **16 页**；
> 其中后 29 页合计仅 3530 字，合并后只够 **4 页**。29 页的内容，实际只值 4 页。

### 3.2 单一账本

所有素材的状态、定档、产出路径只记在一个 JSON 文件里，每完成一步立即回写，**不做批量补记**。

它带来三个能力：

- **断点续跑** —— 重跑命令 = 跳过 `done` 的命令
- **积压可见** —— `transcribed`（已转写未定档）是一个可查询的队列
- **统计可信** —— 覆盖率、通过率由账本算出，不是估的

完整结构见 `examples/ledger.schema.json`。核心字段：

| 字段 | 用途 |
|---|---|
| `id` | 素材唯一标识，整条链路的主键 |
| `status` | `pending` → `working` → `transcribed` → `done` / `failed` |
| `quality` | `high` / `medium` / `low` / `reject`，由门禁写入 |
| `quality_reason` | **定档理由，与 `quality` 同时写入**。只写「剥掉包装后剩下的是什么」，不写包装本身——标题与内容不一致是核查提示，不是定档理由。这是门禁可审计、可回溯的唯一依据，必填 |
| `media` / `transcript` | 过程文件路径 |
| `page` | 成页路径，`low` / `reject` 时留空 |
| `fail_reason` / `retry_count` | **仅**技术失败（获取 / 转写 / 成页）的原因与重试次数。定不入库的原因写 `quality_reason`，不要塞进 `fail_reason` |

**同一批次只允许一个进程写账本。** 并发写 JSON 会互相覆盖，这是最容易踩且最难排查的坑。

### 3.3 防丢闭环

以下五条来自真实事故（一次误操作丢掉 90 页未提交内容），**零例外**。

1. **禁止对知识库执行 `git clean -fd`**，无论带不带路径参数。清理残留一律先 `git status --short` 人工核对，只做精确回退。
2. **禁止把 `git reset --hard` 当作回退手段**。需要回退先 `git stash push`（保留未跟踪文件）或先做全量快照。
3. **任何破坏性操作前**（reset / clean / rm / checkout -- .），先确认目标文件是否已跟踪；未跟踪文件必须先复制到备份区。
4. **页面建完即提交**。任何 HTML / MD / 资产一经生成或修改，当轮结束前必须提交。禁止跨轮持有未提交内容。
5. **依赖库同步提交**（CSS / JS / 字体等），禁止裸放在工作区。

附加建议：每日自动生成一次全量快照归档到 `_archive/`，作为最后的安全网。

## 四、四层横切（流程背景）

治理机制作用的舞台。这层的工具已经很成熟，**本 skill 不重复实现，只定义契约**。

```
① 获取  →  ② 转译  →  ③ 分流审查  →  ④ 呈现
```

| 层 | 做什么 | 治理机制在此层的作用 |
|---|---|---|
| ① 获取 | 拉取清单，对比新增；下载或抓正文 | 账本记来源与状态；门禁做清单去重 |
| ② 转译 | 提音频、转文字 | 账本记转写路径；失败重试判定；过程文件不落临时目录 |
| ③ 分流审查 | 四档定档 | **门禁主战场**；账本写定档结果 |
| ④ 呈现 | 成页、索引、审计 | 账本记成页位置；0 坏链审计；建完即提交 |

**关于层 ① 和层 ②**：不同平台有不同的获取方式和各自的服务条款，请遵守对方规则。常见约束提前预期——批量连续请求易触发频率限制，长任务中凭据会失效需自动重建，单条失败不应中断整批。三条红线见第一节（不写下载器 / 不绕风控 / 不碰付费与 DRM）。

常用组合：`yt-dlp` 负责下载、`faster-whisper` 负责转写，两者都是成熟的开源项目。**平台清单见 `docs/platforms.md`**——需要给用户具体建议时从那里取，**不要凭印象编造平台名、提取器数或链接**。
需登录的入口用 `--cookies-from-browser`（已核实存在于 2026.06.09 版），但只适用于你本人有权访问的内容。
只要清单不要视频时，`--skip-download` + `--flat-playlist` 做增量对账快得多；只要音轨用 `-x`。

**转写实用建议**：
- 小规模用 `faster-whisper` 的 `small` 档即可
- **中文素材显式指定语言，非中文素材让模型自动检测**——强制指定错误语言会产出音译乱码
- 谨慎使用 VAD 过滤，参数不当会把整段音频判为静音
- 耗时约为音频时长的 0.3~0.5 倍（CPU 推理），批量请按小时计

### 呈现层的两个视图

不并列，生产关系不同：

- **人看 HTML** —— 主产物，逐篇写，遵循下方规范
- **AI 看专家索引** —— 派生视图，由账本自动聚合，**不手工维护**

专家索引的形式：`$KB_ROOT/_meta/experts/<主题>.md`，每条含页面路径、核心摘要、关联标签。agent 先检索索引命中主题，再精读少数几篇，避免全文扫描。

它的价值随规模增长——二十篇时无用，两百篇时是刚需。**条件启用，不是标配。**

索引由账本生成，不要靠正则扫 HTML——后者在目录结构调整后必然失真。

## 五、页面规范

模板见同项目 `templates/knowledge_page.html`。单文件、离线可读、无外部依赖。

一篇合格的知识页包含：

| # | 要素 | 说明 |
|---|---|---|
| 1 | 顶部返回条 | 相对路径返回上级索引 |
| 2 | 标题区 | 标题 + 标签 + 难度星级 + 元信息行（学习日期 / 素材来源 / 预计阅读） |
| 3 | 一句话总结 | 页面最上方，1-2 句说清核心结论 |
| 4 | 知识地图 | TOC 导航，5-9 节，锚点对齐 |
| 5 | 分节正文 | 每节一张卡片，带序号 |
| 6 | 对比表格 | 并列概念必用，比段落高效得多 |
| 7 | 提示 / 警告块 | 视觉上区分于正文 |
| 8 | 易混点与误区 | 单独一节，表格呈现"误区 vs 真相" |
| 9 | 自测题 | 折叠块，点击展开答案；**避免元信息题**（考日期、考作者），要考理解和应用 |
| 10 | 页脚 | 素材来源与整理日期 |
| 11 | 笔记组件 | 可选，读者随手记疑问并导出，交给 agent 处理 |

两条硬性纪律：

- **不使用彩色 emoji**。各平台渲染不一致，且干扰文本处理。
  明确边界：**禁止** U+1F000 及以上的彩色 emoji 与变体选择符（U+FE0F）；
  **允许**单色符号如 ★ ☆ ✓ ✗，它们不依赖 emoji 字体，各平台渲染一致。
  拿不准时把字符交给 `unicodedata.name()`，名字含 EMOJI 或码位在 U+1F000+ 的一律不用。
- **相对路径铁律**。返回首页 `../../index.html`、域内 `../<主题>/`、跨域 `../../<域>/`。绝对路径会在迁移或换设备时全盘失效。

大文件提示：写超长 HTML 时生成工具可能截断，做法是分片写临时文件再用脚本拼接。

## 六、反模式清单

**工程层面**
- 后台脚本输出非 ASCII 字符，在非 UTF-8 默认编码环境下崩溃 → 启动即重配置 stdout 编码
- 把脚本代码内联进 shell 执行，遇到引号嵌套必炸 → **一律写成文件再执行**
- 多个进程同时写同一个 JSON 账本 → 单写者原则

**内容层面**
- 强制给非中文音频指定中文转写 → 产出音译乱码
- 开启 VAD 过滤但参数不当 → 整段被判静音，产出空文件
- 自测题出成元信息题 → 没有复习价值
- 用绝对路径链接页面 → 迁移即全断

**成页层面**（见 3.1「关于成页：门禁还有第二道」）
- 用字数当质量指标（「补到 ≥N 字」）→ AI 用通用内容凑数，页面外观被抹平、实质差一个量级
- 把发给 AI 的指令写进标题 → 成品上印着「【AI 扩写样例】…（补到 ≥2000 字）」，工单贴在了成品上
- 同一段通用内容复制到多页 → 跨页重复；**单页检测抓不到**，必须跨页比对
- 短视频单独成页再靠扩写撑长 → 该合并成主题页，不该扩写（详下）

**流程层面**
- 批量跑完再统一定档 → 几十篇的通读必然走过场。**转完一批就定档一批**
- 定档后不回写账本 → 下次重跑全部重来
- 跳过链接审计就宣布完成 → 坏链要等用户点开才发现
- 把专家索引当独立产物手工维护 → 必然与正文脱节，应由账本生成

## 七、检查清单

每批次收尾时逐项确认：

- [ ] 账本中本批次条目状态全部为 `done` 或 `failed`，无 `working` 悬挂
- [ ] 所有 `high` / `medium` 条目都有对应的 `page` 路径
- [ ] `page` 路径指向的文件真实存在

**第二道门禁（成页）—— 四档门禁不管这一环，容易整批漏掉：**

- [ ] 本批次新页面自有知识量 ≥ 800 字（去模板外壳与跨页重复后统计）
- [ ] 本批次新页面跨页重复率 ≤ 15%
- [ ] 页面标题无 AI 指令残留（「扩写」「补到」「样例」「大补」等措辞）
- [ ] **外部工具产出的笔记也过了这三条**（自有知识量按**该工具的**模板外壳剥离；
      不达标则合并 / 降级要点页 / 自行改写——**不能退回工具重跑**，重跑只会拿到同一套模板）
- [ ] 外部笔记无 AI 指令残留（提示词与产出混写在同一份文件里是这类工具的常态）
- [ ] 页面**没有**被按字数配额撑长（写作时若用过「补到 ≥N 字」这类要求，本页需重审）

- [ ] 全库链接审计 0 坏链
- [ ] 域索引与根索引已更新，计数与实际一致
- [ ] 本批次新增页面已提交版本库
- [ ] 无孤儿过程文件（有转写但既无页面也未标记跳过）
- [ ] 专家索引已由账本重新生成（若启用）

## 八、路径约定

本 skill 不附带可执行脚本，下表是**命名约定**，不是需要填写的配置项。执行时按你的实际路径替换。

| 占位符 | 含义 | 建议值 |
|---|---|---|
| `$KB_ROOT` | 知识库根目录 | 自选，建议放在版本库内 |
| `$LEDGER` | 账本文件 | `$KB_ROOT/_meta/ledger.json` |
| `$INCOMING` | 过程文件区 | `$KB_ROOT/_incoming/` |
| `$SOURCE_LIST` | 待处理素材清单 | CSV 或 JSON，自选 |

如果你打算自己写脚本：仓库里的 `config.example.json` 是建议的配置结构，可照它读取。
**不要硬编码绝对路径到脚本里**——换设备或换盘符时会全线失效。

目录约定：

```
$KB_ROOT/
├── _meta/           真源数据（账本、专家索引）
├── _incoming/       过程文件（media/ trans/），建议 gitignore
├── _archive/        每日快照，安全网
├── assets/          样式与脚本
├── index.html       根索引
└── <NN_域>/<主题>/  知识页，按域分组
```