wjs-mining-voicedrop

wjs-mining-voicedrop

VoiceDrop の受信トレイ（jianshuo.dev/files 上の VoiceDrop-*.m4a）→ 1件ずつ文字起こし → wjs-mining-articles に渡して公式アカウントの下書きを作成します。これは VoiceDrop iOS app（話し始めるだけで録音、止めるとすぐアップロード）の Mac 側の一連のワークフローです。

このスキル自体の成果物 = ① 公式アカウントの下書き（~/code/wechat-publish/）+ ② ローカルの音声/SRT アーカイブ（~/code/voicedrop/archive/）+ ③ R2 上の処理マーカー（articles/<stem>.json または .empty）+ ④ バッチレポート（処理した件数、作成した記事数、音声なしとしてマークしたファイルとその理由、未処理の残り件数）。 インターフェース契約の全文は agents/interface.yaml を参照してください。

基本原則

再利用し、書き直さない。 このスキルで新たに行うのは、受信トレイへの出入り（一覧表示/ダウンロード/マーク）と1件ずつのオーケストレーションの2つだけです。文字起こしは wjs-transcribing-audio に、記事の作成は wjs-mining-articles に任せ、1行も書き直しません。

R2 からは絶対に削除せず、マーカーファイルで処理状態を示します。 音声はユーザー自身が app で削除するまで R2 に残ります。「未処理」とは、articles/<stem>.json（記事作成済み）も articles/<stem>.empty（音声なし）のマーカーもない VoiceDrop-*.m4a のことです。list は未処理のファイルだけを自動で一覧表示します。記事作成に成功したら mark-done、音声なし/破損の場合は mark-empty を書き込みます。どちらも、そのファイルが再処理されないようにします。絶対に delete しないでください（delete はユーザーが app で手動で整理する場合に限ります）。

このスキルが実行される場合

• ユーザーが「VoiceDrop の録音を処理して」「新しい録音を記事にして」「自分の口述を処理して」などと言った場合
• ユーザーが /wjs-mining-voicedrop を実行した場合

使用しない場合

• すでに SRT がある → 直接 wjs-mining-articles を使います
• 音声が R2 の受信トレイにない（ローカルに散在するファイル）→ 直接 wjs-transcribing-audio で SRT を作成し、その後 wjs-mining-articles を使います
• バケット内に別のマシンからアップロードされた録音以外のファイルがある → このスキルが対象とするのは VoiceDrop-*.m4a プレフィックスのファイルだけです。それ以外には触れません

前提条件

• ~/code/.env に FILES_TOKEN（受信トレイの認証情報）と Volcano ASR の認証情報（VOLC_ASR_* / VOLC_TTS_*、文字起こし用）が設定されていること。set -a; source ~/code/.env; set +a。

ワークフロー

新たに追加するコードは scripts/voicedrop-inbox.sh（list / download / mark-done / mark-empty / delete）だけです。トークンは実行時に ~/code/.env から読み込み、コード内には絶対に保存しません。list は未処理のファイルだけを一覧表示し、mark-done/mark-empty は処理マーカーを書き込みます。delete は手動での整理に限って使い、記事作成のフローでは呼び出しません。

Step 0 · スクリプトの場所を特定 + 環境を読み込み（現在のディレクトリに依存しない）

INBOX=~/.claude/skills/wjs-mining-voicedrop/scripts/voicedrop-inbox.sh
set -a; source ~/code/.env; set +a    # FILES_TOKEN + 火山 ASR creds

絶対パスの $INBOX を使ってスクリプトを呼び出してください。scripts/voicedrop-inbox.sh と書かないでください。 これは「実行者がたまたまスキルのルートディレクトリにいる」という隠れた前提に依存しており、ディレクトリを移動すると失敗します。

Step 1 · 受信トレイを一覧表示

"$INBOX" list      # 打印未处理的 VoiceDrop-*.m4a，一行一个

• コマンドがゼロ以外の終了コードを返した場合（ネットワークに接続できない / トークンが無効）→「受信トレイに接続できないか、FILES_TOKEN が無効です。~/code/.env を確認してください」と報告して終了し、ループには入りません。
• 出力が空の場合 →「新しい録音はありません」と報告して終了します。
• 空でない場合 → 今回のファイル名一覧を取得します。

Step 2 · 1件ずつ一連の処理を実行（直列で、1件を完了してから次へ）

直列で処理します。 バッチの堅牢性：1件でもどのステップかで失敗したら、原因を記録して次のファイルに進み、バッチ全体を中断せず、マーク漏れも絶対に起こしません。 各録音は最終的に必ず次の3つの状態のいずれかになります。記事作成済み（mark-done）/ 音声なし（mark-empty）/ 失敗（マークせず、次回に残す）。つまり「処理したのに何もマークしない」状態には絶対になりません。各 <name> について：

1. ダウンロードしてアーカイブ：

   "$INBOX" download <name> ~/code/voicedrop/archive
   

   音声は ~/code/voicedrop/archive/<name> に保存します。R2 上のオリジナルは常に残し、ローカルのファイルはオフライン用のコピーとします。
