@lucasygu/redbook 0.1.14 → 0.2.0

package/README.md

@@ -11,6 +11,8 @@
 > **"帮我安装 `@lucasygu/redbook` 这个小红书 CLI 工具，然后运行 `redbook whoami` 验证是否能正常连接。GitHub 地址：https://github.com/lucasygu/redbook"**
 >
 > AI 会自动完成安装、验证连接、处理可能的 Cookie 问题。你只需要确保已在 Chrome 中登录 xiaohongshu.com。
+>
+> 安装完成后，试试：**"帮我分析'AI编程'这个话题在小红书上的竞争格局"** —— AI 会自动搜索关键词、分析互动数据、发现头部博主、给出内容建议。
 
 ## 安装
 
@@ -22,6 +24,16 @@ npm install -g @lucasygu/redbook
 
 安装后运行 `redbook whoami` 验证连接。如果遇到 macOS 钥匙串弹窗，请点击"始终允许"。CLI 会自动检测所有 Chrome 配置文件，找到你的小红书登录状态。
 
+## 能做什么
+
+- **话题研究** —— 搜索关键词，分析哪些话题有流量、哪些是蓝海
+- **竞品分析** —— 找到头部博主，对比粉丝量、互动数据、内容风格
+- **爆款拆解** —— 分析爆款笔记的标题钩子、互动比例、评论主题
+- **内容策划** —— 基于数据发现内容机会，生成有数据支撑的选题建议
+- **受众洞察** —— 从互动信号推断目标用户画像
+
+通过 AI 助手使用时，这些工作流可以自动串联完成。直接使用 CLI 时，每个命令也可以独立运行。
+
 ## 快速开始
 
 ```bash
@@ -66,7 +78,7 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `user <userId>` | 查看用户资料 |
 | `user-posts <userId>` | 列出用户所有笔记 |
 | `feed` | 获取推荐页内容 |
-| `post` | 发布图文笔记 |
+| `post` | 发布图文笔记（易触发验证码，详见下方说明） |
 | `topics <关键词>` | 搜索话题/标签 |
 | `analyze-viral <url>` | 分析爆款笔记（钩子、互动、结构） |
 
@@ -86,7 +98,15 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `--type <类型>` | `all`（全部）、`video`（视频）、`image`（图文） | `all` |
 | `--page <页码>` | 页码 | `1` |
 
-### 发布选项
+### 分析选项（analyze-viral）
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--comment-pages <n>` | 获取评论页数 | `3` |
+
+### 发布选项（post）
+
+发布功能目前**容易触发验证码**（type=124）。图片上传正常，但发布步骤经常被拦截。如需发布笔记，建议使用浏览器自动化。
 
 | 选项 | 说明 |
 |------|------|
@@ -118,13 +138,19 @@ redbook post --title "测试" --body "..." --images img.png --private
 安装后自动注册为 Claude Code 技能。在 Claude Code 中使用 `/redbook` 命令：
 
 ```
-/redbook search "AI编程"              # 搜索笔记
-/redbook read <url>                   # 阅读笔记
-/redbook user <userId>                # 查看博主
-/redbook analyze <userId>             # 完整博主分析
+/redbook search "AI编程"                        # 搜索笔记
+/redbook read <url>                             # 阅读笔记
+/redbook user <userId>                          # 查看博主
+/redbook analyze-viral <url>                    # 分析爆款笔记
 ```
 
-Claude 会自动调用 CLI 命令，解析结果，完成竞品分析、话题研究等复杂任务。
+技能内置了小红书平台专属的分析模块 —— 关键词矩阵、跨话题热力图、互动信号分类、博主画像、内容机会评分等。你可以直接用自然语言下达复杂任务：
+
+- *"分析'AI编程'在小红书的竞争格局，找出蓝海关键词"*
+- *"对比这三个博主的内容策略和互动数据"*
+- *"拆解这篇爆款笔记，告诉我为什么火了"*
+
+Claude 会自动组合多个命令，解析 JSON 数据，输出结构化分析报告。
 
 ## 编程接口
 
