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 字段：

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

四条判据，逐条过：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

成页的三条硬指标

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

为什么字数不能当指标

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

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

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

短源怎么办

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

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

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

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

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

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

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

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

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

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

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

额外一条：外部笔记要查 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。核心字段：

同一批次只允许一个进程写账本。 并发写 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 不重复实现，只定义契约。

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

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

一篇合格的知识页包含：

两条硬性纪律：

• 不使用彩色 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 不附带可执行脚本，下表是命名约定，不是需要填写的配置项。执行时按你的实际路径替换。

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

目录约定：

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