> 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放在同一张表里，用 `xiaohongshu.app_v2.search_notes` 逐个搜索关键词，在返回结果里按笔记ID查找，记录这篇笔记在这次结果中的位置。持续记录就能看出笔记在这些词下有没有被找到、最近的观察有没有变化，适合跟踪新发的教程或产品使用内容。

比如品牌发了三篇咖啡机清洁教程，分别想覆盖“咖啡机清洁”“奶泡管清洗”“咖啡机除垢”。先给每篇笔记配好真正对应的词：一篇教程可以对应多个词，一个词也可以观察多篇笔记。笔记ID取自已有的发布记录、链接或搜索结果，不需要额外查详情。

## 先说清楚这次观察想回答什么

| 观察结果             | 下一步怎样读                              |
| ---------------- | ----------------------------------- |
| 目标笔记出现在已查结果中     | 保存出现位置，回看附近结果是否也在解决同一个问题            |
| 同条件下连续观察的位置前移或后移 | 看多次记录是否持续变化，再结合内容与实际业务指标复盘          |
| 在本次已查页内没找到       | 记下关键词和查到多深；按原定计划决定是否加深，或检查目标词是否匹配内容 |
| 换了排序或筛选后才找到      | 作为另一种观察单独记录，先在相同条件下比较               |

位置指的是**本次 API 返回的顺序**。同一个词在不同时间、对不同 App 用户的结果可能不同；“未找到”作为一种状态保留下来，以后的观察才能继续比较。

## 怎样取得可比较的记录？

1. 固定关键词、目标笔记、排序和筛选。综合排序用 `xiaohongshu.app_v2.search_notes` 的 `sort_type: general`；评论数排序 `comment_descending` 回答的是另一类问题。
2. 约定观察时段和页深，比如每天相近时段、每个词先查一页。按[搜索指南](/zh/guides/xiaohongshu-notes-research)记录实际查询时间与输入，保存原响应。定时运行在你自己的任务环境里配置。
3. 在 `data.data.items[].note.id` 中匹配目标笔记。结果里可能夹有非笔记项，所以页内原位置和笔记项位置分开保留，不要把每页都当成 20 篇笔记。
4. 需要更深时，用返回的 `data.next_page` 和首响应的 `data.search_id`、`data.search_session_id` 继续同一次观察。下一次独立观察重新从第一页开始。

例如，同条件下三次观察依次在笔记槽位 12、9、8，说明这个词下的可见性值得继续关注；昨天在位置 8，今天一页内没找到，就记录这两种状态，不换算成“下降到第 0 名”。要解释变化原因，再读目标笔记和邻近内容；位置记录本身不能证明是哪次改标题带来了变化。

把任务交给已接入工具的助手时，可以这样写：

> 按这张关键词—笔记ID清单观察搜索结果，统一综合排序和筛选，每个词先查一页。保留实际时间、查询条件、找到位置和未找到状态。和同条件历史记录比较后，列出值得继续观察的词；需要读更多页或相关内容时说明理由。

下面的脚本 track_positions.py 复用你已保存的结果，生成观察表和相邻两次的对照。采集和本地比较分开进行，已有响应可以反复分析。

## 准备已保存观察与目标清单

在原始响应旁边创建 `rank-input.json`，替换示意的关键词、ID、文件名和时间。一个关键词可以跟踪多篇目标笔记，同一个文件也可以放多个关键词。每个关键词至少要有一次已保存的观察；后续观察必须真实采集之后才加入。track_positions.py 不定时、不搜索、不重试。

```json
{
  "targets": {"example keyword": ["<known-note-id>", "<another-known-note-id>"]},
  "runs": [
    {"pages": [{"file":"day-one.json","collected_at":"2026-11-16T10:00:00Z","params":{"keyword":"example keyword","sort_type":"general","page":1}}]},
    {"pages": [{"file":"day-two.json","collected_at":"2026-11-17T10:00:00Z","params":{"keyword":"example keyword","sort_type":"general","page":1}}]}
  ]
}
```

多页观察在同一个 `pages` 数组里追加页面，参数用实际的下一页和原会话。track_positions.py 会拒绝跳页、换会话、返回页不符、重复 request_id 和查询条件变化。“省略默认值”和“显式填写默认值”也算不同输入，所以每次都记录同一套完整参数，不要悄悄合并。

保存为 `track_positions.py`，执行这个**离线**命令：

```bash
python3 track_positions.py rank-input.json rank-review
```

