Reading Widget — 微信读书桌面小卡片

把当前用户的微信读书数据渲染成一个 264px 宽的暗色小卡片（Material 3 配色），放在桌面上。

数据由一个本地小后台 server.py（127.0.0.1:47900）提供：它一边按 http 把卡片发给浏览器，一边每 30 分钟自动重抓一次微信读书数据，并接收卡片上手动改目标的请求写回 config.json。所以目标改了重启不丢、数据不用手动 update。

安装流程（Claw 按顺序执行）

Step 1 — 确认前置依赖

1. 检查 WEREAD_API_KEY 是否已设置：
• 先看 ~/.claw/settings.json（Claude Code 用户为 ~/.claude/settings.json）的 env 字段
• 再看当前 shell 环境变量
2. 如果没有 API key：
• 告诉用户 key 格式是 wrk-xxxxxxxx，绑定用户身份（vid）
• 让用户参考微信读书官方 skill 包获取：https://cdn.weread.qq.com/skills/weread-skills.zip，解压后看 SKILL.md 的"鉴权"章节
• 拿到 key 后写进 ~/.claw/settings.json 的 env 字段（不要写进 shell rc，避免泄露到其它进程），格式：

```json

{ "env": { "WEREAD_API_KEY": "wrk-xxxxxxxx" } }

```

1. 检查 python3 是否可用（which python3）。macOS 自带；如缺失提示装 Xcode Command Line Tools。

Step 2 — 安装到桌面

1. 创建 ~/Desktop/reading-widget/ 目录
2. 从 skill 目录复制文件过去：
• update.py → 抓数据+渲染
• template.html → 模板
• server.py → 本地小后台（发卡片 + 存目标 + 自动刷新）
• open-widget.sh → 一键打开脚本
• config.default.json → 重命名为 config.json
• com.user.reading-widget.plist → launchd 模板（Step 4 用，先别动）
3. 跑一次 WEREAD_API_KEY=xxx python3 ~/Desktop/reading-widget/update.py 生成首版 widget.html
4. 如果脚本报错（key 无效、网络等），把错误原样给用户看，不要瞎猜原因

Step 3 — 一键打开 widget

跑打开脚本，它会先确保本地小后台 server.py 起着（没起就拉起来），再用 Chrome --app 模式打开一个无边框小窗，指向 http://127.0.0.1:47900/widget.html：

bash ~/Desktop/reading-widget/open-widget.sh

走 http://127.0.0.1 而不是 file://，是为了让卡片上手动改目标能 POST 回 server.py 存进 config.json（file:// 下同源请求会被拦，目标改了重启就丢）。没装 Chrome 时脚本退化到默认浏览器；后台拉不起来时退化到 file://（此时改目标不持久）。

Step 4（可选，但推荐）— 开机自启后台

Step 3 是「打开时才拉起后台」。如果想让数据一直在后台每 30 分钟刷新（不用每次手动开卡片），把 server.py 设成开机自启。

> ⚠️ 这是给用户电脑加一个常驻 LaunchAgent，属于持久化系统改动。装之前必须明确问一句用户同不同意，不要默默 load。

1. 把 skill 目录里的 com.user.reading-widget.plist 复制到 ~/Library/LaunchAgents/，并把里面的 USERNAME 换成真实用户名、/usr/bin/python3 换成 which python3 实际路径。
2. 加载：launchctl load ~/Library/LaunchAgents/com.user.reading-widget.plist

注意 plist 里不放 WEREAD_API_KEY——server.py → update.py 会自己从 ~/.claw/settings.json 的 env 读 key，别把 key 落进 plist。日志在 ~/Desktop/reading-widget/helper.log。

自定义

• 月度目标：直接在 widget 卡片上点那个数字改即可，会经 server.py 的 POST /set-goal 写回 config.json（重启不丢）；也可以手动编辑 config.json 的 goal_hours。
• 后台刷新间隔：改 server.py 顶部的 REFRESH_INTERVAL（秒，默认 1800）。
• 卡片自刷间隔：改 config.json 的 refresh_seconds（HTML meta refresh，默认 300）。
• 配色/尺寸：直接改 template.html 的 CSS（Material 3 暗色 token 在 :root），重跑 update.py 生效。
• 金句过滤：脏词黑名单在 update.py 顶部的 QUOTE_BLOCKLIST，命中的热门划线会跳过换下一条。

卡片显示了什么

两个 stat 卡片可点击翻面看对比（今日↔本周、本月↔今年），靠 CSS .flipped class 切换，无需 JS 文件。

触发用户调用本 skill 的场景

• 安装/重装：用户说"装这个 widget"、"让我也用上"
• 排错：widget 数据没刷新、卡片打不开、API 报 401、目标改了重启又变回去（多半是没走 server.py / 没用 http://）
• 改样式/改目标：用户想调小、换色、改月度目标
• 卸载：launchctl unload ~/Library/LaunchAgents/com.user.reading-widget.plist 并删该 plist；删 ~/Desktop/reading-widget/；从 settings.json 拿掉 key