WeChat Reader

中文说明 | English

Obsidian 桌面 RSS 阅读器：在右侧栏管理普通 RSS、Atom 和微信公众号，在原生弹窗中阅读、切换、收藏与归档。界面直接使用 Obsidian 主题变量，自动跟随深色、浅色主题。

首次安装前请注意

普通 RSS/Atom 安装即用，不需要公众号引擎。公众号引擎由用户主动选择安装，插件启动或普通刷新不会自动下载。

1.1.0 新增插件内安装入口。旧版 1.0.0 没有此按钮，请先更新插件，或使用完整 ZIP 手动安装。

引擎安装入口在“设置 → RSS 阅读 → 公众号引擎（可选）”和侧栏更多菜单。确认前展示 GitHub 来源、固定版本、约 45.5 MiB 下载量及安装位置；确认后校验 SHA-256、解压并验证随包 Node。支持取消、失败重试和重新安装修复。安装不自动开启公众号功能，完成后需开启并扫码登录。当前仅支持 macOS Apple Silicon（M 系列芯片），无需另装 Node/Python。

安装包固定为已发布的 1.0.0 完整包，仅提取引擎和许可，不覆盖用户设置、缓存或标准插件。安装使用本库插件目录下的 wechat-engine-<随机标识>/，wechat-engine.json 记录当前选择；兼容原有 engine/ 手动安装。成功切换后，正在运行的共享采集实例继续原任务，下次新启动使用新安装。旧版本目录保留，以保护可能仍运行的进程；重新安装会额外占用约 150 MiB，请避免反复安装。

用户主动下载可执行依赖是否符合社区目录政策，尚未获得官方确认；本实现不代表已经通过审核。

安装和使用

1. 先在社区插件页面安装（目录中可用时），或手动将 main.js、manifest.json、styles.css 放入笔记库配置目录的 plugins/wechat-reader/。普通 RSS/Atom 可直接使用；公众号用户在设置中点击“安装公众号引擎”并确认下载，安装后启用公众号并扫码。也可从 1.2.0 发布页 下载 wechat-reader-1.2.0-macos-arm64.zip，解压后复制完整 wechat-reader/（含 engine/）到插件目录；不要下载 Source code 源码包。覆盖安装时保留 data.json 和 cache/。默认配置目录为 .obsidian，自定义配置目录请使用实际路径。
2. 点击 RSS 图标或执行“打开 RSS 阅读侧栏”。首次安装和一期升级默认停靠右侧栏，后续保留用户拖动的布局。
3. 点击 + 添加 RSS/Atom XML 地址。菜单支持 OPML 导入预览和导出；重复 URL 保留原源，同名源可分别放在不同分组。右键源可以修改名称、分组、刷新周期或停止自动刷新；历史缓存和阅读状态保留。
4. 点击文章打开原生阅读弹窗。← / → 切换前后文章，↑ / ↓ 滚动正文，Esc 关闭；输入框、输入法和其他弹窗不受影响。打开时冻结当前已展示的文章队列，标记已读后不会跳篇，首尾不循环。
5. 顶部“全部文章 / 未读 / 已读 / 收藏”直接展示跨来源文章，按发布时间倒序排列，文章注明来源；展开“订阅源”可切换到单个来源。每个列表默认显示 50 篇，底部“加载更多”每次追加 50 篇，数量统计全部匹配文章；切换入口保留本次视图内的加载条数和滚动位置。打开正文、摘要或失败提示后自动已读；后台预取和采集失败不会自行标记。文章、订阅源和分组右键支持标记为已读，右上角可全部标为已读并撤销；“全部文章”和“已读”不显示数字。已读、收藏、归档关联仅属于当前笔记库。
6. 弹窗内“保存为 MD”将正文和本地图片保存至设置目录，不切走阅读弹窗；重复保存保留原笔记及用户编辑。正文版本更新时可确认另存副本。“复制文章”复制清理后的 Markdown 和原文链接，图片使用公开地址或文字占位，不复制本机凭据。

更新方式与原因

Obsidian 标准更新只下载 main.js、manifest.json 和可选的 styles.css，不会解压完整包中的引擎。参见 官方发布说明。

• 普通 RSS/Atom 和仅改界面的版本，通常只需标准插件更新。
• 1.1.0 提供独立的引擎安装入口。插件不查询 latest、不在后台下载，不自动更新自身或引擎；按钮始终安装插件代码中固定的兼容版本。
• 当后续插件版本指定新引擎时，用户需再次确认安装。现阶段仅提供固定 1.0.0 引擎的安装、修复，不检测其他未来版本。
• 手动完整包安装仍可使用。替换正在使用的旧 engine/ 前应关闭所有相关笔记库，等待采集结束和程序退出。保留 data.json、cache/ 和归档文件。同机多个库使用公众号时，应统一更新，避免运行不兼容版本。

