Skip to content
Back to search

huashu-weread-advisor

SkillWorks with Claude CodeGitHub

微信读书高阶顾问。在底层 weread skill 的原子 API 之上,提供四类工作流:基于已读做个性化进阶推荐(advisor)、给方向规划入门到前沿的阶梯书单(path)、把零散划线想法提炼成读书笔记总结(alchemy)、做季度/年度阅读复盘并生成可发朋友圈/公众号的文章(review)。核心方法是「书架 + 笔记交叉分析」——书架揭示用户主动分类的兴趣,笔记数据揭示「真读过的」vs「只放着的」。当用户说「推荐书」「下一本读啥」「该读什么」「想搞懂 X 这个领域」「整理我的笔记」「这本书我记住了啥」「我今年读了什么」「读书复盘」「年度盘点」时触发。即使用户只是说「不知道读啥」「有没有相关的书」「帮我看看这本读完了吗」「这个领域我入门了吗」也应触发。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alchaincyf--huashu-weread/badge.svg)](/listings/alchaincyf--huashu-weread)

HTML

<a href="/listings/alchaincyf--huashu-weread"><img src="/api/listings/alchaincyf--huashu-weread/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 142 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: huashu-weread-advisor
  3. description: 微信读书高阶顾问。在底层 weread skill 的原子 API 之上,提供四类工作流:基于已读做个性化进阶推荐(advisor)、给方向规划入门到前沿的阶梯书单(path)、把零散划线想法提炼成读书笔记总结(alchemy)、做季度/年度阅读复盘并生成可发朋友圈/公众号的文章(review)。核心方法是「书架 + 笔记交叉分析」——书架揭示用户主动分类的兴趣,笔记数据揭示「真读过的」vs「只放着的」。当用户说「推荐书」「下一本读啥」「该读什么」「想搞懂 X 这个领域」「整理我的笔记」「这本书我记住了啥」「我今年读了什么」「读书复盘」「年度盘点」时触发。即使用户只是说「不知道读啥」「有没有相关的书」「帮我看看这本读完了吗」「这个领域我入门了吗」也应触发。
  4. ---
  5. # huashu-weread-advisor
  6. 把原子的微信读书 API 变成一个真正读懂你的读书顾问。
  7. ## 定位
  8. 底层 weread skill 提供原子接口(搜索、书架、笔记、点评、推荐、阅读统计),本 skill 在其之上做**工作流编排**,把原始数据转成对用户有消费价值的产出。
  9. ## 前置依赖
  10. - 必须先有 `WEREAD_API_KEY` 环境变量(在用户 shell 中 export)
  11. - 所有 API 调用走 `POST https://i.weread.qq.com/api/agent/gateway`
  12. - 请求 body 必须带 `skill_version` 字段——**值的权威来源**:`~/.claude/skills/weread/SKILL.md` 顶部 frontmatter 的 `version` 字段(当前 `1.0.3`,会变;别从 prompt 或老模板里抄)
  13. - 接口文档和参数详情见底层 weread skill:`~/.claude/skills/weread/SKILL.md`
  14. ## 核心方法论(所有 workflow 共享)
  15. ### 1. 书架和笔记是两个数据源,必须交叉
  16. | 数据源 | 接口 | 揭示什么 |
  17. |--------|------|---------|
  18. | 书架 | `/shelf/sync` | 用户**主动分类**的兴趣方向 + 加入了什么 |
  19. | 笔记 | `/user/notebooks` | 用户**真读过**的书 + 读得多深(笔记条数) |
  20. | 进度 | `/book/getprogress` | 某本书读到哪、累计读了多久 |
  21. | 统计 | `/readdata/detail` | 周/月/年阅读时长、天数、主题偏好 |
  22. **关键洞察**:很多书在书架但没动,很多书没在书架(借/试读)但深读了。只看书架会漏掉重要信号。
  23. **实战例子**:花叔的 Kandel《追寻记忆的痕迹》27 条笔记,书架的「心理学」分类里根本没列,但其实是他在神经科学领域读得最深的一本。如果只看书架做推荐,会误判他的真实知识地图。
  24. ### 2. 「最近读什么」≠「书架主题」
  25. 用户的当前兴趣可能和书架分类完全不一致。永远用 `readUpdateTime` 倒序看最近 30 天在动什么书,再做推荐。
  26. ### 3. 推荐必附 weread:// 深度链接
  27. `weread://reading?bId={bookId}` 让用户一键打开。链接格式详见底层 weread skill 的「深度链接(URL Schema)」章节。
  28. ### 4. 推荐前必须验证微信读书是否上架
  29. 用 `/store/search` 搜确认。上架的附 weread:// 链接,不上架的明确告诉用户合法替代路径(购买纸质/英文版/作者公开课/图书馆)。**绝不推盗版资源**。
  30. ### 5. 输出走花叔语言风格
  31. - 不堆砌、不破折号(全文 ≤ 2 处)、人味重
  32. - 用「」不用""
  33. - 不用「首先/其次/综上」这类 AI 结构词
  34. - 不用「说白了/简单来说/换句话说」
  35. - markdown 不过度加粗
  36. - 详见 `/04-写作参考/SHARED-RULES.md`
  37. ## 检查点设计原则
  38. 所有 workflow 必须在「分叉影响输出本质」的地方插入用户确认 gate,防止 AI 默认值跑偏:
  39. - **推荐数量分叉**:advisor 推 3 本 vs 8 本完全不同的体验,不要默认 5 本,先问
  40. - **平台语气分叉**:复盘文章发朋友圈/公众号/小红书/视频脚本语气差很多,写前必须确认
  41. - **段位判断分叉**:path workflow 把「我以为你是入门」的判断给用户看,让他确认或纠正
  42. - **数据量分叉**:alchemy 跨主题模式拉出 50+ 划线时,先汇总议题让用户选子集,不要默认全聚
  43. - **未上架处理分叉**:推荐里要不要包含未上架的书(用户可能只想要点开就能读的)
  44. 检查点不是「每步都问」。日常小决策(哪本放第一梯队、用什么动词)AI 自己定,不要打扰用户。规则是:**只在选项影响输出本质时问**。
  45. 如果用户原始 prompt 已经明确指定(「推 3 本上架的发公众号」),所有相关检查点都跳过。
  46. ## 子命令路由
  47. | 用户说什么 | 走哪个 workflow |
  48. |-----------|----------------|
  49. | 推荐书 / 下一本读啥 / 不知道读啥 / 想读 X 方向 | [advisor.md](workflows/advisor.md) |
  50. | 想搞懂 X 这个领域 / 系统学习 X / 从零入门 X | [path.md](workflows/path.md) |
  51. | 整理我的笔记 / 这本书我记住了啥 / 提炼这个主题的划线 | [alchemy.md](workflows/alchemy.md) |
  52. | 我今年读了什么 / 季度复盘 / 年度盘点 / 写一篇复盘 | [review.md](workflows/review.md) |
  53. | 我现在在读哪本 / 最近在读啥 | 轻量直答(见下方) |
  54. ### 轻量直答:「我现在在读哪本」
  55. 不走 workflow,直接:
  56. 1. `/shelf/sync` 拿全书架
  57. 2. 按 `readUpdateTime` 倒序取 top 5
  58. 3. 用最新那本调 `/book/getprogress` 拿章节/进度/累计时长
  59. 4. 一句话回复「你正在读 X,已到第 N 章,进度 X%,累计读了 X 小时」,附 weread:// 链接
  60. 5. 顺带说一句最近一周在读的其他几本,看出主题倾向
  61. ## 共享子模块
  62. - [shared/knowledge-map.md](shared/knowledge-map.md):怎么读懂一个人的知识地图(三个数据源 × 三种交叉信号)
  63. - [shared/shelf-cross-notes.md](shared/shelf-cross-notes.md):书架 + 笔记交叉分析的 Python 代码模板和主题关键词组
  64. ## 示例
  65. - [examples/advisor-neuroscience.md](examples/advisor-neuroscience.md):花叔「神经科学如何更进一步」案例的完整复盘,含步骤、输出、为什么这样推
  66. ## 异常与边界条件
  67. 实操常遇异常。以下为全局通用 fallback,所有 workflow 共享。workflow 各自的特殊异常在各自文档末尾。
  68. | 场景 | 触发条件 | 处理动作 |
  69. |------|---------|---------|
  70. | `WEREAD_API_KEY` 未设置 | 环境变量不存在或不是 `wrk-` 开头 | 报错:「请先 export WEREAD_API_KEY=<你的apikey>,从微信读书后台获取」,终止 |
  71. | API 返回 `errcode != 0` | 接口报错 | 显示中文错误信息,重试 1 次;仍失败告知用户并停止当前 workflow |
  72. | 接口返回 `upgrade_info` | 服务端要求 skill 版本升级 | 暂停当前操作,按 `upgrade_info.message` 完成升级后重试,**不得忽略** |
  73. | **`/store/search` 响应解析** | 解析返回 JSON | 顶层不是 `books[]`!实际结构是 `results[]`,按 section 分类。取上架:`results[?title=='电子书'].books[*].bookInfo`;取未上架:`title=='待上架'`。每本书的 bookId 在 `bookInfo.bookId`。**别用 `res.get('books', [])`,会全部 0 结果** |
  74. | `/store/search` 多候选 | 同关键词返回 ≥ 3 本候选 | 默认取 `readingCount` 最高且**作者完全匹配**的(作者错位视同零结果,避免「Co-Intelligence」误命中「Collaborative Intelligence」类似的坑),**明确告知用户**「我用了《X》这本 by Y,bookId=Z,如果不对告诉我」 |
  75. | `/store/search` 零结果 | 完全搜不到 + 关键词调整 + 作者过滤后仍零 | 标记为「未上架」,按 advisor 的「合法替代路径」规则处理,**绝不推盗版** |
  76. | notebooks 完全空 | 新用户 / 从未做笔记 | 退化:仅用 `/shelf/sync` 推断,但**明确告知用户**「你没做过笔记,我只能用书架猜兴趣,准度会差一些」 |
  77. | 书架完全空 | 全新用户 | 不走 advisor / review / alchemy,建议先读几本;或直接进 path workflow 从零规划 |
  78. | 接口分页未拉完 | `/user/notebooks` 有 `hasMore` | 用 `lastSort` 继续翻页(参数平铺,**不要包在 `params` 里**);累计 > 500 本时给用户警告 |
  79. | `readUpdateTime` = 0 | 加入书架但从未打开 | 当作「未读」,不纳入「最近活跃」排序,但仍计入「书架有但没动」 |
  80. | 用户给的书名搜不到 | alchemy / 任何指名书的场景 | 先模糊搜(去标点/去副标题);仍不到给候选清单让用户选 |
  81. | 主题词过宽或过窄 | 「商业」「人文」太宽;冷门词太窄 | 过宽:请用户细化方向;过窄:告知微信读书覆盖薄,建议组合纸质/Kindle |
  82. **原则**:异常先告知用户,再按规则处理;绝不静默跳过或静默失败;接口报错的具体含义看底层 weread skill 的 `references/` 文档。
  83. ## 数据展示规范(强制)
  84. 所有 workflow 输出给用户时遵守:
  85. - **Unix 时间戳**(`readUpdateTime` / `finishTime` / `createTime` 等)→ 转 `YYYY-MM-DD`,禁止直接展示数字
  86. - **阅读时长字段**单位是秒 → 转「X 小时 Y 分钟」,零小时时只写分钟
  87. - **进度字段**展示为 `X%`
  88. - **bookId** 在用户面前不出现裸数字,要么变成 weread:// 链接,要么藏在 markdown 链接里
  89. ## 调用约定
  90. 无论走哪个 workflow,第一步都是先读 `SKILL.md` 本文件 + 对应 workflow 文件 + `shared/knowledge-map.md`,然后才开始调 API。不要凭印象做推荐,所有推荐必须有数据支撑。
  91. ## 版本自检(静默)
  92. 本节给 AI agent:每次使用本 skill 前,先做一个不联网的判断——读本 skill 目录(SKILL.md 所在目录)下的 `.last-update-check` 文件(内容为一行日期 YYYY-MM-DD)。文件存在且距今不足 30 天,跳过本节直接干活,不向用户提任何更新相关的话。
  93. 到期或文件不存在时,且仅在此时:
  94. 1. 本目录不是 git 克隆(无 `.git` 或无 origin)→ 写入今天日期后跳过本节
  95. 2. 对比版本:`git -C <本目录> rev-parse HEAD` 与 `git -C <本目录> ls-remote origin HEAD`
  96. 3. 无论结果如何,把今天日期写入 `.last-update-check`
  97. 4. 两者一致 → 什么都不说;确认落后 → 先完成用户当前任务,结束后附一句「本 skill 有新版本,可用 `git -C <本目录> pull --ff-only` 更新」。是否更新由用户决定,不要主动执行更新
