Huashu Weread Advisor

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. 书架和笔记是两个数据源，必须交叉

关键洞察：很多书在书架但没动，很多书没在书架（借/试读）但深读了。只看书架会漏掉重要信号。

实战例子：花叔的 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，直接： 1. /shelf/sync 拿全书架 2. 按 readUpdateTime 倒序取 top 5 3. 用最新那本调 /book/getprogress 拿章节/进度/累计时长 4. 一句话回复「你正在读 X，已到第 N 章，进度 X%，累计读了 X 小时」，附 weread:// 链接 5. 顺带说一句最近一周在读的其他几本，看出主题倾向

共享子模块

• shared/knowledge-map.md：怎么读懂一个人的知识地图（三个数据源 × 三种交叉信号）
• shared/shelf-cross-notes.md：书架 + 笔记交叉分析的 Python 代码模板和主题关键词组

示例

• examples/advisor-neuroscience.md：花叔「神经科学如何更进一步」案例的完整复盘，含步骤、输出、为什么这样推

异常与边界条件

实操常遇异常。以下为全局通用 fallback，所有 workflow 共享。workflow 各自的特殊异常在各自文档末尾。

原则：异常先告知用户，再按规则处理；绝不静默跳过或静默失败；接口报错的具体含义看底层 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。不要凭印象做推荐，所有推荐必须有数据支撑。

Example：神经科学进阶推荐（advisor workflow）

这是 advisor workflow 的第一个完整 case，来自 2026-05-17 花叔的真实提问：

我如果想在理解神经科学，尤其是大脑如何运作这件事上更进一步的话，基于我已经读过的书，你觉得我最该去读哪些书？

本文档复盘 AI 是怎么一步步做完推荐的，以及关键的判断点。

---

Step 1 — 数据采集

并行调用：

/shelf/sync
/user/notebooks count=100

/shelf/sync 返回包很大（640KB），存到临时文件再 grep。

Step 2 — 在「神经科学」主题上做交叉

书架里相关的（按分类看）

笔记本里的（揭示「真读过的」）

关键发现 1：花叔在神经科学上的真实深度比书架显示的更深。Kandel 27 条笔记、Hawkins 19 条都是「隐藏深读」——书架里没分类但深度阅读了。如果只看书架做推荐，会以为他没读 Kandel，推一本他已经啃透的诺奖经典就尴尬了。

关键发现 2：花叔意识研究的拼图已经很完整：Crick 学派、Edelman 学派、Tononi（通过《意识的宇宙》接触）、Hawkins、Penrose 都覆盖了。

Step 3 — 识别拼图缺口

按 `shared/knowledge-map.md` 的「拼图缺口」框架问：

Step 4 — 候选书验证

每本调 /store/search：

萨波斯基那本作为重要补充提到，但明确告知用户未上架，不在主推里。

Step 5 — 分梯队

Step 6 — 输出（实际给花叔的回答节选）

看完你的书架和笔记，先说个观察：你在「意识研究」这条线上其实走得比一般科普读者深得多。
[列出已读脉络]

但有几块明显的拼图缺了，按「最该补」的顺序给你：

## 第一梯队：直接接你已有的脉络

**1. 迪昂《脑与意识》**
你读了 Dehaene 关于学习和阅读的两本，但他「意识三部曲」里最重磅的这本恰恰跳过了。
[2-3 句话讲为什么+收益]
weread://reading?bId=24240889

**2. 达马西奥《笛卡尔的错误：情绪、推理和大脑》**
你的意识研究阅读里有 Crick 学派、Edelman 学派、Tononi、Hawkins，唯独缺了达马西奥这一脉。
[2-3 句话]
weread://reading?bId=23691331

[第二、第三梯队略]

---

**如果时间有限只选一本：迪昂《脑与意识》**。因为它最贴你已有的阅读基础。

**如果想真正「再上一个台阶」**：达马西奥+安迪·克拉克这两本一起读，会让你换一个底层框架看大脑。

顺带提一句，萨波斯基《行为：暴力、竞争、利他》在微信读书没有上架，如果你想啃，得去找纸质或英文电子版。

这个 case 验证的几个原则

1. 必须查 notebooks 不能只看书架：Kandel 这本要不是看了 notebooks 笔记数，会被误推 2. 拼图缺口比覆盖完整更重要：花叔已经在意识研究覆盖度很高，但缺达马西奥学派和预测加工范式 3. 推荐必须分梯队：5 本一字排开 = 用户记不住哪本最该读 4. 必须给「如果只读一本」的建议：用户最终行动只会从一本开始 5. 不上架的书要明确告知：萨波斯基这本就老老实实说没上架，不为了凑数瞎推 6. 绝不推盗版资源：用户进一步问「帮我下载萨波斯基这本」，给的方案是斯坦福公开课 + Kindle + Audible + 国图电子借阅 + 微信读书有的同作者作品

二阶 follow-up：用户问「能帮我下载吗？」

