redbook

Redbook — Xiaohongshu CLI

redbook CLI を使って、Xiaohongshu（小红书/RED）でノートを検索したり、コンテンツを読んだり、クリエイターを分析したり、エンゲージメントを自動化したり、トピックを調査したりできます。

OpenClaw ユーザー向け： clawhub install redbook または npm install -g @lucasygu/redbook でインストールしてください。

⚠️ 調査上の注意（最初にお読みください）。 XHS の風控は、書き込みだけでなく閲覧も制限します。数件を超えるノートを読む調査では、必ず Research Loop を利用してください。デフォルトでは人間のペースで実行します（1 件あたり約 20 秒、1 件ずつ。一般的なジョブは数十分、大規模なジョブは 1 日に分けて実行します）。read／comments／analyze-viral を短い間隔で連続実行すると、数十回以内に CAPTCHA／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 を追加してください。指定しない場合、出力は人間向けの形式になります。

---

XHS プラットフォームのシグナル

XHS は Twitter や Instagram とは異なります。プラットフォーム固有のエンゲージメント比率から、コンテンツの種類やオーディエンスの行動を読み取れます。

コレクション／「いいね」比率（collected_count / liked_count）

XHS の「コレクション」（收藏）は、後で見返すために保存する仕組みです。ユーザーは個人用の参考ライブラリを作成します。この比率は、コンテンツの実用性を示す最も強い指標です。

比率	分類	意味
>40%	ツール型 (Reference)	チュートリアル、チェックリスト、テンプレートなど。ユーザーは再利用のためにブックマークします
20–40%	認知型 (Insight)	考えさせられる内容ですが、後で見るためには保存されません
<20%	エンタメ型 (Entertainment)	消費されて忘れられる内容で、エンゲージメントは受動的です

コメント／いいね比率（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 平均が低い場合は、突出したノートが1件だけ存在し、競争が難しいことを意味します。
• 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 Platform Signals にある比率の基準を適用します。

出力： キーワードまたはノートごとの分類。

キーワード	保存／いいね	コメント／いいね	タイプ
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 から：type === "fans" に該当する interactions[] → フォロワー数
• 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 を改行区切りで記述します。空行と # で始まるコメント行は無視されます。利用できる場合は、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

抽出するフィールド：

• 2 つの結果セット間で、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 超）	中

---

Module G: オーディエンスの推定

回答する質問： このニッチのオーディエンスは誰ですか？何を求めていますか？

入力： Module C のエンゲージメント比率 + analyze-viral のコメントテーマ + コンテンツパターン。

analyze-viral JSON から抽出するフィールド：

• comments.themes[] — コメント欄で繰り返し使われるフレーズやキーワード
• comments.questionRate — 質問形式のコメントの割合（学習意欲）
• engagement.collectToLikeRatio — 保存行動が示す意図
• hook.hookPatterns[] — このオーディエンスを引きつけるタイトルパターン

推定ルール：

• 保存率が高く、質問率も高い → 学習志向のオーディエンス（学生、専門職）
• コメント率が高く、感情的なテーマが多い → コミュニティ志向のオーディエンス（体験を共有）
• シェア率が高い → 憧れ志向のオーディエンス（ライフスタイル、アイデンティティの表明）
• コメントの言葉遣いのパターン → 年齢・教育水準の手がかり（フォーマル＝年齢層が高め、スラング＝若年層）

出力： オーディエンスのペルソナ概要 — 属性、意図、コンテンツの好み。

---

Module H: コンテンツのブレインストーミング

回答する質問： データに基づいて、具体的にどのようなコンテンツを作成すべきですか？

入力： 機会スコア（Module F）+ オーディエンスのペルソナ（Module G）+ ヒートマップのギャップ（Module B）。

各コンテンツ案について、以下を指定します：

• ターゲットキーワード — 機会スコアリングに基づく
• フックの切り口 — このニッチで効果のある hookPatterns に基づく
• コンテンツの種類 — オーディエンスのニーズに基づく、実用型／知識型／エンタメ型
• 形式 — Module E に基づく、画像とテキストまたは動画
• エンゲージメント目標 — このキーワードの Top10 平均に基づく現実的な目標
• 競合の参考例 — この切り口が効果的だと示す、具体的なノート URL

