SuperAPI AI Directory

soia-pkm-clip-wechat-account

General & other

View repository

Updated 10-16 08:46

About this skill

soia-pkm-clip-wechat-account

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

  1. State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
  2. 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"} into consent.jsonunder the private configuration directory (at the same level as config.yml :~/.config/soia-skills/soia-pkm-clip-wechat-account/consent.json)。
  • Already exists and disclaimerVersion matches 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/batchget Only 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 's draft/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 as soia-pkm-publish-wechat-draft See 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 YAML env: mapping, see the example in assets/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 that total_count/item_count and the number of articles retrieved match expectations (especially freepublish/batchget field 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 by url are 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.appmsgpublish Although 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:--name When 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.ret will 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"):

    ret Meaning Handling
    200003 invalid session token/cookie has expired; log in to the backend again, capture the request, and replace them
    200013 freq control Rate limiting triggered; community reports say it usually requires waiting a relatively long time, so do not rerun immediately
    200040 invalid 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, author use --account-name / WECHAT_ACCOUNT_NAME as 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 3 seconds between requests per page/article; community reports indicate that even with throttling of 5 seconds/page, scraping nearly a thousand articles may still trigger freq control, and for batch scraping a full year of history it is recommended to use --limit to 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, using appmsgpublish,--page-size default 20.
  • Pass --name and --fakeid(choose one of the two): use searchbiz+appmsg?action=list_ex,--page-size default 5;--name will first run searchbiz search, take the first matching result; when fakeid is known, directly pass --fakeid to 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-size When 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 link for 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-article single-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 of profile_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 above profile_ext solution 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_token is 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.5 seconds 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_url for each list item, the script directly GETs the article's public page and parses #js_content(the same body-fetching approach as soia-pkm-clip-wechat-article single-article archiving; no extra cookie is needed).
  • --dry-run will 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-moc is filed into place—organize is 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 the env.OBSIDIAN_GZH_OUT in 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: [](topics is an extra item this skill adds relative to the user's original field list, to make it easier for organize to 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: false indicates that body extraction failed or is empty, and the original link needs manual verification.
  • Idempotent: all three scripts recursively search under url by out_dir to check whether it has already been archived; if it already exists, they skip it by default (--force is 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:

  1. Add a "## Summary" (30-80 characters) to each article.
  2. Determine/backfill frontmatter topics。
  3. Once the works library refactor is settled, hand it to organize to batch-file them from Inbox/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.