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

# 怎样整理一个视频号的作品目录，再挑出值得研究的视频？

> 按账号收集作品，区分作品列表与主题搜索，保存连续页并从点赞、转发等指标挑选研究样本。

要导出一个视频号账号的作品，把账号的 `@finder` 标识作为 `username` 传给 `wechat_channels.v2.fetch_user_videos`，逐页保存响应，再对保存的页面运行 `export_channel_pages.py`，生成 `selected-videos.csv`、`metric-rankings.csv` 和 `coverage.json`。只想找某个创作者关于某款产品的作品时，改用号内关键词搜索 `wechat_channels.v2.fetch_search_channel_videos`。

## 先选列表，还是号内搜索？

| 你的目标          | 使用方式                                                          | 下一页                                            |
| ------------- | ------------------------------------------------------------- | ---------------------------------------------- |
| 整理指定账号发布的作品   | `data:wechat_channels.v2.fetch_user_videos`，`raw:false`       | 用 `up_continue` 判断续页，把返回的 `last_buffer` 传回同名参数 |
| 找指定账号关于一个词的作品 | `data:wechat_channels.v2.fetch_search_channel_videos`，传账号与关键词 | 首次 `cursor` 留空，后续用返回的 `next_cursor`            |

两种方式都从已确认的 finder username 开始。有 `sph…` 短号或作品分享链接时，先按[账号与作品标识](/zh/faq/wechat-channels-identifiers)找到正确入口；已有规范账号标识就直接复用。

## 把一个账号整理成可选案例的表

1. **设定范围。** 例如先收集最近一个月的作品，列文案、发布时间、作品ID和可返回的互动数。
2. **取得列表。** 向 `POST /v1/social-data/call` 发送 `action:"wechat_channels.v2.fetch_user_videos"`，参数为已确认的 `username`、`raw:false` 和首次的 `last_buffer:""`。作品在 `data.videos` 里，响应同时带有账号和续页字段。
3. **沿同一账号继续。** 保存每页的请求、响应和采集时间，再把最新一页返回的 `last_buffer` 作为下一次的 `last_buffer`。账号和 `raw:false` 保持不变；请求失败时，保留最后一个成功页供核对。
4. **看表选视频。** 用下方的 `export_channel_pages.py` 整理保存的页面，按主题挑作品，分别比较点赞数和转发数。对值得深入研究的作品，再取详情或读[评论](/zh/faq/wechat-channels-comments)。

把任务交给已连接 BeatAPI 的助手时，可以用这段指令：

> 整理这个视频号最近一个月的作品，保留文案、发布时间、作品ID和实际返回的点赞、转发数。分别列出这批样本的点赞与转发前10名，挑出与新品发布有关的案例，说明入选理由和实际检查范围。

先用返回的 `create_time` 核对时间范围，再做主题筛选。名次只反映本次取得的作品；分析案例时还要结合发布时间和具体内容，不能只看累计计数。

## 导出后，先看哪几个文件？

* `selected-videos.csv`：按可用作品ID整理出的选中记录，适合浏览和筛选。
* `video-observations.csv`：每次返回的原始观察，方便回看更新与重复记录。
* `metric-rankings.csv` / `.json`：分别按精确点赞、转发计数排名。
* `coverage.json`：实际观察与选中数量、停止原因、缺失或冲突记录。

计数缺失的作品仍可按内容选用，但不放进数值排名。`read_count` 目前的口径定义不足以把 `read_count` 标成别人的播放量；保留原字段名 `read_count`，研究互动时用已确认的点赞、转发等字段。

## 只找某个主题，怎样少翻一些页？

使用[号内主题搜索](/zh/guides/wechat-channels-channel-search)：保持账号和关键词不变，按 `next_cursor → cursor` 续页。号内主题搜索只搜指定账号；要做更广的发现任务，另选搜一搜入口。

列表、搜索、评论各自保存续页状态。评论用 `data:wechat_channels.v2.fetch_video_comments`；一级评论列表与某条父评论的回复分别续页，具体见[评论导出](/zh/faq/wechat-channels-comments)。

