gitruck/cli/gtrk-transcript

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. 确认用户给的是本地视频路径；需要时再接受输出文件路径或识别语言。

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

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

```bash # 默认：只要文字稿 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[]，那时补跑一次即可；反过来多付的钱收不回来。 > 用户明确说「要建工程 / 要拆分 / 要字幕」才算「喂工程」；只说「转个文字稿」不算。

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

• 带 `--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`。

1. 完整读取 output 指向的 Markdown，必须覆盖完整转写内容，不能只看开头几段。
2. 若 summaryPending:true，只编辑 ## 总结 与 ## 文字记录 之间的内容：删除 <!-- gtrk:agent-summary-pending --> 及提示语，写入 3–7 条忠于原文的语义要点。不得改动 ## 文字记录 和 ## 纯文本，不得创建第二个文件。
3. 写回后验证：

• ## 总结、## 文字记录、## 纯文本 各出现一次且顺序正确；
• gtrk:agent-summary-pending 已消失；
• 时间戳文字记录和纯文本仍完整；
• 返回用户的路径仍是第 3 步拿到的同一个产物路径（带 --json 时是结果 JSON 的 output，

不带时是你传的 --out 或那条缺省路径）——MUST NOT 换成副本或新建文件。

总结标准

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

失败处理

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