obsidian-llm-wiki / inspool-wiki-zh

# Inspool Wiki 维护规则

本文件是 `inspool-wiki-zh/` 实验区的唯一规则入口，用于指导代理维护此知识库。

## 核心目标

把零散原始资料逐步沉淀成一个结构化、可交叉引用、可持续演化的中文 wiki。

代理的职责不是临时回答问题，而是维护知识结构本身。

## 语言默认值

- 用户的默认语言偏好是中文。
- 除非用户明确要求使用英文或其他语言，否则代理生成、更新和整理的文档都应使用中文。
- 这条规则同时适用于页面正文、说明文档、索引、日志和命令模板。
- raw 原始资料可以保留原语言，不需要强制翻译；但 wiki 沉淀层的说明和结构应默认使用中文。

## 三层结构

### 1. `raw/`

- 存放原始资料，例如网页剪藏、文章、书摘、会议纪要、PDF 转写稿、截图说明等。
- 这是事实来源层。
- 正文默认只读。
- 默认允许两类流程性变更：移动文件路径，以及更新少量 frontmatter 处理元数据。
- 除非用户明确要求，否则不得改写、删减或重写 `raw/` 内正文内容。

### 2. `wiki/`

- 存放代理维护的结构化知识页面。
- 允许代理创建、更新、重命名和交叉链接。
- 回答用户问题时，优先从这里读取并综合。

### 3. `AGENTS.md`

- 定义结构约定、页面规范、操作流程和质量标准。
- 如果实践中发现更好的工作方式，可以在征得用户同意后演进本文件。

## 目录约定

### `raw/`

- `raw/unprocessed/`：待处理的新资料
- `raw/processed/`：已完成 ingest 的资料
- `raw/assets/`：从原始资料中保存的图片、附件和其他静态资源
- `raw/index.md`：素材处理状态索引

### `wiki/`

- `wiki/sources/`：单个来源的摘要页
- `wiki/entities/`：人物、组织、产品、项目、工具等实体页
- `wiki/concepts/`：概念、方法、框架、术语页
- `wiki/synthesis/`：专题综述、比较分析、阶段性结论、问答沉淀
- `wiki/meta/`：总览、规范说明、专题边界、维护记录等元信息
- `wiki/index.md`：内容索引
- `wiki/log.md`：时间日志

说明：

- 用户可能会在 `wiki/concepts/`、`wiki/entities/`、`wiki/synthesis/` 下手动创建子文件夹做分类。
- 这些子文件夹属于用户维护的组织层，不应被代理视为稳定不变的语义真相。
- 代理必须默认兼容这些目录下的任意层级子文件夹。

## 页面写作原则

- 默认使用中文撰写，除非用户明确要求其他语言。
- 尽量使用清晰标题和短段落。
- 尽量使用 Obsidian 风格双链，例如 `[[某个概念]]`。
- 重要事实尽量附带来源页引用。
- 事实、判断、猜测要分开写。
- 当资料之间存在冲突时，必须显式记录，不得静默抹平。

## 用户维护分类目录

- 用户可能在 `wiki/concepts/`、`wiki/entities/`、`wiki/synthesis/` 下手动新建子文件夹并移动页面做分类。
- 代理应把这种行为视为正常维护动作，而不是异常状态。
- 页面所属类型由顶层目录决定，例如 `concepts / entities / synthesis`，而不是由更深层子文件夹名决定。
- 更深层子文件夹主要用于用户自己的主题整理，代理不应过度依赖这些路径来推断知识关系。
- 除非用户明确要求，代理不要擅自替用户重组这些分类目录。
- 代理在读取、更新、lint 页面时，必须递归扫描这些目录下的所有子文件夹。

## 路径稳定性规则