```python
import csv, datetime, hashlib, json, pathlib, sys

manifest = pathlib.Path(sys.argv[1]); manifest_bytes = manifest.read_bytes()
config = json.loads(manifest_bytes)
targets, runs = config['targets'], config['runs']
if not isinstance(targets, dict) or not targets or not isinstance(runs,list) or not runs: raise ValueError('Targets and saved runs required')
for keyword, ids in targets.items():
    if not keyword.strip() or not isinstance(ids,list) or not ids or any(not isinstance(x,str) or not x.strip() for x in ids) or len(ids)!=len(set(ids)): raise ValueError('Each keyword needs unique original note IDs')
def stamp(value):
    d=datetime.datetime.fromisoformat(value.replace('Z','+00:00'))
    if d.utcoffset() is None: raise ValueError('Record actual query time with timezone')
    return d
rows, archives, sources, scopes, moments, request_ids = [], [], [], {}, set(), set()
for run in runs:
    pages=run['pages']
    if not isinstance(pages,list) or not pages: raise ValueError('Saved pages required')
    first=pages[0]['params']; keyword=first.get('keyword')
    if keyword not in targets: raise ValueError('No targets for this keyword')
    scope={k:v for k,v in first.items() if k not in ('page','search_id','search_session_id')}
    if keyword in scopes and scopes[keyword]!=scope: raise ValueError('Use identical explicit query/filter parameters across observations')
    scopes[keyword]=scope
    observed=pages[0]['collected_at']; moment=stamp(observed)
    if (keyword,moment) in moments: raise ValueError('Duplicate observation time for keyword')
    moments.add((keyword,moment))
    found, note_slot, total_items, next_page, session, last_time, seen, can_continue = {}, 0, 0, 1, None, None, set(), True
    for page in pages:
        params=page['params']; number=params.get('page')
        if not can_continue: raise ValueError('Do not extend an empty/repeated page')
        if type(number) is not int or number!=next_page: raise ValueError('Start at page one and follow the observed next_page without gaps')
        if {k:v for k,v in params.items() if k not in ('page','search_id','search_session_id')}!=scope: raise ValueError('Mixed query/filter run')
        time=stamp(page['collected_at'])
        if last_time is not None and time<last_time: raise ValueError('Page collection times go backwards')
        last_time=time
        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 request_ids: raise ValueError('Missing/repeated request ID')
        request_ids.add(rid)
        if response.get('status')!='succeeded' or response.get('error') is not None or response.get('action')!='xiaohongshu.app_v2.search_notes': raise ValueError('Failed or mismatched search')
        body=response['data']
        if body.get('success') is not True or type(body.get('code')) is not int or body['code']!=0 or type(body.get('page')) is not int or body['page']!=number: raise ValueError('Wrong page or business error')
        returned=(body.get('search_id'),body.get('search_session_id'))
        if any(not isinstance(x,str) or not x.strip() for x in returned): raise ValueError('Missing session identity')
        if session is None:
            if params.get('search_id') not in (None,'') or params.get('search_session_id') not in (None,''): raise ValueError('Start a fresh page-one observation without prior session IDs')
            session=returned
        elif returned!=session or (params.get('search_id'),params.get('search_session_id'))!=session: raise ValueError('Changed search session')
        items=body['data']['items']
        if not isinstance(items,list): raise ValueError('Missing result items')
        name='raw-'+str(len(archives)+1).zfill(3)+'.json';digest=hashlib.sha256(raw).hexdigest();archives.append((name,raw))
        sources.append({'file':name,'sha256':digest,'request_id':rid,'keyword':keyword,'page':number,'collected_at':page['collected_at']})
        fresh=0
        for position,item in enumerate(items,1):
            if not isinstance(item,dict): raise ValueError('Invalid result item')
            note=item.get('note')
            if note is None: continue
            if not isinstance(note,dict): raise ValueError('Unreadable note object; do not report it as not found')
            nid=note.get('id')
            if not isinstance(nid,str) or not nid.strip(): raise ValueError('Missing note ID')
            note_slot+=1
            if nid not in seen: fresh+=1;seen.add(nid)
            if nid in targets[keyword] and nid not in found:
                found[nid]={'page':number,'item_position_on_page':position,'note_slot_in_saved_run':note_slot,
                    'request_id':rid,'source_file':name,'source_sha256':digest}
        total_items+=len(items);can_continue=fresh>0
        next_page=body.get('next_page')
        if next_page is not None and (type(next_page) is not int or next_page<=number): next_page=None
    for nid in targets[keyword]:
        row={'keyword':keyword,'note_id':nid,'observed_at':observed,'last_page_at':pages[-1]['collected_at'],
             'pages_scanned':len(pages),'items_scanned':total_items,'note_slots_scanned':note_slot,'unique_notes_scanned':len(seen),
             'state':'found' if nid in found else 'not_found_in_scanned_pages','scope':scope,
             'page':None,'item_position_on_page':None,'note_slot_in_saved_run':None,
             'continuation_available':can_continue and next_page is not None,'request_id':None,'source_file':None,'source_sha256':None}
        row.update(found.get(nid,{}));rows.append(row)
missing=set(targets)-{row['keyword'] for row in rows}
if missing: raise ValueError('Every target keyword needs at least one saved run')
rows.sort(key=lambda r:(r['keyword'],r['note_id'],stamp(r['observed_at'])))
previous={};changes=[]
for row in rows:
    key=(row['keyword'],row['note_id']);before=previous.get(key)
    if before:
        both=before['state']=='found' and row['state']=='found'
        changes.append({'keyword':key[0],'note_id':key[1],'before':before['observed_at'],'after':row['observed_at'],
            'before_state':before['state'],'after_state':row['state'],
            'observed_note_slots_up':before['note_slot_in_saved_run']-row['note_slot_in_saved_run'] if both else None,
            'equal_pages_scanned':before['pages_scanned']==row['pages_scanned'],
            'scope':'Change in saved API ordering only; not universal app ranking or causal SEO impact'})
    previous[key]=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 [('observations.json',rows),('changes.json',changes),('coverage.json',{'sources':sources,
    'manifest_sha256':hashlib.sha256(manifest_bytes).hexdigest(),'saved_runs':len(runs),'executed_calls':0,
    'position_definition':'Raw item position on page and note slots across consecutive saved pages; repeated notes occupy slots; first appearance retained'})]:
    (out/name).write_text(json.dumps(value,ensure_ascii=False,indent=2),encoding='utf-8')
fields=['keyword','note_id','observed_at','state','page','item_position_on_page','note_slot_in_saved_run','pages_scanned','items_scanned','unique_notes_scanned','continuation_available','request_id','source_file','source_sha256']
with (out/'observations.csv').open('w',encoding='utf-8-sig',newline='') as f:
    writer=csv.DictWriter(f,fieldnames=fields);writer.writeheader()
    for row in rows:
        cells={k:'' if row.get(k) is None else str(row[k]) for k in fields}
        writer.writerow({k:"'"+v if v.lstrip().startswith(('=','+','-','@')) else v for k,v in cells.items()})
print(json.dumps({'saved_runs':len(runs),'target_observations':len(rows),'comparisons':len(changes),'executed_calls':0}))
```

