> 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.

# 公众号文章页和主页上的数据，分别从哪里取？

> 逐项对应正文、互动、头条位置与主页字段，按五篇文章审核任务选择接口并说明交付边界。

公众号页面上的每个字段都来自一个特定动作。做文章核查表时，标题和正文取自 `wechat_mp.v2.fetch_article_detail_h5`，阅读与互动取自标准 `wechat_mp.v2.fetch_article_stats`，群发内位置取自账号文章列表 `wechat_mp.v2.fetch_account_articles`，账号字段取自 `fetch_account_profile`。每列记下来源动作和采集时间，查不到的值留空。

例如比较同一活动的几篇文章：先看每篇文章讲什么，再对照同一时间范围的互动，并确认哪篇是同次群发的头条。需要账号资料时，用已核对的账号标识单独查询。

## 先列必需的列，不先把所有接口查一遍

| 你真正要判断的事        | 先准备什么                  | 还缺证据时怎样处理                 |
| --------------- | ---------------------- | ------------------------- |
| 文章讲了什么，能否支持某个结论 | 核实的文章URL、返回文本与原文来源     | 没读到的图片/附件或未回答问题保留为缺口      |
| 当前阅读与互动是否值得复盘   | 同一文章的标准统计、采集时点和显隐状态    | 不把缺失或隐藏当零；不混入不同年龄的文章做同龄排名 |
| 文章是同次群发的第几篇     | 已核实的账号，以及文章列表中的文章身份和位置 | 没有列表证据就留未知，不能把第一行默认当头条    |
| 账号是谁、关联哪个视频号    | 账号资料中实际给出的标识与关联字段      | 同名不自动合并；展示名不等于法律主体        |

只需要标题和正文时，不查主页、评论和指标。新增需要的列时，只为这些列加请求，能复用的已有记录直接复用。账号资料只能复用于已核实的同一账号，不能拿去填另一个同名账号。

## 怎样让每一行都能回到原始证据？

保留原请求 URL、返回的文章链接、账号身份，以及正文和统计各自的请求 ID 与采集时间。两份文件标题一样不足以配对，长短链接别名也不能凭猜测合并。来源或身份对不上时先停止关联，不要把数字贴到最像的标题行。

`join_article_review.py`（见本页最后一节）重新核对原始响应、哈希和字段，不直接相信人工可编辑的指标 CSV。`join_article_review.py` 只合并已保存且通过校验的正文和标准统计：头条位置标为未联入，`join_article_review.py` 也不采集评论或主页资料。哈希只说明保存的字节没有变化，不证明文章主张属实，也不独立认证文章的网络来源。

## 交付一张什么样的审核表？

每个需求列都要有实际来源、观察时点和状态，或者写明尚未取得、不支持的原因。把“候选判断、原句、自己的解释、下一步”作为人工审核内容，与接口事实分开。数字看起来正常但显隐状态异常时，保留原值和显隐标志；没有头条证据就不要填 1。

`join_article_review.py` 每批接受 1–5 篇文章。20 篇需要四份明确的配对清单和四个新输出目录，另外还要检查批次之间是否重复；`join_article_review.py` 不会一条命令自动取得 20 篇的所有字段。任一配对校验失败时，保留整批输入并排查原因，不要悄悄丢掉失败的文章让交付看起来完整。

下面先逐项列出字段来源，再给出可离线运行的正文/统计联表。依据：所列各动作公开的输出合同。账号私有数据和完整页面覆盖不在所列字段范围内。

## 文章正文、身份与发布时间

使用 `data:wechat_mp.v2.fetch_article_detail_h5`。下表的公开字段都是可选字段，两种 raw 模式下都位于 `data.content`；`raw=true` 只增加元数据，不改变正文路径。

| 页面项目        | 响应路径                                             | 正确解释                      |
| ----------- | ------------------------------------------------ | ------------------------- |
| 标题／署名作者     | `data.content.title` / `author`                  | 署名不等于账号法律主体               |
| 公众号名称／编号    | `data.content.nick_name` / `user_name`           | 用核实后的编号关联，不凭同名合并          |
| 纯文本／HTML    | `data.content.content_text` / `content_noencode` | HTML是不可信内容；文本不等于看过视频、读过图片 |
| 摘要／封面       | `data.content.desc` / `data.content.cdn_url`     | 摘要不是全文；封面URL不是全部图片集合      |
| 发布时间        | `data.content.create_timestamp` / `create_time`  | Unix时间戳和原格式时间；采集时间另记      |
| 当前文章／阅读原文链接 | `data.content.link` / `source_url`               | `source_url` 可以为空，也可能指向别处 |
| 发文属地        | `data.content.country_name` / `province_name`    | 平台展示的发文属地，不是读者所在地或家庭住址    |

