yao-weread-skill

1<!--
2Copyright © 2026 姚金刚. All rights reserved.
3Project: yao-weread-skill
4Created by: 姚金刚
5Date: 2026-05-16
6X: https://x.com/yaojingang
7-->
8 
9# Yao WeRead Skill
10 
11从微信读书账号数据生成精排中文 HTML 报告。默认范围为截至今天的最近 24 个月。
12 
13## 输入
14 
15- 环境变量 `WEREAD_API_KEY`，格式遵循微信读书 skill 的要求。
16- 可选报告范围：`--years`、`--start` 或 `--end`。
17- 可选笔记深度：`--max-note-books`；省略或传 `0` 时处理微信读书返回的全部笔记书籍。
18- 可选输出目录。
19- 可选示例模式：`--sample-ai-founder --sample-scale 5`，不需要 `WEREAD_API_KEY`。
20 
21## 输出
22 
23流程会生成：
24 
25- `weread-report.html`：参考 kami 排版风格的交互式 HTML 报告。
26- `weread-report-data.json`：聚合后的图表数据。
27- `weread-raw-summary.json`：不含密钥的 API 结构和计数摘要，便于复核。
28 
29报告还会生成一个读者画像模块：顶部诗性总结、1 条画像金句，以及从近两年划线中筛选出的最多 20 条高价值句子。原始划线和想法仅用于聚合分析与画像筛选。除非用户明确要求分享或发布，否则报告产物应视为私有内容。
30 
31## 工作流
32 
331. 调用 API 前先阅读微信读书 skill 文档：
34   - `shelf.md`：书架计数、公开/私密规则。
35   - `readdata.md`：阅读时长单位、周期规则、年度/月度字段。
36   - `notes.md`：笔记分页、笔记数计算、划线/想法文本。
37   - `book.md`：仅在需要书籍详情或阅读进度时使用。
382. 运行 `scripts/generate_weread_report.py`。
393. 检查生成的 HTML 至少包含 20 个图表面板，没有 `TODO`、占位文本或内嵌 API key。
404. 检查矩形树图、热力图、横向条形图等高密度图表没有被默认边距压缩，没有右侧空白导致标签截断。
415. 检查读者画像模块：金句必须来自画像划线清单第一条；真实账号模式不得编造划线，划线不足 20 条时如实少展示。
426. 如果用户要求视觉验证，或报告排版有实质变化，使用浏览器打开生成的 HTML，并检查桌面、平板宽度和窄屏宽度。
43 
44## 命令
45 
46```bash
47python3 scripts/generate_weread_report.py --output reports/generated
48```
49 
50常用选项：
51 
52```bash
53python3 scripts/generate_weread_report.py \
54  --years 2 \
55  --max-note-books 0 \
56  --output reports/generated
57```
58 
59AI 创业者示例报告：
60 
61```bash
62python3 scripts/generate_weread_report.py \
63  --years 2 \
64  --sample-ai-founder \
65  --sample-scale 5 \
66…