# LLM Wiki Schema

> 本文件是 LLM Wiki 维护的操作手册。每次启动时由 AGENTS.md 声明加载。
> 所有 Wiki 相关规范均以本文件为准。

## 目录结构

```
workspace/knowledge/Miralce_knowledge/
├── sources/               # 原始资料（只读）
├── wiki/                  # LLM 维护的 wiki
│   ├── library/          # sources 的影子摘要页
│   ├── entities/         # 实体页（人、公司、产品、项目）
│   ├── concepts/         # 概念页（主题、理论、方法论）
│   ├── synthesis/         # 深度专题报告（多资料融合生成）
│   ├── conflict_room/     # 矛盾记录（有争议的信息）
│   ├── log/              # 按日期拆分的日志
│   └── index.md          # wiki 目录地图
└── llmreadme.md          # 本文件（Wiki Schema）
```

## 页面格式规范

**Library 条目**：`wiki/library/<原始文件名核心>.md`

文件名与 sources/ 里对应的原始文件一一对应（只改扩展名为 .md）。

```yaml
---
type: library
origin: <sources/ 里的原始文件名>
originPath: sources/<文件名>
ingested: <ISO 日期>
tags: [<标签>]
---

## 摘要
（3-5 句话概括核心内容）

## 关键要点
- <要点 1>
- <要点 2>

## 本文件对 wiki 的贡献
- 新增实体：[[entities/...]]
- 新增/更新概念：[[concepts/...]]
- 可能触发的 synthesis：<主题>

## 相关页面
- [[entities/...]]
- [[concepts/...]]
```

**实体页**：`wiki/entities/<name>.md`

```yaml
---
type: entity
title: <实体名>
created: <ISO 日期>
updated: <ISO 日期>
tags: [<标签>]
---

## 基本信息

## 相关概念
- [[concepts/...]]

## 最新动态（来自 [[library/...]]）

## 历史记录
- <日期> <事件描述>

## 参考来源
- [[library/...]]
```

**概念页**：`wiki/concepts/<name>.md`

```yaml
---
type: concept
title: <概念名>
created: <ISO 日期>
updated: <ISO 日期>
tags: [<标签>]
---

## 定义

## 核心要点

## 不同来源的说法
| 来源 | 观点 |
|------|------|
| [[library/...]] | <观点> |

## 相关实体
- [[entities/...]]

## 参考来源
- [[library/...]]
```

**Synthesis 页**：`wiki/synthesis/<topic>.md`

当一个 topic 累计了多个来源后，生成深度报告。

```yaml
---
type: synthesis
title: <报告标题>
created: <ISO 日期>
updated: <ISO 日期>
tags: [<标签>]
sources:
  - [[library/...]]
  - [[library/...]]
---

## 背景

## 核心发现

## 分析

## 矛盾与争议（来自 [[conflict_room/...]]）

## 结论与展望

## 参考来源
```

**Conflict 条目**：`wiki/conflict_room/<topic>.md`

```yaml
---
type: conflict
title: <争议主题>
created: <ISO 日期>
status: open | resolved
---

## 争议焦点

## 来源 A 的说法（[[library/...]]）

## 来源 B 的说法（[[library/...]]）

## 目前判断

## 待验证
```

## 命名约定

- **页面标题**：首字母大写（GPT-5，而非 gpt5）
- **文件名**：小写，空格/特殊字符用连字符（gpt-5.md）
- **内部链接**：`[[wiki/entities/gpt-5|GPT-5]]` 格式
- **日期格式**：ISO YYYY-MM-DD
- **同名歧义消解**：当 entities/ 和 concepts/ 中出现同名冲突时（如 Apple = 公司 + 水果），必须加分类后缀：`apple-company.md` / `apple-fruit.md`

## 安全与权限规则

- **sources/ 设为 Read-Only**：LLM 对 `workspace/knowledge/Miralce_knowledge/sources/` 只有读取权限，绝不写入、移动、删除其中任何文件。配置由用户在 OpenClaw 层设置。
- **原子写入（Atomic Write）**：执行 Ingest 时，LLM 应先在内存中整合所有待写/待改的文件列表，然后一次性顺序写入（先写从属文件，最后写 index.md）。禁止在写入循环中让 File Watcher 触发额外的事件循环。
- **写前检查**：写入任何 wiki 页面之前，先确认该文件名不会与 library/ 形成映射冲突（即不能出现与 sources/ 已有文件同名的 entity/concept 文件）。

