wiki-ingest

Wiki Ingest

将来源添加到 wiki。阅读来源，与用户讨论，编写摘要页面，更新实体／概念页面，并维护索引、概览和日志。

前置条件

从当前目录及其上级目录开始搜索 SCHEMA.md，或在常见的 wiki 位置（~/wikis/）中搜索。如果找不到，请告知用户先运行 wiki-init。

阅读 SCHEMA.md，了解：wiki 根路径、页面 frontmatter 格式、交叉引用约定、日志条目格式、索引分类体系。

链接样式。 从 SCHEMA.md 中读取 link_style:。如果缺少此字段，或 <wiki-root>/config/link-style.md 不存在，则默认使用 obsidian，并将 [[slug]] 用作交叉引用形式。否则，阅读 <wiki-root>/config/link-style.md，了解确切的生成和解析规则。下文中你编写的每个交叉引用和引用 slug 目标都必须遵循该文件的 ## Emit 规则。扫描现有页面时（步骤 7 中的反向链接审计），必须遵循其 ## Parse 规则。

流程

1. 接收来源

来源可以是：

• 文件路径 — 直接读取；如果 raw/<filename> 中尚无副本，则复制到该路径
• URL — 使用 browse skill 获取；保存到 raw/<slug>.<ext>
• 粘贴的文本 — 使用用户提供的内容

2. 完整阅读来源

阅读全部内容。对于较长的来源，分段阅读。不要跳过任何内容。

3. 展示要点 — 写入任何内容之前

告知用户：

• 3-5 条要点
• 这会引入或更新哪些实体／概念
• 是否与 wiki 中的任何内容矛盾（先重新生成索引 — python bin/generate-index.py — 然后阅读 wiki/index.md 和相关页面进行核对）

询问：“有什么内容是你希望我着重强调或弱化的吗？”

等待用户回复后再继续。

4. 生成 slug

使用小写字母、连字符，不含特殊字符。 示例：“Attention Is All You Need” → attention-is-all-you-need

5. 编写来源摘要页面

编写 wiki/pages/<slug>.md：

---
title: <source title>
category: <one of the wiki's Index Categories — e.g. Sources>
summary: <one-line description for the index>
tags: [<relevant tags>]
sources: [<slug>]
created: <today>
updated: <today>
---

# <Source Title>

**Source:** <original URL or file path>
**Date ingested:** <today>
**Type:** <paper | article | transcript | code | other>

## Summary

<2-3 paragraph synthesis — your own words, not abstract copy-paste>

## Key Takeaways

- <bullet>

## Entities & Concepts

<list of entities/concepts as cross-reference links — emit each in the wiki's link_style; see config/link-style.md>

## Relation to Other Wiki Pages

<how this connects to or updates existing knowledge>

5b. 边写边引用 — 不要跳过

起草 Summary、Key Takeaways 以及其他任何文字部分时，每个非公知事实都必须附带脚注。阅读 SCHEMA.md 中的 Citations 部分，了解完整约定。

两种引用类型，三种有效目标：

Quote:     [^N]: <target> <locator> — "<verbatim quote>"
Synthesis: [^N]: <target> <locator> [synthesis] — <what supports the claim>

