redbook

Redbook — 小红书 CLI

使用 redbook CLI 在小红书（小红书/RED）上搜索笔记、阅读内容、分析创作者、自动化互动并研究话题。

OpenClaw 用户： 通过 clawhub install redbook 或 npm install -g @lucasygu/redbook 安装。

⚠️ 研究规范（请先阅读）。 小红书风控会限制阅读，不只是写入。任何需要阅读几篇以上笔记的研究，都必须通过研究循环运行——默认按人工节奏执行（每篇约 20 s，一次一篇；普通任务需几十分钟完成，大型任务则分散到一整天内）。在紧密循环中反复调用 read / comments / analyze-viral，几十次以内就会触发验证码 / IP 封禁（300012），并导致账号数小时内受限。⚡ 快速模式仅用于紧急情况，且必须先打印警告并征得用户明确同意。绝不要并行读取，也不要以零延迟读取。

用法

/redbook search "AI编程"              # Search notes
/redbook read <url>                   # Read a note
/redbook user <profileUrl>            # Creator profile
/redbook account-report --file ids.txt --json  # Batch account metrics
/redbook analyze <userId>             # Full creator analysis (profile + posts)

快速参考

意图	命令
搜索笔记	redbook search "keyword" --json
阅读笔记	redbook read <url> --json
获取评论	redbook comments <url> --json --all
创作者资料	redbook user <userId-or-profileUrl> --json
创作者的帖子	redbook user-posts <userId-or-profileUrl> --json
批量账号报告	redbook account-report --file accounts.txt --month YYYY-MM --json
浏览信息流	redbook feed --json
搜索话题标签	redbook topics "keyword" --json
分析热门笔记	redbook analyze-viral <url> --json
提取内容模板	redbook viral-template <url1> <url2> --json
发布评论	redbook comment <url> --content "text"
回复评论	redbook reply <url> --comment-id <id> --content "text"
批量回复（预览）	redbook batch-reply <url> --strategy questions --dry-run
点赞笔记	redbook like <url>
取消点赞	redbook like <url> --undo
列出收藏	redbook favorites --json 或 redbook favorites <userId> --json
收藏笔记	redbook collect <url>
取消收藏	redbook uncollect <url>
列出粉丝	redbook followers <userId> --json
列出关注对象	redbook following <userId> --json
删除自己的笔记	redbook delete <url>
检查笔记状态	redbook health --json 或 redbook health --all --json
列出用户专辑	redbook boards 或 redbook boards <userId> --json
列出专辑笔记	redbook board <board-url> 或 redbook board <boardId> --json
将 Markdown 渲染为卡片	redbook render content.md --style xiaohongshu
发布图片笔记	redbook post --title "..." --body "..." --images img.jpg
检查连接	redbook whoami
为云端 / OpenClaw 保存 Cookie	redbook auth export 或 redbook auth save --cookie-string "a1=...; web_session=..."

以编程方式解析输出时，始终添加 --json。 不添加时，输出为面向用户的格式化文本。

---

小红书平台信号

小红书不同于 Twitter 或 Instagram。这些平台特有的互动比率揭示了内容类型和受众行为。

收藏 / 点赞比率（collected_count / liked_count）

小红书的“收藏”是一种稍后查看机制——用户会建立个人参考资料库。该比率是衡量内容实用性的最强信号。

比率	分类	含义
>40%	工具型（参考资料）	教程、清单、模板——用户收藏以便重复使用
20–40%	认知型（洞察）	发人深省，但不会留待以后查看
<20%	娱乐型（娱乐）	看过就忘——互动是被动的

评论/点赞比率（comment_count / liked_count）

衡量笔记引发讨论的程度。

比率	分类	含义
>15%	讨论型（Discussion）	辩论、分享经历、提出问题
5–15%	正常互动（Normal）	典型的互动模式
<5%	围观型（Passive）	用户点赞，但不再进一步互动

分享/点赞比率（share_count / liked_count）

衡量社交价值——用户是否通过分享来表达身份认同或帮助他人。

比率	含义
>10%	社交价值——人们分享内容以表达品味、身份认同，或帮助朋友
<10%	内容仅供个人浏览，不会转发

搜索排序语义

排序方式	揭示的信息
--sort popular	已验证的上限——关键词能达到的最佳表现
--sort latest	内容发布速度——当前的发布量
--sort general	按算法权重混合排序（默认）

内容形式动态

形式	趋势
图文（图片和文字，type: "normal"）	收藏率更高——用户会保存参考内容
视频（type: "video"）	点赞率更高——更容易被动浏览

---

分析模块

每个模块都是可组合的构建块。可将它们组合起来进行不同深度的分析。

模块 A：关键词互动矩阵

回答： 哪些关键词的互动上限最高？哪些已饱和，哪些服务不足？

命令：

redbook search "keyword1" --sort popular --json
redbook search "keyword2" --sort popular --json
# Repeat for each keyword in your list

从每条结果的 items[] 中提取的字段：

• items[].note_card.interact_info.liked_count — 点赞数（可能使用中文数字：“1.5万” = 15,000）
• items[].note_card.interact_info.collected_count — 收藏数
• items[].note_card.interact_info.comment_count — 评论数
• items[].note_card.user.nickname — 作者

解读方式：

• Top1 上限 = items[0] 的点赞数——该关键词下表现最佳的笔记。这是已验证的需求信号。
• Top10 平均值 = items[0..9] 点赞数的平均值——排名靠前的笔记平均表现如何。
• Top1 较高但 Top10 平均值较低，说明表现主要由一条异常突出的笔记拉动；竞争难度较大。
• Top10 平均值较高，说明需求稳定；更容易进入。

输出： 按 Top1 上限排序的关键词 × 互动数据表。

关键词	Top1 点赞数	Top10 平均值	Top1 收藏数	收藏/点赞
keyword1	12,000	3,200	5,400	45%
keyword2	8,500	4,100	1,200	14%

---

模块 B：跨主题热力图

回答： 哪些主题 × 场景组合存在需求？内容缺口在哪里？

命令：

# Combine base topic with scene/angle keywords
redbook search "base topic + scene1" --sort popular --json
redbook search "base topic + scene2" --sort popular --json
redbook search "base topic + scene3" --sort popular --json

提取字段： 与模块 A 相同——每种组合的 Top1 liked_count。

解读方式：

• Top1 较高 = 该组合存在已验证的需求
• 结果为零或很少 = 存在内容缺口（可能是机会，也可能是没有需求——请检查该组合是否合理）
• 跨场景比较，找出与基础主题最契合的角度

输出： 基础主题 × 场景热力图。

             scene1    scene2    scene3    scene4
base topic   ████ 8K   ██ 2K     ████ 12K  ░░ 200

---

模块 C：互动信号分析

回答： 每个关键词对应哪种内容？参考、见解还是娱乐？

命令： 使用模块 A 的搜索结果，或针对单条笔记：

redbook analyze-viral "<noteUrl>" --json

提取字段：

• 从搜索结果中：根据 interact_info 字段计算比率
• 从 analyze-viral 中：使用预先计算的 engagement.collectToLikeRatio、engagement.commentToLikeRatio、engagement.shareToLikeRatio

解读方式： 应用上文 XHS 平台信号 中的比率基准。

输出： 按关键词或笔记分类。

