clip family'sofficial account batch member: Unlike soia-pkm-clip-wechat-article(single article, archive by pasting a URL), this skill targets the batch scenario of "pulling all the historical articles of my own official account into the vault at once." It is only for archivingmanaged by you yourselfofficial accounts — not a general-purpose official account scraper.
Client-readable description
What this skill can do
Batch-archive the published articles of a WeChat official account managed by the user into an Obsidian vault. Supports three routes: official API, official account backend interface, and logged-in session Cookie, with deduplication by url
| The client wants | The skill will do | The client can see |
|---|---|---|
| Complete the work covered by this skill | Read the user request, the necessary context, and this skill's body workflow, and execute the minimal reliable steps | The client will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt. |
| Missing dependencies, permissions, configuration, or keys | Stop actions that require external state, and clearly state what is missing | Install commands, application addresses, configuration paths, or questions that need client confirmation |
| Execution complete | Summarize successes, skips, failures, file changes, and verification results | A completion receipt that can be copied into a ticket/log |
How the client uses it
- State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
- For actions that can be dry-run or previewed, give a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask for client confirmation first.
Dependencies and installation
Installation (recommended: install the entire domain plugin, installing all skills in this repo at once):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear in two indexes and each will drift, so it is recommended to pick one of the two:
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-clip-wechat-account -y
Configuration conventions:
~/.config/soia-skills/soia-pkm-clip-wechat-account/config.yml
SOIA_PKM_CLIP_WECHAT_ACCOUNT_CONFIG_FILE=<custom-config-path>
# 兼容别名:$SOIA_PKM_CLIP_GZH_CONFIG_FILE(以及原有 $SOIA_PKM_CLIP_GZH_ENV_FILE)
- If this skill does not need private configuration, you can skip creating
config.yml。 - If it needs an API key, cookie, session, provider home, or local path, it can only go into a private
config.yml, the process environment, or the provider's own login state, and must not be written into the repo, vault body, or logs. - Third-party skills can only declare dependencies and installation methods, and do not directly modify third-party skill files.
WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。
Logs and completion receipt
Batch scraping only means captured; after writing to disk, complete each object according to the lifecycle management skill organized → MOC/导航 → map → Base, and for inapplicable stages explicitly write not_applicable, and a batch success count cannot replace closed-loop evidence.
Each execution must let the client see the process and results. Minimum receipt format:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>
文件变化:
- <绝对路径或“未改动文件”>
验证:
- <运行过的检查、命令或人工核对点>
问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>
Delivery order:Batch archiving must first write all articles to disk, then output the above receipt uniformly; the reverse is not allowed;author relies on --account-name as a fallback,content_complete: false and other uncertain fields such as these must be explicitly marked "unverified" in the receipt; do not fabricate.
How to choose among the three routes
| Route A · Official API | Route C · WeChat Official Account backend interface | Route B · Logged-in Cookie | |
|---|---|---|---|
| Coverage | Only articles published through the **Drafts box "Publish"** | All history, including old articles sent manually in bulk | All history, including old articles sent manually in bulk |
| Account requirements | Requires a verified service account/subscription account | Any WeChat Official Account, as long as you can log in to the backend | Any WeChat Official Account, as long as you can log in to the backend |
| Credentials | AppID/AppSecret, valid long-term + IP whitelist | token/Cookie, expires in a few hours | key/pass_ticket/appmsg_token, expires in a few hours to a few days |
| Difficulty of obtaining credentials | One-time configuration (generated in the backend) | Capture 1 pair of values (token+Cookie) | Capture 3 tickets + Cookie; easy to miss captures/mismatch pairs |
| Degree of officialness | Documented at developers.weixin.qq.com | Unofficial, community reverse engineering (source-level verification) | Unofficial, community reverse engineering, not found in official documentation |
| Script | scripts/fetch_api.py |
scripts/fetch_mp.py |
scripts/fetch_cookie.py |
Recommendation:First run Route A to scout (the one-time cost of setting up credentials is low, and they can be reused long-term for incremental sync; most personal unverified accounts will directly hit the permission threshold, see below). To read all history (including old articles sent manually in bulk),prefer Route C——credentials only require capturing one pair of token/Cookie, which is less error-prone than Route B requiring three tickets to be paired, and is the recommended route in this skill for reading historical articles from your own account. Route B is retained as a fallback when Route C fails (for example, if both interfaces are revised someday). All three routes run only on accounts you can log in to/manage yourself; when accounts that have been run are persisted, they will be automatically deduplicated by url (skipping articles already archived by each other).
Route C is further divided into two subpaths internally; the script automatically selects based on whether you pass --name/--fakeid :If not passed (default), use appmsgpublish to read the account you are currently logged in to; if passed, --name/--fakeid only then use searchbiz+appmsg to read a specified/someone else's account—see the Route C section below for the reason.
Confirmation and authorization before execution
Confirmation policy
Before formally scraping article bodies/writing files, first use --dry-run --limit 3 and similar small samples to scout, and report to the client the WeChat Official Accounts, order of magnitude of article count, and time range expected to be processed this time; only after the client confirms the scope is correct should full scraping be released. Explicitly invoking this skill and passing parameters such as --name/--limit are only recommended inputs and do not constitute a reason to skip this confirmation—the only condition for skipping is if the client's current sentence explicitly says "scrape directly/no need to confirm"; after skipping, the scope assumptions used this time must be stated in the receipt.
Confirmation before use (consent)
Routes B / C use the WeChat Official Account backendunofficial interfaces, there is a ToS risk. On first use of this skill, or when the version declared in this section changes, you must first display the following statement and obtain the client's explicit consent before continuing:
Some routes of this skill (Route B / Route C) use unofficial interfaces of the WeChat Official Account backend, which are not included in WeChat's official documentation and carry a ToS risk; they are limited to archiving accounts you manage yourself and must not be used to scrape other people's Official Accounts. (Statement version v1)
- After the client consents, write
{accepted: true, acceptedAt: <ISO 时间戳>, disclaimerVersion: "v1"}intoconsent.jsonunder the private configuration directory (at the same level asconfig.yml:~/.config/soia-skills/soia-pkm-clip-wechat-account/consent.json)。 - Already exists and
disclaimerVersionmatches the current version (v1) → skip the display, continue directly, and merely mention "Terms of use confirmed (<acceptedAt>)" in the log. - Client refuses → stop, do not perform any scraping action.
- Route A (official API) uses interfaces included in the official documentation and is not subject to this consent constraint.
Route A · Official API
Interface basis (verified 2026-07 against developers.weixin.qq.com + WeChat Open Community; field names have been written into the script comments)
| Interface | Method | Request | Key response fields | Basis |
|---|---|---|---|---|
| Get access_token | GET | /cgi-bin/token?grant_type=client_credential&appid=&secret= |
access_token, expires_in |
Official documentation(complete request/response examples obtained) |
| Get successful publish list | POST | /cgi-bin/freepublish/batchget?access_token=,body {offset,count,no_content} |
total_count,item_count,item[].article_id,item[].update_time,item[].content.news_item[].{title,author,digest,content,content_source_url,thumb_media_id,show_cover_pic,need_open_comment,only_fans_can_comment,url,is_deleted} |
Official documentation(the complete example body could not be obtained at scrape time; field names have been cross-checked and found consistent with multiple independent posts in the WeChat Open Community——recommend first using --dry-run --limit 3 to calibrate once with a real test) |
| Get permanent material list | POST | /cgi-bin/material/batchget_material?access_token=,body {type:"news",offset,count}(count is officially marked as 1-20) |
total_count,item_count,item[].media_id,item[].update_time,item[].content.news_item[].{title,thumb_media_id,show_cover_pic,author,digest,content,url,content_source_url} |
Official documentation(complete request/response examples obtained) |
⚠️ Coverage limitations (must read first)
freepublish/batchgetOnly returns articles sent via the draft box's "publish" action. Content that only went through "mass send" but was never clicked "publish", as well as old-version graphic messages from before the draft box feature launched, currently haveno API at all that can retrieve them——this is not an implementation flaw of this skill, but a platform limitation cross-confirmed by multiple posts in the WeChat Open Community.material/batchget_material(type=news) returns permanent graphic materials; according to community feedback, once an article is officially "published" via the draft box, it may disappear from this material list. The two interfaces are in acomplementary relationship, and even taking their union does not equal "the entire published history".- The documentation for interfaces related to "publishing capability" states:as of 2025-07, the calling permissions for these interfaces will be revoked for personal entity accounts, unverified enterprise entity accounts, and accounts that do not support verification. Most personal subscription accounts will most likely fail on this entire route; a verified service account/subscription account is required (the same account threshold as
soia-pkm-publish-wechat-draft'sdraft/add). - Conclusion: Route A is better suited for "spot-checking/verifying/incrementally syncing already published content"; do not expect it to be a "full backup". To read the entire history (including old articles manually mass-sent), prefer Route C, with Route B as a fallback.
Credentials and limitations
WECHAT_APP_ID/WECHAT_APP_SECRET: the acquisition path and IP whitelist configuration are the same assoia-pkm-publish-wechat-draftSee the "How to Obtain and Configure the WeChat Official Account AppID / AppSecret" section in SKILL.md; it is not repeated here — both skills use the same set of WeChat Official Account development credentials.- Automatic detection of private configuration:
$SOIA_PKM_CLIP_WECHAT_ACCOUNT_CONFIG_FILE(compatible aliases$SOIA_PKM_CLIP_GZH_CONFIG_FILE, as well as the existing$SOIA_PKM_CLIP_GZH_ENV_FILE)>~/.config/soia-skills/soia-pkm-clip-wechat-account/config.yml. The configuration file uses a YAMLenv:mapping, see the example inassets/config.example.yml; secrets do not go into the vault or into this open-source skill repository.
Usage
python3 scripts/fetch_api.py [--out <vault内相对目录>] [--limit N] [--dry-run] \
[--vault <path>] [--account-name <公众号显示名>] [--force] [--page-size 20]
--dry-run: only pull the list and print it, do not write files —For the first run, a dry-run is strongly recommended, verify thattotal_count/item_countand the number of articles retrieved match expectations (especiallyfreepublish/batchgetfield has not been 100% verified against the official example body text).--account-name: Neither interface returns the WeChat Official Account nickname; use it for file name/source information; if not provided, "公众号" is used as a placeholder in the file name.--force: Articles already archived byurlare skipped by default; add this to overwrite and rewrite them.
Path C · WeChat Official Account backend interface (recommended: read all history of your own account)
Reuse the mp.weixin.qq.com backendinterface (the author logs into the backend, not the reader-side profile_ext), and like Path B it can read all history (including old articles sent manually in bulk), but the credentials only require capturing a pair of token/Cookie, which is less error-prone than Path B requiring a matched set of three tickets (key/pass_ticket/appmsg_token).
Path C has two sub-paths internally,scripts/fetch_mp.py automatically switches based on whether you pass --name/--fakeid :
Default (do not pass --name/--fakeid) |
Pass --name or --fakeid |
|
|---|---|---|
| Interface | appmsgpublish(author-side "Publish Records") |
searchbiz(name → fakeid) + appmsg?action=list_ex(fakeid → list) |
| Whose account is read | The account you are currently logged into, no need to specify name/fakeid | The account corresponding to the specified name/fakeid (can be another account that you also manage) |
| Applicable scenarios | Most common scenario: you just want to back up your own account | You are logged into the backend with a certain account, but you need to read another account that you also manage and whose name/fakeid you know |
| Verification status | Tested: ran successfully on a real account on 2026-07-09,ret=0,total_count=152 |
Source-level check, no official documentation found, marked as "pending user testing and calibration" |
Why the default path does not use searchbiz:searchbiz it fuzzy-searches the WeChat Official Account list by name, designed for "finding someone else's account"; searching with your own WeChat Official Account's name often fails to find yourself (returns an empty list), so it is not suitable as the default path for "I am already logged in and this is my account."appmsgpublish directly reads the publish records of the account corresponding to the current login state, so this problem does not exist.
Interface basis (source-level check + appmsgpublish already tested)
| Interface | Method | Request | Key response fields | Basis |
|---|---|---|---|---|
| appmsgpublish (default, read your own account) | GET | /cgi-bin/appmsgpublish,params sub=list&begin=<0,20,40,...>&count=20&type=101_1&free_publish_type=1&sub_action=list_ex&token=&lang=zh_CN&f=json&ajax=1 |
base_resp.ret;publish_page(JSON string,json.loads after that is {total_count, publish_list[]}); each publish_list[].publish_info(is again a layer of JSON string),json.loads after that is {appmsgex[]}, each appmsgex[] contains title/link/update_time/digest |
cv-cat/WechatOAApis — utils/wx_utils.py Source-level cross-check,and verified through real-account testing by the user on 2026-07-09 |
| searchbiz (name → fakeid) | GET | /cgi-bin/searchbiz,params action=search_biz&begin=0&count=5&query=<公众号名>&token=&lang=zh_CN&f=json&ajax=1 |
base_resp.ret,list[].{alias,fakeid,nickname,round_head_img,service_type} |
wnma3mz/wechat_articles_spider — ArticlesUrls.py::official_info() and cv-cat/WechatOAApis — utils/wx_utils.py::get_fakeid_params() the parameters of the two independent repositories are completely identical |
| appmsg (fakeid → article list) | GET | /cgi-bin/appmsg,params action=list_ex&begin=<0,5,10,...>&count=5&fakeid=<fakeid>&type=9&query=&token=&lang=zh_CN&f=json&ajax=1 |
base_resp.ret,app_msg_cnt,app_msg_list[].{aid,appmsgid,cover,digest,itemidx,link,title,update_time}(does not contain an author field) |
wnma3mz/wechat_articles_spider — ArticlesUrls.py::__get_articles_data() |
appmsgpublish and appmsg?action=list_ex are not the same interface; the response structure and pagination step size are both different—they should be interfaces called by the old and new frontend versions of the mp backend respectively, and the script contains two independent implementations (list_own_account() vs fetch_article_list()), which cannot be mixed.
⚠️ Limitations and risks (read first)
-
Unofficial interface: like Route B, it has no official documentation backing it and may be adjusted at any time.
appmsgpublishAlthough it has passed real-account testing, it is likewise not an interface included in official documentation. -
For archiving only official accounts that you manage yourself:
--nameWhen matched, it will print nickname/fakeid and prompt for confirmation; if it is not your own account, press Ctrl+C to interrupt; the default path reads the currently logged-in account itself, so there is no risk of mistaking the account. -
token/Cookie will expire: community reports say they usually become invalid within a few hours, with no refresh mechanism; after expiration,
base_resp.retwill return non-0 (the script already gives targeted prompts according to the table below; the two sub-paths share the same set of prompts, cross-checked by community reverse engineering, with no official documentation found, and still subject to "pending user real-account calibration"):retMeaning Handling 200003invalid session token/cookie has expired; log in to the backend again, capture the request, and replace them 200013freq control Rate limiting triggered; community reports say it usually requires waiting a relatively long time, so do not rerun immediately 200040invalid csrf token The token and Cookie are suspected to have not been captured from the same login session -
Neither sub-path list interface returns an author field: at implementation time,
authoruse--account-name/WECHAT_ACCOUNT_NAMEas a fallback; it is not guaranteed to equal the article's actual bylined author. If you need the exact author, manually check the original article page. -
Rate-limiting risk: by default, the script waits
--sleep 3seconds between requests per page/article; community reports indicate that even with throttling of 5 seconds/page, scraping nearly a thousand articles may still triggerfreq control, and for batch scraping a full year of history it is recommended to use--limitto run in batches.
Credential acquisition
Log in to the mp.weixin.qq.com backend, casually open an article edit page or an article list page, press F12 to open the browser developer tools "Network" panel, and fromthe address bar URL copy the token parameter, and from the request headers copy the complete Cookie string. Fill them in according to assets/config.example.yml into the private config.yml of env.WECHAT_MP_TOKEN / env.WECHAT_MP_COOKIE。
⚠️ Note token must be the one in the address bar URL (the numeric string),notthe ticket in the "Network" panel whose request parameter name is appmsg_token —the two are different tickets,appmsgpublish recognizes the address bar token。
Usage
# 默认:不传 --name/--fakeid,读你自己当前登录的账号(appmsgpublish,推荐)
python3 scripts/fetch_mp.py [--out <目录>] [--limit N] [--dry-run] \
[--vault <path>] [--account-name <显示名>] [--force] [--sleep 3] [--page-size 20]
# 传 --name 或 --fakeid:读指定/别人的号(searchbiz + appmsg?action=list_ex)
python3 scripts/fetch_mp.py --name <公众号名> [--out <目录>] [--limit N] [--dry-run] \
[--vault <path>] [--account-name <显示名>] [--force] [--sleep 3] [--page-size 5]
- Do not pass
--name/--fakeid(default, recommended): read your own currently logged-in account, usingappmsgpublish,--page-sizedefault 20. - Pass
--nameand--fakeid(choose one of the two): usesearchbiz+appmsg?action=list_ex,--page-sizedefault 5;--namewill first runsearchbizsearch, take the first matching result; whenfakeidis known, directly pass--fakeidto skip the search step is more reliable. --dry-run: only paginate to pull the list and print title + link,do not fetch the body, do not write files— faster than route B's dry-run (route B's dry-run still fetches all bodies). For the first run, it is recommended to do a dry-run first to verify whether the article count and titles match expectations.--page-sizeWhen not passed, default values are automatically taken according to the subpath being used (20 for your own account / 5 for a specified account). Both are verified/community-tested stable values; do not increase them.- After getting
linkfor each list item, the script directly GETs the article's public page and parses#js_content(the same body-fetching approach as route B /soia-pkm-clip-wechat-articlesingle-article archiving; no extra cookie is needed).
Route B · Logged-in Cookie
Interface basis (unofficial, community reverse-engineered, cross-checked)
GET https://mp.weixin.qq.com/mp/profile_ext
?action=getmsg&__biz=<biz>&f=json&offset=<offset>&count=10&is_ok=1
&scene=124&uin=<uin,通常固定777>&key=<key>&pass_ticket=<pass_ticket>
&wxtoken=&appmsg_token=<appmsg_token>&x5=0
Header: Cookie: <登录态 Cookie>
响应:{"ret":0,"errmsg":"ok","msg_count":N,"can_msg_continue":0|1,
"general_msg_list":"<JSON 字符串,需二次 json.loads>","next_offset":N,...}
general_msg_list 解析后:
{"list":[{"comm_msg_info":{"datetime":<unix ts>},
"app_msg_ext_info":{"title","author","content_url","is_multi",
"multi_app_msg_item_list":[同字段的合集子项]}}]}
Basis sources: cross-check of reverse-engineering records for the same interface from multiple independent technical blogs (Cnblogs/CSDN/Zhihu, 2019-2024); the field names are consistent with each other, butnone are official documentation, and developers.weixin.qq.com does not include this interface. The script has been implemented accordingly and written into code comments, but it is still marked as “pending user real-world calibration” — on the first run, be sure to --dry-run --limit 3。
Note: the user's original requirements included a reference implementation link (
zjp1997720/wechat-article-search); in testing, that project actually calls Sogou WeChat Search (weixin.sogou.com), and does not use cookie-based scraping ofprofile_ext's technical route, which does not match the goal of "reading all history", so route B did not copy it and instead changed to the aboveprofile_extsolution that has been independently reproduced by multiple parties.
⚠️ Limitations and risks (be sure to read first)
- Unofficial interface: There is no official documentation backing it; WeChat may adjust the implementation at any time and make it stop working; there is no official support channel if problems occur.
- Only for archiving official accounts that you manage yourself: Multiple reference materials suggest that this kind of reverse-engineered call is "recommended for learning and research purposes only"; scraping the historical articles of other people's official accounts may violate WeChat's Terms of Service. This script is designed as self-service backup for your own account; do not use it to scrape other people's accounts.
- The ticket will expire:
key/pass_ticket/appmsg_tokenis a session ticket; community reports range from a few hours to a few days. There is no refresh mechanism; after expiration, if an error occurs, you must log in again, capture packets, and replace it. - Risk of rate limiting: By default, the script waits
--sleep 1.5seconds between each request; do not set it too fast. For batch scraping of a whole year of history, it is recommended to run in batches (with--limit), not to pull several hundred articles at once.
Credential acquisition
Log in to the mp.weixin.qq.com backend, open any historical article of that official account (or profile_ext?action=home), find same-domain requests in the browser developer tools “Network” panel, copy __biz/key/pass_ticket/appmsg_tokenfrom the request URL, and copy the complete Cookie string from the request headers. Fill it in according to assets/config.example.yml into the private config.yml。
Usage
python3 scripts/fetch_cookie.py --biz <__biz> [--out <目录>] [--limit N] [--dry-run] \
[--vault <path>] [--account-name <显示名>] [--force] [--sleep 1.5]
- The list interface has 10 items per page (community-tested upper limit); the script automatically paginates by
can_msg_continue/next_offset. - After getting
content_urlfor each list item, the script directly GETs the article's public page and parses#js_content(the same body-fetching approach assoia-pkm-clip-wechat-articlesingle-article archiving; no extra cookie is needed). --dry-runwill still paginate through the entire list, fetch all the full text, and then print it (without writing files); it takes longer when the volume is large. To quickly check the list itself, first look at the per-page output printed to stderr in拿到 N 条,累计 M。
Landing conventions (shared by all three routes)
- transit area, not the final destination: it lands in the vault'sinbox layer, not the final location after
soia-pkm-organize-article-mocis filed into place—organizeis stockpiled here before launch, and will later be filed into zones 40/50 along with the "works library refactor". - Default output directory:
Inbox/gzh-articles/<年>/(a path relative to the vault, the generic default in the code). You are advised to set this vault to your own transit area, for example<vault-inbox-dir>/gzh-articles/—overridden with--out <vault-relative-dir>or theenv.OBSIDIAN_GZH_OUTin a private config (the default value deliberately does not hardcode a specific Chinese path, in compliance with this repository's SKILL_SPEC.md "no hardcoded personal paths" rule). - Filename:
<出版日期>-公众号-<账号显示名>-<标题>.md, and on name conflicts, a short suffix is appended based on url characteristics. - frontmatter:
tags:[公众号原创, 待归位]、source: 公众号自有、url、title、author、published_at、captured_at、route: api|cookie|mp-backend、content_complete、topics: [](topicsis an extra item this skill adds relative to the user's original field list, to make it easier fororganizeto directly fill in the category later; when there is no content, leave it as an empty array, which does not affect other fields). - Body: HTML → Markdown via stdlib
html.parser(zero third-party dependencies, consistent with other scripts in this repository); it does not guarantee 100% restoration of the layout, and complex inline styles/WeChat-exclusive components will be flattened into plain text + image links.content_complete: falseindicates that body extraction failed or is empty, and the original link needs manual verification. - Idempotent: all three scripts recursively search under
urlbyout_dirto check whether it has already been archived; if it already exists, they skip it by default (--forceis required to overwrite), so running the three routes alternately will not land the same article twice.
After archiving,
following the clip family convention, AI can subsequently:
- Add a "## Summary" (30-80 characters) to each article.
- Determine/backfill frontmatter
topics。 - Once the works library refactor is settled, hand it to
organizeto batch-file them fromInbox/gzh-articles.
Closed-loop position
★clip-gzh(批量收) → organize(归位/分类) → distill(收藏→观点) → compose(观点→文) → publish(发)
and soia-pkm-clip-wechat-article(single-article archiving) are complementary: clip-wechat handles "see a forwarded link, save an article on the fly"; clip-gzh handles "batch-import the historical backlog from my own public account". The landing conventions of the two are not completely consistent (clip-gzh has extra route/content_complete fields), so they will not be merged for now; whether to converge them into one set will be evaluated together during the works library refactor.