修改版本

2026-04-16 16:55:22 +08:00
parent 2a42f9797b
commit f9db36bc38
3 changed files with 1812 additions and 182 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,12 +47,13 @@ Transformer（变压器模型，一种基于注意力机制的神经网络架构

 # 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` |
+| 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` 执行 |

 ---

@@ -117,6 +118,12 @@ last_updated: YYYY-MM-DD
 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 页面
@@ -124,6 +131,142 @@ last_updated: YYYY-MM-DD
 8. 检测并记录冲突
 9. 追加 `wiki/log.md`

+> ⚠️ 本项目所有 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' 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（增强结构）