knowledge-gatekeeper · 知识库治理层
别人解决「怎么把视频变成笔记」，本 skill 解决「什么配进笔记库」。 本文件自包含：读完即可开工，不需要外部文档。
一、定位
转化工具（take-notes、video2knowledge 等）已经能把信息源变成结构化笔记。本 skill 不重复那部分，只做它们上面缺的一层治理：
- 进什么 —— 四档质量门禁
- 怎么攒 —— 单一账本 + 断点续跑
- 怎么不丢 —— 防丢闭环
以及成文时的页面结构规范。
前置假设：你已经能把素材转成文字（转写稿、文章正文），本 skill 从拿到文字稿开始。
二、五条核心原则
- 未提交 = 不存在。页面生成后当轮必须提交版本库。
- 账本是唯一事实源。状态、定档、产出路径只记在一处。
- 质量门禁零例外。未经定档的内容不得入库。
- 只加不删。批量操作默认可回滚，删除前先移位而不是直接删。
- 人机同源。同一批内容同时产出人看页面与 AI 可读索引。
三、三根纵切机制（核心）
治理不是流水线上的某一环，而是贯穿全程的三根支柱。
3.1 四档质量门禁
这是整条链路最重要的一步，不可跳过、不可批量放行。
逐篇通读转写稿，按下表定档，写入账本的 quality 字段：
| 档 | 判据 | 处置 |
|---|---|---|
high | 体系化干货，信息密度高，标题与内容一致 | 完整入库 |
medium | 有可提取的方法论，但夹杂冗余或跑题 | 只精炼有效部分 |
low | 标题党、引流广告、内容空洞、泛娱乐 | 不入库 |
reject | 与知识库主题无关 | 跳过 |
四条判据，逐条过：
- 标题与内容是否一致 —— 最有效的单一指标，标题党一眼可辨
- 是否有引流广告 —— 中后段突然出现加群/带货/引流，通常意味着质量断崖
- 信息密度如何 —— 通读后能否复述出 3 个以上具体知识点
- 是否泛娱乐化 —— 观点输出多、事实和方法少
注意 medium 不是排除项。 它进库，但规格不同——只取有效部分，不做完整展开。审查的产出不是"要不要"，是"以什么规格要"。
这一步必须逐篇通读，无法自动化。也正因如此，它是整套方法里最难被复制的部分。
3.2 单一账本
所有素材的状态、定档、产出路径只记在一个 JSON 文件里，每完成一步立即回写，不做批量补记。
它带来三个能力：
- 断点续跑 —— 重跑命令 = 跳过
done的命令 - 积压可见 ——
transcribed（已转写未定档）是一个可查询的队列 - 统计可信 —— 覆盖率、通过率由账本算出，不是估的
完整结构见 examples/ledger.schema.json。核心字段：
| 字段 | 用途 |
|---|---|
id | 素材唯一标识，整条链路的主键 |
status | pending → working → transcribed → done / failed |
quality | high / medium / low / reject，由门禁写入 |
media / transcript | 过程文件路径 |
page | 成页路径，low / reject 时留空 |
fail_reason / retry_count | 失败原因与重试次数 |
同一批次只允许一个进程写账本。 并发写 JSON 会互相覆盖，这是最容易踩且最难排查的坑。
3.3 防丢闭环
以下五条来自真实事故（一次误操作丢掉 90 页未提交内容），零例外。
- 禁止对知识库执行
git clean -fd，无论带不带路径参数。清理残留一律先git status --short人工核对，只做精确回退。 - 禁止把
git reset --hard当作回退手段。需要回退先git stash push（保留未跟踪文件）或先做全量快照。 - 任何破坏性操作前（reset / clean / rm / checkout -- .），先确认目标文件是否已跟踪；未跟踪文件必须先复制到备份区。
- 页面建完即提交。任何 HTML / MD / 资产一经生成或修改，当轮结束前必须提交。禁止跨轮持有未提交内容。
- 依赖库同步提交（CSS / JS / 字体等），禁止裸放在工作区。
附加建议：每日自动生成一次全量快照归档到 _archive/，作为最后的安全网。
四、四层横切（流程背景）
治理机制作用的舞台。这层的工具已经很成熟，本 skill 不重复实现，只定义契约。
① 获取 → ② 转译 → ③ 分流审查 → ④ 呈现
| 层 | 做什么 | 治理机制在此层的作用 |
|---|---|---|
| ① 获取 | 拉取清单，对比新增；下载或抓正文 | 账本记来源与状态；门禁做清单去重 |
| ② 转译 | 提音频、转文字 | 账本记转写路径；失败重试判定；过程文件不落临时目录 |
| ③ 分流审查 | 四档定档 | 门禁主战场；账本写定档结果 |
| ④ 呈现 | 成页、索引、审计 | 账本记成页位置；0 坏链审计；建完即提交 |
关于层 ① 和层 ②：不同平台有不同的获取方式和各自的服务条款，请自行实现并遵守对方规则。常见约束提前预期——批量连续请求易触发频率限制，长任务中凭据会失效需自动重建，单条失败不应中断整批。
转写实用建议：
- 小规模用
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。各平台渲染不一致，且干扰文本处理。
- 相对路径铁律。返回首页
../../index.html、域内../<主题>/、跨域../../<域>/。绝对路径会在迁移或换设备时全盘失效。
大文件提示：写超长 HTML 时生成工具可能截断，做法是分片写临时文件再用脚本拼接。
六、反模式清单
工程层面
- 后台脚本输出非 ASCII 字符，在非 UTF-8 默认编码环境下崩溃 → 启动即重配置 stdout 编码
- 把脚本代码内联进 shell 执行，遇到引号嵌套必炸 → 一律写成文件再执行
- 多个进程同时写同一个 JSON 账本 → 单写者原则
内容层面
- 强制给非中文音频指定中文转写 → 产出音译乱码
- 开启 VAD 过滤但参数不当 → 整段被判静音，产出空文件
- 自测题出成元信息题 → 没有复习价值
- 用绝对路径链接页面 → 迁移即全断
流程层面
- 批量跑完再统一定档 → 几十篇的通读必然走过场。转完一批就定档一批
- 定档后不回写账本 → 下次重跑全部重来
- 跳过链接审计就宣布完成 → 坏链要等用户点开才发现
- 把专家索引当独立产物手工维护 → 必然与正文脱节，应由账本生成
七、检查清单
每批次收尾时逐项确认：
- 账本中本批次条目状态全部为
done或failed，无working悬挂 - 所有
high/medium条目都有对应的page路径 -
page路径指向的文件真实存在 - 全库链接审计 0 坏链
- 域索引与根索引已更新，计数与实际一致
- 本批次新增页面已提交版本库
- 无孤儿过程文件（有转写但既无页面也未标记跳过）
- 专家索引已由账本重新生成（若启用）
八、配置
使用前把配置模板复制为 config.json 并填写：
| 占位符 | 含义 | 建议值 |
|---|---|---|
$KB_ROOT | 知识库根目录 | 自选，建议放在版本库内 |
$LEDGER | 账本文件 | $KB_ROOT/_meta/ledger.json |
$INCOMING | 过程文件区 | $KB_ROOT/_incoming/ |
$SOURCE_LIST | 待处理素材清单 | CSV 或 JSON，自选 |
不要硬编码绝对路径到脚本里，从配置读取。
目录约定：
$KB_ROOT/
├── _meta/ 真源数据（账本、专家索引）
├── _incoming/ 过程文件（media/ trans/），建议 gitignore
├── _archive/ 每日快照，安全网
├── assets/ 样式与脚本
├── index.html 根索引
└── <NN_域>/<主题>/ 知识页，按域分组