关键词	收藏/点赞	评论/点赞	类型
keyword1	45%	8%	工具型 + 正常互动
keyword2	12%	22%	娱乐型 + 讨论型

---

模块 D：创作者发现与画像分析

回答： 这个细分领域的关键创作者有哪些？他们采用了哪些策略？

命令：

# 1. Collect unique user_ids from search results across keywords
#    Extract from items[].note_card.user.user_id

# 2. For each creator:
redbook user "<userId>" --json
redbook user-posts "<userId>" --json

要提取的字段：

• 从 user 中提取：interactions[] 里 type === "fans" 的数据 → 粉丝数
• 从 user-posts 中提取：所有帖子的 notes[].interact_info.liked_count → 计算平均值、中位数和最大值
• 从 user-posts 中提取：notes[].display_title → 内容模式、发布频率

解读方式：

• 平均点赞数与中位数： 差距较大表示爆款拉高了平均值。中位数才是“真实”的基准。
• 最大值与中位数的比值： >5× 表示创作者曾发布过爆款。重点研究这些笔记。
• 发帖频率： 统计笔记数量以估算发布节奏。高产创作者（>3 篇/周）与注重质量的创作者（<1 篇/周）。

输出： 创作者对比表。

创作者	粉丝数	平均点赞数	中位数	最大值	帖子数	风格
@creator1	12万	3,200	1,800	45,000	89	教程
@creator2	5.4万	8,100	6,500	22,000	34	故事

---

模块 D2：已知账号报告

回答： 对于给定的账号 ID / 个人资料 URL 列表，每个账号的发帖频率如何？每篇帖子的表现如何？

当用户已有 KOS/KOC 账号 ID，并需要按账号统计的清晰指标时使用此功能。不要用关键词搜索近似替代；关键词搜索会引入无关帖子，导致归因噪声。

redbook account-report --file accounts.txt --month 2026-07 --json
redbook account-report "<profileUrl1>" "<profileUrl2>" --max-pages 2 --json

输入文件应包含以换行分隔的用户 ID 或个人资料 URL；空行和 # 注释会被忽略。如果有可用的个人资料 URL，优先使用包含 xsec_token 的 URL。JSON 输出包含账号摘要字段（fetchedPosts、postsInMonth、complete、pagesFetched）、互动总数和平均值、热门帖子，以及包含标题、类型、发布时间、指标和 webUrl 的逐条笔记数据。

默认模式下，每个账号只抓取第一页。complete: false 表示还有更多页面。只有当用户明确需要完整历史记录且账号列表足够小、可以安全控制抓取节奏时，才使用 --all；否则优先使用 --max-pages <n>。

---

模块 E：内容形式分析

回答： 对这个主题而言，图文笔记还是视频笔记的表现更好？

命令：

redbook search "keyword" --type image --sort popular --json
redbook search "keyword" --type video --sort popular --json

要提取的字段：

• 比较两组结果中 Top1 和 Top10 的平均 liked_count 与 collected_count
• 查看 type 字段："normal" = 图文，"video" = 视频

输出： 内容形式 × 互动表现表。

内容形式	Top1 点赞数	Top10 平均值	收藏/点赞
图文	8,000	2,400	42%
视频	15,000	5,100	18%

---

模块 F：机会评分

回答： 我应该重点做哪些关键词？哪里投入产出比最高？

输入： 模块 A 的关键词矩阵。

评分逻辑：

• 需求 = Top1 点赞数上限（已验证的受众规模）
• 竞争度 = 高互动结果的密度（Top10 中点赞数 >1K 的笔记数量）
• 得分 = 需求 × (1 / 竞争密度)

等级阈值（基于 Top1 点赞数）：

等级	Top1 点赞数	含义
S	>100,000（10万+）	需求巨大——竞争激烈，但潜力巨大
A	20,000–100,000	需求强劲——竞争激烈，但有机会胜出
B	5,000–20,000	需求适中——适合成长中的账号
C	<5,000	细分领域——竞争较低，上限也较低

输出： 分级关键词列表。

等级	关键词	Top1	竞争度	机会
A	keyword1	45K	中（6/10 >1K）	高
B	keyword3	12K	低（2/10 >1K）	非常高
S	keyword2	120K	高（10/10 >1K）	中

---

模块 G：受众推断

回答： 这个细分领域的受众是谁？他们想要什么？

输入： 模块 C 的互动率 + analyze-viral 的评论主题 + 内容模式。

从 analyze-viral JSON 中提取的字段：

• comments.themes[] — 评论区中反复出现的短语和关键词
• comments.questionRate — 评论中问题所占的比例（学习意愿）
• engagement.collectToLikeRatio — 收藏行为体现的意愿
• hook.hookPatterns[] — 能吸引该受众的标题模式

推断规则：

• 收藏率高 + 提问率高 → 注重学习的受众（学生、专业人士）
• 评论率高 + 情绪化主题 → 注重社区互动的受众（分享经历）
• 分享率高 → 注重向往感的受众（生活方式、身份表达）
• 评论语言模式 → 年龄／教育程度信号（正式 = 年长，俚语 = 年轻）

输出： 受众画像摘要 — 人口统计特征、意图、内容偏好。

---

模块 H：内容构思

回答： 有哪些具体内容值得创作，并且有数据支撑？

输入： 机会评分（模块 F）+ 受众画像（模块 G）+ 热度图中的空白（模块 B）。

针对每个内容创意，说明：

• 目标关键词 — 来自机会评分
• 吸引角度 — 基于该细分领域有效的 hookPatterns
• 内容类型 — 根据受众需求选择工具型／认知型／娱乐型
• 形式 — 根据模块 E 选择图文或视频
• 互动目标 — 根据该关键词 Top10 的平均值设定现实目标
• 竞争参考 — 具体的笔记 URL，证明此角度有效

输出： 按优先级排序且有数据支撑的内容创意。

#	关键词	吸引角度	类型	目标点赞数	参考
1	keyword3	“N个方法...” (列表)	工具型 图文	5K+	[热门笔记 URL]
2	keyword1	“为什么...” (问题)	认知型 视频	10K+	[热门笔记 URL]

---

模块 I：评论运营

回答： 哪些评论值得回复？评论质量的分布如何？

命令：

# 1. Fetch all comments
redbook comments "<noteUrl>" --all --json

# 2. Preview reply candidates (dry run)
redbook batch-reply "<noteUrl>" --strategy questions --dry-run --json

# 3. Execute replies with template (5 min delay with ±30% jitter)
redbook batch-reply "<noteUrl>" --strategy questions \
  --template "感谢提问！关于{content}，..." \
  --max 10

从 --dry-run JSON 中提取的字段：

• candidates[].commentId — 目标评论
• candidates[].isQuestion — 布尔值，检测到的问题
• candidates[].likes — 互动信号
• candidates[].hasSubReplies — 是否已有回复
• skipped — 被过滤掉的评论数量
• totalComments — 获取的评论总数

策略：

• questions — 回复以 ？ 或 ? 结尾的评论（注重学习的受众）
• top-engaged — 回复获赞最多的评论（获得最大曝光）
• all-unanswered — 回复没有现有子回复的评论（填补空缺）

解读方式：

• 提问率高（>15%）= 受众注重学习 → 通过回复树立专业权威
• 高互动评论获赞多（>100）= 回复曝光度高的评论，以获得最大触达
• 未回复评论较多 = 互动缺口，可借此提高回复率

