Compare commits
13 Commits
753f7841e8
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| b8a9bf0688 | |||
| 21f79be10e | |||
| e1738bade1 | |||
| cbba7a4923 | |||
| 8cba485187 | |||
| a31d28a386 | |||
| 8ec59e18a8 | |||
| 72b7972f3f | |||
| 3aa055dca8 | |||
| 8aba24aa7a | |||
| 9e9b5d4029 | |||
| f9db36bc38 | |||
| 2a42f9797b |
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,2 +1,3 @@
|
|||||||
raw/
|
raw/
|
||||||
wiki/
|
wiki/
|
||||||
|
__pycache__/
|
||||||
|
|||||||
292
AGENTS.md
292
AGENTS.md
@@ -1,73 +1,74 @@
|
|||||||
# LLM Wiki Agent — Schema & Workflow Instructions
|
# LLM Wiki Agent — 结构与工作流说明
|
||||||
|
|
||||||
This wiki is maintained entirely by your coding agent. No API key or Python scripts needed — just open this repo in Codex, OpenCode, or any agent that reads this file, and talk to it.
|
本 Wiki 完全由编码代理（agent）维护。无需 API Key 或 Python 脚本 —— 只需在 Codex、OpenCode 或任何能读取本文件的 agent 中打开此仓库，直接用自然语言交互即可。
|
||||||
|
|
||||||
## How to Use
|
## 使用方式
|
||||||
|
|
||||||
Describe what you want in plain English:
|
用自然语言描述你的需求：
|
||||||
- *"Ingest this file: raw/papers/my-paper.md"*
|
- *"摄取这个文件：raw/papers/my-paper.md"*
|
||||||
- *"What does the wiki say about transformer models?"*
|
- *"Wiki 里关于 transformer 模型说了什么？"*
|
||||||
- *"Check the wiki for orphan pages and contradictions"*
|
- *"检查 Wiki 中的孤立页面和冲突内容"*
|
||||||
- *"Build the knowledge graph"*
|
- *"构建知识图谱"*
|
||||||
|
|
||||||
Or use shorthand triggers:
|
或使用快捷触发词：
|
||||||
- `ingest <file>` → runs the Ingest Workflow
|
- `ingest <file>` → 执行摄取工作流
|
||||||
- `query: <question>` → runs the Query Workflow
|
- `query: <问题>` → 执行查询工作流
|
||||||
- `lint` → runs the Lint Workflow
|
- `lint` → 执行检查工作流
|
||||||
- `build graph` → runs the Graph Workflow
|
- `build graph` → 执行图谱构建工作流
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Directory Layout
|
## 目录结构
|
||||||
|
|
||||||
```
|
```
|
||||||
raw/ # Immutable source documents — never modify these
|
raw/ # 不可变的原始文档 —— 永远不要修改这里的内容
|
||||||
wiki/ # Agent owns this layer entirely
|
wiki/ # Agent 完全负责维护的知识层
|
||||||
index.md # Catalog of all pages — update on every ingest
|
index.md # 所有页面的目录 —— 每次摄取后必须更新
|
||||||
log.md # Append-only chronological record
|
log.md # 只追加的时间线记录
|
||||||
overview.md # Living synthesis across all sources
|
overview.md # 跨所有来源的动态综合摘要
|
||||||
sources/ # One summary page per source document
|
sources/ # 每个原始文档对应一个摘要页
|
||||||
entities/ # People, companies, projects, products
|
entities/ # 人物、公司、项目、产品
|
||||||
concepts/ # Ideas, frameworks, methods, theories
|
concepts/ # 想法、框架、方法、理论
|
||||||
syntheses/ # Saved query answers
|
syntheses/ # 保存的查询答案
|
||||||
graph/ # Auto-generated graph data
|
graph/ # 自动生成的图谱数据
|
||||||
tools/ # Optional standalone Python scripts (require ANTHROPIC_API_KEY)
|
tools/ # 可选的独立 Python 脚本（需要 ANTHROPIC_API_KEY）
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Page Format
|
## 页面格式
|
||||||
|
|
||||||
Every wiki page uses this frontmatter:
|
每个 Wiki 页面都使用以下 frontmatter：
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
title: "Page Title"
|
title: "页面标题"
|
||||||
type: source | entity | concept | synthesis
|
type: source | entity | concept | synthesis
|
||||||
tags: []
|
tags: []
|
||||||
sources: [] # list of source slugs that inform this page
|
sources: [] # 支撑本页面的来源 slug 列表
|
||||||
last_updated: YYYY-MM-DD
|
last_updated: YYYY-MM-DD
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
Use `[[PageName]]` wikilinks to link to other wiki pages.
|
使用 `[[页面名]]` 格式的 wikilink 链接到其他 Wiki 页面。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Ingest Workflow
|
## 摄取工作流（Ingest Workflow）
|
||||||
|
|
||||||
Triggered by: *"ingest <file>"*
|
触发方式：*"ingest <file>"*
|
||||||
|
|
||||||
Steps (in order):
|
### 执行步骤（严格顺序）
|
||||||
1. Read the source document fully
|
|
||||||
2. Read `wiki/index.md` and `wiki/overview.md` for current wiki context
|
1. 使用 Read 工具完整读取待摄取的source文档
|
||||||
3. Write `wiki/sources/<slug>.md` — use the source page format below
|
2. 读取 `wiki/index.md` 和 `wiki/overview.md`，了解当前 Wiki 上下文
|
||||||
4. Update `wiki/index.md` — add entry under Sources section
|
3. 生成 `wiki/sources/<slug>.md`（严格参照下方 Source Page Format）
|
||||||
5. Update `wiki/overview.md` — revise synthesis if warranted
|
4. 更新 `wiki/index.md`，在 Sources 节添加新条目（参照下方 Index 格式）
|
||||||
6. Update/create entity pages for key people, companies, projects mentioned
|
5. 更新 `wiki/overview.md`（如有必要则修订综合摘要）
|
||||||
7. Update/create concept pages for key ideas and frameworks discussed
|
6. 创建或更新提及的关键人物、公司、项目对应的 Entity 页面（参照下方 Entity（实体））
|
||||||
8. Flag any contradictions with existing wiki content
|
7. 创建或更新讨论的关键想法和框架对应的 Concept 页面（参照下方 Concept（概念））
|
||||||
9. Append to `wiki/log.md`: `## [YYYY-MM-DD] ingest | <Title>`
|
8. 检测并记录与现有 Wiki 内容的冲突
|
||||||
|
9. 追加 `wiki/log.md`（参照下方 Log Format（日志格式））
|
||||||
|
|
||||||
### Source Page Format
|
### Source Page Format
|
||||||
|
|
||||||
@@ -77,143 +78,174 @@ title: "Source Title"
|
|||||||
type: source
|
type: source
|
||||||
tags: []
|
tags: []
|
||||||
date: YYYY-MM-DD
|
date: YYYY-MM-DD
|
||||||
source_file: raw/...
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Summary
|
## Source File
|
||||||
2–4 sentence summary.
|
- [[{{ $json.file.rel_path }}]]
|
||||||
|
|
||||||
## Key Claims
|
## Summary（用中文描述）
|
||||||
- Claim 1
|
- 核心主题：
|
||||||
- Claim 2
|
- 问题域：
|
||||||
|
- 方法/机制：
|
||||||
|
- 结论/价值：
|
||||||
|
|
||||||
|
## Key Claims（用中文描述）
|
||||||
|
- （必须符合：主体 + 机制 + 结果）
|
||||||
|
|
||||||
## Key Quotes
|
## Key Quotes
|
||||||
> "Quote here" — context
|
> "引用内容" — 上下文说明
|
||||||
|
|
||||||
|
## Key Concepts
|
||||||
|
- [[ConceptName]]：定义
|
||||||
|
|
||||||
|
## Key Entities
|
||||||
|
- [[EntityName]]：角色说明
|
||||||
|
|
||||||
## Connections
|
## Connections
|
||||||
- [[EntityName]] — how they relate
|
- [[A]] ← depends_on ← [[B]]
|
||||||
- [[ConceptName]] — how it connects
|
- [[C]] ← extends ← [[D]]
|
||||||
|
|
||||||
## Contradictions
|
## Contradictions
|
||||||
- Contradicts [[OtherPage]] on: ...
|
- 与 [[OtherPage]] 冲突：
|
||||||
|
- 冲突点：
|
||||||
|
- 当前观点：
|
||||||
|
- 对方观点：
|
||||||
```
|
```
|
||||||
|
---
|
||||||
|
|
||||||
### Domain-Specific Templates
|
## Entity 与 Concept 规则
|
||||||
|
|
||||||
If the source falls into a specific domain (e.g., personal diary, meeting notes), the agent should use a specialized template instead of the default generic one above:
|
### Entity（实体）
|
||||||
|
|
||||||
|
**创建条件：**
|
||||||
|
- 出现 ≥ 2 次，或
|
||||||
|
- 对主题有关键影响
|
||||||
|
|
||||||
|
**类型：** 人 / 公司 / 产品 / 项目
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Concept（概念）
|
||||||
|
|
||||||
|
**创建条件：**
|
||||||
|
- 可抽象
|
||||||
|
- 可复用
|
||||||
|
- 非具体实例
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 命名规范（强制）
|
||||||
|
|
||||||
|
- 使用唯一标准名称
|
||||||
|
- 所有别名写入页面：
|
||||||
|
|
||||||
#### Diary / Journal Template
|
|
||||||
```markdown
|
```markdown
|
||||||
---
|
## Aliases
|
||||||
title: "YYYY-MM-DD Diary"
|
- GPT4
|
||||||
type: source
|
- GPT-4
|
||||||
tags: [diary]
|
|
||||||
date: YYYY-MM-DD
|
|
||||||
---
|
|
||||||
## Event Summary
|
|
||||||
...
|
|
||||||
## Key Decisions
|
|
||||||
...
|
|
||||||
## Energy & Mood
|
|
||||||
...
|
|
||||||
## Connections
|
|
||||||
...
|
|
||||||
## Shifts & Contradictions
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Meeting Notes Template
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
title: "Meeting Title"
|
|
||||||
type: source
|
|
||||||
tags: [meeting]
|
|
||||||
date: YYYY-MM-DD
|
|
||||||
---
|
|
||||||
## Goal
|
|
||||||
...
|
|
||||||
## Key Discussions
|
|
||||||
...
|
|
||||||
## Decisions Made
|
|
||||||
...
|
|
||||||
## Action Items
|
|
||||||
...
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Query Workflow
|
### 去重机制（必须）
|
||||||
|
|
||||||
Triggered by: *"query: <question>"*
|
创建前必须：
|
||||||
|
1. 搜索 index
|
||||||
Steps:
|
2. 判断是否已存在同名/近义页面
|
||||||
1. Read `wiki/index.md` to identify relevant pages
|
3. 存在则更新，不存在再新建
|
||||||
2. Read those pages
|
|
||||||
3. Synthesize an answer with inline citations as `[[PageName]]` wikilinks
|
|
||||||
4. Ask the user if they want the answer filed as `wiki/syntheses/<slug>.md`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Lint Workflow
|
## 查询工作流（Query Workflow）
|
||||||
|
|
||||||
Triggered by: *"lint"*
|
触发方式：*"query: <问题>"*
|
||||||
|
|
||||||
Check for:
|
步骤：
|
||||||
- **Orphan pages** — wiki pages with no inbound `[[links]]` from other pages
|
1. 读取 `wiki/index.md`，确定相关页面
|
||||||
- **Broken links** — `[[WikiLinks]]` pointing to pages that don't exist
|
2. 读取这些页面的内容
|
||||||
- **Contradictions** — claims that conflict across pages
|
3. 综合生成答案，并以 `[[页面名]]` wikilink 形式内联引用来源
|
||||||
- **Stale summaries** — pages not updated after newer sources
|
4. 询问用户是否将答案保存为 `wiki/syntheses/<slug>.md`
|
||||||
- **Missing entity pages** — entities mentioned in 3+ pages but lacking their own page
|
|
||||||
- **Data gaps** — questions the wiki can't answer; suggest new sources
|
|
||||||
|
|
||||||
Output a lint report and ask if the user wants it saved to `wiki/lint-report.md`.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Graph Workflow
|
## 检查工作流（Lint Workflow）
|
||||||
|
|
||||||
Triggered by: *"build graph"*
|
触发方式：*"lint"*
|
||||||
|
|
||||||
First try: `python tools/build_graph.py --open`
|
检查项目：
|
||||||
|
- **孤立页面** —— 没有任何其他页面通过 `[[links]]` 指向它的 Wiki 页面
|
||||||
|
- **断链** —— `[[WikiLinks]]` 指向不存在的页面
|
||||||
|
- **内容冲突** —— 跨页面存在相互矛盾的论点
|
||||||
|
- **过时摘要** —— 有更新来源后未同步更新的页面
|
||||||
|
- **缺失 Entity 页面** —— 在 3 个以上页面中被提及但没有独立页面的实体
|
||||||
|
- **数据缺口** —— Wiki 无法回答的问题，建议补充新来源
|
||||||
|
|
||||||
If Python/deps unavailable, build manually:
|
输出检查报告，并询问用户是否保存为 `wiki/lint-report.md`。
|
||||||
1. Search for all `[[wikilinks]]` across wiki pages
|
|
||||||
2. Build nodes (one per page) and edges (one per link)
|
|
||||||
3. Infer implicit relationships not captured by wikilinks — tag `INFERRED` with confidence score; low confidence → `AMBIGUOUS`
|
|
||||||
4. Write `graph/graph.json` with `{nodes, edges, built: date}`
|
|
||||||
5. Write `graph/graph.html` as a self-contained vis.js visualization
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Naming Conventions
|
## 图谱构建工作流（Graph Workflow）
|
||||||
|
|
||||||
- Source slugs: `kebab-case` matching source filename
|
触发方式：*"build graph"*
|
||||||
- Entity pages: `TitleCase.md` (e.g. `OpenAI.md`, `SamAltman.md`)
|
|
||||||
- Concept pages: `TitleCase.md` (e.g. `ReinforcementLearning.md`, `RAG.md`)
|
|
||||||
|
|
||||||
## Index Format
|
优先尝试：`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
|
```markdown
|
||||||
# Wiki Index
|
# Wiki Index
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
- [Overview](overview.md) — living synthesis
|
- [Overview](overview.md) — 动态综合摘要
|
||||||
|
|
||||||
## Sources
|
## Sources
|
||||||
- [Source Title](sources/slug.md) — one-line summary
|
- [来源标题](sources/slug.md) — 一行摘要
|
||||||
|
|
||||||
## Entities
|
## Entities
|
||||||
- [Entity Name](entities/EntityName.md) — one-line description
|
- [实体名称](entities/EntityName.md) — 一行描述
|
||||||
|
|
||||||
## Concepts
|
## Concepts
|
||||||
- [Concept Name](concepts/ConceptName.md) — one-line description
|
- [概念名称](concepts/ConceptName.md) — 一行描述
|
||||||
|
|
||||||
## Syntheses
|
## Syntheses
|
||||||
- [Analysis Title](syntheses/slug.md) — what question it answers
|
- [分析标题](syntheses/slug.md) — 回答了什么问题
|
||||||
```
|
```
|
||||||
|
|
||||||
## Log Format
|
## Log Format（日志格式）
|
||||||
|
|
||||||
`## [YYYY-MM-DD] <operation> | <title>`
|
```
|
||||||
|
## [YYYY-MM-DD] ingest | 标题
|
||||||
|
- Source file: {{ $json.file.rel_path }}
|
||||||
|
- Status: ✅ 成功摄入
|
||||||
|
- Summary:
|
||||||
|
- Concepts created: xxx, xxx
|
||||||
|
- Source page: {{ $json.file.source_path }}
|
||||||
|
- Notes:
|
||||||
|
```
|
||||||
|
|
||||||
Operations: `ingest`, `query`, `lint`, `graph`
|
操作类型：`ingest`、`query`、`lint`、`graph`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 最终目标
|
||||||
|
|
||||||
|
该系统用于：
|
||||||
|
- 知识沉淀
|
||||||
|
- 结构化理解
|
||||||
|
- 自动图谱构建
|
||||||
|
- Agent 推理支持
|
||||||
|
|||||||
219
AGENTS.md.bak
Normal file
219
AGENTS.md.bak
Normal file
@@ -0,0 +1,219 @@
|
|||||||
|
# LLM Wiki Agent — Schema & Workflow Instructions
|
||||||
|
|
||||||
|
This wiki is maintained entirely by your coding agent. No API key or Python scripts needed — just open this repo in Codex, OpenCode, or any agent that reads this file, and talk to it.
|
||||||
|
|
||||||
|
## How to Use
|
||||||
|
|
||||||
|
Describe what you want in plain English:
|
||||||
|
- *"Ingest this file: raw/papers/my-paper.md"*
|
||||||
|
- *"What does the wiki say about transformer models?"*
|
||||||
|
- *"Check the wiki for orphan pages and contradictions"*
|
||||||
|
- *"Build the knowledge graph"*
|
||||||
|
|
||||||
|
Or use shorthand triggers:
|
||||||
|
- `ingest <file>` → runs the Ingest Workflow
|
||||||
|
- `query: <question>` → runs the Query Workflow
|
||||||
|
- `lint` → runs the Lint Workflow
|
||||||
|
- `build graph` → runs the Graph Workflow
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Directory Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
raw/ # Immutable source documents — never modify these
|
||||||
|
wiki/ # Agent owns this layer entirely
|
||||||
|
index.md # Catalog of all pages — update on every ingest
|
||||||
|
log.md # Append-only chronological record
|
||||||
|
overview.md # Living synthesis across all sources
|
||||||
|
sources/ # One summary page per source document
|
||||||
|
entities/ # People, companies, projects, products
|
||||||
|
concepts/ # Ideas, frameworks, methods, theories
|
||||||
|
syntheses/ # Saved query answers
|
||||||
|
graph/ # Auto-generated graph data
|
||||||
|
tools/ # Optional standalone Python scripts (require ANTHROPIC_API_KEY)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Page Format
|
||||||
|
|
||||||
|
Every wiki page uses this frontmatter:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
title: "Page Title"
|
||||||
|
type: source | entity | concept | synthesis
|
||||||
|
tags: []
|
||||||
|
sources: [] # list of source slugs that inform this page
|
||||||
|
last_updated: YYYY-MM-DD
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `[[PageName]]` wikilinks to link to other wiki pages.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ingest Workflow
|
||||||
|
|
||||||
|
Triggered by: *"ingest <file>"*
|
||||||
|
|
||||||
|
Steps (in order):
|
||||||
|
1. Read the source document fully
|
||||||
|
2. Read `wiki/index.md` and `wiki/overview.md` for current wiki context
|
||||||
|
3. Write `wiki/sources/<slug>.md` — use the source page format below
|
||||||
|
4. Update `wiki/index.md` — add entry under Sources section
|
||||||
|
5. Update `wiki/overview.md` — revise synthesis if warranted
|
||||||
|
6. Update/create entity pages for key people, companies, projects mentioned
|
||||||
|
7. Update/create concept pages for key ideas and frameworks discussed
|
||||||
|
8. Flag any contradictions with existing wiki content
|
||||||
|
9. Append to `wiki/log.md`: `## [YYYY-MM-DD] ingest | <Title>`
|
||||||
|
|
||||||
|
### Source Page Format
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Source Title"
|
||||||
|
type: source
|
||||||
|
tags: []
|
||||||
|
date: YYYY-MM-DD
|
||||||
|
source_file: raw/...
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
2–4 sentence summary.
|
||||||
|
|
||||||
|
## Key Claims
|
||||||
|
- Claim 1
|
||||||
|
- Claim 2
|
||||||
|
|
||||||
|
## Key Quotes
|
||||||
|
> "Quote here" — context
|
||||||
|
|
||||||
|
## Connections
|
||||||
|
- [[EntityName]] — how they relate
|
||||||
|
- [[ConceptName]] — how it connects
|
||||||
|
|
||||||
|
## Contradictions
|
||||||
|
- Contradicts [[OtherPage]] on: ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Domain-Specific Templates
|
||||||
|
|
||||||
|
If the source falls into a specific domain (e.g., personal diary, meeting notes), the agent should use a specialized template instead of the default generic one above:
|
||||||
|
|
||||||
|
#### Diary / Journal Template
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "YYYY-MM-DD Diary"
|
||||||
|
type: source
|
||||||
|
tags: [diary]
|
||||||
|
date: YYYY-MM-DD
|
||||||
|
---
|
||||||
|
## Event Summary
|
||||||
|
...
|
||||||
|
## Key Decisions
|
||||||
|
...
|
||||||
|
## Energy & Mood
|
||||||
|
...
|
||||||
|
## Connections
|
||||||
|
...
|
||||||
|
## Shifts & Contradictions
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Meeting Notes Template
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Meeting Title"
|
||||||
|
type: source
|
||||||
|
tags: [meeting]
|
||||||
|
date: YYYY-MM-DD
|
||||||
|
---
|
||||||
|
## Goal
|
||||||
|
...
|
||||||
|
## Key Discussions
|
||||||
|
...
|
||||||
|
## Decisions Made
|
||||||
|
...
|
||||||
|
## Action Items
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Query Workflow
|
||||||
|
|
||||||
|
Triggered by: *"query: <question>"*
|
||||||
|
|
||||||
|
Steps:
|
||||||
|
1. Read `wiki/index.md` to identify relevant pages
|
||||||
|
2. Read those pages
|
||||||
|
3. Synthesize an answer with inline citations as `[[PageName]]` wikilinks
|
||||||
|
4. Ask the user if they want the answer filed as `wiki/syntheses/<slug>.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Lint Workflow
|
||||||
|
|
||||||
|
Triggered by: *"lint"*
|
||||||
|
|
||||||
|
Check for:
|
||||||
|
- **Orphan pages** — wiki pages with no inbound `[[links]]` from other pages
|
||||||
|
- **Broken links** — `[[WikiLinks]]` pointing to pages that don't exist
|
||||||
|
- **Contradictions** — claims that conflict across pages
|
||||||
|
- **Stale summaries** — pages not updated after newer sources
|
||||||
|
- **Missing entity pages** — entities mentioned in 3+ pages but lacking their own page
|
||||||
|
- **Data gaps** — questions the wiki can't answer; suggest new sources
|
||||||
|
|
||||||
|
Output a lint report and ask if the user wants it saved to `wiki/lint-report.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Graph Workflow
|
||||||
|
|
||||||
|
Triggered by: *"build graph"*
|
||||||
|
|
||||||
|
First try: `python tools/build_graph.py --open`
|
||||||
|
|
||||||
|
If Python/deps unavailable, build manually:
|
||||||
|
1. Search for all `[[wikilinks]]` across wiki pages
|
||||||
|
2. Build nodes (one per page) and edges (one per link)
|
||||||
|
3. Infer implicit relationships not captured by wikilinks — tag `INFERRED` with confidence score; low confidence → `AMBIGUOUS`
|
||||||
|
4. Write `graph/graph.json` with `{nodes, edges, built: date}`
|
||||||
|
5. Write `graph/graph.html` as a self-contained vis.js visualization
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Naming Conventions
|
||||||
|
|
||||||
|
- Source slugs: `kebab-case` matching source filename
|
||||||
|
- Entity pages: `TitleCase.md` (e.g. `OpenAI.md`, `SamAltman.md`)
|
||||||
|
- Concept pages: `TitleCase.md` (e.g. `ReinforcementLearning.md`, `RAG.md`)
|
||||||
|
|
||||||
|
## Index Format
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Wiki Index
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
- [Overview](overview.md) — living synthesis
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
- [Source Title](sources/slug.md) — one-line summary
|
||||||
|
|
||||||
|
## Entities
|
||||||
|
- [Entity Name](entities/EntityName.md) — one-line description
|
||||||
|
|
||||||
|
## Concepts
|
||||||
|
- [Concept Name](concepts/ConceptName.md) — one-line description
|
||||||
|
|
||||||
|
## Syntheses
|
||||||
|
- [Analysis Title](syntheses/slug.md) — what question it answers
|
||||||
|
```
|
||||||
|
|
||||||
|
## Log Format
|
||||||
|
|
||||||
|
`## [YYYY-MM-DD] <operation> | <title>`
|
||||||
|
|
||||||
|
Operations: `ingest`, `query`, `lint`, `graph`
|
||||||
182
CLAUDE.md
182
CLAUDE.md
@@ -47,12 +47,13 @@ Transformer（变压器模型，一种基于注意力机制的神经网络架构
|
|||||||
|
|
||||||
# Slash Commands（Claude Code）
|
# Slash Commands（Claude Code）
|
||||||
|
|
||||||
| Command | 使用方式 |
|
| Command | 使用方式 |
|
||||||
| -------------- | --------------------------- |
|
| -------------- | ------------------------------ |
|
||||||
| `/wiki-ingest` | `ingest raw/your-file.md` |
|
| `/wiki-ingest` | `ingest raw/your-file.md` |
|
||||||
| `/wiki-query` | `query: 你的问题` |
|
| `/wiki-query` | `query: 你的问题` |
|
||||||
| `/wiki-lint` | `lint the wiki` |
|
| `/wiki-lint` | `lint the wiki` |
|
||||||
| `/wiki-graph` | `build the knowledge graph` |
|
| `/wiki-graph` | `build the knowledge graph` |
|
||||||
|
| `/wiki-sync` | `python tools/sync.py --check` 预览，`--sync` 执行 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -116,13 +117,172 @@ last_updated: YYYY-MM-DD
|
|||||||
## 执行步骤（严格顺序）
|
## 执行步骤（严格顺序）
|
||||||
1. 使用 Read 工具完整读取 source 文档
|
1. 使用 Read 工具完整读取 source 文档
|
||||||
2. 读取 `wiki/index.md` 和 `wiki/overview.md`
|
2. 读取 `wiki/index.md` 和 `wiki/overview.md`
|
||||||
3. 生成 `wiki/sources/原始中文名.md` (非中文使用 slug.md)
|
3. 生成 `wiki/sources/<slug>.md`
|
||||||
|
- 如果原始文件名是中文，就保留中文名字作为source页面的文件名
|
||||||
|
- **必须使用 ASCII 字符，用 `-` 替换空格和特殊字符**
|
||||||
|
- 例如：`Ubuntu 安装 FRP 0.65.0（x86_64）操作笔记.md` → `Ubuntu-安装-FRP-0.65.0-x86-64-操作笔记.md`
|
||||||
|
> ⚠️ **Source Page 必须包含 `## Source File` 段落**，格式为：
|
||||||
|
> ```markdown
|
||||||
|
> ## Source File
|
||||||
|
> - [[raw/相对路径/文件名.md]]
|
||||||
|
> ```
|
||||||
|
> 这是溯源链的关键环节，**禁止省略**。即使同一 raw 文件被多次 ingest，每次都要写明 `## Source File`。
|
||||||
4. 更新 `wiki/index.md`
|
4. 更新 `wiki/index.md`
|
||||||
5. 更新 `wiki/overview.md`（如有必要）
|
5. 更新 `wiki/overview.md`（如有必要）
|
||||||
6. 创建或更新 Entity 页面
|
6. 创建或更新 Entity 页面
|
||||||
7. 创建或更新 Concept 页面
|
7. 创建或更新 Concept 页面
|
||||||
8. 检测并记录冲突
|
8. 检测并记录冲突
|
||||||
9. 追加 `wiki/log.md`
|
9. 追加 `wiki/log.md`，**输出格式必须包含实际使用的 slug**：
|
||||||
|
```markdown
|
||||||
|
## [YYYY-MM-DD] ingest | 标题
|
||||||
|
- Source file: raw/xxx.md
|
||||||
|
- Status: ✅ 成功摄入
|
||||||
|
- Summary:
|
||||||
|
- Concepts created: xxx, xxx
|
||||||
|
- Source page: wiki/sources/xxx.md
|
||||||
|
- Notes:
|
||||||
|
```
|
||||||
|
> ⚠️ 输出 **done** 后必须附加一行显示实际 slug，例如：
|
||||||
|
> ```
|
||||||
|
> done
|
||||||
|
> SLUG: modern-itsm-driving-efficiency-security-resilience
|
||||||
|
> ```
|
||||||
|
|
||||||
|
> ⚠️ 本项目所有 ingest 操作直接通过 Claude Code agent 执行，不使用 `tools/ingest.py`（该脚本依赖 litellm 但未安装）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Sync Workflow（同步更新流程）
|
||||||
|
|
||||||
|
本流程通过 `sync.py` 自动检测 `raw/` 下文件变化，调用 Claude Code agent 按 Ingest Workflow 执行实际同步。
|
||||||
|
|
||||||
|
## manifest.json 格式
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"updated_at": "ISO timestamp",
|
||||||
|
"files": {
|
||||||
|
"relative/path/to/file.md": {
|
||||||
|
"hash": "sha256（前16位）",
|
||||||
|
"modified": "ISO timestamp",
|
||||||
|
"slug": "wiki-source-slug",
|
||||||
|
"source_path": "wiki/sources/slug.md",
|
||||||
|
"ingested": true,
|
||||||
|
"ingested_at": "ISO timestamp"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Slash Command
|
||||||
|
|
||||||
|
| Command | 使用方式 |
|
||||||
|
| -------------- | ------------------------------ |
|
||||||
|
| `/wiki-sync` | `python tools/sync.py --check` 预览 |
|
||||||
|
| `/wiki-sync` | `python tools/sync.py --sync` 执行 |
|
||||||
|
|
||||||
|
## 执行步骤（严格顺序）
|
||||||
|
|
||||||
|
**角色分工：**
|
||||||
|
- **Hermes（我）**：启动 TMUX、发送任务、监控进度、更新 manifest、发送 Telegram
|
||||||
|
- **Claude Code Agent**：执行 `/wiki-ingest`（读取 CLAUDE.md → 严格按 9 步执行）
|
||||||
|
|
||||||
|
1. 执行 `python tools/sync.py --check` — 预览 raw/ 变化（新增/修改/删除）**[Hermes]**
|
||||||
|
2. 确认变化列表后，启动 TMUX + Claude Code：
|
||||||
|
```bash
|
||||||
|
# 启动 Claude Code（跳过信任目录确认）**[Hermes]**
|
||||||
|
tmux new-session -d -s claude-wiki -x 200 -y 50
|
||||||
|
tmux send-keys -t claude-wiki 'cd /Users/weishen/Git/llm-wiki-agent && claude --permission-mode bypassPermissions' Enter
|
||||||
|
sleep 8 && tmux send-keys -t claude-wiki Enter # 确认信任目录
|
||||||
|
|
||||||
|
# 发送任务（完整指令）**[Hermes]**
|
||||||
|
# 注意：实际执行时，将 /absolute/path/to/xxx.md 替换为真正的文件绝对路径
|
||||||
|
tmux send-keys -t claude-wiki '请执行以下任务：
|
||||||
|
|
||||||
|
1. 首先完整阅读 CLAUDE.md 中的 Ingest Workflow 部分
|
||||||
|
2. 然后执行 /wiki-ingest /absolute/path/to/xxx.md
|
||||||
|
3. 严格按 CLAUDE.md 中的 9 步执行，不可跳过任何步骤
|
||||||
|
4. 每篇必须完成：source page + index.md + overview.md（如有必要）+ entity + concept + log.md
|
||||||
|
5. 完成后输出 done，并附加一行：SLUG: 实际生成的-slug（用于更新 manifest）' Enter
|
||||||
|
|
||||||
|
# 监控任务完成状态（等待看到 "done" 或任务完成提示）**[Hermes]**
|
||||||
|
tmux capture-pane -t claude-wiki -p
|
||||||
|
|
||||||
|
# 下一个任务...（必须等上一个完成）
|
||||||
|
```
|
||||||
|
> ⚠️ **关键规则**：必须**一个一个顺序执行**，每完成一个再发下一个。并发会触发 529 rate limit 错误。
|
||||||
|
3. Claude Code Agent 执行 ingest（9 步）**[Claude Code Agent]**
|
||||||
|
4. 每完成一个文件，更新 manifest.json（记录 hash、slug、source_path）**[Hermes]**
|
||||||
|
5. deleted 文件：从 manifest 移除，保留 wiki 内容（不删除 orphan entity/concept）**[Hermes]**
|
||||||
|
6. 检测 orphan entity/concept，报告但不删除**[Hermes]**
|
||||||
|
7. 清理 TMUX session：`tmux kill-session -t claude-wiki`**[Hermes]**
|
||||||
|
|
||||||
|
## Telegram 通知（/wiki-sync 执行时）
|
||||||
|
|
||||||
|
Claude Code 负责执行 `/wiki-sync` 时，通过 `send_message` 向用户发送三阶段简报：
|
||||||
|
|
||||||
|
**① 变化预览（开始时发送）**
|
||||||
|
```
|
||||||
|
🔄 Wiki Sync 开始
|
||||||
|
+ 新增: N 个
|
||||||
|
~ 修改: N 个
|
||||||
|
- 删除: N 个
|
||||||
|
```
|
||||||
|
|
||||||
|
**② 每完成一个文件发送进度**
|
||||||
|
```
|
||||||
|
✅ 已完成 3/10
|
||||||
|
📄 raw/2025 年 11 个神级 AI 开源平替，GitHub 杀疯了。.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**③ 全部完成后发送总结**
|
||||||
|
```
|
||||||
|
✅ Wiki Sync 完成
|
||||||
|
|
||||||
|
📊 同步结果：
|
||||||
|
+ 新增: N（N 个文件列表）
|
||||||
|
~ 修改: N（N 个文件列表）
|
||||||
|
- 删除: N（N 个文件列表）
|
||||||
|
|
||||||
|
📁 Wiki 状态：
|
||||||
|
manifest: N 条记录
|
||||||
|
entities: N 个（新增 N，orphan N）
|
||||||
|
concepts: N 个（新增 N，orphan N）
|
||||||
|
|
||||||
|
⚠️ 如有失败，列出失败文件及原因
|
||||||
|
```
|
||||||
|
|
||||||
|
## 分批同步原则
|
||||||
|
|
||||||
|
- 每次 `--sync` 处理所有 new + updated 文件
|
||||||
|
- 用户可修改 sync.py 中的 `BATCH_SIZE = 5` 限制每批数量
|
||||||
|
- orphan entity/concept 保留，不删除（用户要求）
|
||||||
|
|
||||||
|
## Sync 状态报告格式
|
||||||
|
|
||||||
|
```
|
||||||
|
=== Wiki Sync
|
||||||
|
Date: YYYY-MM-DD HH:MM
|
||||||
|
Raw: /path/to/raw
|
||||||
|
Wiki: /path/to/wiki
|
||||||
|
Mode: LIVE SYNC
|
||||||
|
|
||||||
|
--- Changes
|
||||||
|
+ New: N
|
||||||
|
~ Updated: N
|
||||||
|
- Deleted: N
|
||||||
|
|
||||||
|
--- Applying Sync
|
||||||
|
[+] New: raw/xxx.md → wiki/sources/xxx.md
|
||||||
|
[~] Updated: raw/xxx.md → wiki/sources/xxx.md
|
||||||
|
[-] Deleted: raw/xxx.md（wiki 内容保留）
|
||||||
|
|
||||||
|
manifest.json updated (N entries)
|
||||||
|
--- Orphan Report（保留不删）
|
||||||
|
Orphan Entities: N
|
||||||
|
Orphan Concepts: N
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -334,6 +494,12 @@ date: YYYY-MM-DD
|
|||||||
|
|
||||||
```
|
```
|
||||||
## [YYYY-MM-DD] ingest | 标题
|
## [YYYY-MM-DD] ingest | 标题
|
||||||
|
- Source file: raw/xxx.md
|
||||||
|
- Status: ✅ 成功摄入
|
||||||
|
- Summary:
|
||||||
|
- Concepts created: xxx, xxx
|
||||||
|
- Source page: wiki/sources/xxx.md
|
||||||
|
- Notes:
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
Binary file not shown.
4216
tools/manifest.json
Normal file
4216
tools/manifest.json
Normal file
File diff suppressed because it is too large
Load Diff
1274
tools/sync.py
1274
tools/sync.py
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user