@gitruck/cli 0.2.9 → 0.2.11

package/AGENT.md

@@ -13,8 +13,9 @@
 ## 0. 一句话流程
 
 ```
-gtrk init                                    # 一次性配置（API Key + 剪映目录）
-gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动打开产物目录
+gtrk init                                    # 一次性配置（API Key + 剪映目录）
+gtrk oralcut <毛片.mp4> [--script 文字稿.txt]  # 剪一条；剪完自动打开产物目录
+gtrk transcript <本地视频.mp4> --json          # 转成一个含总结/时码记录/纯文本的 Markdown
 ```
 
 跑完得到一个产物目录：`<毛片同目录>/<毛片名>-video-project-<YYMMDD-HHMMSS>/`，里面按格式分子目录，
@@ -145,13 +146,38 @@ gtrk split <拆分稿.json> --project <目录> --md --json  # ⑤ 校验落地
 - **时码恒挂源时基、每次发起现场投影**：用户手调切点后重导视图即跟随；此前被剪、现落回 clip 的句子自动复活，无需重跑转写。「拖入已剪好成片」= 恒等投影，同一套逻辑。
 - **拆分稿零时码、id 区间引用**：beat 的文稿范围 = `span:{from:"u0007",to:"u0011"}`（utterance id 区间），**绝不抄原句文字、绝不自造时码**（防 LLM 幻觉）。幻觉 id / 区间倒序 / 跨 beat 重叠 / `transcript_hash` 错版 → **硬拒、非 0 退出、零副作用**。
 - **dropped 处理**：beat 的 span 内 utterance 全被剪 → 跳过该 beat 并入报告；部分被剪 → 按存活句包络收缩、标 `shrunk`。均不使命令失败。
-- **transcript 缺失**（旧任务）→ 明确报错引导「用新版本重跑 oralcut（恒出 transcript）或 transcribe（规划中）」，不做降级猜测。
+- **transcript 缺失**（旧任务）→ 明确报错引导「用新版本重跑 oralcut（恒出工程所需的结构化 transcript）」，不做降级猜测；`gtrk transcript` 只产人读 Markdown，不能替代 split 所需的结构化词表。
 - **只动 `struct_meta.split`**：写回不碰 materials/tracks，配合客户端「保存 → 发起 → 写回 → 重载」闭环（opencut 联动）。
 - **下游消费**：`dispatch.json` 的 `film_broll` 队列 → `gtrk matrix --project <dir>`（B-roll 双口检索 → `split/broll-plan.json` 候选清单;url 24h 过期,重跑即重签）；`mg` 槽位表（去品牌化前 `rrv_mg`）→ `gtrk mg` 铺轨 / real-roam-viz 产颗粒；`ai_drama` 队列 → ai-drama-prompter。
 
-> **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
-
----
+> **skill 分工**：拆 beat / 选 lane / 写 handoff 是脑（`gtrk-splitter` skill）的活；投影 / 校验 / 落地 / 写时码是手（本命令）的活。skill 铁律：只引用视图存在的 utterance id、不抄原文定位、不碰时码。
+
+### 2.3 视频转文字稿：`gtrk transcript <本地视频>`
+
+这一能力由独立的 `gtrk-transcript` Skill 驱动，不属于 `gtrk-tools` 单点工具族。用户说「视频转文字 / 视频转文字稿 / 提取视频文稿 / 把本地视频整理成妙记式文稿」时，直接运行：
+
+```bash
+gtrk transcript "D:/素材/采访视频.mp4" --json
+```
+
+| 参数 | 作用 | 缺省 |
+|---|---|---|
+| `<本地视频>` | 用户电脑上的视频文件；拒绝 URL、平台地址和远端下载 | 必填 |
+| `-o, --out <file>` | 唯一 Markdown 产物路径 | `<视频同目录>/<视频名>-transcript.md` |
+| `--lang <code>` | 识别语言 | `zh-CN` |
+| `--ffmpeg-path <dir>` | 指定本地 ffmpeg/ffprobe | 自动解析 |
+| `--reupload` | 忽略上传缓存，强制重传抽取音频 | 关 |
+| `--json` | stdout 只留 `{ok,taskId,fileId,output,summaryPending}` | agent 必带 |
+
+**边界与产物：**
+
+- 原视频始终留在本机；CLI 本地抽取 16 kHz 单声道 MP3，时长自检后只上传这份音频衍生物。
+- 用户目录最终只新增一个 `.md`，固定按「总结 → 文字记录 → 纯文本」排列；文字记录用 `[00:01:23]` 时码，不虚构说话人标签。
+- CLI 不负责总结：它在 `## 总结` 下写入 `<!-- gtrk:agent-summary-pending -->`，并返回 `summaryPending:true`。驱动 Agent 必须阅读全文，生成简洁、忠于原文的语义总结，**原地替换标记及提示语**；不得另建总结文件。
+- 写回时只改 `## 总结` 到 `## 文字记录` 之间，保留后两段原样；建议 3–7 条要点，覆盖主题、关键论点/事实和结论，不补原文没有的信息。
+- `output` 就是最终 Markdown 的绝对路径；确认文件存在、三段标题齐全且待总结标记已消失后，才能回给用户。ASR 实时价格运行前从官网价格表查询，严禁引用记忆价格。
+
+---
 
 ## 3. 产物结构 + 三端打开
 
