wechat-article-exporter

本地优先的微信公众号文章归档工具，提供 Web UI、CLI 与 AI Agent 接口。

本项目基于 wechat-article/wechat-article-exporter 进行二次开发，在原有公众号搜索、文章下载和多格式导出能力之上，增加了本地 CLI、Agent harness、多登录账号池、页面凭证池、持久化任务、SQLite 统一归档，以及 Markdown、OCR、分类和快照处理流水线。

Important

本仓库是由 BigZig233 独立维护的衍生版本，不代表上游项目。上游在线站点、文档、交流群和商业服务不属于本仓库；上游文档也不一定适用于这里新增的 CLI 与处理流程。

功能

搜索、关注并同步微信公众号及历史文章元数据
同步公开合集，按账号、合集、日期、关键词和产物状态筛选文章
下载原始 HTML，并将图片等资源本地化
导出 HTML、Markdown、TXT、JSON、XLSX、DOCX 和 SQLite
获取阅读量、点赞、转发、评论和回复（需要有效的页面凭证）
管理多个公众号后台登录，支持加权/轮询调度、限流冷却和故障转移
运行 Markdown、封面、OCR、活动分类、移动端快照等显式处理步骤
使用持久化 Job、事件日志和锁恢复长时间批处理任务
通过同一套 TypeScript core 服务 Web UI、wxa CLI 和 Agent harness

架构

flowchart LR
  Agent["AI Agent"] --> Harness["Python Agent harness"]
  Shell["Shell / 自动化脚本"] --> CLI["wxa CLI"]
  Harness --> CLI
  CLI --> Core["共享 TypeScript core"]
  UI["Nuxt Web UI"] --> Core
  Core --> DB["SQLite"]
  Core --> Files["HTML / Markdown / 图片 / OCR / 导出"]
  Core --> Jobs["Jobs / Events / Locks"]
  Core --> Profiles["后台 Profile 池"]
  Core --> Credentials["页面 Credential 池"]

Web UI 和 CLI 直接复用同一套业务核心、数据库与文件目录，不通过互相调用子进程来同步状态。SQLite 是业务数据源；浏览器中的旧 Dexie 数据只作为一次性的元数据迁移来源。

快速开始

环境要求

Node.js 22 或更高版本
Yarn 1.22（通过 Corepack 安装）
Chromium 或 Chrome（登录、页面处理和快照需要）
Python 3.10 或更高版本（Agent harness、分类和 OCR 需要）
Docker（可选）

安装与构建

corepack enable
corepack prepare yarn@1.22.22 --activate
yarn install --frozen-lockfile
yarn build
yarn cli:build

设置一个绝对数据目录并初始化配置：

export WXA_DATA_DIR="$HOME/.local/share/wechat-articles"

node wechat-cli/dist/cli/entry.js config init \
  --data-dir "$WXA_DATA_DIR"
node wechat-cli/dist/cli/entry.js data stats --output json

登录并同步公众号：

node wechat-cli/dist/cli/entry.js auth login \
  --profile default --set-default
node wechat-cli/dist/cli/entry.js account search \
  --query "公众号名称" --output json
node wechat-cli/dist/cli/entry.js account follow \
  --fakeid MzExample --auto-sync --output json
node wechat-cli/dist/cli/entry.js account sync \
  --account MzExample --output json

同步只写入账号和文章元数据。下载、转换、OCR、分类、快照和导出均为显式操作：

node wechat-cli/dist/cli/entry.js download html \
  --account MzExample --missing html_raw --output json
node wechat-cli/dist/cli/entry.js pipeline run \
  --account MzExample --preset full --output json
node wechat-cli/dist/cli/entry.js export markdown \
  --account MzExample --output-dir "$PWD/export" --output json

不要猜测 CLI 参数，可直接查询机器可读的命令定义：

node wechat-cli/dist/cli/entry.js schema commands --output json
node wechat-cli/dist/cli/entry.js schema command account.sync --output json

