anycap-human-interaction

AnyCap の人間によるインタラクション

開始する前に、このファイル全体を読んでください。 セクションを飛ばすと、ワークフローが正しく動作しません。メディアの種類ごとに、機能と制約が異なります。

AnyCap の注釈ツールを使用して、人間から構造化された視覚的フィードバックを収集するためのワークフローガイドです。このスキルでは、視覚的な注釈と画面録画を通じて、ワークフローに人間をいつ、どのように関与させるかを説明します。

CLI コマンドのリファレンスについては、anycap-cli スキルをお読みください。メディア生成ワークフローについては、anycap-media-production スキルをお読みください。

前提条件

AnyCap CLI がインストールされ、認証されている必要があります。セットアップが必要な場合は、anycap-cli スキルをお読みください。

2 つの主要なシナリオ

AnyCap の注釈機能は、異なる 2 つのレビュー ワークフローに適しています。状況に合ったものを選んでください。

シナリオ	最適な用途	主な成果物	特徴
URL / Web ページのレビュー	Web ページ、ローカル開発サーバー、ライブ UI	ナレーション付き画面録画	閲覧、注釈、ナレーションを行い、録画にすべてを記録します
画像の共同レビュー	生成画像、スクリーンショット、デザイン	フィードバックを統合した注釈付き画像	複数のレビュアーがリアルタイムで同時に注釈を付けます

どちらのシナリオでも、すべての注釈ツール（Rect、Arrow、Point、Freehand）とテキストラベルを使用できます。異なるのは、得られる成果物とレビューの進め方です。

コマンドのクイックリファレンス

# Blocking -- opens browser, waits for Done click, outputs result
anycap annotate <target> [-o output.png]

# Non-blocking -- starts background server, returns session info
anycap annotate <target> --no-wait [-o output.png]

# Poll for result after human confirms done
anycap annotate poll --session <session_id>

# Stop background server
anycap annotate stop --session <session_id>

# List all active sessions (useful for recovery after context loss)
anycap annotate list

<target> は、コンテンツの種類（画像ファイル、URL（http:// または https://）、動画ファイル、音声ファイル）に基づいて自動検出されます。

主なフラグ

フラグ	説明
--no-wait	非ブロッキングモード（エージェントに推奨）
-o, --output	注釈付き画像をこのパスに保存します
--port <port>	固定ポートにバインドします（デフォルト：ランダム）
--bind <addr>	バインドアドレスを指定します（デフォルト：127.0.0.1）

ヒント： セッション間で一貫した値（例：--port 8888）を --port に指定してください。ブラウザーは各ユーザーの表示名を localStorage に保存します。これはオリジン（ホスト＋ポート）ごとに管理されます。ポートを固定すると、再訪した共同作業者は名前を再入力しなくても自動的に認識されます。

ブラウザーの自動起動

ブロッキングモードと非ブロッキングモードのどちらでも、注釈 URL をデフォルトのブラウザーで自動的に開こうとします。ヘッドレス環境（SSH、コンテナー）では、CLI は代わりに URL を stderr に出力します。エラーは発生しません。

人間に提示する際のガイドライン

人間に注釈セッションを提示する際は、状況に応じてメッセージを調整してください。伝えるべき主な点は次のとおりです。

• ブラウザーの自動起動： デスクトップではページが自動的に開くため、「レビュー ページはすでに開いているはずです」と伝えてください。ヘッドレス環境や SSH では、URL を共有し、アクセス方法を伝えてください。
• Done について必ず伝える： 終了したら Done をクリックするよう伝えてください。これによりフィードバックが保存されます。
• URL モードでの録画： URL モードでは注釈付きスクリーンショットをエクスポートできないため、録画（Rec ボタン）を行うよう強調してください。録画が主な成果物です。
• 複数ユーザー： 複数のレビュアーが参加する場合は、リアルタイムの共同作業が可能で、各自が個別に保存できることを伝えてください。例外：URL/iframe モードはシングルユーザーです（録画が主なフィードバック成果物であり、複数ユーザーのカーソルがあると分かりにくくなるためです）。
• ヘッドレス環境からのアクセス： --bind 0.0.0.0 を使用する場合は、実際のホスト IP アドレスを含む URL を共有してください。SSH 経由の場合は、ポートフォワーディングを提案してください。
• 注釈の付け方： 利用できるツール（Rect、Arrow、Point、Freehand）を簡単に説明し、各注釈にテキストラベルを付けられることを伝えてください。

定型メッセージは使用しないでください。状況（直前に生成または変更した内容、デスクトップ環境かヘッドレス環境か、レビュアーが 1 人か複数か）に合わせて、自然なメッセージを作成してください。

ヘッドレス／リモートアクセス

