shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析需要 API Key

微信读书热评

懒人技能。针对某句划线想法或某本书的公开书评，按「综合评分标准」（语义贴合 + 点赞热度）采集并排序出 TopN…。提示词：给我「书名 + 一句书中划线原句」、给我「书名」即可。

person作者: user_752cff44hubcommunity
download下载资源包

微信读书热评采集（weread-hot-comments）

一句话：给本书名（或书名+一句原话），帮你把微信读书上最值得看的热门评论按综合评分挑出来，生成一份可读 HTML。

用户只要结果（TopN 评论内容），不要把分析过程、评分公式细节塞进结果页正文。结果页 foot 可放一行方法说明。

⚠️ 加载即检查：API Key（agent 每次调用本技能的第一动作）

本技能必须有微信读书 API Key 才能拉数据。加载本技能后，立即用 Bash 检测环境变量是否非空（仅判空，绝不打印 Key 内容）：

if [ -n "$WEREAD_API_KEY" ]; then echo SET; else echo UNSET; fi
  • 若输出 UNSET：
    1. 不要运行任何采集脚本；
    2. 向用户输出「配置 Key 引导」（见下「第一次使用？三步跑通」的第一、二步），说明格式、来源、设置命令，并提醒勿在对话明文发送 Key；
    3. 等用户确认已设置后，再按所选场景执行。
  • 若输出 SET：直接进入「执行流程」按用户所选场景运行。

这是前置闸门，不是运行时兜底。目的是让用户在新装/首次调用时就被友好提醒，而不是跑到一半撞报错。

🔒 Key 安全约定（维护者必读）

  • 唯一来源：脚本仅在运行时从环境变量 WEREAD_API_KEY 读取 Key（scripts/collect_hot_comments.py 取 os.environ["WEREAD_API_KEY"]），绝不把 Key 写入源码、配置或任何数据文件。
  • 切勿硬编码：任何维护者都不要把 Key 写死进 .py/.md/模板，也不要新增"读本地配置文件取 Key"的逻辑——这会让打包/分享技能时泄露凭证。
  • 打包不携 Key：正因为 Key 只在环境变量里，所以打包/分发本技能目录 不会 带上你的 wrk-xxxx。使用者需自行配置环境变量。
  • 轮换建议：若 Key 曾在对话/日志中以明文出现，建议到微信读书侧重置该 Key。

第一次使用？三步跑通

第一步：拿到 Key

  • Key 来自 weread-skills 技能，格式 wrk-xxxxxxxx。如果你还没有，先按 weread-skills 技能说明获取。
  • 重要：Key 是敏感凭证，不要在对话里直接发给我，通过环境变量交给我（见第二步）。

第二步：配置 API Key（让 agent 能读到）

⚠️ 关键认知：我的执行环境是独立 shell，你在本机终端临时 export 的变量我读不到。必须配成「系统/用户级环境变量」让跨进程继承，或改用内联方式交给我。

方式一（推荐，持久且不进对话） —— Windows PowerShell：

[Environment]::SetEnvironmentVariable("WEREAD_API_KEY", "wrk-xxxxxxxx", "User")
  • 写入后重开 WorkBuddy 会话，让新进程继承该变量。
  • 验证：让我跑 if [ -n "$WEREAD_API_KEY" ]，返回 SET 即成功，可直接运行。

方式二（临时，便捷但明文进日志）：

  • 直接把 wrk-xxxx 发给我，我用命令内联执行。注意 Key 会明文出现在对话与执行日志，建议事后到微信读书侧轮换。

第三步：告诉我场景

  • 场景 A（某句话热评）：给我「书名 + 一句书中原话（划线想法）」⚠️ 该句必须是书里真实存在的划线（热门划线或你个人划线），否则匹配不到
  • 场景 B（全书热评）：给我「书名」即可
  • 我会先检查 Key 是否已设；没设会先提醒你，设好即可运行，无需重复说明。

适用场景

  • 场景 A（某句话的热门评论）：用户给出书名 + 一句原话（划线想法），采集该句下全部读者想法，按综合评分取 TopN。⚠️ 该句须为书中划线（热门划线或用户个人划线）；不是划线则无挂它的评论池，匹配不到。
    • 触发表达：「帮我找到关于『XXX』这句话的热门评论」「『XXX』这句话下面点赞最多的想法」「帮我找一找『XXX』的热门评论」。
  • 场景 B（某本书的热门书评）：用户给出书名，采集全书公开点评（书评），按综合评分取 TopN。
    • 触发表达：「帮我找一找《XXX》这本书的热门评论 / 热门书评」。

