llm-wiki

LLM Wiki

纯 Markdown 格式的知识库。来源放在 raw/ 中（不可变）；你将它们编译成由你维护的 wiki/ 文章。采用带 YAML frontmatter 的本地 Markdown 格式，可在 GitHub 上阅读，也可作为 Obsidian 库打开。无需服务器、数据库或嵌入。

核心理念（Karpathy）：由 LLM 编写并维护 wiki；由人类选择来源并提出问题。知识在导入时编译一次。

调用方式

默认操作是查询。 导入、Lint、Audit 和 Critique 是四种需要明确选择的操作，必须通过动词或明确提出相应需求来启用。其他任何内容都是对 wiki 的查询：直接提问、“我对 X 了解什么”、“总结关于 Y 的所有内容”。无需使用 query 关键字。

以模式参数开头即可直接路由到相应操作：

• ingest（别名 add）- 后续文本为来源：URL、路径或粘贴的内容。
• lint - 健康检查；无需其他输入。
• audit - 后续文本指定要核实的文章或主题。
• critique（别名 scrutinise）- 后续文本指定要检查的文章、主题或粘贴的内容。
• query（别名 ask）- 当问题可能被误认为其他操作时，强制按查询处理。

否则，只有在自然语言明确要求时，才路由到导入、Lint、Audit 或 Critique；其他内容一律作为查询回答。

始终必需，以及按情境启用的要求

所有操作始终遵循：

• 只根据用户的请求执行操作；绝不在后台写入。
• 任何写入都必须基于 raw/ 中已有的来源进行编译，不能直接使用实时 URL 或外部路径。
• 任何写入都要更新 wiki/index.md，并在 wiki/log.md 中追加记录。
• 文章内容发生变化时，更新其 updated。
• 通过新增内容取代过时知识，绝不删除或原地编辑。

其他要求按情境启用。根据下方的分支匹配任务，并在操作前阅读对应文件——指向某个文件意味着必须打开它，而不是将其作为引用。拿不准时就阅读：这比猜测导致 wiki 损坏代价更低。

• 导入任何来源 -> references/ingest.md
• 尚无 wiki/，因此本次导入会初始化它 -> references/init.md
• 确定新 wiki 的用途，或判断 llm-wiki 是否适合该任务 -> references/scoping.md
• 来源是 PDF、Word 文件、幻灯片、图片或电子表格 -> references/rich-format-ingest.md
• 用户想要的是来源中的高价值内容，而非完整内容 -> references/distilled-ingest.md
• 来源是转录文本、聊天记录、访谈笔记或篇幅很长且杂乱的文章 -> references/high-fidelity-ingest.md
• 一次处理多个来源，或单次处理会耗尽上下文 -> references/bulk-ingest.md
• wiki 的主题是代码库 -> references/codebase-wiki.md
• 绘制或维护 mermaid 概念图 -> references/concept-map.md
• 记录或弥补知识缺口 -> references/gaps.md
• local/ 下的个人未提交内容 -> references/local-content.md
• 工作目录中并排存放多个 wiki -> references/multiple-wikis.md
• 将答案保存到 wiki 中作为归档页面 -> references/archive.md
• 旧格式 wiki，或有关 type、索引格式或日志格式的问题 -> references/okf.md
• 在 wiki 上以只读方式运行 graphify -> references/graphify.md

Lint、Audit 和 Critique 各自会根据下方相应部分的说明加载自己的参考文件。

设计理念

对于以下各节未涵盖的内容。

• 在摄取时过滤，而不是在保留阶段过滤。 判断哪些内容值得保留，并在来源到达时剔除机密信息。
• 以取代为准，而不是随时间衰减。 知识不会定时过期。当新信息取代旧信息时，将旧文章标记为过时，指向替代文章，并予以保留：已被取代的决策仍能解释当前状态。
• 以证据为准，而不是置信度评分。 绝不为某项说法附加 0.85 这样的数字。说明哪些来源证实了它、哪些来源与之矛盾，以及上次确认的时间。
• Git 是审计记录。 历史和回滚依靠版本控制，而不是专门设计的版本字段。建议使用 git 仓库。
• 由调用触发，人在环路中。 只有用户提出要求时才采取行动；不进行未经监督的后台自动化写入 wiki。由用户整理内容；由你负责记录。
• 仅限文本且自包含。 使用纯 Markdown、相对链接和 YAML frontmatter。普通工具（grep、git、Agent 的文件和网页工具）都可以。外部服务、向量存储、嵌入流水线、知识图谱数据库，以及多 Agent 同步或治理层都不适用——索引加 grep 足以应对个人 wiki 的规模。

