@gitruck/cli 0.2.8 → 0.2.10

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. 产物结构 + 三端打开
 
@@ -239,3 +265,13 @@ gtrk oralcut "D:/素材/某条.mp4" --params-json '{"punctuation_breaks":{"。":
 
 新增命令 = 写 `src/commands/<name>.ts` 的 `register<Name>(program)` + 在 `src/index.ts` 注册一行。
 云端调用走 `src/lib/cloud.ts`（`{code,msg,data}` 包装、鉴权 Header `Authorization:<裸key>`；单发取结果 `getTaskResult`、`pollTask` 复用之）；上传一律走 `src/lib/upload-cache.ts` 的 `uploadCached`（白嫖指纹缓存；≥256MiB 自动分片断点续传，见 `src/lib/chunk-upload.ts`）。本地预处理（探几何 / 抽音频 / 压 720p）在 `src/lib/media.ts`；本地渲染（gtrk EDL → ffmpeg filter_complex）在 `src/lib/render.ts`；三方产物落地 + `result.json` 两段写在 `src/lib/materialize.ts`（`oralcut` 与 `oralcut-result` 共用）。已上线：`oralcut`（云剪）、`oralcut-result`（按 task_id 取回）、`render`（本地渲染 gtrk）、`split`（视觉拆分派单器：`src/lib/projection.ts` 投影纯函数 + `src/lib/splitdoc.ts` 拆分稿校验/落地 + `src/lib/gtrk-writeback.ts` 原子写回 `struct_meta.split`，随包分发 `skills/gtrk-splitter/`）。`matrix`（B-roll 检索：`src/lib/matrix.ts` 双口路由/派单翻译/plan 构建 + `src/commands/matrix.ts`;`matrix search "<词>"` ad-hoc）。规划中：`struct`（已有 gtrk → 三方工程）。
+
+### 工具族：接单点云能力 = 加一个 descriptor（不写编排）
+
+单发单收的单点能力（图转运镜、图片/视频抠像…）不各开顶层命令，而入 `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 覆盖全族）。
+
+`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。

package/README.md

@@ -1,9 +1,11 @@
-# gtrk-cli
+# gtrk-cli（原·同合智创工具箱）
 
 > 同合云成片流水线 CLI —— **agent 驱动云端任务、产物拉回本地、三方工程文件（客户端 / 剪映 / PR）互通**。
 >
 > 一条命令，把口播毛片变成可二次精修的剪辑工程。云端做重活，本地只装配，源视频不出本地。
 
