blurt

blurt 🐔 — 見せて、話して、構造化された作業結果を受け取る

人は画面を見ながら声に出すと、考えが最もまとまります。話題を行き来し、自分の発言を訂正し、ものを指し示します。あなたの仕事は、手間をかけずにそれを記録し、面倒な作業（分割、文書化、スクリーンショットの選択とマーキング、コードの検索、ファイリング）を丁寧に行うことです。ユーザーの流れを優先してください。録音を中断せず、質問は最小限にし、すばやく確認できるようにします。

スクリプトはこのファイルの隣にある scripts/ にあります。uv run <skill-dir>/scripts/<name>.py ... で実行してください（各スクリプトで依存関係が宣言されており、初回実行時に uv がインストールします）。すべてのスクリプトに --help があります。必ずユーザーの言語で返信し、項目はユーザーが話した言語で記述してください。

0. セットアップ（初回実行時、または問題が発生したとき）

• doctor.py → OS、RAM/GPU、ffmpeg、設定済みのASR、おすすめ、todo リストを表示します。
• ffmpeg/uv がない場合：インストールコマンドを提示し、ユーザーが同意してから実行します。
• ASR：設定されていない場合は、asr_recommendations とユーザーが話す言語をもとに選び、何を選んだか、またその理由（サイズ、ローカルかクラウドか、費用）を1行で伝えてから、setup を実行します。詳細：reference/asr.md。クラウドのキーはユーザーが自分の環境に設定します。チャットでキーを貼り付けるよう求めてはいけません。
• record.py build — macOS：ネイティブレコーダーをコンパイル（Xcode Command Line Tools を使用。ない場合は Tk フォールバック）し、メニューバーアプリ Blurt を ~/Applications にインストールします。Windows：初回録音時にスタートメニューのショートカットが表示されます。次のように1行で伝えてください：「Blurt はアプリケーションにもあります — ⌥⇧R でどこからでも録音できます」。
• record.py test → 返された frame を自分で確認します。壁紙のみ／黒画面、または ok: false の場合 ⇒ 画面収録の権限がありません。mic_silent: true の場合 ⇒ マイクの権限がないか、マイクが正しくありません。macOS では、権限は使用中のアプリ（Terminal、iTerm、VS Code、Claude、Codex…）に付与されます。許可した後は、そのアプリを再起動する必要があります。macOS 15 以降では「ウィンドウピッカーをバイパスすることを許可…」というプロンプトが表示される場合があります。ユーザー自身が「許可」をクリックします。
• 任意のプロジェクト設定 .blurt/config.json：エクスポート先、オーナー／モジュールの対応表、カラムのマッピング、.blurt/lenses/ にあるカスタムレンズ。.blurt/sessions/ を .gitignore に追加するよう提案してください。

1. 録画する（または録画を取り込む）

**チャットから：**確認する対象がこのリポジトリ内のローカル開発サーバー／アプリの場合は、起動していることを確認してください。 record.py start を バックグラウンドで開始し（最後に使った範囲を再利用するには --last-region）、次の内容を数行でユーザーに説明します。

• 暗くなったオーバーレイが表示されます。ドラッグして範囲を描画（またはウィンドウをクリック、全画面は F）し、録画開始／Enter を押します。録画されるのはその範囲だけです。タブ、ブックマーク、その他のウィンドウは見られません。
• 3-2-1 のカウントダウン（クリックでスキップ）の後、小さなフローティングバーが表示されます。タイマー · マイクレベル · ⏸ 一時停止 · ↺ 再開／破棄 · 完了。⌥⇧P で一時停止／再開、⌥⇧S で終了（Windows：Alt+Shift）。このバーが録画に映ることはありません。
• 自然に話し、マウスで指し示してください。⌃を押しながらドラッグすると、意図している箇所を丸で囲む／下線を引けます（macOS。インクは3秒後に消えます。バーの✎または⌥⇧Dでペンをオンのままにでき、Esc／⌥⇧D／✎でオフにできます）。完了をクリックします。チャットで別のメッセージを送る必要はありません。

タスクが DONE video=… で終了したら、すぐに§2へ進みます（CANCELLED、終了コード2の場合は、確認して停止します）。チャットから record.py stop | pause | resume | restart を実行することもできます。

バックグラウンド処理の完了を待つ場合（ここおよび§5）：バックグラウンドタスクの完了時にハーネスから通知される場合（Claude Code）は、ターンを終了してください。通知が届きます。通知されない場合（Codex）、子プロセスの終了後に完了したターンを再開することはできません。ターンを開いたまま、同じツールセッションで長いポーリングを行って待ちます（ビジーループはしないでください）。処理の実行中に最終応答を送ってはいけません。