架构

位于用户的项目根目录下：

raw/ - 源材料，事实来源。不可变意味着捕获后不再编辑，并不意味着必须保留未经筛选的原始内容：raw/ 文件可以是逐字副本，也可以是经过审核、从冗长来源中提炼的内容（fidelity: distilled，references/distilled-ingest.md）（优先采用）。写入后，两者都只能读取，不能修改。可按主题建立子目录，例如 raw/machine-learning/。

wiki/ - 由你维护的整理后文章。仅允许一层主题子目录：wiki/<topic>/<article>.md。包含 4 个特殊文件：

• wiki/README.md - 为不了解此技能而打开 wiki 的读者提供说明。大部分内容固定；在初始化时创建。
• wiki/index.md - 采用 OKF 索引格式的全局目录：按主题分节，每项格式为 * [Title](path) - summary，不含 Updated 列。查询入口。
• wiki/log.md - 仅追加的操作日志，带有便于 grep 检索的前缀。
• wiki/gaps.md - 已知未知项的登记表：被提及但尚未撰写的概念，以及 wiki 无法回答的问题。

local/（可选）- 不纳入 git 的个人 Markdown 内容：草稿、工作笔记、私人来源。与 raw/ 和 wiki/ 同级，并在 wiki 的 .gitignore 中排除。无需纳入索引、日志、缺口记录、级联更新和审计。规则：local/ 可以链接到 wiki/ 和 raw/，但任何已提交文件都不得链接到 local/（其他克隆中链接会失效；路径也会泄露到 git 中）。完整规则和转移路径：references/local-content.md。

SKILL.md（此文件）- 架构层。模板位于 references/。

文件格式

每篇文章和原始文件都以 YAML frontmatter 开头，后接标准 Markdown。Frontmatter 可供机器读取（Obsidian 属性、Dataview 查询）；正文链接可在 GitHub 和 Obsidian 的关系图与反向链接中呈现。

文章 frontmatter：

---
title: Transformer Architectures
type: concept          # concept | entity | archive
topic: machine-learning
resource:              # optional canonical URI of the asset an entity describes
created: 2026-04-03
updated: 2026-04-03
status: current        # current | stale
superseded_by:         # relative path to replacement, set only when status: stale
tags: [transformers, attention]
aliases: []
---

• updated 是“知识最后变更”日期的规范字段；Lint 会读取它。内容变更时更新，而不是文件被触及时更新。索引不包含此字段（OKF 将新鲜度保存在 frontmatter 中）。
• type: archive 标记已结晶的查询答案（references/archive.md）；归档内容仅反映某个时间点，永远不会级联更新。
• resource 是 entity 文章所描述资产（表、服务、API、仓库）的规范 URI，与正文中的 Sources/Raw 来源记录行不同。此字段可选，抽象的 concept 文章不填写。对应 OKF 的 resource 字段（references/okf.md）。
• status 和 superseded_by 用于管理取代关系（参见 Ingest > Conflicts and supersession）。当前文章的 superseded_by 留空。
• tags 和 aliases 为可选字段，供 Obsidian 和 Dataview 使用。

本知识库是 Open Knowledge Format（OKF）v0.1 包的超集，因此 OKF 工具无需导出即可读取。遇到采用旧格式的知识库且正处于 Lint 或 Ingest 过程中、创建或迁移 type 字段时，或有任何关于索引或日志格式的问题时，MUST 阅读 references/okf.md 并遵循其中的说明。

链接和路径

在 wiki/ 文件中，所有链接都相对于当前文件：