- 不要把 `wiki/concepts/...`、`wiki/entities/...`、`wiki/synthesis/...` 的完整文件路径写死为知识语义的一部分。
- 正文和 frontmatter 中优先使用 Obsidian wiki 链接，不要依赖裸路径字符串。
- 能用 `[[页面名]]` 或 `[[相对稳定的 wiki 链接]]` 表达时，不要写普通文本路径。
- 当页面被用户移动到新的分类子文件夹时，代理应默认认为这是合法状态，并继续正常工作。
- 如果发现分类迁移后出现旧路径残留，应优先修复旧路径引用，而不是要求用户回退目录结构。
- `raw/unprocessed/` 到 `raw/processed/` 属于流程迁移，不是稳定路径。
- 因此，来源页中的 `raw_note`、正文“原始资料”链接以及其他显式 raw 路径，在 approve 后都必须同步修正到 raw 的当前位置。

## 证据节点与图谱原则

- `wiki/sources/` 中的页面是图谱中的证据节点。
- `wiki/entities/`、`wiki/concepts/`、`wiki/synthesis/` 是知识节点。
- 知识页中的关键结论，优先链接到本地 `sources` 页面，而不是直接链接外部 URL。
- 外部 URL 主要保留在 raw 文件 frontmatter 和来源页“来源信息”中，不作为主要图谱边。
- 如果能定位到来源页中的具体段落，优先使用带锚点的链接，例如 `[[sources/某篇来源#关键观点]]`。
- 一个结论如果来自多个来源，允许挂多个证据节点。
- 一个结论如果存在冲突来源，必须显式记录到 `contradicts` 字段和正文的“分歧与冲突”部分。

## 关系字段约定

为了兼顾 Obsidian Graph 和 Dataview，页面应同时维护：

1. 正文中的显式双链
2. frontmatter 中的结构化关系字段

推荐 frontmatter 字段：

- 通用字段：
  - `type`
  - `status`
  - `topic`
  - `updated`
- 来源页优先字段：
  - `raw_note`
  - `external_url`
  - `related_entities`
  - `related_concepts`
  - `related_sources`
- 实体页、概念页、综合页优先字段：
  - `supports`
  - `contradicts`
  - `related_entities`
  - `related_concepts`
  - `related_sources`
  - `related_synthesis`

字段值优先使用本地 wiki 链接，例如 `[[sources/某篇来源]]`。

## 引用与落链规则

- 关键结论、具体事实、数字、争议判断都应尽量带证据链接。
- 正文里的证据链接优先使用 `[[sources/...#某个小节]]`。
- frontmatter 中的 `supports` 和 `contradicts` 至少应链接到页级来源节点。
- 如果当前没有足够证据，不要硬写 `supports`，应标记为“待确认”。
- 不要在知识页正文里堆放大量裸露外部 URL；优先改为本地来源页链接。

## Raw 流程元数据

允许代理在 raw 文件 frontmatter 中维护少量流程字段，用于降低后续 ingest 的上下文压力。

推荐字段：

- `processing_status`：`unprocessed`、`pending_review` 或 `processed`
- `reviewed_at`：用户确认通过的日期
- `processed_at`：处理完成日期
- `processed_into`：对应沉淀出的 wiki 页面，优先写来源页路径
- `ingest_group`：可选，用于把多篇相关 raw 显式归为同一批次

约束：

- 这些字段属于流程元数据，不属于来源正文
- 允许创建、更新这些字段
- 不允许借此篡改原始资料的正文内容

## 页面推荐结构

不是所有页面都必须完全一致，但优先遵循以下结构。

### 来源页 `wiki/sources/`

建议包含：

- 来源信息
- 核心摘要
- 关键观点
- 证据摘录
- 可抽取的实体
- 可抽取的概念
- 与现有 wiki 的连接
- 待确认问题
- 相关来源

### 实体页 `wiki/entities/`

建议包含：

- 一句话定义
- 背景
- 关键属性
- 支持证据
- 分歧与冲突
- 相关事件或观点
- 相关概念
- 相关来源
- 未决问题

### 概念页 `wiki/concepts/`

建议包含：