既存の動画（QuickTime、OBS、Loom、スマートフォン、チームメイトが録画したBlurtの録画など）：.blurt/sessions/<timestamp>/ を作成し、動画を recording.<ext> としてコピーします（Blurtからの録画の場合は events.jsonl／meta.json もコピーします）。§2へ進みます。

**Blurtアプリでの録画：**メニューバーアプリは現在のワークスペースに録画します。デフォルトでは ~/Blurt/recordings/<ts>/、プロジェクトが紐付けられている場合は <project>/.blurt/sessions/<ts>/ に保存されます。record.py inbox は、すべての録画を processed／reviewed フラグ付きで一覧表示します。「録画を処理して」という指示には、未処理の録画それぞれについて§2～§4を実行し（利用可能であればサブエージェントに処理を分担し）、その後、セッションごとに1回レビューします（ユーザーが1つのリストを希望する場合は、1つのセッションディレクトリにまとめます）。複数の人の録画をまとめる場合は、meta.json の author を各項目に保持します。

2. 文字起こし

transcribe.py run <session>/recording.mp4 → transcript.json + transcript.txt（[mm:ss.s-mm:ss.s] text）。 システム音声付きで録画した場合（record.py start --system-audio、またはアプリのメニュー切り替え。通話、製品デモなど）、相手側の発言には (system)／speaker: "system" のマークが付きます。マークのない発言はユーザーのものです。音声が混ざると、システム側の発言がマイクにも重複して記録されることがあります。 Whisper／APIバックエンドでは、リポジトリから取得した短い用語集（製品名、ページ／モジュール名、人名）を --prompt で渡します。 また、frames.py scan <video>（候補／シート用の視覚的な動きのインデックス）と frames.py marks <video> も実行します。これは、ユーザーがペンで描いた内容（時刻、位置（ボックス）、そのときの発言）に加え、⌥⇧Mのマーカーを表示します。 出力に warning がある場合や、文字起こしの内容が意味をなさない場合（SenseVoiceはフランス語などの未対応言語を、実際には存在しない英語に変換します）は、別のバックエンドが必要です。セットアップ（reference/asr.md）して、再実行してください。

3. 理解 → 項目

まずトランスクリプト全体を読み、いくつかのフレームに目を通してから、<session>/items.json を作成します （スキーマ：reference/schema.md）。項目ごとに、それが何かを判断してください。モード切り替えではなく、録画内容を基準にします。

種類	該当する場合	観点
issue	プロダクト内で修正または磨き込みが必要なもの	reference/lenses/issue.md
idea	構築・変更・参考にするもの（「这个网站的这里好」）	reference/lenses/idea.md
note	残しておく価値のある観察・発見・事実	reference/lenses/note.md
task	プロダクトの課題ではないアクションアイテム	reference/lenses/task.md
custom	.blurt/lenses/ または ~/.blurt/lenses/ に適合するレンズがある場合、またはユーザーが指定した場合	そのファイル

原則 — ルールではなく、判断の指針です。

• ペンの書き込みは、ユーザーが「まさにこれ」と示したものです。項目の時刻と対象を特定する手がかりになります。ユーザーが丸で囲んだ箇所は、曖昧な発言についてのあなたの解釈より優先されます。ただし、書き込み自体が項目になるわけではなく、書き込みのない項目も通常どおりあります。
• 1項目につき、1つの内容にします。人は話題を行き来し、前の話に戻り、言い直し（「不对，是…」）をしたり、1つの文で2つのことを言ったりします。再訪した話題は統合し、撤回された発言は除き、複合した内容は分けます。単なる状況説明は項目にしません。
• 文脈（リポジトリ内の用語、画面に表示されている内容）から ASR の誤りを修正します。quote は実際の発言に近い状態を保ちます。
• 作り上げないでください。確信が持てない場合は、最善の推測を記述し、confidence: "low" を設定して、短い questions エントリを追加します。
• URL やプロダクト名は、フレームから読み取って source に記録します。
• code_refs（リポジトリ内の issue の場合）：画面上のテキスト／ルート／コンポーネントを grep し、該当する可能性の高い path:line を列挙します。
• セッションに title を付けます。アイデア中心または探索的な録画では、digest（markdown）を記述します。テーマ、最も有力なアイデア、それらのつながり、次の推奨ステップをまとめます。これはレビュー画面の概要になります。

4. エビデンス：フレームとクリップ

各項目について、要点（バグそのもの、アイデアのきっかけになったページの箇所）を示すフレームを1～3枚選びます。

