cutsdk 1.0.0 → 1.1.1

package/dist/api/setup/templates/project/.agents/skills/cut-draft/SKILL.md

@@ -2,76 +2,102 @@
 name: cut-draft
 description: >-
   使用 cutsdk 创建和操作剪映/CapCut 草稿工程。用户想创建剪映草稿、添加字幕/图片/视频/音频/特效/贴纸/关键帧/遮罩、
-  提交渲染，或提到 cut_sdk、cut、draft spec、剪映、草稿、字幕、CapCut draft 时使用此 skill。
+  提交渲染，或提到 cutsdk、cutcli、draft spec、剪映、草稿、字幕、CapCut draft 时使用此 skill。
 ---
 
-# cut_sdk 项目级 Skill
+# cutcli 项目级 Skill
 
-`cutsdk` 是用于创建剪映/CapCut 桌面端草稿文件夹的 Node.js SDK 和 CLI。生成后的草稿可直接在剪映桌面端打开。
+`cutsdk` 是用于创建剪映/CapCut 桌面端草稿文件夹的 Node.js SDK。`cutcli` 是给 AI 实时调用的命令行工具。生成后的草稿可直接在剪映桌面端打开。
 
 ## 先读这些
 
 写代码前，先阅读本项目内的文档：
 
-1. `cut-sdk/README.md`
-2. `cut-sdk/quickstart.md`
-3. `cut-sdk/api-cheatsheet.md`
+1. `cutcli-docs/README.md`
+2. `cutcli-docs/quickstart.md`
+3. `cutcli-docs/api-cheatsheet.md`
 
-实现时优先从 `cut-sdk/examples/` 里选择最接近的示例改起。
+实现时优先从 `cutcli-docs/examples/` 里选择最接近的示例改起。
 
 ## 推荐使用路径
 
-- AI 生成完整时间线时，优先使用 `createDraftFromSpec(spec)`。
-- 用户希望“一次创建草稿并提交云渲染”时，使用 `createAndRenderDraft(input)`。
+- AI 生成完整时间线时，优先使用 `cutcli spec create --file draft.json`，或在代码中使用 `createDraftFromSpec(spec)`。
+- 用户希望“一次创建草稿并提交云渲染”时，优先使用 `cutcli spec render --file draft.json --cloud --wait`，或在代码中使用 `createAndRenderDraft(input)`。
 - 用户要逐步编辑草稿，或 Draft Spec 尚未覆盖某个能力时，再使用低层 API，例如 `createDraft`、`addCaptions`、`addImages`、`addVideos`、`addAudios`、`addMasks`、`addKeyframes`。
-- 只有在用户明确需要命令行，或只是做快速手动操作时，才使用 CLI。
+- 需要实时命令行操作时，优先使用便捷命令，例如 `cutcli image add ...`、`cutcli text add ...`、`cutcli audio add ...`。
 
 ## 关键规则
 
 - 包导入名是 `cutsdk`。
-- 低层 SDK 和 CLI 的所有时间数值都是微秒：`1s = 1000000`。
-- AI Draft Spec 的时间字符串可写为 `1.5s`、`500ms`、`300000us`。
+- 低层 SDK 的数字时间单位是微秒：`1s = 1000000`。
+- `cutcli` 便捷命令和 AI Draft Spec 的时间字符串可写为 `1.5s`、`500ms`、`300000us`。
 - 默认草稿目录是 `~/Movies/JianyingPro Drafts/{draftId}/`；可通过 `CUT_DRAFTS_DIR` 覆盖。
-- 媒体 URL 和本地媒体路径会由 SDK 复制/下载到草稿的 `resources/` 文件夹。
+- 媒体本地路径和 URL 都可用：本地路径会复制到草稿 `resources/`，URL 会下载到 `resources/`。
 - 图片必须提供 `width` 和 `height`。
 - 使用低层 API 添加视频或音频时，要提供素材原始时长。
 - 同一轨道内的片段不要重叠，除非目标 API 明确会创建独立轨道。
 - CLI 参数使用 kebab-case，例如 `--font-size`，不要写成 `--fontSize`。
+- 云渲染只有 `status = 7` 才算成功并写入 `video_url`；`0/1/2` 表示等待或处理中，`3/5/6` 表示失败终态。
+- AI 调用 CLI 时，如需结构化错误，使用 `--json-errors` 或 `CUTCLI_JSON_ERRORS=1`。
 
 ## 最小 Draft Spec 示例
 
