zhuzhaoyun/molio/wiki-ingest

wiki-ingest: 增量导入（入库）

将指定的源文件（或资料）增量导入到现有 wiki 中，使 wiki 的知识持续积累和演进。

核心原则

• 源文件不可变：只能读取源文件，绝对不能修改或删除。
• 积累而非替换：新内容要融入现有 wiki 的知识网络，而不是孤立地添加新页面。
• 密集交叉链接：新页面要大量链接到已有页面，已有页面如果与新内容相关也要添加反向链接。
• 矛盾检测：新信息与已有 wiki 内容冲突时，必须明确标注。
• 加粗书写规范（CJK）：**加粗** 的首尾要紧贴文字，别让括号/引号/逗号等标点落在加粗边缘、外侧又紧贴汉字——**生态位（萝卜坑）**的分配（闭合侧失效）、甲**「重点」**乙（两侧都失效）这类写法会被 CommonMark 渲染器判定加粗失效、** 按字面显示（中文没有空格，极易踩中）。改法：调整语序让加粗首尾都是文字；或在贴标点的那一侧补半角空格，把标点和外侧汉字隔开——闭合侧失效在闭合 ** 后补（**生态位（萝卜坑）** 的分配），开启侧失效在开启 ** 前补（甲 **「重点」** 乙），两侧都失效就两侧都补。

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/meta/ — 元数据目录（lint 报告等）
• wiki/sources/ — 源文件摘要页，由 raw/、notes/、docs/ 等原始资料生成；不要把原始资料直接放入这里
• wiki/entities/ — 人物、组织、工具等实体页
• wiki/concepts/ — 概念、模式、框架等
• wiki/comparisons/ — 对比分析页
• wiki/questions/ — 归档的问答页

页面路径规则：

• 默认使用单文件页面，例如 wiki/entities/molio.md、wiki/concepts/agent-routing.md
• 只有当某个实体、项目或主题需要拆成多个稳定页面时，才建立同名目录，并用 index.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 页面）

Hot Cache

wiki/hot.md 是近期上下文缓存，用于快速恢复上下文。格式：

# 近期上下文
 
> 最后更新：YYYY-MM-DD HH:MM
 
## 最近操作
-[操作描述]
 
## 关键页面
-[[页面名]] — 为什么重要
 
## 开放问题
-尚未解决的问题或待跟进的事项

管理规则：

• 每次 build/ingest/lint/save 操作完成后，完全重写 hot.md（不是追加）
• 内容控制在 ~500 字以内
• 重点是让下次会话能快速理解 wiki 当前状态

确定导入目标

• 显式文件路径：用户消息里给了文件路径（如「把 xxx 加入 wiki」「导入：/path/to/file」），直接读该文件。
• URL / 网页分享：用户给了 http 链接。mp.weixin.qq.com 链接必须用 wechat-article-extractor skill 提取正文，禁止用 WebFetch（会被企业安全策略拦截）：

``bash node "<skill_dir>/extract.js" "<url>" ` <skill_dir> 是 vault 下 .claude/skills/wechat-article-extractor/ 的绝对路径。脚本 stdout 输出 Markdown 正文，stderr 输出一行 JSON 元数据（含 title/author/account/publishTime）。退出码为 2（内容不可用）时不要重试，提示用户手动粘贴正文。非 mp.weixin.qq.com` 链接按一般 URL 处理。

• 无显式目标（如只说「入库」「整理进知识库」）：找 raw/wechat/YYYY-MM-DD/ 下最近一次新增的暂存资料（实体文件或 .md）作为导入目标。如果有多份或无法确定，先问用户确认，不要猜测。

实体文件（PDF/图片等）本身就是暂存资料，直接读其内容做摘要，不要再额外新建 `.md` 暂存文件，也不要重命名或移动它。

含图资料（扫描版教材、PPT、带插图的 PDF）：入库时图必须一起进来，不能只留文字。转换用 docling --image-export-mode referenced，再用 media.mjs collect 归置到 wiki/images/<主名>/，页面里用 ![[ ]] 嵌入——完整流程和硬规范见 wiki-build SKILL.md「含图源文件（图版）处理」节。缩短版三条：只能 ![[ ]] 不能 ![]( )；只能写完整 vault 相对路径；caption 要 Read 图片看准了再写。收尾跑 media.mjs check 确认无悬空引用。

超长源文件处理

源文件超长（wc -c > 1.5MB，约 50 万中文字，或 Read 一次读不完）时，复用 wiki-build 的确定性管线脚本（同批安装于 .claude/skills/，维护一份，两个 skill 引同一实现）。完整管线见 wiki-build SKILL.md「超长源文件处理」节，这里只列 ingest 的差异。

# 管线（与 build 相同）：
# build-lock acquire → prep → L1 digest → curate draft → agent 审核 → curate split → 建页 → place → linkpass --batches → deadcheck → sweep → repair

ingest 与 build 的三个关键差异：

1. place 用 `--append` 模式（增量追加，不全量重写 INDEX）：

``bash node ".claude/skills/wiki-build/scripts/place.mjs" <x> --vault . --append `` build 全量重写 INDEX；ingest 只追加新页条目到现有 INDEX（去重），不抹掉既有条目。这是 ingest 与 build 最本质的分界。

