企业官网建设流程全解析

• 知识管理
• 知识库

本文基于 docs/weread-v2-guide.md 与当前仓库源码（ApiRouter、ApiV2Manager、热门划线缓存 等）编写，系统讲解 obsidian-weread-plugin 的 V2 架构升级：以微信读书 Agent API Key 替代 Cookie 作为主要认证方式，并实现热门划线同步、书籍详情页、主题系统与阅读统计。读完本文，你将能够完成 V2 认证配置、理解 V2/V1 双模式路由的底层实现，并掌握自定义模板变量的全部用法。

一、V2 是什么：一次认证方式的架构升级

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

V2 使用微信读书 Agent API Key（格式：wrk-xxxxxxxx）进行认证，相比 Cookie 方式更加稳定：Cookie 会随登录态过期而失效，而 API Key 目前长期有效，插件在每次打开设置页时会自动校验其有效性。

V2 新增功能一览

二、快速开始：获取 API Key

桌面端（推荐）

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

从源码结构看，「扫码获取」的底层链路是 ApiRouter.fetchApiKey()：它在扫码登录（依赖 Cookie）的前提下调用 V1 管理器内部的fetchAndSaveApiKey()完成 Key 的获取与落盘，因此桌面端"已登录即可一键获取 Key"的本质是先有 Cookie 登录态，再换取长效的 API Key。

移动端

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

1. 访问微信读书网页版（weread.qq.com）
2. 登录后在浏览器地址栏打开路径/api/skills/apikeyGet
3. 复制返回的 API Key
4. 粘贴到设置页的 API Key 输入框中

三、API Key 管理

状态校验

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

实现上，ApiRouter.validateApiKey() 分两条路径：已配置 Key 时走 V2 的轻量校验（ApiV2Manager 发起一次/_list调用，以返回的errcode判定有效性）；未配置 Key 时则退化为校验 Cookie 是否有效。设置中用apiKeyValid: true / false / null三态存储，对应图标中的 ✓ / ✗ / ◌ 三档显示。

注销

已配置 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）

V1 / V2 共通功能

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

源码解析：双模式路由是如何实现的

ApiRouter 是双模式的总入口，其内部持有一个 V1 管理器（ApiManager）和一个 V2 管理器（ApiV2Manager），路由决策只取决于一件事——设置中是否存在wereadApiKey：

// src/api-router.ts private useV2(): boolean { const settings = get(settingsStore); return Boolean(settings.wereadApiKey); }

以getBook为例的回退模式：

// src/api-router.ts async getBook(bookId: string): Promise<BookDetailResponse | undefined> { if (this.useV2()) { try { const result = await this.v2Manager.getBook(bookId); if (result) return result as BookDetailResponse; } catch (e) { console.warn('V2 getBook 调用失败，回退到 V1', e); } } return this.v1Manager.getBook(bookId); }

两个值得注意的细节：

1. 失败即回退：V2 调用抛出异常（网络错误、Key 失效、接口errcode非 0）时，catch分支打印警告并静默落到 V1 Cookie 接口，用户无感知。
2. V2 专有接口不回退：getBestBookmarks（热门划线）与getPublicReviews（社区书评）在 V1 侧没有对应端点，useV2()为 false 或调用失败时直接返回undefined，这正是"热门划线需要 API Key"这一前提的代码依据（src/api-router.ts#L164-L173）。
3. 公众号强制走 V1：getNotebookHighlights、getNotebookReviews、getChapters都接收isArticle参数，当书籍为公众号类型（bookType === 3）时跳过 V2 直接使用 V1 Cookie 接口（src/api-router.ts#L54-L59），因为公众号数据依赖 Cookie 登录态。

V2 Agent API 的调用协议

ApiV2Manager 中所有 V2 请求都收敛到一个统一网关https://i.weread.qq.com/api/agent/gateway，采用 POST + Bearer Token 方式：

// src/api-v2.ts const req: RequestUrlParam = { url: this.gatewayUrl, method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${settings.wereadApiKey}` }, body: JSON.stringify({ api_name: apiName, // 如 '/book/info' skill_version: '1.0.3', ...params }) };

