@lucasygu/redbook 0.2.0 → 0.3.1

package/README.md

@@ -6,9 +6,11 @@
 
 > ### 最快上手方式
 >
-> 把这段话发给你的 AI 助手（Claude Code、Cursor、Codex、Windsurf 等）：
+> 把这段话发给你的 AI 助手（Claude Code、Cursor、Codex、Windsurf、OpenClaw 等）：
 >
-> **"帮我安装 `@lucasygu/redbook` 这个小红书 CLI 工具，然后运行 `redbook whoami` 验证是否能正常连接。GitHub 地址：https://github.com/lucasygu/redbook"**
+> **"帮我用 npm 安装 `@lucasygu/redbook` 这个小红书 CLI 工具，然后运行 `redbook whoami` 验证是否能正常连接。GitHub 地址：https://github.com/lucasygu/redbook"**
+>
+> OpenClaw 用户也可以直接：**`clawhub install redbook`**
 >
 > AI 会自动完成安装、验证连接、处理可能的 Cookie 问题。你只需要确保已在 Chrome 中登录 xiaohongshu.com。
 >
@@ -18,6 +20,8 @@
 
 ```bash
 npm install -g @lucasygu/redbook
+# 或通过 ClawHub（OpenClaw 生态）
+clawhub install redbook
 ```
 
 需要 Node.js >= 22。使用 Chrome 浏览器的 Cookie —— 请先在 Chrome 中登录 xiaohongshu.com。
@@ -29,6 +33,9 @@ npm install -g @lucasygu/redbook
 - **话题研究** —— 搜索关键词，分析哪些话题有流量、哪些是蓝海
 - **竞品分析** —— 找到头部博主，对比粉丝量、互动数据、内容风格
 - **爆款拆解** —— 分析爆款笔记的标题钩子、互动比例、评论主题
+- **爆款模板** —— 从多篇爆款笔记提取内容模板（标题结构、正文结构、钩子模式）
+- **评论管理** —— 发评论、回复评论、按策略批量回复（问题优先 / 高赞优先 / 未回复优先）
+- **图文卡片** —— Markdown 渲染为小红书风格的 PNG 图文卡片（7 种配色主题）
 - **内容策划** —— 基于数据发现内容机会，生成有数据支撑的选题建议
 - **受众洞察** —— 从互动信号推断目标用户画像
 
@@ -62,6 +69,23 @@ redbook topics "Claude Code"
 # 分析爆款笔记
 redbook analyze-viral https://www.xiaohongshu.com/explore/abc123
 
+# 从多篇爆款提取内容模板
+redbook viral-template "<url1>" "<url2>" "<url3>" --json
+
+# 发评论
+redbook comment "<noteUrl>" --content "写得好！"
+
+# 回复评论
+redbook reply "<noteUrl>" --comment-id "<id>" --content "感谢提问！"
+
+# 按策略批量回复（先预览再执行）
+redbook batch-reply "<noteUrl>" --strategy questions --dry-run
+redbook batch-reply "<noteUrl>" --strategy questions --template "感谢！{content}" --max 10
+
+# 将 Markdown 渲染为图文卡片（需要可选依赖）
+redbook render content.md --style xiaohongshu
+redbook render content.md --style dark --output-dir ./cards
+
 # 发布图文笔记
 redbook post --title "标题" --body "正文内容" --images cover.png
 redbook post --title "测试" --body "..." --images img.png --private
@@ -81,6 +105,11 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `post` | 发布图文笔记（易触发验证码，详见下方说明） |
 | `topics <关键词>` | 搜索话题/标签 |
 | `analyze-viral <url>` | 分析爆款笔记（钩子、互动、结构） |
+| `viral-template <url...>` | 从 1-3 篇爆款笔记提取内容模板 |
+| `comment <url>` | 发表评论 |
+| `reply <url>` | 回复指定评论 |
+| `batch-reply <url>` | 按策略批量回复评论（支持预览模式） |
+| `render <文件>` | Markdown 渲染为小红书图文卡片 PNG（需可选依赖） |
 
 ### 通用选项
 
@@ -98,12 +127,42 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `--type <类型>` | `all`（全部）、`video`（视频）、`image`（图文） | `all` |
 | `--page <页码>` | 页码 | `1` |
 
