当前问题 → 书架/笔记/章节交叉 → 推荐一本书的一小节 → 读后行动卡 → Markdown回流 → 周阅读行动复盘

看差异

同样一个问题：

我最近信息焦虑，总是在囤资料但不产出，今天该读什么？

普通推荐很容易给一串书名：信息管理、效率、认知、写作、项目管理。书可能都对，但问题还在原地。

真正需要被回答的是：

• 我现在是缺信息，还是缺一个能收束问题的框架？
• 这本书我是不是早就收藏过、读过、划过线？
• 今天到底读哪一小节，读完以后做什么？

carl-weread要给的是一个能在今天完成的小切口：

今天只读这一小节：
《某本书》｜某一章

为什么是它：
资料已经够多，真正卡住的是问题没有收束。这一节刚好能把「继续搜索」改成「提出一个更好的问题」。

读前问题：
我现在反复搜索，是为了做哪个判断？

读完只做一个动作：
把当前文章选题改写成一个问题句，别再扩成资料清单。

打开：weread://reading?bId=...&chapterUid=...

一句话定位：

carl-weread更像「今天这个问题，只读哪一节，然后怎么用」。

和原版/参考项目的区别

功能总览

核心方法

1. 先问问题，再找书

很多阅读推荐从主题开始，比如AI、产品、心理学。carl-weread先看你现在卡在哪里。

2. 书架、笔记、章节要交叉看

单看书架，会把「收藏过」误判成「真的需要」。单看笔记，又容易只围着旧兴趣转。carl-weread把几类数据放在一起看：

3. 阅读统计不比时长，比影响

微信读书已经能告诉你读了多久。这里不再做一个低配统计页。

weekly-loop关心的是：

这周哪次阅读变成了文章角度？
哪条划线进入了项目决策？
哪本书只是制造了收藏安全感？
下周只保留哪一条阅读主线？

所以它吃的输入包括：

微信读书统计 + 本周划线/行动卡 + Obsidian项目/选题上下文

触发话术

装上就能用

先说结论：如果你只是想让Agent理解这套阅读方法，安装SKILL.md就够；如果你要运行微信读书API、脚本、测试和写回功能，需要clone完整仓库。

轻量安装：只让Agent读到说明

hermes skills install https://raw.githubusercontent.com/LearnPrompt/carl-weread/main/SKILL.md

这一步只会安装SKILL.md。它适合加载使用说明，但不会带上scripts/、carl_weread/、workflows/和测试文件。

完整安装：真正运行这套工具

git clone https://github.com/LearnPrompt/carl-weread ~/.hermes/skills/carl-weread
cd ~/.hermes/skills/carl-weread
python3 -m venv .venv
.venv/bin/python -m pip install -U pip pytest
.venv/bin/python -m pytest tests -q

如果你已经clone了仓库，也可以在仓库里跑安装脚本：

scripts/install_skill.py

配置微信读书API Key

自然语言版：

帮我配置carl-weread的微信读书API Key。不要把key写进仓库，也不要在回复里打印key。

代码版：

scripts/setup_api_key.py

它会把key写入~/.config/carl-weread/api_key，文件权限为600，不会写入config.toml，也不会打印key。

也可以只在当前shell临时使用：

export WEREAD_API_KEY="<你的微信读书API Key>"

API Key获取入口：https://weread.qq.com/r/weread-skills

没有Obsidian怎么用

可以用。Obsidian只是最高配上下文源，不是硬依赖。

首次配置也给两种说法。

自然语言版：

帮我把carl-weread配置成WeRead-only模式。先不接Obsidian，只根据我的微信读书书架、笔记和阅读进度推荐。

代码版：

# Obsidian用户
scripts/setup.py --mode obsidian --path "/path/to/your/vault"

# 非Obsidian，但有本地Markdown/TXT笔记
scripts/setup.py --mode folder --path "/path/to/your/notes"

# 只使用当前对话上下文
scripts/setup.py --mode chat

# 只使用微信读书数据
scripts/setup.py --mode weread-only

配置默认写入：~/.config/carl-weread/config.toml。

今日推荐：一本书里的一小节

自然语言版：

根据我的微信读书书架和最近问题，推荐一本现在最该读的书，并告诉我今天只读哪一节。
我的问题是：我正在写一篇微信读书Skill文章，想找一个能推进文章结构的阅读切口。

代码版：

scripts/today_live.py \
  --brief "我正在写一篇微信读书Skill文章，请根据我的书架推荐一本最适合现在读的书，并告诉我今天只读哪一节。"

它会自动做这些事：

读取配置 → 收集上下文 → 拉微信读书书架/笔记/章节 → 选择一本书里的一小节 → 输出读前问题和读后动作

重点放在少一点：只给今天能读完、能接上当前问题的一节。

V0.3：推荐一本没读透但现在该读的书

这条能力不是再给一串书单。它会先看书架和笔记，排除已经明显消化过的书，再把微信读书推荐、相似书和当前问题放在一起交叉验证。

自然语言版：

给我推荐一本我没读过但现在该读的书。
我的问题是：我在写Agent Skill文章，需要找一个能解释「为什么Skill不能只封装API」的阅读切口。

代码版：

scripts/carl_weread.py recommend \
  --brief "我在写Agent Skill文章，需要找一个能解释为什么Skill不能只封装API的阅读切口。"

