learn-llm-wiki

name	learn-llm-wiki
description	用于构建或维护个人 LLM 驱动的知识库。触发词：将资料导入 wiki、查询 wiki 知识、检查 wiki 质量、'添加到 wiki'、'我了解什么关于'，或任何提到 'LLM wiki' 的场景。

Karpathy LLM Wiki

使用 LLM 构建和维护个人知识库。管理两个目录：raw/（不可变原始资料）和 wiki/（编译后的知识文章）。资料进入 raw/，然后编译为 wiki 文章，知识库随时间持续积累。

Karpathy 的核心理念：

• "LLM 负责编写和维护 wiki；人类只负责阅读和提问。"
• "Wiki 是一个持久的、持续积累的知识产物。"

架构

三层结构，均位于用户的项目根目录下：

raw/ — 不可变原始资料。只读，永不修改。按主题子目录组织（例如 raw/machine-learning/）。包含图片的来源必须同时保存本地图片资产，放在对应 raw 文件旁的 raw/<主题>/<raw-slug>.assets/ 目录中。

wiki/ — 编译后的知识文章。完全由 LLM 维护。按主题子目录组织，仅支持一级：wiki/<主题>/<文章>.md。普通文章必须满足：文件名（不含 .md）与正文一级标题 # 标题 完全一致，可直接使用中文文件名。包含两个特殊文件：

• wiki/index.md — 全局索引。按主题分组，使用 Obsidian 原生 [[相对路径.md]] 链接；不要使用 Markdown 表格，也不要使用 [title](path) 形式的普通链接。
• wiki/log.md — 仅追加的操作日志。

SKILL.md（本文件）— 模式层。定义结构和工作流规则。

模板文件位于本文件相对路径的 references/ 目录中。需要 raw 文件、文章、归档页面或索引的精确格式时，请阅读对应模板。

初始化

仅在首次 Ingest 时触发。检查 raw/ 和 wiki/ 是否存在。仅创建缺失的内容；绝不覆盖已有文件：

• raw/ 目录（含 .gitkeep）
• wiki/ 目录（含 .gitkeep）
• wiki/index.md — 标题 # Knowledge Base Index，正文为空
• wiki/log.md — 标题 # Wiki Log，正文为空

如果 Query 或 Lint 找不到 wiki 结构，告诉用户："请先执行一次 ingest 以初始化 wiki。"不要自动创建。

---

Ingest（导入）

将资料抓取到 raw/，然后编译到 wiki/。始终两步都做，无例外。

Fetch（抓取到 raw/）

1. 使用环境中可用的网页或文件工具获取资料内容。如果所有工具都无法访问该资料，请用户直接粘贴内容。

2. 选择主题目录。先检查已有的 raw/ 子目录；如果主题足够接近则复用。仅在真正不同的主题时才创建新子目录。

3. 保存为 raw/<主题>/YYYY-MM-DD-描述性-slug.md。

   • Slug 取自资料标题，kebab-case，最多 60 个字符。
   • 发布日期未知 → 文件名省略日期前缀（例如 描述性-slug.md）。元数据中的 Published 字段仍出现；设为 Unknown。
   • 如果同名文件已存在，追加数字后缀（例如 描述性-slug-2.md）。
   • 包含元数据头部：来源 URL、采集日期、发布日期。
   • 保留原文。清理格式噪声。不要改写观点。
   • 原文中的有意义图片必须下载到 raw/<主题>/<raw-slug>.assets/，并把正文中的图片引用改成本地相对路径，例如 ![原图说明](./<raw-slug>.assets/01-diagram.png)。
   • 图片文件名使用两位序号 + 描述性 slug + 原扩展名，例如 01-system-architecture.png；扩展名未知时根据 Content-Type 推断。
   • 保留图片 alt/caption；若原文无说明，用一句中性描述补充 alt，禁止把图片内容脑补成来源未表达的结论。
   • 跳过头像、logo、按钮、追踪像素、社交分享图标、广告、重复装饰图等低信息图片；如果页面只有这些图片，则不创建 assets 目录。
   • 图片下载失败时不要伪造本地文件；保留原始图片 URL，并在 raw 文中标注 (image unavailable: <reason>)。

   详见 references/raw-template.md。

Compile（编译到 wiki/）

确定新内容的归属：

