wiki-build

name	wiki-build
description	构建/重建本地知识库的 Wiki。扫描 vault 中所有源文件，从中构建一个结构化的 wiki（源文件摘要、实体、概念、对比、概述页），创建 INDEX/log/hot，密集交叉链接。Triggers on: 构建 wiki, 重建 wiki, build wiki, 扫描源文件构建, 初始构建, 重新构建知识库, start wiki build.

wiki-build: 构建 Wiki

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

核心原则

• 源文件不可变：源文件（notes/、docs/ 等）是用户的原始资料，只能读取，绝对不能修改或删除。
• 密集交叉链接：[[wiki 链接]] 是这个知识库的核心价值。每个页面都应大量链接到其他相关页面，形成知识网络。宁可多链接，不要少链接。
• 合成而非搬运：wiki 不是源文件的简单摘要集合，而是要提炼出跨源文件的综合观点、论点和洞察。
• 结构化元数据：每个页面必须带完整的 frontmatter，这是知识网络可查询、可审计的基础。

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/李白.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 篇）且跨多个主题时创建，提炼跨源文件的核心论点

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

建页粒度

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

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

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

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

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

wiki/INDEX.md 格式

按实际创建的分类组织，每个页面一行：链接 + 一句话摘要。

# Wiki 索引

## 源文件摘要
- [[source-page]] — 一句话摘要

## 实体
- [[entity-page]] — 一句话描述

## 概念
- [[concept-page]] — 一句话描述

wiki/log.md 格式

最新条目在最上面：

# 构建日志

## YYYY-MM-DD HH:MM | build | 初始构建
- 扫描源文件数：N
- 创建页面数：N（按类型列出）
- 关键发现：一句话概述

超长源文件处理

源文件若无法在一次上下文内通读（通读后还要留空间规划+生成+交叉链接），不能按"读全文→语义识别"抽取实体，必须先做可检索预处理，从源文件实际内容发现实体——切勿依赖记忆或训练知识列候选名单，那会遗漏大量实体（仅能列出记得住的名字）。

判断是否超长：

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 则继续处理未打勾候选，不要停在"已建够"的错觉上——build 是全量构建，当次必须补全）

多源文件场景下，逐个判断、逐个预处理，每个源文件各一套过程文件。

操作步骤

1. 扫描：读取 vault 中所有源文件（跳过隐藏文件和 wiki/ 本身），了解全貌。超长文件走"超长源文件处理"路径，不要通读
2. 规划：分析内容，列出你打算创建的页面清单和类型，确定目录结构
3. 检查已有 wiki：如果 wiki/ 已存在，先读 INDEX.md 了解已有内容，只新增/更新，不重复创建
4. 生成页面：逐个创建 wiki 页面，每个页面都要带完整 frontmatter 和大量 [[wiki 链接]]。超长文件必须按"超长源文件处理"段落的分轮逻辑执行：每轮处理一个范围（卷/弧/章节段），生成该范围的页面，多轮累积——不要单轮完成
5. 覆盖率自检（超长文件必做）：按"超长源文件处理"段落的完成条件检查——progress-<源文件>.md 待处理范围是否清空、candidates-<源文件>.md 里所有 - [ ] 是否都已变成 - [x]（运行 grep -c "^\- \[ \]" candidates-<源文件>.md，若非 0 则继续处理未打勾候选）。未达标则继续补建，不要把高频实体留到"后续补充"，build 是全量构建，当次必须补全
6. 创建 INDEX.md：完整列出所有页面
7. 创建 log.md：记录本次构建
8. 创建 hot.md：生成近期上下文缓存（~500 字摘要）
9. 汇报：页面数量、核心论点摘要、剩余的知识缺口（仅限低频/边缘实体，高频实体应已在自检中补全）

页面内容要全面但简洁，优先保证准确性。