@@ -168,6 +194,8 @@ A fast CLI tool for [Xiaohongshu (小红书 / RED)](https://www.xiaohongshu.com)
 > **"Install the `@lucasygu/redbook` Xiaohongshu CLI tool and run `redbook whoami` to verify it works. Repo: https://github.com/lucasygu/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.
+>
+> Once installed, try: **"Analyze the competitive landscape for 'AI编程' on Xiaohongshu"** — the agent will search keywords, analyze engagement data, profile top creators, and suggest content opportunities.
 
 ## Install
 
@@ -179,6 +207,16 @@ Requires Node.js >= 22. Uses cookies from your Chrome browser session — you mu
 
 After installing, run `redbook whoami` to verify the connection. If macOS shows a Keychain prompt, click "Always Allow". The CLI auto-detects all Chrome profiles to find your XHS session.
 
+## What You Can Do
+
+- **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
+- **Content planning** — Discover content opportunities with data-backed topic suggestions
+- **Audience insights** — Infer target audience from engagement signals
+
+When used through an AI agent, these workflows chain together automatically. Each CLI command also works standalone.
+
 ## Quick Start
 
 ```bash
@@ -223,7 +261,7 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `user <userId>` | Get user profile info |
 | `user-posts <userId>` | List a user's posted notes |
 | `feed` | Get homepage feed |
-| `post` | Publish an image note |
+| `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) |
 
@@ -243,8 +281,16 @@ redbook post --title "测试" --body "..." --images img.png --private
 | `--type <type>` | `all`, `video`, `image` | `all` |
 | `--page <n>` | Page number | `1` |
 
+### Analyze-Viral Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--comment-pages <n>` | Number of comment pages to fetch | `3` |
+
 ### Post Options
 
+Publishing **frequently triggers captcha** (type=124). Image upload works, but the publish step is unreliable. For posting, consider using browser automation instead.
+
 | Option | Description |
 |--------|-------------|
 | `--title <title>` | Note title (required) |
@@ -275,13 +321,19 @@ redbook post --title "测试" --body "..." --images img.png --private
 Installs automatically as a Claude Code skill. Use `/redbook` in Claude Code:
 
 ```
-/redbook search "AI编程"              # Search notes
-/redbook read <url>                   # Read a note
-/redbook user <userId>                # Creator profile
-/redbook analyze <userId>             # Full creator analysis
+/redbook search "AI编程"                        # Search notes
+/redbook read <url>                             # Read a note
+/redbook user <userId>                          # Creator profile
+/redbook analyze-viral <url>                    # Analyze a viral note
 ```
 
-Claude will call CLI commands, parse results, and handle complex workflows like competitive analysis and topic research.
+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:
+
+- *"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"*
+
+Claude will automatically combine multiple commands, parse JSON data, and produce structured analysis reports.
 
 ## Programmatic Usage
 

package/SKILL.md

@@ -1,11 +1,32 @@
 ---
-description: Search, read, and analyze Xiaohongshu (小红书) content via CLI
+description: Search, read, analyze, and automate Xiaohongshu (小红书) content via CLI
 allowed-tools: Bash, Read, Write, Glob, Grep
+# OpenClaw / ClawHub metadata (clawhub install redbook)
+name: redbook
+version: 0.2.0
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - redbook
+    install:
+      - kind: node
+        package: "@lucasygu/redbook"
+        bins: [redbook]
+    os: [macos]
+    homepage: https://github.com/lucasygu/redbook
+tags:
+  - xiaohongshu
+  - social-media
+  - analytics
+  - content-ops
 ---
 
 # Redbook — Xiaohongshu CLI
 
-Use the `redbook` CLI to search notes, read content, analyze creators, and research topics on Xiaohongshu (小红书/RED).
+Use the `redbook` CLI to search notes, read content, analyze creators, automate engagement, and research topics on Xiaohongshu (小红书/RED).
+
+**OpenClaw users:** Install via `clawhub install redbook` or `npm install -g @lucasygu/redbook`.
 
 ## Usage
 
@@ -28,6 +49,10 @@ Use the `redbook` CLI to search notes, read content, analyze creators, and resea
 | Browse feed | `redbook feed --json` |
 | Search hashtags | `redbook topics "keyword" --json` |
 | Analyze viral note | `redbook analyze-viral <url> --json` |
