515 lines
12 KiB
Markdown
515 lines
12 KiB
Markdown
# LLM Wiki Agent — Schema & Workflow Instructions（中文版增强规范）
|
||
|
||
本 Wiki 完全由 Claude Code 自动维护。无需 API Key 或 Python 脚本 —— 只需在 Claude Code 中打开本仓库并与其对话。
|
||
|
||
---
|
||
# 🔴 全局强制规则（CRITICAL）
|
||
|
||
## 1. 输出语言（必须遵守）
|
||
|
||
- 所有输出必须使用**简体中文**
|
||
- 专有名词允许保留英文，但首次出现必须附带中文解释
|
||
- 如果原始文件名是中文，则source页面的名称尽量用中文，不要用拼音表示, 如果有特殊字符可以忽略
|
||
- 禁止中英混合句（术语除外）
|
||
- 不允许输出纯英文总结或分析
|
||
|
||
示例：
|
||
|
||
Transformer（变压器模型，一种基于注意力机制的神经网络架构）
|
||
|
||
---
|
||
|
||
## 2. 输出风格（严格限制）
|
||
|
||
所有输出必须：
|
||
|
||
- 去修辞（禁止 narrative 风格）
|
||
- 去模糊（禁止“可能”“大概”等词）
|
||
- 信息密度最大化
|
||
- 面向“知识结构化”，而非阅读体验
|
||
|
||
优先级：
|
||
|
||
结构 > 关系 > 结论 > 描述
|
||
|
||
---
|
||
|
||
## 3. 结构化语义（必须）
|
||
|
||
所有页面必须遵循结构化语义规则：
|
||
|
||
- Summary 必须使用固定字段
|
||
- Claim 必须符合标准语法
|
||
- Connections 必须使用关系类型
|
||
- 禁止自由发挥
|
||
|
||
---
|
||
|
||
# Slash Commands（Claude Code）
|
||
|
||
| Command | 使用方式 |
|
||
| -------------- | ------------------------------ |
|
||
| `/wiki-ingest` | `ingest raw/your-file.md` |
|
||
| `/wiki-query` | `query: 你的问题` |
|
||
| `/wiki-lint` | `lint the wiki` |
|
||
| `/wiki-graph` | `build the knowledge graph` |
|
||
| `/wiki-sync` | `python tools/sync.py --check` 预览，`--sync` 执行 |
|
||
|
||
---
|
||
|
||
## 自然语言示例
|
||
|
||
- ingest raw/papers/attention-is-all-you-need.md
|
||
- query: Transformer 的核心机制是什么？
|
||
- lint the wiki
|
||
- build the graph and analyze RAG
|
||
|
||
Claude Code 会自动读取本文件并执行以下工作流。
|
||
|
||
|
||
|
||
---
|
||
|
||
# Directory Layout（目录结构）
|
||
|
||
```
|
||
raw/ # 原始文档（不可修改）
|
||
wiki/ # 知识层（由 Claude 完全维护）
|
||
index.md # 页面索引（每次 ingest 必须更新）
|
||
log.md # 追加式日志
|
||
overview.md # 全局知识总结
|
||
sources/ # 每个原始文档对应一个页面
|
||
entities/ # 实体（人/公司/产品/项目）
|
||
concepts/ # 概念（方法/理论/框架）
|
||
syntheses/ # 查询结果沉淀
|
||
graph/ # 自动生成的图数据
|
||
tools/ # 可选 Python 工具 (require ANTHROPIC_API_KEY)
|
||
````
|
||
|
||
|
||
---
|
||
|
||
# Page Format（页面格式）
|
||
|
||
每个页面必须包含：
|
||
|
||
```yaml
|
||
---
|
||
id: unique_id
|
||
title: "Page Title"
|
||
type: source | entity | concept | synthesis
|
||
tags: []
|
||
sources: [] # 来源
|
||
last_updated: YYYY-MM-DD
|
||
---
|
||
````
|
||
|
||
必须使用 `[[PageName]]` 进行链接。
|
||
|
||
---
|
||
|
||
# Ingest Workflow（摄取流程）
|
||
**重要** 请严格按照摄取流程进行操作，每分析一个页面必须要创建/更新source page，entity, concept等。不可遗漏！
|
||
|
||
触发方式：
|
||
- `/wiki-ingest`
|
||
- 或：`ingest <file>`
|
||
## 执行步骤（严格顺序）
|
||
1. 使用 Read 工具完整读取 source 文档
|
||
2. 读取 `wiki/index.md` 和 `wiki/overview.md`
|
||
3. 生成 `wiki/sources/原始中文名.md` (非中文使用 slug.md)
|
||
> ⚠️ **Source Page 必须包含 `## Source File` 段落**，格式为：
|
||
> ```markdown
|
||
> ## Source File
|
||
> - [[raw/相对路径/文件名.md]]
|
||
> ```
|
||
> 这是溯源链的关键环节，**禁止省略**。即使同一 raw 文件被多次 ingest，每次都要写明 `## Source File`。
|
||
4. 更新 `wiki/index.md`
|
||
5. 更新 `wiki/overview.md`（如有必要）
|
||
6. 创建或更新 Entity 页面
|
||
7. 创建或更新 Concept 页面
|
||
8. 检测并记录冲突
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
# Source Page Format（增强结构）
|
||
|
||
```markdown
|
||
---
|
||
title: "Source Title"
|
||
type: source
|
||
tags: []
|
||
date: YYYY-MM-DD
|
||
---
|
||
|
||
## Source File
|
||
- [[raw/...]]
|
||
|
||
## Summary
|
||
- 核心主题：
|
||
- 问题域：
|
||
- 方法/机制：
|
||
- 结论/价值：
|
||
|
||
## Key Claims
|
||
- （必须符合：主体 + 机制 + 结果）
|
||
|
||
## Key Quotes
|
||
> "引用内容" — 上下文说明
|
||
|
||
## Key Concepts
|
||
- [[ConceptName]]：定义
|
||
|
||
## Key Entities
|
||
- [[EntityName]]：角色说明
|
||
|
||
## Connections
|
||
- [[A]] ← depends_on ← [[B]]
|
||
- [[C]] ← extends ← [[D]]
|
||
|
||
## Contradictions
|
||
- 与 [[OtherPage]] 冲突：
|
||
- 冲突点：
|
||
- 当前观点：
|
||
- 对方观点：
|
||
```
|
||
|
||
---
|
||
|
||
# Domain-Specific Templates（领域模板）
|
||
|
||
## Diary / Journal
|
||
|
||
```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
|
||
|
||
```markdown
|
||
---
|
||
title: "Meeting Title"
|
||
type: source
|
||
tags: [meeting]
|
||
date: YYYY-MM-DD
|
||
---
|
||
## Goal
|
||
## Key Discussions
|
||
## Decisions Made
|
||
## Action Items
|
||
```
|
||
|
||
---
|
||
|
||
# Entity & Concept Rules（关键增强）
|
||
|
||
## Entity（实体）
|
||
|
||
创建条件：
|
||
- 出现 ≥ 2 次
|
||
或
|
||
- 对主题有关键影响
|
||
|
||
类型：
|
||
- 人 / 公司 / 产品 / 项目
|
||
|
||
---
|
||
|
||
## Concept（概念）
|
||
创建条件：
|
||
- 可抽象
|
||
- 可复用
|
||
- 非具体实例
|
||
---
|
||
|
||
## 命名规范（强制）
|
||
- 使用唯一标准名称
|
||
- 所有别名写入页面：
|
||
|
||
```markdown
|
||
## Aliases
|
||
- GPT4
|
||
- GPT-4
|
||
```
|
||
|
||
---
|
||
|
||
## 去重机制（必须）
|
||
|
||
创建前必须：
|
||
1. 搜索 index
|
||
2. 判断是否存在
|
||
3. 存在则更新
|
||
|
||
---
|
||
|
||
# Query Workflow（查询流程）
|
||
|
||
触发：
|
||
- `/wiki-query`
|
||
- 或：`query: 问题`
|
||
|
||
---
|
||
|
||
## 步骤
|
||
|
||
1. 读取 index
|
||
2. 找到相关页面
|
||
3. 使用 Read 工具加载
|
||
4. 输出结构化答案
|
||
5. 使用 `[[Page]]` 引用
|
||
6. 询问是否保存为 synthesis
|
||
|
||
---
|
||
|
||
# Lint Workflow（校验）
|
||
|
||
检查内容：
|
||
|
||
- 孤立页面
|
||
- 断链
|
||
- 冲突
|
||
- 过期内容
|
||
- 缺失Entity
|
||
- 缺失Concept
|
||
- 知识空白
|
||
|
||
---
|
||
|
||
# Graph Workflow（知识图谱）
|
||
|
||
触发：
|
||
- `/wiki-graph`
|
||
|
||
---
|
||
|
||
执行：
|
||
- 优先运行 `tools/build_graph.py`
|
||
- 否则手动构建：
|
||
|
||
步骤：
|
||
1. 提取所有 `[[links]]`
|
||
2. 构建节点与边
|
||
3. 输出 `graph.json`
|
||
|
||
---
|
||
|
||
# Naming Conventions（命名规范）
|
||
- Source：保留原始中文名称（去除特殊符号），非中文使用 kebab-case
|
||
- Entity：TitleCase
|
||
- Concept：TitleCase
|
||
|
||
---
|
||
|
||
# Index Format（索引结构）
|
||
|
||
```markdown
|
||
# Wiki Index
|
||
|
||
## Overview
|
||
- [Overview](overview.md)
|
||
|
||
## Sources
|
||
- [Title](sources/原始中文名.md)
|
||
|
||
## Entities
|
||
- [Entity](entities/Entity.md)
|
||
|
||
## Concepts
|
||
- [Concept](concepts/Concept.md)
|
||
|
||
## Syntheses
|
||
- [Title](syntheses/slug.md)
|
||
```
|
||
|
||
---
|
||
|
||
# Log Format（日志）
|
||
|
||
```
|
||
## [YYYY-MM-DD] ingest | 标题
|
||
- Source file: raw/xxx.md
|
||
- Status: ✅ 成功摄入
|
||
- Summary:
|
||
- Concepts created: xxx, xxx
|
||
- Source page: wiki/sources/xxx.md
|
||
- Notes:
|
||
```
|
||
|
||
---
|
||
|
||
# ✅ 最终目标
|
||
|
||
该系统用于：
|
||
|
||
- 知识沉淀
|
||
- 结构化理解
|
||
- 自动图谱构建
|
||
- Agent 推理支持
|
||
|
||
---
|
||
|
||
# END |