lionad-morotar XHS CLI Skill
通过 xiaohongshu-cli 在终端与小红书交互。
Prerequisites
# 检查是否已安装并登录
xhs status
如果未安装：
uv tool install xiaohongshu-cli
# 升级到最新版本
uv tool upgrade xiaohongshu-cli
首次使用需登录：
xhs login # 自动提取浏览器 Cookie
xhs login --qrcode # 扫码登录
xhs whoami # 确认登录状态
Core Commands
认证（Auth）
xhs login # 从浏览器自动提取 Cookie
xhs login --qrcode # 扫码登录（终端显示二维码）
xhs status # 检查登录状态
xhs whoami # 查看当前用户详细资料
xhs whoami --json # 结构化 JSON 输出
xhs logout # 清除保存的 Cookie
搜索（Search）
xhs search "关键词" # 搜索笔记
xhs search "旅行" --sort popular # 排序：general, popular, latest
xhs search "穿搭" --type video # 类型：all, video, image
xhs search "AI" --page 2 # 翻页
xhs search-user "用户名" # 搜索用户
xhs topics "美食" # 搜索话题/标签
阅读（Reading）
# 短索引（在 search/feed/hot/user-posts 之后使用）
xhs read 1 # 阅读上次列表的第 1 条笔记
xhs comments 1 # 查看上次列表的第 1 条笔记评论
# 完整命令
xhs read <note_id> # 阅读笔记（仅 API）
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" # 通过 URL 阅读
xhs comments <url> # 查看评论（URL 含 xsec_token）
xhs comments <url> --all # 获取全部评论（自动翻页）
xhs comments <url> --all --json # 全部评论，JSON 格式
xhs comments <note_id> --xsec-token T # 显式指定 token
xhs sub-comments <note_id> <cmt_id> # 查看评论的回复
xhs user <user_id> # 用户主页
xhs user-posts <user_id> # 用户发布的笔记
xhs user-posts <user_id> --cursor X # 用 cursor 翻页
发现（Feed & Discovery）
xhs feed # 推荐 Feed
xhs hot # 热门笔记（默认：food）
xhs hot -c fashion # 分类：fashion, food, cosmetics,
# movie, career, love, home,
# gaming, travel, fitness
社交（Social）
xhs favorites # 我的收藏夹
xhs favorites <user_id> # 其他用户的收藏
xhs likes # 我的点赞
xhs likes <user_id> # 其他用户的点赞
xhs follow <user_id> # 关注用户
xhs unfollow <user_id> # 取消关注
互动（Interactions）
# 短索引形式（在列表命令之后使用）
xhs like 1 # 给第 1 条笔记点赞
xhs favorite 1 # 收藏第 1 条笔记
xhs comment 1 -c "好赞！" # 评论第 1 条笔记
xhs reply 1 --comment-id X -c "回复" # 回复第 1 条笔记的评论
# 完整形式
xhs like <note_id> # 点赞
xhs like <note_id> --undo # 取消点赞
xhs favorite <note_id> # 收藏
xhs unfavorite <note_id> # 取消收藏
xhs comment <note_id> -c "好赞！" # 发评论
xhs reply <note_id> --comment-id X -c "回复" # 回复评论
xhs delete-comment <note_id> <cmt_id> # 删除自己的评论
创作者（Creator）
xhs my-notes # 我的笔记列表
xhs my-notes --page 1 # 翻页
xhs post --title "标题" --body "正文" --images img.jpg # 发布图文笔记
xhs delete <note_id> # 删除笔记
xhs delete <note_id> -y # 跳过确认
通知（Notifications）
xhs unread # 未读数（点赞、@、新关注）
xhs notifications # 评论和 @ 通知
xhs notifications --type likes # 赞和收藏通知
xhs notifications --type connections # 新增关注通知
Structured Output
所有命令支持结构化输出：
xhs <command> --yaml # YAML 格式（推荐，token 效率高）
xhs <command> --json # JSON 格式
非 TTY 环境（管道/脚本调用）默认输出 YAML。
统一输出信封（Envelope）格式：
ok: true
schema_version: "1"
data: { ... }
error: null
环境变量控制全局格式：
OUTPUT=yaml xhs search "美食" # 强制 YAML
OUTPUT=json xhs whoami # 强制 JSON
Short-Index Navigation
执行列表命令（search/feed/hot/user-posts/favorites/my-notes）后，结果缓存在 ~/.xiaohongshu-cli/index_cache.json。
可用短索引的命令：read, comments, like, favorite, unfavorite, comment, reply
xhs search "美食" # 搜索后缓存结果
xhs read 1 # 阅读第 1 条
xhs comments 1 # 查看第 1 条评论
xhs like 1 # 点赞第 1 条
Error Handling
| 错误 | 解决方案 |
|---|---|
NoCookieError |
浏览器访问 xiaohongshu.com 登录后，执行 xhs login |
NeedVerifyError |
浏览器完成验证码后重试 |
IpBlockedError |
切换网络（热点/VPN） |
SessionExpiredError |
执行 xhs login 刷新 Cookie |
| 请求慢 | 正常现象，内置高斯随机延迟避免风控 |
Best Practices
- 优先使用短索引：先
xhs search，再xhs read 1操作，流畅自然 - 结构化输出用于自动化：脚本中加
--yaml便于解析 - 定期升级：
uv tool upgrade xiaohongshu-cli，避免 API 变更导致错误 - 合理频率：批量操作间增加间隔，避免触发验证码
Examples
# 场景 1：搜索并阅读笔记
xhs search "川菜教程" --sort popular
xhs read 1
xhs comments 1
# 场景 2：查看用户内容
xhs search-user "某博主"
xhs user-posts <user_id> --yaml
# 场景 3：批量获取热门笔记
xhs hot -c travel --yaml
# 场景 4：互动
xhs search "咖啡探店"
xhs like 1
xhs comment 1 -c "看起来很好喝！"
# 场景 5：获取所有评论
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --yaml