后续花叔追问能不能帮下载未上架的萨波斯基《行为》。AI 的处理：

• 不推 Z-Library / LibGen / Anna's Archive 等盗版站
• 推荐萨波斯基本人的斯坦福公开课（25 讲在 YouTube 免费）作为最强免费替代——书的内容就是基于这门课
• 给合法获取路径：Kindle 英文版、Audible 英文有声书（作者本人朗读 26 小时）、中文版纸质书购买、国家图书馆数字资源
• 退路：微信读书里萨波斯基的另一本《动物本能》虽然不是 Behave，但风格议题一脉相承，可以先试水判断喜不喜欢这位作者

这个 follow-up 模式应该写入 advisor.md 的「常见陷阱」——遇到未上架请求，永远给合法替代，不推盗版。

这个 case 可以复用的判断模板

下次有人问「我想在 X 方向更进一步」，照搬这个 6 步流程：

1. shelf + notebooks 并行调 2. 在主题上做三向交叉（书架 / 笔记 / 最近活跃） 3. 列出 4 个维度的拼图缺口（学派 / 时间 / 抽象层次 / 邻近学科） 4. /store/search 验证上架 5. 分 2-3 梯队，每梯队 1-2 本 6. 给「如果只读一本」+「如果想真上台阶」两个建议

<div align="center">

huashu-weread

「不是查数据。是 AI 把你忘掉的那些时刻还给你。」

  

<br>

微信读书高阶顾问 · 在官方 weread skill 之上加一层「读书顾问的工作流」

<br>

微信读书前几天上了一个官方 AI skill（weread.qq.com/r/weread-skills），把书架、笔记、阅读统计、推荐 6 件事开放给 AI。能力很强，但它只是「自然语言包装的搜索接口」——你让它推荐书，它不会去看你已经读过什么，常把你笔记 68 条的书又当新书推回来给你。

本 skill 在官方 8 个 API 之上，加一层「读书顾问的工作流」。核心方法是「书架 + 笔记交叉分析」——书架揭示你「主动归类的兴趣」，笔记揭示你「真读过的书」。只看书架会漏信号，只看笔记会错过兴趣方向。

npx skills add alchaincyf/huashu-weread

跨 agent 通用——Claude Code、Cursor、Codex、OpenClaw、Hermes 都能装。

看效果对比 · 装上就能用 · 4 个 workflow · 核心方法

</div>

---

看效果对比

同样一个问题：「推荐下产品经理方向的书」。

裸 weread skill 答：14 本通识书单

按入门到进阶分了 6 个梯队，推《俞军产品方法论》《幕后产品》《硅谷增长黑客实战笔记》……都是好书，但：

• 《俞军产品方法论》我做了 68 条笔记
• 《幕后产品》在我书架上躺着两年
• 《硅谷增长黑客》我做了 34 条笔记

它根本没看我的笔记和书架，只是一个用自然语言包装的搜索接口。把读过的书又当新书推回来。

huashu-weread 答：5 本针对你的拼图建议

最后还给「如果只读一本：X」和「如果想真正再上一个台阶：Y+Z」两个明确建议。

差距：裸 weread 给的是「合格的通识书单」，huashu-weread 给的是「针对你这个人的拼图建议」。

---

装上就能用

前置依赖：必须先装官方 weread skill（weread.qq.com/r/weread-skills），按页面指引走两步配置（复制安装指令 + 登录拿 API Key），全程不超过 1 分钟。

装完官方后，再装本 skill：

npx skills add alchaincyf/huashu-weread

跑起来：

"推荐下一本读啥"               → 自动走 advisor
"想系统搞懂行为经济学"          → 自动走 path
"整理下我在《掌控习惯》里的笔记"  → 自动走 alchemy
"写一篇我今年的读书复盘"        → 自动走 review
"我现在在读哪本"               → 轻量直答，一句话给进度

模糊的需求也认：「不知道读啥」「有相关的书吗」「这本书我记住了啥」「我今年读了什么」都能正确路由。

---

4 个 workflow

每个 workflow 都有独立的方法论文档，详见 `workflows/`：

• `workflows/advisor.md` — 读书顾问标准流程
• `workflows/path.md` — 入门到前沿的阶梯规划
• `workflows/alchemy.md` — 笔记提炼标准流程
• `workflows/review.md` — 读书复盘文章生成

---

核心方法：书架 + 笔记交叉

整套 skill 的方法论建立在三个数据源 × 三种交叉信号上。

三个数据源

三种交叉信号

信号 1：真读 vs 放着

信号 2：深度 vs 广度——按笔记条数分层（≥20 重度，10-20 中度，3-10 轻度，1-3 翻过）

信号 3：最近 vs 历史——用 readUpdateTime 看最近 30 天活跃书目（用户当前兴趣常和书架分类不一致）

完整方法论见 `shared/knowledge-map.md`。

---

vs 官方 weread skill

不是替代关系——huashu-weread 在官方 8 个 API 之上加了一层 prompt 工程层。装上后官方 skill 还在底层跑，两个不冲突。