• 同一主题：[Other Article](other-article.md)
• 不同主题：[Other Article](../other-topic/other-article.md)
• 原始文件：[Source](../../raw/topic/file.md)（向上两级到项目根目录）

在对话输出中，使用相对于项目根目录的路径，例如 wiki/topic/article.md。superseded_by 使用与正文链接相同的相对文件路径格式。

特殊文件

wiki/README.md 面向不具备此技能的读者，介绍 raw/wiki 的划分、frontmatter 字段、以取代而非删除的原则，以及 index.md、log.md 和 gaps.md 的用途。保持内容概括且稳定；应指向本文件中的流程，而不是照搬这些流程。模板：references/templates/wiki-readme-template.md。

wiki/index.md 是 Agent 处理任何查询时首先阅读的文件：由人工维护，即使 Dataview 可以生成其中部分内容，它仍是规范版本。

wiki/log.md 采用只追加的方式并按时间顺序记录；git 历史是规范记录。OKF 更新日志格式：

• 使用由新到旧排列的 ## YYYY-MM-DD 日期标题；运行 grep "^## " wiki/log.md | head 可查看最近日期。
• 每次操作在对应标题下写一条项目符号，以加粗的操作词开头：**Ingest**、**Query**、**Lint**、**Audit**、**Critique**，以及 **Supersession**。
• 在今天的标题下追加；如果该标题不存在，就在顶部创建。
• 项目符号内容保持精简：链接到涉及的文章；变更内容由文章正文和 git diff 体现。

wiki/gaps.md 以两种条目类型登记已知未知：

• wanted - 文章引用了某个概念，但没有页面介绍它。
• question - 来源提出的问题或用户询问的问题，知识库无法回答。

条目按主题分组，并依据需求证据排序——哪些文章引用了该缺口、问题被提出的频率——绝不按分数排序。在 ingest、query 和 lint 过程中记录，不由后台进程收集；通过链接到解决方案来关闭条目，而非删除。可用 grep 查找：grep "^### \[open\]" wiki/gaps.md。完整格式、记录规则和生命周期：references/gaps.md。

初始化

只有首次 Ingest 到不含 wiki/ 的目录时，才会触发初始化。**在创建任何内容之前，你必须阅读 references/init.md 并遵循其中的说明。**它以范围界定步骤（references/scoping.md）开篇：llm-wiki 适合个人长期使用，也适合团队围绕某个项目或计划使用，但不适合作为跨产品的长期存储，也不适合供外部利益相关者查询。写入文件前先确定范围；它将约束之后的每项操作。

如果 Query 或 Lint 找不到 wiki 结构，请检查是否存在多个 wiki 子目录（每个子目录都有自己的 wiki/ 和 raw/）——这属于多个独立 llm-wiki 并列的多 wiki 设置，而不是尚未初始化的 wiki。只有两者都不存在时，才告诉用户：“请先运行一次 ingest 以初始化 wiki。”不要自动创建。在跨多个 wiki 查询或维护之前，请阅读 references/multiple-wikis.md。

---

Ingest

将来源抓取到 raw/，然后编译到 wiki/——始终两步都要做。

在 ingest 之前，你必须阅读 references/ingest.md 并遵循其中的说明。

决定保留多少来源内容

在抓取之前决定；这将决定哪些内容会进入 raw/。

• 逐字保留（默认）——忠实副本，是 Audit 检查时所依据的不可变事实来源。除非用户另有要求，否则使用此模式。
• 提炼——仅保留高价值内容，删除填充内容。当用户提出“有价值的内容”“高价值部分”“有用的内容”“只保留精华”“要点”“重要内容”或类似要求时，选择此模式。遵循 references/distilled-ingest.md，通过_删除_填充内容来提炼，而不是泛化或抹去具体信息；最后必须单独安排一个子 Agent 进行审查，确保没有删掉关键内容。

每个来源选择一种模式。丰富的文件格式（如 docx 文字记录、PDF）本身并不能决定模式：先转换为 Markdown，再按所选模式逐字保留或提炼。

