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

# 用Python从小红书找相关笔记、读评论，再整理产品问题

> 用标准库保存一次搜索和选中笔记的评论，保留请求来源，再接已有评论导出与原句主题审核。

要用 Python 把小红书讨论整理成产品问题，先用 `data:xiaohongshu.app_v2.search_notes` 保存一页相关笔记，挑出值得读的讨论，再用 `data:xiaohongshu.app_v2.get_note_comments` 保存选中笔记的评论。最后用已有的评论导出脚本整理成 CSV 和有原句支持的主题报告。

示例以“咖啡机”为例：先搜索一次，再由你挑笔记。手里已有准确的笔记 ID 时，跳过搜索，直接从评论开始。

## 1. 准备环境与范围

使用 Python 3 和标准库，不需要第三方 SDK。把自己的密钥配置为本地环境变量 `BEATAPI_API_KEY`；脚本不把鉴权头写进文件。

先计划一页搜索，加上每篇选中笔记各一页评论。三篇入选笔记对应最多 4 次数据请求，按[价格页](https://beatapi.io/zh/pricing)当前单价估算；实际评论条数以每次返回为准。

## 2. 保存一次请求与结果

把下面的代码存为 `xhs_read.py`。`search` 命令调用 `data:xiaohongshu.app_v2.search_notes`，`comments` 命令调用 `data:xiaohongshu.app_v2.get_note_comments`。每次运行只发一个请求，输出目录必须是新的。

```python
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

if len(sys.argv) != 4 or sys.argv[1] not in {"search", "comments"}:
    raise SystemExit("Usage: python3 xhs_read.py search|comments VALUE NEW_DIRECTORY")
mode, value, directory = sys.argv[1:]
if not value.strip():
    raise SystemExit("Supply a keyword or a verified note ID")
key = os.environ.get("BEATAPI_API_KEY")
if not key:
    raise SystemExit("Set BEATAPI_API_KEY in your local environment")
if mode == "search":
    action = "xiaohongshu.app_v2.search_notes"
    params = {"keyword": value, "page": 1}
else:
    action = "xiaohongshu.app_v2.get_note_comments"
    params = {"note_id": value, "cursor": "", "index": 0,
              "pageArea": "UNFOLDED", "sort_strategy": "latest_v2"}
body = {"action": action, "params": params}
out = Path(directory)
out.mkdir(parents=True, exist_ok=False)
(out / "request.json").write_text(json.dumps(body, ensure_ascii=False, indent=2), encoding="utf-8")
stamp = datetime.now(timezone.utc).isoformat()
(out / "attempt.json").write_text(json.dumps({"started_at": stamp, "action": action}, indent=2), encoding="utf-8")
request = Request("https://api.beatapi.io/v1/social-data/call",
                  data=json.dumps(body).encode("utf-8"), method="POST",
                  headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"})
try:
    with urlopen(request, timeout=60) as response:
        status, raw = response.status, response.read()
except HTTPError as error:
    status, raw = error.code, error.read()
(out / "response.json").write_bytes(raw)
(out / "call.json").write_text(json.dumps({"action": action, "params": params,
    "http_status": status, "collected_at": stamp, "response_file": "response.json"},
    ensure_ascii=False, indent=2), encoding="utf-8")
payload = json.loads(raw)
if status != 200 or not isinstance(payload, dict) or payload.get("status") != "succeeded" or payload.get("error") is not None or payload.get("action") != action:
    raise SystemExit("Request failed or returned an unexpected result; inspect saved response")
inner = payload.get("data")
if not isinstance(inner, dict) or inner.get("success") is not True or type(inner.get("code")) is not int or inner["code"] != 0:
    raise SystemExit("Business result is not successful; retain saved files for review")
if mode == "comments":
    pages = [{"action": action, "note_id": value, "collected_at": stamp, "file": "response.json"}]
    (out / "comment-pages.json").write_text(json.dumps(pages, ensure_ascii=False, indent=2), encoding="utf-8")
print("Saved response: " + str(out / "response.json"))
```

先取得一页笔记：

```bash
python3 xhs_read.py search '咖啡机' search-call-1
```

每次运行的目录里保留 `request.json`、`attempt.json`、`call.json` 和 `response.json`。请求失败时，`xhs_read.py` 也保存已收到的响应，便于排查；超时没有最终结果时，先核对请求记录，再决定是否重发。

## 3. 从结果中选真正相关的笔记

搜索结果中的笔记在 `data.data.items[].note`。先看实际标题和摘录，选有明确使用场景的笔记，每篇保留 `note.id` 和选择理由。广告元素、外层结果项 ID 和昵称都不是笔记 ID。

例如研究清洁步骤，就选确实讨论清洁的笔记；只展示器具、没有相关内容的先排除。想读作者的详情文字，另用[选中笔记详情流程](/zh/guides/xiaohongshu-notes-research)；搜索摘录不能代替完整材料。

## 4. 读选中笔记的评论

复制每篇选中笔记的真实 `note.id`，每篇使用独立的输出目录：

```bash
python3 xhs_read.py comments '<selected_note_id>' comments-call-1
```

已核对的一级评论在 `data.data.comments`。读过原句、时间和上下文后，再归为具体使用问题。返回里内嵌的回复和单独展开的回复分开保留，翻页方法见[评论完整流程](/zh/guides/xiaohongshu-note-comments)。

## 5. 接到CSV与主题报告

评论请求成功后，`xhs_read.py` 生成与现有导出脚本兼容的 `comment-pages.json`。把[评论指南](/zh/guides/xiaohongshu-note-comments)中的 `comment_research.py` 保存到当前工作目录，然后在本地提取：

```bash
python3 comment_research.py extract comments-call-1/comment-pages.json comment-review
```

多篇笔记分别取数后，把各清单记录合成一个数组，并把每个 `file` 写成相对于总清单的实际路径，再交给同一个提取脚本。保留每条记录的笔记 ID 和真实查询时间。

`comments.csv` 用于阅读材料；逐条审核 `labels.json` 后，再生成 `themes.csv`、`evidence.json` 和 `coverage.json`。每个主题都要有实际原句，支持评论数与不同笔记数分别记录，不把有限的评论样本当成所有用户。

比如两篇笔记各有一条评论问「换清洁片以后为什么还有味道」，就在 `themes.csv` 放一条排查主题，记录两条支持评论、两篇不同笔记。同事用 `evidence.json` 回查两条评论的原句和条件，再决定要不要写进清洁手册。

交付的问题例如“清洁步骤哪里不清楚、配件兼容需要确认什么”，每项附原句、笔记来源和下一步。同事拿到的是可以继续处理的问题清单，而不是一堆原始 JSON。

已存响应直接复用。`xhs_read.py` 不自动选笔记、不批量扩页，也不回复评论者；需要扩大研究时，先定新的范围再取数，并继续保存来源。

[搜索与选文](/zh/guides/xiaohongshu-notes-research) · [评论到主题报告](/zh/guides/xiaohongshu-note-comments)