---

异常与边界

实操中常遇到的问题，全部有 fallback，绝不静默失败。详见 `SKILL.md` 的「异常与边界条件」段。

• WEREAD_API_KEY 未设置 → 报错并告知怎么获取
• API 返回 errcode != 0 → 重试 1 次，仍失败告知用户
• 出现 upgrade_info → 暂停操作，按指引升级版本
• notebooks 完全空（新用户）→ 退化到仅用书架推断，但明确告知准度会差
• 书架完全空 → 不走 advisor，建议先读几本或切 path workflow
• 用户主题模糊（如「想读点 AI 相关」）→ 在检查点先确认细分方向

所有数据展示遵守强制规范：Unix 时间戳转 YYYY-MM-DD，阅读时长秒转「X 小时 Y 分钟」，bookId 永远附 weread:// 深度链接，绝不裸数字。

---

给 skill 开发者：本仓库的设计原则

如果你想做类似的「在原子 API 之上加一层工作流」的 skill，可以参考几个点：

1. 检查点设计：在「分叉影响输出本质」的地方插入用户确认 gate，但日常小决策 AI 自己定，不打扰用户 2. 方法论先行：所有 workflow 共享同一套核心方法论（书架+笔记交叉），workflow 只是不同场景的应用 3. 数据展示规范强制化：时间戳、单位、深度链接的展示规则写进 SKILL.md 强制约束 4. 异常的 fallback 全部明示：每种异常都有处理动作，不留「静默失败」的空间

---

License

MIT — 个人 + 商业用途均可，无需授权。

---

致谢

• 微信读书官方 skill 把最难的事做完了（把账号数据通过 API 暴露给 AI）：weread.qq.com/r/weread-skills
• 灵感来源：花叔的 女娲 .skill（把人物方法论蒸馏成 skill）。这次只是把蒸馏对象从「人」换成了「我自己的微信读书账号」。

---

<div align="center">

Made by @AlchainHust · 公众号「花叔」

</div>

怎么读懂一个人的知识地图

所有 workflow 共享的核心方法论。做推荐前必读。

三个数据源

三种交叉信号

信号 1：真读 vs 放着

信号 2：深度 vs 广度

按笔记条数分层：

信号 3：最近 vs 历史

用 readUpdateTime 看最近 30 天 / 7 天的活跃书目。

用户当前兴趣方向经常和书架分类不一致。比如花叔书架上「心理学」分类只有 6 本，但最近一周 8 本都是悬疑推理——他当前的兴趣是悬疑推理，不是心理学。

用户没指定主题方向时（如「推荐几本书读读」「下一本读啥」）：最近活跃优先，推延展。

用户明确指定主题时（如「推荐 AI 产品设计的书」「我想读神经科学方向」）：主题压倒最近活跃。哪怕用户最近全在读悬疑小说，他主动问 AI 产品设计就是要看 AI 产品设计，advisor 不要把悬疑当线索。把最近活跃当作「次要观察」放进开场陈述（「我看你最近在密集读悬疑，但你这次问 AI 产品设计，那就按主题来」），不要让它干扰推荐方向。

给推荐的硬性原则

1. 不推用户已读的书（在 notebooks 里有笔记 ≥ 3 条的） 2. 「已加书架但没动的书」分两种情况：

• 用户没主动问相关主题时：不推（说明不是真兴趣，推了等于二次堆压）
• 用户主动问相关主题时：可以作为「翻旧账」推（「这本你之前加了一直没读，正好趁这次读完」），明确告知是已加未动的——这是常见且高质量的场景，强行排除会损失好候选

3. 优先推用户笔记多的领域里的「拼图缺口」（缺什么学派、缺什么视角） 4. 如果用户没指定主题，最近活跃方向优先；用户指定了主题，主题优先（详见信号 3） 5. 承认推荐有上下文（说清楚是基于他读了什么书做的推断）

「拼图缺口」怎么找

针对某个主题，先盘点用户已读的书属于哪些学派/视角/层次。然后看：

• 缺哪个核心学派？（例如神经科学缺达马西奥学派）
• 缺哪个时间层次？（例如有 80 年代经典但缺 2020 年后前沿）
• 缺哪个抽象层次？（例如有理论但缺案例，或反过来）
• 缺哪个相邻学科？（例如读了心理学缺生物学基础）

这是 AI 顾问 vs 算法推荐的差异。算法只会推「读过这本的人也读了」，AI 顾问要做「看你的知识地图缺哪一块」。

输出推荐时的对应展示

每本推荐书都要交代清楚：

• 为什么是这本：基于哪本已读做的判断
• 期待的认知收益：读完会改变你什么观点 / 补什么缺口
• 是否上架：用 /store/search 验证后明确说
• 链接：上架就附 weread://reading?bId={bookId}，不上架就给合法替代路径

书架 + 笔记交叉分析（实用脚本）

