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

# 做小红书选题，怎么找到值得参考的笔记并整理成表？

> 先围绕一个具体内容方向搜一页，筛掉无关结果，只给值得研究的笔记补详情文字，最后得到带选择理由的选题素材表。

为选题找有用的小红书笔记，先用 `xiaohongshu.app_v2.search_notes` 按一个具体关键词搜一页，挑出相关笔记，只给入选的笔记补详情。比如做一期「新手露营咖啡」，第一轮就搜「露营咖啡」，看大家是在问器具、冲泡步骤，还是收纳。

最后交付一张选题素材表，保留标题、互动数和你写下的入选理由。只读过搜索摘录的条目，标为「搜索摘录」。

手上已经有指定笔记时，不必为了获得 ID 再搜索，直接走[链接和笔记定位](/zh/faq/xiaohongshu-share-links)。要回答“用户到底抱怨什么”时，搜索只负责找样本，后面还需要[阅读评论与回复](/zh/guides/xiaohongshu-note-comments)。

## 做完后，你交给同事的是什么？

交给同事的是一张可以继续挑选的 `notes.csv`：标题、作者、搜索摘录、赞藏评分享、笔记 ID，以及 `selected`（是否入选）、`selection_reason`（为何入选）两列。这两列由你人工填写，脚本不判断相关性，也不生成所谓爆款评分。

下表是**审核方法示例**，不是真实搜索的发现：

| 看到的情况              | 怎么判断                 | 留给下一步的问题          |
| ------------------ | -------------------- | ----------------- |
| 标题在讲营地冲煮方法，与你的选题相符 | 先保留，写明你想研究哪种做法或表达    | 摘录不够时再补正文，核实具体步骤。 |
| 只是咖啡店打卡，互动很高       | 与“新手露营”不符，不能只因数字高就入选 | 本轮不花详情查询费用。       |
| 评论数高，但标题看不出大家在问什么  | 可作讨论样本，暂不下需求结论       | 读过评论才能知道讨论内容。     |

交付时附一段简短说明：本轮搜了什么、筛出了哪些值得读的笔记、每篇为什么入选、还缺哪些信息。收藏不是购买，评论数不是独立用户数，搜索位置也不是内容质量排行榜。

## 1. 先把要回答的问题缩小，再选关键词

“咖啡”太宽时，先把目标写成一句话，例如“给第一次露营的人讲清楚怎样准备咖啡”，再选“露营咖啡”作为第一轮的词。结果偏离目标时，另开一轮换词；不要把不同词、不同筛选条件的结果混成同一份排名。

需要近期内容、只看视频，或按收藏/评论找样本时，先定好[时间、类型和排序](/zh/faq/xiaohongshu-search-filters)。这里的起步示例只用关键词，取不到“最近一周全部高收藏笔记”。

## 2. 用第一页判断关键词是否合适

先读第一页的标题和搜索摘录。看到的多是露营咖啡馆探店时，另开一轮，换成「露营 手冲 入门」。已经找到几篇相关教程、还缺低预算或轻装备的做法时，再补一页或换成更具体的词。