**对于篇幅长、内容嘈杂的来源，应主动提议提炼；默认绝不逐字倾倒。**如果来源冗长且信息密度低——例如会议文字记录、聊天导出、访谈笔记或杂乱冗长的讨论串——且用户未指定模式，则在写入 raw/ 之前先提供选择。说明提炼的做法：保留关键信息，同时保留所有意图、含义和可能有用的上下文；进行总结和去重，但忠实于原文。同一时间也要说明代价——Audit 将无法再与已舍弃的原文进行核对——然后让用户选择。

**只从 raw/ 编译。**先将每个来源以 Markdown 格式放入 raw/，再进行编译；绝不可直接从实时 URL 或外部路径编译（临时文件会消失，URL 可能变化；Raw 链接必须持久有效）。raw/ 中已有的 Markdown 文件可直接编译。

编译过程中的判断

说服性来源。 如果来源是在论证而非报告——例如观点文章、供应商的说法或战略备忘录——在将其编译为定论之前，考虑先进行一轮批判分析（references/critical-analysis.md）。报告推理风险，并让用户决定；通常的处理结果是将有争议的主张归于其来源，或在 gaps.md 中记录相关问题。

长篇和嘈杂的来源。 转录稿、聊天记录、长篇文章和访谈笔记包含许多细节，一轮编译可能会在不知不觉中丢弃。遵循 references/high-fidelity-ingest.md：先列出持久有效的内容（决策、主张、数字、专有名词、未决问题），再根据列表撰写文章，然后对照原始来源将文章重读一遍。保留来源中的确切术语、数字和限定语；在最重要的主张旁边附上内联引文和定位信息（章节、页面、时间戳），并链接原始来源。只有单一主张的短篇来源只需按常规方式编译。

概念图（可选）。 当多篇文章之间存在难以用文字清晰表达的关系——例如分支、汇合、替代关系或因果链——小型 Mermaid 图表可能很有用（references/concept-map.md）。current 文章中的图表承担重要作用：它带有 map-sources 标记，并会在级联更新时维护。type: archive 页面中的图表则是带日期的快照。

冲突与替代

检查新来源是否与现有内容相矛盾。

• 存在分歧，且双方观点仍都合理 -> 用证据链在文中标注冲突，并分别注明观点归属：“使用 Redis 进行缓存（来源 A、来源 B）；来源 C 报告使用 Memcached。” 不要凭数字选定胜方。如果相互冲突的主张位于不同文章中，应在两篇文章中都注明，并添加交叉链接。

• 新来源明确取代旧知识 -> 标记为替代，不要删除。在旧文章中设置 status: stale 和指向替代内容路径的 superseded_by:，并在标题正下方添加提示框：

  > [!warning] Superseded by [New Article](new-article.md) (2026-04-03). Kept for history.
  

  按照常规 current 文章的方式创建或更新替代内容，并在正文中说明它取代了什么。其余内容由 Git 历史保留。

批量和并行导入

对于一次导入多个来源，或单轮处理会耗尽上下文的情况，应并行提取，串行编译。完整协议和导入提案架构见 references/bulk-ingest.md。

这些规则可防止并行批次破坏知识库：

• 分发任务前先分配主题。 阅读现有的 raw/ 和 wiki/ 主题，确定本批次的主题集合，并将其交给每个子 Agent，避免它们各自编造不同的名称。
• 子 Agent 负责提取，不负责编译。 每个子 Agent 只能在 raw/<assigned-topic>/ 下写入内容，并返回结构化提案，不得修改 wiki/、index.md 或 log.md。
• 编排者是唯一有权写入 wiki/、index.md 和 log.md 的角色。 编排者基于同一视图合并提案：将同一概念的提案合并为一篇带有共享证据链的文章，按来源日期顺序应用，以便优先处理最新内容的替代关系，然后执行级联更新，并仅更新一次索引和日志。
• 提交前设检查点。 展示摘要（新建、合并、替代、发现的冲突），并等待用户确认后再为该批次执行 git commit。十篇证据充分的文章胜过五十篇内容单薄的文章。

---

查询

搜索知识库并回答问题。触发示例：“我了解了哪些关于 X 的内容？”“总结 Y 的所有内容”“比较 A 和 B”。

