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. 本棚とノートは別々のデータソースなので、必ず照合する

データソース	インターフェース	明らかになること
本棚	/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 で、分岐によって出力の本質が変わる箇所にユーザー確認のゲートを設け、AI が既定値によって意図と異なる結果を出さないようにします。

• おすすめする冊数の分岐：advisor が3冊すすめる場合と8冊すすめる場合では体験がまったく異なるため、5冊を既定値にせず、先に確認します
• プラットフォームに応じた語調の分岐：振り返り記事を朋友圈／公众号／小红书／動画台本のどれにするかで語調が大きく変わるため、執筆前に必ず確認します
• レベル判断の分岐：path workflow で「入門レベルだと思います」という判断をユーザーに提示し、確認または訂正してもらいます
• データ量の分岐：alchemy のテーマ横断モードでハイライトが50件以上見つかった場合、すべてをまとめるのではなく、まず話題を要約してユーザーに対象を選んでもらいます
• 取り扱いがない本の分岐：おすすめに、微信読書で取り扱いのない本を含めるか確認します（ユーザーはすぐに開いて読める本だけを求めている可能性があります）

確認ポイントは「毎回質問する」という意味ではありません。どの本を最優先にするか、どの動詞を使うかといった日常的な小さな判断は AI が行い、ユーザーの手を煩わせないでください。ルールは、選択肢によって出力の本質が変わるときだけ質問することです。

ユーザーの元の prompt ですでに明確に指定されている場合（「取り扱いのある本を3冊すすめて。公众号向けに」など）は、該当する確認ポイントをすべて省略します。

サブコマンドの振り分け

ユーザーの発言	使用する workflow
本をすすめて／次は何を読めばいい？／何を読めばいいかわからない／X 分野の本が読みたい	advisor.md
X という分野を理解したい／X を体系的に学びたい／X をゼロから学びたい	path.md
自分のノートを整理したい／この本から何を覚えた？／このテーマのハイライトをまとめて	alchemy.md
今年は何を読んだ？／四半期の振り返り／年間の振り返り／振り返り記事を書いて	review.md
今は何を読んでいる？／最近は何を読んでいる？	軽量な直接回答（以下を参照）

軽量な直接回答：「今は何を読んでいる？」

workflow を使わず、次の手順を直接実行します。

1. /shelf/sync で本棚全体を取得します
2. readUpdateTime の降順で上位5冊を取得します
3. 最新の本について /book/getprogress を呼び出し、章／進捗／累計時間を取得します
4. 「X を読んでいます。第 N 章まで進んでいて、進捗は X％、累計で X 時間読んでいます」と一文で回答し、weread:// リンクを付けます
5. あわせて、直近1週間に読んでいるほかの本を挙げ、興味の傾向がわかるようにします

共有サブモジュール

• 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。不要凭印象做推荐，所有推荐必须有数据支撑。

版本自检（静默）

本节给 AI agent：每次使用本 skill 前，先做一个不联网的判断——读本 skill 目录（SKILL.md 所在目录）下的 .last-update-check 文件（内容为一行日期 YYYY-MM-DD）。文件存在且距今不足 30 天，跳过本节直接干活，不向用户提任何更新相关的话。

到期或文件不存在时，且仅在此时：

1. 本目录不是 git 克隆（无 .git 或无 origin）→ 写入今天日期后跳过本节
2. 对比版本：git -C <本目录> rev-parse HEAD 与 git -C <本目录> ls-remote origin HEAD
3. 无论结果如何，把今天日期写入 .last-update-check
4. 两者一致 → 什么都不说；确认落后 → 先完成用户当前任务，结束后附一句「本 skill 有新版本，可用 git -C <本目录> pull --ff-only 更新」。是否更新由用户决定，不要主动执行更新