<target> is one of:
  <slug-reference>     — a source wiki page, written in the wiki's link_style
                         (preferred for the source you're ingesting)
  raw/<file>           — a path, for drive-by citations to other local files
  <URL>                — a live URL or post

对于正在导入的来源，其 slug 引用目标是 <this-source-slug>，格式须遵循 config/link-style.md 中的规定。wiki-ingest 正在创建此页面，因此阅读该页面时目标将已存在。

行范围来源标注 — 对可按文本定位的来源为必需项。 如果你引用的原始文件是 Markdown、纯文本、代码或缓存的 HTML，则每个指向该文件的脚注都必须在语义定位符之后带有行范围标记：L<start>-<end>（单行则为 L<n>）。阅读原始文件时，记录所引用段落的行号——对于引文，记录引文所取自的行；对于 [synthesis] 主张，记录所概括内容对应的行范围。示例：

[^1]: [[<this-source-slug>]] §3.2 L142-143 — "We employ h = 8 parallel attention layers"
[^2]: [[<this-source-slug>]] §3.2-5.3 [synthesis] L138-202 — encoder/decoder + attention describe the architecture

没有稳定行号的来源 — PDF、文字记录以及没有本地缓存副本的实时 URL — 不受此要求限制：保留语义定位符（p.N、[HH:MM:SS]、URL 锚点），省略 L…。

如果无法为某项主张提供任何一种引用，你就没有引用。找到引用、弱化主张（“论文表明……”），或删除该主张。

脚注放在页面底部、所有章节之后。按首次引用的顺序依次编号。

5c. 继续之前的自检

重新通读一遍草稿。分三轮检查：

1. 未添加脚注的说法——检查是否有事实性说法没有脚注（这是长时间摄取过程中最常见的失败模式）。对每一处，添加脚注或修改措辞。
2. 缺少行号范围——对于每条目标为可通过文本定位的原始文件（markdown / 纯文本 / 代码 / 缓存的 HTML）的脚注，确认其中包含 L… 标记。文本来源的脚注没有行号范围就是不完整的：返回原始文件，找到对应行并添加标记。PDF / transcript / 实时 URL 等豁免来源可以不添加。
3. 链接解析——收集本页中你写的所有 [[slug]]，确认每个都能解析到现有的 wiki/pages/<slug>.md，或解析到你在本次摄取中创建的页面。参见 SCHEMA.md 中的 Concept Identity 规则。任何无法解析到上述页面的 [[slug]] 都是幻觉链接：删除它，或创建它指向的页面。这相当于 wiki-lint 在整个 wiki 范围内执行的损坏链接检查的行内版本——现在发现问题，可以从一开始就确保链接图谱可信。

只有三轮检查都没有问题后，才能继续处理实体页面。

6. 更新实体和概念页面

对于此来源涉及的每个实体 / 概念：

• 页面已存在： 阅读页面，在相关部分添加内容或更新内容，将此来源添加到 frontmatter 的 sources 列表中，并更新 updated 日期
• 页面不存在： 创建页面：

---
title: <Entity or Concept Name>
category: <one of the wiki's Index Categories — e.g. Entities or Concepts>
summary: <one-line description for the index>
tags: [entity | concept]
sources: [<this-source-slug>]
created: <today>
updated: <today>
---

# <Name>

## Description

<synthesis across all sources that discuss this>

## Appearances in Sources

- <slug-reference to source-slug, in the wiki's link_style> — <one-line note>

## Related Concepts

- <slug-reference to related-slug, in the wiki's link_style> — <relationship>

7. 反向链接审查——不要跳过

扫描 wiki/pages/ 中的所有现有页面，查找提及此来源中的实体 / 概念，但尚未链接到新页面的页面。使用 config/link-style.md 中的 ## Parse 正则表达式检测现有引用。使用同一文件中的 ## Emit 格式，添加指向新页面的交叉引用。

这是最常被跳过的步骤。不断积累的 wiki，其价值来自双向链接。

**添加每个 [[slug]] 之前，都要应用 Concept Identity 规则：**目标必须能解析到真实页面。当你提到的实体应该有页面但目前没有时，应创建该页面（步骤 6），而不是链接到无法解析的 slug。

**最终链接解析检查。**写完本次摄取涉及的所有页面（摘要、实体 / 概念页面、反向链接）后，收集这些页面中的所有 [[slug]] 引用，并确认每个都能解析到现有的 wiki/pages/<slug>.md。这会将步骤 5c 的检查扩展到之后添加的链接。继续之前，修复所有无法解析的链接——删除链接或创建对应页面。

7b. 矛盾检查——切勿跳过

现在，已写入本次摄取涉及的所有页面，且已将相邻页面纳入上下文，请在提交前检查是否存在矛盾。请阅读 SCHEMA.md 中的 矛盾检查 部分，了解完整约定。这是一道关卡，而不是注释：干净的摄取不会在任何页面留下矛盾元数据。

范围——比较哪些内容（不要重新阅读整个 wiki）：

• 将你写入或编辑的每个页面与其自身进行比较（检查内部矛盾）；以及
• 将你写入或编辑的每个页面与本次摄取中已阅读的页面进行比较——步骤 6 中的实体／概念页面，以及步骤 7 反向链接审查中查看的相邻页面。

与某个你从未打开过的远处页面存在冲突，不在此检查范围内；定期运行的 wiki-lint 扫描会兜底处理。

对发现的每项矛盾进行分类：

1. 阻断性矛盾——同一范围内同一实体的真实事实冲突：日期、数量、名称不一致，或相互排斥的说法（例如，新来源页面称某个模型于 2024 年发布，而 [[that-model]] 已注明其于 2023 年发布）。对于每项阻断性矛盾，在受影响页面的 frontmatter 中写入一行——也就是你编辑过且包含较新说法的页面：

   contradiction-check: failed — launch year conflicts with [[that-model]] (2024 vs 2023)
   

   对于页面内矛盾，请用 internal 代替 [[slug]]。然后停止——不要继续执行提交步骤（步骤 10）。指出冲突（包括两种说法及各自的位置），并向用户提供以下解决方案：

   • 更正新写入的页面；
   • 更正对应页面；
   • 添加范围限定语，协调两者；
   • 或确认这实际上并非冲突（而是轻微分歧，见下文）。

   冲突解决后，请从页面中移除 contradiction-check 行。只有当所有已触及页面都不再包含 contradiction-check: failed 行时，才能继续。

2. 轻微分歧——并非真正冲突的差异：侧重点不同、数值处于合理的版本／测量误差范围内，或说法适用于不同范围。不要写入任何页面，也不要阻断流程。在步骤 11 的摘要中注明，以便用户酌情处理；定期运行的 wiki-lint 扫描会兜底处理。

8. 重新生成 wiki/index.md

不要手动编辑索引。本次摄取写入的每个页面，其 frontmatter 中都已包含 category、summary 和 created——它们是索引的唯一事实来源。重新生成索引：

python bin/generate-index.py

新的来源、实体和概念页面现在会自动出现在对应类别下。如果生成器提示某个页面没有 frontmatter，或页面被归入 Uncategorized，请修正该页面的 frontmatter 并重新运行。

9. 更新 wiki/overview.md

重新阅读当前概览。如果此来源：

• 引入了重要概念：将其添加到“关键实体／概念”；
• 改变了整体认知：更新“当前理解”；
• 提出了新问题：将其添加到“未解决问题”。

更新 frontmatter 中的 updated 日期。

10. 记录操作

**首先通过关卡：**只要本次摄取触及的任何页面仍包含 contradiction-check: failed 行，就不要建议提交（步骤 7b）。先解决阻断性矛盾并移除该行——提交的页面必须始终保持干净。

根据 SCHEMA 的操作日志与提交约定：

• **Git wiki：**暂存 wiki 更改并建议提交（提交主题遵循仓库约定——摄取操作默认使用 Conventional Commits 的 docs: 前缀——并附上 trailer）。经用户确认后提交；切勿自动提交。

  docs: summarize <source title>
  
  Wiki-Op: ingest
  

• **非 Git wiki：**在 wiki/log.md 中追加：

  ## [<today>] ingest | <source title>
  Pages written: <slug>
  Pages updated: <comma-separated list>
  

常见错误

• 追加按时间顺序排列的更新，而不是就地编辑 — Wiki 页面是持续更新的文档，不是日志。不要添加 ## April 27 update: 或 **Update:** 等标题后再附上新内容。请就地更新相关章节，更新 frontmatter 中的 updated 日期，并在操作日志中记录更改内容（在 git wiki 中记为一次提交，否则记录到 log.md）。日志是历史记录；页面才是当前事实。
• 跳过反向链接审查（步骤 7） — 双向链接能不断提升 Wiki 的价值。务必扫描现有页面，查找此来源引入的实体。
• 臆造 [[slug]] 链接 — 切勿引用未确认存在或未在此时创建的 slug。无法跳转的链接就是臆造链接。请根据现有页面集合核实（ls wiki/pages/）；参见 SCHEMA.md 中的 Concept Identity 规则。
• 概述摘要而非进行综合提炼 — Summary 部分应体现你自己的综合提炼，而不是改写摘要。

11. 向用户报告

• 摘要页面：wiki/pages/<slug>.md
• 创建或更新的实体／概念页面：<列表>
• 添加了反向链接的页面：<列表>
• 已更新索引和概览
• 记录的软性张力（步骤 7b）：<列出所有非阻塞性张力，或填写“无”> — 不记录在任何页面上；如有需要，可据此采取行动