已接好 [BeatAPI MCP](https://beatapi.io/mcp) 时，可以这样给助手布置任务：

> 查「露营咖啡」第一页，整理标题、作者、笔记 ID、搜索摘录和互动。按「装备清单、冲泡步骤、清洁收纳」标出候选方向。到第一页就停，把适合补详情或评论的笔记单独列出来。

MCP 工具预览先展示五条。用本次请求号读取已保存的结果，再判断要不要另查一页。

## 3. 导出后，写下“为什么值得看”

用后面的本地导出脚本生成 `notes.csv`。先按内容是否相关筛选，再参考互动信号，把 `selected` 填为 `yes`（入选）或 `no`（排除），未决定留空，并在 `selection_reason` 写明理由。例如“研究新手设备选择的表达”，比“点赞高”更能指导下一步。

同一笔记在不同页出现时只保留一个条目，按 ID 去重，不按标题。导出表保留作者和采集来源，便于核对；导出表不生成可访问的笔记分享链接。需要回看原笔记时，用标题、作者和 ID 到作者账号核对；找不到就记为待核实，不自行拼接缺少访问令牌的链接。

## 4. 只给值得研究的笔记补详情文字

挑出要精读的笔记，把详情返回的描述填进同一行的 `detail_text`。只有搜索摘录的行保留 `search_excerpt`。阅读状态由审核者填写；需要图片中的文字时，再去看原帖。

已知图文笔记调用图文详情动作，已知视频笔记调用视频详情动作，不为判断类型自动轮试两个动作。拿到结果后按目标笔记 ID 匹配，不默认第一条就是目标笔记。视频描述也不是口播逐字稿。

读完后，再决定是保留这个选题角度、换一个切入点，还是继续读评论。要了解讨论内容，进入[评论研究流程](/zh/guides/xiaohongshu-note-comments)；不能只凭评论总数写出用户需求结论。研究他人的内容结构和问题，不直接复制别人的正文当作自己的稿子。

## 5. 控制成本，也保留这轮研究范围

搜索 P 页、选定 N 篇补详情，共 P + N 次平台调用。评论和模型另计，单价见 [BeatAPI 价格页](https://beatapi.io/zh/pricing)。改表格、筛选和重新导出都用已保存的文件完成。

达到批准页数、遇到错误、重复整页、没有明确的下一页或状态异常时就停。在素材表旁记下关键词、筛选、日期和实际页数；素材表代表本轮看到的样本，不是平台全部笔记或稳定排名。要反复观察同一篇笔记在搜索中的位置，另用[搜索位置追踪](/zh/faq/xiaohongshu-search-positions)。

## 技术步骤：查当前能力与价格

需要 BeatAPI API Key。Search、Inspect 免费，执行消耗余额。下面用 HTTP 方式；已经通过 MCP 完成同一搜索时，不要为了导出把同一页再付费请求一次。

```bash
curl -sS https://api.beatapi.io/v1/capabilities/search \
  -H "Content-Type: application/json" \
  -d '{"query":"小红书 搜索笔记"}'
```

把实际的 reference 交给 Inspect；下面的 reference 是已核实的动作：

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H "Content-Type: application/json" \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes"}'
```

检查就绪状态、输入和当前价格，ready/runnable 才执行，listed 不代表可以执行。选择 Run 时，下面的请求只要一页的少量预览：

```bash
curl -sS https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes","input":{"keyword":"露营咖啡"},"view":"preview","max_items":5}'
```

上面的 Run 请求是示例，不是实测返回。用返回的 request_id 按[结果读取合同](https://docs.beatapi.io/zh/capabilities)获取已存结果；预览大小不是平台分页。下方导出脚本接收完整的 Social Data 响应，不接收 MCP 预览。

## 技术步骤：保存搜索页

要用本页的固定导出脚本时，直接调用 Social Data 并保存完整响应。**直接调用与上面的 Run 二选一，不为同一页调用两次。**

```bash
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"xiaohongshu.app_v2.search_notes","params":{"keyword":"露营咖啡","page":1}}' \
  -o xiaohongshu-search-page-1.json
```

第一页真实返回的 `data.search_id`、`data.search_session_id` 与 data.page/data.next_page 同层。获准取下一页时，保留首次的会话、关键词和筛选条件，换成真实的下一页值；下面的请求取第二页：

```bash
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"xiaohongshu.app_v2.search_notes","params":{"keyword":"露营咖啡","page":2,"search_id":"<first_search_id>","search_session_id":"<first_search_session_id>"}}' \
  -o xiaohongshu-search-page-2.json
