wiki-ingest

name	wiki-ingest
description	将源文件/资料增量导入（入库）到现有 wiki，使知识持续积累和演进。读取源文件，生成或更新 source 摘要页与实体/概念/对比等页面，建立交叉链接，检测矛盾，更新 INDEX/log/hot。支持显式文件路径、URL、或无显式目标时自动找最近 raw/wechat 暂存资料。Triggers on: 入库, 导入, 整理进知识库, 保存到知识库, 归档这个文件, ingest, add this to the wiki, process this source, 把这个文件加入 wiki, read and file this.

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

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

核心原则

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

Vault 结构

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

• raw/ — 未处理的原始资料目录
• raw/wechat/ — 微信通道收到的网页、文件等原始资料统一先放在这里
• wiki/ — 所有 wiki 页面的根目录
• wiki/INDEX.md — 主索引，列出所有页面及一句话摘要
• 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（会被企业安全策略拦截）：

  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 -m 源文件          # 中文 1 字 ≈ 1.5 token，token ≈ 字符数 × 1.5

若 token 数 > 当前上下文的 30%，或 Read 工具一次读不完（默认上限 2000 行），即为超长。

过程文件（统一放 .molio/wiki-build/，跨会话可续传；文件树扫描会跳过 .molio，不污染 vault 根。文件名取源文件主名、去特殊字符）：

• transcode-<源文件>.txt — iconv 转码副本（源文件不可变）
• candidates-<源文件>.md — grep 提取的候选实体清单（带计数 + checklist 状态）
• progress-<源文件>.md — 范围切分与处理进度

超长路径（替代下方第 1 步的"通读"）： 0. 开工切范围：按源文件结构（卷/弧/章节段）切成若干范围，写入 progress-<源文件>.md（总范围清单 + 已处理=空）。这是完成条件的依据，不是 agent 自判"差不多了"。

1. 转码：非 UTF-8（如 GBK）则转码到 UTF-8 副本（源文件不可变）：iconv -f GBK -t UTF-8 源文件 > .molio/wiki-build/transcode-<源文件>.txt，后续 grep/采样都基于这个副本。
2. 结构扫描：grep 章节标题/目录/标题层级，从标题提取实体候选。
3. 命名模式发现 + 候选清单：按源文件类型识别命名实体模式，多种模式交叉发现 + 频率排序去噪。不要靠记忆列名单，正则按原文实际内容运行时构造。把 grep 提取的候选写入 candidates-<源文件>.md（每行：- [ ] 名字 计数，计数用 grep -oF 名字 文件 | wc -l）——建页必须从这个清单取，不是从记忆取，这是让"靠记忆"在结构上不可能的硬约束。
   • 称谓/后缀、称谓前缀、章节/标题扫描、尾字模式、去噪（详见"建页粒度"）
4. 分段采样：读首段 + 若干中段 + 末段，靠语义补充发现正则漏掉的实体，追加进候选清单。
5. grep 驱动取证 + 建页：逐个处理候选清单，每个候选用 grep -nF 名字 取首次出现上下文，描述以原文为据，不编造。按"建页粒度"判断哪些独立建页。建页后在清单里打勾：- [ ] → - [x]。超长（>50 万字）必须用 Task subagent 分段并行：每个 subagent 负责一个范围/一批候选，各自 grep -nF 取证 + 撰写草稿，主 agent 汇总去重、建交叉链接、更新 INDEX。
6. 更新进度：每轮结束在 progress-<源文件>.md 标记已处理范围，在 log.md 记一行。

完成条件（硬性，非 agent 自判）：

• progress-<源文件>.md 的待处理范围清空
• candidates-<源文件>.md 里所有 - [ ] 都已变成 - [x]（自检：grep -c "^\- \[ \]" candidates-<源文件>.md 返回 0；若非 0 则继续处理未打勾候选，不要停在"已建够"的错觉上）

超长文件下，第 1 步的"通读"替换为上述预处理；后续步骤不变，但全程靠 grep 取证而非通读。

操作步骤

1. 读取源文件：读取目标源文件/资料，理解其内容。超长文件走"超长源文件处理"路径，不要通读
2. 读取现有 wiki：读取 wiki/INDEX.md，了解现有 wiki 结构和已覆盖的内容
3. 扫描相关页面：读取与新内容最相关的已有 wiki 页面（3-5 个），了解已有知识
4. 分析关联：
   • 新内容有哪些重要洞察？
   • 与现有 wiki 有哪些关联、补充或矛盾？
   • 计划创建和更新哪些页面？
5. 创建/更新页面：
   • 根据现有 wiki 结构选择合适的页面类型和目录
   • 新页面必须带完整 frontmatter 和 [[wiki 链接]]
   • 如果新内容改变了全局认知，更新 overview 页面（如果存在）
   • 超长文件必须按"超长源文件处理"段落的分轮逻辑执行：每轮处理一个范围（卷/弧/章节段），生成该范围的页面，多轮累积——不要单轮完成
6. 反向更新交叉链接：如果新页面与已有页面相关，在已有页面中也添加 [[wiki 链接]]
7. 矛盾处理：如果新信息与已有 wiki 内容冲突：
   • 在两个页面中都添加 > [!contradiction] callout 标注
   • 说明矛盾的具体内容和可能的解决方向
   • 告知用户
8. 更新 wiki/INDEX.md：添加新页面，更新已修改页面的描述
9. 追加 wiki/log.md（最新条目在最上面）：

   ## YYYY-MM-DD HH:MM | ingest | 文件名
   - 创建页面数：N
   - 更新页面数：N
   - 关键发现：一句话概述
   

10. 刷新 wiki/hot.md：完全重写，包含本次操作的摘要和当前 wiki 状态
11. 汇报：创建和更新了哪些页面，发现了哪些矛盾或知识缺口

建页粒度

按内容能否支撑独立页面判断建页粒度（不靠频率百分比或绝对次数——不同长度/领域的源文件频率分布差异大，阈值会失真）：

应建独立页（任一满足）：

• 出现在章节标题/目录中（强信号，必有内容可写）
• 能用 grep -nF 名字 取到足够上下文写出有实质内容的独立描述（首次出现 + 身份归属 + 至少一个关键事件/关系）

只有零星提及（如"某某点头""某某路过"，grep 取证写不出实质内容）→ 放概念页表格行，不独立建页。

不同源文件的粒度不同，按各自内容特征独立判断。

入库页面规则

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

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