## 正确解读交付物

* `observations.csv` / `.json`：每个目标笔记、每次观察一行。`item_position_on_page` 按所有返回项计页内位置；`note_slot_in_saved_run` 按连续已保存页中的笔记项计位置。非笔记项不占笔记位置，重复笔记仍占返回槽位，目标笔记保留首次出现的位置。这两个位置是有明确定义的观察坐标，不是归一化的全站排名。
* `state: not_found_in_scanned_pages`：位置列留空，仍报告扫过的页数、结果项数和去重笔记数；这个状态既不能推断所有人看到的排名下界，也不能证明笔记已经消失。
* `changes.json`：同关键词、同笔记相邻两次观察对照。`observed_note_slots_up` 为正表示在这些返回笔记槽位中前移；任一次未找到，变化为 null，而不是从零名跳升。页深不同会显式标注；同样参数也不能消除个性化或平台结果变化。
* `coverage.json`、`input-manifest.json`、`raw-*.json`：保留原响应字节、请求号、每页实际记录时间和哈希。一次采集覆盖从第一页到末页的时间段，不是一个原子时刻。哈希只检验本地完整性，不是服务器对查询条件的认证，也不证明 App 里可见的排名。完整响应私下保管。

周报里可以这样写：「关键词『露营咖啡』，综合排序，每次查一页。这篇笔记周一在第 8 个笔记位置，周三在第 5 个」。如果周五第一页没找到，就记「本次第一页未找到」，位置变化留空。需要解释原因时，再看相邻笔记和这几天实际改了什么。

## 观察需要多少费用？

track_positions.py 不发起任何调用。新增采集按“关键词观察次数 × 实际请求页数 × [价格页](https://beatapi.io/zh/pricing)中的搜索当前单价”预算。30 个词每天各查一页，一周 210 次；每次都查两页，调用预算翻倍。每页包含多少笔记不固定；在同一份已保存结果里检查多个目标 ID 不需要分别调用。确定位置不需要附加详情或评论请求。

来源：此前付费取得的一页搜索结果在本地回放，用真实返回的目标和一个特意不存在的合成 ID，生成了找到/未找到两种记录，没有新增请求；该页是评论数排序，不是综合排序。多页和双时点对照用合成测试数据验证。要持续监测，另行安排带预算的采集计划；本页没有创建自动任务。