From d877c09cd12461a781c409458791c8ed4b3ad8b6 Mon Sep 17 00:00:00 2001
From: Pnant <73925474+Panniantong@users.noreply.github.com>
Date: Tue, 31 Mar 2026 19:10:36 +0800
Subject: [PATCH] docs(skill): add XHS upstream caveats (xsec_token, rate
 limits, unstable commands)

Based on investigation of jackwener/xiaohongshu-cli issues:
- xsec_token: can't read by bare note_id, must search/feed first
- Rate limiting: high-freq requests trigger CAPTCHA
- v0.6.4: user/user-posts/favorites may return API error
- POST operations: may 406 due to signature issues in v0.6.x

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 agent_reach/skill/references/social.md | 32 +++++++++++++++++---------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/agent_reach/skill/references/social.md b/agent_reach/skill/references/social.md
index d81ee8a..25009d5 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
-
-# 发帖/互动
-xhs post --title "标题" --content "正文" --images img1.jpg img2.jpg
-xhs like NOTE_ID
-xhs comment NOTE_ID "评论内容"
 ```
 
+### 已知不稳定的命令（v0.6.4）
+
+```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