• 与已有文章核心论点相同 → 合并到该文章。将新来源添加到 Sources/Raw。更新受影响的章节。
• 新概念 → 在最相关的主题目录下创建新文章。文件名必须直接等于该文章的正文一级标题，可使用中文；不要再额外生成英文 slug，也不要沿用 raw 文件名。
• 跨越多个主题 → 放在最相关的目录下。在其他主题的相关文章中添加“另见”交叉引用。

以上并非互斥。单个来源可能需要合并到某篇文章，同时为其中引入的独立概念创建一篇新文章。在所有情况下，检查事实冲突：如果新来源与已有内容矛盾，用来源归属标注分歧。合并时，在合并后的文章中注明冲突。冲突内容分处不同文章时，在两篇中都标注并交叉链接。

详见 references/article-template.md。要点：

• 文件名（不含 .md）必须与正文一级标题完全一致。
• Sources 字段：作者、组织或出版物名称 + 日期，分号分隔。
• Raw 字段：指向 raw/ 文件的 markdown 链接，分号分隔。
• 从 wiki/<主题>/ 出发的相对路径使用 ../../raw/<主题>/<文件>.md（向上两级到项目根目录）。
• wiki 文章正文、“另见”与跨文章引用优先使用 Obsidian wikilink，例如 [[文章标题]] 或 [[文章标题|显示文字]]；只有 Raw 字段和外部 URL 使用 Markdown 链接。
• wiki 文章可以嵌入少量原文图片，但必须引用 raw assets 中的本地文件，不要热链外部图片。路径从 wiki/<主题>/ 出发，例如 ![图：系统架构](../../raw/<主题>/<raw-slug>.assets/01-system-architecture.png)。
• 只保留能帮助理解核心机制、架构、流程、数据结果或界面状态的图片。通常每篇 0-3 张；长文最多 5 张。不要为了“好看”搬运配图。
• 图片必须靠近解释它的段落，并在图下用一句话说明它支持了什么信息；说明必须来自原文或可由图片直接观察得到。

级联更新

处理完主要文章后，检查连锁影响：

1. 扫描同一主题目录下的文章，查找受新来源影响的内容。
2. 扫描 wiki/index.md 中其他主题的条目，查找覆盖相关概念的文章。
3. 更新每篇内容受到实质性影响的文章。每篇更新后的文件刷新其 Updated 日期。

归档页面不会被级联更新（它们是时间点快照）。

导入后处理

更新 wiki/index.md：为每篇涉及的文章添加或更新条目。添加新主题分区时，附上一行描述。索引必须使用列表格式，每篇文章写成三行：

- [[topic/文章标题.md]]
  摘要：一句话摘要
  更新：YYYY-MM-DD

Updated 日期反映文章知识内容最后一次变更的时间，而非文件系统时间戳。详见 references/index-template.md。

追加到 wiki/log.md：

## [YYYY-MM-DD] ingest | <主要文章标题>
- Updated: <级联更新的文章标题>
- Updated: <另一篇级联更新的文章标题>

无级联更新时省略 - Updated: 行。

---

Query（查询）

搜索 wiki 并回答问题。触发示例：

• "我了解什么关于 X？"
• "总结所有与 Y 相关的内容"
• "基于我的 wiki 比较 A 和 B"

步骤

1. 读取 wiki/index.md 定位相关文章。
2. 阅读这些文章并综合出答案。
3. 优先使用 wiki 内容而非自身训练知识。对话中引用来源时，使用项目根目录相对路径，例如 wiki/主题/文章.md；在 wiki 文件内部，vault 内部文章使用 Obsidian [[...]]，Raw 字段和外部 URL 使用标准 Markdown 链接。
4. 在对话中输出答案。除非用户要求，否则不写文件。

归档

当用户明确要求将答案归档或保存到 wiki 时：

1. 将答案写为新 wiki 页面。详见 references/archive-template.md。将对话中的项目根目录相对路径（如 wiki/主题/文章.md）转换为文件相对路径（如 ../主题/文章.md 或同目录下的 文章.md）。
   • Sources：指向答案中引用的 wiki 文章的 markdown 链接。
   • 无 Raw 字段（内容不来自 raw/）。
   • 文件名必须直接等于正文一级标题，例如标题为 Transformer 架构总览 时，文件名为 Transformer 架构总览.md。
   • 放在最相关的主题目录下。
2. 始终创建新页面。绝不合并到已有文章（归档内容是综合答案，非原始素材）。
3. 更新 wiki/index.md。归档页面在索引中的摘要前加 [Archived] 前缀，仍使用列表格式和 [[相对路径.md]] 链接。
4. 追加到 wiki/log.md：

   ## [YYYY-MM-DD] query | Archived: <页面标题>
   

