下载微信公众号文章，保存为可阅读、可检索、可继续创作的本地资料；同一应用同时提供 GUI 与纯 JSON CLI。
wx-kit 是一个本地优先的微信公众号文章下载器：
- 粘贴一个或多个文章链接，下载为 Markdown、HTML、PDF、封面和元信息；
- 自动保存正文图片，默认同时下载文章内视频；
- 在本地文库中阅读、搜索、分组、删除和导出素材；
- 可把文库文章同步为 Astro 站点内容；
- GUI 适合日常使用，CLI 输出纯 JSON，适合 AI agent 和脚本调用。
当前能力边界（v0.9.0）
微信公众平台后台的私有文章列表链路已持续不可用。因此，“按公众号下载”、公众号订阅及其设置入口已从 GUI 隐藏；
search、crawl、login、auth-status、session、subscription、protectionCLI 命令保留名称但已停用，会返回稳定错误，不会发起网络请求。旧实现和本地数据仍保留，便于未来重新评估。按文章 URL 下载不依赖上述私有列表能力，仍是当前主功能。
以下截图来自 v0.9.0 正式界面，并由同一篇真实公众号文章完成下载、入库和阅读后生成。
| URL 下载与历史 | 本地文库 |
|---|---|
 |
 |
| Markdown 阅读器 | 有效设置 |
|---|---|
 |
 |
npm install
npm run dev
# CLI 下载一篇或多篇文章
npx electron . download \
--url "https://mp.weixin.qq.com/s/XXX" \
--formats md,html,meta默认文库位于 ~/Documents/wx-kit/，可在设置页修改。
brew install --cask monkeychen/wx-kit/wx-kit
xattr -cr /Applications/wx-kit.app未签名应用带 quarantine 时，Gatekeeper 可能连 CLI 一并拦截，因此安装后需要执行 xattr -cr。升级前先刷新本地配方：
brew update && brew upgrade --cask wx-kit
xattr -cr /Applications/wx-kit.app# 国内网络可先指定 Electron 镜像
export ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/
npm install -g @simiam/wx-kit
wx-kit --version官方 npm latest 已发布 v0.9.0；包名带 scope，但安装后的命令仍是 wx-kit。
前往 GitHub Releases 下载最新已发布版本 v0.9.0：
- Apple Silicon：
wx-kit-0.9.0-arm64.dmg - Intel Mac：
wx-kit-0.9.0.dmg - Windows：
wx-kit.Setup.0.9.0.exe
当前安装包未签名、未公证。macOS 首次打开时需在“系统设置 → 隐私与安全性”中允许，或执行上面的 xattr -cr；Windows 遇到 SmartScreen 时选择“更多信息 → 仍要运行”。
开发期在命令前使用 npx electron .；全局安装后直接使用 wx-kit。
| 目标 | 命令 |
|---|---|
| 下载文章 | wx-kit download --url <URL> [--url <URL> ...] [--formats md,html,pdf,meta] [--out <目录>] |
| 从文件批量下载 | wx-kit download --urls-file <文件> [--no-video] |
| 查看文库 | wx-kit library list |
| 搜索文库 | wx-kit library search <关键词> [--account <公众号>] |
| 导出创作素材 | wx-kit library export --ids <id,id> |
| 删除文章 | wx-kit library remove --ids <id,id> |
| 重建文库索引 | wx-kit library rebuild |
| 同步到 Astro 站点 | wx-kit site sync ... |
| 查看或修改有效设置 | wx-kit settings get [键] / wx-kit settings set <键> <值> |
| 检查更新 | wx-kit update --check |
| 查看版本或帮助 | wx-kit --version / wx-kit --help |
已停用但仍保留命令名：
search crawl login auth-status session subscription protection
这些命令统一返回 MP_BACKEND_UNAVAILABLE 和退出码 1。这是兼容性停用，不是命令拼写错误，也不会误开 GUI。
CLI 契约：stdout 只输出 JSON，stderr 输出进度；退出码 0 表示成功，1 表示业务失败，2 表示用法错误。完整参数和示例见 agent/wx-kit-skill/。
macOS 直接调用应用包内的可执行文件，不能使用 open -a，因为它不会可靠透传 stdout 和退出码：
/Applications/wx-kit.app/Contents/MacOS/wx-kit download \
--url "https://mp.weixin.qq.com/s/XXX" \
--formats md,meta \
--out ~/Documents/wx-kitWindows 默认路径：
& "$env:LOCALAPPDATA\Programs\wx-kit\wx-kit.exe" download --url "..." --formats md,meta --out . > result.json 2> progress.logElectron 在 Windows 是 GUI 子系统程序，stdout 不会回贴当前控制台；请重定向到文件，agent 集成优先使用 macOS 或 Linux。
- 支持普通图文、文字消息、视频消息、图片消息等当前已适配的页面类型；
- 图片和视频会在解析文章的同一次流程中本地化，带时效签名的媒体 URL 不写入文库；
--no-video可以关闭视频下载，适合控制流量和磁盘占用；- 未识别页面类型或媒体下载失败会写入
warnings，不会把可疑结果静默当成完全正常。
文库使用文件系统和 JSON 索引，不依赖数据库。library export 返回每篇文章的 contentPath，下游 agent 可以直接读取 Markdown 正文继续做分析或写作。GUI 也支持多选后“导出为素材”。
site sync 会把文库文章生成到 Astro 站点的 content/posts/<日期>-<slug>/ 中。目标目录已存在时不会覆盖，避免误伤已发布内容；wx-kit 只生成内容，不代替站点预览和发布。
Electron
├── Renderer：React GUI，只通过 preload 暴露的 API 调主进程
├── Main：IPC、CLI 分流、本地协议和 Electron 服务
├── CLI：Commander，stdout 为 JSON
└── Core：GUI 与 CLI 共用的解析、下载、文库和导出逻辑
electron/cli-dispatch.ts通过CLI_COMMANDS白名单判断是否进入 CLI；src/core/不依赖 React 或 renderer；src/renderer/不直接导入 core，只调用window.api；- 私有公众号后台实现目前保留在源码中，但产品入口与执行路径已停用。
npm test
npm run lint
npm run typecheck
npm run test:e2e
npm run test:e2e:live-download
npm run build本地 GUI e2e 覆盖当前有效界面与 fixture 下载闭环；test:e2e:live-download 使用隔离文库执行真实微信公众号文章 URL 的下载、历史、文库和阅读器验收。真实链路测试会访问微信，只在里程碑或发版验收时运行，不能用 fixture 结果代替。
- 最新已发布版本：v0.9.0；GitHub Release、brew tap 与 npm
@simiam/wx-kit三个渠道均已上线； - 当前没有正在实施的新版本，后续候选按真实需求单独立项；
- 完整里程碑、发布史与下一版候选统一维护在
ROADMAP.md，README 不再复制一份容易漂移的版本史。
需求、设计与开发约定分别见 docs/、ROADMAP.md 和 AGENTS.md。