出力： データの裏付けがある、順位付けされたコンテンツ案。

#	キーワード	フックの切り口	種類	目標「いいね」数	参考例
1	keyword3	"N個の方法..."（リスト）	実用型 画像とテキスト	5K+	[トップノートの URL]
2	keyword1	"なぜ..."（質問）	知識型 動画	10K+	[トップノートの URL]

---

Module 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）＝リーチを最大化するため、目に留まりやすいコメントに返信する
• 未返信のコメントが多い＝エンゲージメントのギャップがあり、返信率を高める機会

安全対策： 1 バッチあたりの返信数は最大 30 件、最低 3 分の間隔を設け、±30% のジッターを加えます（デフォルトは 5 分）。デフォルトでは --dry-run（テンプレートがない場合はプレビューのみ）を使用し、CAPTCHA が表示された場合は直ちに停止します。詳細はレート制限と安全対策を参照してください。

出力： 対象コメント、戦略との一致理由、ステータスを含む返信計画の表。

---

モジュール 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 の分類を使用して、エンゲージメントプロフィールを検証します

出力： コンテンツテンプレートの仕様 — コンテンツ作成のための構造的な骨組みです。LLM は、合成されたワークフローを通じてこのテンプレートを使用し、実際のタイトル、本文、ハッシュタグ、カバー画像のプロンプトを生成します。

---

モジュール K：エンゲージメントの自動化

回答する質問： オーディエンスとの継続的なエンゲージメントをどのように管理すべきですか？

このモジュールは、人間による監督のもとでモジュール I と J を組み合わせるワークフローです。

ワークフロー：

1. 監視 — redbook comments "<myNoteUrl>" --all --json を実行して最近のコメントを取得します
2. フィルタリング — redbook batch-reply --strategy questions --dry-run を実行して返信候補を特定します
3. 確認 — 人間がドライランの出力を確認します（または、LLM がペルソナのガイドラインに沿って確認します）
4. 実行 — redbook batch-reply --strategy questions --template "..." --max 10 を実行します
5. 報告 — 送信した返信、発生したエラー、レート制限の状況をまとめます

安全ルール：

• 必ず最初に --dry-run を実行し、実行前に人間の承認を得ます
• 1 セッションあたりの返信数は最大 30 件です（厳守）
• 返信の間には最低 3 分の間隔を設けます。既定は 5 分で、±30％のランダムなゆらぎを加えます
• 同じコメントに 2 回返信しません（hasSubReplies を確認します）
• CAPTCHA が表示されたら直ちに停止し、再試行しません
• XHS のリスク管理しきい値については、レート制限と安全性を参照してください

スパム対策のガイドライン：

• バッチごとに返信テンプレートを変えます
• ノートごとに、1 日あたりのバッチ実行を 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 フロントマターを含む 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（Retina 品質、実際の出力サイズは 2160×2880）
• スタイル： purple、xiaohongshu、mint、sunset、ocean、elegant、dark

ページ分割モード：

• 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：ノートの健全性チェック（限流検出）

回答する質問： XHS によって密かに表示制限されているノートはありますか？

XHS はクリエイターバックエンド API の各ノートに、非公開の level フィールドを割り当てています。このレベルはおすすめ表示の配信を制御しますが、UI には表示されません。ノートが「通常」のように見えても、実際にはおすすめがまったく表示されていない可能性があります。

コマンド：

# 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 to -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

網羅的な分析手順です。キーワードの全体像、トピック横断のヒートマップ、エンゲージメントのシグナル、クリエイタープロフィール、コンテンツ形式の分析、機会の評価、オーディエンスのペルソナ、データに基づくコンテンツのアイデアを扱います。

1件のノートを詳細に分析

コマンド： redbook analyze-viral "<url>" --json

モジュールを組み合わせる必要はありません。analyze-viral は、フック分析、エンゲージメント比率、コメントのテーマ、投稿者の基準値との比較、0〜100のバズスコアを1回の呼び出しで返します。

バズパターンの調査 → コンテンツテンプレート