步骤

1. 阅读 wiki/index.md，查找相关条目。
2. 阅读这些条目。若索引遗漏了相关内容，请沿着正文链接和反向链接查找：grep -rl "article-name.md" wiki/ 可列出链接到该页面的页面。
3. 综合整理答案。优先采用 wiki 内容，而非训练知识。使用 Markdown 链接引用：[Article Title](wiki/topic/article.md)（相对于项目根目录）。
4. 如果引用的条目标记为 status: stale，请注明，并指向替代条目。
5. 如果存在 local/，也要搜索，并将每个命中结果标注为 local/ (uncommitted)，以免将其误认为共享知识（references/local-content.md）。一次查询只针对一个 wiki；绝不能悄悄纳入用户的另一个 wiki。如果问题涉及多个 wiki，请说明这一点，并询问要参考哪个 wiki（references/multiple-wikis.md）。
6. 在对话中回答；除非用户要求，否则不要写入文件。
7. 记录未解问题。 如果 wiki 无法回答或只回答了部分问题，且问题属于其主题范围，请提议将其记录到 wiki/gaps.md：在匹配的 gap 中追加今天的日期作为需求证据，或新增一个 question 条目。只有获得用户同意后才能记录；普通查询不会写入任何内容（references/gaps.md）。

如果用户询问的是推理是否成立，而不是 wiki 中的说法，请切换到批判分析（references/critical-analysis.md）。

凝练（归档）

当用户要求将答案保存到 wiki 时，你必须阅读 references/archive.md 并遵循其中的说明。 答案将成为一个 type: archive 页面，使探索成果像摄入的来源一样不断积累。

---

Lint

分两级进行健康检查：确定性问题会自动修复；需要判断的问题只报告，绝不悄悄改写。 你不得擅自改写条目正文。Lint 用于检查内部一致性；若要依据来源核验条目，请使用 Audit。

修复任何内容前，你必须阅读 references/lint.md 并遵循其中说明——该文件列出了每一级的所有检查项及其修复行为。以下项目只是索引，不是操作流程。

• 确定性问题（自动修复）： 索引一致性、内部链接和原始链接、frontmatter、See Also、日志保留、wiki 技能文件中的链接、概念图时效性、gap 登记表，以及 local/ 泄漏防护。可安全修复，无需询问。
• 启发式问题（仅报告）： 事实矛盾、未标记为 stale 的内容替代、孤立页面、缺少交叉引用、未记录的概念（建议添加为 wanted gap）、已有条目可回答的未解决 gap、多概念条目、内容已偏离的归档、价值较低的概念图、团队 wiki 偏离其声明的范围或时间界限，以及缺少根目录 SKILL.md、CLAUDE.md、scope 区块或 wiki .gitignore。指出这些问题；绝不自动修复。

两个无需依赖、只读的辅助工具可通过 uv 运行，帮助完成确定性检查：scripts/lint_wiki.py <project-root> 用于检查结构问题（frontmatter、索引、链接、原始链接、local/ 泄漏防护），scripts/lint_mermaid.py 用于检查概念图有效性。应运行这些工具，而不是临时编写 shell 脚本；如果没有 uv，请使用 grep 和文件工具，并通过目视检查 Mermaid。辅助工具负责检测；修复由你完成。

Lint 后

在 wiki/log.md 的今天日期标题下记录：

* **Lint**: <N> issues found, <M> auto-fixed.

审核

根据文章引用的 raw/ 来源，核实文章中的说法。Lint 检查内部一致性；审核检查外部忠实度——引用的来源是否确实支持文章中的说法。此功能为可选项，由用户针对指定文章或主题主动调用，绝不自动运行；它会完整读取每个引用来源。触发语句：“审核 X”“检查 Y 的引文”“wiki 现在是否仍与其来源相符”。

审核前，必须阅读 references/audit.md 并遵循其中的说明——该文件包含目标选择、说法提取、针对每个来源的子 Agent 提示词，以及判定结果格式。