---

Lint（质量检查）

对 wiki 执行质量检查。两类检查具有不同的权限级别。

确定性检查（自动修复）

自动修复以下问题：

索引一致性 — 将 wiki/index.md 与实际 wiki/ 文件（排除 index.md 和 log.md）对比：

• 文件存在但索引中缺失 → 以列表格式添加条目，摘要填 (no summary) 占位符。Updated 使用文章元数据中的 Updated 日期（如有）；否则回退到文件最后修改日期。
• 索引条目必须使用 [[相对路径.md]]。发现 Markdown 表格、[title](path.md) 普通链接或 [[path|alias]] 别名链接时，自动改写为标准列表格式。
• 索引条目指向不存在的文件 → 在原条目中标记 [MISSING]。不删除条目；让用户决定。

内部链接 — 检查 wiki/ 文章文件中的每个 markdown 链接（正文和 Sources 元数据），排除 Raw 字段链接（由下方 Raw 引用检查覆盖）以及 index.md/log.md：

• 目标不存在 → 在 wiki/ 中搜索同名文件。
  • 恰好一个匹配 → 修复路径。
  • 零个或多个匹配 → 报告给用户。

Raw 引用 — Raw 字段中的每个链接必须指向实际存在的 raw/ 文件：

• 目标不存在 → 在 raw/ 中搜索同名文件。
  • 恰好一个匹配 → 修复路径。
  • 零个或多个匹配 → 报告给用户。

图片引用 — 检查 raw/ 和 wiki/ 中的本地图片引用：

• raw/ 中指向 ./<raw-slug>.assets/... 的图片必须存在；不存在时在对应 assets 目录中搜索同名或相似文件，恰好一个匹配则修复路径，否则报告。
• wiki/ 中嵌入的原文图片必须指向 ../../raw/<主题>/<raw-slug>.assets/...；如果指向外部 URL，优先下载到对应 raw assets 并改成本地路径，无法下载则报告。
• 不自动删除图片文件；孤立图片只报告，让用户决定是否清理。

另见 — 在每个主题目录内：

• 添加明显缺失的相关文章交叉引用。
• 移除指向已删除文件的链接。

启发式检查（仅报告）

这些依赖判断力。报告发现但不自动修复：

• 跨文章的事实矛盾
• 已被更新来源取代的过时论断
• 来源分歧处缺少冲突标注
• 没有其他 wiki 文章入站链接的孤立页面
• 缺失的跨主题引用
• 频繁提及但缺少独立页面的概念
• 归档页面引用的来源文章在归档后已被大幅更新

Lint 后处理

追加到 wiki/log.md：

## [YYYY-MM-DD] lint | <N> 个问题发现，<M> 个已自动修复

---

约定

• 全程使用标准 markdown；但 vault 内部 wiki 文章链接使用 Obsidian wikilink，Raw 字段和外部 URL 使用 Markdown 链接。wiki/index.md 中的文章链接一律使用 Obsidian [[相对路径.md]]。
• wiki/ 仅支持一级主题子目录。禁止更深层嵌套。
• 除 wiki/index.md 和 wiki/log.md 外，所有 wiki 文章都必须满足：文件名（不含 .md）= 正文一级标题。
• wiki/index.md 禁止使用 Markdown 表格承载文章索引，避免 Obsidian 对 |、空格、中文标点和复杂文件名的解析歧义。
• 日志条目、Collected 日期和 Archived 日期使用当天日期。Updated 日期反映文章知识内容最后一次变更的时间。Published 日期来自来源（不可用时使用 Unknown）。
• wiki/ 文件内部，Raw 字段中的 markdown 链接使用相对于当前文件的路径；正文和“另见”的内部文章引用使用 Obsidian wikilink。对话输出中使用项目根目录相对路径（如 wiki/主题/文章.md）。
• 图片资产属于 raw 原始资料的一部分。raw 图片引用使用相对于 raw 文件的 Markdown 图片链接；wiki 引用 raw 图片使用相对于 wiki 文章的 Markdown 图片链接；不要把 raw 图片复制到 wiki/。
• Ingest 同时更新 wiki/index.md 和 wiki/log.md。Archive（来自 Query）同时更新两者。Lint 更新 wiki/log.md（仅在自动修复索引条目时更新 wiki/index.md）。普通查询不写入任何文件。