• frames.py sheet <video> --from S --to E -o <session>/sheets/<id>.jpg → 時刻付きの、落ち着いた状態の候補フレームを約6枚、1つの画像にまとめます。特定の瞬間（「ここ／this／look」）の場合は --at t1 t2 … を使います。発話は操作より遅れることがよくあります。
• ユーザーが書き込んだ（marks）場合：動画内にそのインク跡があります。frames.py grab --at <frame_t> を実行すると、注釈付きのフレームが取得されます。ボックスは追加しないでください。拡大した2枚目のフレームには --crop stroke を使い、インクが消えたフレームでは --box stroke を使います。
• それ以外の場合、位置を示すときは、サムネイルやコンタクトシートから座標を推測しないでください。
  1. frames.py grid <video> --at T -o <session>/sheets/<id>-grid.jpg → 記録されたカーソルと近くのクリック（events.jsonl — 正確です）を含む、0～1のラベル付きグリッドを生成します。グリッドからボックスの端を読み取ります（--crop で拡大できますが、ラベルはフレーム全体のままです）。
  2. frames.py grab <video> --at T -o <session>/frames/<id>-1.jpg --box x,y,w,h。ユーザーが指し示した箇所やクリックした箇所には --ring cursor|click を使います。細部が小さい場合は、--crop を使って2枚目のフレームを取得します。
  3. 注釈付きのフレームは、使用する前にすべて確認してください。 ボックスが要点を捉えていない場合は、修正して再取得します。
• アニメーション／操作の流れ／タイミング：frames.py clip --from --to -o <session>/clips/<id>.mp4（< 20 MB）。
• 項目が多い場合（約12件超）：利用可能なハーネスでサブエージェントを使えるなら、フレーム作業を複数のバッチに分けます。

5. ユーザーとレビューする

必ずレビュー画面を開いてください。フレームが重要です。review.py <session> をバックグラウンドで実行します（ブラウザーが開き、ユーザーが完了すると終了します）。REVIEW <url> が出力されます。実行環境（SSH、コンテナー）でブラウザーを開けない場合は、その URL をユーザーに伝えてください。同じメッセージで、次の内容も伝えます。

• 5 件以下の場合：完全な番号付きリスト（種類・タイトル・担当者／モジュール、および questions）。それより多い場合：短い要約（種類ごとの件数、主要な項目、未解決の質問）。
• 画面上の操作方法を 2 行で説明します。項目を 1 つずつ確認し、A で保持、X で削除、J/K で次／前、Z で取り消し、? でキーを確認できます。フィールドはその場で編集できます。G でリスト表示、ダイジェストがある場合は V で概要を表示できます。「完成审核」を押すとこちらに戻ります。

ユーザーはチャットまたは画面上で回答できます。レビューの要約が出力されるまで §1 の手順に従って待ちます。その後、§6 に進むため items.json を再読み込みします（削除された項目の status は "deleted"、回答は answer に記録され、統合された項目は意図的に削除されており、対象項目の merged_from に記載されています）。代わりにチャットで返信があった場合は、自分で反映してページを閉じます（pkill -f "review.py <session>"）。

無人実行（Blurt アプリが claude -p／codex exec（環境変数 BLURT_APP=1）で開始した場合、またはその他の非対話モードで実行する場合）：何も質問せず、§2〜§4 を実行して items.json を書き込み、2〜3 文の要約で終了します。BLURT_APP=1 の場合はレビュー画面を起動しないでください。終了時にアプリが開きます。それ以外の場合は、切り離して起動します（nohup uv run …/review.py <session> >/dev/null 2>&1 &）。無人実行中は外部システムにエクスポートしないでください。

6. エクスポート／対応する

保存先を一度確認します（.blurt/config.json の export に保存します）。一般的な保存先：課題 → チームのバグ管理表、アイデア → アイデアボード／ドキュメント、メモ → Markdown、タスク → ユーザーの ToDo ツール。

• Feishu／Lark Bitable → feishu.py export <session> "<table url>" [--kind issue|idea|…]（lark-cli がインストールされていれば使用し、なければアプリの認証情報を使用します。種類ごとの既定列を設定し、不足している列を作成し、フレームとクリップをアップロードします。再開可能です）。 テーブルがまだない場合 → feishu.py create "<name>"。別の列を使う場合 → feishu.py fields を実行してから --map を指定します。 詳細：reference/export-feishu.md。
• Markdown ＋ CSV → export_local.py <session>（すべての種類に対応し、ローカル記録としていつでも便利です）。
• GitHub Issues／Linear／Jira／Notion／Obsidian／その他 → reference/export-other.md を参照し、ユーザーが利用している CLI または MCP ツールを使います。フィールドは意味に基づいて対応付けます。
• リストではなくドキュメントにまとめる場合（「整理成需求文档和设计文档」、ブリーフ、比較など。通常は参考サイトや競合を確認した後、複数の録画にまたがって作成します）→ reference/docs.md。

リモートで作成する前に保存先と件数を確認し、作成後にリンクを報告します。その後、自然な次のステップを提案します。課題の場合は「これらの修正を始めましょうか？」（code_refs があります）、アイデアの場合は「一番のアイデアの簡単なプロトタイプ／仕様を作りましょうか？」と聞きます。