252 lines
6.1 KiB
Markdown
252 lines
6.1 KiB
Markdown
# 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 推理支持
|