独立采集程序提供固定 Node、共享 SQLite 与队列，使普通 RSS 无需依赖公众号运行环境。用户点击安装的目的是减少跳转 GitHub 和手动解压的步骤；离线或下载失败时仍可手动安装完整包。

订阅配置

阅读器“订阅源”标题旁和插件设置中的“管理订阅”打开同一个管理窗口。支持按名称、分组、链接搜索，以及“全部 / 订阅中 / 已暂停”筛选。点击来源名称展开完整只读链接和刷新间隔；公众号链接明确标为“恢复用原文链接”。每行“设置”可修改名称、分组与刷新配置，“更多”支持暂停/恢复自动更新、立即刷新、移除订阅。窗口顶部提供添加订阅，以及 JSON、OPML 导入和 JSON 导出。

“暂停自动更新”保留来源入口；“移除订阅”确认后从当前库列表隐藏，历史文章、已读收藏、归档笔记与缓存保留，重新添加相同来源可恢复入口。移除公众号同时停止本机共享采集，其他库也会停止自动更新；本库移除标记不会被共享快照覆盖。清理下载内容仍由独立的缓存管理执行。

• “导出订阅配置”将统一 JSON 文件保存到笔记库根目录，包括名称、地址、分组、开关、刷新间隔及公众号恢复定义；不导出登录凭据、文章缓存或阅读记录。私有 RSS 地址中的必要查询参数会保留，请自行保管导出文件。
• “导入订阅配置”选择本插件导出的 JSON，先预览再确认。按 RSS 地址和公众号身份去重，保留已有订阅设置，仅补齐缺失恢复信息；无效文件整份拒绝，保存失败回滚，不产生部分导入。
• 配置导入不要求联网验证。普通 RSS 按计划刷新；公众号需启用功能并在本机扫码后自动恢复。只有名称的旧公众号仍需补充原文链接。
• 侧栏原有 OPML 导入导出继续保留，适用于普通 RSS/Atom。

微信公众号

普通 RSS 无需开启公众号功能、登录微信或运行采集程序。在侧栏菜单扫码登录微信读书，添加公众号时粘贴文章链接，解析真实身份并确认显示名称。

• 公众号能力使用独立 TypeScript/Node 运行时，随包携带 Node，无需用户安装 Node 或 Python。只有启用公众号能力才连接或启动。
• 首轮最多 10 篇，后续自动同步仅检查近期文章，最多 30 篇，不再自动回补历史；正文请求间隔 5 秒，全局串行，多个笔记库共享一份 SQLite 和采集队列。旧历史游标保留，右键公众号选择“获取更多历史文章”可手动获取一页（最多 10 篇）。
• 浏览器兜底使用本机 Chrome 或 Edge。访问限制、失效授权需要在手机处理或重新扫码；失败和永久不可用条目不算正文成功。
• 右键公众号可复制本机持续 RSS 订阅地址。固定专用回环端口和源级只读令牌与管理密钥隔离；需要本机采集程序运行，不提供公网订阅或退出 Obsidian 后的后台守护。
• 默认省电模式：插件以轻量计时器等待到期，再启动服务，任务完成后空闲约 15 秒释放租约；无其他库、任务或扫码需求时服务退出。侧栏不做空闲网络轮询。Obsidian 关闭或睡眠期间不采集，恢复后每个过期源最多补一轮。
• 设置中可切换常驻模式，以供其他阅读器持续读取本机 RSS 地址；省电模式下此地址只在服务运行时可访问。
• 刷新设置使用小时：普通 RSS 新订阅默认 1 小时，新公众号默认随机 2～3 小时，已有间隔保持原值。
• 阅读弹窗默认宽度为 720px，可在设置“阅读弹窗宽度”中调整为 480～1000px；左右正文边距 28px，小窗口限制在视口内。

数据与一期迁移