下面是已保存作品页的导出与排名方法。每批处理 1–20 页；一批停在页数上限时，这一批的覆盖范围就到上限为止，更早的历史分批采集、另行合并。当前单价见[价格页](https://beatapi.io/zh/pricing)；在本地整理已保存的页面不需要重新查询。

## 将已保存的账号作品页导成可审核的表格

已知 finder username 时，用 `fetch_user_videos`，不用前面的号内关键词搜索。明确传 `raw:false` 时，响应包含 `data.username`、`videos`、`up_continue` 和 `last_buffer`。发布文档中的作品字段包括 `id`、`title`、`create_time`、`read_count`、`like_count`、`fav_count`、`forward_count`、`comment_count`、`location`。`export_channel_pages.py` 保留每个字段的原值以及字段是否存在，不把 `read_count` 解释成已验证的独立观众，也不把缺失的计数填成零。

[公众号关联证据](/zh/faq/wechat-account-profile)已经给出合法的 finder username 时直接复用。首页 `last_buffer` 留空，之后保持账号和 `raw:false` 不变，并记录每页实际返回的条数。列表费用按页请求数和[当前价格](https://beatapi.io/zh/pricing)计算。

保存每次实际请求的请求体、HTTP 状态、响应和采集时间。`pages.json` 从第二页起，每页的 `last_buffer` 必须与上一页响应返回的 `last_buffer` 完全一致。下面的示例只说明格式，不是录制的响应：

```json
[{"action":"wechat_channels.v2.fetch_user_videos","params":{"username":"v2_123abc@finder","raw":false,"last_buffer":""},"http_status":200,"collected_at":"2026-11-17T09:00:00Z","response_file":"page-1.json"}]
```

把下面的脚本保存为 `export_channel_pages.py`，运行 `python3 export_channel_pages.py pages.json channel-review`。响应路径相对于 `pages.json`，输出用新目录。只对已保存的完整 JSON 运行，不要用截断的预览。脚本不发请求。

```python
import csv,hashlib,json,pathlib,re,sys
from datetime import datetime
manifest,out=map(pathlib.Path,sys.argv[1:3]);original=manifest.read_bytes();pages=json.loads(original)
if not isinstance(pages,list) or not 1<=len(pages)<=20:raise ValueError('Supply 1–20 saved pages')
ACTION='wechat_channels.v2.fetch_user_videos';rows,sources,ids,rids,cursors=[],[],set(),set(),set();expected='';account=None;stop=None;unsafe=0
def cell(v):
 if v is None:return ''
 v=str(v);return "'"+v if v.startswith(('=','+','-','@','\t','\r','\n')) else v
def identity(v):
 if isinstance(v,str) and re.fullmatch(r'[0-9]{1,32}',v):return v,'string'
 if type(v) is int and 0<=v<=9007199254740991:return str(v),'safe_integer'
 return None,'unsafe_or_invalid'
for i,e in enumerate(pages,1):
 if stop is not None:raise ValueError('Pages supplied after stop condition')
 params=e.get('params');u=params.get('username') if isinstance(params,dict) else None
 if e.get('action')!=ACTION or not isinstance(params,dict) or set(params)!={'username','raw','last_buffer'} or params['raw'] is not False:raise ValueError('Use exact raw:false list request')
 if not isinstance(u,str) or not 10<=len(u)<=256 or not re.fullmatch(r'v2_[0-9a-fA-F]+@finder',u):raise ValueError('Invalid finder username')
 if account is None:account=u
 if u!=account or params['last_buffer']!=expected:raise ValueError('Account or cursor chain changed')
 cursors.add(expected)
 t=e.get('collected_at')
 if not isinstance(t,str) or datetime.fromisoformat(t.replace('Z','+00:00')).tzinfo is None:raise ValueError('Record actual collection time with timezone')
 http=e.get('http_status')
 if type(http) is not int or not 100<=http<=599:raise ValueError('Invalid HTTP status')
 raw=(manifest.parent/e['response_file']).read_bytes();body=json.loads(raw)
 if not isinstance(body,dict):raise ValueError('Expected response object')
 source={'index':i,'request':e,'sha256':hashlib.sha256(raw).hexdigest(),'raw_file':'raw-%02d.json'%i};sources.append((source,raw))
 if http!=200:
  error=body.get('error')
  if not isinstance(error,dict) or not isinstance(error.get('code'),str) or not error['code'].strip():raise ValueError('Expected gateway error')
  source.update(error_code=error['code'],request_id=error.get('request_id'));stop='gateway_failed';continue
 data=body.get('data');rid=body.get('request_id')
 if body.get('status')!='succeeded' or body.get('action')!=ACTION or body.get('error') is not None or not isinstance(data,dict):raise ValueError('Wrong successful envelope')
 if not isinstance(rid,str) or not rid.strip() or rid in rids:raise ValueError('Missing or duplicate request ID')
 rids.add(rid);source['request_id']=rid
 if data.get('username')!=account or not isinstance(data.get('videos'),list):raise ValueError('Missing account echo or videos array')
 videos=data['videos'];source['reported_count']=data.get('count');source['observations']=len(videos)
 for j,v in enumerate(videos):
  if not isinstance(v,dict) or (v.get('username') is not None and v['username']!=account):raise ValueError('Video author mismatch')
  object_id,state=identity(v.get('id'));duplicate=object_id in ids if object_id is not None else False
  if object_id is None:unsafe+=1
  else:ids.add(object_id)
  row={'account':account,'object_id':object_id,'id_state':state,'id_raw':json.dumps(v.get('id')),'duplicate_observation':str(duplicate).lower(),'title':v.get('title'),'collected_at':t,'request_id':rid,'source_index':i,'video_index':j}
  if row['title'] is not None and not isinstance(row['title'],str):raise ValueError('Invalid title')
  for field in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']:
   row[field+'_raw']=json.dumps(v.get(field),ensure_ascii=False);row[field+'_present']=str(field in v).lower()
  rows.append(row)
 flag=data.get('up_continue');cursor=data.get('last_buffer');source.update(up_continue=flag,last_buffer=cursor)
 if type(flag) not in (bool,int) or flag not in (0,1):stop='unsupported_more_flag'
 elif not flag:stop='provider_end'
 elif not videos:stop='empty_page_with_more'
 elif not isinstance(cursor,str) or not cursor or not re.fullmatch(r'[A-Za-z0-9+/=_-]+',cursor):stop='missing_or_invalid_cursor'
 elif cursor in cursors:stop='repeated_cursor'
 else:expected=cursor
if stop is None:stop='saved_page_limit'
columns=['account','object_id','id_state','id_raw','duplicate_observation','title','collected_at','request_id','source_index','video_index']
for field in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']:columns.extend([field+'_raw',field+'_present'])
groups={}
for row in rows:
 if row['object_id'] is not None:groups.setdefault(row['object_id'],[]).append(row)
selected,conflicts=[],[]
for object_id,observations in groups.items():
 latest=max(datetime.fromisoformat(r['collected_at'].replace('Z','+00:00')) for r in observations)
 candidates=[r for r in observations if datetime.fromisoformat(r['collected_at'].replace('Z','+00:00'))==latest]
 def values(r):return {k:r[k] for k in ['title']+[f+'_raw' for f in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']]+[f+'_present' for f in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']]}
 if any(values(r)!=values(candidates[0]) for r in candidates[1:]):
  conflicts.append({'object_id':object_id,'reason':'conflicting_newest_observations','sources':[{'source_index':r['source_index'],'video_index':r['video_index']} for r in candidates]})
 else:selected.append(candidates[0])
ranked=[];ranking_coverage={}
def count_state(row,metric):
 if row[metric+'_present']!='true':return None,'missing'
 value=json.loads(row[metric+'_raw'])
 if value is None:return None,'null'
 if type(value) is int:
  return (value,'exact_integer') if 0<=value<=9007199254740991 else (None,'unsafe_or_negative_number')
 if isinstance(value,str) and re.fullmatch(r'[0-9]{1,64}',value):return int(value),'exact_digit_string'
 return None,'unsupported_value'
for metric in ['like_count','forward_count']:
 entries=[]
 for row in selected:
  number,state=count_state(row,metric)
  entries.append({'object_id':row['object_id'],'title':row['title'],'collected_at':row['collected_at'],'metric':metric,'value_raw':row[metric+'_raw'],'value_state':state,'exact_count':str(number) if number is not None else '', 'rank':'','request_id':row['request_id'],'source_index':row['source_index'],'video_index':row['video_index'],'_number':number})
 entries.sort(key=lambda e:(e['_number'] is None,-e['_number'] if e['_number'] is not None else 0,e['object_id']))
 previous=None;rank=None;eligible=0
 for entry in entries:
  number=entry.pop('_number')
  if number is not None:
   eligible+=1
   if number!=previous:rank=eligible
   entry['rank']=rank;previous=number
 ranked.extend(entries)
 ranking_coverage[metric]={'eligible_videos':eligible,'unranked_videos':len(entries)-eligible,'tie_rule':'competition ranks; equal counts share rank','scope':'selected usable IDs only; not plays or unique viewers'}
out.mkdir(mode=0o700,exist_ok=False)
with (out/'video-observations.csv').open('x',encoding='utf-8-sig',newline='') as f:
 w=csv.DictWriter(f,fieldnames=columns);w.writeheader();w.writerows({k:cell(v) for k,v in r.items()} for r in rows)
with (out/'selected-videos.csv').open('x',encoding='utf-8-sig',newline='') as f:
 w=csv.DictWriter(f,fieldnames=columns);w.writeheader();w.writerows({k:cell(v) for k,v in r.items()} for r in selected)
with (out/'metric-rankings.csv').open('x',encoding='utf-8-sig',newline='') as f:
 fields=['object_id','title','collected_at','metric','value_raw','value_state','exact_count','rank','request_id','source_index','video_index']
 w=csv.DictWriter(f,fieldnames=fields);w.writeheader();w.writerows({k:cell(v) for k,v in r.items()} for r in ranked)
(out/'metric-rankings.json').write_text(json.dumps(ranked,ensure_ascii=False,indent=2),encoding='utf-8')
(out/'selection-conflicts.json').write_text(json.dumps(conflicts,ensure_ascii=False,indent=2),encoding='utf-8')
for source,raw in sources:(out/source['raw_file']).write_bytes(raw)
(out/'manifest.json').write_bytes(original)
report={'ranking_coverage':ranking_coverage,'account':account,'sources':[s for s,_ in sources],'stop_reason':stop,'video_observations':len(rows),'distinct_usable_ids':len(ids),'selected_unique_videos':len(selected),'conflicting_ids':len(conflicts),'selection_rule':'latest recorded collection time; equal-time disagreements withheld','unsafe_id_observations':unsafe,'provider_end_seen':stop=='provider_end','all_account_history_verified':False,'media_downloaded':False,'executed_calls':0,'manifest_sha256':hashlib.sha256(original).hexdigest()}
(out/'coverage.json').write_text(json.dumps(report,ensure_ascii=False,indent=2),encoding='utf-8')
if stop=='saved_page_limit':(out/'unexecuted-next-request.json').write_text(json.dumps({'action':ACTION,'params':{'username':account,'raw':False,'last_buffer':expected}},indent=2),encoding='utf-8')
print(json.dumps({'observations':len(rows),'stop_reason':stop,'executed_calls':0}))
```

`video-observations.csv` 一行是一条返回的观察，不保证一行对应一个唯一作品。同一可用 ID 再次出现时会被标记为重复，不会默默覆盖较早的互动量。`coverage.json` 给出不同可用 ID 的数量、不安全 ID 的行、确切的来源下标和停止原因。`*_present` 和 `*_raw` 两类列区分缺失和 null。超过 2^53−1 的裸数字 ID 会被隔离，`object_id` 不给可用值；网关可能已经舍入，事后转成字符串也恢复不了丢失的末位。被隔离的行不能用来继续查详情或评论，也不能按标题去重。

`provider_end` 只表示已保存的分页链到达了服务端报告的终点，不证明账号历史完整。空页却报告还有更多、游标重复或缺失、续页标记未知，这几种情况都会停止，不生成下一请求。末页出现网关错误时，保留此前的观察和错误证据；结构、身份或分页链错误会在创建输出前拒绝整批。只因已保存页数达到上限而停止时，`unexecuted-next-request.json` 保存续页请求，但不代表获得授权，也没有执行。换账号或换 raw 模式要重新开始分页链。

CSV 文件刻意不含媒体 URL token 和解密密钥。完整原始响应可能包含这些 token 和密钥，所以新输出目录默认私有；原件留在本地，分享时另做审核、脱敏后的副本。本流程不下载、解密、发布或发送媒体。文件写入中断不算导出完成；排除中断原因后写到新的输出目录，不覆盖原始证据。

## 哪份文件是一条作品一行？

用 `selected-videos.csv` 查看选出的子集，同时保留 `video-observations.csv` 作为全部返回观察的日志。程序只按可用 ID 分组，取记录的最新采集时间，不按文件里的先后顺序。最新时刻的多份观察在选定的内容和指标字段上完全一致时，取第一份来源引用；同一最新时刻互相矛盾的值写入 `selection-conflicts.json`，不进入选中表。旧观察仍保留在日志里；不同账号的作品不会合并。

`coverage.json` 分别报告 `selected_unique_videos`、`conflicting_ids` 和 `unsafe_id_observations`。`selected-videos.csv` 的行数可能少于不同可用 ID 的数量；交付前先检查被排除的 ID，再决定能否称为完整。导出器不会给不安全或冲突的作品编造一行零。采集时间来自你提供的请求证据，不是作品发布时间，也不证明平台在那一刻刷新了指标。`selected-videos.csv` 不是同龄作品的表现排名，也不代表完整历史。

## read_count 能直接写成别人的视频播放量吗？

只凭 `fetch_user_videos` 的合同不能这样写。已核对的账号作品结构把 `read_count` 列为返回的互动计数，但没有定义 `read_count` 计的是独立观众、实际播放、重复观看还是完播。保留原字段名 `read_count`，不要改叫 `plays`，不要用 `read_count` 算完播率，也不要推断创作者后台的私有分析数据。字段缺失不是零；别家没有某个字段，也不能证明 `fetch_user_videos` 返回什么。

如果实际任务是“所采样作品里，哪些报告的点赞或转发最多”，`export_channel_pages.py` 会生成 `metric-rankings.csv` 和 `metric-rankings.json`。导出器直接使用从原始页面整理、去重并处理过同刻冲突的选中作品，分别按 `like_count` 和 `forward_count` 排序，不混合相加。不需要再查询、购买单作品详情或手动猜字段。

## 缺失或带单位的计数怎么排名？

| 已存值                          | 处理                                   |
| ---------------------------- | ------------------------------------ |
| 整数0或原始数字字符串"0"               | 确切的零，可以排名                            |
| 安全非负JSON整数，或1–64位ASCII数字字符串  | 可以排名；保留原始形式和精确十进制字符串                 |
| 缺失或null                      | 保留该行与状态，不给名次，不补零                     |
| "10万+"、"1.2k"、小数、布尔、负数或不安全数字 | 保留原值，不排名；不编倍率或把下限当精确分数               |
| 精确计数相同                       | 并列竞争名次，例如1、1、3；作品ID只让展示次序确定          |
| 同ID最新同刻观察互相冲突                | 排名前排除，来源仍保留在selection-conflicts.json |

是否可排名由最新的被选观察决定；最新观察没有计数时，导出器不会拿旧计数填榜。不安全的作品 ID 在前一步就被排除，不靠把已舍入的数字转成字符串来“修复”。`coverage.json` 分别记录每项指标可排名和不可排名的数量，所以“前 10”可能不足 10 条。没有可用计数不代表互动表现差。

精确的字符串 ID 和大整数字符串以 `metric-rankings.json` 为准。用表格软件打开 `metric-rankings.csv` 时，把 `object_id` 和 `exact_count` 按文本导入，避免自动舍入；CSV 的引号本身不保证精度。`value_raw`、`request_id`、`source_index` 和 `video_index` 可以把每个名次追溯到归档的原始页面。哈希只检测本地字节是否变化，不能识别伪造的观察。

## 排名能说明什么，报告该怎么写？

排名只排列这批成功采集并选中的样本里报告的计数，不是全账号或全平台的排名。把 `collected_at` 放在每个值旁边，比较表现前先核对发布时间、观察窗口和采集覆盖。同一作品较晚的观察累积互动的时间更长；跨作品比较必须同时核对发布时间和采集时间。排名行不证明购买、独立人数、付费触达或因果关系。

可以这样写：“这份已存样本有 18 个可用作品 ID，其中 16 个有精确点赞计数，另 2 个未排名；报告的最大计数为……，观察时间见表。”把示例里的数字换成 `coverage.json` 里的实际数字。不要根据排名表写“播放最多”或“全账号榜首”。对已保存页面排名不产生平台调用；新取账号页按[价格页](https://beatapi.io/zh/pricing)计费。