当前固定输出 schema 没有声明 `_content_type`，不要要求 `_content_type` 必须出现，也不要把 `_content_type` 缺失推断成经典图文。本地导出与联表只在 `_content_type` 缺失或明确标为 article 时继续，遇到其他显式值就停下人工核对；这是本地的保守校验规则，不是动作返回分类的保证。图片页或额外元数据也不能证明整个可见页面已读。[正文阅读工作流](/zh/guides/read-wechat-article)记录“仅返回文本”的范围，并把引用逐字核对到保存的来源文本。

## 头条／次条要从文章列表取

`wechat_mp.v2.fetch_account_articles` 使用 `raw:false`、文章栏 `item_show_type:0` 时，读取 `data.articles[].idx`：1 为头条，更大的值是同一次群发内的次条位置。账号编号、`app_msg_id` 和 `idx` 一起保留，用群发内的位置判断，不用页面行号。

[头条次条筛选](/zh/faq/wechat-headline-position)提供离线导出、位置未知的处理和原始来源证据。从链接推导身份时用[链接审计](/zh/faq/wechat-link-parameters)；只有短链接时拿不到 `idx`。

## 互动指标要选对统计接口

| 项目     | 标准 `fetch_article_stats`，位于 `data` | H5 `fetch_article_stats_h5`             |
| ------ | ---------------------------------- | --------------------------------------- |
| 阅读     | `read_num`                         | 不提供，不是零                                 |
| 点赞／在看  | `like_count` / `old_like_count`    | 不提供                                     |
| 分享／收藏  | `share_count` / `collect_count`    | 不提供                                     |
| 评论数量   | `comment_count`                    | `comment_count`及`elected_comment_count` |
| star字段 | 原样保留`star_num`名称                   | 不提供；不能把 `star_num` 叫作赞赏收入               |

标准统计 `raw:true` 带 `show_*` 展示标记。隐藏、字段缺失、`null`、展示阈值和实际的零必须分开；改用 H5 统计不能恢复阅读数。[指标审核表导出](/zh/faq/wechat-article-metrics)为每个指标保留 action、URL、采集时间、原值和状态。

## 评论、回复与账号主页

评论和回复是两种请求。一级评论 `fetch_article_comments` 用 `buffer` 翻页；`fetch_comment_replies` 选定一个 `content_id`，用整数 `offset` 翻页。需要更多回复时，按 `fetch_comment_replies` 的 `offset` 续页。评论数不等于已采集的评论，一页不等于全部讨论，也不承诺取得隐藏或未公开的留言。[编号与精度规则](/zh/faq/wechat-comment-identifiers)说明了为什么出现不安全的无引号大数字编号时，必须停止依赖这个编号的回复流程；事后转成字符串恢复不了原来的数字。

`fetch_account_profile` 使用 `raw:false` 时，文档说明 `data` 下有 `user_name`、`nick_name`、`ip_wording`、`original_article_count`、`original_content_str`、`finder_username`、`finder_nickname` 和 `ban_type`。这些字段分别作为账号身份、展示属地、原创信息、关联视频号身份和原始状态码保存，不改称法律主体、注册地址、精确粉丝数或完整历史。`fetch_account_profile` 这条路线明确不提供 `signature` 和 `head_url`，空值不是用户主动留空。见[账号字段与主体边界](/zh/faq/wechat-account-profile)。

账号主页列表用 `item_show_type` 选栏：0 文章、5 视频、7 音频、8 图文贴图。每个账号、每个栏目单独保留游标；主页列表不是视频号查询。已存页导出和真实的 `next_offset` 规则见[栏目与翻页](/zh/faq/wechat-article-pagination)。

公众号公开目录没有专门查询企业主体的动作：登记主体用公开登记资料核对，粉丝数和赞赏收入到你有权访问的后台查。不要从昵称填注册号，也不要从阅读数推算粉丝。赞赏金额、私有受众分析和未选取的评论不在字段对照范围内。

## 五篇文章审核，别把所有接口都买一遍