• 普通 RSS 缓存位于当前库 .obsidian/plugins/wechat-reader/cache/，按源分片，图片按文章隔离；条件请求、失败退避和增量合并保留历史。
• 点击全部已读会记录本库时间基准，此后发现的基准之前发布的公众号文章默认已读；手动未读优先，发布时间未知的文章仍为未读。撤销同时恢复旧基准。
• 设置中的“公众号缓存管理”先按 UTC 日期预览，再由用户确认清理共享正文和图片；保留索引、阅读状态和归档笔记。已登记的其他笔记库必须关闭并可访问，库根目录下配置目录中的收藏和归档文章会被排除；未登记或无法检测的笔记库无法自动核对，请勿清理其依赖的数据。清理影响其他库与本机 RSS 的共享离线正文；可重新获取，不保证远端仍可用。本库已缓存正文继续可读。
• 公众号索引和计划通过私有 runtime/schedule.json 快照恢复，浏览过的正文和图片缓存在当前库 cache/，缓存完整时不启动服务。首次补读或内容更新时短暂连接；服务故障时可继续读取已有正文。
• 当前库 data.json 保存订阅配置、阅读状态和笔记关联，不保存公众号凭据或管理密钥。私有 RSS 地址可能含订阅者自己的查询令牌，请自行决定是否同步配置。
• 公众号共享数据仍位于 ~/Library/Application Support/Obsidian WeChat Reader/：SQLite、版本化正文图片、私有 data/credentials/、运行发现文件。
• 公众号的可迁移定义保存在本库 data.json 的 wechatFeeds[].wechat：稳定身份、公开原文链接、显示名称、暂停/订阅状态和刷新间隔。新电脑同步插件配置后，重新扫码即可自动恢复信息完整的订阅，无需复制登录凭据。后台仅重建缺失账户，不覆盖本机其他库已有账户的设置。
• 已有共享采集记录会自动补齐定义；旧缓存中有可靠身份时也会补齐。只有名称和内部 ID 的旧条目，需要右键“补充恢复链接”填写一次任意原文，并校验属于同一公众号；此后可随配置迁移。也可在更多菜单中选择“恢复本库公众号订阅”重试。
• 新电脑恢复后会重新拉取近期文章，阅读、收藏和归档关联保留；完整历史文章并不会仅靠订阅定义自动迁移。如需保留所有旧正文和图片，可在停用两端插件后迁移旧电脑整个 ~/Library/Application Support/Obsidian WeChat Reader/ 目录。微信登录凭据始终留在本机私有目录，不写入订阅配置。
• 首次 TS 接管前生成 SQLite 和凭据回退快照；沿用原文章 ID、URL 别名、账号池格式和正文目录，保留已读、收藏、归档及用户编辑。不能让旧 Python 进程与新 TS 进程同时写入共享目录。
• companion/ 保留一期历史实现和 MIT 上游来源，当前构建、运行、安装包不调用 Python；离线签名对照样例有固定测试覆盖。

许可与运行说明

本插件采用 MIT License。旧版采集实现参考并保留 wechat-mp-tools 的 MIT 许可；第三方运行依赖的许可随完整包附带。

普通 RSS/Atom 会联网访问用户填写的源和文章图片地址。公众号功能需要微信读书账号，会访问微信/微信读书服务以扫码、查询公众号和下载正文，必要时使用本机 Chrome 或 Edge。插件会读写笔记库之外的本机共享目录，保存凭据、文章与采集进度，位置详见下文。不包含遥测、广告或付费功能。仅用户明确点击确认后从 GitHub 下载公众号引擎，不在启动时自动安装，也不自动更新自身或依赖。

完整包目前仅适用于 macOS Apple Silicon。仅安装标准 main.js、manifest.json、styles.css 时可使用普通 RSS/Atom；公众号功能可在 1.1.0 的设置中主动安装引擎，也可手动复制完整包中的 engine/；没有引擎时会提示安装，只有确认下载后才访问 GitHub。

开发与验证

开发需要 Node 26+（使用原生 node:sqlite）；安装用户无需额外安装运行时。

npm ci
npm test
npm run test:companion
npm run build
npm run package:companion
npm run test:package
WECHAT_READER_TEST_VAULT="/你的测试笔记库路径" npm run deploy:test

test:companion 使用临时目录和网络夹具，不读取真实授权。test:legacy 仅供一期历史回归，需要单独 Python 虚拟环境。当前包针对 macOS Apple Silicon；移动端、本机之外的 RSS 服务、LaunchAgent、完整历史回补不在本次范围。当前版本号为 1.2.0，内核通过 engineVersion: ts-1 与旧实例区分，并要求 power-save、portable-subscriptions、bounded-history 和 cache-cleanup 能力；1.2.0 的公众号功能可通过设置安装固定 1.0.0 引擎，或手动安装 1.2.0 完整包中的 engine/。

安装和回归结果见 VALIDATION.md。私有发现文件、二维码、Cookie、Token 不得复制到日志、报告或 Git。

公众号图片存储

公众号正文保存在本地，图片在阅读时直接从微信 HTTPS 图片 CDN 加载，不再批量保存到共享存储。主动归档时才下载为笔记库附件。旧图片清理工具默认仅预览，操作前需停止采集程序。详见 方案说明。