+| Extract content template | `redbook viral-template <url1> <url2> --json` |
+| 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` |
 | Check connection | `redbook whoami` |
 
 **Always add `--json`** when parsing output programmatically. Without it, output is human-formatted text.
@@ -303,6 +328,112 @@ redbook search "keyword" --type video --sort popular --json
 
 ---
 
+### Module I: Comment Operations
+
+**Answers:** Which comments deserve a reply? What is the comment quality distribution?
+
+**Commands:**
+```bash
+# 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
+redbook batch-reply "<noteUrl>" --strategy questions \
+  --template "感谢提问！关于{content}，..." \
+  --max 10 --delay 3000
+```
+
+**Fields to extract from `--dry-run` JSON:**
+- `candidates[].commentId` — target comments
+- `candidates[].isQuestion` — boolean, detected question
+- `candidates[].likes` — engagement signal
+- `candidates[].hasSubReplies` — whether already answered
+- `skipped` — how many comments were filtered out
+- `totalComments` — total fetched
+
+**Strategies:**
+- `questions` — replies to comments ending with `？` or `?` (learning-oriented audience)
+- `top-engaged` — replies to highest-liked comments (maximum visibility)
+- `all-unanswered` — replies to comments with no existing sub-replies (fill gaps)
+
+**How to interpret:**
+- High question rate (>15%) = audience is learning-oriented → reply to build authority
+- 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.
+
+**Output:** Reply plan table with candidate comments, strategy match reason, and status.
+
+---
+
+### Module J: Viral Replication
+
+**Answers:** What structural template can I extract from successful notes to guide new content creation?
+
+**Commands:**
+```bash
+# 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
+```
+
+**Fields to extract from `viral-template` JSON:**
+- `dominantHookPatterns[]` — hook types appearing in majority of notes
+- `titleStructure.commonPatterns[]` — specific title formula
+- `titleStructure.avgLength` — target title length
+- `bodyStructure.lengthRange` — target word count [min, max]
+- `bodyStructure.paragraphRange` — target paragraph count
+- `engagementProfile.type` — reference/insight/entertainment
+- `audienceSignals.commonThemes[]` — what the audience talks about
+
+**How to interpret:**
+- Consistent hook patterns across notes = proven formula for this niche
+- Narrow body length range = audience has clear content length preference
+- High collect/like in profile = audience saves content → create reference material
+- Common comment themes = topics to address in new content
+
+**Composition with other modules:**
+- Uses Module A results to identify top URLs for template extraction
+- Feeds into Module H (Content Brainstorm) as structural constraint
+- Uses Module C classification to validate engagement profile
+
+**Output:** Content template spec — the structural skeleton for content creation. An LLM (via the composed workflow) uses this template to generate actual title, body, hashtags, and cover image prompt.
+
+---
+
+### Module K: Engagement Automation
+
+**Answers:** How should I manage ongoing engagement with my audience?
+
+This module is a workflow that composes Modules I and J with human oversight.
+
+**Workflow:**
+1. **Monitor** — `redbook comments "<myNoteUrl>" --all --json` to fetch recent comments
+2. **Filter** — `redbook batch-reply --strategy questions --dry-run` to identify reply candidates
+3. **Review** — Human reviews dry-run output (or LLM reviews with persona guidelines)
+4. **Execute** — `redbook batch-reply --strategy questions --template "..." --max 10`
+5. **Report** — Summary of replies sent, errors encountered, rate limit status
+
+**Safety rules:**
+- Always `--dry-run` first, human approval before execution
+- Maximum 50 replies per session
+- Minimum 2-second delay between replies
+- Never reply to the same comment twice (check `hasSubReplies`)
+- Stop immediately on captcha — do not retry
+
+**Anti-spam guidelines:**
+- Vary reply templates across batches
+- Limit to 1-2 batch runs per note per day
+- Prioritize quality (targeted strategy) over quantity
+
+---
+
 ## Composed Workflows
 
 Combine modules for different analysis depths.
@@ -332,22 +463,51 @@ The comprehensive playbook — keyword landscape, cross-topic heatmap, engagemen
 
 No module composition needed — `analyze-viral` returns hook analysis, engagement ratios, comment themes, author baseline comparison, and a 0-100 viral score in one call.
 
-### Viral Pattern Research
+### Viral Pattern Research → Content Template
 ```bash
 # 1. Find top notes
 redbook search "keyword" --sort popular --json
 
