Wechat article downloader

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:

1. Determine this SKILL.md file's directory path as SKILL_DIR
2. Detect runtime: if bun is available use bun, otherwise use npx -y bun. Store as ${BUN_X}
3. 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