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

# 公众号文章是头条还是次条？如何从已存列表筛选？

> 使用文章在群发内的 idx，而不是列表行号，分别导出头条/次条并保留缺失位置，不吞掉同群发的其他文章。

区分头条和次条，看 `wechat_mp.v2.fetch_account_articles` 返回的文章列表里的 **`idx`**：`1` 是这次群发的头条，`2` 是第二篇，更大的值是后续位置。要整理每次推送排在最前面的文章，就筛 `idx=1`；要研究整次群发的内容，就保留同次群发的全部文章。

## 为什么不能按结果页的第一行判断头条？

一页 API 结果可能包含多次群发，也可能从某次群发的中间开始。头条看的是文章**在所属群发里的位置**，不是文章在本页的行号。

例如一页里有两次群发的文章：

| 群发 | idx | 标题示例    | 分类     |
| -- | --- | ------- | ------ |
| A  | 1   | 新产品发布   | 头条     |
| A  | 2   | 新产品使用方法 | 次条，第2篇 |
| B  | 1   | 本周专访    | 头条     |

筛选后有两篇头条、一篇次条。群发 A 的两篇文章共享同一个 `app_msg_id`，也要分别保存：文章身份由账号、`app_msg_id` 和 `idx` 一起确定。

## 只整理头条，怎么做？

1. 用已确认的账号取得[文章列表](/zh/guides/wechat-account-articles)，选择文章栏、`raw:false`。
2. 读取 `data.articles[].idx`，保留值为 1 的文章，列出标题、原文链接和发布时间。
3. 需要次条对照时，另存 `idx>1` 的记录；没有返回位置的记录单列为待核。

已有列表响应就直接筛选，不必为了知道位置逐篇再取正文，列表的 `idx` 字段已经给出位置。只有一篇文章链接时，先按[文章到账号定位](/zh/faq/wechat-account-identifier)找到账号，再在账号的文章列表里定位文章。

把整理交给已接入 BeatAPI 的助手时，可以这样布置：

> 整理目标公众号最近 3 页文章，只保留头条，列出标题、链接和发布时间。次条另存一份；位置缺失的记录列为待核。整理完成后告诉我实际得到多少篇头条。

## `article_positions.py` 导出后，先看哪几个文件？

`article_positions.py`（见最后一节）把已保存的列表页拆成四个文件：

* `headlines.csv`：`idx=1` 的头条。
* `secondary.csv`：后续文章，保留具体篇序。
* `unknown-position.json`：位置没有返回的记录。
* `coverage.json`：本批处理的页数来源、文章分布和数量。

