xiaohongshu-cli — 小红书命令行工具 (Xiaohongshu CLI Tool)

可执行文件 (Binary): xhs
凭证 (Credentials): 浏览器 cookies（自动提取）或浏览器辅助的二维码登录 (--qrcode)

安装 (Setup)

# 安装 (需要 Python 3.10+) (Install - requires Python 3.10+)
uv tool install xiaohongshu-cli
# 或 (Or): pipx install xiaohongshu-cli

# 升级到最新版本（推荐，以避免 API 错误）(Upgrade to latest - recommended to avoid API errors)
uv tool upgrade xiaohongshu-cli
# 或 (Or): pipx upgrade xiaohongshu-cli

认证 (Authentication)

对智能体重要提示 (IMPORTANT FOR AGENTS): 在执行任何 xhs 命令之前，首先检查凭证是否存在。不要假设 cookies 已配置。

步骤 0：检查是否已认证 (Step 0: Check if already authenticated)

xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"

如果结果为 AUTH_OK，跳至 命令参考 (Command Reference)。
如果结果为 AUTH_NEEDED，继续执行步骤 1。当无法提取浏览器 cookie 但可以接受启动浏览器时，优先使用 --qrcode。

步骤 1：引导用户进行认证 (Step 1: Guide user to authenticate)

确保用户已登录 xiaohongshu.com，并且使用 browser_cookie3 支持的浏览器。支持的浏览器：Chrome、Arc、Edge、Firefox、Safari、Brave、Chromium、Opera、Opera GX、Vivaldi、LibreWolf、Lynx、w3m。然后：

xhs login                              # 自动检测包含有效 cookie 的浏览器 (auto-detect browser with valid cookies)
xhs login --cookie-source arc          # 显式指定浏览器 (specify browser explicitly)
xhs login --qrcode                     # 浏览器辅助的二维码登录，终端输出二维码 (browser-assisted QR login with terminal QR output)

使用以下命令验证：

xhs status
xhs whoami

步骤 2：处理常见认证问题 (Step 2: Handle common auth issues)

智能体默认设置 (Agent Defaults)

所有机器可读输出使用 SCHEMA.md 中定义的结构。
数据位于 .data 下。

• 非 TTY 标准输出 → 自动 YAML (Non-TTY stdout → auto YAML)
• --json / --yaml → 显式格式 (explicit format)
• OUTPUT=json 环境变量 → 全局覆盖 (global override)
• OUTPUT=rich 环境变量 → 强制人类可读输出 (force human output)

命令参考 (Command Reference)

读取 (Reading)

交互（写入）(Interactions – Write)

社交 (Social)

创作者 (Creator)

账户 (Account)

智能体工作流示例 (Agent Workflow Examples)

搜索 → 阅读 → 点赞流程 (Search → Read → Like pipeline)

NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
xhs read "$NOTE_ID" --json | jq '.data'
xhs like "$NOTE_ID"

浏览热门美食笔记 (Browse trending food notes)

xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'

获取用户信息然后关注 (Get user info then follow)

xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123

检查通知 (Check notifications)

xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'

分析笔记的所有评论 (Analyze all comments on a note)

# 获取所有评论并分析主题 (Fetch ALL comments and analyze themes)
xhs comments "$NOTE_URL" --all --json | jq '.data.comments | length'
# 统计问题数量 (Count questions)
xhs comments "$NOTE_URL" --all --json | jq '[.data.comments[] | select(.content | test("[\uff1f?]"))] | length'

每日阅读工作流 (Daily reading workflow)

# 浏览推荐流 (Browse recommendation feed)
xhs feed --yaml

# 交互式短索引工作流 (Interactive short-index workflow)
xhs search "旅行"
xhs read 1
xhs comments 1
xhs like 1
xhs favorite 1
xhs comment 1 -c "收藏了"

# 按类别浏览热门 (Browse trending by category)
xhs hot -c food --yaml
xhs hot -c travel --yaml

