gtrk 视频/音频转文字稿

飞书使用教程统一入口：gtrk CLI 使用教程。

本 Skill 驱动一级命令 gtrk transcript，最终只交付一个 Markdown：总结、带 [00:01:23] 时间戳的可读文字记录、完整纯文本。

音频输入与 transcript.json（自备配音时码化兜底）

• 输入白名单已放开音频：wav/mp3/flac/m4a/aac/ogg 等本地音频文件可直接转写（音频无「抽音频」步——已是音频，仍本地转 16k 单声道后只传转码衍生物，原文件不动）。
• --json 除机读 stdout 外另产 <名>-transcript.json（utterances[]{id,text,st,ed} + material_id + text_hash + duration，结构与 gtrk split 消费契约逐字段对齐）；结果 JSON 的 transcriptJson 字段给出路径，可直接被 gtrk project init --audio <配音> --transcript <该文件> 兜底路消费。
• 定位注记（MUST 遵守）：TTS 主路勿走本零件——gtrk tool audio_tts_clone 产的配音自带句级 segments（时码直出、零成本零误差），建工程直接 gtrk project init --tts-task <task_id>；对 TTS 产物再跑一遍 ASR 转写=重复计费零收益。本零件只服务自备配音（用户自录旁白等无时码音频）场景。

硬边界

产物落点纪律（MUST · 全文见随包 AGENT.md 同名一节）：唯一 Markdown 产物写入 CLI 返回的 output 路径（缺省=源文件同目录）或用户指定的 --out；引用媒体用原路径，不复制到 agent 工作目录；临时文件放系统 temp，用完即删。 交付物 MUST NOT 先写 agent 自有目录再拷进工程；中转本身即违规，体积不是豁免理由。

• 只接收用户电脑上已存在的视频/音频文件；遇到 URL、平台视频 ID 或“帮我下载后转写”时，要求用户先提供本地文件，不代为抓取。
• CLI 在本地抽取/转码 16 kHz 单声道音频，只上传音频衍生物；原视频/原音频文件不得上传。
• 最终只保留 CLI 返回的产物：一个 Markdown（--json 时另有 CLI 自产的 <名>-transcript.json），不另建总结、字幕、TXT 或 HTML 文件。
• 没有可靠的说话人分离数据时，不得编造“说话人 1/2”等标签。
• 价格必须以本次 CLI 从官网价格表得到的实时提示为准，不写死金额、不凭记忆报价。

工作流

1. 确认用户给的是本地视频路径；需要时再接受输出文件路径或识别语言。

2. 先判用途，再决定带不带 --json。这一步 MUST NOT 跳过，也 MUST NOT 无脑恒带。

   --json 不是单纯的输出格式开关，它决定服务端用哪个引擎：

   用途	命令	落腿
   只要一份能读的文字稿（默认，含「转文字/提取文稿/出妙记/整理成文档」）	不带 --json	自部署引擎 + 服务端纠错，句级时码
   产物要喂工程（project init 兜底路 / split 拆分 / subtitle 字幕按语音贴时间）	带 --json	厂商字级腿，utterances[].words[] 承载字级

   # 默认：只要文字稿
   gtrk transcript "D:/素材/采访视频.mp4" --out "D:/素材/采访视频-transcript.md"
   
   # 要喂工程时才加 --json
   gtrk transcript "D:/配音/旁白.mp3" --json
   

   可选参数：--out <file>、--lang zh-CN、--ffmpeg-path <dir>、--reupload。

   🔴 恒带 --json 会把只想要文字稿的请求也送进厂商字级腿，且 Markdown 不消费 words[]。拿不准就不带：真需要字级时，消费方（split / subtitle） 会明确报错要 words[]，那时补跑一次即可；反过来多付的钱收不回来。 用户明确说「要建工程 / 要拆分 / 要字幕」才算「喂工程」；只说「转个文字稿」不算。

3. 取产物路径，分两种形态：

   • 带 --json：解析 stdout 的唯一 JSON。仅当 ok:true 时继续；保存 taskId、output、 transcriptJson（句级时码稿路径，建工程时交给 gtrk project init --transcript），并检查 summaryPending:true。 人读进度在 stderr，不要把日志当成结果 JSON。
   • 不带 --json：stdout 末尾是人读行 带时码文字稿已生成：<路径>，没有结果 JSON。 ⇒ 优先显式传 --out，这样路径由你指定、无需从日志里抠；缺省路径是 <源文件同目录>/<源文件名>-transcript.md。 判成功用退出码 + 产物文件存在且非空，MUST NOT 只看日志里有没有那行字。 此形态下 summaryPending 恒为真（Markdown 里的 <!-- gtrk:agent-summary-pending --> 就是判据）， 且不产 transcript.json。

4. 完整读取 output 指向的 Markdown，必须覆盖完整转写内容，不能只看开头几段。

5. 若 summaryPending:true，只编辑 ## 总结 与 ## 文字记录 之间的内容：删除 <!-- gtrk:agent-summary-pending --> 及提示语，写入 3–7 条忠于原文的语义要点。不得改动 ## 文字记录 和 ## 纯文本，不得创建第二个文件。

6. 写回后验证：

   • ## 总结、## 文字记录、## 纯文本 各出现一次且顺序正确；
   • gtrk:agent-summary-pending 已消失；
   • 时间戳文字记录和纯文本仍完整；
   • 返回用户的路径仍是第 3 步拿到的同一个产物路径（带 --json 时是结果 JSON 的 output， 不带时是你传的 --out 或那条缺省路径）——MUST NOT 换成副本或新建文件。

总结标准

• 提炼主题、关键论点或事实、重要数字/人名和结论；合并重复内容。
• 总结应是对全文的压缩，不要只复述第一句或按时间线逐段抄写。
• 只使用转写中能确认的信息；含混或缺失处保持克制，不补充常识性猜测。
• 不在正文中添加服务商、底层 ASR、计费实现等用户未要求的技术说明。

失败处理

• 缺 API Key：引导运行 gtrk init，不要无效重试。
• 输入是 URL 或远端资源：停止执行，要求用户提供本地视频文件。
• ASR 没有可用文字：如实报告失败，不生成虚假总结或空白成品。
• 云任务失败：报告 CLI 返回的错误与 taskId（若有），不要把失败包装成完成。
• 实时价格暂不可用：说明最终以服务端结算为准；不要引用旧价格。