-### 分析选项（analyze-viral）
+### 分析选项（analyze-viral / viral-template）
 
 | 选项 | 说明 | 默认值 |
 |------|------|--------|
 | `--comment-pages <n>` | 获取评论页数 | `3` |
 
+### 批量回复选项（batch-reply）
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--strategy <策略>` | `questions`（提问）、`top-engaged`（高赞）、`all-unanswered`（未回复） | `questions` |
+| `--template <模板>` | 回复模板，支持 `{author}`, `{content}` 占位符 | 无（预览模式） |
+| `--max <数量>` | 最大回复数（上限 30） | `10` |
+| `--delay <毫秒>` | 回复间隔（最小 180000ms/3分钟），自动添加 ±30% 随机抖动 | `300000`（5分钟） |
+| `--dry-run` | 只预览不发送 | 无模板时自动开启 |
+
+> ⚠️ **风控安全：** 小红书检测均匀时间间隔的自动化行为。回复间隔已自动添加 ±30% 随机抖动，避免触发机器人检测。建议每天每篇笔记最多批量回复 1-2 次。
+
+### 渲染选项（render）
+
+将 Markdown 文件渲染为小红书风格的 PNG 图文卡片。使用本机 Chrome 渲染，无需额外下载浏览器。
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--style <名称>` | 配色：purple, xiaohongshu, mint, sunset, ocean, elegant, dark | `xiaohongshu` |
+| `--pagination <模式>` | 分页：auto（自动拆分）、separator（按 `---` 拆分） | `auto` |
+| `--output-dir <目录>` | 输出目录 | 与输入文件同目录 |
+| `--width <像素>` | 卡片宽度 | `1080` |
+| `--height <像素>` | 卡片高度 | `1440` |
+| `--dpr <倍率>` | 设备像素比 | `2` |
+
+**可选依赖：** 需要安装 `puppeteer-core` 和 `marked`：
+```bash
+npm install -g puppeteer-core marked
+```
+
 ### 发布选项（post）
 
 发布功能目前**容易触发验证码**（type=124）。图片上传正常，但发布步骤经常被拦截。如需发布笔记，建议使用浏览器自动化。
@@ -133,7 +192,30 @@ redbook post --title "测试" --body "..." --images img.png --private
 - **主 API**（`edith.xiaohongshu.com`）—— 读取：搜索、推荐页、笔记、评论、用户资料。使用 144 字节 x-s 签名（v4.3.1）
 - **创作者 API**（`creator.xiaohongshu.com`）—— 写入：上传图片、发布笔记。使用 AES-128-CBC 签名
 
-## Claude Code 集成
+## 分析模块（A-L）
+
+内置 12 个可组合的分析模块，覆盖从关键词研究到内容发布的完整工作流：
+
+| 模块 | 功能 |
+|------|------|
+| A. 关键词矩阵 | 分析各关键词的互动天花板和竞争密度 |
+| B. 跨话题热力图 | 发现话题 × 场景的内容空白 |
+| C. 互动信号分析 | 分类内容类型（工具型 / 认知型 / 娱乐型） |
+| D. 博主画像 | 对比头部博主的粉丝、互动、风格 |
+| E. 内容形式分析 | 图文 vs. 视频的表现对比 |
+| F. 机会评分 | 按性价比排序关键词 |
+| G. 受众推断 | 从互动信号推断用户画像 |
+| H. 选题策划 | 数据驱动的内容创意 |
+| I. 评论运营 | 按策略筛选和批量回复评论 |
+| J. 爆款复刻 | 从爆款笔记提取内容模板 |
+| K. 互动自动化 | 组合 I + J 的自动化运营工作流 |
+| L. 图文卡片 | Markdown → 小红书风格 PNG 图文卡片（7 种配色） |
+
+详见 [SKILL.md](SKILL.md) 的模块文档和组合工作流。
+
+## AI 助手集成
+
+### Claude Code
 
 安装后自动注册为 Claude Code 技能。在 Claude Code 中使用 `/redbook` 命令：
 
