/wiki-build

name: wiki-build
description: 构建/重建本地知识库的 Wiki。扫描 vault 中所有源文件，从中构建一个结构化的 wiki（源文件摘要、实体、概念、对比、概述页），创建分层 INDEX（根索引 + 各目录索引）/log/hot，密集交叉链接。支持超长源文件（百万字级小说等）：prep.mjs 确定性预处理 + 分层 digest 构建 + 断点续传。开工前先侦察源文件：扫描版走 OCR、电子版直接抽文字，**电子版文字层被坏字体污染**（方正书版把数学斜体字母映射成不相干汉字）则先用 fontmap.py 清洗——三类管线完全不同，选错代价极大。支持含图源文件（扫描版教材、PPT、带插图的 PDF/论文）：docling 抽图 → media.mjs 归置与规范化 → 页面内 ![[ ]] 嵌入 → 图版对账。也能把旧单索引库的索引重构为分层布局。Triggers on: 构建 wiki, 重建 wiki, build wiki, 扫描源文件构建, 初始构建, 重新构建知识库, start wiki build, 重构索引, 索引分层, 索引迁移, restructure index, 图片入库, 图版, 插图, 带图的源文件, 扫描版教材, 教材入库, figure, image ingest.
version: 2.3.0

wiki-build: 构建 Wiki

wiki 不是一次性的输出，而是一个持续增长的复利资产 — 每次构建、导入、查询都会让它更丰富。

> **维护注记**：wiki-* 五件套（build/query/ingest/save/lint）同版本号共进——改任一 skill 时，五个 `version:` 一起 bump 到同一下一个版本；同一 PR（或一次对外发布）内的连续修订只 bump 一次。

核心原则

• **源文件不可变**：源文件（notes/、docs/ 等）是用户的原始资料，只能读取，绝对不能修改或删除。
• **密集交叉链接**：[[wiki 链接]] 是这个知识库的核心价值。每个页面都应大量链接到其他相关页面，形成知识网络。宁可多链接，不要少链接——但**只链接最终页面集合里存在的页面**：没有页面的名字在正文中一律用纯文本（或先建 stub 页再链）。收尾对账（deadcheck/linkpass，见"链接对账"节）机械保证零死链、零漏链。
• **图是内容，不是附件**：源文件里的图形承载的信息常常无法用文字替代（几何关系、函数形态、解剖结构、电路拓扑）。建页时必须把图**归置到 `wiki/images/`、用 `![[ ]]` 引用、并看图写准 caption**；丢了图，页面就只剩空话。图版与页面受同等强度的对账门禁约束。
• **合成而非搬运**：wiki 不是源文件的简单摘要集合，而是要提炼出跨源文件的综合观点、论点和洞察。
• **结构化元数据**：每个页面必须带完整的 frontmatter，这是知识网络可查询、可审计的基础。

Vault 结构

vault 根目录就是当前工作目录。源文件在子目录中（如 raw/、notes/、docs/）。 wiki 相关内容的目录结构：

• `raw/` — 未处理的原始资料目录
• `raw/wechat/` — 微信通道收到的网页、文件等原始资料统一先放在这里
• `wiki/` — 所有 wiki 页面的根目录
• `wiki/INDEX.md` — 根索引，只列目录级概览（各目录页数 + 覆盖范围）与概述入口页，不逐页罗列
• `wiki/<dir>/INDEX.md` — 每个内容目录（sources/entities/concepts/comparisons/questions）自己的索引，列全该目录页面及一句话摘要
• `wiki/log.md` — 按时间顺序记录的操作日志（最新条目在最上面）
• `wiki/hot.md` — 近期上下文缓存（~500 字，每次操作后刷新）
• `wiki/images/` — 图版根目录；每个含图源文件一个子目录（`wiki/images/<源文件主名>/`），图按文档顺序命名 `001.png`、`002.png`…，整页兜底图为 `page-042.png`。**不参与页面索引与知识图谱**（图谱只收 `.md`），但会出现在文件树里
• `wiki/meta/` — 元数据目录（lint 报告等）
• `wiki/sources/` — 源文件摘要页，由 raw/、notes/、docs/ 等原始资料生成；不要把原始资料直接放入这里
• `wiki/entities/` — 人物、组织、工具等实体页
• `wiki/concepts/` — 概念、模式、框架等
• `wiki/comparisons/` — 对比分析页
• `wiki/questions/` — 归档的问答页

