| 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 当前状态
确定导入目标
实体文件（PDF/图片等）本身就是暂存资料，直接读其内容做摘要，不要再额外新建 .md 暂存文件，也不要重命名或移动它。
超长源文件处理
源文件若无法在一次上下文内通读（通读后还要留空间分析关联+生成页面+交叉链接），不能按"读全文→语义识别"抽取实体，必须先做可检索预处理，从源文件实际内容发现实体——切勿依赖记忆或训练知识列候选名单，那会遗漏大量实体（仅能列出记得住的名字）。
判断是否超长：
wc -m 源文件
若 token 数 > 当前上下文的 30%，或 Read 工具一次读不完（默认上限 2000 行），即为超长。
过程文件（统一放 .molio/wiki-build/，跨会话可续传；文件树扫描会跳过 .molio，不污染 vault 根。文件名取源文件主名、去特殊字符）：
transcode-<源文件>.txt — iconv 转码副本（源文件不可变）candidates-<源文件>.md — grep 提取的候选实体清单（带计数 + checklist 状态）progress-<源文件>.md — 范围切分与处理进度
超长路径（替代下方第 1 步的"通读"）：
0. 开工切范围：按源文件结构（卷/弧/章节段）切成若干范围，写入 progress-<源文件>.md（总范围清单 + 已处理=空）。这是完成条件的依据，不是 agent 自判"差不多了"。
- 转码：非 UTF-8（如 GBK）则转码到 UTF-8 副本（源文件不可变）：
iconv -f GBK -t UTF-8 源文件 > .molio/wiki-build/transcode-<源文件>.txt，后续 grep/采样都基于这个副本。
- 结构扫描：grep 章节标题/目录/标题层级，从标题提取实体候选。
- 命名模式发现 + 候选清单：按源文件类型识别命名实体模式，多种模式交叉发现 + 频率排序去噪。不要靠记忆列名单，正则按原文实际内容运行时构造。把 grep 提取的候选写入
candidates-<源文件>.md（每行：- [ ] 名字 计数，计数用 grep -oF 名字 文件 | wc -l）——建页必须从这个清单取，不是从记忆取，这是让"靠记忆"在结构上不可能的硬约束。
- 称谓/后缀、称谓前缀、章节/标题扫描、尾字模式、去噪（详见"建页粒度"）
- 分段采样：读首段 + 若干中段 + 末段，靠语义补充发现正则漏掉的实体，追加进候选清单。
- grep 驱动取证 + 建页：逐个处理候选清单，每个候选用
grep -nF 名字 取首次出现上下文，描述以原文为据，不编造。按"建页粒度"判断哪些独立建页。建页后在清单里打勾：- [ ] → - [x]。超长（>50 万字）必须用 Task subagent 分段并行：每个 subagent 负责一个范围/一批候选，各自 grep -nF 取证 + 撰写草稿，主 agent 汇总去重、建交叉链接、更新 INDEX。
- 更新进度：每轮结束在
progress-<源文件>.md 标记已处理范围，在 log.md 记一行。
完成条件（硬性，非 agent 自判）：
progress-<源文件>.md 的待处理范围清空candidates-<源文件>.md 里所有 - [ ] 都已变成 - [x]（自检：grep -c "^\- \[ \]" candidates-<源文件>.md 返回 0；若非 0 则继续处理未打勾候选，不要停在"已建够"的错觉上）
超长文件下，第 1 步的"通读"替换为上述预处理；后续步骤不变，但全程靠 grep 取证而非通读。
操作步骤
- 读取源文件：读取目标源文件/资料，理解其内容。超长文件走"超长源文件处理"路径，不要通读
- 读取现有 wiki：读取
wiki/INDEX.md，了解现有 wiki 结构和已覆盖的内容
- 扫描相关页面：读取与新内容最相关的已有 wiki 页面（3-5 个），了解已有知识
- 分析关联：
- 新内容有哪些重要洞察？
- 与现有 wiki 有哪些关联、补充或矛盾？
- 计划创建和更新哪些页面？
- 创建/更新页面：
- 根据现有 wiki 结构选择合适的页面类型和目录
- 新页面必须带完整 frontmatter 和 [[wiki 链接]]
- 如果新内容改变了全局认知，更新 overview 页面（如果存在）
- 超长文件必须按"超长源文件处理"段落的分轮逻辑执行：每轮处理一个范围（卷/弧/章节段），生成该范围的页面，多轮累积——不要单轮完成
- 反向更新交叉链接：如果新页面与已有页面相关，在已有页面中也添加 [[wiki 链接]]
- 矛盾处理：如果新信息与已有 wiki 内容冲突：
- 在两个页面中都添加
> [!contradiction] callout 标注
- 说明矛盾的具体内容和可能的解决方向
- 告知用户
- 更新 wiki/INDEX.md：添加新页面，更新已修改页面的描述
- 追加 wiki/log.md（最新条目在最上面）：
## YYYY-MM-DD HH:MM | ingest | 文件名
- 创建页面数：N
- 更新页面数：N
- 关键发现：一句话概述
- 刷新 wiki/hot.md：完全重写，包含本次操作的摘要和当前 wiki 状态
- 汇报：创建和更新了哪些页面，发现了哪些矛盾或知识缺口
建页粒度
按内容能否支撑独立页面判断建页粒度（不靠频率百分比或绝对次数——不同长度/领域的源文件频率分布差异大，阈值会失真）：
应建独立页（任一满足）：
- 出现在章节标题/目录中（强信号，必有内容可写）
- 能用
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 页面存在矛盾，在两个页面中都要明确标注，并告知用户。
