WeChat Article Downloader

Downloads WeChat Official Account articles via Chrome CDP and converts to clean Markdown with locally saved images.

Script Directory

Agent Execution Instructions:

Determine this SKILL.md file's directory path as SKILL_DIR
Detect runtime: if bun is available use bun, otherwise use npx -y bun. Store as ${BUN_X}
Script path = ${SKILL_DIR}/scripts/main.ts

Runtime Detection (one-time per session):

command -v bun >/dev/null 2>&1 && echo "bun" || echo "npx -y bun"

Run ${BUN_X} ${SKILL_DIR}/scripts/main.ts --help for full CLI options.

Preferences (EXTEND.md)

Check for user preferences (priority order):

test -f .wechat-article-downloader/EXTEND.md && echo "project"
test -f "$HOME/.wechat-article-downloader/EXTEND.md" && echo "user"

Result	Action
Found	Read, parse, apply settings
Not found	Use defaults

See references/config/preferences-schema.md for full schema.

Usage

Single Article

${BUN_X} ${SKILL_DIR}/scripts/main.ts "https://mp.weixin.qq.com/s/xxxx"

Custom Output Directory

${BUN_X} ${SKILL_DIR}/scripts/main.ts "https://mp.weixin.qq.com/s/xxxx" -o ./articles/

Search by Account Name (via Sogou)

${BUN_X} ${SKILL_DIR}/scripts/main.ts --search "公众号名称" --max 5
${BUN_X} ${SKILL_DIR}/scripts/main.ts --search "公众号名称" --list

Batch Download from URL List

${BUN_X} ${SKILL_DIR}/scripts/main.ts urls.txt -o ./backup/

Download from Own Account (API)

Requires WeChat Official Account API credentials (see Environment Variables):

${BUN_X} ${SKILL_DIR}/scripts/main.ts --account --list
${BUN_X} ${SKILL_DIR}/scripts/main.ts --account -o ./my-articles/
${BUN_X} ${SKILL_DIR}/scripts/main.ts --account --max 20

Download Modes

Mode	Trigger	Behavior
Single URL	Pass a `mp.weixin.qq.com` URL	Download one article via CDP
Batch file	Pass a `.txt` file path	Download all URLs sequentially
Search	`--search "name"`	Find articles via Sogou, then download
Account	`--account` flag	List + download all via WeChat API
Wait	`--wait` flag	Open Chrome, user logs in, press Enter to capture

Output Format

YAML frontmatter + Markdown body:

---
title: "Article Title"
author: "Author Name"
date: "2024-01-15"
source_url: "https://mp.weixin.qq.com/s/xxxx"
description: "Article digest..."
captured_at: "2024-01-15T12:00:00.000Z"
---

Environment Variables

Variable	Description
`WECHAT_DL_CHROME_PATH`	Custom Chrome executable path
`WECHAT_DL_CHROME_PROFILE_DIR`	Custom Chrome profile directory
`WECHAT_APP_ID`	WeChat Official Account App ID (for `--account` mode)
`WECHAT_APP_SECRET`	WeChat Official Account App Secret (for `--account` mode)

API credentials can also be set in .wechat-article-downloader/.env or ~/.wechat-article-downloader/.env.

Troubleshooting

Issue	Fix
Chrome not found	Install Chrome or set `WECHAT_DL_CHROME_PATH`
Timeout	Increase `--timeout` value
Login required	Use `--wait` mode
API errors	Check `WECHAT_APP_ID` and `WECHAT_APP_SECRET`
Images not loading	Page may need more scroll time; increase timeout
Sogou captcha	Try again later or use direct article URL

wechat-article-downloader