kuaishou-comment

快手のコメント分析

📝 概要

快手の作品リンクを入力すると、トップレベルのコメントデータを取得できます。1ページあたり20件で、cursor によるページネーションに対応しています。会話内に現在のページの全コメントと AI による要約分析を表示するとともに、現在のページのデータと要約を含むインタラクティブな HTML レポートを生成します。

✨ 機能

機能モジュール	機能の説明	主な価値
コメント取得	作品リンクを貼り付けるだけでコメントを取得	作品のコメント欄データをリアルタイムで取得
ページネーション	1ページあたり20件、cursor によるページ送り	大量のコメントをページごとに閲覧
AI 要約	4つの観点による感情分析（肯定的／否定的／ニーズ／競合）	コメントの世論全体をすばやく把握
ピン留め表示	ピン留めコメントを特別に表示	重要なコメントをひと目で識別
HTML レポート	ダークテーマのインタラクティブなレポート	分析結果をオフラインで保存・共有
レポートの統合	複数ページを統合し、3ページを超えると自動的に折りたたみ	すべてのコメント分析を一度にエクスポート

🔑 認証

红狐hub で API Key を取得し、以下の方法で設定します。

# 方式一：配置文件（如 OpenClaw 的 ~/.openclaw/openclaw.json）
{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }

# 方式二：终端环境变量
export REDFOX_API_KEY="ak_xxxx..."

🔄 ワークフロー

Step 1：ユーザーの意図を理解し、opusId を抽出する

⚠️ 重要なルール：ユーザーが作品リンクを指定した場合、エージェントはリンクから opusId を抽出します。

• ユーザーが作品リンク（例：https://www.kuaishou.com/short-video/3x4ibfzs5e68yxu）を指定した場合、エージェントはリンクから opusId を抽出します
• ユーザーが opusId（例：3x4ibfzs5e68yxu）を直接指定する場合もあります。その場合はそのまま使用します
• ユーザーが作品リンクを指定していない場合は、「快手の作品リンクを指定してください」と尋ねます
• 前回の会話で作品のデータを検索しており、今回の入力が曖昧な場合（「次のページ」「コメント分析」など）は、前回の opusId を引き継ぎます

Step 2：コメント取得スクリプトを呼び出す（HTML を自動生成）

⚠️ 呼び出し1回につき1ページ分のみリクエストします（API リクエスト1回）。複数回呼び出して複数ページを取得することはできません。

スクリプトは呼び出しごとに HTML レポートを自動生成します（プレースホルダーを含み、分析データは未入力）。ターミナル表示と HTML は同じ API 呼び出しに基づくため、データは一致します。

python3 ~/.agents/skills/kuaishou-comment/scripts/kuaishou_comment_search.py "<opusId>" [--cursor <cursor>] [--page <page>]

パラメーターの説明：

パラメーター	説明	デフォルト値
opusId	快手作品の opusId（必須）	—
--cursor	カーソル。最初のページには空文字列を指定し、次のページには前のページで返された nextCursor を指定します	""
--page	現在のページ番号（HTML ファイル名と出力マーカーにのみ使用）	1
--output-dir	HTML 出力ディレクトリ	~/Downloads/QoderReports

スクリプトが返す JSON フィールドについては、下記のコメントフィールド表を参照してください。

注意： この時点の HTML レポートにはコメントの生データのみが含まれます。分析のプレースホルダーは、ユーザーの確認後に入力します。

Step 3：会話内にコメントデータと AI 要約を表示する

⚠️ 1回の操作につき API を1回だけ呼び出し、1ページ分のデータを取得します。

A1. 検索範囲を伝える

📊 作品「{opusId}」から N 件のコメントを取得しました（{page} ページ目）。詳細データは以下のとおりです。

A2. コメントの表を表示する（現在のページの全コメントを表示）

形式のルール：

• コメント投稿者の列にはニックネームのみを表示し、アバターは表示せず、ハイパーリンクも生成しません
• コメント内容が40文字を超える場合は切り詰めて ... を付けます
• 時刻は MM-DD HH:MM 形式にします
• ピン留めコメントはニックネームの後ろに 📌 マークを付けます（行全体を太字にします）
• like_count / reply_count の数値が ≥ 10000 の場合は x.xw 形式にします
• 各ページのすべてのコメントを表示し、省略してはいけません

A3. AI によるコメント要約（⚠️ ページ送りを含め、検索のたびに必ず出力）

最初のページ：現在のページのコメントに基づいて、4つの観点から感情を分析します。

ページ送り後：これまでに取得したすべてのページの累積データに基づいて総合分析し、累計件数を明記します。

分析前に快手コミュニティの文化を理解します（老鉄文化、絵文字の意味、「奥利给」「双击」などの特有の表現）。

📈 コメントの要約分析（{total} 件のコメントに基づく）

✅ 肯定的な評価（{positive_ratio}%）

• {要点。代表的なコメントのキーワードを引用}

⚠️ 否定的な評価（{negative_ratio}%）