输出会包含：

推荐哪本书
为什么不是继续读老书
书架/笔记/推荐来源的证据
翻开后先问什么
读完只做哪个动作

读后行动卡与写回

行动卡要贴着书走。它必须带着书名、章节、划线/想法和当前问题一起生成，否则就会变成空泛总结。

自然语言版：

我刚读完《AI Engineering》的「Evals and workflows」。
这句划线对我有用：Agent的价值在模型、工具、上下文和验证之间。
我现在的问题是：我在写一篇介绍carl-weread的文章，需要把阅读变成可演示动作。
请把这次阅读消化成一张行动卡；如果已经配置写回，就存到我的笔记目录。

代码版：

scripts/carl_weread.py after-read \
  --book-title "AI Engineering" \
  --chapter-title "Evals and workflows" \
  --highlight "Agent的价值在模型、工具、上下文和验证之间。" \
  --current-problem "我在写一篇介绍carl-weread的文章，需要把阅读变成可演示动作。" \
  --writeback

如果你已经知道bookId和chapterUid，也可以让它先自动拉本章划线：

scripts/carl_weread.py after-read \
  --book-id BOOK_ID \
  --chapter-uid CHAPTER_UID \
  --book-title "AI Engineering" \
  --chapter-title "Evals and workflows" \
  --current-problem "我在写一篇介绍carl-weread的文章，需要把阅读变成可演示动作。" \
  --auto-fetch

如果这一章没有划线，它不会硬写总结，而是输出「无划线读后检查」：让你补一条原文/转述，说明它解释了哪个问题，再决定要不要生成行动卡。

写回路径形如：

<你的笔记目录>/carl-weread/reading-cards/YYYY-MM-DD-书名-章节.md

这张卡会保留「哪本书、哪一节、哪条划线、解决什么问题、下一步做什么」。周复盘从这些卡里读证据，避免空泛总结。

本周阅读行动复盘

自然语言版：

基于本周carl-weread写回的阅读行动卡，帮我做一次阅读复盘。
重点看：哪些阅读进入了文章或项目，哪些只是收藏安全感，下周只保留哪一条阅读主线。

代码版：

scripts/carl_weread.py weekly \
  --cards /path/to/reading-cards \
  --context "本周在写Agent Skill文章，也在验证carl-weread的安装链路"

这里不重复微信读书周报。微信读书周报告诉你「读了多久」，这里要回答：

哪本书的哪一节真的推进了工作？
哪条划线变成了文章角度或项目动作？
哪些收藏只是缓解焦虑？

打开微信读书

推荐输出中会给weread://深度链接。它依赖本机微信读书客户端和系统协议注册。更稳妥的输出方式：

open 'weread://reading?bId=BOOK_ID&chapterUid=CHAPTER_UID'

如果没有反应：

1. 安装并打开微信读书客户端。
2. 登录同一个微信读书账号。
3. 再执行上面的open命令。
4. 仍然打不开时，用书名和章节名在微信读书里手动搜索。

仓库结构

carl-weread/
├── SKILL.md          # Agent读取的技能说明
├── README.md         # 给人看的产品说明和安装指南
├── carl_weread/      # Python核心逻辑
├── scripts/          # 可直接运行的命令入口
├── workflows/        # 可复用工作流说明
├── shared/           # 输出风格等共享约定
└── tests/            # 回归测试

当前边界

• V0.3已经跑通真实WeRead API helper、今日章节、未读书推荐、读后划线检查、无划线追问、行动卡写回、周复盘和统一CLI。
• 推荐章节仍使用轻量规则，不做embedding或全文语义检索；它适合演示和日常使用，不伪装成完整阅读智能体。
• 未读书推荐会根据书架、笔记和推荐/相似书数据做交叉判断，但微信读书接口字段在不同账号上可能有差异，异常时应保留原始JSON样本再补适配。
• 写回会写入真实Obsidian vault或普通文件夹；Chat/WeRead-only模式默认只在对话中返回，不写文件。

开发者附录：WeRead原子能力

普通用户可以跳过这里。这一节给开发者调试接口、排查字段和复用底层API。

已知兼容处理：

• readdata默认补--mode=overall，避免服务端返回参数格式错误。
• recommend和similar默认补--count=12 --maxIdx=0，避免部分环境缺分页参数失败。
• best-bookmarks默认补--chapterUid=0，表示全书热门划线。
• readreviews --reviews=...支持JSON数组/对象参数。
• 频率超限时不要反复重试，优先复用.cache/weread/或/private/tmp/中已保存的候选章节JSON。

开发者如果只想调试候选章节生成，可以拆开跑：

scripts/fetch_candidates.py \
  --output .cache/weread/candidates.json \
  --limit-books 5

scripts/today.py \
  --config ~/.config/carl-weread/config.toml \
  --brief "我最近在做一个可分享的微信读书Skill" \
  --chapters .cache/weread/candidates.json

致谢

• 微信读书官方API提供底层能力：https://weread.qq.com/r/weread-skills
• huashu-weread提供了「书架+笔记交叉分析」这个关键启发：https://github.com/alchaincyf/huashu-weread
• jerlin-weread启发了CLI化、字段契约和Agent可稳定调用的工程底座：https://github.com/jerlinn/jerlin-weread