@@ -144,14 +226,25 @@ redbook post --title "测试" --body "..." --images img.png --private
 /redbook analyze-viral <url>                    # 分析爆款笔记
 ```
 
-技能内置了小红书平台专属的分析模块 —— 关键词矩阵、跨话题热力图、互动信号分类、博主画像、内容机会评分等。你可以直接用自然语言下达复杂任务：
+你可以直接用自然语言下达复杂任务：
 
 - *"分析'AI编程'在小红书的竞争格局，找出蓝海关键词"*
 - *"对比这三个博主的内容策略和互动数据"*
 - *"拆解这篇爆款笔记，告诉我为什么火了"*
+- *"帮我回复这篇笔记下面的提问评论"*
 
 Claude 会自动组合多个命令，解析 JSON 数据，输出结构化分析报告。
 
+### OpenClaw / ClawHub
+
+官方支持 [OpenClaw](https://openclaw.ai) 和 [ClawHub](https://docs.openclaw.ai/tools/clawhub) 生态。通过 ClawHub 安装：
+
+```bash
+clawhub install redbook
+```
+
+安装后在 OpenClaw 中可直接使用所有 `redbook` 命令。SKILL.md 同时兼容 Claude Code 和 OpenClaw 两个生态。
+
 ## 编程接口
 
 ```typescript