-```ts
-import { createDraftFromSpec } from 'cutsdk';
+保存为 `draft.json`：
 
-await createDraftFromSpec({
-  version: '1.0',
-  canvas: { width: 1080, height: 1920 },
-  tracks: [
+```json
+{
+  "version": "1.0",
+  "canvas": { "width": 1080, "height": 1920 },
+  "tracks": [
     {
-      type: 'text',
-      clips: [
-        { type: 'caption', text: '你好剪映', start: '0s', duration: '3s' },
-      ],
-    },
-  ],
-});
+      "type": "text",
+      "clips": [
+        { "type": "caption", "text": "你好剪映", "start": "0s", "duration": "3s" }
+      ]
+    }
+  ]
+}
 ```
 
-## 云渲染环境变量
+然后执行：
 
-云渲染需要：
-
-```env
-CUT_API_TOKEN=your_token
-CUT_UPLOAD_API_BASE=http://your-render-backend:8080
+```bash
+cutcli spec validate --file draft.json --pretty
+cutcli spec create --file draft.json --pretty
 ```
 
-在调用方项目中使用 `.env`，或在调用 SDK 前自行加载环境变量。
+## 云渲染与 API Token 配置
+
+云渲染需要配置 API Token，有以下三种方式：
+
+1. **命令行保存**：
+   ```bash
+   cutcli login <apiToken>
+   ```
+   这会将 Token 保存到本机 `~/.cutcli/config.json`。
+
+2. **环境变量**：
+   设置环境变量 `CUT_API_TOKEN`：
+   ```env
+   CUT_API_TOKEN=your_token
+   ```
+
+3. **SDK 参数显式传入**：
+   在调用一站式 SDK 时显式设置 `apiToken` 字段：
+   ```typescript
+   render: {
+     cloud: true,
+     apiToken: 'your_api_token'
+   }
+   ```
+
+`cutcli config show` 可检查配置状态，它只会显示 `<set>`，不会打印 Token 明文。
 
 ## 常见坑
 
 1. 不要混用包名。除非项目明确覆盖，否则始终使用 `cutsdk`。
-2. 不要把“秒”直接作为低层 API 的数字传入。数字 `3` 表示 3 微秒，不是 3 秒。
-3. 对动画/特效名有精确要求时，不要凭空编造。先用 CLI 查询可用资源，或使用项目里已有示例。
-4. 除非 SDK 无法表达目标操作，否则不要手动改剪映草稿 JSON。
-5. 生成复杂时间线时，先用 `validateDraftSpec(spec)` 校验 Draft Spec。
+2. 本地拼接优先用 `cutcli image/video/audio/text add`；批量 JSON 命令只在需要一次添加多段素材时使用。
+3. 不要把“秒”直接作为低层 API 的数字传入。数字 `3` 表示 3 微秒，不是 3 秒。
+4. 对动画/特效名有精确要求时，不要凭空编造。先用 CLI 查询可用资源，或使用项目里已有示例。
+5. 除非 SDK 无法表达目标操作，否则不要手动改剪映草稿 JSON。
+6. 生成复杂时间线时，先用 `cutcli spec validate --file draft.json` 或 `validateDraftSpec(spec)` 校验 Draft Spec。

package/dist/api/setup/templates/project/{cut-sdk → cutcli-docs}/.env.example

@@ -4,4 +4,3 @@ CUT_DRAFTS_DIR=/absolute/path/to/JianyingPro Drafts
 
 # 仅云渲染需要。
 CUT_API_TOKEN=your_render_api_token
-CUT_UPLOAD_API_BASE=http://your-render-backend:8080

package/dist/api/setup/templates/project/cutcli-docs/README.md