-# 2. Analyze 3-5 top notes
-redbook analyze-viral "<url1>" --json
-redbook analyze-viral "<url2>" --json
-redbook analyze-viral "<url3>" --json
-
-# 3. Synthesize across notes:
-#    - Which hookPatterns[] appear most often?
-#    - What collectToLikeRatio is typical?
-#    - What content structure drives saves vs. shares?
+# 2. Extract template from top 3 notes (replaces manual synthesis)
+redbook viral-template "<url1>" "<url2>" "<url3>" --json
 ```
 
+`viral-template` automates what previously required manual synthesis across `analyze-viral` results. It outputs a `ContentTemplate` JSON that captures dominant hooks, body structure ranges, engagement profile, and audience signals.
+
+### Reply Management
+**Modules:** I
+
+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
+
+Keyword research → viral template extraction → data-backed content brainstorm. The template provides structural constraints that guide Module H's content ideas.
+
+### Full Operations
+**Modules:** A → C → I → J → K
+
+Comprehensive automation playbook — keyword analysis, engagement classification, comment operations, viral replication templates, and engagement automation workflow.
+
+---
+
+## API vs Browser Limitations
+
+The following operations work reliably via API:
+- **Reading**: search, notes, comments, user profiles, feed
+- **Writing**: top-level comments, comment replies
+- **Analysis**: viral scoring, template extraction, batch reply planning
+
+The following operations are unreliable via API (frequently trigger captcha):
+- Publishing notes (use `--private` for higher success rate)
+- Bulk operations at very high frequency
+
+The following operations require browser automation (not supported by this CLI):
+- Captcha solving, real-time notifications
+- Like/collect/follow (heavy anti-automation enforcement)
+- DM/private messaging
+- Cover image generation (use external tools like Gemini/DALL-E)
+
 ---
 
 ## Command Details
@@ -443,6 +603,72 @@ Returns `{ note, score, hook, content, visual, engagement, comments, relative, f
 - `relative.isOutlier` — true if viralMultiplier > 3
 - `comments.themes[]` — top recurring keyword phrases from comments
 
+### `redbook viral-template <url> [url2] [url3]`
+
+Extract a reusable content template from 1-3 viral notes. Analyzes each note (same pipeline as `analyze-viral`) and synthesizes common structural patterns.
+
+```bash
+redbook viral-template "<url1>" "<url2>" "<url3>" --json
+redbook viral-template "<url1>" --comment-pages 5 --json
+```
+
+**Options:**
+- `--comment-pages <n>`: Comment pages to fetch per note (default: 3, max: 10)
+
+**JSON output structure:**
+Returns `{ dominantHookPatterns, titleStructure, bodyStructure, engagementProfile, audienceSignals, sourceNotes, generatedAt }`.
+
+- `dominantHookPatterns[]` — hook types appearing in majority of input notes
+- `titleStructure.avgLength` — average title length across notes
+- `bodyStructure.lengthRange` — [min, max] body length
+- `engagementProfile.type` — "reference" / "insight" / "entertainment"
+- `audienceSignals.commonThemes[]` — merged comment themes across notes
+
+### `redbook comment <url>`
+
+Post a top-level comment on a note.
+
+```bash
+redbook comment "<noteUrl>" --content "Great post!" --json
+```
+
+**Options:**
+- `--content <text>` (required): Comment text
+
+### `redbook reply <url>`
+
+Reply to a specific comment on a note.
+
+```bash
+redbook reply "<noteUrl>" --comment-id "<commentId>" --content "Thanks for asking!" --json
+```
+
+**Options:**
+- `--comment-id <id>` (required): Comment ID to reply to (from `comments --json` output)
+- `--content <text>` (required): Reply text
+
+### `redbook batch-reply <url>`
+
+Reply to multiple comments using a filtering strategy. Always preview with `--dry-run` first.
+
+```bash
+# Preview which comments match the strategy
+redbook batch-reply "<noteUrl>" --strategy questions --dry-run --json
+
+# Execute replies with a template
+redbook batch-reply "<noteUrl>" --strategy questions \
+  --template "感谢提问！{content}" --max 10 --delay 3000
+```
+
+**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)
+- `--dry-run`: Preview candidates without posting (default when no template)
+
+**Safety:** Stops immediately on captcha. No template = dry-run only.
+
 ### `redbook whoami`
 
 Check connection status. Verifies cookies are valid and shows the logged-in user.