> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 只有一篇公众号文章链接，怎么找到账号 ID 并查历史文章？

> 从 wechat_mp.v2.fetch_article_detail_h5 响应读取 data.content.user_name，原样作为 username 传给 wechat_mp.v2.fetch_account_articles，区分 nick_name、author、__biz 与旧导出中的 fakeid。

从一篇文章链接查公众号以前的文章：先用[文章详情](/zh/faq/wechat-article-full-text)取 `data.content.user_name`，再把 `data.content.user_name` 原样填进 `wechat_mp.v2.fetch_account_articles` 的 `username`。公众号显示名、文章署名和长链接里的 `__biz` 都不能填成 `username`。已经保存了这篇文章的成功详情响应，或手里已有核对过的账号 ID，就直接把已核对的账号 ID 作为 `username` 使用。

## 用 `username` 取第一页文章

把示例里的 `<user_name_from_article>` 换成返回的账号 ID。`wechat_mp.v2.fetch_account_articles` 的 `username` 接受 `gh_…`、`gh_…@app` 和自定义微信号。第一页的 `offset` 留空。

```bash
curl -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"wechat_mp.v2.fetch_account_articles","params":{"username":"<user_name_from_article>","raw":false,"item_show_type":0,"offset":""}}' \
  -o wechat-articles-page-1.json
```

请求成功后，核对响应对应的是目标账号，并查看 `data.articles` 是否覆盖要找的日期。需要更多文章时，按[历史文章指南](/zh/guides/wechat-account-articles)用返回的游标续页。

## 手里的值能用来查什么？

| 手里的值                     | 用法                                                                |
| ------------------------ | ----------------------------------------------------------------- |
| `data.content.user_name` | 把 `data.content.user_name` 填成 `username`，查账号资料或历史列表。按返回值原样保留。     |
| `nick_name`、`author`     | `nick_name` 是账号显示名，`author` 是文章署名，两者只用于人工核查。只有名称时，先找到这个账号的一篇公开文章。 |
| 长链接中的 `__biz`            | 把 `__biz` 和原文章链接一起保留；查账号时用链接取详情，再读 `user_name`。                   |
| 旧导出里的 `fakeid`           | 把旧值存为 `legacy_fakeid`，另用原文确认账号。                                   |