1. curation 只选与本次相关的候选：ingest 是增量入库，curation 审核时只保留与新源文件相关的候选行（已有 wiki 覆盖的不重建）。不要求全量处理——剩余留待后续 ingest。审核必须分块、边审边落盘——禁止在一次回复里生成完整 curation TSV（超大单次生成会撞输出上限，长时间无输出还会被 daemon 判为挂起而杀掉 run），分块规则见 wiki-build SKILL.md 步骤 3「3b 必须分块审核、边审边落盘」。

1. 增量融合：新页面必须与现有 wiki 页面建立反向链接、检测矛盾（> [!contradiction] callout）——这是 ingest 独有的要求，build 不需要。

其余完全照 build 管线：建页判据（信息落点）、批次 TSV 格式、并发限制（≤5-6）、取证封顶（≤30 条）、对账门禁（deadcheck exit 0）、引文核验（sweep 分类 → 只修 real）。

旧库索引自动升级（首触自愈）

若 wiki 仍是旧单索引布局（根 wiki/INDEX.md 以 - [[页面]] — 摘要 逐页罗列、内容目录无 INDEX.md），在本次入库前先自动完成索引分层迁移（只重构索引，不动页面文件）：

1. find wiki/ -name '*.md' 一次，建「页名 → 所在目录」映射
2. 旧根 INDEX 的页面条目按映射分流写入各目录的 INDEX.md（保留原摘要；条目多则 ## 分组）
3. 根 INDEX.md 改写为分层结构：概述条目内联，其余目录各一行（目录链接 + 页数 + 覆盖范围）

过程幂等（目录索引已存在即跳过）；执行后在回答末尾告知用户「索引布局已升级为分层」。布局规范详见 wiki-build SKILL.md「索引分层结构」节。

操作步骤

1. 读取源文件：读取目标源文件/资料，理解其内容。超长文件先走 build-lock acquire（见"超长源文件处理"），再走分层消化，不要通读
2. 读取现有 wiki：读根 wiki/INDEX.md + 相关目录的 INDEX.md，了解现有结构和已覆盖内容；若发现是旧单索引布局，先按上节完成索引升级再继续
3. 扫描相关页面：读取与新内容最相关的已有 wiki 页面（3-5 个），了解已有知识
4. 分析关联：

• 新内容有哪些重要洞察？
• 与现有 wiki 有哪些关联、补充或矛盾？
• 计划创建和更新哪些页面？

1. 创建/更新页面：

• 根据现有 wiki 结构选择合适的页面类型和目录
• 新页面必须带完整 frontmatter 和 [[wiki 链接]]
• 如果新内容改变了全局认知，更新 overview 页面（如果存在）
• 超长文件按"超长源文件处理"段落的分层消化执行：subagent 按范围产出 digest → 主 agent 从 digest 建页安置 → 打勾推进度，多轮累积——不要单轮通读完成

1. 反向更新交叉链接：如果新页面与已有页面相关，在已有页面中也添加 [[wiki 链接]]
2. 矛盾处理：如果新信息与已有 wiki 内容冲突：

• 在两个页面中都添加 > [!contradiction] callout 标注
• 说明矛盾的具体内容和可能的解决方向
• 告知用户

1. 更新索引（追加，不重写）：新页面条目追加入所在目录的 INDEX.md（对应分组下），已修改页面的描述同步更新；根 INDEX.md 的对应目录行更新页数与覆盖范围（新目录则补一行）。超长文件禁止用 build 的 place.mjs 重写 INDEX（会抹掉既有条目）
2. 追加 wiki/log.md（最新条目在最上面）：

``` ## YYYY-MM-DD HH:MM | ingest | 文件名

• 创建页面数：N
• 更新页面数：N
• 关键发现：一句话概述

```

1. 刷新 wiki/hot.md：完全重写，包含本次操作的摘要和当前 wiki 状态
2. 释放构建权：超长文件处理时，build-lock.mjs release "ingest-<主名>-<日期>"（必须释放，否则后续 build/ingest 会话会被挡）
3. 汇报：创建和更新了哪些页面，发现了哪些矛盾或知识缺口

建页粒度

判据与 wiki-build 共享，见该 skill 的「建页粒度」节——信息落点三结构量（覆盖深度 / 独立信息量 / 引用需求）+ "讨论对象 vs 背景挂点"二元判据 + 删除测试。两个 skill 对同一 vault 必须用同一套判据，不在本文件另写一套规则。

ingest 侧强调两点：

• 已有则并入：新源文件里的名字若已有对应页面，优先链接/并入既有页面，不重复建页（增量积累而非替换）。
• 零星提及不建页：grep 取证写不出实质内容（只够"某某点头"级别）→ 放概念页表格行，不独立建页。

入库页面规则

• wiki/sources/ 只放 source 摘要页，不放原始资料。
• 默认使用单文件页面。文件名 = 实体/概念的规范名本身：中文内容用中文名直做文件名（如 wiki/entities/李白.md），英文内容用 kebab-case（如 wiki/entities/molio.md）。[[wiki 链接]] 的链接名必须与目标文件名（去掉 .md）完全一致——[[李白]] 对应 李白.md，写成 libai.md 会断链。
• 只有当某个实体、项目或主题需要拆成多个稳定页面时，才建立同名目录，并用 index.md 作为该目录入口。
• 新页面必须包含完整 frontmatter，并与相关页面建立 [[wiki 链接]]。
• 新信息与已有 wiki 内容冲突时，明确标注矛盾并告知用户。

如果新内容与现有 wiki 页面存在矛盾，在两个页面中都要明确标注，并告知用户。