安全性： 每批最多回复 30 条，最短延迟为 3 分钟，带有 ±30% 的随机抖动（默认 5 分钟）；默认使用 --dry-run（无模板 = 仅预览）；遇到验证码立即停止。详情请参阅速率限制与安全。

输出： 回复计划表，包含候选评论、策略匹配原因和状态。

---

模块 J：病毒式传播复刻

解答： 我可以从成功的笔记中提取哪些结构模板，为新内容创作提供指导？

命令：

# 1. Find top notes for a keyword
redbook search "keyword" --sort popular --json

# 2. Extract structural template from 2-3 top performers
redbook viral-template "<url1>" "<url2>" "<url3>" --json

从 viral-template JSON 中提取的字段：

• dominantHookPatterns[] — 多数笔记中出现的钩子类型
• titleStructure.commonPatterns[] — 特定的标题公式
• titleStructure.avgLength — 目标标题长度
• bodyStructure.lengthRange — 目标字数范围 [最小值, 最大值]
• bodyStructure.paragraphRange — 目标段落数
• engagementProfile.type — 参考/洞察/娱乐
• audienceSignals.commonThemes[] — 受众讨论的内容

如何解读：

• 多篇笔记中钩子模式一致 = 该细分领域经过验证的公式
• 正文长度范围较窄 = 受众对内容长度有明确偏好
• 互动概况中的收藏/点赞较高 = 受众会保存内容 → 创作参考资料
• 常见评论主题 = 新内容可探讨的话题

与其他模块组合：

• 使用模块 A 的结果，找出适合提取模板的热门 URL
• 将结果作为结构约束传递给模块 H（内容构思）
• 使用模块 C 的分类结果验证互动概况

输出： 内容模板规范 — 内容创作的结构框架。大模型（通过组合工作流）会使用此模板生成实际的标题、正文、话题标签和封面图片提示词。

---

模块 K：互动自动化

解答： 我该如何管理与受众的持续互动？

此模块是一个将模块 I 和 J 与人工监督相结合的工作流。

工作流：

1. 监控 — 使用 redbook comments "<myNoteUrl>" --all --json 获取最新评论
2. 筛选 — 使用 redbook batch-reply --strategy questions --dry-run 找出适合回复的评论
3. 审核 — 人工审核 dry-run 输出（或由大模型依据人设指南审核）
4. 执行 — 使用 redbook batch-reply --strategy questions --template "..." --max 10
5. 报告 — 汇总已发送的回复、遇到的错误和速率限制状态

安全规则：

• 始终先使用 --dry-run，执行前须经人工批准
• 每个会话最多回复 30 条（硬性上限）
• 回复之间至少间隔 3 分钟，默认间隔 5 分钟，并随机加入 ±30% 的抖动
• 不要重复回复同一条评论（检查 hasSubReplies）
• 遇到验证码时立即停止，不要重试
• 有关 XHS 风险控制阈值，请参阅速率限制与安全

防垃圾信息指南：

• 在不同批次中更换回复模板
• 每条笔记每天最多运行 1-2 次批量回复
• 优先保证质量（定向策略），而非追求数量
• 固定的时间模式会触发机器人检测 — 系统会自动加入抖动

模块 L：卡片渲染

**解答：**如何将 Markdown 内容转换为适合发布到小红书的图片卡片？

命令：

# Render markdown to styled PNG cards
redbook render content.md --style xiaohongshu

# Custom style and output directory
redbook render content.md --style dark --output-dir ./cards

# JSON output (for programmatic use)
redbook render content.md --json

**输入：**带有 YAML frontmatter 的 Markdown 文件：

---
emoji: "🚀"
title: "5个AI效率技巧"
subtitle: "Claude Code 实战"
---

## 技巧一：...
Content here...

---

## 技巧二：...
More content...

**输出：**同一目录下的 cover.png + card_1.png、card_2.png……

卡片规格：

• **尺寸：**1080×1440（3:4 比例，小红书标准图片尺寸）
• **DPR：**2（视网膜屏幕品质，实际输出尺寸为 2160×2880）
• **样式：**紫色、小红书、薄荷、日落、海洋、优雅、深色

分页模式：

• auto（默认）— 使用字符数启发式算法，在标题或段落边界处智能拆分
• separator — 根据 Markdown 中的 --- 手动拆分

使用说明：

• 使用用户现有的 Chrome 进行渲染（通过 puppeteer-core）——无需下载浏览器
• 完全离线运行——无需 XHS API 或 Cookie
• 输出图片可直接用于 redbook post --images cover.png card_1.png ...

**依赖项：**需要 puppeteer-core 和 marked（可选，通过 npm install -g puppeteer-core marked 安装）。

与其他模块组合使用：

• 与模块 H（内容构思）搭配——生成内容创意、撰写 Markdown，并渲染为卡片
• 与模块 J（爆款复刻）搭配——提取模板、撰写符合模板的内容，并进行渲染
• 输出可传入 redbook post --images 进行发布

---

模块 M：笔记健康检查（限流检测）

**解答：**我的笔记是否被小红书暗中限流？

小红书会在创作者后台 API 中为每篇笔记分配一个隐藏的 level 字段。该等级会影响推荐分发，但不会显示在界面中。你的笔记看起来可能“正常”，实际上却收不到任何推荐。

命令：

# Check all notes (first page)
redbook health

# Check all pages
redbook health --all

# JSON output for programmatic use
redbook health --all --json

等级定义：

等级	状态	含义
4	🟢 正常	完整推荐分发
2-3	🟡 基本正常	基本正常，存在轻微限制
1	⚪ 新笔记	审核中（新发布的笔记）
-1	🔴 轻度限流	轻微限流，推荐减少
-5 至 -101	🔴 中度限流	中度限流，几乎没有推广
-102	⛔ 严重限流	不可逆——必须删除并重新发布

其他检查：

• 敏感词检测 — 标记标题中包含自动化/AI 关键词的笔记（自动化、AI生成、批量等）
• 标签数量警告 — 标记标签数超过 5 个的笔记（风险因素）

使用说明：

• 等级为 -1 或更低 = 笔记正在被限流。可考虑编辑或删除后重新发布。
• 等级为 -102 = 不可逆。删除笔记并创建全新内容。
• 命中敏感词 = 标题中含有可能触发限流的高风险关键词。请改写。
• 标签过多 = 可能被视为垃圾信息。使用 3-5 个有针对性的标签。

**输出：**终端仪表板，显示颜色编码的分布摘要、受限笔记列表和风险因素警告。

发现致谢：@xxx111god — xhs-note-health-checker

---

组合工作流

组合不同模块，满足不同深度的分析需求。

快速主题扫描（约 5 分钟）

**模块：**A → C → F

搜索 3–5 个关键词，分类互动类型并排列机会。适合快速验证一个细分领域是否值得深入研究。

内容规划

**模块：**A → B → E → F → H

构建关键词矩阵，绘制主题 × 场景交叉关系，检查内容形式的表现，为机会评分，并构思具体的内容创意。

创作者竞品分析

**模块：**A → D

找出在某个细分领域占据主导地位的创作者，并研究其内容策略、发布频率和互动模式。

完整细分领域分析

**模块：**A → B → C → D → E → F → G → H

全面的分析方案——关键词全景、跨主题热力图、互动信号、创作者档案、内容形式分析、机会评分、受众画像和数据支持的内容创意。

