1仕組みと動作原理
本スキルが存在する前提は、「別の問題に見える」3つの落とし穴を解消することにあります。具体的には、誤ったエンドポイントによる誤解を招くエラー、Planキーによるサイレント失敗、SSEストリーム内で送られるerrorイベントです。
daymade-audio/stepfun-asr/SKILL.md
1. **Wrong endpoint, wrong error**. `stepaudio-2.5-asr` does **not** live on `/v1/audio/transcriptions` (that endpoint serves the older `step-asr` family). It lives on `/v1/audio/asr/sse` — SSE streaming, JSON body, base64 audio.
ここでの処理内容：「model stepaudio-2.5-asr not supported」のような「モデルが存在しない」と同型の誤認エラーをエンドポイントの誤りとして正しく再定義し、ユーザーが無駄にホワイトリスト申請チケットを発行する手間を回避します。スクリプトが正しいエンドポイントとリクエストボディをカプセル化しているため、呼び出し側が再度躓くことはありません。
単一ファイルスクリプトによる正確なリクエストのカプセル化：音声ファイルの読み込み→base64エンコード→ネストされたJSONボディの構築→SSEエンドポイントへのPOSTを実行し、Authorization Bearerは環境変数または設定から取得します。
daymade-audio/stepfun-asr/scripts/asr_transcribe.py
audio_b64 = base64.b64encode(audio_path.read_bytes()).decode("ascii") body = json.dumps({"audio": {"data": audio_b64, "input": {"transcription": {"language": language, "model": MODEL, "enable_itn": enable_itn}, "format": {"type": audio_format}}}}).encode()
ASR_URL = "https://api.stepfun.com/v1/audio/asr/sse"、MODEL = "stepaudio-2.5-asr"。サードパーティ依存関係なしのurllib標準ライブラリ実装で、長時間音声に対応したtimeout=1200（20分）を設定しています。
SSEパースの規約：非ストリーミングへのバッファリングを行わず、deltaを収集し、transcript.text.doneのtextを信頼できる全文およびusageのソースとし、errorイベントを明示的に処理します。
daymade-audio/stepfun-asr/scripts/asr_transcribe.py
if t == "transcript.text.delta": deltas += 1 elif t == "transcript.text.done": text = ev.get("text", "") usage = ev.get("usage")
SKILL.md Design invariantsの条項に準拠：「**Take final text from `transcript.text.done.text`** — concatenated deltas can drift on edge cases.（最終テキストはtranscript.text.done.textから取得すること。deltaの連結はエッジケースでズレが生じる可能性があります）」および「Always pass through SSE」に従い、deltaは進捗表示UIのみに使用し、連結によるドリフトを防ぎます。
APIキーのFail-fast解決：$STEPFUN_API_KEYを最優先し、次に${CLAUDE_PLUGIN_DATA}/config.jsonのapi_keyを参照します。欠落時はプレースホルダーを使用せず即座にエラー終了します。
daymade-audio/stepfun-asr/scripts/asr_transcribe.py
k = os.environ.get("STEPFUN_API_KEY", "").strip() if k: return k plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA", "").strip() if plugin_data: cfg = Path(plugin_data) / "config.json"
SKILL.mdではPlanキーではなくNormalキーの使用を明記しています（Planサブスクリプションキーは音声エンドポイントを呼び出せず、認証エラーの形式も取らずに失敗します）。「ユーザーがキーを設定していない場合は入力を求め、推測やプレースホルダーは絶対に使用しないこと」を徹底しています。
容量・パフォーマンス境界の管理：32Kコンテキストにより1リクエストの上限は約30分の音声となります。30分を超える場合は事前にffmpegで分割します。フォーマットは拡張子から自動識別（mp3/wav/ogg/opus/pcm）されます。
daymade-audio/stepfun-asr/SKILL.md
| Audio > 30 min | Split with ffmpeg before sending; the API rejects oversized payloads |
決定表では、重複コンテンツ（同一フレーズの5回以上の反復、90秒超）に対してstep-asr-1.1でクロス検証を行うハルシネーション対策の推奨事項も提示しています。フォーマット表では.opusはoggとして透過処理され、.pcmはrate/channel/bitsの指定が必要と記載されています。
エラーパターンを実行可能な修正テーブルに変換：誤解を招く412、サイレントな4xx、重複文字の急増、censorshipイベントのそれぞれに対応策を定義しています。
daymade-audio/stepfun-asr/SKILL.md
| `data: {"type":"error","message":"content blocked..."}` mid-stream | Censorship fired on user-uploaded content | Handle SSE `error` event explicitly; don't assume only `delta`/`done` arrive |
スクリプト側ではcensorship/blockedを含むレスポンスを検疫済みとして分類し、専用の通知（'content blocked by StepFun censorship. The audio likely contains sensitive content.'）を出力することで、伝送エラーと明確に区別します。
2コア機能
01単一コマンドでの文字起こし（python3 scripts/asr_transcribe.py audio.mp3 → 標準出力へプレーンテキスト出力、--json指定でusage/処理時間を出力）
02長尺音声の単一リクエスト処理（5〜30分、32Kコンテキストによりチャンク分割不要）
03中国語・英語のバイリンガル対応およびフォーマット自動識別（mp3/wav/ogg/opus/pcm、--language/--formatで上書き可能）
04誤解を招くエンドポイントエラーに対する適切な対処ガイダンス（not supported → /v1/audio/asr/sse への切り替え）
05censorship/コンテンツ遮断の明示的ハンドリング（エラーイベントをサイレントに破棄しない）
06利用量統計の取得（--json時のusage.input_tokens / usage.total_tokens）
07下流パイプラインへの連携提案：文字起こし完了後にtranscript-fixer / meeting-minutes-takerの利用を提案（スキップ可能）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| network | api.stepfun.com（StepAudio ASR SSE 端点） |
| network | platform.stepfun.com（文档/定价/取 key，仅指引） |
| cli | python3（stdlib urllib，无第三方包） |
| cli | ffmpeg（仅 >30 分钟切分建议，非脚本依赖） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: daymade-audio/stepfun-asr/scripts/asr_transcribe.py
- 网络端点: 外部ネットワークアクセスの宣言: POST https://api.stepfun.com/v1/audio/asr/sse（リクエストボディにbase64音声全文 + Bearer認証を含む）
監査ノート： 標準分類基準に基づく評価：外部送信の有無にかかわらず、平文のAPI認証情報へのアクセス（環境変数 $STEPFUN_API_KEY または ${CLAUDE_PLUGIN_DATA}/config.json 内の api_key の読み取り）があるため「オレンジ」に該当します。同時にネットワークへの外部送信（Bearer認証を用い、完全な音声コンテンツをapi.stepfun.comの公式エンドポイントへPOST）が存在します。送信先は既知で予測可能ですが、送信コンテンツの機密度はユーザーの音声データに依存します。ローカルファイルへの書き込みやシェルインジェクションの脆弱性はありません。
5二重目の独立検証
- [ok] 端点与 body 形状（SSE/嵌套/32K 不切片） — asr_transcribe.py ASR_URL 与嵌套 dict body 逐字存在；SKILL.md 决策表同描述。
- [ok] API key 解析顺序（env → CLAUDE_PLUGIN_DATA/config.json） — load_api_key() 先 os.environ.get('STEPFUN_API_KEY') 后读 Path(plugin_data)/config.json 的 api_key，fail-fast sys.exit(2)，无占位默认。
- [ok] SSE 事件处理（delta/done/error） — 脚本对 data: 行 json 解析后按 type 分支：delta 计数、done 取 text+usage、error 收 message；无 text 且有 errors 时返回失败。
- [ok] 无第三方 python 包依赖 — imports 仅 argparse/base64/json/os/sys/time/urllib/pathlib；SKILL.md『Prefer it over hand-rolled HTTP calls』成立。
- [ok] 凭证接触面仅 STEPFUN_API_KEY/config.json — 全目录 token 扫描无其他 key/token/secret 读取；config.json 只读 api_key 字段。
- [ok] 网络外发对象与 SKILL 描述一致 — 仅 POST api.stepfun.com/v1/audio/asr/sse + 文档站点指引（无请求）；无任何回调/遥测 URL。
- [ok] 功能声明 vs 夸大检查 — 性能/容量数字均标注『verified 2026-04-23』与价格 volatile；误导性报错解释与 known_issues 诊断轨迹一致。
- [ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。
6結論
最適な用途： 推奨対象：中国語/英語の長尺音声（5〜30分）を1回のリクエストで文字起こしする必要があるStepFunユーザー、step-asr/step-asr-1.1から移行するチーム、「model not supported」という誤認エラーで手詰まりになり正しいエンドポイントやリクエスト構文のテンプレートを必要としているインテグレーター、および文字起こし結果をtranscript-fixerやmeeting-minutes-takerなどの下流パイプラインへ渡すワークフロー。
不向きな用途： 非推奨対象：30分を超えて未分割の音声（APIが過大ペイロードを拒否するため、事前にffmpegでの分割が必要）、StepFunのNormalキーを保持していないユーザー（Planキーではサイレントに失敗）、ASR校正を挟まず出力結果をそのまま最終原稿として要求するユースケース（transcript-fixerと連携すべき）、StepFunのサービスを利用せず一般的なローカル環境や他社クラウドASRを求める環境。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload stepfun-asr.tar.gz
sha256:
Option B · Copy Guide for Agent6954122ed209d0d4…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.