- 定义
- 核心机制
- 与相邻概念的区别
- 支持证据
- 反例或限制
- 相关实体
- 相关来源

### 综合页 `wiki/synthesis/`

建议包含：

- 主题说明
- 结论摘要
- 支持证据
- 分歧与冲突
- 当前判断
- 开放问题
- 后续建议
- 相关来源

## 来源引用约定

- 重要结论后尽量追加来源页链接，例如 `见 [[sources/某篇文章]]`。
- 如果能定位到具体段落，优先写成 `见 [[sources/某篇文章#关键观点]]`。
- 如果结论来自多个来源，可以列出多个相关来源。
- 如果当前无法确认来源，不得写成确定性事实，应标记为“待确认”。

## 三类核心操作

### 1. Ingest

当用户要求处理新资料时：

1. 优先扫描 `raw/unprocessed/`
2. 选择下一个 ingest 单元，而不是机械地只选一篇
3. 读取 `raw/index.md`
4. 读取并提炼该来源的关键信息
5. 创建或更新对应的来源摘要页，并把它作为证据节点接入图谱
6. 更新相关实体页、概念页、综合页，同时补充 `supports`、`contradicts` 与相关双链
7. 更新 `wiki/index.md`
8. 追加写入 `wiki/log.md`
9. 更新该 ingest 单元内 raw 文件的流程元数据，将其状态改为 `pending_review`
10. 更新 `raw/index.md`
11. 明确告知用户本次 ingest 已完成，等待用户确认

单次 ingest 不应只生成一篇摘要页。只要有必要，应同步更新多个相关页面。

只有在 wiki 更新、日志更新、raw/index 更新都成功后，才允许把 raw 文件状态改为 `pending_review`。

Ingest 阶段禁止将 raw 文件直接移入 `processed/`。从 `unprocessed/` 迁移到 `processed/` 必须等到用户确认。

### 1b. Approve

当用户明确表示“这次 ingest 没问题，可以归档到 processed”时：

1. 扫描 `raw/unprocessed/` 中状态为 `pending_review` 的 ingest 单元
2. 选择用户刚刚确认的那一组；如用户未指定，则优先选择最近一次进入 `pending_review` 的那一组
3. 再次核对对应的 wiki 页面与 `raw/index.md` 记录是否存在
4. 记录组内每个 raw 文件的旧路径、目标新路径和 `processed_into`
5. 将组内每个 raw 文件的 `processing_status` 更新为 `processed`
6. 写入 `reviewed_at`
7. 如有必要，补齐 `processed_at`
8. 将该 ingest 单元内的 raw 文件迁移到 `raw/processed/`
9. 同步修复 wiki 中引用这些 raw 的旧路径，至少包括来源页 frontmatter 的 `raw_note` 与正文“原始资料”链接
10. 对本批 raw 做一次局部自检，确认 `wiki/` 中不再残留对应的旧 `raw/unprocessed/` 路径字符串
11. 更新 `raw/index.md`
12. 在 `wiki/log.md` 中追加一条 `approve` 日志

Approve 阶段不应再大幅改写 wiki 正文，除非用户在确认时明确提出修订要求。

如果第 10 步局部自检未通过，则不得把本次 approve 视为完整完成，必须明确报告残留路径并继续修复或中止。

### Ingest 单元判定规则

默认处理的是“下一组待处理内容”，判定优先级如下：

1. 如果 `raw/unprocessed/` 下存在子文件夹，则优先把同一子文件夹中的文件视为一个 ingest 单元
2. 如果多个 raw 文件拥有相同的 `ingest_group`，则把该组视为一个 ingest 单元
3. 如果用户明确说明这几篇素材需要一起处理，则把它们视为一个 ingest 单元
4. 如果没有明确分组信号，则默认把单篇文件视为一个 ingest 单元

### 批量 ingest 约束

