---
id: gh-yao-weread-skill
name: "yao-weread-skill"
url: https://skills.yangsir.net/skill/gh-yao-weread-skill
author: yaojingang
domain: data-analysis
tags: ["wechat-reading", "data-analysis", "visualization", "report", "reading-history"]
install_count: 520
rating: 4.20 (121 reviews)
github: https://github.com/yaojingang/yao-open-skills/tree/main/skills/yao-weread-skill
---

# yao-weread-skill

> 此技能用于深度分析微信读书账户数据，自动生成包含阅读节律、偏好、书架资产、笔记统计等可视化报告，并导出精美 HTML 报告，助力用户全面回顾个人阅读画像。

**Stats**: 520 installs · 4.2/5 (121 reviews)

## Before / After 对比

### 微信读书报告生成效率

**Before**:

手动从微信读书导出数据，耗费大量时间进行数据清洗、图表制作和报告撰写，且报告质量参差不齐。

**After**:

一键生成专业、精美的微信读书阅读报告，包含多维度可视化图表，省时省力，报告质量高。

| Metric | Before | After | Change |
|---|---|---|---|
| 报告生成时间 | 480分钟 | 5分钟 | -99% |

## Readme

# Yao WeRead Skill

从微信读书账号数据生成精排中文 HTML 报告。默认范围为截至今天的最近 24 个月。

## 输入

- 环境变量 `WEREAD_API_KEY`，格式遵循微信读书 skill 的要求。
- 可选报告范围：`--years`、`--start` 或 `--end`。
- 可选笔记深度：`--max-note-books`；省略或传 `0` 时处理微信读书返回的全部笔记书籍。
- 可选输出目录。
- 可选示例模式：`--sample-ai-founder --sample-scale 5`，不需要 `WEREAD_API_KEY`。

## 输出

流程会生成：

- `weread-report.html`：参考 kami 排版风格的交互式 HTML 报告。
- `weread-report-data.json`：聚合后的图表数据。
- `weread-raw-summary.json`：不含密钥的 API 结构和计数摘要，便于复核。

原始划线和想法仅用于聚合分析。除非用户明确要求分享或发布，否则报告产物应视为私有内容。

## 工作流

1. 调用 API 前先阅读微信读书 skill 文档：
   - `shelf.md`：书架计数、公开/私密规则。
   - `readdata.md`：阅读时长单位、周期规则、年度/月度字段。
   - `notes.md`：笔记分页、笔记数计算、划线/想法文本。
   - `book.md`：仅在需要书籍详情或阅读进度时使用。
2. 运行 `scripts/generate_weread_report.py`。
3. 检查生成的 HTML 至少包含 20 个图表面板，没有 `TODO`、占位文本或内嵌 API key。
4. 检查矩形树图、热力图、横向条形图等高密度图表没有被默认边距压缩，没有右侧空白导致标签截断。
5. 如果用户要求视觉验证，或报告排版有实质变化，使用浏览器打开生成的 HTML，并检查桌面、平板宽度和窄屏宽度。

## 命令

```bash
python3 scripts/generate_weread_report.py --output reports/generated
```

常用选项：

```bash
python3 scripts/generate_weread_report.py \
  --years 2 \
  --max-note-books 0 \
  --output reports/generated
```

AI 创业者示例报告：

```bash
python3 scripts/generate_weread_report.py \
  --years 2 \
  --sample-ai-founder \
  --sample-scale 5 \
  --output reports/generated/ai-founder-sample
```

## 报告设计

- 视觉系统遵循 `references/report-design.md`。
- 图表模块遵循 `references/chart-catalog.md`。
- API 字段语义和降级规则遵循 `references/data-contract.md`。
- 高密度图表必须显式设置容器占满、标签换行/隐藏策略和 resize 监听，避免 ECharts 默认布局留下空白。

## 边界

- 真实账号模式下，不编造微信读书响应中不存在的阅读事件、笔记文本、评分或分类。
- AI 创业者示例模式用于在不接入真实账号时生成可复用示例报告。
- 不导出书籍全文；只使用用户自己的划线/想法，以及微信读书 skill 可访问的元数据。
- 不存储或打印 `WEREAD_API_KEY`。
- 无法获得精确滚动日期边界时，必须清楚标注月度或年度近似口径。


---

# Yao WeRead Skill

`yao-weread-skill` 用来把微信读书账户数据生成一份完整的个人阅读可视化报告。

它不是简单导出阅读时长，而是把阅读节律、书架资产、分类偏好、作者与出版社偏好、笔记密度、划线长度和高频笔记短语汇总到一份中文 HTML 报告中，便于做年度复盘、知识管理回顾和阅读画像展示。

## 输出内容

- `weread-report.html`：带 KPI 卡片、叙事分区、表格和图表的交互式 HTML 报告。
- `weread-report-data.json`：已经聚合好的图表数据。
- `weread-raw-summary.json`：不含密钥的覆盖范围和关键指标摘要，用于复核生成结果。

标准报告包含 20 个以上可视化模块。当前图表目录覆盖月度阅读时长、阅读天数、星期节律、累计阅读小时、读得最久的书、分类雷达、分类矩形树图、偏好作者、偏好出版社、文字阅读与听书拆分、书架构成、笔记类型构成、阅读进度与笔记量散点图、词云、笔记时间线和划线长度分布。

## 快速开始

真实微信读书账号报告：

```bash
export WEREAD_API_KEY="<你的_WEREAD_API_KEY>"

python3 scripts/generate_weread_report.py \
  --years 2 \
  --max-note-books 0 \
  --workers 6 \
  --output reports/generated/latest
```

AI 创业者示例报告：

```bash
python3 scripts/generate_weread_report.py \
  --years 2 \
  --sample-ai-founder \
  --sample-scale 5 \
  --output reports/generated/ai-founder-sample
```

生成后用浏览器打开 `weread-report.html`。

## 工作逻辑

1. 通过已安装的微信读书 skill 网关读取数据。
2. 从 `/readdata/detail` 获取月度和年度阅读统计。
3. 从 `/shelf/sync` 获取书架结构。
4. 从 `/user/notebooks` 获取有笔记的书籍概览。
5. 从 `/book/bookmarklist` 和 `/review/list/mine` 获取划线和想法。
6. 将接口数据聚合成稳定的 JSON 数据契约。
7. 使用 ECharts 和确定性的中文短语抽取逻辑渲染独立 HTML 报告。

## 设计说明

- 报告采用 `kami` 风格的中文长报告视觉系统：暖纸底、墨蓝强调、编辑式层级和紧凑证据卡片。
- 图表按叙事分区组织：时间节律、阅读偏好、书架资产、笔记与语义。
- 高密度图表会显式占满容器，树图标签优先中文折行，小块隐藏标签并保留 tooltip，避免右侧留白和边缘裁切。
- 词云优先保留领域词，并过滤常见中文短语碎片。
- 书籍阅读时长使用 `readLongest[].readTime`，不从书架更新时间推断。
- 没有真实书名或专辑名的匿名 `readLongest` 记录会被过滤。

## 隐私说明

- 脚本从环境变量读取 `WEREAD_API_KEY`，不会把它写入磁盘。
- 真实生成的报告可能包含个人划线和想法，不要把 `reports/generated/latest` 直接提交到公开仓库。
- 仓库内置的 `examples/ai-founder-report/weread-report.html` 是公开示例报告。


---
*Source: https://skills.yangsir.net/skill/gh-yao-weread-skill*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-yao-weread-skill/markdown*