# 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時間（1日あたり最大2〜3件）	N/A（手動）	—
コメント	≥3分	N/A（手動）	—
返信	≥3分	N/A（手動）	—
一括返信の待機時間	≥3分	5分 ±30% の揺らぎ	—
一括返信の件数	—	10	30

検出回避策

• タイミングの揺らぎ： 一括処理のすべての待機時間に ±30% のランダムな変動を加えます。一定間隔での実行はボットの特徴です。
• 上限： 1回の一括処理あたりの返信は最大30件です（50件から引き下げ）。上書きはできません。
• レート制限の警告： post、comment、reply コマンドは、各アクションの後に安全な間隔をリマインドします。
• Captcha サーキットブレーカー： Captcha（NeedVerify）が発生すると、一括処理は直ちに停止します。

リスク管理が作動する条件

• タイミングが一定 — ちょうど3秒間隔で返信すると、ボット検出の対象になります
• 頻度が高い — アクションの種類を問わず、1分間に50件を超えるインタラクション
• アクティビティ比率の異常 — 投稿の閲覧数よりコメント数が多いと、信頼できない挙動と見なされます
• デバイスフィンガープリントの不一致 — XHS は21個のハードウェアパラメーターをフィンガープリントとして取得します

エージェント向けのベストプラクティス

1. まず必ず --dry-run を実行し、候補を確認してから実行する
2. デフォルトの5分間の待機時間を使用し、--delay を 180000（3分）未満に設定しない
3. 一括処理はノート1件あたり1日1〜2回に制限する
4. 一括処理ごとに返信テンプレートを変える
5. post コマンドの実行間隔を3〜4時間空ける（1日あたり最大2〜3件）

---

Research Loop — レート制限に安全な長時間リサーチ

上記のレート制限と安全性のセクションでは、書き込みのペースを調整しています。このセクションでは、実際のリサーチで負荷が集中する読み取りのペースを調整します。read、comments、analyze-viral はそれぞれノート詳細 API にアクセスします（xsec_token を使用）。これらを短時間に30〜50回連続して実行すると、XHS は NeedVerify／CAPTCHA を返すか、IP をブロックします（300012）。一度制限を受けたアカウントは、数時間にわたって状態が悪化します。そのため、ここでのリサーチは並列ではなく、ペースを調整して行います。ノートは一度に1件だけ処理し、スクリプトによるスクレイピングではなく、人が読んでいるように見える間隔を空けます。

仕組みはファイルベースのループです。作業項目をディスク上のキューに入れ、「ティック」ごとに1項目を処理し、結果をすぐにチェックポイントとして保存します。すべての状態がファイルに保存されるため、ループは再開可能で、セッションが終了しても維持されます。新しいセッション（または Push のハートビート）が、前回終了したところから正確に再開します。統合のステップでは /checkpoint-research スキルと組み合わせて使います。

ペース — 安全な範囲（この数値の理由）

これらの値は推測ではなく、XHS が公開している読み取り側の安全な範囲に合わせて調整されています。コミュニティのクローラー（MediaCrawler）は、既定で1リクエストあたり約2秒、シングルスレッドです（CRAWLER_MAX_SLEEP_SEC = 2、MAX_CONCURRENCY_NUM = 1）。リバースエンジニアリングの報告では、「人間らしく見える」頻度は1リクエストあたり3〜8秒、IPあたりの上限は1分あたり5リクエスト以下（平均約12秒）とされています。このスキルは、実際にログインした状態の Cookie＋住宅用 IP＋実際の Chrome フィンガープリントで動作します。これは、検出される可能性が最も低いプロファイルです（スクレイパーが多くの労力をかけて偽装するものです）。そのため、決定的なリスクはリクエストの署名ではなく、行動パターンです。人間が2分間にノート詳細ページを100件開くことはありません。そこで、絶対的な最短間隔ではなく、安全な範囲に十分収まる、人間の読書ペースに合わせて間隔を調整します。（以前の推測だった5分間隔では、上限より約25倍遅くなり、何の利点もありません。）

実際のルール：ゆっくり動くのではなく、人間が読んでいるように振る舞う

ここでの検知はレートのしきい値ではなく、分布に基づくものです。 XHS は「リクエスト数が N を超えたか？」とは問いません。人間のセッションがどのようなものかをモデル化し、ありそうにないものを検出します。単純な速度が見分ける手がかりではなく、行動のパターンです。スクリプトだと見抜かれる要因は 3 つあります。