单篇笔记深度分析

命令： redbook analyze-viral "<url>" --json

无需组合模块——analyze-viral 一次调用即可返回钩子分析、互动率、评论主题、作者基准对比，以及 0-100 的爆款评分。

爆款模式研究 → 内容模板

# 1. Find top notes
redbook search "keyword" --sort popular --json

# 2. Extract template from top 3 notes (replaces manual synthesis)
redbook viral-template "<url1>" "<url2>" "<url3>" --json

viral-template 将此前需要手动综合 analyze-viral 结果的工作自动化。它会输出一个 ContentTemplate JSON，其中包含主要钩子、正文结构范围、互动情况和受众信号。

回复管理

模块： I

用于管理笔记评论互动的单模块工作流。先使用 batch-reply --dry-run 进行审核，再使用模板执行。

内容复刻

模块： A → J → H → L

关键词研究 → 爆款模板提取 → 基于数据的内容构思 → 渲染为图片卡片。模板会提供结构约束，为模块 H 的内容创意提供指引。模块 L 会将最终 Markdown 渲染为适用于小红书（XHS）的 PNG 图片。

端到端内容创作

模块： A → J → H → L → post

完整流程：研究关键词 → 提取爆款模板 → 构思内容 → 撰写 Markdown → 渲染为样式化图片卡片 → 通过 redbook post --images cover.png card_1.png ... 发布

账号健康监测

模块： M

定期运行 redbook health --all，尽早发现被限流的笔记。如果等级低于 1，请检查笔记内容是否违反政策。结合模块 I，检查被限流笔记是否仍有值得回复的未答复评论。

完整运营

模块： A → C → I → J → K → M

全面的自动化运营方案——关键词分析、互动分类、评论操作、爆款复刻模板和互动自动化工作流。

---

速率限制与安全

小红书（XHS）会严格执行反垃圾（风控）措施，通过设备指纹、活动比例监控和时间模式分析来检测自动化行为。CLI 根据平台研究采用安全默认值。

安全阈值

操作	安全间隔	CLI 默认值	硬性上限
发布笔记	3-4 小时（每天最多 2-3 篇）	N/A（手动）	—
评论	≥3 分钟	N/A（手动）	—
回复	≥3 分钟	N/A（手动）	—
批量回复延迟	≥3 分钟	5 分钟 ±30% 抖动	—
批量回复数量	—	10	30

反检测措施

• 时间抖动： 所有批量操作延迟均随机浮动 ±30%。固定间隔是机器人的特征。
• 硬性上限： 每批最多回复 30 条（从 50 条下调）。不可覆盖。
• 速率限制警告： post、comment 和 reply 命令会在每次操作后显示安全间隔提醒。
• 验证码熔断机制： 遇到验证码（NeedVerify）时，批量操作会立即停止。

触发风控的情况

• 时间固定——按精确的 3 秒间隔回复会触发机器人检测
• 频率过高——任意操作类型每分钟超过 50 次互动
• 活动比例异常——评论数超过笔记浏览量，表明行为不真实
• 设备指纹不匹配——小红书（XHS）会对 21 项硬件参数进行指纹识别

Agent 最佳实践

1. 始终先运行 --dry-run，审核候选内容后再执行
2. 使用默认的 5 分钟延迟——不要将 --delay 覆盖为低于 180000（3 分钟）的值
3. 每篇笔记每天最多执行 1-2 次批量操作
4. 每批次更换回复模板
5. post 命令之间间隔 3-4 小时（每天最多发布 2-3 篇笔记）

---

研究循环 — 安全应对速率限制的长期研究

上面的速率限制与安全部分控制的是写入频率。本节控制的是读取频率——研究过程中实际会大量触发的操作。read、comments 和 analyze-viral 都会调用笔记详情 API（携带 xsec_token）；如果在短时间内连续调用 30–50 次，XHS 就会返回 NeedVerify / 验证码，或者封锁你的 IP（300012），而触发风控的账号会在数小时内保持受限状态。因此，这里的研究采用限速而非并行：一次只处理一篇笔记，并留出间隔，让行为看起来像人在阅读，而不是脚本在抓取。

此机制采用基于文件的循环：将待处理工作项放在磁盘上，每个“周期”处理一项，并立即保存每项结果的检查点。由于所有状态都保存在文件中，循环可恢复，且不会因会话结束而中断——新会话（或 Push 心跳）会从上次停止的位置准确继续。综合分析步骤可搭配 /checkpoint-research 技能使用。

节奏 — 安全范围（为何采用这些数字）

这些参数是根据 XHS 有文档记录的读取侧安全范围校准的，并非凭空猜测。社区爬虫（MediaCrawler）默认采用 约 2 秒/请求、单线程（CRAWLER_MAX_SLEEP_SEC = 2，MAX_CONCURRENCY_NUM = 1）；逆向分析文章指出，“看起来像人类”的频率是 3–8 秒/请求，每个 IP 的上限为 ≤5 次请求/分钟（平均约 12 秒）。此技能使用你的真实登录 Cookie + 住宅 IP + 真实 Chrome 指纹——这是检测率最低的配置（爬虫会把大部分精力花在伪造这些特征上）。因此，主要风险并非请求特征，而是行为模式：人类不会在两分钟内打开 100 个笔记详情页。我们因此按照人类的阅读节奏限速——远在安全范围之内——而不是追求绝对最低间隔。（此前猜测的 5 分钟间隔，比上限慢约 25 倍，却毫无益处。）

真正的规则：像人一样阅读（而不是“放慢速度”）

这里的检测是基于行为分布的，而不是基于速率阈值。XHS 不会问“请求是否超过 N 次？”——它会对人类会话的样子建模，并标记那些不太可能出现的行为。单纯的速度并不是破绽；行为的形态才是。以下三点会暴露脚本：

• **时间微观结构。**人类操作之间的间隔方差很大，且呈重尾分布（2 s，然后 40 s，再然后 5 min——人们会阅读、滚动、分心）。脚本则会发出紧凑、低方差的请求流。五秒内进行三次不同搜索，方差几乎为零，而且快到人类来不及阅读搜索结果页——光这一点就比总次数更能说明问题。
• **会话宏观结构。**人类会深入浏览：搜索 → 打开一篇笔记 → 停留阅读 → 打开相关笔记 → 随意浏览。抓取则是广度优先的枚举：搜索 A、搜索 B、搜索 C……从不点进去，也不停留。关键词列表从头到尾依次跑一遍，本身就是特征。
• **操作组合。**真实会话会混合点赞、收藏、停留、滚动和观看视频。研究任务则是 100% 阅读，不停留，也不互动——对人类来说，这种比例不可能出现。

因此，规则不是“放慢速度”。而是让会话看起来与真人阅读毫无区别：具有符合人类习惯的方差（加入抖动和偶尔的长时间停顿，而不是只把固定间隔调大），一次只读一篇笔记，并留出阅读时间，注重深度而非广度，设置上限，因为人们不会打开数百个内容；并且一遇到阻力就停止（遇到验证码的人会退后，机器人则会重试——所以断路器本身就是符合人类习惯的行为）。

