| name | yichen-asr |
| description | 逸尘自用的统一音视频转写入口，在 StepFun Step ASR 与火山引擎豆包 ASR 之间按输出需求、安全边界和可用状态路由。用于本地音频或视频的纯文本转写、时间戳、SRT 字幕、口播粗剪，以及转写前体检；用户明确指定服务商时不得静默切换。Use when a local audio or video file needs transcription and the correct ASR backend is unclear, or when the user explicitly invokes $yichen-asr. |
逸尘统一 ASR
这是一个统一路由层，不是第三套 ASR 引擎。Step ASR 与豆包 ASR 继续作为底层执行器，由本 Skill 负责选择、体检、失败收敛和交接。
路由规则
| 需求 | 默认后端 | 原因 |
|---|
| 只要全文、摘要或内容分析 | Step ASR | 30 秒切片，失败片段可缩成 10/5 秒重试 |
| 需要较细时间戳、SRT 字幕 | 豆包 ASR | 返回结构化 utterances 和时间信息 |
| 需要口播停顿、填充词分析或自动粗剪 | 豆包 ASR | 现有脚本包含 SRT 与 ffmpeg 粗剪链 |
| 用户明确说“只用 Step” | Step ASR | 不得跨服务商补齐 |
| 用户明确说“只用豆包/火山” | 豆包 ASR | 不得跨服务商补齐 |
自动路由只允许在“尚未向任何服务商提交任务”时切换。如果某个请求已经上传、提交或留下 request ID，必须恢复或报告该任务，不得再向另一家提交同一媒体，以免重复计费。
用离线路由器确认选择：
python3 ~/.agents/skills/yichen-asr/scripts/route_asr.py \
--provider auto --text-only
需要字幕时：
python3 ~/.agents/skills/yichen-asr/scripts/route_asr.py \
--provider auto --need-timestamps --need-srt
执行前体检
先运行只读体检；它只报告密钥是否存在，不显示密钥内容，也不会调用付费接口：
python3 ~/.agents/skills/yichen-asr/scripts/asr_doctor.py
体检中的 token_present 仅表示本机配置了调用凭证，不代表账户有余额。ASR Token 无权读取火山引擎财务余额；余额和欠费状态必须登录费用中心核验。
Step ASR
执行器：
python3 "$YICHEN_STEP_ASR_SCRIPT" \
--input "/absolute/path/input.mp4" \
--output-dir "/absolute/path/output" \
--title "标题" \
--resume
公开版不内置 Step ASR 执行器。通过 YICHEN_STEP_ASR_SCRIPT 指向你已安装并审计过的兼容脚本；也可把它安装为同级 step-asr/scripts/step_asr_transcribe.py。执行时完整遵守该执行器的 SKILL.md。不得删除失败标记，也不得用豆包结果静默填补 Step 失败片段。
豆包 ASR
执行器：
python3 ~/.agents/skills/yichen-volc-asr/scripts/transcribe.py \
"/absolute/path/input.mp4" \
--transcribe-only
需要 SRT 与口播粗剪时，去掉 --transcribe-only；只生成分析和命令、不执行剪辑时加 --no-execute。
执行时完整遵守 ~/.agents/skills/yichen-volc-asr/SKILL.md。发现同媒体的 .asr_pending.json 时，优先恢复原任务；除非用户明确授权，不得使用 --force-new。
豆包调用不需要每次网页登录。公开版不包含 App ID、Token 或钥匙串名称：试用与付费 App ID 分别通过 VOLC_ASR_TRIAL_APP_ID、VOLC_ASR_PAID_APP_ID 提供，Token 分别通过 VOLC_ASR_TRIAL_TOKEN、VOLC_ASR_PAID_TOKEN 提供。脚本直接把本地媒体提交到极速版接口；视频先由 ffmpeg 在内存中提取音轨。
财务余额只能在火山引擎控制台登录后查看：
失败与回退
- 用户指定服务商：失败后只报告该服务商的错误和恢复路径，不自动换服务商。
- 自动路由且尚未提交：若默认后端缺少脚本、密钥或必要能力，可改用满足输出要求的另一后端，并明确说明。
- 自动路由且已经提交：不得跨服务商重提；优先用 request ID、缓存或
--resume 恢复。
- 豆包余额未知：不得说成“余额充足”或“余额不足”。只有费用中心、账单或明确的接口欠费错误可确认。
- 精确 SRT 需求不能因豆包不可用而悄悄降级为 Step 的分块 Markdown；应说明能力差异。
费用与安全
- 单个文件的明确转写请求可按选定后端执行；批量任务或可能产生显著付费额度时，先说明文件数、总时长和后端，再取得用户确认。
- 不输出 Cookie、Token、API Key；长期凭据只存 macOS 钥匙串，不写入 Skill、脚本、日志或记忆。
- 不把密钥提交到 Skill、产物、日志或记忆文件。
- 不自动充值、购买资源包或开通后付费。
- 不覆盖既有产物。不得自动删除临时文件；任何清理都要用户明确允许，并且只能移入废纸篓。
交接
向上层研究流程至少交接：
{
"provider": "step|doubao",
"mode": "text|timestamps|srt|rough_cut",
"input": "/absolute/path/input",
"outputs": [],
"request_id": null,
"billing_status": "unknown|verified_ok|verified_insufficient",
"errors": []
}
本 Skill 是 $yichen-web-research 的转写子路由。研究总入口负责决定何时需要转写；本 Skill 只负责已有本地音视频的 ASR，不负责搜索、下载或归档。
