huashu-weread-advisor
New微信读书高阶顾问。在底层 weread skill 的原子 API 之上，提供四类工作流：基于已读做个性化进阶推荐（advisor）、给方向规划入门到前沿的阶梯书单（path）、把零散划线想法提炼成读书笔记总结（alchemy）、做季度/年度阅读复盘并生成可发朋友圈/公众号的文章（review）。核心方法是「书架 + 笔记交叉分析」——书架揭示用户主动分类的兴趣，笔记数据揭示「真读过的」vs「只放着的」。当用户说「推荐书」「下一本读啥」「该读什么」「想搞懂 X 这个领域」「整理我的笔记」「这本书我记住了啥」「我今年读了什么」「读书复盘」「年度盘点」时触发。即使用户只是说「不知道读啥」「有没有相关的书」「帮我看看这本读完了吗」「这个领域我入门了吗」也应触发。
Summary
huashu-weread-advisor is a high-level reading advisor that orchestrates WeRead APIs into four workflows: personalized recommendations, curated reading paths, note distillation, and reading reviews.
- It cross-analyzes your bookshelf and notebook data to uncover what you've truly read versus what's just sitting there, then delivers actionable insights with deep links.
Overview
huashu-weread-advisor
把原子的微信读书 API 变成一个真正读懂你的读书顾问。
定位
底层 weread skill 提供原子接口（搜索、书架、笔记、点评、推荐、阅读统计），本 skill 在其之上做工作流编排，把原始数据转成对用户有消费价值的产出。
前置依赖
- •必须先有
WEREAD_API_KEY环境变量（在用户 shell 中 export） - •所有 API 调用走
POST https://i.weread.qq.com/api/agent/gateway - •请求 body 必须带
skill_version字段——值的权威来源：~/.claude/skills/weread/SKILL.md顶部 frontmatter 的version字段（当前1.0.3，会变；别从 prompt 或老模板里抄） - •接口文档和参数详情见底层 weread skill：
~/.claude/skills/weread/SKILL.md
核心方法论（所有 workflow 共享）
1. 书架和笔记是两个数据源，必须交叉
| 数据源 | 接口 | 揭示什么 |
|---|---|---|
| 书架 | /shelf/sync | 用户主动分类的兴趣方向 + 加入了什么 |
| 笔记 | /user/notebooks | 用户真读过的书 + 读得多深（笔记条数） |
| 进度 | /book/getprogress | 某本书读到哪、累计读了多久 |
| 统计 | /readdata/detail | 周/月/年阅读时长、天数、主题偏好 |
关键洞察：很多书在书架但没动，很多书没在书架（借/试读）但深读了。只看书架会漏掉重要信号。
实战例子：花叔的 Kandel《追寻记忆的痕迹》27 条笔记，书架的「心理学」分类里根本没列，但其实是他在神经科学领域读得最深的一本。如果只看书架做推荐，会误判他的真实知识地图。
2. 「最近读什么」≠「书架主题」
用户的当前兴趣可能和书架分类完全不一致。永远用 readUpdateTime 倒序看最近 30 天在动什么书，再做推荐。
3. 推荐必附 weread:// 深度链接
weread://reading?bId={bookId} 让用户一键打开。链接格式详见底层 weread skill 的「深度链接（URL Schema）」章节。
4. 推荐前必须验证微信读书是否上架
用 /store/search 搜确认。上架的附 weread:// 链接，不上架的明确告诉用户合法替代路径（购买纸质/英文版/作者公开课/图书馆）。绝不推盗版资源。
5. 输出走花叔语言风格
- •不堆砌、不破折号（全文 ≤ 2 处）、人味重
- •用「」不用""
- •不用「首先/其次/综上」这类 AI 结构词
- •不用「说白了/简单来说/换句话说」
- •markdown 不过度加粗
- •详见
/04-写作参考/SHARED-RULES.md
检查点设计原则
所有 workflow 必须在「分叉影响输出本质」的地方插入用户确认 gate，防止 AI 默认值跑偏：
- •推荐数量分叉：advisor 推 3 本 vs 8 本完全不同的体验，不要默认 5 本，先问
- •平台语气分叉：复盘文章发朋友圈/公众号/小红书/视频脚本语气差很多，写前必须确认
- •段位判断分叉：path workflow 把「我以为你是入门」的判断给用户看，让他确认或纠正
- •数据量分叉：alchemy 跨主题模式拉出 50+ 划线时，先汇总议题让用户选子集，不要默认全聚
- •未上架处理分叉：推荐里要不要包含未上架的书（用户可能只想要点开就能读的）
检查点不是「每步都问」。日常小决策（哪本放第一梯队、用什么动词）AI 自己定，不要打扰用户。规则是：只在选项影响输出本质时问。
如果用户原始 prompt 已经明确指定（「推 3 本上架的发公众号」），所有相关检查点都跳过。
子命令路由
| 用户说什么 | 走哪个 workflow |
|---|---|
| 推荐书 / 下一本读啥 / 不知道读啥 / 想读 X 方向 | advisor.md |
| 想搞懂 X 这个领域 / 系统学习 X / 从零入门 X | path.md |
| 整理我的笔记 / 这本书我记住了啥 / 提炼这个主题的划线 | alchemy.md |
| 我今年读了什么 / 季度复盘 / 年度盘点 / 写一篇复盘 | review.md |
| 我现在在读哪本 / 最近在读啥 | 轻量直答（见下方） |
轻量直答：「我现在在读哪本」
不走 workflow，直接：
/shelf/sync拿全书架- 按
readUpdateTime倒序取 top 5 - 用最新那本调
/book/getprogress拿章节/进度/累计时长 - 一句话回复「你正在读 X，已到第 N 章，进度 X%，累计读了 X 小时」，附 weread:// 链接
- 顺带说一句最近一周在读的其他几本，看出主题倾向
共享子模块
- •shared/knowledge-map.md：怎么读懂一个人的知识地图（三个数据源 × 三种交叉信号）
- •shared/shelf-cross-notes.md：书架 + 笔记交叉分析的 Python 代码模板和主题关键词组
示例
- •examples/advisor-neuroscience.md：花叔「神经科学如何更进一步」案例的完整复盘，含步骤、输出、为什么这样推
异常与边界条件
实操常遇异常。以下为全局通用 fallback，所有 workflow 共享。workflow 各自的特殊异常在各自文档末尾。
| 场景 | 触发条件 | 处理动作 |
|---|---|---|
WEREAD_API_KEY 未设置 | 环境变量不存在或不是 wrk- 开头 | 报错：「请先 export WEREAD_API_KEY=<你的apikey>，从微信读书后台获取」，终止 |
API 返回 errcode != 0 | 接口报错 | 显示中文错误信息，重试 1 次；仍失败告知用户并停止当前 workflow |
接口返回 upgrade_info | 服务端要求 skill 版本升级 | 暂停当前操作，按 upgrade_info.message 完成升级后重试，不得忽略 |
| `/store/search` 响应解析 | 解析返回 JSON | 顶层不是 books[]！实际结构是 results[]，按 section 分类。取上架：results[?title=='电子书'].books[*].bookInfo；取未上架：title=='待上架'。每本书的 bookId 在 bookInfo.bookId。别用 `res.get('books', [])`，会全部 0 结果 |
/store/search 多候选 | 同关键词返回 ≥ 3 本候选 | 默认取 readingCount 最高且作者完全匹配的（作者错位视同零结果，避免「Co-Intelligence」误命中「Collaborative Intelligence」类似的坑），明确告知用户「我用了《X》这本 by Y，bookId=Z，如果不对告诉我」 |
/store/search 零结果 | 完全搜不到 + 关键词调整 + 作者过滤后仍零 | 标记为「未上架」，按 advisor 的「合法替代路径」规则处理，绝不推盗版 |
| notebooks 完全空 | 新用户 / 从未做笔记 | 退化：仅用 /shelf/sync 推断，但明确告知用户「你没做过笔记，我只能用书架猜兴趣，准度会差一些」 |
| 书架完全空 | 全新用户 | 不走 advisor / review / alchemy，建议先读几本；或直接进 path workflow 从零规划 |
| 接口分页未拉完 | /user/notebooks 有 hasMore | 用 lastSort 继续翻页（参数平铺，不要包在 `params` 里）；累计 > 500 本时给用户警告 |
readUpdateTime = 0 | 加入书架但从未打开 | 当作「未读」，不纳入「最近活跃」排序，但仍计入「书架有但没动」 |
| 用户给的书名搜不到 | alchemy / 任何指名书的场景 | 先模糊搜（去标点/去副标题）；仍不到给候选清单让用户选 |
| 主题词过宽或过窄 | 「商业」「人文」太宽；冷门词太窄 | 过宽：请用户细化方向；过窄：告知微信读书覆盖薄，建议组合纸质/Kindle |
原则：异常先告知用户，再按规则处理；绝不静默跳过或静默失败；接口报错的具体含义看底层 weread skill 的 references/ 文档。
数据展示规范（强制）
所有 workflow 输出给用户时遵守：
- •Unix 时间戳（
readUpdateTime/finishTime/createTime等）→ 转YYYY-MM-DD，禁止直接展示数字 - •阅读时长字段单位是秒 → 转「X 小时 Y 分钟」，零小时时只写分钟
- •进度字段展示为
X% - •bookId 在用户面前不出现裸数字，要么变成 weread:// 链接，要么藏在 markdown 链接里
调用约定
无论走哪个 workflow，第一步都是先读 SKILL.md 本文件 + 对应 workflow 文件 + shared/knowledge-map.md，然后才开始调 API。不要凭印象做推荐，所有推荐必须有数据支撑。
Install & Usage
mkdir -p .claude/skillsmkdir -p .claude/skills && curl -o .claude/skills/huashu-weread-advisor.md https://raw.githubusercontent.com/alchaincyf/huashu-weread/main/SKILL.md/huashu-weread-advisorUse Cases
Usage Examples
/huashu-weread-advisor recommend me 3 books based on what I've read this month
/huashu-weread-advisor path for learning machine learning from scratch
/huashu-weread-advisor alchemy summarize my notes from 'Thinking, Fast and Slow'
Security Audits
Frequently Asked Questions
What is huashu-weread-advisor?
huashu-weread-advisor is a high-level reading advisor that orchestrates WeRead APIs into four workflows: personalized recommendations, curated reading paths, note distillation, and reading reviews. It cross-analyzes your bookshelf and notebook data to uncover what you've truly read versus what's just sitting there, then delivers actionable insights with deep links.
How to install huashu-weread-advisor?
To install huashu-weread-advisor: create the skills directory (mkdir -p .claude/skills), then run: mkdir -p .claude/skills && curl -o .claude/skills/huashu-weread-advisor.md https://raw.githubusercontent.com/alchaincyf/huashu-weread/main/SKILL.md. Finally, /huashu-weread-advisor in Claude Code.
What is huashu-weread-advisor best for?
huashu-weread-advisor is a skill categorized under General. It is designed for: code-review, api. Created by alchaincyf.
What can I use huashu-weread-advisor for?
huashu-weread-advisor is useful for: Get personalized book recommendations based on your actual reading history and notes.; Receive a structured reading path from beginner to advanced in a new domain.; Transform scattered highlights and notes into a coherent book summary.; Generate a quarterly or annual reading review ready to share on social media.; Check whether you've actually finished a book or just added it to your shelf.; Identify gaps in your knowledge map for a specific field..