# Weread Export Skill

> weread-export — 微信读书整本导出（Markdown / EPUB / PDF）

- Skill: `yyucchen/weread-export-skill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add yyucchen/weread-export-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yyucchen/weread-export-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: YYuCChen (https://skillmd.com/u/yyucchen)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yyucchen/weread-export-skill

---

# weread-export — 微信读书整本导出（Markdown / EPUB / PDF）
当用户说“把这本微信读书给我导出来”或近似表达时，将单本微信读书导出为 Markdown、EPUB、PDF，并生成核验报告。

## When to Use

适用：

- 典型说法包括「把这本微信读书给我导出来」「帮我导出这本微信读书」「把这个微信读书链接导成 PDF / EPUB / Markdown」「微信读书导出」；
- 不要求用户说出技能名 `weread-export`，也不要求语句与上述示例完全一致；
- 用户给出微信读书链接、`weread.qq.com` 链接或 book_id，并表达导出、保存或转成电子书的意图；
- 需要复跑核验：对照平台逐章字数复核已有产物；
- 需要三格式交付：Markdown（图片内嵌）/ EPUB / PDF + 核验报告；
- 导出中断后续跑、图片缺失补齐（同一条命令重跑即可）。

不适用：

- 书架 / 书单批量导出 —— 本技能不提供，一次只导一本（见 Rules）；
- 绕过验证码 / 会员 / 付费墙的内容 —— 不做。

## 前置条件

- 依赖：Python 3.10+、playwright、chromium、pandoc —— 安装命令见 `README.md`「5 分钟上手」。
- Windows 命令：优先在 PowerShell 使用 `py -3`；下文所有 `python3` 均替换为 `py -3`，路径含空格或中文时必须加引号。
- 登录：首次运行会弹出浏览器要求扫码；登录态持久化在 `~/.weread-export/profile/`（不随项目走）。
- 脚本路径：`<skill>/scripts/`（本项目中即 `.thincoder/skills/weread-export/scripts`），下文的命令按该路径给出。
- 脚本路径解析：项目级优先（`<当前项目目录>/.thincoder/skills/weread-export/scripts/`）；若技能只装在
  用户级 `~/.thincoder/skills/weread-export/scripts/`，把命令里的路径替换为实际位置即可（两处脚本一致）。
- 状态目录：工作数据在 `~/.weread-export/`（环境变量 `WEREAD_EXPORT_HOME` 可覆盖）；交付物在 `<当前项目目录>/<书名>/`。
- 状态目录清理：macOS/Linux 的 `rm -rf ~/.weread-export` 或 Windows PowerShell 的 `Remove-Item -Recurse -Force "$HOME\.weread-export"` 会连登录态一起清掉（下次运行需重新扫码）。

## 包结构（速览）

| 路径 | 内容 |
|---|---|
| `SKILL.md` | 本文件：agent 入口（适用条件 / 停询触发点 / 合规 / 流程） |
| `README.md` | 给人看的上手说明与故障对照表 |
| `references/playbook.md` | 症状 → 判据 → 修法速查表（30 条实测坑） |
| `scripts/preflight.py` | 预检：登录 / 可读性 / 端到端冒烟 / 平台逐章基线 |
| `scripts/export_precise.py` | 导出引擎入口（含 `--postprocess` 离线后处理） |
| `scripts/download_images.py` | 普通图片与 TAR 图片包下载 / 补齐（可重复运行） |
| `scripts/verify_export.py` | 低 Token 核验并产出报告（含 `--report-out`、`--verbose`） |
| `scripts/make_formats.py` | 三格式转换（md 内嵌 / epub / pdf） |
| `scripts/weread_*.py` | 引擎模块（共享 / 切章 / 文本 / 抓取 / 导航 / 会话 / 后处理） |
| `scripts/tests/` | 回归测试（54 项，含包级检查） |

## 停询触发点（五条）

> 命中任一条：**先停下、给建议**；用户明确坚持时，按各条的「用户坚持时」执行。

### 触发点① 一次任务导 ≥2 本

- 条件：一次任务里要导 ≥2 本。
- 检测点：步骤 0（用户诉求）。
- 停询文案：「【停询】一次先导 1 本——同时导出多本会明显提高账号风控风险。我先做《X》，完成后再接下一本；确认连续导出请回复『确认连续导出』。」
- 用户坚持时：逐本串行继续，每本之间仍受本表第 4 条约束。

### 触发点② 想加速（低于默认间隔）

- 条件：用户想加速（要求低于默认的每页 1–2 秒）。
- 检测点：任一步（用户提出）。
- 停询文案：「【停询】默认节流（每页 1–2 秒）是防封底线，不建议加速。确认要加速请回复『确认加速』，我按你要求调低等待间隔（风险由你承担）。」
- 用户坚持时：设 `WEREAD_SLEEP_SCALE<1` 并保留醒目警告横幅；默认值不得偏离 1.0。

### 触发点③ 想并发多会话

- 条件：用户想同账号并发 / 多会话导出。
- 检测点：任一步（用户提出）。
- 停询文案：「【停询】同账号并发 / 多会话是高风险特征，本技能不提供并发编排；建议单会话串行。若你坚持自行并发，请在知情风险下进行。」
- 用户坚持时：不提供并发入口；用户可自行另开终端（各自后果自负）。

### 触发点④ 单日累计 ≥3 本

- 条件：今天的导出本数已达 3 本（本次将成为第 4 本）。
- 检测点：步骤 0（读 `~/.weread-export/runs.log` 数今日 `start` 行）。
- 停询文案：「【停询】今天已导出 N 本（见 ~/.weread-export/runs.log）。再导这本是今日第 N+1 本，接近风控红线，建议改天。继续请回复『确认继续』。」
- 用户坚持时：用户确认后继续（日志照记，供未来核对）。

### 触发点⑤ 异常信号（登录失效 / 验证码 / 访问受限 / 页面结构变化）

- 条件：各脚本输出 `⛔` 标记行，或退出码为 2 / 3 / 4。
- 检测点：各步骤命令的退出码与标记行。
- 停询文案：「【停询】检测到异常信号：<具体信号>。已停止。建议：登录失效→扫码重登；验证码/受限→暂停一段时间，勿反复重试；结构变化→保留现场，等修复后重试。」
- 用户坚持时：登录类重登即可继续；受限 / 结构类不强行推进。

## 合规边界

- 仅导出**账号已获阅读权限**的书（无限卡 / 已购买）；没有权限的书不做。
- 导出物**仅个人使用**：不传播、不上传、不分享给不特定人群。
- **不绕过**验证码 / 会员 / 付费墙；受限信号出现时停下询问，不静默重试绕过。
- 导出物不搬离本机：本技能不提供上传 / 分享 / 外发功能。

## Workflow

按顺序执行；每一步都有通过判据，未过判据不进入下一步。

### 步骤 0 开工前检查（agent 执行，不涉脚本）

1. 书目数：这次要导几本？≥2 本 → 见「停询触发点（五条）」表第 1 条。
2. 今日计数：读 `~/.weread-export/runs.log`，数今天的 `start` 行；≥3 本 → 见同表第 4 条。
3. 依赖探测：macOS/Linux 检查 `python3`，Windows 检查 `py -3`；同时检查 playwright / chromium / pandoc。缺 → 给出 README 对应系统的安装命令并停。

### 步骤 1 预检

```bash
python3 .thincoder/skills/weread-export/scripts/preflight.py "<链接或 book_id>"
```

通过判据：退出码 0 + 末尾 `✅ 预检通过`；输出含「抓到首页字符」且数值 > 0；
`~/.weread-export/books/<book_id>/_platform_chapterinfo.json` 已生成。记下 book_id 与书名。

首次运行需要在弹出的浏览器窗口里扫码登录（等待扫码 = 正常流程，不是失败）；登录态此后长期复用。

若用户要求重新登录，或旧登录态损坏，运行：

```bash
python3 .thincoder/skills/weread-export/scripts/preflight.py "<链接或 book_id>" --relogin
```

`--relogin` 会把旧 `profile` 改名备份，不删除书籍进度；Windows 将 `python3` 换成 `py -3`。

任一 `⛔` 标记 → 走下方「失败升级路径」。

### 步骤 2 导出

```bash
python3 .thincoder/skills/weread-export/scripts/export_precise.py "<链接或 book_id>"
```

长跑（实测量级 10–15 分钟；随书的长短线性变化）；中断后重跑同一条命令自动续传（从已完成章节续起）。
图片缺失 → 补齐：

```bash
python3 .thincoder/skills/weread-export/scripts/download_images.py <book_id>
```

通过判据：退出码 0；退出码 4（未达书末）→ 见失败升级路径。

导出期间不要手动关闭浏览器窗口（关闭 = 会话中断；重跑同命令会从已完成章节续起，不重抓）。
浏览器由脚本自动开关；中途遇到验证码 / 受限提示，脚本会停下并按上表给出信号。

不重爬、只重跑后处理（如调整后处理规则后重建合并稿）：

```bash
python3 .thincoder/skills/weread-export/scripts/export_precise.py --postprocess <book_id>
```

### 步骤 3 核验

```bash
python3 .thincoder/skills/weread-export/scripts/verify_export.py <book_id> \
  --report-out "<当前项目目录>/<书名>/核验报告.txt"