执行流程（直接用脚本，不要手搓 API 调用）

直接用 scripts/collect_hot_comments.py，它已封装鉴权、书定位、句子匹配、翻页、评分、HTML 渲染全链路。

场景 A 命令

python scripts/collect_hot_comments.py \
  --book "纳瓦尔宝典" \
  --quote "获得财富的一个途径，就是为社会提供其有需求但无从获得的东西，并实现规模化。" \
  --top 10 \
  --out result.html
  • --quote 为目标句子；脚本会自动在热门划线 + 你的个人划线中匹配 range + chapterUid。
  • 若匹配不到：脚本打印 Top10 热门划线候选，提示用 --range <range> 强制指定（配合 --chapter-uid 指定章节）。

场景 B 命令

python scripts/collect_hot_comments.py --book "纳瓦尔宝典" --top 10 --out result.html
  • 不传 --quote 即进入书籍模式，拉取全书公开点评（默认 reviewListType=1 推荐，高赞集中；可用 --review-list-type 切换）。
  • --max-pages 对场景 A/B 通用，控制最大翻页数（脚本内建默认 200，传参可覆盖）。

常用参数

| 参数 | 说明 | 默认 | |------|------|------| | --book | 书名或 bookId（必填） | — | | --quote | 目标句子（场景 A）；不传=书籍模式 | — | | --range | 强制指定划线 range（跳过句子匹配） | — | | --chapter-uid | 配合 --range 指定章节 uid（API 未返回章节时使用） | 0 | | --review-list-type | 场景 B 点评列表类型（1=推荐/高赞集中） | 1 | | --top | 输出条数 | 10 | | --out | 输出 HTML 路径 | weread_hot_top{top}.html | | --max-pages | 最大翻页数（场景 A/B 通用，覆盖全量想法/点评） | 200 |

常见问题 / 排错（新用户自助）

| 现象 | 原因 | 处理 | |------|------|------| | 请先设置环境变量 WEREAD_API_KEY=wrk-xxxx | Key 未配（系统/用户环境变量缺失，或本机临时 export 对 agent 不可见） | 配系统/用户级环境变量（见第二步方式一）后重开会话；或内联发 Key 给我执行 | | 匹配到错误的书 / 同名书选错 | 书名模糊，精确匹配取首位 | 用 bookId 代替书名，或书名写更完整 | | 句子匹配不到评论 | 该句不是书中划线，或原话与划线不一致 | 句子必须是书里真实划线（热门划线或你个人划线）；复制原句；或脚本给的候选里挑 --range 强制 | | 结果太少 / 像没数据 | 该书公开点评本身就少，或 reviewListType 不符 | 试 --review-list-type 0/2；或换场景 A | | 输出文件找不到 | 未指定 --out | 默认落在 weread_hot_top{top}.html（当前工作目录）；建议显式 --out 指定绝对路径 |

评分标准（详见 references/scoring_standard.md）

  • 场景 A：composite = 0.55 × semantic + 0.45 × like_norm
    • semantic = 概念覆盖(≤30) + 区分度(≤20) + 洞察增量(≤35) + 准确性(≤15)
    • like_norm = 100 × ln(1+likes) / ln(1+max_likes)
  • 场景 B：composite = 0.7 × like_norm + 0.3 × quality
    • quality 由长度与结构信号（是否含案例/逻辑/框架）决定，上限 100。

关键接口与坑（详见 references/api_docs.md）

  • 网关 https://i.weread.qq.com/api/agent/gateway，POST + JSON body，字段 api_name 指定接口，skill_version=1.0.4。
  • 句子模式 /book/readreviews：likesCount 在 pageReview 顶层；翻页游标 maxIdx 取自 reviews[0].maxIdx，停于 hasMore != 1。
  • 书籍模式 /review/list：likesCount 在 review.review.likesCount（嵌套）；翻页游标 maxIdx = 末条.idx + 1，停于 reviewsHasMore != 1。

输出与呈现

  • 生成自包含 HTML（内嵌 CSS，浅色主题），含标题、目标句引用块（场景 A）、TopN 评论卡片（作者 + 点赞 ♥ + 正文）、底部方法来源说明。
  • 用 present_files 将该 HTML 呈现给用户。

参考文件

  • references/api_docs.md：接口、鉴权、翻页、字段位置全记录。
  • references/scoring_standard.md：综合评分标准七节说明。
  • assets/top10_template.html：结果页 HTML 模板（可改样式复用）。