---
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/`                | 准备书籍内容       |