- 批量 ingest 适用于明确相关的一小组素材
- 推荐单批次 2 到 5 篇
- 如果某组超过 5 篇，优先拆成多个小批次，避免上下文过载
- 批量 ingest 完成后，要为组内每个 raw 文件分别更新流程元数据
- 迁移到 `processed/` 时应整组迁移，避免一半已处理、一半未处理的状态分裂

### 2. Query

当用户提出问题时：

1. 优先查看 `wiki/index.md`
2. 读取相关页面
3. 基于已有 wiki 进行综合回答
4. 回答关键判断时，优先引用本地来源页，必要时使用来源页锚点
5. 如发现回答具有长期价值，可在用户同意或场景明确时回填为 `wiki/synthesis/` 页面
6. 回填后更新 `wiki/index.md` 和 `wiki/log.md`

### 3. Lint

定期对 wiki 做健康检查，重点关注：

- 是否有孤立页面
- 是否有缺少来源支撑的强结论
- 是否有陈旧结论被新资料推翻但未更新
- 是否有高频提及但尚未独立建页的概念或实体
- 是否有交叉链接明显不足的页面
- 是否有重复页面或命名不一致
- 是否存在知识页直接依赖外部 URL，而没有先落到本地来源页
- 是否存在缺少 `supports` / `contradicts` 等关键关系字段的核心页面
- 是否存在只在 frontmatter 有关系、正文却没有显式双链的页面
- 是否存在用户分类迁移后残留的旧路径字符串或失效目录假设
- `raw/index.md` 是否与 `raw/unprocessed/` 和 `raw/processed/` 的实际情况一致
- 是否存在长时间停留在 `pending_review` 的 raw 素材
- 是否存在应当成组处理却被拆散的相关 raw 素材
- 是否存在批次过大导致上下文噪声过高的 ingest 组

完成 lint 后要把结果写入 `wiki/log.md`。

## 索引规则

`wiki/index.md` 是目录视图，不是正文页面。

它至少要维护以下信息：

- 每个重要页面的链接
- 每个页面的一句话说明
- 可选的主题分组
- 可选的来源数量或更新时间

回答问题前，优先从 `wiki/index.md` 定位相关页面。

`raw/index.md` 则是流程视图，用于记录待处理队列和已处理记录。不要把这类操作流水直接堆进 `wiki/index.md`。

## 日志规则

`wiki/log.md` 是时间线，不是讨论区。

每条日志建议使用统一标题格式：

`## [YYYY-MM-DD] 动作 | 标题`

可选动作：

- `init`
- `ingest`
- `approve`
- `query`
- `lint`
- `refactor`

日志正文应简洁记录：

- 本次处理了什么
- 新增或更新了哪些页面
- 是否发现冲突或待办

## 命名规则

- 文件名优先简洁、稳定、可复用。
- 同一概念不要创建多个近义文件名。
- 如果是来源摘要页，可在文件名中保留来源主题，不必强求日期前缀。
- 如果需要迁移命名，应同步修复链接和索引。

## 禁止事项

- 不得把未经确认的猜测写成事实。
- 不得删除原始资料来“保持整洁”。
- 不得只更新正文而忘记维护 `wiki/index.md` 与 `wiki/log.md`。
- 不得只更新 wiki 而忘记维护 `raw/index.md` 与 raw 文件状态。
- 未经用户确认，不得把 `pending_review` 的 raw 文件迁移到 `processed/`。
- 不得为了好看而删除冲突信息。
- 不得在 `wiki/` 中堆积无结构的大段聊天记录。
- 不得把外部 URL 当作知识图谱中的主要关系边，而忽略本地来源页。
- 不得因为用户调整了分类子文件夹，就把这种变化误判为链接错误或结构异常。

## 默认行为

- 默认单次处理一个 ingest 单元；这个单元可以是单篇，也可以是一个小批次。
- 默认优先做小步更新，保持 wiki 可审阅。
- 默认使用 markdown，不引入额外复杂系统。
- 默认以 Obsidian 双链为主，不依赖外部数据库。