Skip to content

Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.

docs(skill): add XHS upstream caveats (xsec_token, rate limits, unstable commands)

Pnantd877c09cd124
diff --git a/agent_reach/skill/references/social.md b/agent_reach/skill/references/social.md
index d81ee8af..25009d51 100644
--- a/agent_reach/skill/references/social.md
+++ b/agent_reach/skill/references/social.md
@@ -4,11 +4,13 @@
## 小红书 / XiaoHongShu (xhs-cli)
+### 稳定可用的命令
+
```bash
-# 搜索笔记
+# 搜索笔记(推荐入口)
xhs search "query"
-# 阅读笔记详情
+# 阅读笔记详情(必须用搜索结果中的 URL 或 ID,不能裸 note_id)
xhs read NOTE_ID_OR_URL
# 查看评论
@@ -19,18 +21,26 @@ xhs hot
# 推荐 feed
xhs feed
+```
-# 用户主页
-xhs user USER_ID
-xhs user-posts USER_ID
+### 已知不稳定的命令(v0.6.4)
-# 发帖/互动
-xhs post --title "标题" --content "正文" --images img1.jpg img2.jpg
-xhs like NOTE_ID
-xhs comment NOTE_ID "评论内容"
+```bash
+# 以下命令当前可能返回 API error,谨慎使用:
+xhs user USER_ID # 可能返回 {code: -1}
+xhs user-posts USER_ID # 可能返回 {code: -1}
+xhs favorites # 可能返回 API error
```
+### 重要注意事项
+
> **安装**: `pipx install xiaohongshu-cli`,然后 `xhs login`(自动从浏览器提取 Cookie)。
+>
+> **xsec_token 限制**: 小红书强制 xsec_token 机制,**不能直接用裸 note_id 去读**。正确流程是:先 `xhs search` 或 `xhs feed` 获取结果,再用结果中的 URL/ID 去 `xhs read`。直接构造 note_id 会被拦截。
+>
+> **频率控制**: 高频请求(批量搜索、深翻评论)会触发验证码,这是平台限制无法绕过。建议每次操作间隔 2-3 秒。
+>
+> **POST 操作风险**: 发帖(post)、评论(comment)、点赞(like) 等写操作在 v0.6.x 可能因签名问题返回 406。如需使用,建议降级到 v0.3.5 (`pipx install xiaohongshu-cli==0.3.5`)。
## 抖音 / Douyin