完整命令说明见 wechat-cli/README.md，Agent 操作约定见 skills/cli-anything-wechat-spider/SKILL.md。

Web UI

开发模式：

export WXA_DATA_DIR="$HOME/.local/share/wechat-articles"
yarn dev

使用 CLI 启动构建后的同库 Web UI：

yarn build
node wechat-cli/dist/cli/entry.js ui open --output json
node wechat-cli/dist/cli/entry.js ui status --output json
node wechat-cli/dist/cli/entry.js ui stop --output json

CLI 管理的 UI 只绑定 127.0.0.1。若通过其他设备或域名访问，请在前面配置 HTTPS 反向代理；登录流程使用安全 Cookie，生产部署不应直接暴露 HTTP 端口。

Agent harness

Python harness 遵循 CLI-Anything 风格，只负责命令适配、JSON 输出和 REPL；微信请求、SQLite、文件处理和 Job 状态仍由 TypeScript 后端执行。

python3 -m venv .venv
.venv/bin/pip install -e agent-harness
.venv/bin/cli-anything-wechat-spider --json version

Docker

docker build -t wechat-article-exporter:local .

docker run -d \
  --name wechat-article-exporter \
  -p 127.0.0.1:3006:3006 \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/.local/share/wechat-articles:/app/.data" \
  wechat-article-exporter:local

端口	服务	建议
`3006`	Nuxt Web UI / Nitro API	仅本机访问，或置于 HTTPS 反向代理后
`8080`	Python 分类与 OCR 服务	仅供应用内部调用，不要直接暴露公网

容器内的默认数据目录为 /app/.data。升级或重建容器前，请确认该目录已挂载并完成备份。

两类凭证

项目严格区分两类登录材料：

类型	用途	生命周期
后台 Profile	搜索公众号、关注、同步文章列表、发现合集	持久化登录，可管理多个 profile
页面 Credential	阅读量、点赞、转发、评论和回复	按 `fakeid` 保存，默认约 25 分钟有效

页面凭证可从 wxdown-service/mitmproxy 产生的 credentials.json 导入。命令输出、API 和 Web UI 只显示脱敏元数据；原始值写入 WXA_DATA_DIR/auth/page-credentials 下权限为 0600 的文件，SQLite 只保存随机引用。

node wechat-cli/dist/cli/entry.js credential import /absolute/credentials.json \
  --source wxdown-service --output json
node wechat-cli/dist/cli/entry.js credential status --output json
node wechat-cli/dist/cli/entry.js download metadata \
  --account MzExample --missing metadata --output json
node wechat-cli/dist/cli/entry.js download comments \
  --aid ARTICLE_AID --force --output json

多 Profile 调度和页面 Credential 池都只服务于当前用户的本地归档，不会组成或接入公共账号池。

数据目录

WXA_DATA_DIR/
  database/wechat.db
  auth/
  html/
  state/jobs/
  state/locks/
  state/ui.json

SQLite 保存账号、文章、合集、任务和产物索引。
HTML、图片、Markdown、OCR、快照和导出文件保存在文件系统。
job show 和 job events 可查看持久化任务状态；失败项可单独重试。
请将整个 WXA_DATA_DIR 作为一个整体备份，避免数据库索引与文件产物版本不一致。

可选处理能力

能力	说明	额外要求
Markdown	本地化 HTML 转 Markdown	Go `html2md` 或 Python `markdownify`
页面快照	生成移动端 JPEG 快照	Chromium、Playwright、`shot-scraper`
OCR	从文章快照提取文字	macOS Vision、Linux Tesseract 或兼容 HTTP 服务
活动分类	识别讲座、招募、竞赛和非活动文章	本地规则/模型，或兼容的 LLM/Embedding API

模型缓存与训练产物（如 *.joblib）不纳入 Git。需要分发模型时，应先确认模型与训练数据的许可，再使用 Git LFS 或 GitHub Release，并在发布说明中记录来源、版本和校验值。

