# Xiaohongshu

> 小红书全能 Skill：搜索笔记、发布图文/视频、点赞/收藏/评论/回复、用户主页、数据看板、通知。 通过 `xhs` 命令行调用，所有命令支持 --json-output 结构化输出；MCP 引擎负责主要功能（常驻），CDP 引擎负责数据看板/通知并作为回退。

- Skill: `youhai020616/xiaohongshu` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add youhai020616/xiaohongshu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/youhai020616/xiaohongshu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: youhai020616 (https://skillmd.com/u/youhai020616)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/youhai020616/xiaohongshu

---


# 小红书 Skill（redbook-cli）

Agent 通过 `xhs` 命令与小红书交互。**始终加 `--json-output`**：stdout 只有一个 JSON 信封，进度提示在 stderr，退出码 0/1 表示成败。约定见 [SCHEMA.md](./SCHEMA.md)。

## 0. 前置检查

```bash
xhs status --json-output          # data.authenticated 为 true 才能执行主要功能
xhs server status --json-output   # data.running 为 false 时: xhs server start
```

未登录时运行 `xhs login`（会自动启动 MCP 并显示二维码，需要人扫码）。登录是交互操作，无 JSON 模式；扫码后再次 `xhs status --json-output` 确认。

## 1. 搜索 → 短索引 → 操作

```bash
xhs search "AI创业" --json-output                     # 结果自动缓存，序号从 1 开始
xhs search "旅行" --sort 最多点赞 --type 图文 --time 一周内 --json-output
xhs detail 1 --json-output                            # 按短索引查看详情
xhs detail 1 --comments --comment-limit 50 --json-output
xhs like 1 --json-output
xhs fav 1 --json-output
xhs comment 1 -c "写得很实用" --json-output
xhs reply 1 --comment-id CID --user-id UID -c "谢谢" --json-output
```

短索引只在**最近一次搜索**内有效；跨会话请用 `FEED_ID -t XSEC_TOKEN`（两者都在搜索结果里）。

## 2. 发布

```bash
xhs publish -t "标题" -c "正文" -i /abs/a.jpg -i /abs/b.jpg --tags 标签1 --tags 标签2 --json-output
xhs publish -t "标题" -c "正文" -v /abs/video.mp4 --json-output
xhs publish -t "标题" -c "正文" -i /abs/a.jpg --visibility 仅自己可见 --json-output
xhs publish -t "标题" -c "正文" -i /abs/a.jpg --schedule "2026-05-01T10:00:00+08:00" --json-output
xhs publish -t "标题" -c "正文" -i /abs/a.jpg --dry-run --json-output    # 先预览再发
```

规则与陷阱：
- 标题 ≤ 20 字，正文 ≤ 1000 字；`--visibility` 只接受中文值：`公开可见` / `仅自己可见` / `仅互关好友可见`
- 图片可用本地路径或 HTTP URL（本地更快）；视频只接受本地绝对路径
- `--schedule` / `--visibility` / `--original` / `--products` 仅 MCP 引擎支持，CDP 回退时会被忽略（stderr 有警告）
- 发布返回 `status: published` 但 PostID 为空是**正常**的；用 `xhs search "<昵称或标题>"` 验证
- **发布超时不代表失败** —— 先搜索验证，不要盲目重试，避免重复发帖

## 3. 数据与通知（CDP，需要 Chrome）

```bash
xhs analytics --json-output                 # 创作者数据看板
xhs analytics --csv /abs/out.csv            # 导出 CSV
xhs notifications --json-output             # @提及 / 互动通知
xhs me --json-output
xhs profile USER_ID -t XSEC_TOKEN --json-output
```

CDP 登录态与 MCP 独立：`xhs login --cdp` 扫码一次，缓存约 12h。

## 4. 错误处理

| `error.code` | 含义 | 建议动作 |
|---|---|---|
| `not_authenticated` | 未登录 | 提示用户运行 `xhs login` 扫码 |
| `mcp_error` | MCP 未运行 / 调用失败 | `xhs server start`，或加 `--engine cdp` |
| `cdp_error` | Chrome 未启动 / 调用失败 | `xhs login --cdp`，确认 Chrome 已安装 |
| `invalid_argument` | 短索引失效、缺 token、文件不存在 | 重新搜索或改用 `FEED_ID -t TOKEN` |
| `action_failed` | 服务端明确返回失败 | 检查登录态，稍后重试 |

`like` / `favorite` 在 CDP 引擎下可能返回 `ok: true` 但 `data.success: false`，表示动作已执行但无法确认，不要重复点击。

## 5. 引擎与配置

- 引擎自动选择：MCP 服务在运行则用 MCP，否则 CDP。`--engine mcp|cdp` 强制指定
- 代理：`xhs config set mcp.proxy http://127.0.0.1:7897`（大多数环境不需要）
- 同一账号不要在多个网页端同时登录，会踢掉 MCP 的 session
- MCP 无响应：`xhs server status` → `xhs server stop && xhs server start`；日志 `xhs server log`
- Docker 环境：所有命令前加 `docker compose exec cli`，本地文件放 `./docker/data/images/`，容器内路径 `/app/data/images/`

## 附：直接调用 MCP 工具

如果宿主 Agent 本身是 MCP 客户端，可直连 `http://127.0.0.1:18060/mcp`（JSON-RPC）。工具名：`check_login_status` `get_login_qrcode` `delete_cookies` `publish_content` `publish_with_video` `search_feeds` `get_feed_detail` `post_comment_to_feed` `reply_comment_in_feed` `like_feed` `favorite_feed` `list_feeds` `user_profile` `get_self_info`。参数与 `xhs` 命令一一对应；上游文档见 [xpzouying/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)。