ヘッドレス環境（SSH、コンテナー、クラウド VM）で実行する場合、人間は 127.0.0.1 に直接アクセスできません。--bind と --port を使用して、注釈サーバーにアクセスできるようにします。

# Bind to all interfaces on a fixed port
anycap annotate screenshot.png --no-wait --bind 0.0.0.0 --port 8888

その後、人間は以下の方法で注釈 UI にアクセスできます。

• 直接アクセス： ポートが公開されている場合は http://<server-ip>:8888
• SSH ポートフォワーディング： ssh -L 8888:localhost:8888 user@host を実行し、http://localhost:8888 を開きます
• コンテナーのポートマッピング： docker run -p 8888:8888 ... を実行し、http://localhost:8888 を開きます
• リバースプロキシ： nginx、Caddy、またはパスプレフィックスに対応した任意のリバースプロキシを介して公開します

ヘッドレス環境では、URL を予測可能にし、ポートフォワーディングできるよう、必ず固定の番号を指定して --port を使用してください。

リバースプロキシとの互換性

注釈 UI は、任意のパスプレフィックスを持つリバースプロキシの背後で動作します。すべてのアセット、API、WebSocket の URL はページの URL を基準に解決されるため、以下のような構成もそのまま動作します。

https://yourserver.com/tools/annotate/  ->  http://localhost:8888/

プロキシがクエリパラメーター（アクセス制御用の ?token=... など）を渡す場合、それらはすべての内部リクエストに自動的に引き継がれます。注釈サーバー側で追加の設定は必要ありません。

注釈を使用する場面

以下の場合は注釈を使用してください。

• 画像／動画を生成し、人間に変更箇所を指し示してもらう必要がある
• Web ページを作成または変更し、人間に視覚的に確認してもらう必要がある
• 空間的な位置に基づくフィードバック（「これをここに移動して」「この領域は間違っています」）が必要である
• テキストだけのフィードバックでは、位置や視覚的な詳細が曖昧になる
• 人間にフィードバックをナレーション付きのウォークスルーとして記録してもらいたい

以下の場合は注釈を使用しないでください。

• はい／いいえの承認だけが必要である（チャットで尋ねてください）
• フィードバックがテキストのみである（例：「タイトルのテキストを X に変更してください」）

インタラクションパターン

すべての注釈ワークフローは、以下のパターンに従います。

sequenceDiagram
    participant Agent
    participant CLI as AnyCap CLI
    participant Human

    Agent->>CLI: anycap annotate <target> --no-wait
    CLI-->>Agent: {session, url, session_file, poll_command, stop_command}
    Agent->>Human: Present URL with guidance
    Human->>Human: Annotate, record, click Done
    Human->>Agent: Confirms done
    Agent->>CLI: poll_command
    CLI-->>Agent: Annotations + recording
    Agent->>Agent: Process feedback
    Agent->>CLI: stop_command

「Done」ボタン

人間が注釈ツールバーの Done をクリックすると、フィードバックが保存されます。動作はモードによって異なります。

• ブロッキングモード（--no-wait なし）：Done をクリックするとセッションが終了します。CLI コマンドは結果を返してすぐに終了します。共同作業モード（画像、動画、音声）では、ほかの接続ユーザーに「Feedback Submitted」オーバーレイが表示されます。
• ノンブロッキングモード（--no-wait）：Done をクリックすると、セッションを終了せずにフィードバックを保存します。共同作業モードでは、ほかのユーザーにトースト通知が表示され、注釈を続けられます。その後 Done をクリックするたびに、保存済みの結果が上書きされます。エージェントは最新の保存状態を取得するためにポーリングします。

エージェント向け： 人間には、作業が終わったら必ず Done をクリックするよう伝えてください。複数のレビュアーがいるノンブロッキングモード（画像／動画／音声のみ）では、各レビュアーが個別に保存できます。ポーリング結果には、最も新しい保存内容が反映されます。

セッションの復旧

セッション状態は、作業ディレクトリ内の .anycap/annotate/<session_id>.json に保存されます（開始レスポンスでは session_file として返されます）。コンテキストがリセットされ、セッション ID やコマンドが失われた場合：

# List all sessions with their status and recovery commands
anycap annotate list

list の出力には各セッションの poll_command と stop_command が含まれるため、セッションファイルを手動で読み取らずに再開できます。

---

シナリオ 1：URL／ウェブページのレビュー

ウェブページ、UI、またはブラウザーからアクセスできるコンテンツを作成または変更し、人間に視覚的なレビューを依頼する場合に使用します。

URL モードは単一ユーザー用です。 録画が主なフィードバック成果物です（クロスオリジンの iframe により、注釈付きスクリーンショットをエクスポートできません）。複数のユーザーのカーソルや注釈があると、録画が分かりにくくなります。クライアント名タグと参加者インジケーターは非表示になります。URL セッションをレビューする人は、一度に 1 人にしてください。