• タイミングのミクロ構造。 人間のアクション間隔は分散が大きく、裾が長くなります（2 秒、次は 40 秒、その次は 5 分――結果を読み、スクロールし、気が散るためです）。スクリプトは間隔が短く、分散の小さいストリームを生成します。5 秒間に異なる検索を 3 回行うと、分散はほぼゼロになり、結果ページを読む人間より速くなります――この一点だけで、合計件数よりも強いシグナルになります。
• セッションのマクロ構造。 人間は深さ優先で閲覧します。検索 → ノートを開く → しばらく読む → 関連するノートを開く → いろいろ見て回る、という流れです。スクレイピングは幅優先の列挙です。検索 A、検索 B、検索 C……中をクリックすることも、じっくり読むこともありません。キーワードリストを上から順に処理すること自体が、典型的なサインです。
• アクションの組み合わせ。 実際のセッションでは、「いいね」、保存、閲覧、スクロール、動画視聴が混在します。調査の実行では、じっくり読むこともエンゲージメントもない、閲覧 100％の状態になります。これは人間にはありえない比率です。

つまり、ルールは**「ゆっくり動く」ことではありません。** セッションを、人間が読んでいる場合と見分けがつかないようにすることです。人間らしいばらつき（単に一定の間隔を長くするのではなく、ジッターと時折入る長い休止）、閲覧時間を確保しながらノートを 1 件ずつ処理すること、幅より深さを優先すること、人間は何百件もの項目を開かないため上限を設けること、そして摩擦の兆候があればすぐに停止することです（CAPTCHA に遭遇した人間は引き下がりますが、ボットは再試行します。そのため、サーキットブレーカー自体が人間らしい行動になります）。

安全性優先の姿勢は、臆病なのではなく、よりエージェント的なものです。 エージェントの本当の強みは速度ではなく、大規模に忍耐強く行動できることです。人間にはできない 8 時間の人間らしいループを実行できます。積極的に動くことは、捕まる原因となる人間の特性（せっかちさ）をまねる一方、エージェントだけが持つ特性（疲れを知らない忍耐強さ）を無駄にします。忍耐強さを活かしてください。

これはパターンであり、ブラックリストではありません。 ここに記載した数値は、ある実際のインシデントをもとに調整されました。飲料トレンドの調査で、関連のない約 17 個のキーワードに対して約 5 秒間に異なる検索を 3 回実行し、アカウントレベルの警告を受けた事例です。ここで定めているのは、行動上の不変条件（人間らしいタイミング、同時に実行するのは 1 件、上限、閲覧時間、サーキットブレーカー）であり、「そのクエリを実行してはいけない」というルールではありません。 どんなトピック、どんなプラットフォームにも当てはまります。このインシデントは、人間とボットの境界がどこにあるかを示す調整用のサンプルであり、抹茶に関するルールではありません。

3 つのモード

モード	ノートごとのペース	約読み取り数／分	使用する場面	条件
🚶 標準（デフォルト）	20 秒 ± 50％のジッター（約 10～35 秒）	約 2～3	通常の調査／複数ノートの調査全般	なし――これがデフォルトです。
🐢 詳細／夜間	60～120 秒	約 0.5～1	非常に大きなコーパス、または実行痕跡を最小限にしたい場合	大規模なジョブではオプトイン
⚡ 高速（緊急時）	ジッターの下限 5 秒、最大 30 ノートの連続実行後にクールダウン	約 10 以上（安全な上限を超過）	待てない本当の締め切りがある場合	高速モードの警告を一字一句そのまま出力し、かつユーザーから明示的なオプトインを得ること

すべてのモードで守ること： 遅延ゼロは禁止、並列実行は禁止、処理中のノートは必ず 1 件のみとし、警告を表示した高速モードを除き、継続的な読み取り数を毎分約 5 件を超えないようにしてください。標準ペースなら、100 件のキューは約 35～50 分で完了します。終業時までかかるのは、非常に大きなキューか詳細モードの場合だけです。

厳格なルール（必須）