README.md · README · 193 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # huashu-weread
  3. > *「不是查数据。是 AI 把你忘掉的那些时刻还给你。」*
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  5. [![Agent-Agnostic](https://img.shields.io/badge/Agent-Agnostic-blueviolet)](https://skills.sh)
  6. [![Skills](https://img.shields.io/badge/skills.sh-Compatible-green)](https://skills.sh)
  7. <br>
  8. **微信读书高阶顾问 · 在官方 weread skill 之上加一层「读书顾问的工作流」**
  9. <br>
  10. 微信读书前几天上了一个官方 AI skill([weread.qq.com/r/weread-skills](https://weread.qq.com/r/weread-skills)),把书架、笔记、阅读统计、推荐 6 件事开放给 AI。能力很强,但它只是「自然语言包装的搜索接口」——你让它推荐书,它不会去看你已经读过什么,常把你笔记 68 条的书又当新书推回来给你。
  11. 本 skill 在官方 8 个 API 之上,加一层「**读书顾问的工作流**」。核心方法是「**书架 + 笔记交叉分析**」——书架揭示你「主动归类的兴趣」,笔记揭示你「真读过的书」。只看书架会漏信号,只看笔记会错过兴趣方向。
  12. ```
  13. npx skills add alchaincyf/huashu-weread
  14. ```
  15. 跨 agent 通用——Claude Code、Cursor、Codex、OpenClaw、Hermes 都能装。
  16. [看效果对比](#看效果对比) · [装上就能用](#装上就能用) · [4 个 workflow](#4-个-workflow) · [核心方法](#核心方法书架--笔记交叉)
  17. </div>
  18. ---
  19. ## 看效果对比
  20. 同样一个问题:「**推荐下产品经理方向的书**」。
  21. **裸 weread skill 答:14 本通识书单**
  22. 按入门到进阶分了 6 个梯队,推《俞军产品方法论》《幕后产品》《硅谷增长黑客实战笔记》……都是好书,但:
  23. - 《俞军产品方法论》我做了 **68 条笔记**
  24. - 《幕后产品》**在我书架上躺着两年**
  25. - 《硅谷增长黑客》我做了 **34 条笔记**
  26. 它根本没看我的笔记和书架,只是一个用自然语言包装的搜索接口。把读过的书又当新书推回来。
  27. **huashu-weread 答:5 本针对你的拼图建议**
  28. | 推荐 | 理由(基于你的实际阅读数据) |
  29. |---|---|
  30. | 《转型启示录》Marty Cagan | 你读了俞军、苏杰这一脉中国 PM 经典,但完全没碰 Cagan |
  31. | 《设计心理学》诺曼 | 你方法论书一堆但 UX 根基缺 |
  32. | 《AI Product Manager's Handbook》 | 你在做 AI 产品但 AI PM 书架空白 |
  33. | 《重来》Jason Fried | 你是独立开发者但读的 PM 书大多是大公司视角 |
  34. | 《重来 3》 | 你之前加了《小而美》没读完,这本是同一谱系更系统 |
  35. 最后还给「如果只读一本:X」和「如果想真正再上一个台阶:Y+Z」两个明确建议。
  36. 差距:**裸 weread 给的是「合格的通识书单」,huashu-weread 给的是「针对你这个人的拼图建议」**。
  37. ---
  38. ## 装上就能用
  39. **前置依赖**:必须先装官方 weread skill([weread.qq.com/r/weread-skills](https://weread.qq.com/r/weread-skills)),按页面指引走两步配置(复制安装指令 + 登录拿 API Key),全程不超过 1 分钟。
  40. 装完官方后,再装本 skill:
  41. ```bash
  42. npx skills add alchaincyf/huashu-weread
  43. ```
  44. 跑起来:
  45. ```
  46. "推荐下一本读啥" → 自动走 advisor
  47. "想系统搞懂行为经济学" → 自动走 path
  48. "整理下我在《掌控习惯》里的笔记" → 自动走 alchemy
  49. "写一篇我今年的读书复盘" → 自动走 review
  50. "我现在在读哪本" → 轻量直答,一句话给进度
  51. ```
  52. 模糊的需求也认:「不知道读啥」「有相关的书吗」「这本书我记住了啥」「我今年读了什么」都能正确路由。
  53. ---
  54. ## 4 个 workflow
  55. | Workflow | 干什么 | 触发话术 |
  56. |---|---|---|
  57. | **advisor** | 推荐下一本读什么。扒书架+笔记交叉,找拼图缺口,验证微信读书是否上架 | 「推荐书」「下一本读啥」「不知道读啥」 |
  58. | **path** | 想搞懂一个领域。先判断你段位,再给入门→进阶→前沿的阶梯书单 | 「想搞懂 X」「从零入门 X」「系统学习 X」 |
  59. | **alchemy** | 整理你的笔记。把零散划线想法提炼成有结构的读书笔记 | 「整理我的笔记」「这本书我记住了啥」 |
  60. | **review** | 写读书复盘。给一段时间,输出能发朋友圈/公众号/小红书的复盘文章 | 「我今年读了什么」「年度盘点」 |
  61. 每个 workflow 都有独立的方法论文档,详见 [`workflows/`](workflows/):
  62. - [`workflows/advisor.md`](workflows/advisor.md) — 读书顾问标准流程
  63. - [`workflows/path.md`](workflows/path.md) — 入门到前沿的阶梯规划
  64. - [`workflows/alchemy.md`](workflows/alchemy.md) — 笔记提炼标准流程
  65. - [`workflows/review.md`](workflows/review.md) — 读书复盘文章生成
  66. ---
  67. ## 核心方法:书架 + 笔记交叉
  68. 整套 skill 的方法论建立在三个数据源 × 三种交叉信号上。
  69. ### 三个数据源
  70. | 源 | 接口 | 揭示什么 |
  71. |---|---|---|
  72. | 书架分类 | `/shelf/sync` 的 `archive[]` | 用户**主动给书归类**的兴趣方向 |
  73. | 书架书目 | `/shelf/sync` 的 `books[]` | 加入书架的所有书 + 每本最近翻页时间 |
  74. | 笔记列表 | `/user/notebooks` | 真做了笔记的书 + 每本笔记条数 |
  75. ### 三种交叉信号
  76. **信号 1:真读 vs 放着**
  77. | 状态 | 判定条件 | 含义 |
  78. |---|---|---|
  79. | 真读了 | 书架有 + notebooks 有 + 笔记 ≥ 5 | 吃进去了的书 |
  80. | 放着没动 | 书架有 + notebooks 无 | 收藏癖,不是真兴趣 |
  81. | 隐藏深读 | 书架无 + notebooks 有 + 笔记 ≥ 10 | 借/试读但真读了,常被推荐忽略 |
  82. | 浅尝即止 | 书架有 + notebooks 笔记 1-3 条 | 翻了几页就放下 |
  83. **信号 2:深度 vs 广度**——按笔记条数分层(≥20 重度,10-20 中度,3-10 轻度,1-3 翻过)
  84. **信号 3:最近 vs 历史**——用 `readUpdateTime` 看最近 30 天活跃书目(用户当前兴趣常和书架分类不一致)
  85. 完整方法论见 [`shared/knowledge-map.md`](shared/knowledge-map.md)。
  86. ---
  87. ## vs 官方 weread skill
  88. | 维度 | 官方 weread | huashu-weread |
  89. |---|---|---|
  90. | 定位 | 能力提供者(8 个 API) | 读书顾问(4 个 workflow) |
  91. | 推荐书 | 调 `/store/search`,返回通识书单 | 先扒书架+笔记,再找拼图缺口 |
  92. | 整理笔记 | 调 `/book/bookmarklist`,给原始数据 | 按主题聚类,提炼结构化笔记 |
  93. | 阅读复盘 | 调 `/readdata/detail`,给统计数据 | 按平台(朋友圈/公众号/小红书)生成文章 |
  94. | 是否会去看用户已读什么 | 否 | 是(书架+笔记交叉) |
  95. 不是替代关系——huashu-weread 在官方 8 个 API 之上加了一层 prompt 工程层。装上后官方 skill 还在底层跑,两个不冲突。
  96. ---
  97. ## 异常与边界
  98. > 实操中常遇到的问题,全部有 fallback,绝不静默失败。详见 [`SKILL.md`](SKILL.md) 的「异常与边界条件」段。
  99. - `WEREAD_API_KEY` 未设置 → 报错并告知怎么获取
  100. - API 返回 `errcode != 0` → 重试 1 次,仍失败告知用户
  101. - 出现 `upgrade_info` → 暂停操作,按指引升级版本
  102. - notebooks 完全空(新用户)→ 退化到仅用书架推断,但明确告知准度会差
  103. - 书架完全空 → 不走 advisor,建议先读几本或切 path workflow
  104. - 用户主题模糊(如「想读点 AI 相关」)→ 在检查点先确认细分方向
  105. 所有数据展示遵守强制规范:Unix 时间戳转 `YYYY-MM-DD`,阅读时长秒转「X 小时 Y 分钟」,bookId 永远附 `weread://` 深度链接,绝不裸数字。
  106. ---
  107. ## 给 skill 开发者:本仓库的设计原则
  108. 如果你想做类似的「在原子 API 之上加一层工作流」的 skill,可以参考几个点:
  109. 1. **检查点设计**:在「分叉影响输出本质」的地方插入用户确认 gate,但日常小决策 AI 自己定,不打扰用户
  110. 2. **方法论先行**:所有 workflow 共享同一套核心方法论(书架+笔记交叉),workflow 只是不同场景的应用
  111. 3. **数据展示规范强制化**:时间戳、单位、深度链接的展示规则写进 SKILL.md 强制约束
  112. 4. **异常的 fallback 全部明示**:每种异常都有处理动作,不留「静默失败」的空间
  113. ---
  114. ## License
  115. MIT — 个人 + 商业用途均可,无需授权。
  116. ---
  117. ## 致谢
  118. - 微信读书官方 skill 把最难的事做完了(把账号数据通过 API 暴露给 AI):[weread.qq.com/r/weread-skills](https://weread.qq.com/r/weread-skills)
  119. - 灵感来源:花叔的 [女娲 .skill](https://github.com/alchaincyf/nuwa-skill)(把人物方法论蒸馏成 skill)。这次只是把蒸馏对象从「人」换成了「我自己的微信读书账号」。
  120. ---
  121. <div align="center">
  122. Made by [@AlchainHust](https://x.com/AlchainHust) · 公众号「花叔」
  123. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.