録画が重要な理由： 画像モードとは異なり、URL モードでは注釈付きスクリーンショットをエクスポートできません（クロスオリジン iframe の制約）。ナレーション付き画面録画が主なフィードバック成果物です。人間は注釈フレーム内でページを閲覧し、上から注釈を書き込み、ナレーション付きのウォークスルーを録画します。これにより、視覚的な書き込みと、相手が見たものや話した内容を正確に記録した動画の両方を受け取れます。

セッションを開始する

# Local dev server
anycap annotate http://localhost:3000 --no-wait

# Live URL
anycap annotate https://staging.example.com --no-wait

フィードバックを収集して分析する

# Poll for result
anycap annotate poll --session <session_id>

# Check if recording exists
RECORDING=$(anycap annotate poll --session <session_id> | jq -r '.recording // empty')

# Analyze the recording with AI video understanding
if [ -n "$RECORDING" ]; then
  anycap actions video-read --file "$RECORDING" \
    --instruction "List all issues the user pointed out. For each issue, describe what they are looking at, what is wrong, and what they want changed. Include timestamps."
fi

# Also read text annotations
anycap annotate poll --session <session_id> \
  | jq -r '.annotations[] | "#\(.id) [\(.type)]: \(.label)"'

# Clean up
anycap annotate stop --session <session_id>

録画が空の場合があります。 Rec ボタンはブラウザーの getDisplayMedia API を使用します。この API では、ユーザーが画面共有の許可を与える必要があります。ユーザーが許可を求めるプロンプトを拒否した場合や、Rec をクリックしなかった場合、ポーリング結果に recording フィールドは含まれません。動画の読み取りを試みる前に、必ずこのフィールドが存在するか確認してください。テキスト注釈は引き続き利用できます。

URL のフィードバックを適用する -- 反復レビュー

URL のレビューで得られるフィードバックは通常、画像生成ではなくコードの変更につながります。録画と注釈を分析した後は、次の手順に従います。

1. 視覚的なフィードバックに基づいて、変更が必要なファイルを特定します
2. コードを変更します
3. 前のセッションを停止します
4. 人間が確認するための新しい注釈セッションを開始します

URL のコンテンツが変更されているため、変更の各ラウンドでは新しいセッションが必要です。

# Round 1: Initial review
anycap annotate http://localhost:3000 --no-wait
# ... human reviews, you poll and analyze ...
anycap annotate stop --session <session_1>

# Apply code changes based on feedback
# ... edit files ...

# Round 2: Verification review
anycap annotate http://localhost:3000 --no-wait
# ... human confirms or gives more feedback ...
anycap annotate stop --session <session_2>

人間が進捗を把握できるよう、メッセージにラウンド番号を付けてください（「ラウンド 2：最初のレビューで指摘された問題 #1 と #3 に対応しました」）。

録画の分析パターン

録画は、注釈の書き込みと音声ナレーションを含む、ブラウザータブからキャプチャされた .webm 動画です。anycap actions video-read を使って分析します。

# General feedback extraction
anycap actions video-read --file <recording_path> \
  --instruction "List all issues and desired changes the user described"

# UI-specific review
anycap actions video-read --file <recording_path> \
  --instruction "For each UI element the user points at, describe the current state and the desired change"

# Prioritized feedback
anycap actions video-read --file <recording_path> \
  --instruction "Categorize the user's feedback by priority (critical, important, nice-to-have)"

---

シナリオ 2：画像の共同レビュー

画像を生成し、人間に変更したい箇所をマークしてもらう場合に使用します。このシナリオは、リアルタイムの複数ユーザーによる共同作業に最適です。複数のレビュー担当者が同じ URL を開いて同時に注釈を付け、互いのカーソルや描画をリアルタイムで確認できます。

注： 複数ユーザーによる共同作業は、画像、動画、音声の各モードで利用できます。URL／iframe モードは単一ユーザー用です。

画像から画像への完全な反復改善ワークフロー（生成 -> 注釈 -> 編集 -> 反復）については、anycap-media-production スキルをお読みください。

セッションを開始する

# Single reviewer
anycap annotate hero-banner.png --no-wait -o hero-banner-annotated.png

# Multi-user review -- bind to network so teammates can join
anycap annotate hero-banner.png --no-wait -o hero-banner-annotated.png \
  --bind 0.0.0.0 --port 8888

フィードバックを収集して活用する

# Poll for result
anycap annotate poll --session <session_id>

# Extract annotation labels for image-to-image prompt
anycap annotate poll --session <session_id> \
  | jq -r '[.annotations[] | select(.label != "") | "#\(.id): \(.label)"] | join(". ")'