1. 从五个确切的公开文章 URL 开始，保存每个请求 URL，不暗中合并长短链别名。调用之前先确定交付哪些列。
2. 五篇文章都要标题和正文时，计划五次 H5 详情查询；还要互动数据时，再加五次标准统计。每个动作的单价见 [BeatAPI 价格页](https://beatapi.io/zh/pricing)。
3. 需要头条位置时，复用已保存、含这篇文章身份的列表，或单独预算所需的列表页。十次详情和统计请求拿不到五篇文章的位置。主页资料、评论页和选定的回复页也按需要另计请求。
4. 用上面链接的正文导出器和统计导出器保留原始响应和哈希。按保存的“请求—文章”对应关系关联，不按标题连接。每个请求 ID 和这次请求的采集时间一起记录；先后调用不是原子快照。
5. 按保存的请求映射，用下方的 `join_article_review.py` 合并正文和标准统计导出。每篇文章交付一行：请求 URL、标题、账号编号、发布时间、正文和指标来源文件、指标观察时间，每个所需指标旁边再有状态列。有列表证据才填头条位置。缺失保持缺失；不提供、隐藏和阈值都加注释，不填零。把全文复制进摘要格不算完成分析。

合成示例：来源标题是“示例”，`read_num:null`、`show_read:false`，且没有头条证据。这一行交付标题“示例”、阅读 `null` 并标记隐藏、位置未知；不是零阅读，不是头条，也不是文章失败。

## 交付前核对两行

从表里选一行数据齐全的和一行有空值的，分别打开两篇原文，对照保存的详情、统计和列表记录。请同事确认能看出每个数的采集时间，以及每个空值是缺字段、隐藏还是查询失败。

## 把已有正文和标准统计实际合成一张审核表

先分别运行[正文来源导出器](/zh/guides/read-wechat-article)和[指标导出器](/zh/faq/wechat-article-metrics)。联表复用这两个导出器的输出，不再查询。准备 `pairs.json`，每条记录明确指向一篇来源记录、一个指标目录，以及 `evidence.json` 中 requests 的第几个元素（从 1 开始）：

```json
[{"source_record":"article-1/wechat-article-source.json","metric_directory":"metric-review","metric_source_index":1}]
```

保留每条来源记录引用的原始 `wechat-article.json`。配对路径相对于 `pairs.json`；记录内部的 `source_file` 相对于这条来源记录所在目录（已经是绝对路径的保持不变）。最多五对，逐对手工选定，不按标题猜配，也不自动合并短长链别名。详情和统计两边记录的原请求 URL 必须逐字相同，不拿正文返回的另一个 link 暗中替代匹配键。

把下面的代码保存为 `join_article_review.py`，运行 `python3 join_article_review.py pairs.json article-review`：

```python
import csv, hashlib, json, pathlib, sys
from datetime import datetime, timezone
from urllib.parse import urlsplit, parse_qs

manifest, output = map(pathlib.Path, sys.argv[1:3])
manifest_bytes = manifest.read_bytes()
entries = json.loads(manifest_bytes)
if not isinstance(entries, list) or not 1 <= len(entries) <= 5:
    raise ValueError('Provide 1–5 explicit article pairs')
DETAIL = 'wechat_mp.v2.fetch_article_detail_h5'
STATS = 'wechat_mp.v2.fetch_article_stats'
metrics = {'read_num':'show_read','like_count':'show_like','old_like_count':'show_old_like','share_count':'show_share','collect_count':'show_collect','comment_count':'comment_enabled','star_num':'show_star'}
rows, evidence, archives, urls, ids = [], [], [], set(), set()
def load(path):
    raw = path.read_bytes()
    return json.loads(raw), raw
def sha(raw): return hashlib.sha256(raw).hexdigest()
def time(value):
    if not isinstance(value, str): raise ValueError('Collection time missing')
    parsed = datetime.fromisoformat(value.replace('Z','+00:00'))
    if parsed.tzinfo is None: raise ValueError('Collection time needs timezone')
    return value
def url(value):
    if not isinstance(value, str) or any(c.isspace() or ord(c)<32 for c in value): raise ValueError('Invalid request URL')
    u = urlsplit(value); q = parse_qs(u.query, keep_blank_values=True)
    if u.scheme not in ('https','http') 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('Expected public article URL')
    if any(k.lower() in ('key','uin','pass_ticket','ticket','access_token') for k in q): raise ValueError('Use a public share URL without session data')
    if u.path == '/s':
        if any(len(q.get(k,[]))!=1 or not q[k][0] for k in ('__biz','mid','idx')): raise ValueError('Ambiguous long URL')
        if not all(q[k][0].isascii() and q[k][0].isdigit() for k in ('mid','idx')) or int(q['idx'][0])<1: raise ValueError('Invalid article position')
    elif not u.path.startswith('/s/') or not u.path[3:] or '/' in u.path[3:]: raise ValueError('Missing article token')
    return value
def success(body, action, expected_id):
    if not isinstance(body,dict) or body.get('status')!='succeeded' or body.get('action')!=action or body.get('error') is not None or not isinstance(body.get('data'),dict): raise ValueError('Expected successful recorded action')
    rid=body.get('request_id')
    if not isinstance(rid,str) or not rid.strip() or rid!=expected_id or rid in ids: raise ValueError('Missing, mismatched or reused request ID')
    ids.add(rid)
    return body['data']
def classify(value, present):
    if not present: return 'missing', None
    if value is None: return 'null', None
    if isinstance(value,bool): return 'invalid_boolean', None
    if type(value) is int:
        if value>9007199254740991:return 'unsafe_numeric',None
        return ('reported_integer',str(value)) if value>=0 else ('invalid_negative',None)
    if isinstance(value,str):return ('reported_integer',value) if value.isascii() and value.isdigit() else ('reported_text',None)
    raise ValueError('Structured or floating metric unsupported')
for index, entry in enumerate(entries,1):
    if set(entry)!={'source_record','metric_directory','metric_source_index'}: raise ValueError('Use explicit source record and metric evidence index')
    record_path = manifest.parent / entry['source_record']
    record, record_bytes = load(record_path)
    requested = url(record['requested_url'])
    if requested in urls: raise ValueError('Duplicate requested URL; choose one observation explicitly')
    urls.add(requested)
    detail_path = record_path.parent / record['source_file']
    detail, detail_bytes = load(detail_path)
    if record.get('source_sha256')!=sha(detail_bytes):raise ValueError('Detail hash mismatch')
    data = success(detail,DETAIL,record.get('request_id')); article=data.get('content')
    if not isinstance(article,dict) or article.get('_content_type') not in (None,'article'):raise ValueError('Need a classic article source')
    body=article.get('content_text')
    if not isinstance(body,str) or not body.strip() or body!=record.get('text'):raise ValueError('Source text differs from recorded detail')
    if body.strip() in ('[redacted]','[redacted-depth]') or (isinstance(article.get('desc'),str) and body.strip()==article['desc'].strip()):raise ValueError('Body is redacted or identical to summary')
    if data.get('url') is not None and data['url']!=requested:raise ValueError('Detail request URL mismatch')
    for field,key in [('title','title'),('user_name','account_id'),('nick_name','account_name')]:
        if article.get(field)!=record.get(key) or (record.get(key) is not None and not isinstance(record[key],str)):raise ValueError('Detail metadata mismatch')
    returned=article.get('link'); chosen=url(returned) if returned not in (None,'') else requested
    if chosen!=record.get('article_url'):raise ValueError('Returned article URL mismatch')
    detail_time=time(record.get('collected_at'))
    stamp=article.get('create_timestamp')
    if stamp is not None and (isinstance(stamp,bool) or not isinstance(stamp,(int,float))):raise ValueError('Invalid publication timestamp')
    published=datetime.fromtimestamp(stamp,timezone.utc).isoformat() if stamp is not None else None
    if published!=record.get('published_at_utc'):raise ValueError('Publication time mismatch')
    metric_dir=manifest.parent / entry['metric_directory']
    metric_evidence, metric_evidence_bytes=load(metric_dir/'evidence.json')
    n=entry['metric_source_index']; requests=metric_evidence.get('requests')
    if type(n) is not int or not isinstance(requests,list) or not 1<=n<=len(requests):raise ValueError('Invalid metric source index')
    m=requests[n-1]; params=m.get('params')
    if m.get('action')!=STATS or type(m.get('http_status')) is not int or m['http_status']!=200 or m.get('error_code') is not None:raise ValueError('Need successful standard stats, not H5 or failure')
    if not isinstance(params,dict) or set(params)!={'url','raw'} or params['url']!=requested or type(params['raw']) is not bool:raise ValueError('Pair by exact recorded request URL, not title or guessed alias')
    stats, stats_bytes=load(metric_dir/('raw-%03d.json'%n))
    if m.get('sha256')!=sha(stats_bytes):raise ValueError('Stats hash mismatch')
    counts=success(stats,STATS,m.get('request_id')); stats_time=time(m.get('collected_at'))
    unavailable=counts.get('unavailable',[])
    if not isinstance(unavailable,list) or any(not isinstance(x,str) for x in unavailable):raise ValueError('Invalid unavailable flags')
    row={'requested_url':requested,'article_url':chosen,'title':record.get('title'),'account_id':record.get('account_id'),'published_at_utc':published,'detail_collected_at':detail_time,'stats_collected_at':stats_time,'detail_request_id':record['request_id'],'stats_request_id':m['request_id'],'get_data_succ_raw':json.dumps(counts.get('get_data_succ')),'position_state':'not_joined','coverage':'returned_plain_text_and_one_stats_observation'}
    for metric,flag in metrics.items():
        raw_value=counts.get(metric);state,value=classify(raw_value,metric in counts)
        if metric in unavailable:state,value=('unavailable' if raw_value is None else 'inconsistent_unavailable'),None
        row[metric+'_value']=value;row[metric+'_state']=state
        row[metric+'_raw']=json.dumps(raw_value,ensure_ascii=False)
        row[metric+'_visibility_raw']=json.dumps(counts.get(flag),ensure_ascii=False)
    rows.append(row)
    prefix='article-%02d-'%index
    files={prefix+'source-record.json':record_bytes,prefix+'detail.json':detail_bytes,prefix+'metric-evidence.json':metric_evidence_bytes,prefix+'stats.json':stats_bytes}
    archives.extend(files.items())
    evidence.append({'requested_url':requested,'input_pair':entry,'files':{name:sha(raw) for name,raw in files.items()},'detail_request_url_echo_verified':data.get('url')==requested,'identity_basis':'saved request metadata; no network identity verification'})
def cell(value):
    if value is None:return ''
    value=str(value)
    return "'"+value if value.startswith(('=','+','-','@','\t','\r','\n')) else value
output.mkdir(parents=False,exist_ok=False)
with (output/'article-review.csv').open('x',encoding='utf-8-sig',newline='') as f:
    writer=csv.DictWriter(f,fieldnames=list(rows[0]));writer.writeheader();writer.writerows({k:cell(v) for k,v in row.items()} for row in rows)
for name,raw in archives:(output/name).write_bytes(raw)
(output/'pair-manifest.json').write_bytes(manifest_bytes)
(output/'review-evidence.json').write_text(json.dumps({'manifest_sha256':sha(manifest_bytes),'articles':evidence,'executed_calls':0,'atomic_snapshot':False,'automatic_ranking':False,'position_joined':False},ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'articles':len(rows),'executed_calls':0}))
```

新目录里的 `article-review.csv` 每篇文章一行，正文和统计分别保留采集时间和请求编号，每项指标有 `value`/`state`/`raw`/`visibility_raw` 四列。`review-evidence.json` 和归档原件保留文件哈希；CSV 单元格加的安全前缀不改变归档原文。`join_article_review.py` 从原始统计重新分类，不信任可编辑的 `metrics.csv` 数值，还核对来源记录的标题、账号、正文和发布时间与详情原件一致。

| 输入情况                      | 结果                   |
| ------------------------- | -------------------- |
| 同一原请求 URL，两个动作都成功且文件哈希吻合  | 合成一行，仍是两次独立观察，不是原子快照 |
| 标题相同但 URL 不同，或猜测短长链等价     | 拒绝配对，不自动归一化          |
| H5 统计或失败统计                | 拒绝该批次，不拿缺失阅读写成 0     |
| 同一文章重复配对或 request_id 复用   | 拒绝，先明确选择哪次观察         |
| 原件/来源字段被改，哈希或内容不匹配        | 创建输出目录前停止，保留旧表       |
| 显隐标记为 false，数值为 null/阈值/零 | 原状态保留，不据此自动排名或估计人数   |

`position_state` 固定为 `not_joined`，因为 `join_article_review.py` 不联入列表里的头条证据；`join_article_review.py` 也不采集评论、回复或主页资料。只有整批校验通过才生成审核表；校验失败时修正来源配对，不要删掉校验或默默丢掉失败的文章。文件系统写入失败时，把这次输出视为不完整；原始输入保持不变，半张表不算验收通过。

哈希证明归档字节一致，不证明文章内容真实，也不独立认证可编辑请求元数据的网络来源。原始正文、指标和证据目录可能含私有工作信息，默认在本地保管；分享时另做核对过的脱敏副本。本地生成不产生新的 BeatAPI 请求。

[公众号问题目录](/zh/faq/wechat)