**安全优先体现的是更具 Agent 特质的做法，而非畏首畏尾。**Agent 的真正优势不在速度，而在于大规模持续等待的耐心：它可以按符合人类习惯的方式循环运行八小时，而人类做不到。激进只会模仿最容易让人被识破的人类特质（急躁），浪费 Agent 独有的优势（不知疲倦的耐心）。要善用这份耐心。

**这是一个行为模式，不是黑名单。**这里的数字根据一次真实事件校准得出——一次饮料趋势扫描，在约 17 个互不相关的关键词中，于约 5 秒内触发了3 次不同搜索，并导致账号级警告。这里编码的是行为不变量（符合人类习惯的时间间隔、同一时间只处理一个请求、上限、停留时间、断路器），**而不是“不要搜索那些关键词”。**它适用于任何主题和任何平台。这次事件是用于确定人类与机器人界限的校准样本，而不是一条关于抹茶的规则。

三种模式

模式	每篇笔记的间隔	~读取次数/分钟	适用场景	条件
🚶 稳定（默认）	20 s ± 50% 抖动（≈10–35 s）	~2–3	所有常规研究／多篇笔记研究	无——这是默认模式。
🐢 深入／通宵	60–120 s	~0.5–1	超大型语料库，或需要尽量减少访问痕迹	大型任务可选择此模式
⚡ 快速（紧急）	5 s ± 抖动下限，最多连续突发读取 30 篇笔记，然后冷却	~10+（超过安全上限）	确实无法等待的紧急截止期限	必须原样打印快速模式警告，并取得用户明确同意

**所有模式的不变量：**绝不零延迟，绝不并行，同一时间恰好只处理一篇笔记；除非是已发出警告的快速模式，**持续读取次数绝不超过约 5 次／分钟。**稳定模式下，100 篇笔记的队列约需 35–50 分钟完成；只有非常大的队列或深入模式才会耗至一天结束。

严格规则（不可妥协）

1. 必须运行循环；Steady 是默认节奏。 任何涉及超过约 5 条笔记的研究都必须以 Steady 节奏运行循环。Deep/overnight 和尤其是 Fast 都必须明确选择；Fast 还需要打印警告并获得用户确认。
2. 同一时间只处理一条笔记。 绝不批量或并行读取。不能在没有条目间延迟的情况下运行 for url in …; do redbook read …; done。不能通过后台 & 扇出。（MAX_CONCURRENCY = 1，与参考爬虫相同。）
3. 始终控制在每分钟约 5 次读取以内，并加入随机抖动。 单 IP 的安全上限约为每分钟 5 个请求（每条笔记约 12 秒）；Steady（20 秒）明显低于此上限。每次等待都要应用 ±50% 的随机抖动——固定间隔是机器人特征。只有发出警告后的 Fast 模式才可超过此上限。
4. 限制评论分页。 评论／子评论读取是风险最高的端点——最先触发风控（即使休眠很长时间，深度爬取评论也会失败）。将 --comment-pages ≤ 3，并像其他读取一样，将每个评论页计入节奏和预算；绝不深度爬取评论串。
5. 每处理一项都要设置检查点。 将每条结果写入磁盘并更新清单，然后再进入下一次循环。不能只保存在内存中。
6. 遵守每日预算。 默认软上限为每天约 200 次详情读取——异常的读取量本身就是风控触发因素，与读取节奏无关。当 consumedToday >= dailyBudget 时，停止操作，直到下一个日历日——不要“再多完成几条”。
7. 熔断器绝对有效。 首次出现风控信号时（参见熔断器），立即停止整个循环、保存状态并告知用户，不得自动重试绕过熔断。只有收到明确的人工“恢复”指令后才能继续。
8. 读取，不写入。 此循环仅用于读取／分析。互动操作（评论／回复／点赞）遵守各自的写入端限制，绝不纳入研究循环的一次迭代中。

状态约定（可恢复，即使会话终止也能保留）

所有状态都保存在同一个任务目录下——默认位于私有内容仓库中的 research/xhs/<job-slug>/（如果不清楚使用哪个仓库，请先询问）：

文件	作用
queue.jsonl	工作队列，每行一项：{ "id": "001", "kind": "read|comments|analyze-viral|search|user|user-posts", "arg": "<url-or-keyword-or-userId>", "status": "pending|done|error", "note": "" }
results/<id>.json	每项处理结果的原始 --json 输出（语料库）
loop-state.json	{ "mode": "steady|deep|fast", "intervalSec": 20, "jitterPct": 50, "dailyBudget": 200, "consumedToday": 0, "budgetDate": "YYYY-MM-DD", "lastTickAt": "<iso>", "breaker": "ok|tripped", "breakerReason": null }（Deep：intervalSec 为 60–120；Fast：intervalSec 为 5，且 mode:"fast"）
manifest.md	人类可读的计划和进度（每项完成后标记勾选）——恢复检查点，每次循环迭代后更新
SUMMARY.md	队列清空后编写的最终综合总结

填充队列： 使用廉价的列表端点（search、feed，以及使用新鲜个人资料 URL／令牌的 user-posts）来构建队列，而不是将它们纳入限速循环。预先运行 search／feed，提取每条笔记的 webUrl，然后为每条笔记在 queue.jsonl 中写入一项 read／analyze-viral 任务。之后，循环会以 Steady 节奏处理昂贵的详情读取。始终将带令牌的新鲜 webUrl 作为任务的 arg——令牌会过期，因此不要只将 noteId 加入队列（参见 xsec_token）。对于创作者队列，优先使用包含 xsec_token 的个人资料 URL；仅使用 userId 可能会返回 code=-1。

一次 tick = 一条笔记

tick 是两个驱动程序都会调用的处理单元。每次只处理一项，然后停止：

1. 加载 loop-state.json。 如果 breaker != "ok" → 立即退出（说明原因；不要处理）。
2. 滚动每日预算。 如果 budgetDate != 今天，则重置 consumedToday = 0、budgetDate = today。如果 consumedToday >= dailyBudget → 退出，直到明天。
3. 从 queue.jsonl 中弹出下一项 pending 项目。 如果没有剩余项目 → 完成收尾：根据 results/ 生成 SUMMARY.md，将循环标记为完成，并告知驱动程序停止。完成。
4. 恰好执行一次读取： redbook <kind> "<arg>" --json。
5. 检查结果中是否有风控信号（空 {}、NeedVerify/captcha、Session expired、IP 封禁 300012）。如果发现 → 触发断路器：设置 breaker:"tripped" + breakerReason，将该项目保留为 pending（不计入已处理），持久化，向用户说明，然后停止。（参见断路器。）
6. **成功时：**写入 results/<id>.json，将项目的 status 设为 "done"，在 manifest.md 中勾选该项，consumedToday += 1，设置 lastTickAt。
7. **停止。**每次只处理一条笔记——驱动程序会在（带随机抖动的）间隔后重新调用。

驱动程序——让循环在后台持续运行

同一个 tick，有两种驱动方式。根据任务需要运行多久来选择：

**A）会话内节奏控制（默认 — Steady）。**这是最简单的驱动方式，也适用于大多数任务：在一个会话内连续运行多个 tick，每次读取之间休眠 intervalSec ± 随机抖动。采用 Steady 节奏时，100 条笔记的队列约需 35–50 分钟完成——完全能在一个会话内完成；且每项都会保存检查点，因此崩溃后只需恢复即可。无需调度器。（控制每次读取的节奏；不要用一次长时间阻塞的 sleep 来模拟。）

