# Wiki Ingest

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

- Skill: `zhuzhaoyun/wiki-ingest` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhuzhaoyun/wiki-ingest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhuzhaoyun/wiki-ingest/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhuzhaoyun (https://skillmd.com/u/zhuzhaoyun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhuzhaoyun/wiki-ingest

---


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

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

## 核心原则

- **源文件不可变**：只能读取源文件，绝对不能修改或删除。
- **积累而非替换**：新内容要融入现有 wiki 的知识网络，而不是孤立地添加新页面。
- **密集交叉链接**：新页面要大量链接到已有页面，已有页面如果与新内容相关也要添加反向链接。
- **矛盾检测**：新信息与已有 wiki 内容冲突时，必须明确标注。

## 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：

```yaml
---
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` 是近期上下文缓存，用于快速恢复上下文。格式：

```markdown
# 近期上下文

> 最后更新：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` 暂存文件**，也不要重命名或移动它。

## 超长源文件处理

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

```bash
# 管线（与 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 最本质的分界**。

2. **curation 只选与本次相关的候选**：ingest 是增量入库，curation 审核时只保留与新源文件相关的候选行（已有 wiki 覆盖的不重建）。不要求全量处理——剩余留待后续 ingest。

3. **增量融合**：新页面必须与现有 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 有哪些关联、补充或矛盾？
   - 计划创建和更新哪些页面？
5. **创建/更新页面**：
   - 根据现有 wiki 结构选择合适的页面类型和目录
   - 新页面必须带完整 frontmatter 和 [[wiki 链接]]
   - 如果新内容改变了全局认知，更新 overview 页面（如果存在）
   - **超长文件按"超长源文件处理"段落的分层消化执行**：subagent 按范围产出 digest → 主 agent 从 digest 建页安置 → 打勾推进度，多轮累积——不要单轮通读完成
6. **反向更新交叉链接**：如果新页面与已有页面相关，在已有页面中也添加 [[wiki 链接]]
7. **矛盾处理**：如果新信息与已有 wiki 内容冲突：
   - 在两个页面中都添加 `> [!contradiction]` callout 标注
   - 说明矛盾的具体内容和可能的解决方向
   - 告知用户
8. **更新索引（追加，不重写）**：新页面条目**追加**入**所在目录的 INDEX.md**（对应分组下），已修改页面的描述同步更新；根 INDEX.md 的对应目录行更新页数与覆盖范围（新目录则补一行）。**超长文件禁止用 build 的 place.mjs 重写 INDEX**（会抹掉既有条目）
9. **追加 wiki/log.md**（最新条目在最上面）：
   ```
   ## YYYY-MM-DD HH:MM | ingest | 文件名
   - 创建页面数：N
   - 更新页面数：N
   - 关键发现：一句话概述
   ```
10. **刷新 wiki/hot.md**：完全重写，包含本次操作的摘要和当前 wiki 状态
11. **释放构建权**：超长文件处理时，`build-lock.mjs release "ingest-<主名>-<日期>"`（必须释放，否则后续 build/ingest 会话会被挡）
12. **汇报**：创建和更新了哪些页面，发现了哪些矛盾或知识缺口

## 建页粒度

**判据与 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 页面存在矛盾，在两个页面中都要明确标注，并告知用户。