构建超长源文件时，确定性过程文件统一放 `.molio/wiki-build/`（文件树扫描会跳过 `.molio`，不污染 vault；跨会话可续传）。

页面路径规则：

• 默认使用单文件页面。**文件名 = 实体/概念的规范名本身**：中文内容用中文名直做文件名（如 `wiki/entities/李白.md`），英文内容用 kebab-case（如 `wiki/entities/molio.md`）。`[[wiki 链接]]` 的链接名必须与目标文件名（去掉 `.md`）完全一致——`[[李白]]` 对应 `李白.md`，写成 `libai.md` 会断链
• 只有当某个实体、项目或主题需要拆成多个稳定页面时，才建立同名目录，并用 `index.md` 作为该目录入口
• 同名目录下的子页面必须围绕该入口主题展开，例如 `wiki/entities/molio/index.md`、`wiki/entities/molio/architecture.md`
• 不要把项目命名空间强行放进错误的内容类型目录；目录首先按页面类型归类，再按主题自然生长

Frontmatter 规范

每个 wiki 页面必须包含以下 YAML frontmatter：

---
type: source | entity | concept | comparison | overview | question | session
title: "人类可读的标题"
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags:
  - 领域标签
related:
  - "[[相关页面]]"
sources:
  - "[[源文件名]]"
---

字段说明：

• `type`：页面类型，必须是以上值之一
• `title`：人类可读标题
• `created` / `updated`：创建和最后更新日期
• `tags`：领域标签列表（至少一个）
• `related`：相关页面的 [[wiki 链接]] 列表（尽量多填）
• `sources`：信息来源的 [[wiki 链接]] 列表（source 类型页面填原始文件名，其他类型填参考了哪些 source 页面）

页面类型说明

根据源文件的内容、规模和领域，自行决定最合适的页面类型。以下是参考：

• **source**（源文件摘要）— 每个源文件一个摘要页，提取关键信息，放在 `wiki/sources/`
• **entity**（实体）— 人物、组织、工具等命名实体，放在 `wiki/entities/`
• **concept**（概念）— 关键概念、想法、模式、框架，放在 `wiki/concepts/`
• **comparison**（对比）— 相关概念或方法之间的对比分析，放在 `wiki/comparisons/`
• **overview**（概述）— 当源文件较多（≥5 篇）且跨多个主题时创建，提炼跨源文件的核心论点

目录结构应从内容中自然生长，不要强行套用固定模板。如果源文件只有几篇且主题集中，扁平结构就够用。

建页粒度

哪些实体建页、建什么样的页，按**信息落点判断，不按实体类别**。判据只问三个**结构量**，与语料领域无关——同一套规则适用于小说、史书、技术文档、论文任何语料；不要按"某类东西该建/不该建"的领域直觉分类（人物/地点/器物/概念在各自语料中的重要度完全不同，预置类别会把管线锁死在一种语料上）：

1. **覆盖深度**：它出现在几个独立区段/章节（跨度）。可机械统计（census/segments）。 2. **独立信息量**：去掉它，已有页面是否仍能完整表达同等信息。若它的全部内容可并入一句描述 → 没有独立落点。 3. **引用需求**：其他页面是否把它的名字当作**讨论对象**、而不是行文背景来提及（判法见下）。

分三档：

**完整页**（任一满足）：

• 出现在章节标题/目录中（强信号，必有内容可写）
• 能用 `grep -nF 名字` 取到足够上下文写出有实质内容的独立描述（首次出现 + 身份归属 + 至少一个关键事件/关系），且**跨度≥2 区段**。跨度=1 的内容通常不足以当独立页——除非它承载了不可并入其他页的关键信息。

**stub 页**（内容撑不起完整页，但有**引用需求**）：

• 格式：完整 frontmatter + `stub: true` 标记 + 一句话身份定性（必须 grep 取证，不靠记忆）+ 关键关系链接，3-8 行即可
• 判据只有一个：**其他页面会主动链接它**（它是文本中反复被"讨论"的话题，即使篇幅小）。判断方法见下一节"讨论对象 vs 背景挂点"。
• 图谱/问答链路需要这些中间节点（别处提及时钟链到它）；缺了就是死链或漏链。