• {要点}

💡 ユーザーのニーズ（{demand_ratio}%）

• {要点}

🔍 競合との比較に関する反応（{competitor_ratio}%）

• {競合に言及している場合のみ出力。それ以外は「競合への言及なし」と出力}

分析要件：

• 各要点で代表的なコメントのキーワード／フレーズを引用します
• パーセンテージは各タイプのコメントの割合です。4つのタイプの合計が100%を超える場合があります
• 快手コミュニティの文化を必ず理解します

A4. ページ送りの案内（⚠️ A3 の直後に続けて出力）

• has_next が true の場合：📄 現在 {page} ページ目（合計 {total_fetched} 件）。「次のページ」と返信すると続きを表示します。
• has_next が false の場合：📄 現在 {page} ページ目。これ以上データはありません。

⚠️ A1～A4 は同じ応答内で続けてすべて実行し、いずれも省略してはいけません。

A4 の出力後、HTML ビジュアルレポートを生成するかどうかユーザーに尋ねます。

📊 HTML ビジュアルレポートを生成しますか？

ユーザーが確認した場合は、閲覧済みページ数に応じて方法を選択します。

---

1ページのみ → 単一ページ HTML（backfill_html.py）

HTML ファイルは Step 2 で生成済みです。分析データを入力して開きます。

python3 ~/.agents/skills/kuaishou-comment/scripts/backfill_html.py "<html_path>" --analysis-json '<分析JSON>'
open "<html_path>"

---

2ページ以上 → 統合レポート（consolidate_report.py）

閲覧済みの全ページの JSON データを収集し、すべてのコメントと累積分析を含む完全な HTML を1つ生成します。ページごとに区分して表示し、3ページを超える場合は自動的に折りたたみ、クリックして展開するようユーザーに案内します。

python3 ~/.agents/skills/kuaishou-comment/scripts/consolidate_report.py "<opusId>" \
  --pages-json '[{"page":1,"total":31,"comments":[...]},{"page":2,"total":20,"comments":[...]}]' \
  --analysis-json '<累计分析JSON>'
open "<html_path>"

パラメーター	説明
opusId	快手作品の opusId（位置引数）
--pages-json	複数ページのデータを含む JSON 配列。各項目には page、total、comments が含まれます
--analysis-json	累積分析の JSON（フィールドは backfill と同じ）

pages データは各スクリプト呼び出しの出力から収集します。累積分析は A3 のページ送り後の総合分析に基づきます。

---

分析 JSON フィールドの説明：

フィールド	型	説明
positive_ratio	string	肯定的な評価の割合（数字のみ。例："62"。テンプレートが自動的に % を追加）
negative_ratio	string	否定的な評価の割合
demand_ratio	string	ユーザーニーズの割合
competitor_ratio	string	競合との比較の割合
positive_summary	string	肯定的な評価の要約（HTML ul 形式）
negative_summary	string	否定的な評価の要約
demand_summary	string	ユーザーニーズの要約
competitor_summary	string	競合との比較の要約

Step 4：ページ送りの処理（ユーザーが「次のページ」などと返信した場合）

1. opusId を引き継ぎます
2. 前のページの nextCursor を使用します
3. スクリプトを再度呼び出します：python3 ~/.agents/skills/kuaishou-comment/scripts/kuaishou_comment_search.py "<opusId>" --cursor "<nextCursor>" --page <page>
4. A1～A4 をすべて実行します。A3 は累積データに基づいて総合分析します
5. A4 の後に HTML が必要かどうかを尋ねます

ページ送りのルール： has_next が true の場合は nextCursor を使用してページ送りし、false の場合はそれ以上データがありません。cursor は変更せず、そのまま渡します。

Step 5：エラー処理

エラーの種類	対処方法
API Key がない	REDFOX_API_KEY の設定を案内
作品リンクが無効	「この作品のコメントが見つかりません。作品リンクが正しいか確認してください」と案内
インターフェースがエラーを返す	エラーコードとエラーメッセージを表示
コメントを0件取得	「この作品にはまだコメントがありません」と案内
ネットワークリクエストがタイムアウト	「ネットワークリクエストがタイムアウトしました。しばらくしてからもう一度お試しください」と案内

---

📋 依存関係

スクリプトでは urllib（Python 標準ライブラリ）を使用するため、依存関係を追加でインストールする必要はありません。

---

🎯 使用例

例 1：指定した作品のコメントを表示

用户：查看快手作品 3x4ibfzs5e68yxu 的评论
助手：调用脚本 → 展示当前页 + AI总结 → 询问HTML → backfill → open

例 2：リンクから検索

用户：https://www.kuaishou.com/short-video/3x4ibfzs5e68yxu 这个作品的评论怎么样
助手：提取 opusId → 调用脚本 → 展示分析 → 询问HTML

例 3：ページ送り後に統合してエクスポート

用户：下一页 → 下一页 → 生成html
助手：收集3页JSON → consolidate_report.py → 1个HTML含全部评论+折叠 → open