+**🔗 [官网](https://cloud.ai-mcn.tv/zh-CN/cli) · [使用教程](https://hocassian.feishu.cn/wiki/HCFpwoF7SivIFbkKosgcFMcEnxk) · [快速开始](https://cloud.ai-mcn.tv/zh-CN/docs/quick-start) · [客户端下载](https://cloud.ai-mcn.tv/zh-CN/download) · [npm](https://www.npmjs.com/package/@gitruck/cli)**
+
 ---
 
 ## 为什么用 gtrk-cli
@@ -18,14 +20,16 @@
 | | 命令 | 做什么 |
 |---|---|---|
 | 🎬 | `gtrk oralcut <毛片>` | 智能口播剪辑闭环：一次出 gtrk + 剪映 + PR 三方工程，自动打开 |
+| 📝 | `gtrk transcript <本地视频>` | 视频转文字稿：原视频不上传，只传本地抽取音频，生成一个含总结、时码记录和纯文本的 Markdown |
 | ✂️ | `gtrk split [拆分稿]` | 视觉拆分派单器：成片 × transcript 投影 → beat 分镜校验落地（`struct_meta.split` + `dispatch.json`），驱动四车道派单；`--column <id>` 按栏目词表校验 |
 | ⚙️ | `gtrk init` | 引导式一次性配置（API Key + 剪映草稿目录），之后免管 |
 | 🩺 | `gtrk doctor` | 体检：配置 / 云端连通 / 剪映目录 / 运行时一键自检 |
-| 🤖 | `gtrk skills install` | 把 6 个 CLI 自带 skill（`/gtrk-oralcut`·`/gtrk-splitter`·`/gtrk-matrix`·`/gtrk-mg`·`/gtrk-ai-drama`·`/gtrk-style-maker`）装进 Claude Code |
+| 🤖 | `gtrk skills install` | 把 8 个 CLI 自带 skill（`/gtrk-oralcut`·`/gtrk-splitter`·`/gtrk-matrix`·`/gtrk-mg`·`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-transcript`·`/gtrk-tools`）装进 Claude Code |
 | ⬆️ | `gtrk upgrade` | 升级 CLI 到最新版 + 刷新 skill（配置保留）；`--check` 只查不装 |
 | 🎞️ | `gtrk render` | 本地渲染 gtrk 工程（EDL）→ 成片 mp4（需 ffmpeg） |
 | 🔎 | `gtrk matrix` | B-roll 检索+**候选铺轨**：消费 FILM_BROLL 派单 → 产候选清单 + 下载 preview 代理铺 N 条候选轨（`--lay N` 默认 1，opencut 打开即可用轨道小眼睛对比；`--lay 0` 只出清单）；`matrix search "<词>"` 单条 ad-hoc |
 | 🎨 | `gtrk mg` | MG 动态图颗粒铺轨：消费 MG 派单 → 把 html-particle 颗粒（透明叠加 / 满屏底层，由你栏目的 MG 生产 skill 所产）铺进 `.gtrk` 的 beat_track；`mg lint <颗粒.html>` 六铁律静态校验、`mg status --project <dir>` 编排看板（缺 HTML / 已产未铺 / 已铺）；aux 叠层颗粒同段多铺（一 beat 派生主 + `-aux<n>`）。旧名 `gtrk rrv` 保留为弃用别名 |
+| 🧰 | `gtrk tool <name>` | 单点工具族：图转运镜、图片/视频抠像、图片去黑边/比例转换/净化、视频去黑边/比例转换/防抖/蒸汽波滤镜、人声伴奏分离、音视频降噪、静音移除、MAD 等；`gtrk tool list` 查全部输入/产物/实时价格/状态。单发单收、共享 runner，接新工具只加一个 descriptor |
 | 🚧 | `struct` | （规划中）已有 gtrk 转三方工程 |
 
 ---
@@ -51,6 +55,9 @@ npm i -g @gitruck/cli@latest && gtrk install
 
 # 2) 剪一条（剪完自动打开产物目录）
 gtrk oralcut "D:/素材/某选题-原始口播.mp4" --script "D:/素材/某选题-文字稿.txt"
+
+# 或把本地视频转成一个 Markdown 文字稿
+gtrk transcript "D:/素材/采访视频.mp4"
 ```
 
 > 只想配置、不装 skill：用 `gtrk init`。本地开发：`cd gtrk-cli && bun install && bun run src/index.ts <命令>`。
@@ -143,7 +150,7 @@ irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex
 
 ## 给 AI Agent 用
 
-`gtrk install` 已经把 6 个 CLI 自带 skill（`/gtrk-oralcut`·`/gtrk-splitter`·`/gtrk-matrix`·`/gtrk-mg`·`/gtrk-ai-drama`·`/gtrk-style-maker`）装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
+`gtrk install` 已经把 8 个 CLI 自带 skill（`/gtrk-oralcut`·`/gtrk-splitter`·`/gtrk-matrix`·`/gtrk-mg`·`/gtrk-ai-drama`·`/gtrk-style-maker`·`/gtrk-transcript`·`/gtrk-tools`）装进 `~/.claude/skills`（单独装用 `gtrk skills install`）。
 
 然后在 Claude Code 里直接说「**帮我把这条口播剪一版**」或打 `/gtrk-oralcut`，agent 会问清毛片 / 文稿 / 节奏，调 `gtrk oralcut --json` 跑通闭环、验证产物、把三端打开方式回给你。完整可移植 playbook 见 [`AGENT.md`](./AGENT.md)。
 
@@ -162,11 +169,11 @@ irm https://api.ai-mcn.tv:9000/broadcast/exe/install.ps1 | iex
 | ⑤ | `/gtrk-ai-drama` | （无命令，纯创作） | **最后上 AI 再现**：产四段描述稿（故事背景/角色/分镜/原文，中英分块）→ 任意外部平台出片、手动回铺（产物即描述文本、无机械尾巴，同 `/gtrk-style-maker` 只 skill 无命令） |
 | — | `/gtrk-style-maker` | （无命令，建栏目） | 一次性访谈式建你栏目的风格体系（skill 家族 + 栏目配置，见下节） |
 | — | （收口） | `gtrk render` | 本地渲染 gtrk 工程 → 成片 mp4 |
+| 📝 | `/gtrk-transcript` | `gtrk transcript` | 本地视频 → 一个含 Agent 总结、时码记录和纯文本的 Markdown，**不在成片 SOP 序列内** |
+| 🧰 | `/gtrk-tools` | `gtrk tool <name>` | 单点工具族（图转运镜 / 图片·视频抠像…）——单发单收，**不在成片 SOP 序列内**、随时可独立用 |
 
 > **skill 与命令的区别**：`/gtrk-mg` 是**脑**——懂它在 SOP 第 ④ 步（B-roll 定了才铺 MG）、带用户确认、按栏目配置解析该产哪种颗粒；`gtrk mg` 是**手**——纯确定性 lint + 铺轨。你对话触发 skill，skill 替你跑命令。
-> 上面 6 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装）——`/gtrk-matrix`·`/gtrk-mg` 各驱动一个 gtrk 命令，`/gtrk-ai-drama`·`/gtrk-style-maker` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
-
-上面三个是 **CLI 自带的框架 skill**（`gtrk skills install` 装，业务无关）。
+> 上面 8 个 `/gtrk-X` 都是 **CLI 自带框架 skill**（`gtrk skills install` 装）——`/gtrk-transcript` 独立驱动视频转文字稿，`/gtrk-tools` 只负责单点工具族，二者都不属成片 SOP 序列；`/gtrk-ai-drama`·`/gtrk-style-maker` 是纯创作 skill（无命令）。栏目专属的**视觉风格/生产内容**另由你栏目的生产 skill（`/gtrk-style-maker` 产、经栏目配置 `style.skills` 绑定）供，不写死在这些框架 skill 里。
 
 **各车道的具体视觉/内容怎么产**——MG 动态图长什么样、AI 再现什么调性——不写死在 CLI 里，而由**你自己栏目的生产 skill** 提供（用 `/gtrk-style-maker` 访谈式产出、留本地）。它们经**栏目配置 `style.skills[].produces`**（值 = 车道名）绑定，`gtrk mg` / `gtrk matrix` 等**通用驱动器**据此消费。**驱动方向 = CLI 驱动栏目 skill**：栏目 skill 只供风格/内容、不含任何「跑哪条命令」的编排职责；框架只认车道与管线接口，画面风格永远归你的栏目。不建栏目就用内置默认，端到端照常跑。
 
@@ -226,6 +233,23 @@ gtrk init --api-key <KEY> --jianying-draft-dir auto -y
 
 ## 命令参考
 
+### `gtrk transcript <本地视频>`
+
+把本地视频转为一个多层级的 Markdown 文字稿。只接受本地视频路径：CLI 在本机抽取 16 kHz 单声道音频，只上传音频衍生物，原视频不会上传，也不支持 URL 或平台视频下载。
+
+```bash
+gtrk transcript "D:/素材/采访视频.mp4"
+gtrk transcript "D:/素材/采访视频.mp4" --lang zh-CN --out "D:/文字稿/采访.md" --json
+```
+
+缺省只生成 `D:/素材/采访视频-transcript.md`，内容固定为：
+
+1. `## 总结`：CLI 先标记为待完成，由 `/gtrk-transcript` 驱动 Agent 阅读全文后生成并写回；
+2. `## 文字记录`：以 `[00:01:23]` 开头的可读段落；
+3. `## 纯文本`：完整识别正文，便于整段复制。
+
+实时计费在运行前从官网价格表按 `asr` 查询，CLI 与文档不保存价格数字。`--json` 的 stdout 只输出 `{ok,taskId,fileId,output,summaryPending}`，其中 `output` 指向这一个 Markdown；`summaryPending:true` 表示 `/gtrk-transcript` 驱动 Agent 还需生成语义总结、原地替换待总结标记，完成后仍只交付同一个文件。
+
 ### `gtrk oralcut <毛片>`
 
 | 参数 | 作用 | 缺省 |
@@ -310,6 +334,58 @@ gtrk init --api-key <KEY> --jianying-draft-dir auto -y
 > **aux 叠层颗粒**：`gtrk split` 若在某 beat 的 `aux_layers` 派了 `overlay` 颗粒，会派生 `<beat>-aux<n>` 合成条目进 `dispatch.mg`——`gtrk mg` 一并铺，实现「同段既有底轨主视觉、又叠透明概念图解」。
 > **双读兼容**：`dispatch.mg`（读旧 `rrv_mg`）、源目录 `mg/`（读旧 `rrv/`）、素材前缀 `mg-`（读旧 `rrv-`）——去品牌化前的既有工程零迁移。
 
+### `gtrk tool <name> [input]` — 单点工具族
+
+单发单收的独立能力，与成片管线的车道命令（`oralcut`/`split`/`matrix`/`mg`）分家。**顶层命令 + 首个 positional 词分派**（不用父子命令）：`gtrk tool <name> [input]` 跑工具，`gtrk tool list` 查全部。一个工具 = 一个薄 descriptor（输入类别 / payload 拼装 / 产物映射 / 计费 / 可用门），共享 runner 跑「校验 → 上传（指纹缓存、≥256MiB 自动分片）→ 提交 → 轮询 → 流式下载落地 → `task.json`/`result.json` 面包屑」——接新工具只加一个 descriptor、不写编排。
+
+| 工具 | 输入 | 产物 | 计费 | 状态 |
+|---|---|---|---|---|
+| `image_move` | 单张图片 | 运镜视频（几何按原图朝向推导：横 1920×1080 / 竖 1080×1920） | 运行前实时查询 | 已上线 |
+| `image_matting` | 单张图片 | 透明背景 png（可 `--param` 请求背景底板） | 运行前实时查询 | 已上线 |
+| `image_blackborder_remove` | 单张本地图片 | 去黑边图片 | 运行前实时查询 | 已上线 |
+| `image_canvas_adapt` | 单张本地图片；可选目标宽高与 `normal` / `rectangle` / `square` | 比例适配图片 | 运行前实时查询 | 已上线 |
+| `image_purify` | 单张本地图片（仅处理你有权处理的素材） | 清理水印、Logo 或叠加元素后的净化图片 | 运行前实时查询 | 已上线 |
+| `video_matting` | 单条视频（**≤10 分钟**，原片直传不压代理） | 透明背景 webm | 运行前实时查询 | 已上线 |
+| `video_blackborder_remove` | 单条本地视频 | 去黑边视频 | 运行前实时查询 | 已上线 |
+| `video_canvas_adapt` | 单条本地视频；可选目标宽高、片段、画布模式和无音轨输出 | 比例适配视频 | 运行前实时查询 | 已上线 |
+| `video_stabilizer` | 单条本地视频；可选 `fast` / `exp` / `turbo` | 防抖视频 | 运行前实时查询 | 已上线 |
+| `video_vaporwave` | 单条本地视频；滤镜使用精确预设名称 | 蒸汽波滤镜视频 | 运行前实时查询 | 已上线 |
+| `video_purify` | 单条本地视频；可选 `full_screen` / `subtitle` / `custom`、`ffmpeg` / `raft` 与归一化 ROI（仅处理有权修改的素材） | 一条净化视频 | 运行前实时查询 | 已上线 |
+| `video_upscale` | 单条本地视频（**≤1 分钟**）；可选 `2` / `3` / `4` 倍与 `Reality` / `Anime` | 一条超分视频 | 运行前实时查询 | 已上线 |
+| `video_interpolate` | 单条本地视频；可选 `2` / `3` / `4` 倍，不附加 1 分钟限制 | 一条插帧视频 | 运行前实时查询 | 已上线 |
+| `audio_separation` | 单条音频；可选 `--mode fast|turbo` | 人声与伴奏音频（按实际返回可为一项或两项） | 运行前实时查询 | 已上线 |
+| `audio_noise_reduce` | 单条音频或视频；可选 `--prop-decrease 0..1` | 降噪后的音频 | 运行前实时查询 | 已上线 |
+| `audio_silence_remove` | 单条音频；可选静音阈值与保留时长 | 去静音音频 | 运行前实时查询 | 已上线 |
+| `mad` | 一个素材文件夹（3~10 条视频）+ 可选 `--bgm` | AE 母合成成片工程 `.jsx`（仅支持 AE） | 仅 `--bgm` 触发实时查价 | 已上线 |
+
+> 价格以 `gtrk tool list --json` 和执行前 stderr 的匿名实时查询为准，README 不保存价格快照。`video_matting` 上传前 ffprobe 探时长，> 10 分钟直接拒绝（不上传不提交、请先裁剪）。
+> `mad` 是族内首个 **local 型「纯本地工具、可选云端加料」**：无 Key 可跑且不触发计费任务（技法数据经云端 manifest 下发 + `~/.gitruck/mad-cache` 缓存，**首拉联网、缓存后离线可跑**），`--bgm` 卡点才需 Key 并触发一次云端节拍分析；三级降级（有 Key 卡点 / 无 Key 或坏 BGM 固定节奏 / 云端失败降级）全程不崩。仅产 `.jsx`／仅支持 AE。
+
+去黑边、比例转换、防抖、蒸汽波、净化、超分、插帧七个公共视频工具只接受服务端当前 `video_ext`：`.mp4`、`.avi`、`.mpg`、`.mov`、`.flv`、`.mxf`、`.mpeg`、`.ogg`、`.3gp`、`.wmv`、`.h264`、`.m4v`、`.ts`；`.mkv` 与 `.webm` 会在本地拒绝。输入必须是本地文件路径，CLI 不负责下载远端视频。
+
+- `gtrk tool list [--json]` — 列全部工具（名称/说明/输入/产物/实时价格/状态）；`--json` 出单行机读数组（含动态 `billingHint`/`pricing`）。**无 API Key 也能跑**；价格通过公开接口匿名查询，失败仍列完整清单并标记暂不可用。
+- `gtrk tool image_move ./photo.jpg [--json]` — 图转运镜；产物落 `photo-image_move/`。`--param width=1080 --param height=1920` 覆盖推导几何。
+- `gtrk tool image_matting ./portrait.jpg` / `gtrk tool video_matting ./clip.mp4` — 图片/视频抠像。
+- `gtrk tool image_blackborder_remove ./photo.jpg [--json]` — 自动裁去单张图片四周黑边。
+- `gtrk tool image_canvas_adapt ./photo.jpg --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle [--json]` — 图片比例转换；省略画布参数时沿用服务端默认。画布模式按实际运行时契约只接受 `normal`、`rectangle`、`square`，不接受旧文档中的 `fit`。
+- `gtrk tool image_purify ./photo.jpg [--json]` — 清理你有权处理的图片中的水印、Logo 或叠加元素。
+- `gtrk tool video_blackborder_remove ./clip.mp4 [--json]` — 自动裁去单条视频四周黑边并保留原音轨。
+- `gtrk tool video_canvas_adapt ./clip.mp4 --canvas-width 1080 --canvas-height 1920 --canvas-type rectangle --clip-start 12 --clip-end 60 --without-audio [--json]` — 视频比例转换；`--clip-start/--clip-end` 是起止帧序号，省略字段时沿用服务端默认，画布模式只接受 `normal`、`rectangle`、`square`。
+- `gtrk tool video_stabilizer ./clip.mp4 --stabilizer-method turbo [--json]` — 视频防抖；支持 `fast`、`exp`、`turbo`，其中 `exp` 为实验方式，产物观感需自行检查。
+- `gtrk tool video_vaporwave ./clip.mp4 --vaporwave-filter "灼熱苦夏" [--json]` — 使用精确预设名称添加蒸汽波滤镜；省略时显式使用 `愈漸升溫`。
+- `gtrk tool video_purify ./clip.mp4 --purify-scope custom --purify-method ffmpeg --purify-roi 0,0.78,1,0.2 [--json]` — 净化用户有权修改的视频；ROI 为归一化 `x,y,w,h` 且只和 `custom` 同用。`raft` 仅支持 20 分钟以内视频，`ffmpeg` 不套用该限制；不承诺还原被遮挡内容。
+- `gtrk tool video_upscale ./clip.mp4 --upscale-times 3 --upscale-type Anime [--json]` — 实验性视频超分；输入最多 60 秒，放大后任一边不得超过 4000 px，支持 `2`、`3`、`4` 倍和 `Reality`、`Anime`。
+- `gtrk tool video_interpolate ./clip.mp4 --interpolate-multiplier 3 [--json]` — 视频插帧；支持 `2`、`3`、`4` 倍，不套用旧文档中的 1 分钟限制，原视频任一边不得超过 4000 px。
+- `gtrk tool audio_separation ./song.mp3 [--mode turbo]` — 人声伴奏分离；`--param need_vocals=false` 等低频字段仍可透传。
+- `gtrk tool audio_noise_reduce ./interview.mp4 [--prop-decrease 0.5]` — 音频或视频均可输入，统一输出降噪音频。
+- `gtrk tool audio_silence_remove ./talk.mp3 [--min-silence-len 800] [--desired-silence-len 200]` — 移除过长静音，只落处理后的音频。
+- `gtrk tool mad ./素材 [--bgm 歌.mp3] [--duration 20] [--seed 42] [--refresh] [--json]` — 一键剪 MAD：扫素材文件夹 → 自动选技法 → 单一 `.jsx`（AE 2020+ 跑一遍出母合成成片工程）。`--seed` 可复现；`result.json` 记 seed/数据版本/降级档位/选中技法。
+- 通用：`--out <dir>` 覆盖产物目录、`--param k=v`（可重复）/`--params-json '<对象>'` 透传云端参数、`--reupload` 忽略上传缓存、`--json` 机读、`--ffmpeg-path <dir>` 指定 ffmpeg 目录。
+- cloud 型工具缺 Key → 报错引导 `gtrk init`。产物下载失败（如链接过期 404）→ `result.json` 记 `errors`、`ok=false`、`task.json` 保留可凭 `taskId` 恢复。
+- 净化、超分、插帧为长耗时 GPU 任务，描述器最多轮询 4 小时。等待超时不代表任务取消；保留 `task.json` / `result.json` 并按 `taskId` 恢复，不要直接重跑造成重复计费。
+
+配套 skill `/gtrk-tools`（一个 skill 覆盖整个工具族）。
+
 ### 其它
 
 - `gtrk install [--api-key … -y --skills-dir …]` — 一条命令装全（skill + 配置 + 体检），对标飞书 `lark-cli install`。
@@ -346,9 +422,9 @@ gtrk init --api-key <KEY> --jianying-draft-dir auto -y
 ```
 gtrk-cli/
 ├── src/index.ts              # commander 入口
-├── src/commands/             # 子命令：install / init / oralcut / split / doctor / upgrade / skills
+├── src/commands/             # 子命令：install / init / oralcut / transcript / split / doctor / upgrade / skills
 ├── src/lib/                  # cloud / column-config / splitdoc / projection / user-config / jianying / …
-├── skills/                   # 打包的框架 skills：gtrk-oralcut / splitter / matrix / mg / ai-drama / style-maker
+├── skills/                   # 打包的框架 skills：oralcut / splitter / matrix / mg / ai-drama / style-maker / transcript / tools
 ├── contracts/                # 框架契约库正本（gsap-emit v1 + handoff→契约映射表）
 ├── assets/                   # 剪映草稿目录指引图
 └── AGENT.md                  # 可移植 agent playbook（skill 底座）