@@ -0,0 +1,96 @@
+# cutsdk 项目接入指南
+
+这个目录是给 AI Agent 和开发者第一次在项目中使用 `cutsdk` 时看的接入资料。
+
+`cutsdk` 可以用 Node.js 代码创建剪映/CapCut 桌面端草稿文件夹，支持字幕、图片、视频、音频、特效、贴纸、关键帧、遮罩、AI Draft Spec，以及可选的云渲染。
+
+## 阅读顺序
+
+1. 先读 `quickstart.md`。
+2. 再扫一遍 `api-cheatsheet.md`。
+3. 从 `examples/` 中复制最接近需求的示例改起。
+4. 需要挑选花字、特效、贴纸、转场时，直接打开 `material-browser.html`。特效/转场使用本地在线缓存，贴纸会联网刷新全量素材库。
+
+## 安装
+
+```bash
+npm install cutsdk
+```
+
+如果要使用 CLI：
+
+```bash
+npm install -g @cutcli/cutcli
+cutcli agents install
+cutcli login <apiToken>
+cutcli spec validate --file draft.json
+cutcli spec create --file draft.json
+```
+
+不全局安装也可以直接用 `npx`：
+
+```bash
+npx @cutcli/cutcli spec create --file draft.json
+```
+
+## 环境变量
+
+当项目需要自定义草稿目录或使用云渲染时，把 `.env.example` 复制为 `.env` 并填写：
+
+```env
+CUT_DRAFTS_DIR=/absolute/path/to/JianyingPro Drafts
+CUT_API_TOKEN=your_token
+```
+
+也可以用 CLI 保存云渲染 Token：
+
+```bash
+cutcli login <apiToken>
+cutcli config show --pretty
+```
+
+Token 会保存到本机 `~/.cutcli/config.json`，输出中只显示 `<set>`。
+
+云渲染状态码：
+
+| status | 含义 |
+|--------|------|
+| `0` | 初始创建，尚未正式入队 |
+| `1` | 已提交/排队中，等待云渲染机器领取 |
+| `2` | 处理中，机器已领取任务并开始渲染 |
+| `3` | 草稿 ID 异常或草稿 ID 不存在 |
+| `5` | 处理超时 |
+| `6` | 处理失败 |
+| `7` | 成功完成，此时才会写入 `video_url` |
+
+## 核心概念
+
+- 一个草稿就是磁盘上的剪映兼容工程文件夹。
+- 默认草稿路径是 `~/Movies/JianyingPro Drafts/{draftId}/`。
+- 低层 SDK API 的时间数值使用微秒。
+- AI Draft Spec 和 `cutcli image/text/audio/video add` 支持更易读的时间字符串，例如 `3s`、`500ms`、`300000us`。
+- 媒体 URL 和本地文件路径会被复制/下载到草稿的 `resources` 文件夹。
+
+## 推荐优先使用
+
+AI 生成视频草稿时，优先使用 `createDraftFromSpec`。它允许用一个 JSON 对象描述完整时间线，再由 SDK 调用底层草稿 API。
+
+创建草稿后还需要补充高级操作时，可以使用带 `afterCreate` 的 `createAndRenderDraft`，或直接调用低层 API。
+
+使用命令行时，优先使用：
+
+```bash
+cutcli spec validate --file draft.json --pretty
+cutcli spec create --file draft.json --pretty
+cutcli spec render --file draft.json --cloud --wait --pretty
+```
+
+逐步修改草稿时，优先使用便捷命令：
+
+```bash
+cutcli text add <draftId> --text "标题" --start 0s --duration 3s --font-size 8
+cutcli image add <draftId> --src ./素材/bg.png --start 0s --duration 5s --width 1080 --height 1920
+cutcli audio add <draftId> --src ./素材/bgm.mp3 --start 0s --duration 20s
+```
+
+AI 调用 CLI 时，如果需要结构化错误输出，可以加 `--json-errors` 或设置 `CUTCLI_JSON_ERRORS=1`。

package/dist/api/setup/templates/project/{cut-sdk → cutcli-docs}/api-cheatsheet.md

@@ -1,4 +1,4 @@
-# cut_sdk API 速查
+# cutsdk API 速查
 
 从 `cutsdk` 导入：
 
@@ -17,6 +17,8 @@ import {
   addSticker,
   addKeyframes,
   addMasks,
+  getTextEffects,
+  getTextEffect,
   renderDraft,
   isCutSdkError,
 } from 'cutsdk';
@@ -49,7 +51,6 @@ const result = await createAndRenderDraft({
   render: {
     cloud: true,
     apiToken: process.env.CUT_API_TOKEN,
-    apiBase: process.env.CUT_UPLOAD_API_BASE,
   },
 });
 
@@ -73,6 +74,8 @@ await addCaptions({
   captions: [{ text: 'Hello', start: 0, end: 5000000 }],
   fontSize: 8,
   textColor: '#ffffff',
+  textEffect: '红黄火焰综艺花字',
+  hasShadow: true,
 });
 ```
 
@@ -126,7 +129,28 @@ try {
 ## 对应 CLI 命令
 
 ```bash