**不建页**（噪音）：

• 通用词、尊称、无名字的泛称（"某某的娘""某某家的"这类）→ 收纳进相关页的一句话或概念页表格行
• **仅作行文背景、不被讨论**的名字（判据见下）→ 正文出现用纯文本，**禁止**建页、**禁止**在正文中以 `[[ ]]` 出现
• 判定启发式：**跨度=1 且内容可并入其他页面的一句话** → 不建页（信息已被承载，单独立页是重复，只会产生一张空洞的 stub 图）

讨论对象 vs 背景挂点（领域无关的二元判据）

对正文里每个候选名字的每一处提及，问：**它是被"讨论"还是被"用作背景"？**

• **讨论对象**：句子以它为主语/宾语在陈述它的属性、行为、关系（"**X** 在 N 处做了某事，因其 Y 而被 Z 所知"；读者查它是因为它本身构成话题）。此类提及即使零散，也指向实体。
• **背景挂点**：它只出现在方位/工具/附属语境里，删掉或换成泛指后句子语义不变（"某事发生在 P 处""用 T 完成了……""安置于 Q"——P/T/Q 是描述其他实体的背景，读者查的是句子的主体而不是它）。

同一句话里两者可并存（"发生在 R 的那个事件"——R 是背景；"事件本身"是讨论对象）。逐处判定时要看**这句话的语义中心**，不是按候选名所属的领域类别划分。拿不准时用**删除测试**：把该名字从所有出现处换成纯文本/泛指，若任何页面的可读性都不受损 → 背景挂点，不建页；若某处去掉后话题悬空（读者会问"它到底是谁"）→ 有引用需求，建 stub 都值得。

不同源文件的粒度不同，按各自内容特征独立判断。census 频率是排序信号，不是建页阈值。**建了 stub 不代表必须留着**：收尾时对入度=0 的 stub 做孤儿审计（见步骤 3），确认是背景挂点误建就删除/降级为纯文本。

索引分层结构（根 INDEX + 各目录 INDEX）

索引固定分两层：**根 INDEX 只给目录级概览**（与页面总数解耦，始终几十行），**每个内容目录有自己的 INDEX.md 列全该目录页面**。检索层层递进：根 INDEX → 相关目录 INDEX → 页面。根索引若逐页罗列，页面一多就会长到 runtime 一次读不完（Read 上限 2000 行），整个问答链路随之失效——这是分层的原因，不要因为"库还小"而退回单索引。

**根 `wiki/INDEX.md`** 格式：

# Wiki 索引

> 一句话全库概述 + 页面总数构成（源摘要 N · 实体 N · 概念 N · 对比 N …）

## 概述
- [[概述页]] — 一句话摘要（入口页，直接内联列出）

## 目录
- [[sources/INDEX|源文件摘要]]（N 页）— 覆盖主题一句话概览 + 2-3 个代表条目名
- [[entities/INDEX|实体]]（N 页）— 人物/组织/工具；代表条目名
- [[concepts/INDEX|概念]]（N 页）— 覆盖领域；代表条目名
- [[comparisons/INDEX|对比分析]]（N 页）— 有哪些对比
- [[questions/INDEX|归档问答]]（N 页）— …（有页面时才列）

**各目录 `wiki/<dir>/INDEX.md`**（sources / entities / concepts / comparisons / questions）格式：

# <分类名>索引

- [[页面]] — 一句话摘要

规则：

• 概述页（通常 1-2 篇、全库入口）直接在根 INDEX 内联，不为 overview/ 单建目录索引
• `meta/` 是元数据目录（lint 报告等），不建索引、不列入根 INDEX
• 目录 INDEX 列全该目录页面（wikilink + 一句话摘要）；条目多时用 `##` 子标题分组（sources 按主题、entities 按人物/组织/工具、concepts 按领域）
• 目录索引统一大写 `INDEX.md`，与多页主题目录的小写 `index.md` 入口页区分
• 单目录索引几百行 Read 一次可读完，不做二次分片

索引分层迁移（已有 wiki）

存量库若是旧单索引布局（根 INDEX.md 直接