```

遇到空页、重复整页、错误或授权上限就停；翻页不承诺搜尽所有匹配。`export_notes.py` 只合并同一查询和筛选轮次；原始文件留存，不用标题代替 ID。

## 技术步骤：导出可筛选的笔记表

创建 `search-manifest.json`，每页填实际参数、采集时间和文件。下面的示例只列一页：

```json
{"pages":[{"params":{"keyword":"露营咖啡","page":1},"collected_at":"<actual_query_time>","file":"xiaohongshu-search-page-1.json"}],"details":[]}
```

把下面的脚本保存为 `export_notes.py`。已核实的搜索路径是 `data.data.items[].note`；`export_notes.py` 把搜索摘录和后来取得的正文分列，给人工判断留下入选标记和理由两列。依据：`export_notes.py` 用一页已获准保存的真实响应导出了 20 条不同笔记，没有新增收费。

```python
import csv,json,pathlib,sys
from decimal import Decimal,InvalidOperation
manifest_path,target=map(pathlib.Path,sys.argv[1:3])
manifest=json.loads(manifest_path.read_text(encoding='utf-8'))
if not manifest.get('pages') or manifest['pages'][0]['params'].get('page')!=1:raise ValueError('Start manifest with page one')
rows,seen,session=[],set(),None
scope=None;states=[]
for page in manifest['pages']:
    params=page['params'];identity={k:v for k,v in params.items() if k not in ('page','search_id','search_session_id')}
    if scope is None:scope=identity
    if identity!=scope:raise ValueError('Do not merge different query/filter runs')
    payload=json.loads((manifest_path.parent/page['file']).read_text(encoding='utf-8'))
    if payload.get('status')!='succeeded' or payload.get('action')!='xiaohongshu.app_v2.search_notes':raise ValueError('Wrong or failed search')
    upstream=payload['data']
    if upstream.get('success') is not True or upstream.get('code')!=0:raise ValueError('Search business failure')
    if upstream['page']!=params['page']:raise ValueError('Wrong page returned')
    if session is None:session=(upstream['search_id'],upstream['search_session_id'])
    if params['page']>1 and (params.get('search_id'),params.get('search_session_id'))!=session:raise ValueError('Use first-page session')
    new=0
    for rank,item in enumerate(upstream['data']['items'],1):
        note=item.get('note')
        if not isinstance(note,dict):continue
        nid=note.get('id')
        if not isinstance(nid,str) or not nid:raise ValueError('Missing note ID')
        if nid in seen:continue
        seen.add(nid);new+=1
        row={'note_id':nid,'title':note.get('title'),'search_excerpt':note.get('desc'),
             'type':note.get('type'),'published_at_raw':note.get('timestamp'),
             'author_name':(note.get('user') or {}).get('nickname'),
             'author_id':(note.get('user') or {}).get('userid'),
             'first_seen_page':params['page'],'position_on_page':rank,
             'request_id':payload.get('request_id'),'source_file':page['file'],
             'collected_at':page['collected_at'],'selected':'','selection_reason':'',
             'detail_text':'','detail_source_file':'','detail_request_id':'','text_scope':'search_excerpt'}
        for out,key in [('likes','liked_count'),('saves','collected_count'),('comments','comments_count'),('shares','shared_count')]:
            value=note.get(key)
            if value is not None:
                if isinstance(value,bool):raise ValueError('Invalid metric')
                n=Decimal(str(value))
                if not n.is_finite() or n<0 or n!=n.to_integral_value():raise ValueError('Invalid metric')
                value=int(n)
            row[out]=value
        row['image_urls']=json.dumps([x['url'] for x in note.get('images_list',[]) if isinstance(x,dict) and isinstance(x.get('url'),str)],ensure_ascii=False)
        rows.append(row)
    states.append({'page':params['page'],'new_notes':new,'next_page':upstream.get('next_page'),
        'search_id':session[0],'search_session_id':session[1]})
    if not new:break  # Empty or repeated full page: do not continue scanning blindly.
if not rows:raise ValueError('No usable notes; do not replace an old export')
by_id={row['note_id']:row for row in rows}
review_path=sys.argv[3] if len(sys.argv)>3 else None
if review_path is not None:
    with pathlib.Path(review_path).open(encoding='utf-8-sig',newline='') as review:
        reader=csv.DictReader(review)
        if not reader.fieldnames or any(reader.fieldnames.count(k)!=1 for k in ('note_id','selected','selection_reason')):raise ValueError('Missing or duplicate review columns')
        reviewed=set()
        for entry in reader:
            nid=entry['note_id']
            if nid not in by_id or nid in reviewed:raise ValueError('Unknown or duplicate reviewed note ID')
            selected,reason=entry['selected'],entry['selection_reason']
            if selected not in ('','yes','no') or not isinstance(reason,str):raise ValueError('Use blank/yes/no and a text reason')
            if selected and not reason.strip():raise ValueError('Selected or excluded notes need a reason')
            # Undo this exporter's formula guard once, then reapply on CSV output.
            if reason.startswith("'") and reason[1:].lstrip().startswith(('=','+','-','@')):reason=reason[1:]
            by_id[nid].update(selected=selected,selection_reason=reason);reviewed.add(nid)
        if reviewed!=set(by_id):raise ValueError('Review must include every candidate; do not silently drop decisions')