某次群发只看到第 2 篇时，先保留这条次条，回查列表时再补这次群发的第一篇。需要比较阅读表现时，先按头条和次条分组，再结合发布时间与题材看数据，接着用[互动统计](/zh/faq/wechat-article-metrics)整理选中的文章。取数价格见[价格页](https://beatapi.io/zh/pricing)。

## 附：从已存列表导出

列表请求使用 `data:wechat_mp.v2.fetch_account_articles`；取回列表后，`article_positions.py` 在本地筛选已保存的响应。

`article_positions.py` 接受同一个规范 `gh_` 账号、文章栏、`raw:false` 的 1–20 个已存页面。清单里记录实际请求、时间和文件；后续每一页使用上一页响应的 `next_offset`。

`history-pages.json` 格式如下，替换为自己的记录：

```json
[
  {"file":"articles-page-1.json","action":"wechat_mp.v2.fetch_account_articles","http_status":200,"collected_at":"2026-11-16T10:00:00Z","params":{"username":"gh_example","raw":false,"item_show_type":0}}
]
```

保存代码为 `article_positions.py`，执行：

```bash
python3 article_positions.py history-pages.json position-review
```

```python
import csv, datetime, hashlib, json, pathlib, re, sys
manifest=pathlib.Path(sys.argv[1]);manifest_bytes=manifest.read_bytes();pages=json.loads(manifest_bytes)
if not isinstance(pages,list) or not 1<=len(pages)<=20: raise ValueError('Use 1..20 saved article-list pages')
ACTION='wechat_mp.v2.fetch_account_articles'
rows,unknown,seen,requests,archives,sources=[],[],{},set(),[],[]
account=None;next_offset=None;last_time=None;used_offsets=set()
def identifier(value):
    if type(value) is int and 1<=value<=9007199254740991:return str(value)
    if isinstance(value,str) and re.fullmatch(r'[0-9]+',value) and int(value)>0:return str(int(value))
    raise ValueError('Use original positive digit strings or safe integers')
for page_index,page in enumerate(pages):
    params=page['params'];username=params.get('username')
    if not isinstance(username,str) or not re.fullmatch(r'gh_[A-Za-z0-9_]+',username):raise ValueError('Use the canonical account username')
    if account is None:account=username
    if username!=account or params.get('raw') is not False or type(params.get('item_show_type')) is not int or params['item_show_type']!=0:raise ValueError('Same account, explicit raw=false and article tab 0 required')
    if page_index and (not isinstance(next_offset,str) or not next_offset or params.get('offset')!=next_offset):raise ValueError('Saved pages do not follow the previous cursor')
    offset=params.get('offset','')
    if not isinstance(offset,str) or offset in used_offsets:raise ValueError('Repeated or invalid requested cursor')
    used_offsets.add(offset)
    time=datetime.datetime.fromisoformat(page['collected_at'].replace('Z','+00:00'))
    if time.utcoffset() is None or (last_time is not None and time<last_time):raise ValueError('Use ordered actual collection times with timezone')
    last_time=time
    if page.get('action')!=ACTION or type(page.get('http_status')) is not int or page['http_status']!=200:raise ValueError('Expected successful recorded article-list request')
    raw=(manifest.parent/page['file']).read_bytes();response=json.loads(raw)
    rid=response.get('request_id')
    if not isinstance(rid,str) or not rid.strip() or rid in requests:raise ValueError('Missing/repeated request ID')
    requests.add(rid)
    if response.get('status')!='succeeded' or response.get('error') is not None or response.get('action')!=ACTION:raise ValueError('Failed or wrong response')
    data=response['data']
    if data.get('biz_username')!=account or not isinstance(data.get('articles'),list):raise ValueError('Wrong account or simplified article shape missing')
    if type(data.get('is_end')) is not int or data['is_end'] not in (0,1):raise ValueError('Invalid end marker')
    next_offset=None if data['is_end']==1 else data.get('next_offset')
    if next_offset is not None and (not isinstance(next_offset,str) or not next_offset or next_offset in used_offsets):raise ValueError('Repeated or invalid continuation cursor')
    name='raw-'+str(page_index+1).zfill(3)+'.json';digest=hashlib.sha256(raw).hexdigest();archives.append((name,raw));sources.append({'file':name,'sha256':digest,'request_id':rid,'collected_at':page['collected_at']})
    for position,article in enumerate(data['articles'],1):
        if not isinstance(article,dict):raise ValueError('Unreadable article object')
        appid=identifier(article.get('app_msg_id'))
        idx=None if article.get('idx') is None else int(identifier(article['idx']))
        values={k:article.get(k) for k in ['title','url','create_time']}
        if values['title'] is not None and not isinstance(values['title'],str):raise ValueError('Invalid title')
        if values['url'] is not None and not isinstance(values['url'],str):raise ValueError('Invalid article URL field')
        published=values['create_time']
        if published is not None and not ((type(published) is int and 0<=published<=9007199254740991) or (isinstance(published,str) and re.fullmatch(r'[0-9]+',published))):raise ValueError('Invalid raw publication timestamp')
        row={'account':account,'app_msg_id':appid,'idx':idx,'placement':'unknown' if idx is None else 'headline' if idx==1 else 'secondary',
             **values,'request_id':rid,'collected_at':page['collected_at'],'source_file':name,'source_sha256':digest,'item_position_on_page':position}
        if idx is None:unknown.append(row);continue
        key=(appid,idx)
        if key in seen:
            if any(seen[key][k]!=row[k] for k in values):raise ValueError('Conflicting duplicate article metadata; split observations for review')
            continue
        seen[key]=row;rows.append(row)
out=pathlib.Path(sys.argv[2]);out.mkdir()
for name,raw in archives:(out/name).write_bytes(raw)
(out/'input-manifest.json').write_bytes(manifest_bytes)
for name,value in [('articles.json',rows),('unknown-position.json',unknown),('coverage.json',{'account':account,
    'known_position_articles':len(rows),'headlines':sum(r['idx']==1 for r in rows),'secondary_articles':sum(r['idx']>1 for r in rows),
    'unknown_position_observations':len(unknown),'sources':sources,'manifest_sha256':hashlib.sha256(manifest_bytes).hexdigest(),
    'observed_groups':[{'app_msg_id':appid,'positions':sorted(r['idx'] for r in rows if r['app_msg_id']==appid),'complete_group_verified':False} for appid in sorted({r['app_msg_id'] for r in rows})],
    'complete_history':False,'executed_calls':0})]:
    (out/name).write_text(json.dumps(value,ensure_ascii=False,indent=2),encoding='utf-8')
fields=['account','app_msg_id','idx','placement','title','url','create_time','collected_at','request_id','source_file','source_sha256']
for filename,selected in [('headlines.csv',[r for r in rows if r['idx']==1]),('secondary.csv',[r for r in rows if r['idx']>1])]:
    with (out/filename).open('w',encoding='utf-8-sig',newline='') as f:
        w=csv.DictWriter(f,fieldnames=fields);w.writeheader()
        for row in selected:
            cells={k:'' if row[k] is None else str(row[k]) for k in fields};w.writerow({k:"'"+v if v.lstrip().startswith(('=','+','-','@')) else v for k,v in cells.items()})
print(json.dumps({'headlines':sum(r['idx']==1 for r in rows),'secondary':sum(r['idx']>1 for r in rows),'unknown':len(unknown),'executed_calls':0}))
```