2. 本当に録音かどうかを手早く確認：

   dur=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$audio" 2>/dev/null)
   

   dur が空（音声でない/破損）→ "$INBOX" mark-empty <name> corrupt；< 1.0 秒（誤アップロード/無音）→ "$INBOX" mark-empty <name> silent。マークしたらユーザーに報告し、次のファイルに進みます。このファイルは処理完了状態となり、再処理されません。
3. 文字起こし → SRT：wjs-transcribing-audio を読み込みます（中国語は Volcano 豆包の volc_asr_stream.py + build_srt_from_asr.py を使い、session 内で AI による推敲と誤字修正を行います）。SRT は ~/code/voicedrop/archive/<stem>.srt に保存します。
   • 文字起こし結果が空（音声はあるが ASR が1文字も出力しない。環境音が原因であることが多い）→ "$INBOX" mark-empty <name> no-speech を実行し、報告して次のファイルに進みます。
4. 記事を作成：この SRT を wjs-mining-articles に渡し、完全なワークフローを実行します。トピック候補リストを作成し（人間による確認ゲートです。必ず実行し、スキップしないでください）、記事を作成して、WeChat の下書きを作成します。音声メモは短い独白で、テーマが1つだけのことが多いため、リストが1件だけでも、通常どおりユーザーに確認してもらいます。
5. 記事の作成に成功したら処理マーカーを書き込む（下書きが1件以上作成され、ユーザーが中止していない場合）：このファイルから作成した記事をまとめて v2 JSON（{"schema":2,"status":"ready","sourceAudio":"<name>","articles":[{"title","body"},…]}。transcript/srt を含めても構いません）にし、一時ファイルに書き込んでから、次を実行します。

   "$INBOX" mark-done <name> /tmp/<stem>.json
   

   このファイルは記事作成済みとしてマークされ、app でも確認できるようになり、サーバーや次回の実行で再処理されなくなります。 文字起こしの失敗 / ユーザーがトピック候補を1つも選択しない / 記事を作成できない場合 → done も empty もマークせず未処理のままにし、次回に回します。理由を報告してください。

Step 3 · 結果を報告

処理した件数、作成した下書きの数（~/code/wechat-publish/ に保存）、音声なしとしてマークしたファイルとその理由（corrupt/silent/no-speech）、ローカルのアーカイブパス、R2 に残っている未処理のファイル数を報告します。

マーク付けに関する絶対ルール

download(存档) → 判别 → 成文 ? mark-done : 无语音 ? mark-empty : 留着不标
                                                     ↑ 绝不 delete

• 絶対に delete しないでください。 音声は常に R2 に残します。削除は、ユーザーが app で手動操作する場合に限ります。
• 各ファイルには必ず最終状態を設定します。 記事作成済み → mark-done；破損/無音/音声なし → mark-empty（reason を指定）；実際の失敗（文字起こしエラー、ユーザーによる中止、記事を作成できなかった）→ マークせず、未処理のまま次回に再試行します。「一度処理したのにマーカーを何も残さない」状態は絶対に作らないでください。 そうなると、そのファイルが毎回再処理されます。

再利用する範囲

再利用するもの	用途
wjs-transcribing-audio	音声1件ごとに → SRT（中国語は Volcano 豆包、推敲と誤字修正を含む）
wjs-mining-articles	SRT ごとに → トピック候補リスト → 記事作成 → WeChat の下書き（独自の人間による確認ゲートを含む）
~/code/.env	FILES_TOKEN + Volcano ASR の認証情報
VoiceDrop app	上流：ファイル名は VoiceDrop-<时间戳>-<时长>-<星期>-<时段>[-<城市-城区>].m4a の形式です（すべて ASCII）。このスキルは VoiceDrop- プレフィックスと .m4a サフィックスで対象を判断します。ファイル名の途中に含まれる時間、曜日、時間帯、場所は文脈情報です。記事の作成時に、その録音がいつどこで行われた口述か判断するために利用できます
サーバーの miner（~/code/voicedrop/mining/mine.py、2時間ごと）	同じマーカー規約を使います。記事作成済みは articles/<stem>.json、音声なしは articles/<stem>.empty に書き込み、音声は決して削除しません。受信トレイを自動処理するため、このスキルの実行時に list がすでに空になっていることはよくあります。これは想定どおりです。このスキルは手動処理で補完します

このスキルで新たに追加するコードは次の1つだけです：scripts/voicedrop-inbox.sh。

Common Mistakes

• delete 音频 —— 红线。成文流程永不 delete，只 mark-done/mark-empty；delete 仅用户在 app 里手动用。
• 跑过一条却不标记 —— 无语音/损坏的也要 mark-empty，否则它每次都被重新下载转写，永远「待处理」。
• 转写失败/用户没勾选也硬标 done —— 真失败就留未处理（不标），下次再试；只有出了草稿才 mark-done。
• 跳过 wjs-mining-articles 的选题闸自己硬写 —— 那个闸是它的设计，照走。
• 把桶里非 VoiceDrop 文件也当源 —— 只认 VoiceDrop-*.m4a 前缀；list 也只列未处理的。
• 误传/0 秒/环境音当真录音反复试 —— 先 ffprobe 看时长，空/损坏/<1s 直接 mark-empty，别送去转写。