```

通过判据：退出码 0 且报告含 `核验结论: ✅ 达标`。
未达标（退出码 5）→ **停下如实报告，不自动重跑**，交用户裁决。
报告同时默认写一份到状态目录（`books/<book_id>/_verify_report.txt`）；`--report-out` 是交付副本。
默认终端只打印结论和计数，逐章明细留在报告文件中；只有排错确有需要时才加 `--verbose`。
图片只在本机读取文件头和大小，不上传图片、不做 OCR，也不要把图片/base64 或整份漫画载入 Agent 上下文。

### 步骤 4 转格式

```bash
python3 .thincoder/skills/weread-export/scripts/make_formats.py \
  ~/.weread-export/books/<book_id>/<书名>.md "<当前项目目录>/<书名>/"
```

通过判据：输出 `✅ 构建断言通过`（内嵌 md 无外部引用 / EPUB 内嵌图数 == 引用图数 / 打印 HTML 无外部资源）。
三件套（`<书名>.md` / `<书名>.epub` / `<书名>.pdf`）直接落在交付目录；配合步骤 3 的报告副本即四件齐全。

### 步骤 5 交付核对

- 四件套齐全：`<书名>.md` / `<书名>.epub` / `<书名>.pdf` / `核验报告.txt`。
- 向用户报路径 + 合规提醒（仅个人使用，不传播不上传）。

## 失败升级路径

退出码与标记行一一对应（契约见下表）——按表处置，不自行猜测：

| 信号 | 退出码 | 动作 |
|---|---|---|
| `⛔ 登录失效` | 2 | 提示用户扫码重登后重跑当前步骤（等待扫码 = 正常流程，非失败） |
| `⛔ 访问受限` | 3 | 停下 + 说明 + 建议暂停一段时间，勿反复重试（见停询表第 5 条） |
| `⛔ 页面结构可能变化` | 4 | 停下 + 报告证据与根因初判 + 等修复（见停询表第 5 条） |
| `⛔ 未检测到书末` | 4 | 停下 + 报告不完整章节 + 用户裁决 |
| `⛔ 核验未达标` | 5 | 停下 + 列出不达标字段 + 用户裁决 |
| 输入缺失 | 6 | 回查前置步骤（预检 / 导出）是否已跑、产物是否在状态目录 |
| 构建失败 | 7 | 按错误行处理（如缺 pandoc → 给安装命令）并重跑本步 |

## Rules

- 不提供书架批量（含书单）导出；用户要求时明确说明不支持（一次一本）。
- 不并发多会话、不自动重试受限类失败；不改默认节流（加速必须走停询表第 2 条流程）。
- 导出物仅个人使用：不传播、不上传、不分享。
- 不修改上游参考项目目录本体；包内副本才是交付物。
- 受限 / 结构类失败不静默绕过，不强行推进。

## References

- `README.md` —— 人类上手：5 分钟上手 / 手动路径 / 常见故障对照表。
- `references/playbook.md` —— 症状 → 判据 → 修法速查表（本轮全部坑的落点）。