**B）/loop 自主节奏控制（Deep / 过夜 / 跨越空闲间隔）。**对于 Deep 模式或持续数小时的任务，使用 /loop 驱动 tick，不设间隔（自主节奏）：执行一次 tick，然后通过 ScheduleWakeup 设置 intervalSec + 随机抖动的唤醒时间，再次触发。ScheduleWakeup 的下限为 ≥60 s，因此适用于 Deep（60–120 s）——不适用于不到一分钟的 Steady（按 A 在会话内运行）。队列处理完毕（步骤 3）或断路器触发（步骤 5）时，循环会自行结束。

C）Hook — Push 定期 issue（多日 / 真正的后台运行，可跨应用重启）。最适合“每天运行一次”的研究任务，或大到无法在一天内完成的语料库。创建一个定期 issue（每个 tick 的 recurringIntervalSec 可设为几分钟，或每天扫描一次），并分配给具备 redbook 能力的 Agent。每次触发都是一个全新会话 = 针对同一任务目录的一个 tick——因此 issue 正文必须指向任务目录，并说明“恰好运行一次 tick，然后退出”。它会持续触发，直到有人将其停用；队列处理完毕时，Agent 会完成收尾并发表评论；若断路器触发，则会发表评论并保留 issue，等待人工处理。（Push“侦察”模式——计划安排在 issue 上，Agent 的 Auto 开关控制是否启用。）

**为何使用文件状态，而非长期运行的进程：**单个阻塞式 sleep 循环会随终端关闭而终止，且无法恢复。队列、loop-state.json 和每项结果文件意味着，任何后续会话——/loop 唤醒、Push 心跳或人工重新运行 tick——都能从上次停止的位置准确继续，并且不会丢失已收集的部分语料。

⚡ Fast 模式警告（仅限紧急情况）

在任何 Fast 模式运行之前，必须逐字打印以下内容，并要求用户明确回复“yes, fast mode”。用户没有回复或只给出模糊的肯定答复时，不得继续：

⚠️  XHS FAST RESEARCH MODE — elevated 风控 risk
    Reading at ~12 notes/min crosses the safe ~5/min ceiling and
    materially raises the chance of:
      • captcha / NeedVerify mid-run (stops the loop)
      • IP block (error 300012) for hours
      • account-level recommendation throttling
    Steady mode (the default, ~20s/note) stays inside the safe band
    and still finishes a typical job in well under an hour.
    Proceed with fast mode for this run only? (yes / no)

Fast 模式仍遵守下限（笔记之间至少间隔 5 s ± 随机抖动——绝不为零），每批最多处理 30 条笔记，然后强制冷却并恢复到 Steady 节奏；断路器仍会在出现首个风控信号时硬性停止。Fast 模式会将节奏提升到安全上限之上，但绝不会取消下限或断路器。

熔断器

读取时遇到以下任一情况，立即触发熔断并停止整个循环：

信号	出现位置
NeedVerify / 验证码	错误消息或响应标记
空 {} 响应	通常表示 xsec_token 已过期或无效，或触发了反爬机制——使用新的 webUrls 重新填充队列，不要盲目重试
Session expired / "No 'a1' cookie"	Cookie 无效——继续操作前先在 Chrome 中重新登录
IP 封禁 300012	严格限流——等待解除或切换网络

触发时：设置 loop-state.breaker:"tripped" 和 breakerReason，将当前条目保留为 pending，持久化，并告知用户（或在 Push issue 中发表评论）。绝不要在封禁期间自动重试——这会让轻度限流升级为持续数小时的封禁。只有在人工解决问题并明确表示继续后，才能恢复。

---

API 与浏览器的限制

以下操作通过 API 可以可靠地完成：

• 读取：搜索、笔记、评论、用户资料、动态、收藏
• 写入：顶级评论、评论回复、收藏/取消收藏笔记
• 分析：爆款评分、模板提取、批量回复规划

以下操作通过 API 不可靠（经常触发验证码）：

• 发布笔记（使用 --private 可提高成功率）
• 极高频率的批量操作

以下操作需要浏览器自动化（此 CLI 不支持）：

• 验证码识别、实时通知
• 点赞/关注（反自动化限制严格）
• 私信
• 封面图片生成（使用 Gemini/DALL-E 等外部工具）

---

命令详情

redbook search <keyword>

按关键词搜索笔记。返回笔记标题、URL、点赞数和作者信息。

redbook search "Claude Code教程" --json
redbook search "AI编程" --sort popular --json        # Sort: general, popular, latest
redbook search "Cursor" --type image --json           # Type: all, video, image
redbook search "MCP Server" --page 2 --json           # Pagination

选项：

• --sort <type>：general（默认）、popular、latest
• --type <type>：all（默认）、video、image
• --page <n>：页码（默认：1）

redbook read <url>

读取笔记的完整内容——标题、正文、图片、点赞数和评论数。

redbook read "https://www.xiaohongshu.com/explore/abc123" --json

接受完整 URL 或短笔记 ID。如果 API 返回验证码，则回退到 HTML 抓取。

redbook comments <url>

获取笔记评论。使用 --all 获取所有页面。

redbook comments "https://www.xiaohongshu.com/explore/abc123" --json
redbook comments "https://www.xiaohongshu.com/explore/abc123" --all --json

redbook user <userId|profileUrl>

获取创作者资料——昵称、简介、粉丝数、笔记数和获赞数。

redbook user "https://www.xiaohongshu.com/user/profile/5a1234567890abcdef012345?xsec_token=...&xsec_source=pc_search" --json

接受裸 userId 或完整资料页 URL。如果裸 userId 返回 code=-1，请使用包含 xsec_token 的新资料页 URL，或传入 --xsec-token <token> --xsec-source pc_search。

redbook user-posts <userId|profileUrl>

列出创作者发布的所有笔记。返回标题、URL、点赞数和时间戳。

redbook user-posts "https://www.xiaohongshu.com/user/profile/5a1234567890abcdef012345?xsec_token=...&xsec_source=pc_search" --json

redbook account-report <userId|profileUrl...>

批量汇总账号发帖和互动指标。

redbook account-report --file accounts.txt --month 2026-07 --json
redbook account-report "<profileUrl1>" "<profileUrl2>" --max-pages 2 --json

选项：

• --file <path>：以换行符分隔的账号 ID/资料页 URL
• --month <YYYY-MM>：用于 postsInMonth 的月份（默认：当前月份）
• --max-pages <n>：未使用 --all 时每个账号的页数上限（默认：1）
• --all：获取每个账号的所有页面
• --delay <ms>：页面/账号请求之间的延迟（默认：3000）

进行 KOS/KOC 报告时，请输入已知账号 ID 或资料页 URL，不要使用关键词搜索。如果裸 userId 返回 code=-1，请使用包含 xsec_token 的新资料页 URL。

redbook feed

浏览推荐动态。

redbook feed --json

redbook topics <keyword>

搜索话题标签。可用于查找可添加到帖子中的热门话题。

redbook topics "Claude Code" --json

redbook favorites [userId]

列出用户收藏的笔记。未提供 userId 时，默认使用当前登录用户。

redbook favorites --json                        # Your own favorites
redbook favorites "5a1234567890abcdef" --json   # Another user's favorites
redbook favorites --all --json                  # Fetch all pages

选项：

• --all：获取所有收藏页面（默认仅获取第一页）