常用环境变量见 .env.example。分类服务的 Python 依赖见 requirements.txt。密钥只应写入本地 .env 或秘密管理服务，不要写入示例配置、日志或提交历史。

依赖与参考项目

本仓库直接基于或参考了以下项目。各项目仍适用其自己的许可证和使用条款。

项目	用途或关系	许可证/说明
wechat-article-exporter	本项目的上游代码基础，提供 Web UI、公众号搜索与导出能力	MIT，原始版权声明保留在 LICENSE
WeChat_Article	上游项目所参考的公众号文章获取原理	以其仓库声明为准
CLI-Anything	Agent harness 的接口与交互风格参考	以其仓库声明为准
shot-scraper	可选的真实网页快照工具	Apache-2.0；默认通过外部仓库路径调用
html-to-markdown	Go 侧 HTML 转 Markdown	MIT
python-markdownify	Python 侧 HTML 转 Markdown	BSD-3-Clause

主要运行时依赖：

范围	关键依赖	完整声明
Web UI / Node 后端	Nuxt 3、Vue 3、Nitro、better-sqlite3、Playwright、Cheerio、Turndown、ExcelJS、docx	package.json、yarn.lock、package-lock.json
Python 服务	FastAPI、Uvicorn、Beautiful Soup、Pillow、scikit-learn、XGBoost、markdownify	requirements.txt
Go 转换器	html-to-markdown	go.mod
浏览器运行时	Chromium / Chrome	系统安装或 Docker 镜像提供

项目包含 ag-grid-enterprise 依赖。AG Grid Enterprise 不随本项目的 MIT 许可证重新授权；需要 Enterprise 功能时，请自行取得并配置合法授权。其他第三方包同样以各自许可证为准。

开发与验证

yarn cli:check
yarn typecheck:server
yarn build

cli:check 会执行 TypeScript 类型检查、Vitest 测试、CLI 构建和命令契约校验。提交前还应确认 git status 中没有 .env、数据库、凭证、文章内容、截图缓存或模型文件。

许可

项目代码采用 MIT License。本仓库保留了上游作者的版权与许可声明；二次开发部分在同一 MIT 条款下发布。

使用声明

本工具仅用于用户有权访问和保存的内容。通过本工具获取的文章、图片、评论及其他内容，其版权和相关权利仍归原作者或权利人所有。使用者应遵守微信平台规则、适用法律、接口频率限制与个人信息保护要求，并自行承担使用和再分发责任。

本项目不会把本地登录或页面凭证上传到公共账号池。请勿公开 .env、WXA_DATA_DIR/auth、浏览器用户目录、抓包文件或任何包含 Cookie、token、pass_ticket、wap_sid2、appmsg_token 的内容。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
agent-harness		agent-harness
apis		apis
assets		assets
components		components
composables		composables
config		config
docker		docker
docs/wechat-cli-plan		docs/wechat-cli-plan
pages		pages
plugins		plugins
public		public
scripts		scripts
server		server
shared		shared
skills		skills
store/v2		store/v2
types		types
unused-wechat-cli		unused-wechat-cli
utils		utils
wechat-cli		wechat-cli
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.vue		app.vue
biome.json		biome.json
error.vue		error.vue
nuxt.config.ts		nuxt.config.ts
package-lock.json		package-lock.json
package.json		package.json
sentry.client.config.ts		sentry.client.config.ts
style.css		style.css
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Navigation Menu

Repository files navigation

wechat-article-exporter

功能

架构

快速开始

环境要求

安装与构建

Web UI

Agent harness

Docker

两类凭证

数据目录

可选处理能力

依赖与参考项目

开发与验证

许可

使用声明

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

wechat-article-exporter

功能

架构

快速开始

环境要求

安装与构建

Web UI

Agent harness

Docker

两类凭证

数据目录

可选处理能力

依赖与参考项目

开发与验证

许可

使用声明

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages