cutsdk 0.0.1 → 1.1.0

package/dist/api/masks/get-masks.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMasks = getMasks;
+const draft_service_1 = require("../../shared/draft-service");
+async function getMasks(params) {
+    const draft = await (0, draft_service_1.loadDraft)(params.draftId);
+    const masks = draft.materials?.masks || [];
+    if (!params.segmentId) {
+        const results = [];
+        for (const track of draft.tracks || []) {
+            for (const segment of track.segments || []) {
+                const refs = segment.extra_material_refs || [];
+                for (const mask of masks) {
+                    if (refs.includes(mask.id))
+                        results.push(toMaskInfo(mask));
+                }
+            }
+        }
+        return results.length > 0 ? results : masks.map(toMaskInfo);
+    }
+    const segment = draft.get_segment_by_id(params.segmentId);
+    if (!segment)
+        return [];
+    const refs = segment.extra_material_refs || [];
+    return masks.filter((m) => refs.includes(m.id)).map(toMaskInfo);
+}
+function toMaskInfo(m) {
+    return {
+        id: m.id,
+        name: m.name || '',
+        resourceType: m.resource_type || '',
+        config: {
+            centerX: m.config?.centerX || 0,
+            centerY: m.config?.centerY || 0,
+            width: m.config?.width || 0,
+            height: m.config?.height || 0,
+            feather: m.config?.feather || 0,
+            rotation: m.config?.rotation || 0,
+            invert: m.config?.invert || false,
+            roundCorner: m.config?.roundCorner || 0,
+        },
+    };
+}
+//# sourceMappingURL=get-masks.js.map

package/dist/api/masks/get-masks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-masks.js","sourceRoot":"","sources":["../../../src/api/masks/get-masks.ts"],"names":[],"mappings":";;AAGA,4BAsBC;AAzBD,8DAAuD;AAGhD,KAAK,UAAU,QAAQ,CAAC,MAA+C;IAC5E,MAAM,KAAK,GAAG,MAAM,IAAA,yBAAS,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAU,KAAK,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC;IAElD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,OAAO,GAAe,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YACvC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAa,OAAO,CAAC,mBAAmB,IAAI,EAAE,CAAC;gBACzD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;wBAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC7D,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,IAAI,GAAa,OAAO,CAAC,mBAAmB,IAAI,EAAE,CAAC;IACzD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,UAAU,CAAC,CAAM;IACxB,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE;QAClB,YAAY,EAAE,CAAC,CAAC,aAAa,IAAI,EAAE;QACnC,MAAM,EAAE;YACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC;YAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;YAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC;YAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,IAAI,CAAC;YACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,IAAI,KAAK;YACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,WAAW,IAAI,CAAC;SACxC;KACF,CAAC;AACJ,CAAC"}

package/dist/api/query/get-audio-duration.d.ts

@@ -0,0 +1,3 @@
+import type { GetAudioDurationInput, GetAudioDurationOutput } from '../../types';
+export declare function getAudioDurationApi(params: GetAudioDurationInput): Promise<GetAudioDurationOutput>;
+//# sourceMappingURL=get-audio-duration.d.ts.map

package/dist/api/query/get-audio-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-audio-duration.d.ts","sourceRoot":"","sources":["../../../src/api/query/get-audio-duration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEjF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAMxG"}

package/dist/api/query/get-audio-duration.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAudioDurationApi = getAudioDurationApi;
+const media_1 = require("../../shared/media");
+async function getAudioDurationApi(params) {
+    const duration = await (0, media_1.getAudioDuration)(params.url);
+    if (duration === 0) {
+        return { message: 'Failed to get audio duration', duration: 0 };
+    }
+    return { message: 'ok', duration };
+}
+//# sourceMappingURL=get-audio-duration.js.map

package/dist/api/query/get-audio-duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-audio-duration.js","sourceRoot":"","sources":["../../../src/api/query/get-audio-duration.ts"],"names":[],"mappings":";;AAGA,kDAMC;AATD,8CAA8E;AAGvE,KAAK,UAAU,mBAAmB,CAAC,MAA6B;IACrE,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAoB,EAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACxD,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,8BAA8B,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACrC,CAAC"}

package/dist/api/query/get-image-animations.d.ts

@@ -0,0 +1,3 @@
+import type { GetImageAnimationsInput, GetImageAnimationsOutput } from '../../types';
+export declare function getImageAnimations(params?: GetImageAnimationsInput): Promise<GetImageAnimationsOutput>;
+//# sourceMappingURL=get-image-animations.d.ts.map

package/dist/api/query/get-image-animations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-image-animations.d.ts","sourceRoot":"","sources":["../../../src/api/query/get-image-animations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAIrF,wBAAsB,kBAAkB,CAAC,MAAM,GAAE,uBAA4B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAehH"}

package/dist/api/query/get-image-animations.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getImageAnimations = getImageAnimations;
+const { Draft } = require('../../draft');
+async function getImageAnimations(params = {}) {
+    const mode = params.mode || 0;
+    const type = params.type || 'in';
+    const draft = new Draft();
+    let effects;
+    if (type === 'loop') {
+        effects = draft.get_all_video_loop_Effects(mode);
+    }
+    else if (type === 'out') {
+        effects = draft.get_all_video_chuchang_Effects(mode);
+    }
+    else {
+        effects = draft.get_all_video_ruchang_Effects(mode);
+    }
+    return { effects };
+}
+//# sourceMappingURL=get-image-animations.js.map

package/dist/api/query/get-image-animations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-image-animations.js","sourceRoot":"","sources":["../../../src/api/query/get-image-animations.ts"],"names":[],"mappings":";;AAIA,gDAeC;AAjBD,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAElC,KAAK,UAAU,kBAAkB,CAAC,SAAkC,EAAE;IAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;IAE1B,IAAI,OAAc,CAAC;IACnB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,GAAG,KAAK,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;SAAM,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QAC1B,OAAO,GAAG,KAAK,CAAC,8BAA8B,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,KAAK,CAAC,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/api/query/get-text-effects.d.ts

@@ -0,0 +1,4 @@
+import type { GetTextEffectInput, GetTextEffectOutput, GetTextEffectsInput, GetTextEffectsOutput } from '../../types';
+export declare function getTextEffects(params?: GetTextEffectsInput): Promise<GetTextEffectsOutput>;
+export declare function getTextEffect(params: GetTextEffectInput): Promise<GetTextEffectOutput>;
+//# sourceMappingURL=get-text-effects.d.ts.map

package/dist/api/query/get-text-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-text-effects.d.ts","sourceRoot":"","sources":["../../../src/api/query/get-text-effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EAErB,MAAM,aAAa,CAAC;AAerB,wBAAsB,cAAc,CAAC,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAUpG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAS5F"}

package/dist/api/query/get-text-effects.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTextEffects = getTextEffects;
+exports.getTextEffect = getTextEffect;
+const { fetch_all_huazi, fetch_huazi_by_title, search_huazi_by_keyword } = require('../../draft/drafts/data/huazi/online_huazi');
+function toTextEffectInfo(item) {
+    const attr = item?.common_attr || {};
+    return {
+        title: attr.title || '',
+        effectId: attr.effect_id,
+        description: attr.description,
+        isVip: attr.is_vip,
+        raw: item,
+    };
+}
+async function getTextEffects(params = {}) {
+    const limit = params.limit && params.limit > 0 ? params.limit : 20;
+    const keyword = params.keyword || '';
+    const items = keyword
+        ? await search_huazi_by_keyword(keyword, limit)
+        : (await fetch_all_huazi(false)).slice(0, limit);
+    return {
+        effects: items.map(toTextEffectInfo).filter((item) => item.title),
+    };
+}
+async function getTextEffect(params) {
+    const effect = await fetch_huazi_by_title(params.name);
+    if (!effect)
+        return { effect: null, exact: false };
+    const info = toTextEffectInfo(effect);
+    return {
+        effect: info,
+        exact: info.title === params.name,
+    };
+}
+//# sourceMappingURL=get-text-effects.js.map

package/dist/api/query/get-text-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-text-effects.js","sourceRoot":"","sources":["../../../src/api/query/get-text-effects.ts"],"names":[],"mappings":";;AAqBA,wCAUC;AAED,sCASC;AAlCD,MAAM,EAAE,eAAe,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC,4CAA4C,CAAC,CAAC;AAEjI,SAAS,gBAAgB,CAAC,IAAS;IACjC,MAAM,IAAI,GAAG,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC;IACrC,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;QACvB,QAAQ,EAAE,IAAI,CAAC,SAAS;QACxB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,GAAG,EAAE,IAAI;KACV,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,cAAc,CAAC,SAA8B,EAAE;IACnE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,OAAO;QACnB,CAAC,CAAC,MAAM,uBAAuB,CAAC,OAAO,EAAE,KAAK,CAAC;QAC/C,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAEnD,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAoB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;KAClF,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,aAAa,CAAC,MAA0B;IAC5D,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAEnD,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,MAAM,CAAC,IAAI;KAClC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,92 @@
+---
+name: cut-draft
+description: >-
+  使用 cutsdk 创建和操作剪映/CapCut 草稿工程。用户想创建剪映草稿、添加字幕/图片/视频/音频/特效/贴纸/关键帧/遮罩、
+  提交渲染，或提到 cutsdk、cutcli、draft spec、剪映、草稿、字幕、CapCut draft 时使用此 skill。
+---
+
+# cutcli 项目级 Skill
+
+`cutsdk` 是用于创建剪映/CapCut 桌面端草稿文件夹的 Node.js SDK。`cutcli` 是给 AI 实时调用的命令行工具。生成后的草稿可直接在剪映桌面端打开。
+
+## 先读这些
+
+写代码前，先阅读本项目内的文档：
+
+1. `cutcli-docs/README.md`
+2. `cutcli-docs/quickstart.md`
+3. `cutcli-docs/api-cheatsheet.md`
+
+实现时优先从 `cutcli-docs/examples/` 里选择最接近的示例改起。
+
+## 推荐使用路径
+
+- 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`。
+- 需要实时命令行操作时，优先使用便捷命令，例如 `cutcli image add ...`、`cutcli text add ...`、`cutcli audio add ...`。
+
+## 关键规则
+
+- 包导入名是 `cutsdk`。
+- 低层 SDK 的数字时间单位是微秒：`1s = 1000000`。
+- `cutcli` 便捷命令和 AI Draft Spec 的时间字符串可写为 `1.5s`、`500ms`、`300000us`。
+- 默认草稿目录是 `~/Movies/JianyingPro Drafts/{draftId}/`；可通过 `CUT_DRAFTS_DIR` 覆盖。
+- 媒体本地路径和 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 示例
+
+保存为 `draft.json`：
+
+```json
+{
+  "version": "1.0",
+  "canvas": { "width": 1080, "height": 1920 },
+  "tracks": [
+    {
+      "type": "text",
+      "clips": [
+        { "type": "caption", "text": "你好剪映", "start": "0s", "duration": "3s" }
+      ]
+    }
+  ]
+}
+```
+
+然后执行：
+
+```bash
+cutcli spec validate --file draft.json --pretty
+cutcli spec create --file draft.json --pretty
+```
+
+## 云渲染环境变量
+
+云渲染需要 API Token。优先让用户运行：
+
+```bash
+cutcli login <apiToken>
+```
+
+也可以使用环境变量：
+
+```env
+CUT_API_TOKEN=your_token
+```
+
+`cutcli login` 会把 Token 保存到本机 `~/.cutcli/config.json`；`cutcli config show` 只显示 `<set>`，不会打印 Token 明文。
+
+## 常见坑
+
+1. 不要混用包名。除非项目明确覆盖，否则始终使用 `cutsdk`。
+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/cutcli-docs/.env.example

@@ -0,0 +1,6 @@
+# 可选：本地剪映草稿文件夹创建位置。
+# macOS 默认路径是 ~/Movies/JianyingPro Drafts
+CUT_DRAFTS_DIR=/absolute/path/to/JianyingPro Drafts
+
+# 仅云渲染需要。
+CUT_API_TOKEN=your_render_api_token

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

@@ -0,0 +1,95 @@
+# cutsdk 项目接入指南
+
+这个目录是给 AI Agent 和开发者第一次在项目中使用 `cutsdk` 时看的接入资料。
+
+`cutsdk` 可以用 Node.js 代码创建剪映/CapCut 桌面端草稿文件夹，支持字幕、图片、视频、音频、特效、贴纸、关键帧、遮罩、AI Draft Spec，以及可选的云渲染。
+
+## 阅读顺序
+
+1. 先读 `quickstart.md`。
+2. 再扫一遍 `api-cheatsheet.md`。
+3. 从 `examples/` 中复制最接近需求的示例改起。
+
+## 安装
+
+```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/cutcli-docs/api-cheatsheet.md

@@ -0,0 +1,156 @@
+# cutsdk API 速查
+
+从 `cutsdk` 导入：
+
+```ts
+import {
+  createDraftFromSpec,
+  validateDraftSpec,
+  createAndRenderDraft,
+  createDraft,
+  getDraftInfo,
+  addCaptions,
+  addImages,
+  addVideos,
+  addAudios,
+  addEffects,
+  addSticker,
+  addKeyframes,
+  addMasks,
+  getTextEffects,
+  getTextEffect,
+  renderDraft,
+  isCutSdkError,
+} from 'cutsdk';
+```
+
+## 优先选择：AI Draft Spec
+
+```ts
+const result = await createDraftFromSpec({
+  version: '1.0',
+  canvas: { width: 1080, height: 1920 },
+  duration: '5s',
+  tracks: [
+    { type: 'text', clips: [{ type: 'caption', text: 'Hello', start: '0s', duration: '5s' }] },
+  ],
+});
+```
+
+用于一次性生成完整时间线。
+
+## 创建并渲染
+
+```ts
+const result = await createAndRenderDraft({
+  draft: spec,
+  output: {
+    draftsDir: process.env.CUT_DRAFTS_DIR,
+    name: 'demo-draft',
+  },
+  render: {
+    cloud: true,
+    apiToken: process.env.CUT_API_TOKEN,
+  },
+});
+
+console.log(result.render?.videoUrl);
+```
+
+## 低层草稿流程
+
+```ts
+const draft = await createDraft({ width: 1080, height: 1920 });
+
+await addImages({
+  draftId: draft.draftId,
+  imageInfos: [
+    { imageUrl: '/absolute/path/bg.png', width: 1080, height: 1920, start: 0, end: 5000000 },
+  ],
+});
+
+await addCaptions({
+  draftId: draft.draftId,
+  captions: [{ text: 'Hello', start: 0, end: 5000000 }],
+  fontSize: 8,
+  textColor: '#ffffff',
+  textEffect: '红黄火焰综艺花字',
+  hasShadow: true,
+});
+```
+
+需要逐步添加素材或操作时使用这种方式。
+
+## 时间
+
+低层 API 使用微秒：
+
+| 人类时间 | 数值 |
+|------------|-------|
+| 0.5s | `500000` |
+| 1s | `1000000` |
+| 3s | `3000000` |
+| 10s | `10000000` |
+
+Draft Spec 可以使用字符串：
+
+```ts
+'1.5s'
+'500ms'
+'300000us'
+```
+
+## 错误处理
+
+```ts
+try {
+  await createDraftFromSpec(spec);
+} catch (error) {
+  if (isCutSdkError(error)) {
+    console.error(error.code, error.operation, error.details);
+  } else {
+    console.error(error);
+  }
+}
+```
+
+常见错误码：
+
+| code | 含义 |
+|------|---------|
+| `INVALID_INPUT` | SDK 参数不合法 |
+| `DRAFT_NOT_FOUND` | 草稿 ID 或草稿文件夹不存在 |
+| `MEDIA_NOT_FOUND` | 本地媒体文件不存在 |
+| `MEDIA_DOWNLOAD_FAILED` | 远程媒体下载失败 |
+| `MISSING_API_TOKEN` | 缺少云渲染 token |
+| `DRAFT_SPEC_VALIDATION_FAILED` | Draft Spec 校验失败 |
+| `DRAFT_SPEC_RESOLVE_FAILED` | Draft Spec 无法归一化 |
+
+## 对应 CLI 命令
+
+```bash
+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/cutcli-docs/examples/01-create-draft.ts

@@ -0,0 +1,43 @@
+import { addCaptions, addImages, createDraft, getDraftInfo } from 'cutsdk';
+
+async function main() {
+  const draft = await createDraft({ width: 1080, height: 1920 });
+
+  await addImages({
+    draftId: draft.draftId,
+    imageInfos: [
+      {
+        imageUrl: '/absolute/path/to/background.png',
+        width: 1080,
+        height: 1920,
+        start: 0,
+        end: 5000000,
+      },
+    ],
+  });
+
+  await addCaptions({
+    draftId: draft.draftId,
+    captions: [
+      {
+        text: '低层 SDK 示例',
+        start: 0,
+        end: 5000000,
+        keyword: 'SDK',
+        keywordColor: '#00ffaa',
+      },
+    ],
+    fontSize: 8,
+    textColor: '#ffffff',
+    bold: true,
+    transformY: -0.65,
+  });
+
+  const info = await getDraftInfo({ draftId: draft.draftId });
+  console.log({ draft, info });
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/api/setup/templates/project/cutcli-docs/examples/02-draft-spec.ts

@@ -0,0 +1,73 @@
+import { createDraftFromSpec, validateDraftSpec } from 'cutsdk';
+
+const spec = {
+  version: '1.0',
+  canvas: { width: 1080, height: 1920 },
+  duration: '6s',
+  assets: {
+    cover: {
+      type: 'image',
+      src: '/absolute/path/to/cover.png',
+      width: 1080,
+      height: 1920,
+    },
+    bgm: {
+      type: 'audio',
+      src: '/absolute/path/to/music.mp3',
+      duration: '6s',
+    },
+  },
+  styles: {
+    title: {
+      fontSize: 10,
+      color: '#ffffff',
+      bold: true,
+      shadow: true,
+    },
+  },
+  tracks: [
+    {
+      type: 'visual',
+      clips: [
+        { type: 'image', asset: 'cover', start: '0s', duration: '6s' },
+      ],
+    },
+    {
+      type: 'text',
+      clips: [
+        {
+          type: 'caption',
+          text: 'AI Draft Spec 示例',
+          style: 'title',
+          keyword: 'AI|Spec',
+          keywordColor: '#00ffaa',
+          start: '0s',
+          duration: '6s',
+          position: 'bottom',
+        },
+      ],
+    },
+    {
+      type: 'audio',
+      clips: [
+        { type: 'audio', asset: 'bgm', start: '0s', duration: '6s', volume: 0.7 },
+      ],
+    },
+  ],
+} as const;
+
+async function main() {
+  const validation = validateDraftSpec(spec);
+  if (!validation.valid) {
+    console.error(validation.errors);
+    process.exit(1);
+  }
+
+  const draft = await createDraftFromSpec(spec);
+  console.log(draft);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});