# 微信读书 Obsidian 插件 V2 使用指南

V2 是一次重大架构升级，核心变化是**以 API Key 替代 Cookie 作为主要认证方式**，并引入了**热门划线同步**、**书籍详情页**、**主题系统**和**阅读统计**等全新功能。

## 目录

- [快速开始：获取 API Key](#快速开始获取-api-key)
- [API Key 管理](#api-key-管理)
- [认证机制：V2 / V1 双模式](#认证机制v2--v1-双模式)
- [热门划线同步](#热门划线同步)
- [书籍详情页](#书籍详情页)
- [主题系统与模板编辑器](#主题系统与模板编辑器)
- [阅读统计](#阅读统计)
- [书架增强](#书架增强)
- [全部设置项说明](#全部设置项说明)
- [自定义模板变量参考](#自定义模板变量参考)
- [常见问题](#常见问题)

---

## 快速开始：获取 API Key

V2 使用微信读书 Agent API Key（格式：`wrk-xxxxxxxx`）进行认证，相比 Cookie 方式更加稳定。

### 桌面端（推荐）

1. 打开设置页（书架页右上角 ⚙️ 图标）
2. 找到「API Key」输入框
3. 点击 **「扫码获取」** 按钮：
   - **已登录**：自动从微信读书网页版获取并填入 Key
   - **未登录**：弹出二维码窗口，用微信扫描完成登录后自动获取
4. 获取成功后输入框旁显示 ✓ 绿色图标表示 Key 有效

### 移动端

移动端无法使用扫码登录（需要 Electron），需手动获取：

1. 访问 [微信读书网页版](https://weread.qq.com)
2. 登录后进入 <https://weread.qq.com/api/skills/apikeyGet>
3. 复制返回的 API Key
4. 粘贴到设置页的 API Key 输入框中

---

## API Key 管理

### 状态校验

- 打开设置页时自动校验 API Key 有效性
- 状态图标：**✓ 绿色** = 有效 · **✗ 红色** = 无效 · **◌ 灰色** = 未校验
- 鼠标悬停在图标上可查看状态提示

### 注销

已配置 API Key 时会显示 **「注销」** 按钮，点击可一键清除 Key 和登录态。

### Cookie 向后兼容

保留 Cookie 登录方式作为后备选项：
- 支持 CookieCloud 同步和手动扫码两种登录方式
- 如果 API Key 请求失败，自动回退到 Cookie 模式
- 没有 API Key 时插件行为与 V1 完全一致

---

## 认证机制：V2 / V1 双模式

插件内置双模式路由（ApiRouter），自动选择最优认证方式：

```
有 API Key → 优先 V2 Agent API (Bearer Token) → 失败时回退 V1 Cookie API
无 API Key → 仅 V1 Cookie API
```

### V2 专有功能（需要 API Key）

| 功能 | V2 API 接口 | 说明 |
|------|------------|------|
| 热门划线 | `/book/bestbookmarks` | 每本书 TOP 20 热门划线 |
| 公开书评 | `/review/list` | 书籍的社区公开点评 |
| 书架同步 | `/shelf/sync` | 完整书架数据（含有声书） |
| 阅读统计 | `/readdata/detail` | 详细阅读统计和偏好分析 |

### V1 / V2 共通功能

书籍详情、划线列表、个人笔记、章节信息、阅读进度等接口同时支持 V1 和 V2，自动选择可用方式。

---

## 热门划线同步

**热门划线**是微信读书社区的公开精华内容——被最多读者标记的段落。V2 支持将这些内容同步到本地笔记。

### 启用

1. 确保已配置有效的 API Key
2. 在设置页开启 **「同步热门划线」** 开关
3. 执行同步（手动或定时），热门划线将写入笔记文件

### 同步策略

- **每本书最多 20 条**热门划线（按热度排序）
- 按章节并发查询，每批 5 个章节
- 本地缓存（`.weread-cache/` 目录），默认 **7 天有效期**
- 同步时如果缓存未过期则直接复用，无需联网请求

### 模板中的展示

在合并式模板中，热门划线与用户划线融合：

| 场景 | 标记 | 说明 |
|------|------|------|
| 自己划了 + 是热门 | 📌🔥 `N 人共读` | 保留自己的 reviewContent 和 createTime |
| 仅热门（自己没划） | 🔥 `N 人共读` | 追加到对应章节中，按位置排序 |
| 仅自己划线（不热门） | 📌 | 与 V1 行为一致 |

**不在热门划线时切换说明**：关闭设置页的「同步热门划线」开关后，下次同步的热门标记和共读人数信息将不会出现在笔记中。

### 分离式（含热门划线）模板

如果选用 `builtin_separated_with_popular` 主题，热门划线会在独立的「热门划线」区块中展示，以章节为分组，每段标注热度人数和 deeplink 链接。

### 缓存管理

可调整缓存有效期（默认 7 天）。缓存文件保存在 vault 的 `.weread-cache/` 目录下，删除后下次同步会自动重建。

---

## 书籍详情页

点击书架上的书籍封面或标题，会在新标签页打开**书籍详情视图**。

### 四个标签页

1. **划线** — 按章节分组展示所有个人划线
   - 每张卡片有**颜色边线**（黄/蓝/绿/红/紫），对应划线颜色
   - 显示创建时间、位置
   - 有笔记的划线显示 ✏️ 图标
   - 支持 deeplink 跳转到微信读书 App 和复制原文

2. **笔记** — 所有个人想法和注解
   - 按时间倒序排列
   - 显示引用原文（abstract）和笔记内容
   - 支持换行等 Markdown 格式

3. **热门划线** — 社区热度最高的划线（需 API Key）
   - 按章节分组展示
   - 显示 `🔥 N 人划线`
   - 支持 deeplink 跳转

4. **书评** — 两部分
   - **我的书评**：个人对书籍的完整评价
   - **社区书评**：公开的精选书评（最多 20 条），含用户头像、昵称、评分

### Header 区域

- 书籍封面、标题、作者
- 阅读进度、阅读时长、最后阅读日期
- 分类、出版社、字数、出版时间
- 简介（长文本可折叠展开）

### 操作按钮

- **阅读** — 快速打开微信读书网页版或 App（根据设置）
- **刷新** — 重新获取书籍数据并同步本地笔记
- **返回笔记** — 右下角悬浮按钮，点击打开本地 Markdown 笔记

### UI 特性

- 新标签页打开，不覆盖书架页，支持原生 Tab 切换
- 响应式布局，移动端适配（768px / 480px 断点）
- Tab 栏吸顶效果（sticky），滚动时保持可见
- 悬浮按钮在移动端放大（52px）便于触控

---

## 主题系统与模板编辑器

V2 用**主题系统**替代了原先的单一模板设置，支持多个主题并存和一键切换。

### 内置主题（4 个）

1. **合并式模板** (`builtin_merged`) — 划线和笔记内联展示，热门划线合并到章节
2. **分离式模板** (`builtin_separated`) — 划线在前，笔记汇总在后
3. **微信官方笔记主题** (`builtin_official`) — 微信读书官方风格，含详细元数据
4. **分离式（含热门划线）** (`builtin_separated_with_popular`) — 我的划线、热门划线、笔记三个独立区块

### 主题管理器

在设置页点击「主题管理」进入管理界面：

- **切换主题** — 点击「使用」设置活动主题，下次同步生效
- **预览** — 以只读方式查看模板源码和预览效果
- **编辑** — 自定义主题可打开模板编辑器修改
- **复制** — 基于内置主题创建副本进行定制
- **导入/导出** — 支持 JSON 格式模板文件分享和导入
- **新建** — 从零编写自定义模板

### 模板编辑器

三栏布局的完整编辑器（详见 [template-editor-window.md](./template-editor-window.md)）：

- **左侧**：Nunjucks 模板语法参考文档
- **中间**：模板源码编辑器
- **右侧**：实时预览（300ms 防抖），使用示例数据渲染

特性：
- 自动去空白（trimBlocks）开关
- Markdown 渲染 / 源码视图切换
- 保存前验证模板语法
- 关闭时未保存提醒

### 社区主题

支持导入他人分享的 `.json` 格式主题文件，也支持从 URL 远程导入。V1 的自定义模板自动迁移为「旧模板」类型，保持向后兼容。

---

## 阅读统计

需要 API Key。从命令面板或书架页「阅读统计」按钮触发。

### 同步统计文件

生成一份 Markdown 文件，包含：

1. **历年总览** — 总阅读时长、阅读天数、读完数、各年阅读时长分布
2. **当年阅读概况** — 月度时长柱状图（文本）、阅读 TOP 书籍、分类偏好、作者偏好
3. **当月阅读概况** — 每日时长柱状图、阅读 TOP 书籍、分类偏好
4. **阅读偏好分析** — 24 小时时间分布（阅读 vs 听书）、品类偏好

设置中可指定：
- **统计文件存放位置** — 默认 vault 根目录
- **起始年份** — 热力图起始年（0 = 使用注册时间）

### 交互式统计视图

从书架页打开「阅读统计」视图，提供四个维度的可视化：

- **全部** — 历史累计统计
- **周** / **月** / **年** — 按周期拆分，支持前后翻页
- 热力图展示每日阅读强度
- 分类、作者偏好饼图
- 阅读时间分布柱状图

---

## 书架增强

### 工具栏

- **搜索** — 按标题/作者实时过滤
- **类型筛选** — 图书 / 公众号（关闭「同步公众号内容」时自动隐藏并过滤）
- **同步状态** — 全部 / 仅远程 / 已同步 / 仅本地
- **阅读状态** — 全部 / 在读 / 已读完

### 操作按钮

- **同步** — 全量同步；按住 Alt/Opt 点击为**强制同步**（忽略缓存）
- **Web 阅读** — 桌面端可用，打开微信读书网页版
- **阅读统计** — 打开交互式统计视图
- **同步日志** — 最近 10 次同步记录
- **设置** — 打开插件设置页

### 书籍卡片

- 按年份分组（可关闭）
- 排序模式：最近阅读 / 按标题
- 同步状态标签：已同步 / 仅远程 / 仅本地 / 公众号
- 点击标题 → 打开本地笔记
- 点击封面或详情 → 打开书籍详情页
- 单本书操作：同步 / 删除 / 阅读

---

## 全部设置项说明

### 登录与认证

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 登录方式 | 扫码登录 | `扫码登录` 或 `CookieCloud` |
| CookieCloud 配置 | — | 服务器地址、UUID、密码 |
| API Key | 空 | 格式 `wrk-xxxxxxxx`，用于 V2 Agent API |
| 注销 | — | 清除 API Key 和 Cookie |

### 同步设置

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 笔记保存位置 | `/` | vault 根目录 |
| 文件夹分类 | 不分类 | `不分类` / `按书名` / `按分类` |
| 文件名格式 | 书名 | `书名` / `书籍ID` / `书名-作者` / `书名-ID` |
| 书名去括号 | 关闭 | 去除书名中的 `()` 及其内容 |
| 书名去括号白名单 | 空 | 含关键词的书名不去括号 |
| 过滤 `[图片]` 占位符 | 关闭 | 移除划线中的图片/插图提示 |
| 划线加标签 | 关闭 | `#tag` 转为 `[[tag]]` |
| 去掉空白行 | 关闭 | 渲染后去除多余空格 |
| 同步公众号内容 | 开启 | 关闭后书架不显示公众号 |
| 同步阅读信息到 frontmatter | 开启 | 写入元数据到 YAML frontmatter |
| **同步热门划线** 🔥 | 关闭 | 同步每本书 TOP 20 热门划线（需 API Key） |
| **热门划线缓存 TTL** 🔥 | 7 天 | 缓存有效期 |

### 同步过滤

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 笔记最小数量 | -1（不限） | 低于此数量的书不同步 |
| 过滤模式 | 黑名单 | `黑名单` / `白名单` |
| 黑名单/白名单 | 空 | 逗号分隔的书籍 ID |
| 同步天数过滤 | 不限 | 仅同步最近 N 天更新的书 |

### 阅读

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 阅读打开方式 | 标签页 | 打开网页时使用标签页或窗口 |
| 书籍链接方式 | 网页版 | 点击书籍 `网页版` 或 `App deeplink` |
| App 阅读跳转方式 | TAB | 使用 TAB 或 WINDOW 打开 |

### 模板主题 🔥

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 活动主题 | 合并式模板 | 当前使用的同步模板 |
| 主题管理 | — | 打开主题管理器 |

### 定时同步

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 启用定时同步 | 关闭 | 每隔 N 分钟自动同步 |
| 同步间隔 | 5 分钟 | 最小 1 分钟 |

### 阅读统计 🔥

| 设置 | 默认值 | 说明 |
|------|--------|------|
| 统计文件位置 | `/` | vault 根目录 |
| 起始年份 | 0 | 热力图起始年（0 = 使用注册时间） |

> 🔥 = V2 新增功能

---

## 自定义模板变量参考

自定义模板可访问以下变量：

### 元数据 `metaData`

| 变量 | 类型 | 说明 |
|------|------|------|
| `metaData.bookId` | string | 书籍 ID |
| `metaData.title` | string | 书名 |
| `metaData.author` | string | 作者 |
| `metaData.cover` | string | 封面图片 URL |
| `metaData.url` | string | 网页版链接 |
| `metaData.pcUrl` | string | PC 版链接 |
| `metaData.noteCount` | number | 划线总数 |
| `metaData.reviewCount` | number | 笔记总数 |
| `metaData.isbn` | string | ISBN（可能为空） |
| `metaData.category` | string | 分类 |
| `metaData.publisher` | string | 出版社 |
| `metaData.intro` | string | 简介 |
| `metaData.totalWords` | number | 总字数 |
| `metaData.lastReadDate` | string | 最后阅读日期 |
| `metaData.rating` | number | 评分 |
| `metaData.readInfo` | object | 阅读信息（状态、进度、时长等） |

### 章节划线 `chapterHighlights`

数组，每个元素包含：

| 变量 | 类型 | 说明 |
|------|------|------|
| `chapterUid` | number | 章节 UID |
| `chapterIdx` | number | 章节序号 |
| `chapterTitle` | string | 章节标题 |
| `level` | number | 标题层级（1/2/3） |
| `highlights` | array | 该章节的划线列表 |
| `popularHighlights` | array | 该章节的热门划线 🔥（已废弃，见下方） |
| `chapterReviews` | array | 该章节的笔记列表 |

每条 `highlight` 包含：

| 变量 | 类型 | 说明 |
|------|------|------|
| `bookmarkId` | string | 划线 ID |
| `markText` | string | 划线原文 |
| `range` | string | 位置范围（"起始-结束"） |
| `createTime` | number | 创建时间戳 |
| `colorStyle` | number | 颜色（0-4） |
| `reviewContent` | string | 笔记内容（非空表示有想法） |
| `isPopular` | boolean | 是否为热门划线 🔥 |
| `popularCount` | number | 热门人数 🔥 |
| `isUserHighlight` | boolean | 是否为自己的划线 🔥 |
| `deeplink` | string | App 跳转链接 |
| `abstract` | string | 引用原文（笔记项用） |

### 书评 `bookReview`

| 变量 | 类型 | 说明 |
|------|------|------|
| `bookReview.chapterReviews` | array | 各章节的笔记汇总 |
| `bookReview.bookReviews` | array | 书籍级点评 |
| `review.content` | string | 点评/笔记内容 |
| `review.abstract` | string | 引用的原文 |
| `review.createTime` | number | 创建时间戳 |
| `review.chapterName` | string | 所属章节名 |
| `review.type` | number | 1=划线想法, 4=章节点评, 6=书评 |

### 热门划线 `popularHighlights` 🔥

仅在 `syncPopularHighlightsToggle` 为 true 时存在：

| 变量 | 类型 | 说明 |
|------|------|------|
| `chapterUid` | number | 章节 UID |
| `chapterIdx` | number | 章节序号 |
| `chapterTitle` | string | 章节标题 |
| `highlights` | array | 该章节的热门划线列表（每条含 `markText`, `totalCount`, `range` 等） |

### 开关变量

| 变量 | 类型 | 说明 |
|------|------|------|
| `syncPopularHighlightsToggle` | boolean | 热门划线开关状态 |

### 可用过滤器

| 过滤器 | 参数 | 示例 |
|--------|------|------|
| `formatDate` | 时间戳 | `{{ createTime \| formatDate }}` → `2024-01-15` |
| `formatDateTime` | 时间戳 | `{{ createTime \| formatDateTime }}` → `2024-01-15 14:30` |
| `formatTime` | 时间戳 | `{{ createTime \| formatTime }}` → `14:30` |
| `split` | 分隔符 | `{{ range \| split('-') }}` → `["1277", "1599"]` |
| `replace` | 搜索, 替换 | `{{ text \| replace('/regex/', 'new') }}` |

### 模板条件示例

```nunjucks
{# 根据热门划线开关控制展示 #}
{% if syncPopularHighlightsToggle %}
  {% for chapter in popularHighlights %}
    ## {{ chapter.chapterTitle }}
    {% for item in chapter.highlights %}
      > {{ item.markText }}
      🔥 {{ item.totalCount }} 人划线
    {% endfor %}
  {% endfor %}
{% endif %}

{# 在划线中标注热门 #}
{% for highlight in chapter.highlights %}
  {% if highlight.isPopular and highlight.isUserHighlight %}
    📌🔥 {{ highlight.popularCount }} 人共读
  {% elif highlight.isPopular %}
    🔥 {{ highlight.popularCount }} 人共读
  {% else %}
    📌
  {% endif %}
  > {{ highlight.markText }}
{% endfor %}
```

---

## 常见问题

### Q: V2 一定要用 API Key 吗？

不必须。如果不配置 API Key，插件仍可使用 Cookie 方式（V1），行为与之前版本一致。但热门划线、公开书评、阅读统计等 V2 专有功能需要 API Key。

### Q: API Key 和 Cookie 可以共存吗？

可以。两者共存时，API 调用优先使用 API Key（V2），失败时自动回退到 Cookie（V1）。

### Q: API Key 会过期吗？

API Key 目前长期有效。插件会在每次打开设置页时自动校验，状态图标实时显示有效性。

### Q: 热门划线会重复同步吗？

不会。已同步到笔记的热门划线作为划线数据的一部分写入 Markdown 文件，每次同步会使用**缓存**（默认 7 天 TTL）避免重复请求 API。缓存过期后自动刷新。

### Q: 切换到不同主题需要重新同步吗？

需要。主题切换是即时生效的，但需要执行一次同步来按新模板重新生成笔记文件。

### Q: 公众号内容可以同步吗？

可以。设置中的「同步公众号内容」开关控制是否在书架上显示公众号文章和是否将其纳入同步范围。关闭后书架的类型筛选下拉框也会自动隐藏。

### Q: 如何实现移动端和桌面端同步？

如果你在不同设备上使用 Obsidian（如通过 iCloud / Obsidian Sync 同步 vault）：
- **桌面端**：可直接扫码获取 API Key，设置后自动同步到 vault
- **移动端**：vault 同步后 API Key 设置项会自动同步，无需重复配置

### Q: 从 V1 升级后原来的模板怎么办？

V1 的自定义模板会自动迁移为「旧模板」类型的主题，不会被覆盖。你可以继续使用或基于旧模板创建新的自定义主题。

---

## 相关文档

- [微信读书 Agent API 文档](./weread-agent-api.md) — V2 API 接口详细说明
- [V1 vs V2 API 接口对照](./weread-agent-api.md#v1-vs-v2-对比) — 接口迁移对照表
- [模板编辑器文档](./template-editor-window.md) — 模板编辑器使用说明
- [微信读书 API 文档](./weread-api.md) — V1 Cookie API 参考

---

**最后更新**：2026-06-12