-cut draft create --width 1080 --height 1920
-cut captions add <draftId> --captions '[{"text":"Hello","start":0,"end":3000000}]'
-cut cloud render <draftId> --wait
+cutcli draft create --width 1080 --height 1920
+cutcli query text-effects --keyword 火焰 --limit 5
+cutcli text add <draftId> --text "Hello" --start 0s --duration 3s
+cutcli image add <draftId> --src ./素材/bg.png --start 0s --duration 5s --width 1080 --height 1920
+cutcli cloud render <draftId> --wait
+```
+
+云渲染状态：
+
+| status | 含义 |
+|--------|------|
+| `0` | 初始创建，尚未正式入队 |
+| `1` | 已提交/排队中 |
+| `2` | 处理中 |
+| `3` | 草稿 ID 异常或不存在 |
+| `5` | 处理超时 |
+| `6` | 处理失败 |
+| `7` | 成功完成，读取 `video_url` |
+
+## 花字查询
+
+```ts
+const effects = await getTextEffects({ keyword: '火焰', limit: 5 });
+const exact = await getTextEffect({ name: effects.effects[0].title });
 ```

package/dist/api/setup/templates/project/{cut-sdk → cutcli-docs}/examples/03-create-and-render.ts

@@ -27,7 +27,7 @@ async function main() {
     },
     output: {
       draftsDir: process.env.CUT_DRAFTS_DIR,
-      name: 'cut-sdk-render-demo',
+      name: 'cutcli-render-demo',
     },
     afterCreate: async ({ draft, clip }) => {
       const firstImage = clip('image', 0);
@@ -52,7 +52,6 @@ async function main() {
     render: {
       cloud: true,
       apiToken: process.env.CUT_API_TOKEN,
-      apiBase: process.env.CUT_UPLOAD_API_BASE,
       wait: true,
     },
   });

package/dist/api/setup/templates/project/cutcli-docs/examples/04-cli-examples.md

@@ -0,0 +1,109 @@
+# cutcli CLI 示例
+
+当用户希望使用命令行而不是 SDK 代码时，参考这些示例。
+
+## 创建草稿
+
+```bash
+cutcli draft create --width 1080 --height 1920 --pretty
+```
+
+输出中会包含 `draftId`，后续命令都使用这个草稿 ID。
+
+## 使用 Draft Spec 创建完整草稿
+
+```bash
+cutcli spec validate --file draft.json --pretty
+cutcli spec create --file draft.json --pretty
+```
+
+需要云渲染时：
+
+```bash
+cutcli spec render --file draft.json --cloud --wait --pretty
+```
+
+## 便捷添加单个素材
+
+便捷命令支持 `1.5s`、`500ms`、`300000us` 这类时间字符串。
+
+```bash
+cutcli query text-effects --keyword 火焰 --limit 5 --pretty
+cutcli text add <draftId> --text "主标题" --start 0s --duration 3s --font-size 10 \
+  --text-effect "红黄火焰综艺花字" --border-color "#000000" --shadow --shadow-color "#000000" --pretty
+cutcli image add <draftId> --src ./素材/bg.png --start 0s --duration 5s --width 1080 --height 1920 \
+  --in-animation 渐显 --in-animation-duration 500ms --transition 叠化 --transition-duration 500ms --pretty
+cutcli audio add <draftId> --src ./素材/bgm.mp3 --start 0s --duration 20s --pretty
+cutcli video add <draftId> --src ./素材/clip.mp4 --start 5s --duration 3s --width 1080 --height 1920 \
+  --mask 圆形 --scale-x 0.9 --scale-y 0.9 --pretty
+```
+
+## 批量 JSON 命令
+
+单素材命令是本地拼接主路径。下面的 `captions/images/audios` 批量 JSON 命令用于一次添加多段素材，或需要更细字段时使用。
+
+### 添加字幕
+
+```bash
+cutcli captions add <draftId> --captions '[
+  {
+    "text": "CLI 字幕示例",
+    "start": 0,
+    "end": 3000000,
+    "keyword": "CLI",
+    "keywordColor": "#00ffaa",
+    "inAnimation": "渐显",
+    "outAnimation": "渐隐",
+    "inAnimationDuration": 500000,
+    "outAnimationDuration": 500000
+  }
+]' --font-size 8 --text-color "#ffffff" --bold --text-effect "红黄火焰综艺花字" --shadow --pretty
+```
+
+### 添加图片
+
+```bash
+cutcli images add <draftId> --image-infos '[
+  {
+    "imageUrl": "/absolute/path/to/background.png",
+    "width": 1080,
+    "height": 1920,
+    "start": 0,
+    "end": 5000000
+  }
+]' --scale-x 0.9 --scale-y 0.9 --transform-y 0.05 --pretty
+```
+
+### 添加音频
+
+```bash
+cutcli audios add <draftId> --audio-infos '[
+  {
+    "audioUrl": "/absolute/path/to/music.mp3",
+    "duration": 5000000,
+    "start": 0,
+    "end": 5000000,
+    "volume": 0.7
+  }
+]' --pretty
+```
+
+## 渲染
+
+首次使用云渲染前保存 Token：
+
+```bash
+cutcli login <apiToken>
+```
+
+```bash
+cutcli cloud render <draftId> --wait --pretty
+```
+
+## JSON 文件输入
+
+大多数 JSON 参数也支持 `@file.json`：
+
+```bash
+cutcli captions add <draftId> --captions @captions.json --pretty
+```