注意： 仅当其他用户未将收藏设为私密时，才能查看其收藏。

redbook collect <url>

将笔记收藏到你的收藏夹。

redbook collect "https://www.xiaohongshu.com/explore/abc123"

redbook uncollect <url>

从你的收藏中移除一篇笔记。

redbook uncollect "https://www.xiaohongshu.com/explore/abc123"

redbook analyze-viral <url>

分析一篇爆款笔记为何有效。返回确定性的爆款评分（0–100）。

redbook analyze-viral "https://www.xiaohongshu.com/explore/abc123" --json
redbook analyze-viral "https://www.xiaohongshu.com/explore/abc123" --comment-pages 5

选项：

• --comment-pages <n>：要获取的评论页数（默认值：3，最大值：10）

JSON 输出结构： 返回 { note, score, hook, content, visual, engagement, comments, relative, fetchedAt }。

• score.overall（0–100）——由 hook（20）+ engagement（20）+ relative（20）+ content（20）+ comments（20）综合得出
• hook.hookPatterns[] ——检测到的标题模式（身份钩子、情绪词、数字钩子、问句等）
• engagement ——点赞、评论、收藏、分享及其比率（collectToLikeRatio、commentToLikeRatio、shareToLikeRatio）
• relative.viralMultiplier ——该笔记的点赞数 / 作者的点赞数中位数
• relative.isOutlier ——当 viralMultiplier > 3 时为 true
• comments.themes[] ——评论中重复出现频率最高的关键词短语

redbook viral-template <url> [url2] [url3]

从 1–3 篇爆款笔记中提取可复用的内容模板。分析每篇笔记（使用与 analyze-viral 相同的流程），并综合得出共同的结构模式。

redbook viral-template "<url1>" "<url2>" "<url3>" --json
redbook viral-template "<url1>" --comment-pages 5 --json

选项：

• --comment-pages <n>：每篇笔记要获取的评论页数（默认值：3，最大值：10）

JSON 输出结构： 返回 { dominantHookPatterns, titleStructure, bodyStructure, engagementProfile, audienceSignals, sourceNotes, generatedAt }。

• dominantHookPatterns[] ——多数输入笔记中出现的钩子类型
• titleStructure.avgLength ——各笔记标题的平均长度
• bodyStructure.lengthRange ——正文长度范围 [最小值，最大值]
• engagementProfile.type ——“reference” / “insight” / “entertainment”
• audienceSignals.commonThemes[] ——合并各笔记评论主题后得到的共同主题

redbook comment <url>

在笔记下发布顶级评论。

redbook comment "<noteUrl>" --content "Great post!" --json

选项：

• --content <text>（必需）：评论内容

redbook reply <url>

回复笔记下的一条指定评论。

redbook reply "<noteUrl>" --comment-id "<commentId>" --content "Thanks for asking!" --json

选项：

• --comment-id <id>（必需）：要回复的评论 ID（来自 comments --json 输出）
• --content <text>（必需）：回复内容

redbook batch-reply <url>

使用筛选策略回复多条评论。请务必先使用 --dry-run 预览。

# Preview which comments match the strategy
redbook batch-reply "<noteUrl>" --strategy questions --dry-run --json

# Execute replies with a template (default 5 min delay with jitter)
redbook batch-reply "<noteUrl>" --strategy questions \
  --template "感谢提问！{content}" --max 10

选项：

• --strategy <name>：questions（默认值）、top-engaged、all-unanswered
• --template <text>：回复模板，包含 {author}、{content} 占位符
• --max <n>：最多回复数（默认值：10，硬性上限：30）
• --delay <ms>：回复间隔（毫秒）（默认值：300000 / 5 分钟，最小值：180000 / 3 分钟）。系统会自动应用 ±30% 的随机抖动。
• --dry-run：预览候选评论，不发布（未提供模板时的默认行为）

**安全性：**遇到验证码时立即停止。未提供模板时仅运行 dry-run。延迟会加入随机抖动，以避免出现可能触发 XHS 机器人检测的固定时间间隔模式。

redbook render <file>

将带有 YAML frontmatter 的 Markdown 文件渲染为带样式的 PNG 图片卡片。使用用户现有的 Chrome 安装，无需下载浏览器。

redbook render content.md --style xiaohongshu
redbook render content.md --style dark --output-dir ./cards
redbook render content.md --pagination separator --json

选项：

• --style <name>：purple、xiaohongshu（默认值）、mint、sunset、ocean、elegant、dark
• --pagination <mode>：auto（默认值）、separator（按 --- 分隔）
• --output-dir <dir>：输出目录（默认值：与输入文件相同）
• --width <n>：卡片宽度（像素）（默认值：1080）
• --height <n>：卡片高度（像素）（默认值：1440）
• --dpr <n>：设备像素比（默认值：2）

要求：puppeteer-core 和 marked（npm install -g puppeteer-core marked）。无需 XHS Cookie——完全离线渲染。

**指定 Chrome 路径：**如果 Chrome 不在标准位置，请设置 CHROME_PATH 环境变量。

redbook whoami

检查连接状态。验证 Cookie 是否有效，并显示已登录的用户。

redbook whoami

redbook auth

管理 OpenClaw、云端或 CI 运行所用的已保存 Cookie，以便在无法从浏览器提取 Cookie，或每次执行命令都要重复传入 --cookie-string 时使用。

# Export from the logged-in local browser to ~/.redbook/cookies.json
redbook auth export

# Or save a cookie string copied from Chrome DevTools
redbook auth save --cookie-string "a1=VALUE; web_session=VALUE"

# Inspect without printing secret cookie values
redbook auth path
redbook auth inspect --json

# Remove saved local reuse
redbook auth clear

常规命令按以下顺序解析 Cookie：--cookie-string、REDBOOK_COOKIE_STRING、REDBOOK_COOKIE_FILE、~/.redbook/cookies.json，然后从浏览器提取。已保存的 Cookie 文件以明文形式存储登录凭据，并使用 0600 权限写入；切勿提交这些文件，也不要将其写入日志。

redbook post（受限）

发布图片笔记。在创作者 API 上经常触发验证码（type=124）。 图片上传可用，但发布步骤不可靠。发布内容时，可以考虑改用浏览器自动化。

redbook post --title "标题" --body "正文" --images cover.png --json
redbook post --title "测试" --body "..." --images img.png --private --json

选项：

• --title <title>：笔记标题（必填）
• --body <body>：笔记正文（必填）
• --images <paths...>：图片文件路径（必填，至少一个）
• --topic <keyword>：搜索并添加话题标签
• --private：发布为私密笔记

全局选项

所有命令均支持：

• --cookie-source <browser>：chrome（默认）、safari、firefox
• --chrome-profile <name>：Chrome 配置文件目录名称（例如 “Profile 1”）。若省略则自动发现。
• --cookie-string <cookies>：手动指定 Cookie 字符串，例如 "a1=VALUE; web_session=VALUE"
• --platform <name>：强制使用 xhs（中国大陆版）或 rednote（全球版）。默认：自动检测已登录的平台，参见中国大陆版小红书与全球版 RedNote。
• --global：强制使用全球版 RedNote 后端（等同于 --platform rednote）
• --json：以 JSON 格式输出

---

中国大陆版小红书与全球版 RedNote

XHS 使用两个彼此独立、不共享会话或 Cookie 的后端：

	中国大陆版	全球版
