giteahh/llm_wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e8c22a4794799a78e4b6ae3e4fa0ea27647edcb1
llm_wiki/tools/reading-club-guide.md
T
hehaiguang1123 a6f05ab2d5 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

8.7 KiB
Raw Blame History

created, tags, para
created tags para
2026-04-28
note
journal

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/ 准备书籍内容
Reference in New Issue View Git Blame Copy Permalink