例如两篇文章显示的公众号都是「城市观察」，先分别核对两篇文章详情里的账号 ID，再决定是否合并记录。取一篇文章的详情和查账号列表第一页是两次独立请求；有保存的详情响应就复用。新增调用的价格见 [BeatAPI 价格页](https://beatapi.io/zh/pricing)。

如果旧表只有 `fakeid`，但同事手里有原文章链接，先复用保存的文章详情，从中读 `data.content.user_name`。把旧的 `fakeid` 值留在单独一列，把核对过的 `user_name` 值填进历史列表请求的 `username`。显示名相同时，以核对过的账号 ID 判断是否同一公众号。

## 把已保存文章变成核对过的历史列表请求

同事发来一篇文章，让你查这个公众号以前的文章：已有成功的 H5 详情响应就直接复用；没有时用 `wechat_mp.v2.fetch_article_detail_h5` 查一次这篇文章，并记录 `url` 和明确的 `raw:true` 或 `raw:false`。两种 raw 模式都返回 `data.content.user_name`。复用已保存的详情后，只为实际请求的列表页付费；当前价格见[价格页](https://beatapi.io/zh/pricing)。

把 `detail-meta.json` 放在 `article.json` 旁边：

```json
{"action":"wechat_mp.v2.fetch_article_detail_h5","params":{"url":"https://mp.weixin.qq.com/s/example-token","raw":false},"http_status":200,"collected_at":"2026-11-17T03:15:00+08:00","response_file":"article.json"}
```

把示例里的 URL 和时间换成原请求和实际采集时间。把下面的脚本保存为 `account_handoff.py`，执行 `python3 account_handoff.py detail-meta.json account-handoff`。`account_handoff.py` 校验动作、成功信封、来源 URL 和文档规定的 `username` 语法，再写出原样的来源响应、响应哈希、`account-evidence.json` 和 `history-request.json`。脚本不发请求，不产生费用。响应里的 URL 与记录的请求 URL 不一致时，脚本直接停止，不把响应当成同一篇文章；先查清来源关系再继续。

```python
import hashlib, json, pathlib, re, sys
from datetime import datetime
from urllib.parse import urlsplit, parse_qs
metadata, target = map(pathlib.Path, sys.argv[1:3])
metadata_bytes = metadata.read_bytes()
m = json.loads(metadata_bytes)
if m['action'] != 'wechat_mp.v2.fetch_article_detail_h5' or type(m.get('http_status')) is not int or m['http_status'] != 200:
    raise ValueError('Require a successful H5 detail request')
p = m['params']
if set(p) != {'url','raw'} or type(p['raw']) is not bool:
    raise ValueError('Record url and explicit raw mode')
url = p['url']
if not isinstance(url,str) or not url or any(c.isspace() or ord(c)<32 or ord(c)==127 for c in url):
    raise ValueError('Use an intact public URL without whitespace/control characters')
u = urlsplit(url); q = parse_qs(u.query, keep_blank_values=True)
if any(k.startswith('amp;') for k in q) or any(k.lower() in ('pass_ticket','key','uin','ticket','access_token') for k in q):
    raise ValueError('Use a public share URL, not HTML markup or browser-session parameters')
for k in ('__biz','mid','idx','sn'):
    if k in q and (len(q[k])!=1 or not q[k][0] or any(c.isspace() or ord(c)<32 or ord(c)==127 for c in q[k][0])):
        raise ValueError('Ambiguous or invalid article component')
if u.scheme not in ('http','https') or u.hostname != 'mp.weixin.qq.com' or u.username is not None or u.password is not None or u.port not in (None,80,443):
    raise ValueError('Not a WeChat article URL')
short = u.path.startswith('/s/') and bool(u.path[3:]) and '/' not in u.path[3:]
long = u.path == '/s' and all(len(q.get(k,[])) == 1 and q[k][0] for k in ('__biz','mid','idx'))
long = long and q['mid'][0].isascii() and q['mid'][0].isdigit() and int(q['mid'][0]) >= 1 and q['idx'][0].isascii() and q['idx'][0].isdigit() and int(q['idx'][0]) >= 1
if not short and not long: raise ValueError('Missing article locator')
t = datetime.fromisoformat(m['collected_at'].replace('Z','+00:00'))
if t.tzinfo is None: raise ValueError('Use a timezone-aware collection time')
raw = (metadata.parent / m['response_file']).read_bytes(); body = json.loads(raw)
if body.get('status') != 'succeeded' or body.get('action') != m['action'] or body.get('error') is not None:
    raise ValueError('Response is not the recorded successful action')
rid = body.get('request_id')
if not isinstance(rid,str) or not rid.strip(): raise ValueError('Missing request ID')
data = body['data']
if data.get('url') != url: raise ValueError('Response URL differs from recorded request')
content = data['content']; username = content.get('user_name')
if not isinstance(username,str) or len(username)>80 or not re.fullmatch(r'[0-9A-Za-z][-_0-9A-Za-z]{1,63}(@[0-9A-Za-z]{1,16})?',username):
    raise ValueError('Missing or invalid account username; never infer from name/byline')
request = {'action':'wechat_mp.v2.fetch_account_articles','params':{'username':username,'offset':'','item_show_type':0,'raw':False}}
evidence = {'source_url':url,'collected_at':m['collected_at'],'request_id':rid,'source_sha256':hashlib.sha256(raw).hexdigest(),
            'metadata_sha256':hashlib.sha256(metadata_bytes).hexdigest(),
            'canonical_gh_candidate': bool(re.fullmatch(r'gh_[A-Za-z0-9_]+',username)),
            'username':username,'nick_name':content.get('nick_name'),'author_byline':content.get('author'),
            'identity_scope':'returned account identifier; not proof of legal ownership','next_request_executed':False}
target.mkdir(parents=True,exist_ok=False)
(target/'source.json').write_bytes(raw)
(target/'request-metadata.json').write_bytes(metadata_bytes)
for name,value in [('account-evidence.json',evidence),('history-request.json',request)]:
    (target/name).write_text(json.dumps(value,ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'username':username,'next_request_executed':False}))

```

检查 `history-request.json`，再在自己的预算内把完整请求体发给 social-data call 接口。自定义微信号或 `gh_…@app` 按返回值保留，`account_handoff.py` 不会把自定义微信号或 `gh_…@app` 改造成 `gh_` ID。`history-request.json` 从空 `offset` 开始，使用 `raw=false` 和文章页签。不要把来源文章的 `mid`、`comment_id`、作者或显示名填进 `username`。

使用交接包前先核对：生成的 `username` 必须与 `source.json` 里的 `data.content.user_name` 逐字相同，`source_sha256` 必须与 `source.json` 匹配。缺少 ID、数字 ID、带空格的昵称和失败响应都不生成交接包；输出目录已存在时 `account_handoff.py` 拒绝覆盖。语法合法不证明账号仍然存在或属于某个品牌，下一次成功的列表响应才是单独的取数核验。文中链接的历史文章脚本和每日同步脚本目前要求规范的 `gh_` 账号，并检查响应账号一致。API 接受的自定义微信号仍可能通不过要求规范 `gh_` 前缀的历史文章与每日同步脚本；不要改名绕过身份校验。

只有昵称时，先通过一篇文章或已核验的账号搜索结果确认目标账号。名称相同不能证明是同一个账号。

## 为什么解码 \_\_biz 得不到历史列表的 username？

长链接里的 `__biz` 表示这篇文章链接所属的账号上下文，`__biz` 与 `gh_…` 不是同一种标识；在同一个 `__biz` 上下文里，再用 `mid` 和 `idx` 区分文章。保留完整 URL：删掉 `mid`、`idx`，或解码看起来像 Base64 的 `__biz` 值，都得不到可用的历史请求。BeatAPI 公开的输入、输出合同里没有从 `__biz` 转换成 `gh_` 的方法。

自定义微信号通过语法校验，也不证明账号正确。不要假设“任意 `__biz` 都会在扣费前被拒绝”：有的字符串符合较宽的 `username` 规则。必须核实传入的 `username` 来自 `data.content.user_name`，而不只是字符合法。

例如 `https://mp.weixin.qq.com/s?__biz=Example%2B&mid=123&idx=1` 这样的长链接，[离线链接审计](/zh/faq/wechat-link-parameters)保存解码后的查询值和原 URL；链接审计不调用接口，也不推导 `gh_` 值。要生成历史请求，`account_handoff.py` 要求已保存的详情响应里回显的请求 URL 与 `detail-meta.json` 中的 URL 完全相同。短链接同样从文章详情取 `user_name`，不需要先拼出长链接。

`account_handoff.py` 还会逐字节保存 `request-metadata.json`，并把 `request-metadata.json` 的 SHA-256 与 `source_sha256` 记录在一起。`canonical_gh_candidate` 只按交接脚本的保守语法规则标记不带后缀的 `gh_` 编号。`canonical_gh_candidate` 为 false 不表示 API 拒绝该 `username`，而是表示不要将非 `gh_` 别名直接交给要求 `gh_` 前缀的脚本，也不要擅自改名。`canonical_gh_candidate` 不检查账号是否存在。

把 `history-request.json` 交给别人前，核对来源 URL、返回的 `username`、采集时间和两个已保存文件的哈希。`author` 和 `nick_name` 只作描述字段。响应带有明确非 null 的网关 `error` 或空白 `request_id`，或者 URL 含用户信息或浏览器会话参数时，`account_handoff.py` 在创建输出目录前停止。`account_handoff.py` 不发请求，也不安排后续调用。

## 旧公众号导出里的 fakeid 是什么，能直接复用吗？

把 `fakeid` 看作某个老工具或某条路线里的字段，不要当作 BeatAPI `username` 的通用别名。在 [wechat-article-exporter issue 117](https://github.com/wechat-article/wechat-article-exporter/issues/117) 里，维护者把当时所讨论路线中文章的 biz 参数称为 fakeid。issue 117 的命名不能证明所有后台或工具里叫 fakeid 的字段都是同一种表示，更不能证明 fakeid 是 `gh_` 编号。

当前 `wechat_mp.v2.fetch_account_articles` 的输入是 `username`，没有 fakeid 参数。不要把旧表改个列名就发请求，不要在旧值前补 `gh_`，也不要认为解码 `__biz` 就能确定账号。字符串符合输入规则，不等于对应的是正确账号。使用 BeatAPI 公开的 action 也不需要抓取微信会话。

旧归档只有 fakeid、昵称和文章链接时，按下面的步骤换成 `username` 路线：

1. 把旧列保留为 `legacy_fakeid`，记录旧值来自哪个工具或文件。不要用新标识覆盖 `legacy_fakeid`。
2. 选一条属于目标账号的完整公开文章 URL。昵称只作背景信息，不作关联主键。过期、私有或带会话参数的 URL 不是合法的公开来源，即使旧工具保存过这条 URL。
3. 复用匹配的已保存详情响应，或单独预算一次详情查询。`account_handoff.py` 检查原请求 URL、回显 URL 和返回的 `data.content.user_name`；`account-evidence.json` 记录这篇文章属于哪个账号。
4. 审核 `account-evidence.json` 和 `history-request.json`。`legacy_fakeid`、核实后的 username 和来源文章分成三列。其他旧记录要在各自的账号核实后才能合并，昵称相同不够。
5. 新路线从空 `offset` 开始。旧 fakeid、后台游标、cookie、uin、key、pass_ticket 都不能复制进 BeatAPI 参数或支持工单。[频控错误排查](/zh/faq/wechat-frequency-error)说明老同步失效时如何保留本地文件。

如果只剩 `fakeid`，又没有公开文章或独立核实的账号来源，交接脚本没有可用的转换步骤。把仅有 `fakeid` 的记录标为未解析，不要盲目发付费请求。`account_handoff.py` 产出的是核对过的请求和证据包，不是批量导入工具、身份登记库，也不是已经下载完成的新历史。