应用 / 网站	小红书 / xiaohongshu.com	RedNote / rednote.com
API 主机	edith.xiaohongshu.com	webapi.rednote.com
Cookie 域名	.xiaohongshu.com	.rednote.com

RedNote 会根据 IP/地区 将你导向中国大陆版或全球版；同一台机器上一次只能登录其中一个，因此 CLI 会自动检测你登录的平台。通常无需传入任何标志：

redbook whoami            # auto-detects mainland vs global, then shows your account
redbook search "AI"       # runs against whichever backend you're logged into

**检测方式：**它会探测两个 Cookie 域名；如果只有一个域名有会话，就使用该域名。如果两个域名都有 Cookie（未使用的域名通常会保留过期的访客 Cookie），则会通过一次轻量的 /user/me 调用，确认哪个域名实际处于登录状态。检测结果会缓存到 ~/.redbook/platform-cache.json（以 Cookie 指纹为键），这样每次执行命令时都不必重新请求 API；登录或退出时缓存会自动失效。你会在 stderr 上看到一行灰显的 Platform: … [auto-detected|cached]。

仅在需要强制选择平台时覆盖此设置（这种情况很少见）：

redbook whoami --global            # force global RedNote (= --platform rednote)
redbook whoami --platform xhs      # force mainland
# or: export REDBOOK_PLATFORM=rednote

Web 签名（x-s/x-t）算法在两个后端上完全相同，只有主机和 Cookie 域名不同。

全球版后端的已知限制：

• user-posts / user 可能需要新鲜的个人资料 xsec_token；如果仅提供 userId 返回 code -1，请传入完整的个人资料 URL 或 --xsec-token。
• health（笔记限流等级）需要创作者后台 Cookie；请先登录 RedNote 创作者后台。

---

技术参考

xsec_token — 读取和分享笔记的必需参数

XHS API 需要有效的 xsec_token 才能获取笔记内容。没有它，read、comments 和 analyze-viral 会返回 {}。

分享链接同样需要此令牌。 任何不带 ?xsec_token=...&xsec_source=... 的 https://www.xiaohongshu.com/explore/<id> URL，都会被 XHS 的反爬层 302 重定向到 https://www.xiaohongshu.com/404/sec_*?source=xhs_sec_server&originalUrl=...。这会影响所有点击该 URL 的人，包括使用 Safari 的用户、iOS 链接预览、Agent 操作按钮等。

webUrl — 请使用此字段（自 v0.7.0 起）：

每个返回笔记的命令（feed、search、user-posts、favorites、board、read、post）现在都会包含一个 webUrl 字段，其中已嵌入令牌并设置了正确的 xsec_source。使用方应直接使用 webUrl，不要手动拼接 URL。

redbook feed --json | jq '.items[0].webUrl'
# => "https://www.xiaohongshu.com/explore/<id>?xsec_token=<t>&xsec_source=pc_feed"

xsec_source 按命令设置：pc_feed、pc_search、pc_user、pc_board、pc_share。

关键规则：

1. 令牌会过期。 使用之前会话中的 ?xsec_token=... URL 会返回 {}。切勿缓存或重复使用旧 URL。
2. search 和 feed 始终会返回新令牌。 每个条目都包含有效的 xsec_token 和预先构建好的 webUrl。
3. 仅提供 noteId 会返回 {}。 不带令牌运行 redbook read <noteId> 几乎总会失败。

正确的工作流 — 始终先搜索：

# WRONG — stale URL or bare noteId, will likely return {}
redbook read "689da7b0000000001b0372c6" --json
redbook read "https://www.xiaohongshu.com/explore/689da7b0?xsec_token=OLD_TOKEN" --json

# RIGHT — search first, then use the fresh URL with token
redbook search "AI编程" --sort popular --json
# Extract the webUrl from search results, then:
redbook read "<webUrl from search result>" --json

对于 Agent： 优先使用响应中的 webUrl。如果只有裸 noteId，请先搜索以获取新令牌，然后使用返回的 webUrl。

需要笔记 xsec_token 的命令： read、comments、analyze-viral 可能需要个人资料 xsec_token 的命令： user、user-posts 不需要 xsec_token 的命令： search、feed、whoami、topics

API 响应中的中文数字格式

XHS API 返回带有中文单位后缀的缩写数字：

API 值	实际数字
"1.5万"	15,000
"2.4万"	24,000
"1.2亿"	120,000,000
"115"	115

万 = ×10,000。亿 = ×100,000,000。小于 10,000 的数字会以字符串形式返回普通整数。

analyze-viral 命令会自动处理此格式。手动解析 --json 输出时，请留意 interact_info 字段（liked_count、collected_count 等）中的这些后缀。

错误处理

错误	含义	修复方法
{} 空响应	缺少或过期的 xsec_token	先搜索以获取新令牌
"No 'a1' cookie"	浏览器未登录 XHS	在 Chrome 中登录 xiaohongshu.com
"Session expired"	Cookie 过期	在 Chrome 中重新登录
"NeedVerify" / 验证码	触发反机器人机制	等待后重试，或降低请求频率
"IP blocked" (300012)	请求频率受限	等待或切换网络
"Request signature rejected (HTTP 406)"	XHS 更改了网页签名方式	更新 redbook（npm i -g @lucasygu/redbook@latest）；不要循环重试
"No API permission for this account" (-104)	XHS 对账号的限制（通常发生在 search），并非 Cookie 或签名问题	确认 whoami 可正常运行，然后换用其他账号或使用浏览器。不要继续重试
"looks like a 小红书号 (Red ID)"	传入的是数字 Red ID，而不是用户 ID	使用 /user/profile/<id> 中的 24 位 ID，或完整个人资料 URL

---

输出格式指南

生成分析报告时，请使用以下格式：

数据表： 使用包含精确字段映射的 Markdown 表格。始终注明指标单位。

热力图： 使用 ASCII 条形图进行跨主题比较：

             职场    生活    教育    创业
AI编程       ████ 8K  ██ 2K   ████ 12K ░░ 200
Claude Code  ██ 3K    ░░ 100  ██ 4K    █ 1K

创作者对比： 使用结构化表格，同时包含定量指标和定性风格评估。

最终报告： 按以下顺序组织各部分：

1. 市场概览（需求信号、内容产出速度）
2. 关键词概况（互动矩阵、机会等级）
3. 跨主题热力图（主题 × 场景交叉分析）
4. 受众画像（人口统计特征、意图、偏好）
5. 竞争格局（创作者画像、策略模式）
6. 内容机会（有数据支撑的分级建议）
7. 内容创意（具体钩子、角度、目标）

程序化 API

import { XhsClient } from "@lucasygu/redbook";
import { loadCookies } from "@lucasygu/redbook/cookies";

const cookies = await loadCookies("chrome");
const client = new XhsClient(cookies);

const results = await client.searchNotes("AI编程", 1, 20, "popular");
const topics = await client.searchTopics("Claude Code");

要求

• Node.js >= 22
• 已在 Chrome 中登录 xiaohongshu.com（也可使用 Safari/Firefox，并传入 --cookie-source）
• macOS（Cookie 提取使用原生钥匙串访问）
• 仅用于卡片渲染： puppeteer-core 和 marked（npm install -g puppeteer-core marked）。使用现有的 Chrome，无需额外下载浏览器。