@@ -189,9 +282,11 @@ A fast CLI tool for [Xiaohongshu (小红书 / RED)](https://www.xiaohongshu.com)
 
 > ### Easiest way to get started
 >
-> Paste this to your AI coding agent (Claude Code, Cursor, Codex, Windsurf, etc.):
+> Paste this to your AI coding agent (Claude Code, Cursor, Codex, Windsurf, OpenClaw, etc.):
 >
-> **"Install the `@lucasygu/redbook` Xiaohongshu CLI tool and run `redbook whoami` to verify it works. Repo: https://github.com/lucasygu/redbook"**
+> **"Install the `@lucasygu/redbook` Xiaohongshu CLI tool via npm and run `redbook whoami` to verify it works. Repo: https://github.com/lucasygu/redbook"**
+>
+> OpenClaw users can also run: **`clawhub install redbook`**
 >
 > The agent will handle installation, verify the connection, and troubleshoot any cookie issues. Just make sure you're logged into xiaohongshu.com in Chrome first.
 >
@@ -201,6 +296,8 @@ A fast CLI tool for [Xiaohongshu (小红书 / RED)](https://www.xiaohongshu.com)
 
 ```bash
 npm install -g @lucasygu/redbook
+# Or via ClawHub (OpenClaw ecosystem)
+clawhub install redbook
 ```
 
 Requires Node.js >= 22. Uses cookies from your Chrome browser session — you must be logged into xiaohongshu.com in Chrome.
@@ -212,6 +309,9 @@ After installing, run `redbook whoami` to verify the connection. If macOS shows
 - **Topic research** — Search keywords, analyze which topics have demand vs. gaps
 - **Competitive analysis** — Find top creators, compare followers, engagement, content style
 - **Viral note breakdown** — Analyze title hooks, engagement ratios, comment themes
+- **Viral templates** — Extract content templates from multiple viral notes (hook patterns, body structure, engagement profile)
+- **Comment management** — Post comments, reply to comments, batch-reply with strategies (questions / top-engaged / unanswered)
+- **Image cards** — Render markdown to styled PNG cards for XHS posts (7 color themes)
 - **Content planning** — Discover content opportunities with data-backed topic suggestions
 - **Audience insights** — Infer target audience from engagement signals
 
@@ -245,6 +345,23 @@ redbook topics "Claude Code"
 # Analyze a viral note
 redbook analyze-viral https://www.xiaohongshu.com/explore/abc123
 
+# Extract content template from viral notes
+redbook viral-template "<url1>" "<url2>" "<url3>" --json
+
+# Post a comment
+redbook comment "<noteUrl>" --content "Great post!"
+
+# Reply to a comment
+redbook reply "<noteUrl>" --comment-id "<id>" --content "Thanks for asking!"
+
+# Batch reply with strategy (preview first, then execute)
+redbook batch-reply "<noteUrl>" --strategy questions --dry-run
+redbook batch-reply "<noteUrl>" --strategy questions --template "Thanks! {content}" --max 10
+
+# Render markdown to image cards (requires optional deps)
+redbook render content.md --style xiaohongshu
+redbook render content.md --style dark --output-dir ./cards
+
 # Publish (requires image)
 redbook post --title "标题" --body "正文" --images cover.png
 redbook post --title "测试" --body "..." --images img.png --private
@@ -264,6 +381,11 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `post` | Publish an image note (captcha-prone, see below) |
 | `topics <keyword>` | Search for topics/hashtags |
 | `analyze-viral <url>` | Analyze why a viral note works (hooks, engagement, structure) |
+| `viral-template <url...>` | Extract a content template from 1-3 viral notes |
+| `comment <url>` | Post a top-level comment |
+| `reply <url>` | Reply to a specific comment |
+| `batch-reply <url>` | Batch reply to comments with filtering strategy (supports dry-run) |
+| `render <file>` | Render markdown to styled PNG image cards for XHS posts (optional deps) |
 
 ### Global Options
 
@@ -281,12 +403,42 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `--type <type>` | `all`, `video`, `image` | `all` |
 | `--page <n>` | Page number | `1` |
 
-### Analyze-Viral Options
+### Analyze-Viral / Viral-Template Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--comment-pages <n>` | Number of comment pages to fetch | `3` |
 
+### Batch-Reply Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--strategy <name>` | `questions`, `top-engaged`, `all-unanswered` | `questions` |
+| `--template <text>` | Reply template with `{author}`, `{content}` placeholders | none (dry-run) |
+| `--max <n>` | Max replies to send (hard cap: 30) | `10` |
+| `--delay <ms>` | Delay between replies in ms (min: 180000 / 3 min), ±30% random jitter applied automatically | `300000` (5 min) |
+| `--dry-run` | Preview candidates without posting | auto when no template |
+
+> ⚠️ **Rate limit safety:** XHS detects uniform timing patterns as bot behavior. Reply delays include ±30% random jitter automatically. Limit to 1-2 batch runs per note per day. See SKILL.md for full rate limit guidance.
+
+### Render Options
+
+Render a markdown file to styled PNG image cards. Uses your existing Chrome for rendering — no browser download needed.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--style <name>` | Color style: purple, xiaohongshu, mint, sunset, ocean, elegant, dark | `xiaohongshu` |
+| `--pagination <mode>` | Pagination: auto, separator | `auto` |
+| `--output-dir <dir>` | Output directory | same as input |
+| `--width <n>` | Card width in pixels | `1080` |
+| `--height <n>` | Card height in pixels | `1440` |
+| `--dpr <n>` | Device pixel ratio | `2` |
+
+**Optional dependencies:** Requires `puppeteer-core` and `marked`:
+```bash
+npm install -g puppeteer-core marked
+```
+
 ### Post Options
 
 Publishing **frequently triggers captcha** (type=124). Image upload works, but the publish step is unreliable. For posting, consider using browser automation instead.
@@ -316,7 +468,30 @@ Publishing **frequently triggers captcha** (type=124). Image upload works, but t
 - **Main API** (`edith.xiaohongshu.com`) — for reading: search, feed, notes, comments, user profiles. Uses x-s signature with 144-byte payload (v4.3.1).
 - **Creator API** (`creator.xiaohongshu.com`) — for writing: upload images, publish notes. Uses simpler AES-128-CBC signing.
 
-## Claude Code Integration
+## Analysis Modules (A-L)
+
+12 composable analysis modules covering the full workflow from keyword research to content publishing:
+
+| Module | Purpose |
+|--------|---------|
+| A. Keyword Matrix | Analyze engagement ceiling and competition density per keyword |
+| B. Cross-Topic Heatmap | Find topic × scene content gaps |
+| C. Engagement Signals | Classify content type (reference / insight / entertainment) |
+| D. Creator Profiling | Compare top creators' followers, engagement, style |
+| E. Content Form | Image-text vs. video performance comparison |
+| F. Opportunity Scoring | Rank keywords by effort-to-reward ratio |
+| G. Audience Inference | Infer user persona from engagement signals |
+| H. Content Brainstorm | Data-backed content ideas |
+| I. Comment Operations | Filter and batch-reply to comments by strategy |
+| J. Viral Replication | Extract content templates from viral notes |
+| K. Engagement Automation | Combined I + J workflow for operations |
+| L. Card Rendering | Markdown → styled PNG image cards for XHS posts (7 color themes) |
+
+See [SKILL.md](SKILL.md) for full module documentation and composed workflows.
+
+## AI Agent Integration
+
+### Claude Code
 
 Installs automatically as a Claude Code skill. Use `/redbook` in Claude Code:
 
@@ -327,14 +502,25 @@ Installs automatically as a Claude Code skill. Use `/redbook` in Claude Code:
 /redbook analyze-viral <url>                    # Analyze a viral note
 ```
 
-The skill includes XHS-native analysis modules — keyword engagement matrix, cross-topic heatmaps, engagement signal classification, creator profiling, opportunity scoring, and more. You can give natural language instructions for complex tasks:
+You can give natural language instructions for complex tasks:
 
 - *"Analyze the competitive landscape for 'AI编程' on Xiaohongshu and find blue ocean keywords"*
 - *"Compare the content strategies of these three creators"*
 - *"Break down this viral note and tell me why it worked"*
+- *"Reply to the question comments on my latest post"*
 
 Claude will automatically combine multiple commands, parse JSON data, and produce structured analysis reports.
 
+### OpenClaw / ClawHub
+
+Officially supports [OpenClaw](https://openclaw.ai) and [ClawHub](https://docs.openclaw.ai/tools/clawhub). Install via ClawHub:
+
+```bash
+clawhub install redbook
+```
+
+All `redbook` commands are available in OpenClaw after installation. The SKILL.md is compatible with both Claude Code and OpenClaw ecosystems.
+
 ## Programmatic Usage
 
 ```typescript

package/SKILL.md

@@ -53,6 +53,7 @@ Use the `redbook` CLI to search notes, read content, analyze creators, automate
 | Post a comment | `redbook comment <url> --content "text"` |
 | Reply to comment | `redbook reply <url> --comment-id <id> --content "text"` |
 | Batch reply (preview) | `redbook batch-reply <url> --strategy questions --dry-run` |
+| Render markdown to cards | `redbook render content.md --style xiaohongshu` |
 | Check connection | `redbook whoami` |
 
 **Always add `--json`** when parsing output programmatically. Without it, output is human-formatted text.
@@ -340,10 +341,10 @@ 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
+# 3. Execute replies with template (5 min delay with ±30% jitter)
 redbook batch-reply "<noteUrl>" --strategy questions \
   --template "感谢提问！关于{content}，..." \
-  --max 10 --delay 3000
+  --max 10
 ```
 
 **Fields to extract from `--dry-run` JSON:**
@@ -364,7 +365,7 @@ redbook batch-reply "<noteUrl>" --strategy questions \
 - High top-engaged comments (>100 likes) = reply to visible comments for maximum reach
 - Many unanswered comments = engagement gap, opportunity to increase reply rate
 
-**Safety:** Hard cap 50 replies per batch, minimum 2s delay, `--dry-run` by default (no template = preview only), immediate stop on captcha.
+**Safety:** Hard cap 30 replies per batch, minimum 3-minute delay with ±30% jitter (default 5 min), `--dry-run` by default (no template = preview only), immediate stop on captcha. See [Rate Limits & Safety](#rate-limits--safety) for details.
 
 **Output:** Reply plan table with candidate comments, strategy match reason, and status.
 
@@ -422,15 +423,75 @@ This module is a workflow that composes Modules I and J with human oversight.
 
 **Safety rules:**
 - Always `--dry-run` first, human approval before execution
-- Maximum 50 replies per session
-- Minimum 2-second delay between replies
+- Maximum 30 replies per session (hard cap)
+- Minimum 3-minute delay between replies, default 5 minutes, with ±30% random jitter
 - Never reply to the same comment twice (check `hasSubReplies`)
 - Stop immediately on captcha — do not retry
+- See [Rate Limits & Safety](#rate-limits--safety) for XHS risk control thresholds
 
 **Anti-spam guidelines:**
 - Vary reply templates across batches
 - Limit to 1-2 batch runs per note per day
 - Prioritize quality (targeted strategy) over quantity
+- Uniform timing patterns trigger bot detection — jitter is applied automatically
+
+---
+
+### Module L: Card Rendering
+
+**Answers:** How do I turn markdown content into Xiaohongshu-ready image cards?
+
+**Commands:**
+```bash
+# 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
+```
+
+**Input:** Markdown file with YAML frontmatter:
+```markdown
+---
+emoji: "🚀"
+title: "5个AI效率技巧"
+subtitle: "Claude Code 实战"
+---
+
+## 技巧一：...
+Content here...
+
+---
+
+## 技巧二：...
+More content...
+```
+
+**Output:** `cover.png` + `card_1.png`, `card_2.png`, ... in the same directory.
+
+**Card specs:**
+- **Size:** 1080×1440 (3:4 ratio, standard XHS image)
+- **DPR:** 2 (retina quality, actual output 2160×2880)
+- **Styles:** purple, xiaohongshu, mint, sunset, ocean, elegant, dark
+
+**Pagination modes:**
+- `auto` (default) — smart split on heading/paragraph boundaries using character-count heuristic
+- `separator` — manual split on `---` in markdown
+
+**How to interpret:**
+- Uses the user's existing Chrome for rendering (via `puppeteer-core`) — no browser download needed
+- Purely offline — no XHS API or cookies required
+- Output images are ready for `redbook post --images cover.png card_1.png ...`
+
+**Dependencies:** Requires `puppeteer-core` and `marked` (optional, install with `npm install -g puppeteer-core marked`).
+
+**Composition with other modules:**
+- Pairs with Module H (Content Brainstorm) — generate content ideas, write markdown, render to cards
+- Pairs with Module J (Viral Replication) — extract template, write content matching the template, render
+- Output feeds into `redbook post --images` for publishing
 
 ---
 
@@ -480,9 +541,14 @@ redbook viral-template "<url1>" "<url2>" "<url3>" --json
 Single-module workflow for managing comment engagement on your notes. Use `batch-reply --dry-run` to audit, then execute with a template.
 
 ### Content Replication
-**Modules:** A → J → H
+**Modules:** A → J → H → L
+
+Keyword research → viral template extraction → data-backed content brainstorm → render to image cards. The template provides structural constraints that guide Module H's content ideas. Module L renders the final markdown to XHS-ready PNGs.
+
+### Content Creation End-to-End
+**Modules:** A → J → H → L → `post`
 
-Keyword research → viral template extraction → data-backed content brainstorm. The template provides structural constraints that guide Module H's content ideas.
+The full pipeline: research keywords → extract viral template → brainstorm content → write markdown → render to styled image cards → publish via `redbook post --images cover.png card_1.png ...`
 
 ### Full Operations
 **Modules:** A → C → I → J → K
@@ -491,6 +557,44 @@ Comprehensive automation playbook — keyword analysis, engagement classificatio
 
 ---
 
+## Rate Limits & Safety
+
+XHS enforces aggressive anti-spam (风控) that detects automated behavior through device fingerprinting, activity ratio monitoring, and timing pattern analysis. The CLI applies safe defaults based on platform research.
+
+### Safe Thresholds
+
+| Action | Safe Interval | CLI Default | Hard Cap |
+|--------|--------------|-------------|----------|
+| Post a note | 3-4 hours (2-3 notes/day max) | N/A (manual) | — |
+| Comment | ≥3 minutes | N/A (manual) | — |
+| Reply | ≥3 minutes | N/A (manual) | — |
+| Batch reply delay | ≥3 minutes | 5 min ±30% jitter | — |
+| Batch reply count | — | 10 | 30 |
+
+### Anti-Detection Measures
+
+- **Timing jitter:** ±30% random variation on all batch delays. Uniform intervals are a bot signature.
+- **Hard caps:** Maximum 30 replies per batch (down from 50). No override.
+- **Rate limit warnings:** `post`, `comment`, and `reply` commands display safe interval reminders after each action.
+- **Captcha circuit breaker:** Batch operations stop immediately on captcha (NeedVerify).
+
+### What Triggers Risk Control
+
+- **Uniform timing** — replying at exact 3-second intervals flags bot detection
+- **High frequency** — >50 interactions/minute across any action type
+- **Activity ratio anomaly** — more comments than post views signals inauthentic behavior
+- **Device fingerprint mismatch** — XHS fingerprints 21 hardware parameters
+
+### Best Practices for Agents
+
+1. Always `--dry-run` first, review candidates, then execute
+2. Use the default 5-minute delay — do not override `--delay` below 180000 (3 min)
+3. Limit batch runs to 1-2 per note per day
+4. Vary reply templates between batches
+5. Space `post` commands 3-4 hours apart (2-3 notes/day maximum)
+
+---
+
 ## API vs Browser Limitations
 
 The following operations work reliably via API:
@@ -655,19 +759,41 @@ Reply to multiple comments using a filtering strategy. Always preview with `--dr
 # Preview which comments match the strategy
 redbook batch-reply "<noteUrl>" --strategy questions --dry-run --json
 
-# Execute replies with a template
+# Execute replies with a template (default 5 min delay with jitter)
 redbook batch-reply "<noteUrl>" --strategy questions \
-  --template "感谢提问！{content}" --max 10 --delay 3000
+  --template "感谢提问！{content}" --max 10
 ```
 
 **Options:**
 - `--strategy <name>`: `questions` (default), `top-engaged`, `all-unanswered`
 - `--template <text>`: Reply template with `{author}`, `{content}` placeholders
-- `--max <n>`: Max replies (default: 10, hard cap: 50)
-- `--delay <ms>`: Delay between replies in ms (default: 3000, min: 2000)
+- `--max <n>`: Max replies (default: 10, hard cap: 30)
+- `--delay <ms>`: Delay between replies in ms (default: 300000 / 5 min, min: 180000 / 3 min). ±30% random jitter applied automatically.
 - `--dry-run`: Preview candidates without posting (default when no template)
 
-**Safety:** Stops immediately on captcha. No template = dry-run only.
+**Safety:** Stops immediately on captcha. No template = dry-run only. Delays include random jitter to avoid uniform timing patterns that trigger XHS bot detection.
+
+### `redbook render <file>`
+
+Render a markdown file with YAML frontmatter into styled PNG image cards. Uses the user's existing Chrome installation — no browser download needed.
+
+```bash
+redbook render content.md --style xiaohongshu
+redbook render content.md --style dark --output-dir ./cards
+redbook render content.md --pagination separator --json
+```
+
+**Options:**
+- `--style <name>`: `purple`, `xiaohongshu` (default), `mint`, `sunset`, `ocean`, `elegant`, `dark`
+- `--pagination <mode>`: `auto` (default), `separator` (split on `---`)
+- `--output-dir <dir>`: Output directory (default: same as input file)
+- `--width <n>`: Card width in px (default: 1080)
+- `--height <n>`: Card height in px (default: 1440)
+- `--dpr <n>`: Device pixel ratio (default: 2)
+
+**Requires:** `puppeteer-core` and `marked` (`npm install -g puppeteer-core marked`). Does NOT require XHS cookies — purely offline rendering.
+
+**Override Chrome path:** Set `CHROME_PATH` environment variable if Chrome is not in the standard location.
 
 ### `redbook whoami`
 
@@ -808,3 +934,4 @@ const topics = await client.searchTopics("Claude Code");
 - Node.js >= 22
 - Logged into xiaohongshu.com in Chrome (or Safari/Firefox with `--cookie-source`)
 - macOS (cookie extraction uses native keychain access)
+- **For card rendering only:** `puppeteer-core` and `marked` (`npm install -g puppeteer-core marked`). Uses your existing Chrome — no additional browser download.

package/dist/cli.js

@@ -21,7 +21,7 @@ import { dirname, join } from "node:path";
 import { extractCookies } from "./lib/cookies.js";
 import { XhsClient, XhsApiError } from "./lib/client.js";
 import { analyzeViral, formatViralAnalysis } from "./lib/analyze.js";
-import { selectCandidates, executeReplies, } from "./lib/reply-strategy.js";
+import { selectCandidates, executeReplies, DEFAULT_DELAY_MS, MIN_DELAY_MS as MIN_REPLY_DELAY, MAX_REPLIES_HARD_CAP, } from "./lib/reply-strategy.js";
 import { extractTemplate, formatTemplate } from "./lib/template.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -330,6 +330,7 @@ postCmd.action(async (opts) => {
             if (r.note_id) {
                 console.log(`  URL: https://www.xiaohongshu.com/explore/${r.note_id}`);
             }
+            console.error(kleur.yellow("⚠ Rate limit: wait ≥3-4 hours before the next post (2-3 notes/day max)."));
         }
     }
     catch (err) {
@@ -591,6 +592,7 @@ commentCmd.action(async (url, opts) => {
         }
         else {
             console.log(kleur.green("Comment posted!"));
+            console.error(kleur.yellow("⚠ Rate limit: wait ≥3 minutes before the next comment to avoid risk control."));
         }
     }
     catch (err) {
@@ -615,6 +617,7 @@ replyCmd.action(async (url, opts) => {
         }
         else {
             console.log(kleur.green("Reply posted!"));
+            console.error(kleur.yellow("⚠ Rate limit: wait ≥3 minutes before the next reply to avoid risk control."));
         }
     }
     catch (err) {
@@ -627,8 +630,8 @@ const batchReplyCmd = program
     .description("Reply to multiple comments using a strategy")
     .option("--strategy <name>", "Filter strategy: questions, top-engaged, all-unanswered", "questions")
     .option("--template <text>", "Reply template with {author}, {content} placeholders")
-    .option("--max <n>", "Max replies to send (hard cap: 50)", "10")
-    .option("--delay <ms>", "Delay between replies in ms (min: 2000)", "3000")
+    .option("--max <n>", `Max replies to send (hard cap: ${MAX_REPLIES_HARD_CAP})`, "10")
+    .option("--delay <ms>", `Delay between replies in ms (min: ${MIN_REPLY_DELAY / 1000}s)`, String(DEFAULT_DELAY_MS))
     .option("--dry-run", "Preview candidates without posting");
 addCookieOption(batchReplyCmd);
 addJsonOption(batchReplyCmd);
@@ -637,7 +640,7 @@ batchReplyCmd.action(async (url, opts) => {
         const client = await getClient(opts.cookieSource, opts.chromeProfile);
         const { noteId, xsecToken } = parseNoteUrl(url);
         const strategy = opts.strategy;
-        const max = Math.min(parseInt(opts.max) || 10, 50);
+        const max = Math.min(parseInt(opts.max) || 10, MAX_REPLIES_HARD_CAP);
         const isDryRun = opts.dryRun || !opts.template;
         // Fetch all comments
         console.error(kleur.dim("Fetching comments..."));
@@ -675,8 +678,10 @@ batchReplyCmd.action(async (url, opts) => {
             return;
         }
         // Execute replies
-        console.error(kleur.dim(`Sending ${plan.candidates.length} replies (delay: ${opts.delay}ms)...`));
-        const results = await executeReplies(client, noteId, plan.candidates, opts.template, parseInt(opts.delay) || 3000, {});
+        const delayMs = parseInt(opts.delay) || DEFAULT_DELAY_MS;
+        console.error(kleur.dim(`Sending ${plan.candidates.length} replies (delay: ~${Math.round(delayMs / 60000)}min ±30% jitter)...`));
+        console.error(kleur.yellow("⚠ Rate limit: XHS enforces anti-spam — replies spaced ≥3min apart with jitter."));
+        const results = await executeReplies(client, noteId, plan.candidates, opts.template, delayMs, {});
         const succeeded = results.filter((r) => r.success).length;
         const failed = results.filter((r) => !r.success).length;
         if (opts.json) {
@@ -696,6 +701,43 @@ batchReplyCmd.action(async (url, opts) => {
         handleError(err);
     }
 });
+// ─── render ──────────────────────────────────────────────────────────────────
+const renderCmd = program
+    .command("render <file>")
+    .description("Render markdown to styled PNG cards for Xiaohongshu posts")
+    .option("--style <name>", "Color style: purple, xiaohongshu, mint, sunset, ocean, elegant, dark", "xiaohongshu")
+    .option("--pagination <mode>", "Pagination: auto, separator", "auto")
+    .option("--output-dir <dir>", "Output directory (default: same as input file)")
+    .option("--width <n>", "Card width in px", "1080")
+    .option("--height <n>", "Card height in px", "1440")
+    .option("--dpr <n>", "Device pixel ratio", "2");
+addJsonOption(renderCmd);
+renderCmd.action(async (file, opts) => {
+    try {
+        const { renderCards } = await import("./lib/render.js");
+        const result = await renderCards(file, {
+            style: opts.style,
+            pagination: opts.pagination,
+            outputDir: opts.outputDir,
+            width: parseInt(opts.width),
+            height: parseInt(opts.height),
+            dpr: parseInt(opts.dpr),
+        });
+        if (opts.json) {
+            output(result, true);
+        }
+        else {
+            console.log(kleur.green(`\nRendered ${result.totalCards + 1} images:`));
+            console.log(`  Cover: ${kleur.bold(result.coverPath)}`);
+            for (const p of result.cardPaths) {
+                console.log(`  Card:  ${kleur.bold(p)}`);
+            }
+        }
+    }
+    catch (err) {
+        handleError(err);
+    }
+});
 // ─── Helpers ────────────────────────────────────────────────────────────────
 function parseNoteUrl(url) {
     // Handle full URLs like https://www.xiaohongshu.com/explore/abc123?xsec_token=xxx