ishenwei/llm-wiki-agent

Fork 0

Files

weishen 8ec59e18a8 bug修复

2026-04-18 05:59:27 +08:00

12 KiB

Raw Permalink Blame History

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（页面格式）

每个页面必须包含：

---
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>

执行步骤（严格顺序）

使用 Read 工具完整读取 source 文档
读取 wiki/index.md 和 wiki/overview.md
生成 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 段落，格式为：
```
## Source File
- [[raw/相对路径/文件名.md]]
```
这是溯源链的关键环节，禁止省略。即使同一 raw 文件被多次 ingest，每次都要写明 ## Source File。
更新 wiki/index.md
更新 wiki/overview.md（如有必要）
创建或更新 Entity 页面
创建或更新 Concept 页面
检测并记录冲突

追加 wiki/log.md，输出格式必须包含实际使用的 slug：

 ## [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 格式

{
  "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 步执行）

执行 python tools/sync.py --check — 预览 raw/ 变化（新增/修改/删除）[Hermes]

确认变化列表后，启动 TMUX + Claude Code：

# 启动 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 错误。

Claude Code Agent 执行 ingest（9 步）[Claude Code Agent]
每完成一个文件，更新 manifest.json（记录 hash、slug、source_path）[Hermes]
deleted 文件：从 manifest 移除，保留 wiki 内容（不删除 orphan entity/concept）[Hermes]
检测 orphan entity/concept，报告但不删除**[Hermes]**
清理 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（增强结构）

---
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

---
title: "YYYY-MM-DD Diary"
type: source
tags: [diary]
date: YYYY-MM-DD
---
## Event Summary
## Key Decisions
## Energy & Mood
## Connections
## Shifts & Contradictions

Meeting Notes

---
title: "Meeting Title"
type: source
tags: [meeting]
date: YYYY-MM-DD
---
## Goal
## Key Discussions
## Decisions Made
## Action Items

Entity & Concept Rules（关键增强）

Entity（实体）

创建条件：

出现 ≥ 2 次
或
对主题有关键影响

类型：

人 / 公司 / 产品 / 项目

Concept（概念）

创建条件：

可抽象
可复用
非具体实例

命名规范（强制）

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

## Aliases
- GPT4
- GPT-4

去重机制（必须）

创建前必须：

搜索 index
判断是否存在
存在则更新

Query Workflow（查询流程）

触发：

/wiki-query
或：query: 问题

步骤

读取 index
找到相关页面
使用 Read 工具加载
输出结构化答案
使用 [[Page]] 引用
询问是否保存为 synthesis

Lint Workflow（校验）

检查内容：

孤立页面
断链
冲突
过期内容
缺失Entity
缺失Concept
知识空白

Graph Workflow（知识图谱）

触发：

/wiki-graph

执行：

优先运行 tools/build_graph.py
否则手动构建：

步骤：

提取所有 [[links]]
构建节点与边
输出 graph.json

Naming Conventions（命名规范）

Source：保留原始中文名称（去除特殊符号），非中文使用 kebab-case
Entity：TitleCase
Concept：TitleCase

Index Format（索引结构）

# 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 推理支持

12 KiB Raw Permalink Blame History Unescape Escape

LLM Wiki Agent — Schema & Workflow Instructions（中文版增强规范）

🔴 全局强制规则（CRITICAL）

1. 输出语言（必须遵守）

2. 输出风格（严格限制）

3. 结构化语义（必须）

Slash Commands（Claude Code）

自然语言示例

Directory Layout（目录结构）

Page Format（页面格式）

Ingest Workflow（摄取流程）

执行步骤（严格顺序）

Sync Workflow（同步更新流程）

manifest.json 格式

Slash Command

执行步骤（严格顺序）

Telegram 通知（/wiki-sync 执行时）

分批同步原则

Sync 状态报告格式

Source Page Format（增强结构）

Domain-Specific Templates（领域模板）

Diary / Journal

Meeting Notes

Entity & Concept Rules（关键增强）

Entity（实体）

Concept（概念）

命名规范（强制）

去重机制（必须）

Query Workflow（查询流程）

步骤

Lint Workflow（校验）

Graph Workflow（知识图谱）

Naming Conventions（命名规范）

Index Format（索引结构）

Log Format（日志）

✅ 最终目标

END

12 KiB

Raw Permalink Blame History