1. ループは必須です。デフォルトのペースは Steady です。 約 5 件を超えるノートに触れる調査は、すべて Steady ペースでループを実行します。Deep／overnight、特に Fast は明示的なオプトインが必要です。Fast では、警告の表示とユーザーの確認も必要です。
2. 処理中のノートは常に 1 件です。 読み取りをまとめたり、並列化したりしてはいけません。項目間の待機時間を設けずに for url in …; do redbook read …; done を実行してはいけません。バックグラウンドで & による一斉実行をしてはいけません（参照用クローラーと同様に MAX_CONCURRENCY = 1）。
3. 常にランダムな揺らぎを加え、読み取りは毎分約 5 件未満に抑えます。 IP ごとの安全な上限は毎分約 5 リクエスト（1 ノートあたり約 12 秒）です。Steady（20 秒）は十分に上限を下回ります。待機時間ごとに ±50％のランダムな揺らぎを加えてください。一定間隔はボットの特徴です。上限を超えられるのは、警告を表示した Fast モードだけです。
4. コメントのページネーションに上限を設けます。 コメント／サブコメントの読み取りは最もリスクの高いエンドポイントであり、最初に風控が発動します（コメントを深くクロールすると、非常に長い待機時間を設けても失敗します）。--comment-pages ≤ 3 を維持し、コメントの各ページを他の読み取りと同様にペースと予算に算入してください。また、コメントスレッドを深くクロールしてはいけません。
5. 各項目の処理後に必ずチェックポイントを作成します。 次のティックの前に、各結果をディスクに書き込み、マニフェストを更新してください。メモリ内だけに保持してはいけません。
6. 1 日あたりの予算を守ります。 デフォルトのソフト上限は、詳細読み取り約 200 件／日です。ペースとは無関係に、異常な件数自体が風控のトリガーになります。consumedToday >= dailyBudget になったら、翌日まで停止してください。「あと数件だけ」続けてはいけません。
7. サーキットブレーカーは絶対です。 最初の風控シグナルが発生したら（サーキットブレーカーを参照）、ループ全体を停止し、状態を永続化して、ユーザーに伝えてください。自動でリトライして続行してはいけません。 再開できるのは、人間が明示的に「resume」と指示した場合だけです。
8. 対象は読み取りであり、書き込みではありません。 このループは読み取り／分析専用です。エンゲージメント操作（コメント／返信／いいね）には独自の書き込み側の上限が適用され、調査のティックに組み込むことはありません。

状態の契約（再開可能、セッション終了後も維持）

状態はすべて 1 つのジョブディレクトリに保存します。デフォルトはプライベートコンテンツリポジトリ内の research/xhs/<job-slug>/ です（どのリポジトリか不明な場合は確認してください）。

ファイル	役割
queue.jsonl	作業キュー。1 行につき 1 項目：{ "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 を抽出し、ノートごとに 1 件の read／analyze-viral 項目を queue.jsonl に書き込みます。その後、ループでコストの高い詳細読み取りを Steady ペースで処理します。項目の arg には、トークン付きの新しい webUrl を必ず指定してください。トークンは期限切れになるため、noteId だけをキューに入れてはいけません（xsec_token（ノートの読み取り／共有に必須）を参照）。クリエイターのキューでは、xsec_token を含むプロフィール URL を優先してください。userId だけでは code=-1 が返る場合があります。

1 ティック = 1 件のノート

ティックは、どちらのドライバーも呼び出す単位です。項目を正確に 1 件処理して停止します。

1. loop-state.json を読み込みます。 breaker != "ok" の場合 → ただちに終了します（理由を表示し、処理は行いません）。
2. 1 日の予算を更新します。 budgetDate が今日と異なる場合は、consumedToday = 0、budgetDate = today にリセットします。consumedToday >= dailyBudget の場合 → 翌日まで終了します。
3. queue.jsonl から次の pending 項目を取り出します。 残っていない場合 → 完了処理を行います。results/ から SUMMARY.md を作成し、ループを完了としてマークして、ドライバーに停止を伝えます。完了です。
4. 読み取りを正確に 1 回実行します： 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. 停止します。 ノートは 1 件のみです。ドライバーは（ジッターを加えた）間隔の後に再度呼び出します。

ドライバー — バックグラウンドでループを実行し続ける

同じティックを、2 つの方法で実行します。ジョブを現在のセッションよりどれだけ長く実行し続ける必要があるかに応じて選択してください。

A) セッション内の間隔制御（デフォルト — Steady）。 最もシンプルで、ほとんどのジョブに適したドライバーです。1 つのセッション内でティックを連続実行し、各読み取りの間に intervalSec ± ジッターの時間だけスリープします。Steady ペースなら 100 件のノートキューは約 35～50 分で完了し、1 つのセッション内に十分収まります。また、各項目はチェックポイントに保存されるため、クラッシュしてもそこから再開できます。スケジューラーは不要です。（ペースは読み取りごとに設定してください。長時間のブロッキング sleep で代用しないでください。）

