小红书批量采集 nataliwhite20534-droid/dsh-xhs-collector

dsh-xhs-collector

小红书 XHS 数据采集工具，基于 cn-scraper-mcp 0.5.0，源码 + 实跑双重验证，错误码对照表完备。

DSH Plugin
Python 3.11+
License: MIT
[Verified: 2026-09-03]()

验证状态

不是设计文档，是真实跑通的输出。

| 验证项 | 结果 |
| pip install cn-scraper-mcp==0.5.0 | ✅ 成功 |
| from cn_scraper_mcp.engines import XiaohongshuEngine | ✅ 成功 |
| XiaohongshuEngine() 实例化 | ✅ 成功 |
| engine.search('完美日记', 5) 调用 | ✅ 真实执行 |
| engine.ensure_browser() 启动 Chrome | ✅ 成功（系统已有 Chrome） |
| 无 Cookie 触发 XHS_LOGIN_EXPIRED 错误码 | ✅ 符合预期 |

真实返回（端到端）

from cn_scraper_mcp.engines import XiaohongshuEngine

engine = XiaohongshuEngine(port=9251)
result = engine.search('完美日记', 5)

无登录态返回（关键词无结果）：

{
"keyword": "完美日记", "state": "empty", "count": 0,
"items": [],
"error_code": "XHS_EMPTY",
"error_message": "未找到相关笔记。非风控问题，可能是关键词无结果。"
}

Chrome 启动后，无 Cookie 返回：

{
"keyword": "完美日记", "state": "login_expired", "count": 0,
"items": [],
"error_code": "XHS_LOGIN_EXPIRED",
"error_message": "检测到登录页面，cookies 可能已过期。请更新 ~/.cn-scraper-cookies/xiaohongshu.json" }

已知事实 vs 文档差异

| 误区 | 正确做法 |
| from cn_scraper_mcp import XiaohongshuEngine | from cn_scraper_mcp.engines import XiaohongshuEngine ✅ |
| 必须装 playwright | 不需要，cn-scraper-mcp 用 curl_cffi + CDP 直接连 |
| 用 Chrome | Obscura 首选（内置反检测），Chrome 作为 fallback |

安装

pip install cn-scraper-mcp>=0.5.0

完整 API 签名（源码验证）

class XiaohongshuEngine:
def __init__(self, cookies_path: str | None = None, port: int = 9251): ...
def ensure_browser(self) -> bool: ... # Obscura → Chrome fallback
def search(self, keyword: str, limit: int = 10) -> dict: ...
def get_note(self, note_id: str, xsec_token: str | None = None) -> dict: ...
def get_comments(self, note_id: str, xsec_token: str | None = None) -> dict: ...
def cleanup(self): ...

错误码对照表

| error_code | 触发条件 | 处理 |
| XHS_EMPTY | 关键词无结果 | 换关键词 |
| XHS_LOGIN_EXPIRED | Cookie 过期 | 重新扫码登录 |
| XHS_IP_RISK | IP 风险 | 换住宅 IP |
| XHS_CAPTCHA | 验证码 | 人工或 Obscura stealth |
| XHS_NOTE_NOT_FOUND | 笔记不存在 | 跳过 |
| XHS_BROWSER_UNAVAILABLE | 无法启动浏览器 | 检查 Chrome/Obscura 安装 |

Cookie 配置

首次使用需要登录：

在 DSH 中调用 cn-scraper-mcp 的 guided_login 或手动配置：
mkdir -p ~/.cn-scraper-cookies
放入 xiaohongshu.json（格式见 cn-scraper-mcp 文档）

配套工具

- dsh-4-role-workflow — 4 角色协作工作流（用 xhs-cli）
- dsh-china-research-notes — 中国平台踩坑经验合集