即：每个 V2 接口（/book/info、/book/bookmarklist、/book/bestbookmarks、/readdata/detail等）都不是独立的 HTTP 端点，而是通过api_name字段在同一个 Agent 网关上分发。从源码结构看，书架/笔记本列表的获取走的是/user/notebooks接口并自动分页（每页 300 本，见 src/api-v2.ts#L161-L187）；接口层的完整请求/响应字段说明可参考 docs/weread-agent-api.md 中的 V1 vs V2 对比表。

五、热门划线同步

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

启用

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

同步策略

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

源码解析：缓存优先 + 分批并发

同步主流程在 syncNotebooks.ts 中：只有当syncPopularHighlightsToggle为 true 时才会进入热门划线分支，随后调用私有方法getPopularHighlights()，其策略是"缓存命中即返回，未命中才发网络请求"：

// src/syncNotebooks.ts private async getPopularHighlights(bookId, chapters) { // 1. 尝试从缓存获取 const cached = await this.cacheManager.get(bookId); if (cached) { return this.groupPopularByChapter(cached.items, cached.chapters); } // 2. 缓存未命中，使用并发批量获取（每批 5 章） const chapterUids = chapters.map((c) => c.chapterUid); const popularByChapter = await this.apiManager.getBestBookmarksBatch(bookId, chapterUids, 5); // ... 3. 组装 items 4. 写入缓存 5. 按章节分组返回 }

其中getBestBookmarksBatch（src/api-router.ts#L181-L211）将章节 UID 按batchSize = 5切块，每块内用Promise.allSettled并发请求/book/bestbookmarks，单章失败只记录警告、不中断整本书的同步。

缓存层由 PopularHighlightsCacheManager 实现，要点：

• 每本书一个 JSON 文件，路径为.weread-cache/popular-{bookId}.json；
• 过期判定：Date.now() > cachedAt + TTL，TTL 读取设置项popularHighlightsCacheTtl（天数，默认 7）；
• 除了单本清除（clear），还提供clearExpired()批量清理过期缓存文件，避免.weread-cache/无限膨胀。

模板中的展示

在合并式模板中，热门划线与用户划线融合（合并逻辑见 src/syncNotebooks.ts#L239-L287，以划线range位置为匹配键）：

从源码看，合并规则是：已有划线与热门划线range相同，则就地打上isPopular = true、popularCount = match.totalCount并标记isUserHighlight = true（保留用户自己的笔记内容与创建时间）；热门划线中用户未划过的部分，则构造为isUserHighlight = false的新划线追加进章节，最后整个章节按range起始值重新排序，保证笔记中的段落顺序与原文一致。

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

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

使用指南（docs/weread-v2-guide.md）中描述了builtin_separated_with_popular主题：热门划线会在独立的「热门划线」区块中展示，以章节为分组，每段标注热度人数和 deeplink 链接。需要说明的是：从当前源码看，src/settings.ts 的BUILT_IN_THEMES数组目前注册了 3 个内置主题（合并式/分离式/官方笔记），该主题在规划文档 docs/superpowers/plans/2026-06-01-popular-highlights-plan.md 中作为计划任务描述，可推断属于规划中或随版本演进的条目。即便不启用该主题，模板变量popularHighlights也已进入渲染上下文，可在自定义模板中自行组织独立区块（见下文模板变量参考）。

缓存管理

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

六、书籍详情页

点击书架上的书籍封面或标题，会在新标签页打开书籍详情视图（实现位于 src/components/wereadBookDetailView.ts 与 wereadBookDetailModal.ts）。

四个标签页

1. 划线— 按章节分组展示所有个人划线
   • 每张卡片有颜色边线（黄/蓝/绿/红/紫），对应划线颜色
   • 显示创建时间、位置
   • 有笔记的划线显示 ✏️ 图标
   • 支持 deeplink 跳转到微信读书 App 和复制原文
2. 笔记— 所有个人想法和注解
   • 按时间倒序排列
   • 显示引用原文（abstract）和笔记内容
   • 支持换行等 Markdown 格式
3. 热门划线— 社区热度最高的划线（需 API Key）
   • 按章节分组展示
   • 显示🔥 N 人划线
   • 支持 deeplink 跳转
4. 书评— 两部分
   • 我的书评：个人对书籍的完整评价
   • 社区书评：公开的精选书评（最多 20 条），含用户头像、昵称、评分。从源码看，getPublicReviews向/review/list请求时传入count: 30作为拉取上限（src/api-v2.ts#L104-L110），详情视图再从中展示精选部分

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) — 我的划线、热门划线、笔记三个独立区块

