knowledge-base

知识库包 — 如何在此工作

本项目采用以来源为依据的知识库布局。核心在于建立闭环证据链：任何规范内容都必须有一条可追溯的链路，回溯到已保存的来源。本技能承载工作流，让模板和 log.md 保持整洁——从模板创建文档时，模板提供结构，而如何操作则由此处说明。

本技能是知识库包的指南。平台的 /open-knowledge 技能（读取／写入／预览／链接／依据规则）仍适用于所有 Markdown 操作；本指南在此基础上叠加知识库工作流。

创建时建立链接

用户会实时查看你的构建过程——编辑器会跟随你正在编写的文件，知识图谱也会随着页面相互链接而在屏幕上逐步构建。你无需管理视图；只需认真撰写：每个页面从写下的那一刻起就带有链接（至少链接到中心／索引页面及其最相关的同级页面——未链接的页面在图谱中不可见），相关页面还应共享一个 cluster: frontmatter 值（例如 cluster: architecture），这样图谱的集群配色就能让地图一目了然。

三个层次

external-sources/   raw sources, saved verbatim     (produced by `ingest`)
      ↓ cite
research/           provisional analysis            (produced by `research`)
      ↓ promote
articles/           canonical, decided knowledge     (produced by `consolidate`)

整个流程为摄取 → 研究 → 整合，对应 Karpathy 的知识库三层模式。每一项下游主张都能追溯到上游的已保存来源。引用 external-sources/ 中的本地路径，绝不要只引用网页 URL——知识库必须能经受链接失效。

Karpathy 的见解是：“维护知识库最乏味的部分不是阅读或思考，而是记账。”人们会放弃 Wiki，因为维护成本超过了感知到的价值。这些流程的存在，就是为了让 Agent 能够不知疲倦地处理这些事务（抓取、总结、交叉链接、标记取代）。跳过交叉链接、取代链或原始来源保存，都会让有用的 Wiki 再次沦为无人维护的 Wiki。

三个流程

每个层次都有一套完整的、带 STOP 门控的流程，并各自以独立技能的形式提供，只有在工作需要时才会加载。由你亲自使用 OK 动词执行流程——当工作符合某个层次时，这是你默认采用的做法，而非直接 write。

流程	所在位置	适用情况
ingest	平台 /open-knowledge 技能（references/ingest-and-sources.md）——其依据规则处处依赖该流程，因此每个项目都会附带此技能，而不仅限于本知识库包。	原样保存共享的 URL／PDF／文件，或者你获取了 URL 来为知识库主张提供依据（保存二进制来源，不进行抓取）。
research	同级技能 /research-with-sources	调查／比较／综合多个来源 → 生成带有 status: draft 和 sources: 的暂定文章。
consolidate	同级技能 /consolidate-notes	确实做出了决定 → 提交带有 status: stable 和 supersedes: 链的规范事实来源。

典型的第二天工作流：用户分享一个 URL → ingest（保存）→ 用户问“现在研究一下这个” → research（生成暂定文章，并按需摄取更多来源）→ 决策确定 → consolidate（生成规范文章，取代研究文章）。

不要默默串联流程。 摄取后，询问是否继续研究。研究后，让用户决定研究结果是否已准备好进行整合。每个流程都按自身要求完成——由用户决定是否进入下一步。

流程自主性门控与会话级自主性。 流程的 STOP 门控（research 的范围界定门控、consolidate 的决策确认门控）不会被会话级的“无需停下来提出澄清问题即可工作”提示覆盖。这类提示适用于琐碎的来回确认（“你指的是哪个文件？”）；门控则用于可能造成不可逆后果的决策。如有疑问，以门控要求为准。

各文件夹规则

external-sources/ — 原样保存的原始来源，不只是引用：实际获取的 URL 文本、PDF 提取文本、引用文件的副本。每个文件的 frontmatter 都包含原始 URL、访问日期以及作者／发布者的相关元数据。由摄取流程生成（无论 URL 是用户分享的，还是你为证实某项主张而自行获取的，均适用）。捕获后不可修改——仅在获取内容过时需要刷新时更新。此处不做分析；分析应放在 research/ 中。

research/ — 综合外部来源形成的临时分析，以 OKF status: draft 存储。由 /research-with-sources 技能生成。每项事实性主张都要引用 external-sources/ 中的特定文档（如果跳过摄取，则引用行内 URL）；不得包含无来源支撑的断言。确保 sources: frontmatter 列表与正文中实际链接的文档一致。团队认定研究结果稳定后，通过 /consolidate-notes 技能将其提升至 articles/。

articles/ — 经团队决策后提交的权威知识，以 OKF status: stable 存储。由 /consolidate-notes 技能生成。包含 supersedes: 链，指向其取代的 research/ 文档（这些文档又引用 external-sources/），因此无需离开仓库即可追溯完整的证据链。这是该领域的事实来源；仅在有新决策取代现有内容时更新。

状态流转

层级	status	设置时机
research/	draft	创建时
articles/	stable	决策后通过 consolidate 提升时

当新文章取代研究文档时，将该研究文档的状态设为 status: deprecated，在文章的 supersedes: 列表中添加其路径，并通过 superseded_by: 指向新文章。

旧版兼容性

较旧的项目可能使用 status: provisional / canonical，以及 sources: 下的字符串条目。将这些形式视为 draft / stable 和来源资源。不要重写未触及的文档；新建或更新已有文件时，使用上述 OKF 格式。

日志规范（必须）

项目根目录下有一个 log.md。凡是在某轮操作中创建、编辑或重组了内容，都要追加一条带日期的记录——每轮一条，而非每个文件一条。静默编辑会破坏审计轨迹。

记录：ingest 运行（新来源）、research / consolidate 运行（临时或权威文章）、三个流程之外的直接 write / edit / move / delete、项目引导运行、文件夹重组，以及 .ok/config.yml 变更。

用 Markdown 链接引用文档，不要只写裸路径——[path/to/doc](./path/to/doc.md)，这样该条目才会显示在这些文档的 links({ kind: "backlinks" }) 中。单独的路径字符串不会在关系图中注册。

由于这个只追加的 log.md 是专用日志，其损坏的链接可能会从 audit 结果中隐藏。干净的结果包含 brokenLinkSuppression 时，表示这些链接已被过滤，而非证明所有原始链接都能解析；不要为了清除这些链接而重写日志历史。

条目格式：

## YYYY-MM-DD: <short title>

- <what was done>
- Files touched: [doc-a](./path/doc-a.md), [doc-b](./path/doc-b.md)
- Sources ingested: [source-slug](./external-sources/source-slug.md)
- Open follow-ups: <topic-1>, <topic-2>

模板

每个文件夹都有一个起始模板（clip、research-log、article）。使用 write({ document: { path, template: "<name>" } }) 创建。模板只包含结构（标题 + frontmatter 框架）——每个字段和章节的含义已在上文说明，不会在文档正文中重复。