## Library 映射规则（Shadow Files）

`wiki/library/` 中的文件名必须与 `sources/` 中对应的原始文件名（不含扩展名）完全一致。

**规则 A（默认）**：原始文件名已有可读性 → 直接替换扩展名为 .md
> sources/article-2026-04-25.pdf → wiki/library/article-2026-04-25.md

**规则 B（文件名无意义）**：如果原始文件名无描述性（如 IMG_8821.pdf、document1.pdf）→
1. 先将 sources/ 里的文件重命名为 `YYYY-MM-DD-主题简述.ext`
2. 再在 library/ 生成同名的 .md 条目

禁止 LLM 自行生成 slug 来命名 library 条目，必须与原始文件保持确定性映射。

## 原子化原则（Core Principle）

一个原始文件进入 sources/，触发以下联动：

1. **Library**：在 `wiki/library/` 生成影子摘要页
2. **Entities**：提取其中实体，更新或新建 `wiki/entities/`
3. **Concepts**：提取其中概念，更新或新建 `wiki/concepts/`
4. **Synthesis**：若该文件显著改变了对某个专题的认知，在 `wiki/synthesis/` 生成或更新深度报告
5. **Conflict**：发现矛盾 → 写入 `wiki/conflict_room/` 并在相关页面标注

## Ingest 流程

**触发时机**：用户主动提供链接或文件时执行。

1. **获取内容**：`web_fetch` / `read` 读取来源
2. **Library 条目**：按 Shadow Files 规则，在 `wiki/library/` 写入摘要
3. **提取实体**：涉及哪些实体 → 更新或新建 `wiki/entities/<name>.md`
4. **提取概念**：涉及哪些概念 → 更新或新建 `wiki/concepts/<name>.md`
5. **判断 Synthesis**：是否显著推进某个专题的认知？→ 在 `wiki/synthesis/` 生成或更新报告
6. **检查矛盾**：新内容是否与现有 wiki 冲突？→ 写入 `wiki/conflict_room/`
7. **更新目录**：更新 `wiki/index.md`
8. **写入日志**：在 `wiki/log/` 下按日期生成日志文件
9. **汇报用户**：简述 ingest 结果（新建/更新了哪些页面，是否触发 Synthesis，是否发现矛盾）

## Query 流程

1. **读 index**：先读 `wiki/index.md` 找到相关页面
2. **读相关页面**：读 entities/concepts/synthesis 页面
3. **综合回答**：结合 wiki 内容回答，引用来源
4. **值得沉淀？**：如果回答产生了新的综合分析、对比、发现 → 写成 `wiki/synthesis/<topic>.md`
5. **写入日志**：`wiki/log/<date>.md` 追加 query 记录

## Lint 流程

每 3 天 Heartbeat 时执行一次 wiki 健康检查：

1. **矛盾扫描**：遍历 `wiki/conflict_room/`，看是否有新来源可以解决冲突
2. **过时检查**：library 条目 > 30 天未更新的，检查相关 entity/concept 是否需标注"可能过时"
3. **孤立页面**：没有任何页面引用的 entity/concept → 记录并通知用户
4. **空白概念**：某个概念被多人提到但没有专属页面 → 建议创建
5. **交叉引用检查**：检查所有 `[[wiki/...]]` 链接是否有效

结果写入 `wiki/log/<date>.md`，通知用户需要处理的问题。

## 保留原则

- **Sources 绝不修改**：sources/ 下的文件只有只读权限，LLM 不可移动、删除、重命名其中任何文件
- **Library 是影子**：library 条目是原始文件的摘要镜像，不是独立创作
- **Wiki 随时间演变**：entity/concept/synthesis 页面会不断被新来源更新
- **Synthesis 是核心价值**：深度报告才是知识复利的体现，优先生成
- **诚实标注矛盾**：不同来源说法冲突时，不压不隐藏，单独建 conflict 条目