@gitruck/cli 0.2.8 → 0.2.9

package/package.json

@@ -1,62 +1,64 @@
-{
-  "name": "@gitruck/cli",
-  "version": "0.2.8",
-  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
-  "license": "MIT",
-  "author": "Gitruck (同合云)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Gitruck/cli.git"
-  },
-  "homepage": "https://github.com/Gitruck/cli#readme",
-  "bugs": {
-    "url": "https://github.com/Gitruck/cli/issues"
-  },
-  "type": "module",
-  "bin": {
-    "gtrk": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "assets",
-    "skills",
-    "contracts",
-    "AGENT.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20.6"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "gitruck",
-    "同合云",
-    "video",
-    "oral-cut",
-    "口播剪辑",
-    "cli",
-    "jianying",
-    "剪映",
-    "agent"
-  ],
-  "scripts": {
-    "gtrk": "bun run src/index.ts",
-    "build": "bun build ./src/index.ts --target=node --outfile dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run build",
-    "test": "esbuild src/lib/chunk-upload.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts src/lib/mg-lint.ts src/lib/mg-lay.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && node --test \"test/*.test.mjs\""
-  },
-  "devDependencies": {
-    "bun-types": "^1.1.0",
-    "commander": "^12.1.0",
-    "esbuild": "^0.28.1",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "hash-wasm": "^4.12.0"
-  }
-}
+{
+  "name": "@gitruck/cli",
+  "version": "0.2.9",
+  "description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
+  "license": "MIT",
+  "author": "Gitruck (同合云)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gitruck/cli.git"
+  },
+  "homepage": "https://github.com/Gitruck/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Gitruck/cli/issues"
+  },
+  "type": "module",
+  "bin": {
+    "gtrk": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "skills",
+    "contracts",
+    "AGENT.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "gitruck",
+    "同合云",
+    "video",
+    "oral-cut",
+    "口播剪辑",
+    "cli",
+    "jianying",
+    "剪映",
+    "agent"
+  ],
+  "scripts": {
+    "gtrk": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --target=node --outfile dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "test": "esbuild src/lib/chunk-upload.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/projection.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/column-config.ts src/lib/matrix.ts src/lib/matrix-lay.ts src/lib/mg-lint.ts src/lib/mg-lay.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --test \"test/*.test.mjs\""
+  },
+  "devDependencies": {
+    "@xmldom/xmldom": "^0.9.6",
+    "bun-types": "^1.1.0",
+    "commander": "^12.1.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "hash-wasm": "^4.12.0",
+    "jszip": "^3.10.1"
+  }
+}