@@ -242,8 +268,10 @@ gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":
 
 ### 工具族：接单点云能力 = 加一个 descriptor（不写编排）
 
-单发单收的单点能力（图转运镜、图片/视频抠像…）不各开顶层命令，而入 `gtrk tool <name>` 工具族。骨架全归共享 runner `src/lib/tool-runner.ts`（校验 → 可选 preprocess → `uploadCached` → 提交前打印 `billingHint` → `submitTask`（6004 失效重传收编于此）→ 自循环轮询（复用 `getTaskResult`、墙钟 per-tool 可覆盖，**不改 `pollTask`**）→ `mapOutputs` **流式下载**落地（fetch body pipe 到 `createWriteStream`，大产物不过内存，**不用 `cloud.ts` 全内存 `download`**）→ `task.json`/`result.json` 面包屑）。差异全归一个薄 descriptor `src/lib/tool-descriptors.ts`（`name`/`kind`/`input`（含扩展名白名单、视频类 `maxDurationSec` 硬上限）/`taskType`/`buildPayload`/`mapOutputs`/`billingHint`/`options`/`enabled`+`disabledReason`/`pollTimeoutMs`）。
+单发单收的单点能力（图转运镜、图片/视频抠像…）不各开顶层命令，而入 `gtrk tool <name>` 工具族。骨架全归共享 runner `src/lib/tool-runner.ts`（校验 → 可选 preprocess → 按 descriptor `priceKey` 匿名查询官网实时价格并提示 → `uploadCached` → `submitTask`（6004 失效重传收编于此）→ 自循环轮询（复用 `getTaskResult`、墙钟 per-tool 可覆盖，**不改 `pollTask`**）→ `mapOutputs` **流式下载**落地（fetch body pipe 到 `createWriteStream`，大产物不过内存，**不用 `cloud.ts` 全内存 `download`**）→ `task.json`/`result.json` 面包屑）。差异全归一个薄 descriptor `src/lib/tool-descriptors.ts`（`name`/`kind`/`input`（含扩展名白名单、视频类 `maxDurationSec` 硬上限）/`taskType`/`priceKey`/`pricingContext`/`buildPayload`/`mapOutputs`/`options`/`enabled`+`disabledReason`/`pollTimeoutMs`）。价格数字不得写进 descriptor、README 或 skill；以 `https://cloud.ai-mcn.tv/api/get_price_list` 为唯一真相，失败显示暂不可用但不阻断任务。
 
-**接新工具 = 在 `TOOL_REGISTRY` 追加一个 descriptor 对象**（`tool list` 与分派自动生效），不新写命令编排。`--param`/`--params-json` 在 `buildPayload` 结果上逐字段合并覆盖。`cloud.ts`/`upload-cache.ts`/`chunk-upload.ts`/`media.ts` 只被复用、零改动。`list` 为保留字。工具长出多模式子命令 / SOP 检查点链 / 栏目风格注入时按 `mg`/`matrix` 先例毕业为独立命令。随包分发伞形 skill `skills/gtrk-tools/`（一个 skill 覆盖全族）。
+**接新工具 = 在 `TOOL_REGISTRY` 追加一个 descriptor 对象**（`tool list` 与分派自动生效），不新写命令编排。`--param`/`--params-json` 在 `buildPayload` 结果上逐字段合并覆盖。`cloud.ts`/`upload-cache.ts`/`chunk-upload.ts`/`media.ts` 只被复用、零改动。`list` 为保留字。工具长出多模式子命令 / SOP 检查点链 / 栏目风格注入时按 `mg`/`matrix` 先例毕业为独立命令。随包分发伞形 skill `skills/gtrk-tools/`（一个 skill 覆盖全族）。
+
+`transcript` 已毕业为一级命令，并由 `skills/gtrk-transcript/` 独立承接自然语言触发和总结写回；不得再把这套工作流塞回 `gtrk-tools`。
 
 **local 型（`kind:"local"`）首个实例 = `mad`（一键剪 MAD，add-tool-mad）**：无 Key 可跑、可选云端加料。cloud 型走共享 runner 全链，local 型（复杂度上限标尺）在 `tool.ts` 的 local 分支**分派到自己的 handler**（`src/lib/mad/mad.ts::runMad`），不套 runCloudTool。mad 的新逻辑全住 `src/lib/mad/`（数据获取层 `data.ts` = 云端 manifest `/task/mad/manifest` + `~/.gitruck/mad-cache` 版本感知缓存 + sha256 自愈；`selector.ts` 六维规则选窗 + 种子 PRNG；`beat.ts` downbeat 量化 + 三级降级；`pool.ts` IR 分片按需拉取；`scan.ts` 素材扫描；`cloud-beat.ts` audio_music_analyze 接线 + 6004 失效重传）与 `src/lib/convert/`（IR→JSX，含 `madJsx` 母合成拼接 + `bake_ops.ts` 时序算子烘焙）——`tool-descriptors.ts`/`tool-runner.ts`/`cloud.ts` 零改动（红线）。产物仅 `.jsx`／仅支持 AE。