# Apply changes via image-to-image
anycap image generate \
  --prompt "<annotations as prompt>. Keep all other elements unchanged." \
  --model <model-id> \
  --mode image-to-image \
  --param images=./hero-banner-annotated.png \
  -o hero-banner-v2.png

# Clean up
anycap annotate stop --session <session_id>

---

その他のメディア形式

動画レビュー

動画を生成した場合や、人間に動画コンテンツをレビューしてもらう場合に使用します。人間は動画を任意のフレームで一時停止して、注釈を付けることができます。注釈付き画像の出力は、一時停止したフレームにすべての注釈を合成したスナップショットです。

開始

anycap annotate output.mp4 --no-wait

人間に、重要な場面で動画を一時停止し、フレームに注釈を描き、必要に応じてナレーション付きで録画し、完了したら Done をクリックするよう伝えます。

収集して分析する

# Poll for result
anycap annotate poll --session <session_id>

# The annotated_image is a snapshot of the paused frame with annotations
# Read the annotations for spatial feedback on that frame
anycap annotate poll --session <session_id> \
  | jq -r '.annotations[] | "#\(.id) [\(.type)]: \(.label)"'

# If recording exists, analyze it for time-specific feedback
RECORDING=$(anycap annotate poll --session <session_id> | jq -r '.recording // empty')
if [ -n "$RECORDING" ]; then
  anycap actions video-read --file "$RECORDING" \
    --instruction "What feedback did the user give about the video? For each issue, note the timestamp in the original video, what is wrong, and what they want changed."
fi

# Clean up
anycap annotate stop --session <session_id>

動画のフィードバックは通常、プロンプトを調整して再生成するか、モデルが対応している場合は特定のフレームを編集することにつながります。

音声レビュー

音楽や音声を生成し、人間からフィードバックを得る場合に使用します。人間には、下部に描画キャンバスがあるオーディオプレーヤーが表示されます。

開始

anycap annotate track.mp3 --no-wait

人間に、音声を再生し、時間範囲やセクションを示すためにキャンバスに注釈を描き、希望する変更を説明するラベルを追加して、完了したら Done をクリックするよう伝えます。

収集して分析する

# Poll for result
anycap annotate poll --session <session_id>

# Read annotation labels -- these describe desired audio changes
anycap annotate poll --session <session_id> \
  | jq -r '.annotations[] | "#\(.id) [\(.type)]: \(.label)"'

# If recording exists, analyze the narrated feedback
RECORDING=$(anycap annotate poll --session <session_id> | jq -r '.recording // empty')
if [ -n "$RECORDING" ]; then
  anycap actions video-read --file "$RECORDING" \
    --instruction "What audio changes did the user request? Note any specific time ranges or sections they mentioned."
fi

# Clean up
anycap annotate stop --session <session_id>

音声のフィードバックは通常、空間的な編集ではなく、プロンプトを調整して再生成することにつながります。

---

反復レビューのループ

複雑なタスクでは、反復して進めます。

graph TD
    A[Agent produces work] --> B[Start annotation session]
    B --> C[Human reviews and annotates]
    C --> D[Agent collects feedback]
    D --> E[Agent applies changes]
    E --> F{More changes needed?}
    F -->|Yes| B
    F -->|No| G[Deliver final result]

反復のヒント：

• 出力にバージョンを付けます（v1、v2、v3）。人間が比較できるようになります
• 変更内容で前回のフィードバックに言及します（「前回のレビューの #1 に対応しました：…」）
• 2～3回繰り返した後、見落としがないことを確認するため、変更内容をすべてまとめます

適切なシナリオの選び方

状況	シナリオ	理由
ウェブページを作成・変更した	URL レビュー（シングルユーザー）	録画にブラウジング、スクロール、音声によるフィードバックが記録されます
ローカルの開発サーバーをレビューする必要がある	URL レビュー（シングルユーザー）	上記と同じです。http://localhost:PORT を使用します
生成した画像を編集する必要がある	画像レビュー	注釈付き画像をそのまま画像から画像への編集に使用できます
チームでデザインをレビューする必要がある	画像レビュー（マルチユーザー）	全員が一緒に注釈を付けられ、フィードバックを一か所にまとめられます
ステークホルダーとデザインを批評する	画像レビュー（マルチユーザー）	リアルタイムのカーソルと注釈により、全員の認識をそろえられます
生成した動画にフィードバックが必要	動画レビュー	重要な場面で一時停止し、特定のフレームに注釈を付けられます
音楽／音声にフィードバックが必要	音声レビュー	キャンバスに注釈を付けて時間範囲を示せます
図を作成・反復する必要がある	代わりに anycap draw を使用	Mermaid 入力に対応したインタラクティブなホワイトボードで、エージェントが更新を反映できます
アーキテクチャ図に人間の入力が必要	代わりに anycap draw を使用	リアルタイム同期に対応した、共同編集可能な Excalidraw エディターです