从当前源码看，BUILT_IN_THEMES 数组注册了前三个主题（模板文件分别为 notebookTemplate.njk、separatedTemplate.njk、wereadOfficialTemplate.njk），第四个主题的规划见前文说明。当前活动主题由设置项activeThemeId指定，默认为builtin_merged。

主题管理器

在设置页点击「主题管理」进入管理界面（实现见 src/components/themeManagerModal.ts）：

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

模板编辑器

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

• 左侧：Nunjucks 模板语法参考文档（内容由 src/assets/templateInstructions.html 提供）
• 中间：模板源码编辑器
• 右侧：实时预览（300ms 防抖），使用示例数据渲染

特性：

• 自动去空白（trimBlocks）开关
• Markdown 渲染 / 源码视图切换
• 保存前验证模板语法——Renderer.validate() 会用空数据执行一次nunjucks.renderString试渲染，抛异常即判定语法不通过
• 关闭时未保存提醒

社区主题

支持导入他人分享的.json格式主题文件，也支持从 URL 远程导入。V1 的自定义模板自动迁移为「旧模板」类型，保持向后兼容。迁移逻辑在 settings.ts 中：加载设置时若themes为空，则将旧版template字段包装为id: user_{时间戳}、source: 'legacy'的「旧模板」主题并设为活动主题；渲染时 Renderer.render() 对source === 'legacy'的主题仍回退使用顶层settings.template，保证旧模板输出不变。

八、阅读统计

需要 API Key。从命令面板或书架页「阅读统计」按钮触发（文件生成逻辑见 src/syncReadingStats.ts，交互式视图见 src/components/wereadReadingStats.ts）。

同步统计文件

生成一份 Markdown 文件，包含：

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

设置中可指定：

• 统计文件存放位置— 默认 vault 根目录（readingStatsLocation，默认/）
• 起始年份— 热力图起始年（statsStartYear，默认 0 = 使用注册时间；源码注释明确0 = use registTime from API，见 src/settings.ts#L165）

数据来源于/readdata/detail接口，ApiV2Manager.getReadingStats() 会以mode（统计周期）加可选baseTime（周期锚点时间）为参数请求，支撑交互式视图的翻页能力。

交互式统计视图

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

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

九、书架增强

工具栏

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

操作按钮

• 同步— 全量同步；按住 Alt/Opt 点击为强制同步（忽略缓存）
• Web 阅读— 桌面端可用，打开微信读书网页版
• 阅读统计— 打开交互式统计视图
• 同步日志— 最近 10 次同步记录（对应 src/components/syncLogModal.ts 与设置中的syncLogs环形缓冲）
• 设置— 打开插件设置页

书籍卡片

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

十、全部设置项说明

以下默认值均已对照 src/settings.ts 的DEFAULT_SETTINGS核对。

登录与认证

同步设置

同步过滤

阅读

模板主题 🔥

定时同步

阅读统计 🔥

🔥 = V2 新增功能

十一、自定义模板变量参考

自定义模板可访问以下变量。渲染入口 Renderer.render() 将上下文对象{ metaData, chapterHighlights, bookReview, popularHighlights, syncPopularHighlightsToggle }传入 Nunjucks 环境，并依据当前活动主题的trimBlocks选项决定是否启用trimBlocks + lstripBlocks去空白渲染。

元数据metaData

章节划线chapterHighlights

数组，每个元素包含：

每条highlight包含：

书评bookReview

热门划线popularHighlights🔥

仅在syncPopularHighlightsToggle为 true 时存在：

开关变量

可用过滤器

以下过滤器在 src/renderer.ts#L6-L50 中注册，时间类过滤器底层基于 moment（时间戳为秒级）：

从源码结构看，replace过滤器对/.../形式的字符串参数会自动解析为正则表达式（末尾可带 flag），否则按普通字符串做全量替换；另有一个未在指南中列出的trim过滤器用于去除字符串首尾空白。

模板条件示例

{# 根据热门划线开关控制展示 #} {% 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 文档 — V2 API 接口详细说明
• V1 vs V2 API 接口对照 — 接口迁移对照表
• 模板编辑器文档 — 模板编辑器使用说明
• 微信读书 API 文档 — V1 Cookie API 参考

本文对应文档最后更新时间为 2026-06-12；涉及源码行为的描述以当前仓库快照为准。

• 知识管理
• 知识库