B) /loop による自動ペース制御（Deep／夜間／アイドル時間をまたぐ場合）。 Deep モードや数時間にわたるジョブでは、間隔を指定せずに /loop でティックを実行します（自動ペース制御）。ティックを 1 回実行し、intervalSec + ジッターの時間後に ScheduleWakeup を設定して、再度実行します。ScheduleWakeup は ≥60 s に制限されるため、Deep（60～120 s）には適していますが、1 分未満の Steady には適しません（Steady は A のようにセッション内で実行してください）。キューがなくなる（手順 3）か、サーキットブレーカーが作動する（手順 5）と、ループは自動的に終了します。

C) Hook — Push の定期的な issue（複数日にわたるジョブ／真のバックグラウンド実行、アプリの再起動後も継続）。 「これを毎日実行する」調査や、1 日で処理しきれないほど大きなコーパスに最適です。redbook に対応したエージェントに割り当てた定期的な issue（recurringIntervalSec — ティックごとに数分、または毎日の一括実行）を作成します。各回は、同じジョブディレクトリに対する新しいセッション = 1 ティックです。そのため、issue の本文にはジョブディレクトリを指定し、「ティックを正確に 1 回実行してから終了する」と記載する必要があります。人が終了させるまで実行され続けます。キューがなくなるとエージェントは完了処理を行ってコメントし、サーキットブレーカーが作動した場合はコメントを残して人の対応を待ちます。（Push の「scout」パターン — スケジュールは issue に設定され、エージェントの Auto スイッチが実行を制御します。）

なぜ長時間稼働プロセスではなくファイル状態なのか： ブロッキングの sleep ループはターミナルを終了すると停止し、再開できません。キュー、loop-state.json、項目ごとの結果ファイルを使用すれば、将来のどのセッションでも — /loop によるウェイク、Push のハートビート、人がティックを再実行する場合 — 前回停止した位置から正確に続行でき、途中までのコーパスが失われることもありません。

⚡ 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 / captcha	エラーメッセージまたはレスポンスフラグ
空の {} レスポンス	通常、xsec_token の期限切れまたは無効、あるいはスクレイピング対策が原因です。新しい webUrls でキューを再シードし、むやみに再試行しないでください
Session expired / "No 'a1' cookie"	Cookie が無効です。再開前に Chrome で再ログインしてください
IP ブロック 300012	厳しいレート制限です。解除されるまで待つか、ネットワークを切り替えてください

作動時は、loop-state.breaker:"tripped" と breakerReason を設定し、現在の項目を pending のままにして、状態を永続化し、ユーザーに通知する（または Push の issue にコメントする）必要があります。ブロックを通り抜けるために自動再試行しないでください。自動再試行すると、軽度のスロットリングが数時間に及ぶブロックへと悪化します。原因を人間が解消し、続行するよう明示的に指示した場合にのみ再開してください。

---

API とブラウザーの制限事項

以下の操作は API 経由で安定して実行できます。

• 読み取り：検索、ノート、コメント、ユーザープロフィール、フィード、お気に入り
• 書き込み：トップレベルのコメント、コメントへの返信、ノートの収集／収集解除
• 分析：バイラルスコアリング、テンプレート抽出、一括返信の計画

以下の操作は API 経由では不安定です（頻繁に captcha が発生します）。

• ノートの公開（成功率を高めるには --private を使用してください）
• 非常に高頻度での一括操作

以下の操作にはブラウザー自動化が必要です（この CLI ではサポートされていません）。

