Phase 0-2: Schema cleanup, typed relations, event-driven automation

- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
@@ -0,0 +1,261 @@
+---
+created: 2026-04-28
+tags:
+  - note
+  - journal
+para: []
+---
+
+# Reading Club v2 — 项目指南与使用说明
+
+> 版本：v2 | 日期：2026-04-28 | 状态：已实现，待测试
+
+---
+
+## 一、项目概述
+
+Reading Club 是基于 opencode 的交互式多智能体阅读协作框架。它不是传统的 AI 摘要工具，而是一个**以人类读者为中心的读书会**——三个 AI 角色作为你的对话伙伴，围绕你正在阅读的书籍章节展开深度讨论。
+
+### 与传统 AI 阅读工具的区别
+
+| 传统工具 | Reading Club v2 |
+|----------|----------------|
+| AI 输出摘要，人类阅读 | 人类先发言，AI 回应 |
+| 单向输出 | 多轮对话 |
+| 中立客观的分析 | 带有鲜明认知偏见的角色 |
+| 一次性结果 | 交互式探索，人类可以追问、反驳、换角度 |
+| 输出即弃 | 自动归档为 LLM Wiki 页面 |
+
+---
+
+## 二、文件结构
+
+```
+kepano-obsidian-main/
+├── .agents/skills/reading-club/
+│   └── SKILL.md                  # ← 核心 Skill 定义（v2）
+├── wiki/
+│   └── ReadingClub.md            # ← Wiki 工具页面（刚生成）
+├── raw/
+│   ├── 呼吸之间_李谨伯/          # ← 可用书籍
+│   │   ├── 调息.md
+│   │   ├── 胎息法.md
+│   │   └── ...
+│   └── 《大国大民》王志纲/       # ← 可用书籍
+│       ├── 《大国大民》第一章-我是怎么读中国的.md
+│       └── ...
+└── .sisyphus/
+    └── plans/
+        └── reading-club-guide.md # ← 本文件
+```
+
+---
+
+## 三、快速开始
+
+### 前置条件
+
+1. opencode 已安装并运行
+2. 至少一本书已转换到 `raw/` 目录（使用 `tools/epub_converter/`）
+3. `.agents/skills/reading-club/SKILL.md` 存在
+
+### 第一步：选择书籍和章节
+
+查看可用书籍：
+
+```
+ls raw/
+```
+
+查看某本书的章节：
+
+```
+ls "raw/呼吸之间_李谨伯/"
+```
+
+### 第二步：启动 Reading Club
+
+在 opencode 对话中输入以下任一形式：
+
+**触发词形式**：
+```
+/reading-club book_path="raw/呼吸之间_李谨伯" chapter="调息.md"
+```
+
+**自然语言形式**：
+```
+我想用阅读俱乐部讨论《呼吸之间》的调息章节
+```
+
+**带模式指定**：
+```
+/reading-club book_path="raw/《大国大民》王志纲" chapter="《大国大民》第一章-我是怎么读中国的.md" mode="deep"
+```
+
+### 第三步：参与讨论
+
+框架会自动引导你进入讨论：
+
+1. **阅读开头** — 系统展示章节开头 3-5 句
+2. **说出第一反应** — 任何想法都行，一个词也可以
+3. **听取 Agent 分析** — 三个 Agent 会回应你的反应
+4. **自由对话** — 反驳、追问、提问、换角度
+5. **结束讨论** — 说"停止"即可
+
+### 第四步：查看输出
+
+讨论结束后，wiki 页面自动生成到：
+
+```
+wiki/{书名}-{章节名}-ReadingClub.md
+```
+
+---
+
+## 四、详细使用指南
+
+### 4.1 讨论模式选择
+
+| 场景 | 推荐模式 | 理由 |
+|------|----------|------|
+| 第一次使用，想体验一下 | `browse` | 4 轮快速完成，了解流程 |
+| 正常阅读，想深入讨论 | `balanced` | 8 轮，平衡深度和效率 |
+| 学术研究，需要深度分析 | `deep` | 14 轮，充分挖掘 |
+| 自己掌控节奏 | `human-led` | 你决定何时结束 |
+
+### 4.2 人类参与策略
+
+**最佳实践**：
+- 第一反应**越直觉越好**，不要过度思考
+- 当 Agent 说了一些你不认同的，**直接反驳**
+- 如果某个观点触发了联想，**追问**那个方向
+- 不确定说什么时，**"pass"** 让 Agent 继续也可以
+
+**避免**：
+- 只说"继续"让 Agent 自说自话（浪费了交互设计）
+- 等待 Agent 给出"正确答案"（没有正确答案）
+- 想要面面俱到（聚焦 1-2 个最有感觉的点）
+
+### 4.3 交互指令速查
+
+| 你想做什么 | 怎么说 | Agent 会怎样 |
+|------------|--------|-------------|
+| 分享想法 | "我觉得这里说其实不只是地理…" | 回应你的具体观点 |
+| 提问 | "为什么作者用'读'中国？" | 认真回答你的问题 |
+| 反驳某个 Agent | "我不同意 Critic" | 与你辩论 |
+| 深入某个话题 | "追问：一方水土养一方人" | 聚焦该话题 |
+| 换个视角 | "从反面想想" | 重新从对立面分析 |
+| 不想说话 | "pass" | Agent 继续讨论 |
+| 结束讨论 | "停止" | 生成 Wiki 页面 |
+
+### 4.4 输出内容解读
+
+Wiki 页面包含以下部分：
+
+| 部分 | 内容 | 价值 |
+|------|------|------|
+| **读者的第一反应** | 你最初的直觉 | 记录阅读起点 |
+| **初始回应** | 3 个 Agent 的第一轮分析 | 三个不同视角 |
+| **深入讨论** | 后续轮次记录 | 思想碰撞过程 |
+| **人类思考轨迹** | 你的观点如何变化 | 元认知记录 |
+| **Agent 共识与分歧** | Agent 之间的一致和分歧 | 多角度分析 |
+| **讨论总结** | 关键洞见 + 未决问题 | 行动指引 |
+
+---
+
+## 五、架构设计说明
+
+### 5.1 状态机
+
+```
+INIT → HUMAN_FIRST_READ → SEED_ROUND → PRESENT_SEED → CONVERSATION_LOOP* → SYNTHESIS → DONE
+```
+
+每个状态的详细说明见 `.agents/skills/reading-club/SKILL.md`。
+
+### 5.2 Agent 角色
+
+三个角色通过 prompt engineering 区分，底层使用相同的 `build` subagent：
+
+| 角色 | 刻意编码的偏见 | 目的 |
+|------|---------------|------|
+| Summarizer | 同化偏见 — 找秩序 | 梳理逻辑，找出核心结构 |
+| Critic | 对抗性偏见 — 找缺陷 | 质疑假设，发现盲点 |
+| Questioner | 好奇偏见 — 找问题 | 追问深层含义，打开新视角 |
+
+### 5.3 上下文管理
+
+| 层级 | 内容 | 策略 |
+|------|------|------|
+| 最近 3 轮 | 完整记录 | 逐字传递 |
+| 更早轮次 | 压缩摘要 | 每轮 1-2 句 |
+| 章节内容 | 首轮完整 | 之后仅引用路径 |
+| 总限制 | 6000 tokens | 超出则压缩最早的轮次 |
+
+### 5.4 技术实现
+
+- **编排**：Sisyphus（主 Agent）管理状态机和人类交互
+- **Agent 调度**：通过 `task(subagent_type="build")` 实现
+- **SEED_ROUND**：3 个 Agent 并行 `run_in_background=true`
+- **CONVERSATION_LOOP**：每轮 1 个 Agent 同步 `run_in_background=false`
+- **Wiki 输出**：SYNTHESIS 阶段由 build Agent 编译
+
+---
+
+## 六、v1 → v2 变更日志
+
+| 方面 | v1 | v2 |
+|------|----|----|
+| 人类角色 | 旁观者，只能说"继续/停止" | 主角，每轮先发言 |
+| Agent 语气 | Agent 之间对话 | 用"你"直接称呼人类 |
+| 每轮结构 | Agent→Agent→checkpoint | 人类→Agent→人类→Agent |
+| 讨论模式 | 3 种（browse/balanced/deep） | 4 种（+human-led） |
+| Prompt 格式 | ===摘要===/===核心主张=== 刚性格式 | 自然段落，以问题结尾 |
+| Wiki 输出 | "人类参与"是附录 | "人类思考轨迹"是核心 |
+| 人类指令 | 2 种（继续/停止） | 8 种（反驳/追问/换角度等） |
+| 错误处理 | 基础 | 增加"连续3轮pass主动询问" |
+
+---
+
+## 七、故障排除
+
+| 问题         | 原因           | 解决                      |
+| ---------- | ------------ | ----------------------- |
+| 触发词不识别     | SKILL.md 未加载 | 重启 opencode 会话          |
+| Agent 调度失败 | 模型配置/网络      | 检查 oh-my-openagent.json |
+| 章节不存在      | 路径错误         | 框架会自动列出可用章节             |
+| 章节太长       | >8000 tokens | 框架建议按小节分段               |
+| Wiki 写入冲突  | 文件已存在        | 自动添加时间戳后缀               |
+| Agent 输出泛泛 | 人类输入太模糊      | 尝试说具体的观点或问题             |
+
+---
+
+## 八、测试计划
+
+### 待执行测试
+
+- [ ] **基础功能测试**：`browse` 模式，4 轮，验证完整流程
+- [ ] **人类交互测试**：测试 8 种交互指令
+- [ ] **Wiki 输出验证**：检查 frontmatter、内容结构、溯源标注
+- [ ] **长章节测试**：`deep` 模式，14 轮
+- [ ] **边界测试**：章节不存在、Agent 调度失败、人类立即说停止
+
+### 推荐测试章节
+
+| 优先级 | 书籍 | 章节 | 理由 |
+|--------|------|------|------|
+| 1 | 《大国大民》 | 第一章 | 205行，长度适中 |
+| 2 | 《呼吸之间》 | 调息 | 核心章节，内容集中 |
+| 3 | 《呼吸之间》 | 胎息法 | 较短，适合快速测试 |
+
+---
+
+## 九、相关资源
+
+| 资源        | 位置                                     | 说明           |
+| --------- | -------------------------------------- | ------------ |
+| SKILL.md  | `.agents/skills/reading-club/SKILL.md` | 核心定义         |
+| Wiki 页面   | `wiki/ReadingClub.md`                  | 工具参考         |
+| 启动指南      | `.sisyphus/START-READING-CLUB.md`      | 快速启动（v1，需更新） |
+| AGENTS.md | `AGENTS.md`                            | 仓库操作规范       |
+| EPUB 转换   | `tools/epub_converter/`                | 准备书籍内容       |