• 仅报告——绝不擅自改写文章内容（与 Lint 的启发式层级遵循相同界限）。未通过核实的说法会标出，供用户修正、替换或接受。
• 针对每个引用来源并行启动一个只读子 Agent，然后按问题严重程度从高到低汇总。

审核后

在 wiki/log.md 今天的日期标题下记录：

* **Audit**: [<article or topic>](<path>) - <N> claims, <S> supported, <U> unsupported/partial.

如果用户要求保留审核结果，将其整理为 type: archive 页面，并引用经过审核的文章——阅读 references/archive.md 并遵循其中的说明。

---

评析

检查来源或文章中的推理，并报告其中经得起检验的部分：论证结构、隐含假设、逻辑谬误、偏见风险、内部一致性。审核会根据引用的 raw/ 来源检查外部忠实度；评析检查内部合理性，不会对照现实核查经验性说法。与审核一样，此功能为可选项，由用户主动调用，只读且绝不改写内容。它针对用户指定的任何内容运行——raw/ 来源、wiki/ 文章或粘贴的内容——无需 raw/。触发语句：“评析 X”“这个论证合理吗？”“这里有哪些假设？”“对 Y 中的推理进行压力测试”。

开始评析前，必须阅读 references/critical-analysis.md 并遵循其中的分析步骤和输出结构——不要凭记忆操作。 如果推理合理，请明确说明；不要无中生有地挑刺。目标较多时，针对每个目标并行启动一个只读子 Agent，然后按问题最薄弱到最扎实的顺序分组呈现。

评析后

在 wiki/log.md 今天的日期标题下记录：

* **Critique**: [<article, topic, or source>](<path>) - <overall assessment>.

评析本身不会写入其他内容。经用户同意后，可将分析整理为 type: archive 页面，并引用经过评析的目标——阅读 references/archive.md 并遵循其中的说明——也可以将发现的假设或未解决问题记录为 wiki/gaps.md 中的 question 类型缺口（references/gaps.md）。

---

可选：将 graphify 用作外部视角

如果 graphify 技能或工具可用，可将其用于 wiki，作为临时的只读知识图谱视角：查看文章之间的关联、发现孤立文章和缺失的交叉引用、在摄取前梳理大型 raw/ 语料库，或回答涉及大量关联的问题。Markdown 始终是事实来源；graphify-out/ 是生成内容，并已加入 gitignore，绝不提交。仅通过常规 llm-wiki 操作处理发现的问题（添加 See Also、在 gaps.md 中记录条目、标记内容已被取代、回答 Query），并先对照 Markdown 进行核实。使用 graphify 时，先阅读 references/graphify.md 并遵循其中的说明。

---

注意事项

• Wiki 内的路径方向。 从 wiki/<topic>/ 出发，原始文件位于上两级目录（../../raw/<topic>/file.md）；同一主题的文章只需写文件名。../ 层级数写错是最常见的链接失效原因。
• 让索引前缀与文章保持同步。 内容被取代或归档时，应在同一轮操作中为索引摘要设置或切换 [Stale]/[Archived] 前缀；如果核心论点有变，也要更新摘要。
• 长篇来源的细节容易悄然流失。 直接将转录内容编写成散文时，论断和精确数字可能会被删掉或弱化。先列出需要保留的要点，再对照来源重读文章后再完成（references/high-fidelity-ingest.md）。
• 只删除 raw/ 中的富格式原件。 将二进制文件提取为 Markdown 后，只有在原件位于 raw/ 中（仅含 Markdown）且已确认提取内容忠实无误时，才删除原件。Downloads 或临时目录中的 PDF 属于用户：将 Markdown 副本提取到 raw/，原件保留不动。
• 缺口代表探索前沿，而非愿望清单。 只有证据支持时才记录 wanted 页面或未解决的 question——例如文章引用了它，或查询提出了它；通过添加解决链接来填补缺口，不要让已填补的缺口一直留着（references/gaps.md）。
• 概念图会悄然过时。 文章变更时，正文会随之更新，但概念图可能仍在沿用旧关系。级联更新时要重新检查，确保 map-sources 标记准确；如果概念图不再有价值，就将其移除（references/concept-map.md）。