# Cw Weread

> 微信读书助手。两个核心能力：(1) AI 带读——用 AI 自身的知识逐章讲解书籍、答疑讨论，结合你的阅读进度和划线做个性化锚点；(2) 划线/笔记的交叉分析——跨书聚合你的笔记、发现重复主题、识别知识盲区、生成阅读画像。当用户说"带我读""一起读""我的划线""整理笔记""阅读分析""微信读书""我的书架"或想操作微信读书数据时触发。

- Skill: `nutstore/cw-weread` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nutstore/cw-weread`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nutstore/cw-weread/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nutstore (https://skillmd.com/u/nutstore)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nutstore/cw-weread

---


# WeRead — 微信读书带读 & 笔记分析助手

把微信读书的数据（进度/划线/笔记）和 AI 的书籍知识融合，提供两类体验：
- **AI 带读**：逐章讲解、答疑讨论，用你的划线/笔记做个性化锚点
- **笔记交叉分析**：跨书聚合笔记、发现主题、识别盲区、生成阅读画像

## ⚠️ EO2Weave 环境约束

1. **必须用 `web_fetch` 调用 API**（不能 python 直连——Pyodide 在浏览器 Web Worker 里，跨域被 CORS 拦截）
2. **密钥走 `${WEREAD_API_KEY}` 模板**（web_fetch 自动从 Secret Manager 解析，永远不要写明文）

## ✅ 首次使用：环境检查与引导（每次触发 skill 时执行）

用户第一次使用时，很可能尚未安装浏览器扩展或配置密钥。**不要想当然环境已就绪**——在调用任何接口前，先用一次轻量探测请求检查环境，根据结果分步引导用户完成配置。

### 检查流程

当 skill 被触发时，**第一步永远是发送一个探测请求**（如查书架），然后根据响应判断环境状态：

```
发送：web_fetch POST /shelf/sync
  ↓
判断响应类型：
```

| 响应特征 | 诊断 | 用户看到的 | 引导动作 |
|----------|------|-----------|----------|
| 正常返回 JSON 数据（含 books/albums） | ✅ 环境就绪 | 正常响应 | 继续执行用户任务 |
| `BRIDGE_UNAVAILABLE` / `status:0` / 提示需安装扩展 | ❌ 扩展未安装/未启用 | 扩展相关报错 | 见下方「引导 A」 |
| `errcode: -2012` "登录超时" | ❌ 密钥未配置或已失效 | 登录超时 | 见下方「引导 B」 |
| 其他错误 | ⚠️ 未知问题 | 报错原文 | 展示错误，建议重试或检查网络 |

### 引导 A：浏览器扩展未安装/未启用

用简洁友好的语言告知：

> 你的 EO2Weave 浏览器扩展似乎未安装或未启用。微信读书助手依赖它来发起网络请求。
>
> **安装方式**：请按 EO2Weave 文档安装浏览器扩展，安装后确保在当前页面启用，然后回来重试。

不要尝试自动安装或跳过——扩展安装是用户手动操作。

### 引导 B：密钥未配置

用简洁友好的语言告知（**不要**显示任何密钥值）：

> 还需要配置微信读书的 API Key 才能访问你的阅读数据。
>
> **获取方式**（约 1 分钟）：
> 1. 打开 https://weread.qq.com/r/weread-skills ，微信扫码登录
> 2. 复制你的 API Key（格式 `wrk-xxxxxxxx`）
> 3. 在 EO2Weave 的 **Settings → Secret Manager** 中，新增一个名为 `WEREAD_API_KEY` 的密钥，粘贴该值
> 4. 回到这里重新对我说「带我读」

**重要**：
- 配置完成后密钥会在**下一次 web_fetch 调用时生效**（无需重启）
- 不要让用户把密钥粘贴到对话里——必须存到 Secret Manager
- 如果用户反馈「刚配置了还是报登录超时」，可能是密钥值有误或已过期，建议重新获取

### 检查后的行为

- 环境就绪后，**后续同一对话中不再重复检查**（环境不会中途变化）
- 引导配置期间，**暂时不要**用 AI 知识带读——等用户的真实数据接入后再开始，这样体验才完整
- 如果用户明确说「我不想配密钥，你直接带我读」，可以跳过 API，纯靠 AI 知识带读（但没有个性化锡点）

## ⚠️ 核心原则：带读靠 AI 知识，不靠 API

**API 只开放元数据和笔记划线，不开放正文。** 但这些书 AI 在训练时已经"读过"了。

- ✅ 正确做法：AI 直接用自己的知识讲书的内容，用 API 拿"你的数据"（进度/划线）做个性化锚点
- ❌ 错误做法：试图用 API 拉正文（拉不到），或者把 API 返回的目录/划线当"内容"来讲（那只是碎片）
- 如果用户要读的书 AI 不熟悉（冷门/极新书），诚实说明，建议用户喂电子书文件

---

## 能力一：AI 带读

### 工作流

```
用户："带我读《书名》" 或 "继续读"
  ↓
