知识管理知识库【免费下载链接】obsidian-weread-pluginObsidian Weread Plugin is a plugin to sync Weread(微信读书) hightlights and annotations into your Obsidian Vault.项目地址https://gitcode.com/gh_mirrors/ob/obsidian-weread-plugin点击查看免费下载本文基于 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每本书 TOP 20 热门划线写入本地笔记书籍详情页API Key社区书评比划线/笔记/热门划线/书评四个标签页主题系统无多主题并存、一键切换、模板编辑器阅读统计API KeyMarkdown 统计文件 交互式可视化视图书架增强无搜索、类型/状态筛选、同步日志二、快速开始获取 API Key桌面端推荐打开设置页书架页右上角 ⚙️ 图标找到「API Key」输入框点击「扫码获取」按钮已登录自动从微信读书网页版获取并填入 Key未登录弹出二维码窗口用微信扫描完成登录后自动获取获取成功后输入框旁显示 ✓ 绿色图标表示 Key 有效从源码结构看「扫码获取」的底层链路是 ApiRouter.fetchApiKey()它在扫码登录依赖 Cookie的前提下调用 V1 管理器内部的fetchAndSaveApiKey()完成 Key 的获取与落盘因此桌面端已登录即可一键获取 Key的本质是先有 Cookie 登录态再换取长效的 API Key。移动端移动端无法使用扫码登录需要 Electron需手动获取访问微信读书网页版weread.qq.com登录后在浏览器地址栏打开路径/api/skills/apikeyGet复制返回的 API Key粘贴到设置页的 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 APIV2 专有功能需要 API Key功能V2 API 接口说明热门划线/book/bestbookmarks每本书 TOP 20 热门划线公开书评/review/list书籍的社区公开点评书架同步/shelf/sync完整书架数据含有声书阅读统计/readdata/detail详细阅读统计和偏好分析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): PromiseBookDetailResponse | 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); }两个值得注意的细节失败即回退V2 调用抛出异常网络错误、Key 失效、接口errcode非 0时catch分支打印警告并静默落到 V1 Cookie 接口用户无感知。V2 专有接口不回退getBestBookmarks热门划线与getPublicReviews社区书评在 V1 侧没有对应端点useV2()为 false 或调用失败时直接返回undefined这正是热门划线需要 API Key这一前提的代码依据src/api-router.ts#L164-L173。公众号强制走 V1getNotebookHighlights、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 支持将这些内容同步到本地笔记。启用确保已配置有效的 API Key在设置页开启「同步热门划线」开关执行同步手动或定时热门划线将写入笔记文件同步策略每本书最多 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. 按章节分组返回 }其中getBestBookmarksBatchsrc/api-router.ts#L181-L211将章节 UID 按batchSize 5切块每块内用Promise.allSettled并发请求/book/bestbookmarks单章失败只记录警告、不中断整本书的同步。缓存层由 PopularHighlightsCacheManager 实现要点每本书一个 JSON 文件路径为.weread-cache/popular-{bookId}.json过期判定Date.now() cachedAt TTLTTL 读取设置项popularHighlightsCacheTtl天数默认 7除了单本清除clear还提供clearExpired()批量清理过期缓存文件避免.weread-cache/无限膨胀。模板中的展示在合并式模板中热门划线与用户划线融合合并逻辑见 src/syncNotebooks.ts#L239-L287以划线range位置为匹配键场景标记说明自己划了 是热门N 人共读保留自己的 reviewContent 和 createTime仅热门自己没划N 人共读追加到对应章节中按位置排序仅自己划线不热门与 V1 行为一致从源码看合并规则是已有划线与热门划线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。四个标签页划线— 按章节分组展示所有个人划线每张卡片有颜色边线黄/蓝/绿/红/紫对应划线颜色显示创建时间、位置有笔记的划线显示 ✏️ 图标支持 deeplink 跳转到微信读书 App 和复制原文笔记— 所有个人想法和注解按时间倒序排列显示引用原文abstract和笔记内容支持换行等 Markdown 格式热门划线— 社区热度最高的划线需 API Key按章节分组展示显示 N 人划线支持 deeplink 跳转书评— 两部分我的书评个人对书籍的完整评价社区书评公开的精选书评最多 20 条含用户头像、昵称、评分。从源码看getPublicReviews向/review/list请求时传入count: 30作为拉取上限src/api-v2.ts#L104-L110详情视图再从中展示精选部分Header 区域书籍封面、标题、作者阅读进度、阅读时长、最后阅读日期分类、出版社、字数、出版时间简介长文本可折叠展开操作按钮阅读— 快速打开微信读书网页版或 App根据设置刷新— 重新获取书籍数据并同步本地笔记返回笔记— 右下角悬浮按钮点击打开本地 Markdown 笔记UI 特性新标签页打开不覆盖书架页支持原生 Tab 切换响应式布局移动端适配768px / 480px 断点Tab 栏吸顶效果sticky滚动时保持可见悬浮按钮在移动端放大52px便于触控七、主题系统与模板编辑器V2 用主题系统替代了原先的单一模板设置支持多个主题并存和一键切换。内置主题使用指南列出 4 个内置主题合并式模板(builtin_merged) — 划线和笔记内联展示热门划线合并到章节分离式模板(builtin_separated) — 划线在前笔记汇总在后微信官方笔记主题(builtin_official) — 微信读书官方风格含详细元数据分离式含热门划线(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 文件包含历年总览— 总阅读时长、阅读天数、读完数、各年阅读时长分布当年阅读概况— 月度时长柱状图文本、阅读 TOP 书籍、分类偏好、作者偏好当月阅读概况— 每日时长柱状图、阅读 TOP 书籍、分类偏好阅读偏好分析— 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核对。登录与认证设置默认值说明登录方式扫码登录扫码登录或CookieCloudCookieCloud 配置—服务器地址、UUID、密码API Key空格式wrk-xxxxxxxx用于 V2 Agent API注销—清除 API Key 和 Cookie同步设置设置默认值说明笔记保存位置/vault 根目录文件夹分类不分类不分类/按书名/按分类文件名格式书名书名/书籍ID/书名-作者/书名-ID书名去括号关闭去除书名中的()及其内容书名去括号白名单空含关键词的书名不去括号过滤[图片]占位符关闭移除划线中的图片/插图提示划线加标签关闭#tag转为[[tag]]去掉空白行关闭渲染后去除多余空格同步公众号内容开启关闭后书架不显示公众号同步阅读信息到 frontmatter开启写入元数据到 YAML frontmatter同步热门划线关闭同步每本书 TOP 20 热门划线需 API Key热门划线缓存 TTL7 天缓存有效期同步过滤设置默认值说明笔记最小数量-1不限低于此数量的书不同步过滤模式黑名单黑名单/白名单黑名单/白名单空逗号分隔的书籍 ID同步天数过滤不限仅同步最近 N 天更新的书阅读设置默认值说明阅读打开方式标签页打开网页时使用标签页或窗口书籍链接方式网页版点击书籍网页版或App deeplinkApp 阅读跳转方式TAB使用 TAB 或 WINDOW 打开模板主题 设置默认值说明活动主题合并式模板当前使用的同步模板主题管理—打开主题管理器定时同步设置默认值说明启用定时同步关闭每隔 N 分钟自动同步同步间隔5 分钟最小 1 分钟阅读统计 设置默认值说明统计文件位置/vault 根目录起始年份0热力图起始年0 使用注册时间 V2 新增功能十一、自定义模板变量参考自定义模板可访问以下变量。渲染入口 Renderer.render() 将上下文对象{ metaData, chapterHighlights, bookReview, popularHighlights, syncPopularHighlightsToggle }传入 Nunjucks 环境并依据当前活动主题的trimBlocks选项决定是否启用trimBlocks lstripBlocks去空白渲染。元数据metaData变量类型说明metaData.bookIdstring书籍 IDmetaData.titlestring书名metaData.authorstring作者metaData.coverstring封面图片 URLmetaData.urlstring网页版链接metaData.pcUrlstringPC 版链接metaData.noteCountnumber划线总数metaData.reviewCountnumber笔记总数metaData.isbnstringISBN可能为空metaData.categorystring分类metaData.publisherstring出版社metaData.introstring简介metaData.totalWordsnumber总字数metaData.lastReadDatestring最后阅读日期metaData.ratingnumber评分metaData.readInfoobject阅读信息状态、进度、时长等章节划线chapterHighlights数组每个元素包含变量类型说明chapterUidnumber章节 UIDchapterIdxnumber章节序号chapterTitlestring章节标题levelnumber标题层级1/2/3highlightsarray该章节的划线列表popularHighlightsarray该章节的热门划线 已废弃见下方chapterReviewsarray该章节的笔记列表每条highlight包含变量类型说明bookmarkIdstring划线 IDmarkTextstring划线原文rangestring位置范围起始-结束createTimenumber创建时间戳colorStylenumber颜色0-4reviewContentstring笔记内容非空表示有想法isPopularboolean是否为热门划线 popularCountnumber热门人数 isUserHighlightboolean是否为自己的划线 deeplinkstringApp 跳转链接abstractstring引用原文笔记项用书评bookReview变量类型说明bookReview.chapterReviewsarray各章节的笔记汇总bookReview.bookReviewsarray书籍级点评review.contentstring点评/笔记内容review.abstractstring引用的原文review.createTimenumber创建时间戳review.chapterNamestring所属章节名review.typenumber1划线想法, 4章节点评, 6书评热门划线popularHighlights仅在syncPopularHighlightsToggle为 true 时存在变量类型说明chapterUidnumber章节 UIDchapterIdxnumber章节序号chapterTitlestring章节标题highlightsarray该章节的热门划线列表每条含markText,totalCount,range等开关变量变量类型说明syncPopularHighlightsToggleboolean热门划线开关状态可用过滤器以下过滤器在 src/renderer.ts#L6-L50 中注册时间类过滤器底层基于 moment时间戳为秒级过滤器参数示例formatDate时间戳{{ createTime \| formatDate }}→2024-01-15formatDateTime时间戳{{ createTime \| formatDateTime }}→2024-01-15 14:30formatTime时间戳{{ createTime \| formatTime }}→14:30split分隔符{{ range \| split(-) }}→[1277, 1599]replace搜索, 替换{{ text \| replace(/regex/, new) }}从源码结构看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 KeyV2失败时自动回退到 CookieV1。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涉及源码行为的描述以当前仓库快照为准。赞分享知识管理知识库【免费下载链接】obsidian-weread-pluginObsidian Weread Plugin is a plugin to sync Weread(微信读书) hightlights and annotations into your Obsidian Vault.项目地址https://gitcode.com/gh_mirrors/ob/obsidian-weread-plugin点击查看免费下载相关推荐Obsidian Weread Plugin将微信读书划线、笔记与热门划线同步到 Obsidian 的实践指南Obsidian Weread Plugin将微信读书划线、笔记与热门划线同步到 Obsidian 的实践指南 Obsidian Weread Plugin知识管理知识库obsidian-weread-plugin 热门划线同步从设计文档到源码落地的缓存、并发与模板实践obsidian weread plugin 热门划线同步从设计文档到源码落地的缓存、并发与模板实践 本文以仓库中的设计文档 2026 06 01 popul知识管理知识库obsidian-weread-plugin 模板编辑器窗口三栏布局、Nunjucks 实时预览与主题系统集成obsidian weread plugin 模板编辑器窗口三栏布局、Nunjucks 实时预览与主题系统集成 本文基于仓库设计文档 template edi知识管理知识库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考