package/skills/gtrk-tools/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: gtrk-tools
+description: gtrk 单点工具族的调用向导——一个 skill 覆盖 `gtrk tool` 家族的全部单发单收能力（图转运镜、图片抠像、视频抠像…）。当用户想「把这张图做成运镜视频 / 让图动起来 / 给图片抠像去背景 / 抠出主体 / 视频抠像出透明背景 / 用某个 gtrk 单点工具 / gtrk 工具族里有什么」时使用本 skill。凡涉及调 `gtrk tool <name>` 跑一个单点云端能力（非成片管线的 oralcut/split/matrix/mg 车道命令），优先用本 skill 驱动 CLI，别让用户自己去终端敲，也别手搓 ffmpeg。
+---
+
+# gtrk 工具族（gtrk-tools）
+
+`gtrk tool <name> [input]` 是 gtrk 的**单点能力**族：一个工具 = 单发单收（给一个输入、出一份产物），没有 SOP 次序、没有用户检查点链——与成片管线的车道命令（`oralcut` / `split` / `matrix` / `mg`）是两回事。本 skill 是这个族的**统一调用向导**：认清有哪些工具、按纪律驱动 `gtrk tool` 命令、把产物和计费如实回给用户。
+
+> **本 skill 已含你需要的全部信息**（工具清单、调用纪律、恢复语义、排错话术）。工具清单以 `gtrk tool list --json` 为**唯一真相**——本文件与它漂移时以命令输出为准并回来修本文件。参数细节以 `gtrk tool --help` 为准。
+
+## 工具清单（与 `gtrk tool list` 同源）
+
+| 工具名 | 触发语（用户可能怎么说） | 输入要求 | 产物形态 | 计费 | 可用状态 |
+|---|---|---|---|---|---|
+| `image_move` | 「把这张图做成运镜视频 / 让图动起来 / 图转视频」 | 单张图片 | 运镜视频 | 2 积分/个 | 已上线 |
+| `image_matting` | 「给图片抠像 / 抠出主体 / 去背景 / 出透明 png」 | 单张图片 | 透明背景 png | 免费 | 已上线 |
+| `video_matting` | 「视频抠像 / 视频去背景 / 出透明背景视频」 | 单条视频（≤10 分钟） | 透明背景 webm | 免费 | 已上线 |
+| `mad` | 「一键剪 MAD / 素材文件夹自动出卡点成片 / 自动选技法 / 给这堆素材出个 AE 工程」 | 一个素材文件夹（3~10 条视频）+ 可选 `--bgm 歌.mp3` | AE 母合成工程 `.jsx`（仅支持 AE） | 免费（`--bgm` 卡点计费一次） | 已上线 |
+
+> 清单随 CLI 版本增补。**动手前先跑 `gtrk tool list --json` 拿最新清单**，别凭记忆——新工具、状态变化都在那里。
+
+### mad（一键剪 MAD）的特殊之处
+
+`mad` 是族内首个 **local 型「纯本地工具、可选云端加料」**成员，与前三个 cloud 型不同：
+
+- **无 Key 可跑、零费用**：不带 `--bgm` 时全程只走免鉴权数据面（技法数据经云端 manifest 下发 + `~/.gitruck/mad-cache` 缓存），**首拉联网一次性下载、缓存命中后离线可跑**；不要求 API Key、不计费。
+- **`--bgm` 才需 Key 且计费一次**：带 `--bgm` 且已配 Key → BGM 卡点到 downbeat（调一次云端节拍分析计费）；没配 Key → **温和提示 `gtrk init` 可解锁卡点，不阻断**，BGM 仍入轨、按固定节奏出片；坏 BGM/云端失败一律降级不崩。
+- **产物只有 `.jsx`、只支持 AE**：完成后引导「装 AE 2020+ → 文件›脚本›运行脚本文件 选它」。**不承诺 `.amproj`/Alight Motion 等本命令未产出的形态**。
+- **可复现**：`--seed <n>` 固定选窗序列（同素材同种子同数据版本 → 同结果）；`result.json` 记录 seed、数据版本、降级档位、选中技法清单。
+- 常用：`gtrk tool mad ./素材 --bgm 歌.mp3 --duration 20 --json`。
+
+## 调用纪律（每次都照做）
+
+1. **先看清单、再对号**：用户的意图对到某个工具名（拿不准就 `gtrk tool list --json` 核对触发语与输入要求）。
+2. **执行前转述计费提示**：跑之前把该工具的计费（如「2 积分/个」或「免费」）如实告诉用户，让用户知情。免费的也说一句「这个免费」。
+3. **一律带 `--json`**：`gtrk tool <name> <输入> --json`。stdout 只会有一行结果 JSON（`{ ok, outDir, files, taskId, fileId, … }`），人读日志在 stderr。按 `ok` 判成败、从 `files` 拿产物路径、把 `outDir` 回给用户。
+4. **缺 API Key 先引导配置**：cloud 型工具没配 Key 会报错让先跑 `gtrk init`。遇到就引导用户 `gtrk init`（或设 `GITRUCK_API_KEY`），别反复重试。
+5. **产物落地与恢复**：产物落在 `outDir`（缺省 = 输入同目录下 `<输入名>-<工具名>/`，可 `--out <dir>` 覆盖）。提交成功即写 `task.json`（含 `taskId`）、完成即写 `result.json`。**若 `ok=false`**（任务完成但产物下载失败，如链接过期）：`result.json` 的 `errors` 有明细、`task.json` 保留——凭其中的 `taskId` 可稍后人工恢复取回，别急着重跑整条（重跑会重新计费）。
+6. **透传高级参数**：命令没为某个云端参数开 flag 时，用 `--param k=v`（可重复）或 `--params-json '<对象>'` 直接透传（如 `image_move` 想指定输出几何 `--param width=1080 --param height=1920`）。
+7. **单发单收、批量靠循环**：一次一个输入；用户要批处理就你逐个循环调，不是一条命令喂多文件。
+
+### 某工具显示「未开放」时怎么回应
+
+清单里若某工具状态为**未开放**（带原因），如实告诉用户「这个能力暂时没开放」即可——**不承诺开放时间点、不展开内部原因细节**。首批三个工具均已上线（抠像免费），此话术是通用兜底。
+
+## 与栏目生产 skill 的边界
+
+本 skill 是**框架向导**、不含任何审美/栏目设定：它只教「怎么调 `gtrk tool`」，不规定运镜风格、不规定抠像用在什么画面上——那些是你自己的创作判断或栏目资产的事。工具族只认「输入 → 产物」的通用契约。
+
+## 毕业条款
+
+某个工具若长出复杂度——需要多模式子命令、需要分步用户确认、需要注入栏目风格——它就该从工具族**毕业**成独立命令 / 独立 skill（照成片车道命令的先例）。毕业后旧的 `gtrk tool <名>` 会报错并指路新命令。你只要跟着 `gtrk tool list` 的当前清单走即可。