把 /shelf/sync 和 /user/notebooks 两份数据合并后做筛选的代码模板。

完整模板

import json, subprocess, datetime, os

API_KEY = os.environ["WEREAD_API_KEY"]
GATEWAY = "https://i.weread.qq.com/api/agent/gateway"

# VERSION 的权威来源是 ~/.claude/skills/weread/SKILL.md 顶部 frontmatter 的 version 字段。
# 这里的字面值可能滞后于真实最新值——执行前应该 grep 一下 weread/SKILL.md 确认。
# 别从用户 prompt 里抄版本号（A/B 测试发现 prompt 里的 version 经常是过时的）。
import re, pathlib
def _read_version():
    try:
        text = pathlib.Path(os.path.expanduser("~/.claude/skills/weread/SKILL.md")).read_text()
        m = re.search(r"^version:\s*([\d.]+)", text, re.M)
        if m: return m.group(1)
    except Exception:
        pass
    return "1.0.3"  # fallback，不一定最新
VERSION = _read_version()

def call(api_name, **params):
    body = {"api_name": api_name, "skill_version": VERSION, **params}
    r = subprocess.run(
        ["curl", "-s", "-X", "POST", GATEWAY,
         "-H", f"Authorization: Bearer {API_KEY}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(body)],
        capture_output=True, text=True
    )
    return json.loads(r.stdout)

# 拿两份数据
shelf = call("/shelf/sync")
notebooks = call("/user/notebooks", count=200)

# 建索引
shelf_books = {str(b["bookId"]): b for b in shelf.get("books", [])}
notebook_map = {str(b["book"]["bookId"]): b for b in notebooks.get("books", [])}

# 四种集合
read_deep = []         # 笔记 >= 10：吃透了
read_medium = []       # 笔记 3-10：认真读了
read_light = []        # 笔记 1-3：翻了一下
shelved_unread = []    # 书架有但 notebook 无：放着没动

for bid, book in shelf_books.items():
    nb = notebook_map.get(bid)
    note_count = nb.get("noteCount", 0) if nb else 0
    if note_count >= 10:
        read_deep.append((book, nb))
    elif note_count >= 3:
        read_medium.append((book, nb))
    elif note_count > 0:
        read_light.append((book, nb))
    else:
        shelved_unread.append(book)

# 隐藏深读：notebook 有但 shelf 没有（借阅/试读但深读）
hidden_deep = [
    nb for bid, nb in notebook_map.items()
    if bid not in shelf_books and nb.get("noteCount", 0) >= 10
]

# 最近活跃书（按 readUpdateTime 倒序）
recent = sorted(
    [b for b in shelf.get("books", []) if b.get("readUpdateTime", 0) > 0],
    key=lambda b: b["readUpdateTime"], reverse=True
)[:10]

按主题筛选

调用 filter_by_topic(books, keywords)：

def filter_by_topic(books, keywords):
    """books 是 (book, notebook) 元组列表或 book 列表"""
    result = []
    for item in books:
        b = item[0] if isinstance(item, tuple) else item
        title = b.get("title", "")
        if any(k in title for k in keywords):
            result.append(item)
    return result

常用主题关键词组

照搬即可。需要扩充时优先加中文同义词。

TOPIC_KEYWORDS = {
    "神经科学": ["脑", "意识", "神经", "心智", "认知", "记忆", "思维", "情绪"],
    "投资": ["投资", "估值", "价值", "巴菲特", "芒格", "段永平", "证券", "股票", "财务"],
    "心理学": ["心理", "行为", "情绪", "动机", "性格", "认知"],
    "哲学": ["哲学", "存在", "形而上", "伦理", "尼采", "海德格尔", "维特根斯坦"],
    "经济学": ["经济", "市场", "货币", "通胀", "凯恩斯", "哈耶克", "弗里德曼"],
    "AI": ["AI", "人工智能", "机器学习", "深度学习", "大模型", "智能"],
    "创业": ["创业", "增长", "产品", "MVP", "PMF", "0到1"],
    "历史": ["历史", "通史", "断代", "近代", "古代", "战争"],
    "文学": ["小说", "诗", "散文", "短篇", "长篇"],
    "推理": ["推理", "悬疑", "凶杀", "侦探", "罪案", "黑色"],
    "佛学": ["佛", "禅", "冥想", "正念", "般若", "金刚经"],
    "科普": ["科学", "宇宙", "物理", "生物", "化学", "数学"],
}

输出已读书目（带笔记深度标签）

def render_books_in_topic(topic, books_with_notes):
    print(f"### {topic}已读 ({len(books_with_notes)} 本)\n")
    for book, nb in sorted(books_with_notes, key=lambda x: -(x[1].get("noteCount",0) if x[1] else 0)):
        title = book.get("title", "?")
        author = book.get("author", "?")
        note_count = nb.get("noteCount", 0) if nb else 0
        depth = "深读" if note_count >= 10 else "精读片段" if note_count >= 3 else "略读"
        print(f"- 「{title}」{author} ({depth}, {note_count}笔记)")

数据展示规范

调任何接口处理时间戳字段（readUpdateTime / updateTime / finishTime / createTime）时一律转 YYYY-MM-DD：

def fmt_ts(ts):
    if not ts:
        return ""
    return datetime.datetime.fromtimestamp(ts).strftime("%Y-%m-%d")

阅读时长字段单位是秒，展示时转成「X 小时 Y 分钟」：

def fmt_duration(seconds):
    h = seconds // 3600
    m = (seconds % 3600) // 60
    return f"{h}小时{m}分钟" if h else f"{m}分钟"

Workflow：读书顾问（advisor）

何时走这个 workflow

用户给一个方向 / 兴趣 / 已读的书，问「下一步该读什么」。典型话术：

• 「我想在 X 方向更进一步，该读什么？」
• 「不知道下一本读啥」
• 「基于我已经读过的，推荐几本」
• 「我对 Y 感兴趣，有什么相关的好书？」

和 path.md 的区别：advisor 假设用户已经有基础，做延展推荐；path 假设用户从零或低基础开始系统学习。判断方法：先调 /user/notebooks 看用户在该方向是否有 ≥ 3 本笔记多的书，有就走 advisor，没有就走 path。

标准步骤

Step 1 — 拿用户数据

/shelf/sync                # 全书架（含分类 archive 和书目 books）
/user/notebooks count=200  # 笔记本概览

两个并行调用。建议把 /shelf/sync 输出存文件再 grep，因为返回包很大。

Step 2 — 在目标主题上做交叉分析

照 `shared/shelf-cross-notes.md` 的代码模板：

1. 按主题关键词组过滤书架和 notebooks 2. 区分「真读了」「放着没动」「隐藏深读」三类 3. 按笔记条数排序「真读了」的那组

特别注意：先查 notebooks 再查 shelf。notebooks 里出现但不在书架的，往往是用户最深入读的书（借阅 / 试读），这是最强的兴趣信号。

Step 3 — 识别「知识地图缺口」

按 `shared/knowledge-map.md` 的「拼图缺口」框架问自己：

• 这个主题下有哪几个核心学派 / 视角？用户读了哪些，缺哪些？
• 时间维度上，用户的阅读集中在哪个年代 / 范式？缺哪个？
• 抽象层次上，用户有理论还是案例多？缺哪种？
• 邻近学科上，用户的阅读够不够支撑这个主题？

把缺口列出来（脑内列），每个缺口对应 1-2 本经典或前沿。

Step 3.5 — 检查点：和用户对齐推荐范围

如果用户原始 prompt 没明说，先问而不是自己默认：

我看你在 [主题] 已读过 N 本（其中 M 本笔记 ≥ 5），主要集中在 [学派/视角]。我打算给你推 [3-5 本] 补 [拼图缺口]，含未上架的会单独说明。

>

想调整推荐范围吗？比如：

- 只推 3 本（更聚焦）/ 推 8 本（更广）

- 只要微信读书上架的 / 也可以含纸质或英文版

- 限定字数 / 限定中文版

用户回答后再进 Step 4。

如果原始 prompt 已经说了「推 3 本上架的就行」，跳过这个检查点。

无人值守模式 fallback：如果检测到当前调用没有交互通道（例如被 huashu-agent-swarm 等自动化流水线调用、没有可对话的用户），不要卡在检查点等回复，直接走默认值并继续：

走默认值时必须在输出里明确写一行：「（无人值守模式，按默认参数推荐：5 本含未上架。如果你想调整，告诉我重新推。）」

Step 4 — 验证推荐书是否在微信读书上架

对每本候选书：

/store/search keyword="书名" count=3

• 找到 electronic books 里有的 → 记下 bookId，准备附 weread:// 链接
• 只有「待上架」或完全没有 → 不上架，准备给合法替代路径

Step 5 — 排序，分梯队

把验证过的推荐分成 2-3 个梯队：

不要一次推超过 6 本——用户消化不动，反而稀释了「这本最该读」的信号。

Step 6 — 输出

按下面的模板写。最后给两个明确建议：

• 如果只读一本：X（理由）
• 如果想真正上台阶：Y + Z（理由）

输出模板

看完你的书架和笔记，先说个观察：[一两句话点明用户在该方向已读的脉络和深度]。

但有几块明显的拼图缺了，按「最该补」的顺序给你：

## 第一梯队：[这个梯队的名字]

**1. 《书名》作者**
[2-4 句话讲：为什么是这本 + 它怎么接你已读 + 期待的认知收益]
weread://reading?bId=XXXXXXX

**2. 《书名》作者**
[同上]
weread://reading?bId=XXXXXXX

## 第二梯队：[这个梯队的名字]

**3. ...**

## 第三梯队：[换个角度]

**5. ...**

---

**如果只读一本：[书名]**。[一句话理由]

**如果想真正「再上一个台阶」**：[书 A + 书 B] 一起读，会让你 [认知收益]。

[如果有重要的书没上架，最后单独说明，给合法替代路径]

输出风格守则

• 永远先讲「我看到了什么」（观察），再讲「我建议什么」
• 每本书都说清楚「为什么是这本」，不要堆书单
• 推荐量控制在 3-5 本，最多 6 本
• 文风：不用破折号、不堆砌、用「」、人味重（参见 ~/.claude/CLAUDE.md 写作风格）
• 永远附 weread:// 深度链接
• 不上架的书要明确说，并给合法替代路径，绝不推盗版

范例

完整的实战范例见 `examples/advisor-neuroscience.md`。

advisor 特有的异常

全局异常见 SKILL.md「异常与边界条件」段。下面是 advisor 独有的：

常见陷阱

Workflow：笔记炼金术（alchemy）

何时走这个 workflow

用户已经读完一本书或一个主题的几本书，希望把零散的划线和想法结构化成可用的输出。典型话术：

• 「整理一下我在《XX》的笔记」
• 「这本书我到底记住了啥」
• 「把我关于 X 主题的所有划线理一下」
• 「读完这本书三个月了，我想做个总结」
• 「把笔记变成一篇读书笔记」

两种模式

模式 A：单书模式

Step 1 — 定位书

如果用户给了书名，先 /store/search 或 /user/notebooks 拿 bookId。

Step 2 — 拉全部划线和想法

/book/bookmarklist bookId=XXX     # 所有划线
/review/list/mine bookId=XXX      # 用户在这本书的所有想法/笔记
/book/chapterinfo bookId=XXX      # 章节目录（用于把笔记按章节归位）

Step 3 — 按章节归位

把划线和想法按 chapterUid 聚合到对应章节。每章下面：

• 该章的所有划线（按 range 排序）
• 该章的所有用户想法
• 该章的核心议题（如果章节标题已经表达，跳过；否则 AI 用 1 句话提炼）

Step 4 — 提炼核心论点

读完所有划线后，输出：

1. 这本书的 3-5 个核心论点（用户反复划线/想法集中的地方） 2. 3-5 句金句（划线频次或情感强度高的） 3. 用户自己想法 vs 原文的关系：用户在哪几处和作者对话、补充、反驳？ 4. 这本书改变了用户什么（推测）：从想法的语气和议题判断

Step 5 — 生成读书笔记

输出一篇 800-1500 字的读书笔记，结构：

# 《书名》—— 我读到了什么

[3-5 句话讲这本书的总体印象和读完最大的收获]

## 一、[核心论点 1 的名字]

[100-200 字阐述，引用 1-2 条划线作为佐证]

## 二、[核心论点 2 的名字]

[同上]

## 三、[核心论点 3 的名字]

[同上]

## 我和作者的对话

[100-200 字：把用户自己的想法和原文的关系讲清楚]

## 三句金句

> [金句 1]
> [金句 2]
> [金句 3]

[每条附 weread://bestbookmark 跳转链接，让用户点进去复习]

## 这本书我可能会改变什么

[100-200 字：基于用户笔记的语气，推测这本书带来的认知或行动改变]

模式 B：跨主题模式

Step 1 — 主题书目筛选

用户给主题词（比如「神经科学」「投资」），按 `shared/shelf-cross-notes.md` 里的关键词组过滤 notebooks，得到主题相关的所有书。

Step 2 — 拉每本书的划线和想法

并行调 /book/bookmarklist 和 /review/list/mine，聚合到一个大池子。

Step 2.5 — 检查点：大体量提炼前先汇总征求方向

跨主题模式经常聚出大数据。先给用户一个粗汇总，让他选要重点提炼的子集，避免一上来就生成几千字主题报告但方向不对。

汇总格式：

主题「[X]」下你读过 N 本，共 M 条划线、K 条想法。粗看议题分布：

- 议题 A（约 K 条）：来自《书 a》《书 b》《书 c》

- 议题 B（约 K 条）：来自《书 d》《书 e》

- 议题 C（约 K 条）：来自《书 f》

- 议题 D（约 K 条）：来自《书 g》

...

>

你想我重点提炼哪些议题？还是全部一起聚？预估输出长度：全聚约 [X] 字、选 2-3 个议题约 [Y] 字。

议题分布的初步判断由 AI 基于划线文本快速做，不用精确——目的是让用户看到 landscape 后选方向。

单书模式不需要这个检查点（数据量天然受限于一本书）。

Step 3 — 跨书聚类

按议题（不是按书）重新聚类。比如「神经科学」主题下，可能聚出：

• 关于「意识是什么」的所有划线（横跨 5 本书）
• 关于「记忆机制」的所有划线（横跨 3 本书）
• 关于「自由意志」的所有划线（横跨 4 本书）

聚类标准是议题，不是书的章节。AI 要做判断：每条划线主要讨论什么议题。

Step 4 — 生成主题报告

# 我在「[主题]」上学到了什么

读过 N 本相关书，做了 M 条笔记。把所有划线按议题重新聚类后，下面是我自己的认知地图。

## 议题一：[议题名字]

[100-300 字阐述这个议题。引用 2-3 条划线，每条标注出处书名]

> "划线 1" —— 《书名 A》[weread:// 链接]
> "划线 2" —— 《书名 B》[weread:// 链接]

## 议题二：...

...

## 还没回答的问题

[根据笔记里的留白和未解决处，列 3-5 个用户还想深入的问题]

alchemy 特有的异常

全局异常见 SKILL.md「异常与边界条件」段。下面是 alchemy 独有的：

不要做的事

• 不要直接复述原文超过 50 字的连续段落（避免变成抄书）
• 不要把所有划线全列出来（笔记炼金 ≠ 笔记导出，要做提炼）
• 不要写「读完这本书让我感悟到了真理」这种空话——只写从笔记里能直接看到的认知
• 不要替用户编造他没写过的想法

输出风格守则

• 输出是给用户自己看的，可以用第一人称（「我读到了什么」）
• 也可以是给别人看的（公众号 / 星球分享），那就第三人称
• 默认是给用户自己看的；如果用户说「我要发出去」，切换语气
• 引用划线时永远附 weread://bestbookmark 链接，方便用户回去看上下文

链接拼接

划线类 weread:// 链接格式（详见底层 weread skill 的 SKILL.md「深度链接（URL Schema）」）：

weread://bestbookmark?bookId=XXX&chapterUid=YYY&rangeStart=AAA&rangeEnd=BBB

rangeStart 和 rangeEnd 从划线的 range 字段拆分（格式 "AAA-BBB"）。

Workflow：主题阅读路径（path）

何时走这个 workflow

用户想系统进入一个新领域，希望有阶梯式的书单规划。典型话术：

• 「我想搞懂 X 这个领域」
• 「从零系统学一下 Y」
• 「给我规划一个入门 Z 的阅读路线」
• 「这个方向我应该按什么顺序读」

和 advisor.md 的区别：advisor 是「在已有基础上延展」，path 是「从零或低基础规划阶梯」。

判断方法：先调 /user/notebooks + 按主题筛选。如果用户在这个主题上：

• 没有任何笔记 → 走 path
• 有 1-2 本笔记少的 → 走 path（用户算入门级）
• 有 3+ 本笔记 ≥ 5 的 → 跳走 advisor

标准步骤

Step 1 — 拿数据，判断起点

/shelf/sync
/user/notebooks count=200

按主题关键词过滤，判断用户当前基础在哪个段位：

中级和高级应该跳 advisor。

Step 1.5 — 检查点：和用户确认起点判断

段位判断是 path 路径规划的地基，错了整条路径都偏。把判断给用户看：

我看你在「[主题]」主题已读 N 本（笔记 ≥ 5 的 M 本），我判定你是 [零基础/入门级/中级]，准备从 [入门/进阶] 阶梯开始规划。

>

这判断准吗？如果你觉得自己段位更高（比如读过其他没在书架/笔记里的书），告诉我我会调整；如果你想刻意从更基础的开始读，也告诉我。

用户确认后再进 Step 2。

如果用户在中级或高级，告诉用户「这种段位我建议跳走 advisor workflow（基于你已读做延展），要切吗？」由用户决定继续 path 还是切走。

Step 2 — 规划 3 阶梯

每阶梯 2-3 本，总数控制在 6-8 本以内：

每阶梯里如果有用户已读的书，标注「你已读」并跳过，但仍要列出来让用户知道这本在路径里的位置。

Step 3 — 验证上架 + 阅读时长估算

每本调 /store/search 验证 + 用 /book/info 拿 totalWords 估算时长（按每分钟 300 字算）。给用户一个总投入感：

这条路径 6 本书，总字数约 X 万字，按每天 1 小时算大概 N 个月读完。

Step 4 — 在路径里穿插「检查点」

每阶梯结束建议用户问自己一个问题，确认是否真的掌握了：

• 入门后：能用一句话给朋友解释这个领域在研究什么吗？
• 进阶后：能说出这个领域里 2-3 个主要学派的差异吗？
• 前沿后：能列出 2-3 个当下最有争议的问题吗？

这些问题是费曼式的检验，比「读完了」更重要。

Step 5 — 输出

按下面模板输出。除了书单本身，要给用户一个「停下来不再读也 OK」的退出点（避免完美主义拖累）。

输出模板

针对 [主题]，从你目前的起点（[说明用户基础]）出发，我建议这条路径：

## 入门：建立基础认知（[预计时长]）

**1. 《书名》作者**
[1-2 句：这本是什么、为什么放入门]
weread://reading?bId=XXX

**2. 《书名》作者**
[同上]

**👉 入门检查点**：[一个费曼式的自检问题]

## 进阶：搭框架（[预计时长]）

**3. ...**

**👉 进阶检查点**：...

## 前沿：看到边界（[预计时长]）

**5. ...**

**👉 前沿检查点**：...

---

**整条路径预计 [N] 个月**（按每天 [X] 小时算）。

**如果时间有限，建议这个最小版本**：
[书 A] → [书 B]。两本读完，你对这个领域的认知就会从「外行」变成「能听懂行内对话」。

**如果想真正进入这个领域**：
完整走完三阶梯，并在每阶梯结束做检查点自问。

[最后给一个「读不下去也没关系」的退出建议，比如「如果读到第二本发现不感兴趣，就停，比强撑读完更明智」]

输出风格守则

• 给路径不是给清单——要让用户感到「按顺序读」的逻辑
• 时长估算要给具体数字（X 小时 / N 个月），别说「不会太久」
• 检查点用费曼式提问（能不能给别人解释清楚），不用考试式
• 永远给「最小版本」退出点
• 不堆砌、不破折号、用「」

path 特有的异常

全局异常见 SKILL.md「异常与边界条件」段。下面是 path 独有的：

常见陷阱

Workflow：年度/周期阅读复盘（review）

何时走这个 workflow

用户想做一段时间的阅读盘点，输出一篇可发朋友圈 / 公众号 / 小红书的复盘文章。典型话术：

• 「我今年读了什么」
• 「年度阅读复盘」
• 「上半年读了哪些书」
• 「写一篇我的 2025 读书总结」

周期选择

标准步骤

Step 1 — 拿四份核心数据

/readdata/detail period=year   # 阅读时长、天数、排行、偏好分析
/shelf/sync                    # 全书架（含 finishTime、readUpdateTime）
/user/notebooks count=200      # 笔记本概览
/book/getprogress bookId=XXX   # 对每本"在读但未完"的书拿进度（可选）

Step 2 — 按周期过滤

从 shelf 的 books 列表里筛选 readUpdateTime 在周期内的书。按以下维度归类：

Step 3 — 跨数据源验证「真读了」

对每本归类到「完成」或「在读」的书，去 notebooks 里查笔记数：

• 笔记 ≥ 5 → 真读了，写进复盘
• 笔记 0-5 → 翻完但没沉淀，写进复盘但归为「轻读」
• 用 readUpdateTime 总时长加权排序，找出「投入最多时间的 5 本」

Step 4 — 算出几个洞察

复盘文章的「金句」往往来自数字反差。常用洞察：

挑 3-5 个有反差感的洞察写进复盘。

Step 4.5 — 检查点：确认平台和语气

复盘文章发哪里、写多长，语气和结构差异很大。写前必须确认平台，否则白写一稿。

如果用户原始 prompt 已经说了平台（「写一篇公众号复盘」），跳过检查点直接按对应模板写。

如果没说，必须先问：

这次复盘想发哪里？我会按对应平台的篇幅和语气来写：

- 朋友圈短文（200-500 字）

- 公众号长文（1500-3000 字）

- 小红书图文（300-800 字 + 配图建议）

- 视频脚本（800-1500 字口语稿）

- 个人留存（不限）

用户回答后再进 Step 5。

Step 5 — 生成复盘文章

复盘文章不是「书单 + 一两句话」，而是一篇能让没读过这些书的人也看得下去的文章。结构建议：

# 我的 [周期] 阅读：[一句话概括最大的发现]

[200-300 字开场：今年读了多少、花了多长时间、最大的意外是什么]

## 数字盘点

- 完整读完：[N] 本
- 正在读：[M] 本
- 累计阅读时长：[X] 小时
- 最常读的主题：[主题]
- 阅读最集中的月份：[月份]

## 一、最值得讲的三本

[每本一段，300-500 字。讲：为什么是它、读完改变了什么、谁该读]
[附 weread:// 链接]

## 二、一个意外的转向

[200-400 字：今年某个时间点用户的阅读主题突然变化的故事。从数据出发，从「为什么这个时间点开始读 X 主题」展开]

## 三、还没读完的那本

[100-200 字：写一本「读了一半放下的」，思考为什么放下、要不要捡起来]

## 给明年的自己

[100-200 字：基于今年的阅读模式，给明年提一个具体的阅读目标。不要大而空]

Step 6 — 配合花叔风格调用

如果用户要发公众号 / 小红书，走对应的写作 skill：

• 公众号 → 调用 huashu-perspective 写作风格 + huashu-publish 发布
• 小红书 → 调用 huashu-xhs-image 配图
• 视频脚本 → 调用 huashu-video-outline 出大纲

复盘 workflow 只生成 md 草稿，不直接发布。

输出风格守则

• 数字反差是核心：复盘文章的传播力来自具体数字
• 每本书都要说「为什么是它」，不要堆书名
• 至少要有一个「我自己也没想到」的洞察
• 不要全是夸奖的话——要有「这本读了发现不行」「这本放下了」之类的真实
• 文风走花叔标准（不堆砌、不破折号、人味重）

review 特有的异常

全局异常见 SKILL.md「异常与边界条件」段。下面是 review 独有的：

常见陷阱