把微信公众号文章下载为多种格式并在应用内浏览；支持按公众号批量爬取； 同一二进制带 CLI，可被 AI agent 直接调用。单进程 Electron，GUI 与 CLI 双启动模式。
-ready-success.svg){kind=icon}
| 下载 · 按链接 | 下载 · 按公众号 | 文库 · 分组卡片 | 文库 · 列表 | 设置 |
|---|---|---|---|---|
 |
 |
 |
 |
 |
微信百宝箱是一个桌面工具:
- 下载任意微信文章为封面 / Markdown / 网页 / PDF / 元信息 5 种格式;
- 批量爬取某个公众号的历史文章(按数量或日期范围);
- 库内阅读已下载文章;
- 同二进制带 CLI(
npx electron . download ...),面向 AI agent 自动化调用。
v0.2.0 已落地(主题「下得放心、找得到、看得见」):
- 下得放心 —— 下载结果就地确认/阅读/复制下载项;失败归一为人话话术+下一步,频控退避有朱砂横幅+倒数;取消要二次确认,未下载的文章进历史可单篇补下。
- 找得到 —— 文库可按下载/发布时间排序、按公众号筛选与分组折叠,批量选择+批量删除(只删记录不删文件)。
- 看得见 —— 卡片⇄列表(访达式)两视图随切,分组时列头只一次;PDF 导出不跨页切图。
- 🖥 GUI + CLI 双启动 —— 同一份 Electron 二进制,带子命令即进 CLI,否则开窗口。
- 📦 多格式导出 —— 封面、Markdown、HTML、PDF、元信息,可任意组合。
- 🔁 断点续传 + 去重 —— 每篇落盘即写索引,中断/重跑自动跳过。
- 🛡 节流 + 退避 —— 批量爬取默认串行 + 随机延迟,命中频控自动退避,不裸报错。
- 💻 单进程单语言 —— 纯 Node + Electron 31,无 Python 边车、无独立 chromium、无数据库(文件系统 + JSON 索引)。
- 🤖 Agent 友好 —— 同一 CLI 输出纯 JSON,
stdout走数据、stderr走进度、退出码0/1/2。
# 1. 装依赖
npm install
# 2. 跑 GUI(开发模式)
npm run dev
# 3. 跑 CLI 试一下
npx electron . download --url "https://mp.weixin.qq.com/s/xxx" --formats md,html,meta输出在 ~/Documents/wx-kit/(默认库根,可在「设置」改)。
去 Releases 选平台对应包(当前可用的 v0.1.0:wx-kit-0.1.0-arm64.dmg(Apple Silicon) /
wx-kit-0.1.0.dmg(Intel) / wx-kit Setup 0.1.0.exe(Windows);v0.2.0 包待发布)。当前未签名,首次打开需手动放行:
- macOS —— 右键应用 →「打开」→ 再次「打开」;或
xattr -cr /Applications/wx-kit.app。 - Windows —— SmartScreen →「更多信息」→「仍要运行」。
┌─────────────────────────────────────────────┐
│ Electron (单进程) │
│ ┌────────────┐ ┌──────────────────────┐ │
│ │ Renderer │◄─┤ IPC (preload 桥) │ │
│ │ React UI │ │ main process │ │
│ └────────────┘ │ services/* │ │
│ │ ipc / wxfile proto │ │
│ └─────────┬────────────┘ │
│ │ │
│ 同一二进制带 CLI ────────┤ │
│ ┌────────────┐ ┌─────────▼────────────┐ │
│ │ CLI │──│ src/core/ (纯逻辑) │ │
│ │ commander │ │ - parse / export │ │
│ └────────────┘ │ - library / queue │ │
│ │ - mp-auth / crawl │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────┘
src/core/—— UI 无关纯逻辑,被 GUI 与 CLI 共享。绝不 import electron/renderer。electron/—— 主进程,IPC 处理器做薄委派,mp-*服务对接微信后台。src/cli/—— 同二进制,src/renderer/缺失时即 CLI 模式(详见AGENTS.md)。
完整需求见 docs/PRD.md;当前进度见 ROADMAP.md;开发指南(决策/不变量/陷阱)见 AGENTS.md。
| 场景 | 命令 |
|---|---|
| 开发(GUI 热更) | npm run dev |
| 类型检查 | npm run typecheck |
| 单测 | npm test |
| 单测(监听) | npm run test:watch |
| Lint | npm run lint |
| GUI 端到端(Playwright) | npm run test:e2e |
| 出 mac 安装包 | npm run package:mac |
| 出 win 安装包 | npm run package:win |
| 一次性出 mac+win | npm run package |
| 进入 CLI 模式 | npx electron . <子命令> |
npx electron . download --url <u> [--formats md,html,pdf,meta] [--out <dir>]
npx electron . login # 扫码登录公众号后台
npx electron . auth-status # 查登录态(真探测)
npx electron . search <公众号名> # 搜号,返候选
npx electron . crawl <公众号名> --count 2 # 批量爬取
npx electron . library list # 列已下文章退出码:0 成功、1 业务失败、2 用法或鉴权错误。详见 docs/PRD.md §F4。
v0.1.0 已发布、v0.2.0 功能完成待打 0.2.0 安装包。各里程碑均合入 main,端到端在真实微信公众号后台验证通过:
v0.1.0 · 第一阶段主线
- ✅ M1 — 核心层 + CLI
download五格式 - ✅ M2 — GUI:下载页 / 书架 / 阅读器 / 设置
- ✅ M3 — 扫码登录 + 批量爬取(CLI)
- ✅ M3.5 — 批量爬取 GUI 页(单页渐进:登录引导 → 搜号 → 实时逐篇)
- ✅ M4 — electron-builder 打包:未签名 mac(dmg arm64+x64)+ win(nsis x64)
v0.2.0 · 下得放心、找得到、看得见
- ✅ M5 — 信息架构重构:导航三项(下载/文库/设置)+「下载」页双模式(URL/公众号)+「书架」→「文库」改名
- ✅ M6 — 下载闭环 + 历史:结果区就地确认/阅读(R1)+ 下载历史
history.json(R2) - ✅ M7 — 反馈引导:频控退避可见 + 失败话术归一(R5);取消需二次确认,未下载文章进历史可单篇补下
- ✅ M8 — PDF 保真:导出 PDF 不跨页切图(R4)
- ✅ M9 — 文库组织:排序 / 按公众号筛选+分组 / 批量删除(R6)+ 卡片⇄列表(访达式)视图切换
详见 ROADMAP.md 与 docs/devlog/wx-kit-vibe-coding.md(逐里程碑的决策/踩坑/方法论)。
欢迎 PR!具体流程见 CONTRIBUTING.md ——
跑 npm test / npm run typecheck / npm run lint 全部通过再提。
行为准则见 CODE_OF_CONDUCT.md。
安全漏洞请不要公开提 issue,按 SECURITY.md 私下报告。
Apache License 2.0 — 见文件正文。Copyright 2026 monkeychen。
- 设计脱胎于技术探索原型
../trae/x-downloader,感谢那段 PyQt 时代留下的判断。 - 用了
playwright做 e2e 与图标渲染、electron-builder](https://www.electron.build) 出安装包。