for detail in manifest.get('details',[]):
    nid=detail['note_id']
    if nid not in by_id:raise ValueError('Detail is outside this candidate set')
    response=json.loads((manifest_path.parent/detail['file']).read_text(encoding='utf-8'))
    if response.get('status')!='succeeded':raise ValueError('Failed detail')
    if response['data'].get('success') is False or ('code' in response['data'] and (type(response['data']['code']) is not int or response['data']['code']!=0)):raise ValueError('Detail business failure')
    action=response.get('action')
    if action=='xiaohongshu.app_v2.get_image_note_detail':notes=[n for w in response['data']['data'] for n in w.get('note_list',[])]
    elif action=='xiaohongshu.app_v2.get_video_note_detail':notes=response['data']['data']
    else:raise ValueError('Wrong detail action')
    matches=[n for n in notes if n.get('id')==nid]
    if len(matches)!=1 or not isinstance(matches[0].get('desc'),str) or not matches[0]['desc'].strip():raise ValueError('Expected one matching nonempty detail text')
    by_id[nid].update(detail_text=matches[0]['desc'],detail_source_file=detail['file'],detail_request_id=response.get('request_id'),text_scope='detail_retrieved')
def safe(value):
    if value is None:return ''
    text=str(value)
    return "'"+text if text.lstrip().startswith(('=','+','-','@')) else text
target.mkdir()
with (target/'notes.csv').open('x',encoding='utf-8-sig',newline='') as output:
    writer=csv.DictWriter(output,fieldnames=list(rows[0]));writer.writeheader()
    writer.writerows({k:safe(v) for k,v in row.items()} for row in rows)
(target/'notes.json').write_text(json.dumps(rows,ensure_ascii=False,indent=2),encoding='utf-8')
(target/'paging.json').write_text(json.dumps(states,ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'unique_notes':len(rows),'details_attached':sum(r['text_scope']=='detail_retrieved' for r in rows)}))
```

```bash
python3 export_notes.py search-manifest.json note-shortlist
```

输出 `notes.csv`、`notes.json`、`paging.json`，不覆盖已有目录。`notes.csv` 用于人工筛选，`notes.json` 保留全部字段，`paging.json` 保存这轮的分页状态。搜索字段包含 title/desc、liked_count/collected_count/comments_count/shared_count、user.nickname/user.userid 和 images_list\[].url；搜索结果里的 desc 只是卡片摘录，不是全文、独立 hashtags 或 views。

### 给选中的条目附加正文

对每篇已选笔记，用笔记 ID 调用 `xiaohongshu.app_v2.get_image_note_detail`（图文）或 `xiaohongshu.app_v2.get_video_note_detail`（视频），请求参数为 `{"note_id":"<selected_note_id>"}`，每篇单独保存响应。不要两个动作都自动执行。

在 manifest 的 details 里添加 `{"note_id":"<selected_note_id>","file":"selected-detail.json"}`，用新的输出目录重新运行导出脚本，并把人工审核过的旧 CSV 作为第三个参数传入：

```bash
python3 export_notes.py search-manifest.json note-shortlist-with-details note-shortlist/notes.csv
```

传入旧 CSV 后，筛选决定和理由按笔记 ID 保留；原表每一行都要保留，用筛选代替删行。不传第三个参数时，审核列全部为空，不能当作保留了审核。空白正文或业务失败会停止本次导出，不产生“已取得详情文字”标记；旧表保留，修正清单后可以再次离线导出。`export_notes.py` 在图文 `data.data[].note_list[]`、视频 `data.data[]` 中精确匹配 ID，把 desc 写入 detail_text，并保存来源和请求 ID。没取到详情的行保留为搜索摘录；`detail_retrieved` 只表示取到了非空的详情描述，不表示已人工阅读或已取得完整正文。需要核对其他指标时，注意[阅读与曝光的区别](/zh/faq/xiaohongshu-views-impressions)。

依据：搜索导出用已保存的真实响应验证过；追加页和详情匹配依据合同和离线样例回归，没有新增付费详情测试。空数据或错误不自动等于“没有内容”，也不自动重试。完整合同见[社媒数据说明](https://docs.beatapi.io/zh/social-data)。

如果只想先跑一次搜索，可以看[小红书单页搜索指南](/zh/guides/search-xiaohongshu-notes)。