二维码登录 (QR code login)

# 当无法提取浏览器 cookie 时 (When browser cookie extraction is not available)
xhs login --qrcode
# → 启动浏览器辅助登录流程 (Launches a browser-assisted login flow)
# → 使用 Unicode 半块在终端中渲染二维码 (Renders QR in terminal using Unicode half-blocks)
# → 用小红书应用扫描 → 确认 → 导出 cookies (Scan with Xiaohongshu app → confirm → export cookies)

URL 到洞察流程 (URL to insights pipeline)

# 用户粘贴 URL → 阅读 + 所有评论 (User pastes a URL → read + all comments)
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --json
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --json

热门类别 (Hot Categories)

可用于 xhs hot -c <category> 的类别：
fashion（时尚）, food（美食）, cosmetics（美妆）, movie（影视）, career（职场）, love（情感）, home（家居）, gaming（游戏）, travel（旅行）, fitness（健身）

错误代码 (Error Codes)

结构化错误代码在 error.code 字段中返回：

• not_authenticated — cookies 已过期或缺失 (cookies expired or missing)
• verification_required — 需要验证码/验证 (captcha/verification needed)
• ip_blocked — IP 被限流 (IP rate limited)
• signature_error — 请求签名失败 (request signing failed)
• api_error — 上游 API 错误 (upstream API error)
• unsupported_operation — 操作不可用 (operation not available)

限制 (Limitations)

• 无法下载视频 (No video download) — 无法下载笔记图片/视频 (cannot download note images/videos)
• 无私信功能 (No DMs) — 无法访问私信 (cannot access private messages)
• 无直播功能 (No live streaming) — 不支持直播功能 (live features not supported)
• 无法获取关注/粉丝列表 (No following/followers list) — 小红书网页 API 未暴露这些端点 (XHS web API doesn’t expose these endpoints)
• 单账户 (Single account) — 一次只能使用一组 cookie (one set of cookies at a time)
• 速率限制 (Rate limited) — 内置高斯抖动延迟（约 1-1.5 秒）(built-in Gaussian jitter delay ~1-1.5s between requests)；过度使用可能触发验证码或 IP 封锁 (aggressive usage may trigger captchas or IP blocks)

对智能体的反检测提示 (Anti-Detection Notes for Agents)

• 不要并行化请求 (Do NOT parallelize requests) — 内置速率限制延迟是为了账户安全 (the built-in rate-limit delay exists for account safety)
• 验证码恢复 (Captcha recovery): 如果出现 NeedVerifyError，客户端会自动增加延迟进行冷却（5秒→10秒→20秒→30秒）(the client auto-cools-down with increasing delays 5s→10s→20s→30s)。在重试之前，请用户在浏览器中完成验证码。
• 批量操作 (Batch operations): 执行批量工作时（例如，阅读许多笔记），在 CLI 调用之间添加 time.sleep() (when doing bulk work, add time.sleep() between CLI calls)
• 会话稳定性 (Session stability): 一个会话中的所有请求共享一致的浏览器指纹。重新启动 CLI 会创建一个新的指纹会话 (all requests in a session share a consistent browser fingerprint. Restarting the CLI creates a new fingerprint session)

安全提示 (Safety Notes)

• 不要在聊天日志中要求用户分享原始 cookie 值 (Do not ask users to share raw cookie values in chat logs)。
• 优先使用本地浏览器 cookie 提取，而不是手动复制/粘贴密钥 (Prefer local browser cookie extraction over manual secret copy/paste)。
• 如果认证失败，请用户通过 xhs login 重新登录 (If auth fails, ask the user to re-login via xhs login)。
• 智能体应将 cookie 值视为秘密（不要不必要地输出到标准输出）(Agent should treat cookie values as secrets – do not echo to stdout unnecessarily)。
• 内置速率限制延迟保护账户；不要绕过它 (Built-in rate-limit delay protects accounts; do not bypass it)。