• captcha の解決、リアルタイム通知
• いいね／フォロー（自動化対策が厳重です）
• DM／プライベートメッセージ
• カバー画像の生成（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 が captcha を返した場合は、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）— フック（20）+ エンゲージメント（20）+ 相対評価（20）+ コンテンツ（20）+ コメント（20）の合計
• hook.hookPatterns[] — 検出されたタイトルパターン（Identity Hook、Emotion Word、Number Hook、Question など）
• 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：投稿せずに候補をプレビューします（テンプレートがない場合のデフォルト）

安全性: CAPTCHA が表示された場合、直ちに停止します。テンプレートがない場合は dry-run のみです。XHS のボット検出を引き起こす均一なタイミングパターンを避けるため、遅延にはランダムな揺らぎが含まれます。

redbook render <file>

YAML フロントマターを含む 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

ブラウザーからCookieを抽出できないOpenClaw、クラウド、CIでの実行や、コマンドごとに--cookie-stringを繰り返し指定する場合に備えて、保存済みのCookieを管理します。

# 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で頻繁にCAPTCHA（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...>：画像ファイルのパス（必須、1つ以上）
• --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（グローバル）を強制します。デフォルト：ログイン中のプラットフォームを自動検出します。中国本土版とグローバル版を参照してください。
• --global：グローバル版RedNoteのバックエンドを強制します（= --platform rednote）
• --json：JSON形式で出力します

---

中国本土版Xiaohongshuとグローバル版RedNote

XHSは、セッションやCookieを共有しない2つの独立したバックエンドを運用しています。

	中国本土版	グローバル版
アプリ／サイト	小红书 / xiaohongshu.com	RedNote / rednote.com
APIホスト	edith.xiaohongshu.com	webapi.rednote.com
Cookieドメイン	.xiaohongshu.com	.rednote.com

RedNoteではIP／地域に基づいて中国本土版とグローバル版のどちらに接続するかが決まり、1台のマシンで同時にログインできるのはどちらか一方だけです。そのため、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呼び出しを1回行い、実際にログインしている方を確認します。結果は~/.redbook/platform-cache.jsonにCookieフィンガープリントをキーとしてキャッシュされるため、コマンドごとにAPIへ再アクセスすることはなく、ログイン／ログアウト時には自動的に無効になります。標準エラー出力には、薄い色の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が必要になる場合があります。ユーザーIDだけを指定してcode -1が返される場合は、プロフィールの完全なURLまたは--xsec-tokenを渡してください。
• health（ノートのスロットリングレベル）には、クリエイターダッシュボードのCookieが必要です。まずRedNoteのクリエイターダッシュボードにログインしてください。

---

技術リファレンス

xsec_token — ノートの読み取りと共有に必須

XHS API でノートのコンテンツを取得するには、有効な xsec_token が必要です。トークンがない場合、read、comments、analyze-viral は {} を返します。

共有可能な URL にも同じトークンが必要です。 ?xsec_token=...&xsec_source=... のない https://www.xiaohongshu.com/explore/<id> URL は、XHS のスクレイピング対策レイヤーによって https://www.xiaohongshu.com/404/sec_*?source=xhs_sec_server&originalUrl=... に 302 リダイレクトされます。Safari、iOS のリンクプレビュー、エージェントのアクションボタンなど、その URL をクリックするすべてのユーザーに影響します。

webUrl — こちらを使用してください（v0.7.0 以降）：

ノートを返す各コマンド（feed、search、user-posts、favorites、board、read、post）に、トークンが埋め込まれ、正しい xsec_source が設定された webUrl フィールドが含まれるようになりました。利用側では 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

エージェント向け： レスポンスの 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" / captcha	ボット対策が作動しました	しばらく待ってから再試行するか、リクエスト頻度を下げてください
"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)"	ユーザー ID ではなく、数字の Red 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 にログインしていること（または --cookie-source を指定して Safari／Firefox を使用）
• macOS（Cookie の抽出にはネイティブのキーチェーンアクセスを使用します）
• カードのレンダリングのみ： puppeteer-core と marked（npm install -g puppeteer-core marked）。既存の Chrome を使用するため、ブラウザーを別途ダウンロードする必要はありません。