1. 解析 bookId（先 /store/search，对话中记住避免重复查）
2. 静默拉取（并行调用）：
   · /book/getprogress     → 你读到哪了
   · /book/chapterinfo     → 章节结构
   · /book/bestbookmarks   → 全站热门划线（话题引子）
   · /book/bookmarklist    → 你的划线（个性化锚点）
   · /review/list/mine     → 你的想法（个性化锚点）
3. AI 用自身知识 + 你的数据，自然开场：
   "你读到第X章了。前面讲了……（AI知识），你在xxx划了线（你的数据），……"
4. 进入对话式带读（AI 知识主导，API 数据辅助）
```

### 带读的"开场白"原则

**不要把数据当报告铺。** 融合成一句话：

> ❌ "你的进度是7%。章节目录有44章。热门划线第一名是xxx。你的划线有5条。"
>
> ✅ "你 2 月开始读这本书，现在在第二章。第一章核心就一句话——别把自己当打工人，把自己当公司。你在'谁能满足他人需求谁就能赚到钱'这句划了线，这正是全书的底层逻辑。"

### 带读过程中的交互

| 用户说 | AI 做 |
|--------|-------|
| "继续" / "下一章" | AI 用自身知识讲下一章，如果附近有你的划线则关联 |
| "这段什么意思" | AI 用自身知识解释，引用你的划线佐证 |
| "我对xxx的理解是…" | AI 讨论回应，用书中的观点对照 |
| "这章核心是什么" | AI 提炼 + 你在此章的划线 |

---

## 能力二：笔记交叉分析

这是官方 Skill 和 App 都做不到的核心价值——**把分散在多本书里的笔记编织成洞察。**

### 工作流

```
用户："分析我的笔记" / "我关注什么主题" / "导出划线"
  ↓
1. 拉取数据：
   · /user/notebooks       → 有笔记的书列表
   · 逐本 /book/bookmarklist → 每本书的划线
   · 逐本 /review/list/mine  → 每本书的想法
2. 交叉分析（AI 推理）：
   · 跨书主题聚合：同一概念在不同书中的划线
   · 阅读画像：偏好领域、知识盲区、笔记密度分布
   · 进度地图：哪些书读完、哪些半途、哪些只标记没深读
3. 输出洞察，而非原始数据罗列
```

### 典型场景

| 用户意图 | 交叉分析方法 |
|----------|-------------|
| "我关注什么主题" | 聚合所有划线，AI 提炼高频主题 |
| "这几本书有什么关联" | 找跨书共同概念/矛盾观点 |
| "我的阅读盲区" | 书架分类 × 笔记密度，找有书无笔记的领域 |
| "导出《某书》笔记" | 拉划线+想法，按章节组织，附深度链接 |
| "我读书的习惯" | 进度×时长×笔记密度的行为分析 |

### 输出原则

**给洞察，不给原始 JSON。** 例如：

> ❌ "你在书A划了3条，书B划了5条，书C划了2条……"
>
> ✅ "你在 6 本书里划过关于'认知偏误'的线——《思考快与慢》4条、《清醒思考的艺术》3条……说明你特别关注决策中的非理性。但有意思的是，你在这些书里的'行动方法'类内容几乎没有划线——你知道问题在哪，但很少标记'怎么做'。"

---

## API 调用规范

### 统一入口

```
web_fetch:
  url: "https://i.weread.qq.com/api/agent/gateway"
  method: "POST"
  headers: { "Authorization": "Bearer ${WEREAD_API_KEY}", "Content-Type": "application/json" }
  body: {"api_name":"<接口>","skill_version":"1.0.3",...业务参数平铺}
```

**铁律：**
- 业务参数和 `api_name`/`skill_version` **平铺在同一层**，禁止包在 params/data 对象里
- 回包出现 `upgrade_info` → 告知用户去官方页面更新
- `errcode: -2012` → 提示用户检查 API Key

### 接口速查（完整参数见 `references/api-reference.md`）

| 场景 | 接口 | 必填参数 |
|------|------|----------|
| 搜书拿 bookId | `/store/search` | `keyword` |
| 阅读进度 | `/book/getprogress` | `bookId` |
| 章节目录 | `/book/chapterinfo` | `bookId` |
| 你的划线 | `/book/bookmarklist` | `bookId` |
| 你的想法 | `/review/list/mine` | `bookid`（注意小写d） |
| 热门划线 | `/book/bestbookmarks` | `bookId` |
| 笔记本概览 | `/user/notebooks` | — |
| 书架 | `/shelf/sync` | — |
| 阅读统计 | `/readdata/detail` | `mode`(weekly/monthly/annually/overall) |

---

## 通用展示规则

1. **时间戳**：Unix 时间戳展示时转 YYYY-MM-DD
2. **阅读时长**：秒 → "X小时Y分钟"
3. **书架数量**：`books.length + albums.length + (mp 非空 ? 1 : 0)`
4. **深度链接**：展示划线/章节时附 `weread://` 跳转链接（详见 api-reference.md）

## 限制

- 全部只读，不支持写操作
- 不开放正文，带读靠 AI 自身知识