# LLM Wiki Agent — 结构与工作流说明

本 Wiki 完全由编码代理（agent）维护。无需 API Key 或 Python 脚本 —— 只需在 Codex、OpenCode 或任何能读取本文件的 agent 中打开此仓库，直接用自然语言交互即可。

## 使用方式

用自然语言描述你的需求：
- *"摄取这个文件：raw/papers/my-paper.md"*
- *"Wiki 里关于 transformer 模型说了什么？"*
- *"检查 Wiki 中的孤立页面和冲突内容"*
- *"构建知识图谱"*

或使用快捷触发词：
- `ingest <file>` → 执行摄取工作流
- `query: <问题>` → 执行查询工作流
- `lint` → 执行检查工作流
- `build graph` → 执行图谱构建工作流

---

## 目录结构

```
raw/          # 不可变的原始文档 —— 永远不要修改这里的内容
wiki/         # Agent 完全负责维护的知识层
  index.md    # 所有页面的目录 —— 每次摄取后必须更新
  log.md      # 只追加的时间线记录
  overview.md # 跨所有来源的动态综合摘要
  sources/    # 每个原始文档对应一个摘要页
  entities/   # 人物、公司、项目、产品
  concepts/   # 想法、框架、方法、理论
  syntheses/  # 保存的查询答案
graph/        # 自动生成的图谱数据
tools/        # 可选的独立 Python 脚本（需要 ANTHROPIC_API_KEY）
```

---

## 页面格式

每个 Wiki 页面都使用以下 frontmatter：

```yaml
---
title: "页面标题"
type: source | entity | concept | synthesis
tags: []
sources: []       # 支撑本页面的来源 slug 列表
last_updated: YYYY-MM-DD
---
```

使用 `[[页面名]]` 格式的 wikilink 链接到其他 Wiki 页面。

---

## 摄取工作流（Ingest Workflow）

触发方式：*"ingest <file>"*

### 执行步骤（严格顺序）

1. 使用 Read 工具完整读取待摄取的source文档
2. 读取 `wiki/index.md` 和 `wiki/overview.md`，了解当前 Wiki 上下文
3. 生成 `wiki/sources/<slug>.md`（严格参照下方 Source Page Format）
4. 更新 `wiki/index.md`，在 Sources 节添加新条目（参照下方 Index 格式）
5. 更新 `wiki/overview.md`（如有必要则修订综合摘要）
6. 创建或更新提及的关键人物、公司、项目对应的 Entity 页面（参照下方 Entity（实体））
7. 创建或更新讨论的关键想法和框架对应的 Concept 页面（参照下方 Concept（概念））
8. 检测并记录与现有 Wiki 内容的冲突
9. 追加 `wiki/log.md`（参照下方 Log Format（日志格式））

### Source Page Format

```markdown
---
title: "Source Title"
type: source
tags: []
date: YYYY-MM-DD
---

## Source File
- [[{{ $json.file.rel_path }}]]

## Summary（用中文描述）
- 核心主题：
- 问题域：
- 方法/机制：
- 结论/价值：

## Key Claims（用中文描述）
- （必须符合：主体 + 机制 + 结果）

## Key Quotes
> "引用内容" — 上下文说明

## Key Concepts
- [[ConceptName]]：定义

## Key Entities
- [[EntityName]]：角色说明

## Connections
- [[A]] ← depends_on ← [[B]]
- [[C]] ← extends ← [[D]]

## Contradictions
- 与 [[OtherPage]] 冲突：
  - 冲突点：
  - 当前观点：
  - 对方观点：
```
---

## Entity 与 Concept 规则

### Entity（实体）

**创建条件：**
- 出现 ≥ 2 次，或
- 对主题有关键影响

**类型：** 人 / 公司 / 产品 / 项目

---

### Concept（概念）

**创建条件：**
- 可抽象
- 可复用
- 非具体实例

---

### 命名规范（强制）

- 使用唯一标准名称
- 所有别名写入页面：

```markdown
## Aliases
- GPT4
- GPT-4
```

---

### 去重机制（必须）

创建前必须：
1. 搜索 index
2. 判断是否已存在同名/近义页面
3. 存在则更新，不存在再新建

---

## 查询工作流（Query Workflow）

触发方式：*"query: <问题>"*

步骤：
1. 读取 `wiki/index.md`，确定相关页面
2. 读取这些页面的内容
3. 综合生成答案，并以 `[[页面名]]` wikilink 形式内联引用来源
4. 询问用户是否将答案保存为 `wiki/syntheses/<slug>.md`

---

## 检查工作流（Lint Workflow）

触发方式：*"lint"*

检查项目：
- **孤立页面** —— 没有任何其他页面通过 `[[links]]` 指向它的 Wiki 页面
- **断链** —— `[[WikiLinks]]` 指向不存在的页面
- **内容冲突** —— 跨页面存在相互矛盾的论点
- **过时摘要** —— 有更新来源后未同步更新的页面
- **缺失 Entity 页面** —— 在 3 个以上页面中被提及但没有独立页面的实体
- **数据缺口** —— Wiki 无法回答的问题，建议补充新来源

输出检查报告，并询问用户是否保存为 `wiki/lint-report.md`。

---

## 图谱构建工作流（Graph Workflow）

触发方式：*"build graph"*

优先尝试：`python tools/build_graph.py --open`

若 Python/依赖不可用，则手动构建：
1. 搜索所有 Wiki 页面中的 `[[wikilinks]]`
2. 构建节点（每页一个）和边（每个链接一条）
3. 推断 wikilink 未捕获的隐式关系 —— 标记为 `INFERRED` 并附置信度；低置信度 → `AMBIGUOUS`
4. 写入 `graph/graph.json`，格式：`{nodes, edges, built: date}`
5. 写入 `graph/graph.html`，作为独立的 vis.js 可视化文件

---

## 命名规范

- Source slug：`kebab-case`，与源文件名保持一致
- Entity 页面：`TitleCase.md`（如 `OpenAI.md`、`SamAltman.md`）
- Concept 页面：`TitleCase.md`（如 `ReinforcementLearning.md`、`RAG.md`）

## Index 格式

```markdown
# Wiki Index

## Overview
- [Overview](overview.md) — 动态综合摘要

## Sources
- [来源标题](sources/slug.md) — 一行摘要

## Entities
- [实体名称](entities/EntityName.md) — 一行描述

## Concepts
- [概念名称](concepts/ConceptName.md) — 一行描述

## Syntheses
- [分析标题](syntheses/slug.md) — 回答了什么问题
```

## Log Format（日志格式）

```
## [YYYY-MM-DD] ingest | 标题
- Source file: {{ $json.file.rel_path }}
- Status: ✅ 成功摄入
- Summary:
- Concepts created: xxx, xxx
- Source page: {{ $json.file.source_path }}
- Notes:
```

操作类型：`ingest`、`query`、`lint`、`graph`

---

## 最终目标

该系统用于：
- 知识沉淀
- 结构化理解
- 自动图谱构建
- Agent 推理支持