cutsdk 1.1.2 → 1.1.4

package/README.md

@@ -3,7 +3,7 @@
 CapCut / 剪映草稿 Node.js SDK。用于代码化、批量化创建剪映标准草稿，可直接被剪映桌面端打开，也可提交云渲染。
 
 - npm 包名：`cutsdk`
-- 当前发布版本：`1.1.0`（SDK 和 CLI 统一版本）
+- 当前发布版本：`1.1.4`（SDK 和 CLI 统一版本）
 - 版本迭代记录：[CHANGELOG.md](./CHANGELOG.md)
 
 - Node.js SDK，用于服务端、脚本和批量生成视频
@@ -58,26 +58,34 @@ await addCaptions({
 
 ### AI Draft Spec
 
-面向 AI 自动生成草稿时，推荐使用单一 JSON Spec：
+面向 AI 自动生成草稿、本地素材拼接和批量混剪时，推荐使用单一 JSON Spec，并用 `createAndRenderDraft` 统一处理输出目录、草稿名和可选云渲染：
 
 ```typescript
-import { createDraftFromSpec } from 'cutsdk';
-
-await createDraftFromSpec({
-  version: '1.0',
-  canvas: { width: 1080, height: 1920 },
-  duration: '3s',
-  tracks: [
-    {
-      type: 'text',
-      clips: [{ type: 'caption', text: '你好世界', start: '0s', duration: '3s' }],
-    },
-  ],
+import { createAndRenderDraft } from 'cutsdk';
+
+await createAndRenderDraft({
+  draft: {
+    version: '1.0',
+    canvas: { width: 1080, height: 1920 },
+    duration: '3s',
+    tracks: [
+      {
+        type: 'text',
+        clips: [{ type: 'caption', text: '你好世界', start: '0s', duration: '3s' }],
+      },
+    ],
+  },
+  output: {
+    draftsDir: '/Users/x013/jy_draft/JianyingPro Drafts',
+    name: '测试草稿',
+  },
+  render: false,
 });
 ```
 
 Spec 只是编排层，底层仍复用现有草稿创建和素材添加方法，保证导出的草稿格式不变。
 顶层 `duration` 可选；不传时会按时间线 clips 自动计算草稿总时长。
+`createDraftFromSpec(spec)` 也可直接创建草稿，但不能传输出目录和草稿名；需要这些控制时使用 `createAndRenderDraft`。
 
 需要创建后直接提交云渲染时，可以使用一站式 SDK：
 
@@ -107,6 +115,8 @@ const result = await createAndRenderDraft({
 console.log(result.render?.videoUrl);
 ```
 
+当前 Draft Spec 有两个批量限制需要提前考虑：同一个 Spec 内图片/视频 `transform` 会整批应用，不能每段素材独立设置不同 scale/position；字幕 `style`/`position` 也会整批应用，不能每条字幕完全不同位置样式。需要逐片段差异化时，先用 Spec 创建主体，再在 `afterCreate` 或低层 SDK API 里补后处理。
+
 ### 云渲染 API Token 配置
 
 `cutsdk` 和 `cutcli` 均支持将生成的草稿打包并提交至云端进行快速渲染。使用云渲染需要配置 API Token，有以下三种方式：
@@ -137,9 +147,11 @@ console.log(result.render?.videoUrl);
 CLI 可把项目级 AI 使用说明安装到业务项目：
 
 ```bash
-cutcli agents install
+npm install cutsdk && npx cutsdk init
 ```
 
+如果项目里已存在 `.agents/skills/cut-draft` 或 `cutcli-docs`，`npx cutsdk init` 会询问是否覆盖更新；输入 `y` 或 `yes` 才会覆盖。需要跳过询问时使用 `npx cutsdk init --force`。
+
 模板位于 `src/api/setup/templates/project/`，包含 `.agents/skills/cut-draft/SKILL.md`、SDK 快速开始、API 速查和示例代码。
 
 ## 文档

package/dist/api/setup/install-project-docs.d.ts

@@ -0,0 +1,13 @@
+export interface InstallProjectDocsOptions {
+    dir?: string;
+    force?: boolean;
+    onConflict?: (paths: string[]) => boolean;
+}
+export interface InstallProjectDocsResult {
+    targetDir: string;
+    installed: string[];
+    skipped: string[];
+}
+export declare function getProjectDocConflicts(options?: Pick<InstallProjectDocsOptions, 'dir'>): string[];
+export declare function installProjectDocs(options?: InstallProjectDocsOptions): InstallProjectDocsResult;
+//# sourceMappingURL=install-project-docs.d.ts.map

package/dist/api/setup/install-project-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-project-docs.d.ts","sourceRoot":"","sources":["../../../src/api/setup/install-project-docs.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAsBD,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,KAAK,CAAM,GAAG,MAAM,EAAE,CAKrG;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,wBAAwB,CAmBpG"}

package/dist/api/setup/install-project-docs.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProjectDocConflicts = getProjectDocConflicts;
+exports.installProjectDocs = installProjectDocs;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function getProjectDocTargets(targetDir) {
+    const sourceDir = path_1.default.join(__dirname, 'templates', 'project');
+    if (!fs_1.default.existsSync(sourceDir)) {
+        throw new Error(`cutsdk project template not found: ${sourceDir}`);
+    }
+    return [
+        {
+            from: path_1.default.join(sourceDir, '.agents', 'skills', 'cut-draft'),
+            to: path_1.default.join(targetDir, '.agents', 'skills', 'cut-draft'),
+        },
+        { from: path_1.default.join(sourceDir, 'cutcli-docs'), to: path_1.default.join(targetDir, 'cutcli-docs') },
+    ];
+}
+function getProjectDocConflicts(options = {}) {
+    const targetDir = path_1.default.resolve(options.dir || process.cwd());
+    return getProjectDocTargets(targetDir)
+        .filter((item) => fs_1.default.existsSync(item.to))
+        .map((item) => item.to);
+}
+function installProjectDocs(options = {}) {
+    const targetDir = path_1.default.resolve(options.dir || process.cwd());
+    const targets = getProjectDocTargets(targetDir);
+    const conflicts = targets.filter((item) => fs_1.default.existsSync(item.to)).map((item) => item.to);
+    const overwriteConflicts = Boolean(options.force || (conflicts.length > 0 && options.onConflict?.(conflicts)));
+    const installed = [];
+    const skipped = [];
+    for (const item of targets) {
+        const exists = fs_1.default.existsSync(item.to);
+        if (exists && !overwriteConflicts) {
+            skipped.push(item.to);
+            continue;
+        }
+        fs_1.default.cpSync(item.from, item.to, { recursive: true, force: exists ? overwriteConflicts : true });
+        installed.push(item.to);
+    }
+    return { targetDir, installed, skipped };
+}
+//# sourceMappingURL=install-project-docs.js.map

package/dist/api/setup/install-project-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-project-docs.js","sourceRoot":"","sources":["../../../src/api/setup/install-project-docs.ts"],"names":[],"mappings":";;;;;AAmCA,wDAKC;AAED,gDAmBC;AA7DD,4CAAoB;AACpB,gDAAwB;AAmBxB,SAAS,oBAAoB,CAAC,SAAiB;IAC7C,MAAM,SAAS,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,sCAAsC,SAAS,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO;QACL;YACE,IAAI,EAAE,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC;YAC5D,EAAE,EAAE,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC;SAC3D;QACD,EAAE,IAAI,EAAE,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,EAAE,EAAE,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE;KACvF,CAAC;AACJ,CAAC;AAED,SAAgB,sBAAsB,CAAC,UAAkD,EAAE;IACzF,MAAM,SAAS,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D,OAAO,oBAAoB,CAAC,SAAS,CAAC;SACnC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,SAAgB,kBAAkB,CAAC,UAAqC,EAAE;IACxE,MAAM,SAAS,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1F,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAE/G,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,YAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACtB,SAAS;QACX,CAAC;QACD,YAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9F,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC"}

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

@@ -1,13 +1,13 @@
 ---
 name: cut-draft
 description: >-
-  使用 cutsdk 创建和操作剪映/CapCut 草稿工程。用户想创建剪映草稿、添加字幕/图片/视频/音频/特效/贴纸/关键帧/遮罩、
-  提交渲染，或提到 cutsdk、cutcli、draft spec、剪映、草稿、字幕、CapCut draft 时使用此 skill。
+  使用 cutsdk/cutcli 创建和操作剪映/CapCut 草稿。用户想批量生成草稿、本地素材混剪、Agent 自动编排、
+  添加字幕/图片/视频/音频/特效/贴纸/关键帧/遮罩，或提到 Draft Spec、剪映、草稿、cutcli、cutsdk、CapCut draft 时使用此 skill。
 ---
 
-# cutcli 项目级 Skill
+# cutsdk / cutcli 项目级 Skill
 
-`cutsdk` 是用于创建剪映/CapCut 桌面端草稿文件夹的 Node.js SDK。`cutcli` 是给 AI 实时调用的命令行工具。生成后的草稿可直接在剪映桌面端打开。
+`cutsdk` 是用于创建剪映/CapCut 桌面端草稿文件夹的 Node.js SDK；`cutcli` 是命令行辅助工具。生成后的草稿可直接在剪映桌面端打开。
 
 ## 先读这些
 
@@ -17,21 +17,71 @@ description: >-
 2. `cutcli-docs/quickstart.md`
 3. `cutcli-docs/api-cheatsheet.md`
 
-实现时优先从 `cutcli-docs/examples/` 里选择最接近的示例改起。
+实现时优先从 `cutcli-docs/examples/` 里选择最接近的示例改起。需要挑选花字、特效、贴纸、转场时，打开 `cutcli-docs/material-browser.html`。
 
-## 推荐使用路径
+## 推荐路径
 
-- 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 ...`。
+1. **首选：AI Draft Spec + `createAndRenderDraft`**
+   用于本地素材拼接、批量生成草稿、Agent 自动编排、多轨时间线和模板化复用。需要指定草稿目录或草稿名时，使用 `createAndRenderDraft({ draft: spec, output, render: false })`。
+2. **次选：SDK 函数式 API**
+   用于创建后补关键帧、遮罩、特殊后处理，或 Draft Spec 暂未覆盖的能力。优先放在 `createAndRenderDraft` 的 `afterCreate` 里执行。
+3. **最后：`cutcli` 单命令**
+   用于临时测试、单素材追加、人工命令行调试。批量混剪不要围绕一串 CLI add 命令组织，优先生成 Spec。
+
+## 主路径示例
+
+```typescript
+import { createAndRenderDraft, validateDraftSpec } from 'cutsdk';
+
+const spec = {
+  version: '1.0',
+  canvas: { width: 1080, height: 1920 },
+  duration: '6s',
+  assets: {
+    cover: { type: 'image', src: '/absolute/path/cover.png', width: 1080, height: 1920 },
+    bgm: { type: 'audio', src: '/absolute/path/bgm.mp3', duration: '6s' },
+  },
+  tracks: [
+    {
+      type: 'visual',
+      clips: [{ type: 'image', asset: 'cover', start: '0s', duration: '6s' }],
+    },
+    {
+      type: 'text',
+      clips: [{ type: 'caption', text: '批量混剪示例', start: '0s', duration: '6s', position: 'bottom' }],
+    },
+    {
+      type: 'audio',
+      clips: [{ type: 'audio', asset: 'bgm', start: '0s', duration: '6s', volume: 0.7 }],
+    },
+  ],
+} as const;
+
+const validation = validateDraftSpec(spec);
+if (!validation.valid) {
+  throw new Error(JSON.stringify(validation.errors, null, 2));
+}
+
+const result = await createAndRenderDraft({
+  draft: spec,
+  output: {
+    draftsDir: '/absolute/path/JianyingPro Drafts',
+    name: '批量混剪-001',
+  },
+  render: false,
+});
+
+console.log(result.draft.filePath);
+```
+
+`createDraftFromSpec(spec)` 只能按当前配置创建草稿，不能直接传输出目录和草稿名；需要控制 `draftsDir` 或 `name` 时，使用上面的 `createAndRenderDraft`。
 
 ## 关键规则
 
 - 包导入名是 `cutsdk`。
-- 低层 SDK 的数字时间单位是微秒：`1s = 1000000`。
-- `cutcli` 便捷命令和 AI Draft Spec 的时间字符串可写为 `1.5s`、`500ms`、`300000us`。
-- 默认草稿目录是 `~/Movies/JianyingPro Drafts/{draftId}/`；可通过 `CUT_DRAFTS_DIR` 覆盖。
+- 低层 SDK 的数字时间单位是微秒，`1s = 1000000`。
+- AI Draft Spec 和 `cutcli` 便捷命令可写 `1.5s`、`500ms`、`300000us`。
+- 默认草稿目录是 `~/Movies/JianyingPro Drafts/{draftId}/`；可通过 `CUT_DRAFTS_DIR` 或 `createAndRenderDraft().output.draftsDir` 覆盖。
 - 媒体本地路径和 URL 都可用：本地路径会复制到草稿 `resources/`，URL 会下载到 `resources/`。
 - 图片必须提供 `width` 和 `height`。
 - 使用低层 API 添加视频或音频时，要提供素材原始时长。
@@ -40,64 +90,41 @@ description: >-
 - 云渲染只有 `status = 7` 才算成功并写入 `video_url`；`0/1/2` 表示等待或处理中，`3/5/6` 表示失败终态。
 - AI 调用 CLI 时，如需结构化错误，使用 `--json-errors` 或 `CUTCLI_JSON_ERRORS=1`。
 
-## 最小 Draft Spec 示例
+## 当前 Spec 限制
 
-保存为 `draft.json`：
+- 同一个 Spec 内，图片 `transform` 会被合并成一次 `addImages` 批量参数；所有图片的 `scaleX`、`scaleY`、`x`、`y`、`alpha` 必须一致，不能每张图独立设置。
+- 同一个 Spec 内，视频 `transform` 同理会整批应用，不能每段视频独立设置不同 transform。
+- 同一个 Spec 内，字幕 `style` 和 `position` 会被合并成一次 `addCaptions` 批量参数；不要在多条字幕上设置完全不同的位置或样式。
+- 需要逐片段差异化 transform、字幕位置、遮罩或关键帧时，先用 Spec 创建主体，再用 `afterCreate` 或低层 SDK API 后处理。
 
-```json
-{
-  "version": "1.0",
-  "canvas": { "width": 1080, "height": 1920 },
-  "tracks": [
-    {
-      "type": "text",
-      "clips": [
-        { "type": "caption", "text": "你好剪映", "start": "0s", "duration": "3s" }
-      ]
-    }
-  ]
-}
-```
+## 转场和素材名
+
+- 不要凭空编造转场、动画、花字或特效名。
+- 当前 CLI 可查询：`cutcli query image-animations --type in|out|loop`、`cutcli query text-effects --keyword 火焰 --limit 5`。
+- 转场优先从 `cutcli-docs/material-browser.html` 挑选名称；当前 CLI 还没有 `cutcli query transitions`，不要把它当成可用命令。
+- 如果遇到类似 `Cannot read properties of null` 的转场错误，通常是转场名没有匹配到。换成素材库中存在的名称，或先去掉转场完成草稿生成。
+
+## CLI 只作为补充
 
-然后执行：
+常用命令：
 
 ```bash
 cutcli spec validate --file draft.json --pretty
-cutcli spec create --file draft.json --pretty
+cutcli spec render --file draft.json --name "批量混剪-001" --drafts-dir "/absolute/path/JianyingPro Drafts" --pretty
+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
 ```
 
-## 云渲染与 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. 本地拼接优先用 `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。
+不要使用文档外的旧目录配置命令或旧内置文档命令。配置检查使用：
+
+```bash
+cutcli config show --pretty
+cutcli config doctor --pretty
+```
+
+## 产品改进记录
+
+- 更友好的 Spec 模板 DSL 可以建立在 Draft Spec 之上，例如 `createMontage({ output, canvas, durationPerImage, images, captions, style })`，内部展开为标准 Draft Spec。
+- 后续 SDK 可在 Spec validate 阶段校验转场名，错误提示应类似：`transition xxx not found，建议使用素材浏览器或 query transitions 返回的名称`。
+- 后续 SDK 可返回 `actualPath`、`displayName`、`draftFolderName`，并支持 `cleanupOnFailure: true` 清理失败半成品。

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

@@ -15,13 +15,15 @@
 
 ```bash
 npm install cutsdk
+npx cutsdk init
 ```
 
+如果项目里已存在 `.agents/skills/cut-draft` 或 `cutcli-docs`，`npx cutsdk init` 会询问是否覆盖更新；输入 `y` 或 `yes` 才会覆盖。需要跳过询问时使用 `npx cutsdk init --force`。
+
 如果要使用 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
@@ -73,9 +75,22 @@ Token 会保存到本机 `~/.cutcli/config.json`，输出中只显示 `<set>`。
 
 ## 推荐优先使用
 
-AI 生成视频草稿时，优先使用 `createDraftFromSpec`。它允许用一个 JSON 对象描述完整时间线，再由 SDK 调用底层草稿 API。
+AI 生成视频草稿、本地素材拼接、批量混剪和 Agent 自动编排时，优先使用 AI Draft Spec + `createAndRenderDraft`。它允许用一个 JSON 对象描述完整时间线，并在同一次调用里指定输出目录、草稿名和可选云渲染。
+
+`createDraftFromSpec(spec)` 只能按当前配置创建草稿，不能直接传输出目录和草稿名；需要 `draftsDir` 或 `name` 时使用：
+
+```ts
+await createAndRenderDraft({
+  draft: spec,
+  output: {
+    draftsDir: process.env.CUT_DRAFTS_DIR,
+    name: '批量混剪-001',
+  },
+  render: false,
+});
+```
 
-创建草稿后还需要补充高级操作时，可以使用带 `afterCreate` 的 `createAndRenderDraft`，或直接调用低层 API。
+创建草稿后还需要补充高级操作时，优先使用 `createAndRenderDraft` 的 `afterCreate`，或直接调用低层 API。
 
 使用命令行时，优先使用：
 
@@ -94,3 +109,9 @@ cutcli audio add <draftId> --src ./素材/bgm.mp3 --start 0s --duration 20s
 ```
 
 AI 调用 CLI 时，如果需要结构化错误输出，可以加 `--json-errors` 或设置 `CUTCLI_JSON_ERRORS=1`。
+
+## 当前 Draft Spec 限制
+
+- 同一个 Spec 内，图片/视频 `transform` 会整批应用，不能每段素材独立设置不同 scale/position。
+- 同一个 Spec 内，字幕 `style` 和 `position` 会整批应用，不能每条字幕完全不同位置样式。
+- 转场、花字、动画、特效名不要凭空编造。当前可用 `cutcli query image-animations`、`cutcli query text-effects` 查询部分素材；转场请先用 `material-browser.html` 挑选名称。

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

@@ -24,20 +24,27 @@ import {
 } from 'cutsdk';
 ```
 
-## 优先选择：AI Draft Spec
+## 优先选择：AI Draft Spec + createAndRenderDraft
 
 ```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' }] },
-  ],
+const result = await createAndRenderDraft({
+  draft: {
+    version: '1.0',
+    canvas: { width: 1080, height: 1920 },
+    duration: '5s',
+    tracks: [
+      { type: 'text', clips: [{ type: 'caption', text: 'Hello', start: '0s', duration: '5s' }] },
+    ],
+  },
+  output: {
+    draftsDir: process.env.CUT_DRAFTS_DIR,
+    name: 'demo-draft',
+  },
+  render: false,
 });
 ```
 
-用于一次性生成完整时间线。
+用于一次性生成完整时间线，并控制输出目录和草稿名。`createDraftFromSpec(spec)` 只能按当前配置创建草稿，不能直接传 `draftsDir` 和 `name`。
 
 ## 创建并渲染
 
@@ -57,6 +64,13 @@ const result = await createAndRenderDraft({
 console.log(result.render?.videoUrl);
 ```
 
+## 当前 Draft Spec 限制
+
+- 同一个 Spec 内，图片/视频 `transform` 会整批应用，不能每段素材独立设置不同 scale/position。
+- 同一个 Spec 内，字幕 `style` 和 `position` 会整批应用，不能每条字幕完全不同位置样式。
+- 需要逐片段差异化时，先用 Spec 创建主体，再用 `afterCreate` 或低层 SDK API 后处理。
+- 转场名先从 `material-browser.html` 挑选；当前 CLI 还没有 `cutcli query transitions`。
+
 ## 低层草稿流程
 
 ```ts

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

@@ -1,4 +1,4 @@
-import { createDraftFromSpec, validateDraftSpec } from 'cutsdk';
+import { createAndRenderDraft, validateDraftSpec } from 'cutsdk';
 
 const spec = {
   version: '1.0',
@@ -63,8 +63,15 @@ async function main() {
     process.exit(1);
   }
 
-  const draft = await createDraftFromSpec(spec);
-  console.log(draft);
+  const result = await createAndRenderDraft({
+    draft: spec,
+    output: {
+      draftsDir: process.env.CUT_DRAFTS_DIR,
+      name: 'AI Draft Spec 示例',
+    },
+    render: false,
+  });
+  console.log(result.draft);
 }
 
 main().catch((error) => {

package/dist/api/setup/templates/project/cutcli-docs/material-browser.html

@@ -188,7 +188,7 @@
   <header>
     <div class="wrap">
       <h1>cutcli 素材选择器</h1>
-      <p class="sub">花字、特效、贴纸、转场来自 SDK 本地素材索引。生成时间 2026-06-11 03:17:23。</p>
+      <p class="sub">花字、特效、贴纸、转场来自 SDK 本地素材索引。生成时间 2026-06-11 03:29:45。</p>
       <div class="toolbar">
         <input id="search" type="search" placeholder="搜索名称、ID、分类、作者">
         <select id="category"></select>

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

@@ -4,6 +4,7 @@
 
 ```bash
 npm install cutsdk
+npx cutsdk init
 ```
 
 ## 2. 创建一个简单草稿
@@ -11,31 +12,38 @@ npm install cutsdk
 创建 `create-draft.ts`：
 
 ```ts
-import { createDraftFromSpec } from 'cutsdk';
+import { createAndRenderDraft } from 'cutsdk';
 
 async function main() {
-  const draft = await createDraftFromSpec({
-    version: '1.0',
-    canvas: { width: 1080, height: 1920 },
-    duration: '3s',
-    tracks: [
-      {
-        type: 'text',
-        clips: [
-          {
-            type: 'caption',
-            text: '第一个 cutsdk 草稿',
-            start: '0s',
-            duration: '3s',
-            position: 'center',
-          },
-        ],
-      },
-    ],
+  const result = await createAndRenderDraft({
+    draft: {
+      version: '1.0',
+      canvas: { width: 1080, height: 1920 },
+      duration: '3s',
+      tracks: [
+        {
+          type: 'text',
+          clips: [
+            {
+              type: 'caption',
+              text: '第一个 cutsdk 草稿',
+              start: '0s',
+              duration: '3s',
+              position: 'center',
+            },
+          ],
+        },
+      ],
+    },
+    output: {
+      draftsDir: process.env.CUT_DRAFTS_DIR,
+      name: '第一个 cutsdk 草稿',
+    },
+    render: false,
   });
 
-  console.log(draft.draftId);
-  console.log(draft.filePath);
+  console.log(result.draft.draftId);
+  console.log(result.draft.filePath);
 }
 
 main().catch((error) => {
@@ -57,30 +65,34 @@ npx ts-node create-draft.ts
 使用 `assets` 定义可复用媒体，再在 clips 中引用：
 
 ```ts
-import { createDraftFromSpec } from 'cutsdk';
-
-await createDraftFromSpec({
-  version: '1.0',
-  canvas: { width: 1080, height: 1920 },
-  duration: '5s',
-  assets: {
-    bg: { type: 'image', src: '/absolute/path/bg.png', width: 1080, height: 1920 },
-    music: { type: 'audio', src: '/absolute/path/music.mp3', duration: '5s' },
-  },
-  tracks: [
-    {
-      type: 'visual',
-      clips: [{ type: 'image', asset: 'bg', start: '0s', duration: '5s' }],
-    },
-    {
-      type: 'audio',
-      clips: [{ type: 'audio', asset: 'music', start: '0s', duration: '5s', volume: 0.7 }],
-    },
-    {
-      type: 'text',
-      clips: [{ type: 'caption', text: '图片 + 音乐 + 字幕', start: '0s', duration: '5s' }],
+import { createAndRenderDraft } from 'cutsdk';
+
+await createAndRenderDraft({
+  draft: {
+    version: '1.0',
+    canvas: { width: 1080, height: 1920 },
+    duration: '5s',
+    assets: {
+      bg: { type: 'image', src: '/absolute/path/bg.png', width: 1080, height: 1920 },
+      music: { type: 'audio', src: '/absolute/path/music.mp3', duration: '5s' },
     },
-  ],
+    tracks: [
+      {
+        type: 'visual',
+        clips: [{ type: 'image', asset: 'bg', start: '0s', duration: '5s' }],
+      },
+      {
+        type: 'audio',
+        clips: [{ type: 'audio', asset: 'music', start: '0s', duration: '5s', volume: 0.7 }],
+      },
+      {
+        type: 'text',
+        clips: [{ type: 'caption', text: '图片 + 音乐 + 字幕', start: '0s', duration: '5s' }],
+      },
+    ],
+  },
+  output: { draftsDir: process.env.CUT_DRAFTS_DIR, name: '图片音乐字幕' },
+  render: false,
 });
 ```
 
@@ -109,7 +121,13 @@ AI Draft Spec：
 { start: '0s', duration: '3s' }
 ```
 
-## 6. CLI 本地路径与文字效果
+## 6. 当前 Spec 限制
+
+- 同一个 Spec 内，图片/视频 `transform` 会整批应用，不能每段素材独立设置不同 scale/position。
+- 同一个 Spec 内，字幕 `style` 和 `position` 会整批应用，不能每条字幕完全不同位置样式。
+- 需要逐片段差异化时，先用 Spec 创建主体，再用 `createAndRenderDraft` 的 `afterCreate` 或低层 SDK API 后处理。
+
+## 7. CLI 本地路径与文字效果
 
 ```bash
 cutcli draft easy <draftId> --audio-src ./素材/bgm.mp3 --image-src ./素材/bg.png \
@@ -120,7 +138,7 @@ cutcli text add <draftId> --text "爆款标题" --start 0s --duration 3s \
   --text-effect "红黄火焰综艺花字" --shadow --shadow-color "#000000"
 ```
 
-## 7. 云渲染状态
+## 8. 云渲染状态
 
 ```bash
 cutcli cloud render <draftId> --wait --pretty

package/dist/bin/cutsdk.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cutsdk.d.ts.map

package/dist/bin/cutsdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cutsdk.d.ts","sourceRoot":"","sources":["../../src/bin/cutsdk.ts"],"names":[],"mappings":""}

package/dist/bin/cutsdk.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("readline/promises");
+const install_project_docs_1 = require("../api/setup/install-project-docs");
+function getVersion() {
+    return require('../../package.json').version;
+}
+function printHelp() {
+    console.log(`cutsdk ${getVersion()}
+
+Usage:
+  cutsdk init [--dir <path>] [--force] [--pretty]
+
+Commands:
+  init    初始化或更新当前项目的 .agents/skills/cut-draft 和 cutcli-docs
+`);
+}
+function readOption(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    return args[index + 1];
+}
+async function confirmOverwrite(paths) {
+    console.error('检测到项目中已存在 cutsdk 文档/skill：');
+    for (const item of paths) {
+        console.error(`  - ${item}`);
+    }
+    const rl = (0, promises_1.createInterface)({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await rl.question('是否覆盖更新？输入 y 确认：');
+        return /^(y|yes)$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+async function run() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === '--help' || command === '-h') {
+        printHelp();
+        return;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(getVersion());
+        return;
+    }
+    if (command !== 'init') {
+        throw new Error(`Unknown command: ${command}. Usage: cutsdk init [--dir <path>] [--force]`);
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+        return;
+    }
+    const dir = readOption(args, '--dir');
+    const force = args.includes('--force');
+    const conflicts = force ? [] : (0, install_project_docs_1.getProjectDocConflicts)({ dir });
+    const shouldOverwrite = force || (conflicts.length > 0 ? await confirmOverwrite(conflicts) : false);
+    const result = (0, install_project_docs_1.installProjectDocs)({ dir, force: shouldOverwrite });
+    if (args.includes('--pretty')) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(JSON.stringify(result));
+    }
+}
+run().catch((error) => {
+    console.error(error?.message || String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=cutsdk.js.map

package/dist/bin/cutsdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cutsdk.js","sourceRoot":"","sources":["../../src/bin/cutsdk.ts"],"names":[],"mappings":";;;AAEA,gDAAoD;AAEpD,4EAA+F;AAE/F,SAAS,UAAU;IACjB,OAAO,OAAO,CAAC,oBAAoB,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,CAAC,GAAG,CAAC,UAAU,UAAU,EAAE;;;;;;;CAOnC,CAAC,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAc,EAAE,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,KAAe;IAC7C,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,EAAE,GAAG,IAAA,0BAAe,EAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QACpD,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED,KAAK,UAAU,GAAG;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,WAAW,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAC1B,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,+CAA+C,CAAC,CAAC;IAC9F,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAA,6CAAsB,EAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/D,MAAM,eAAe,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAEpG,MAAM,MAAM,GAAG,IAAA,yCAAkB,EAAC,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;IAEnE,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACpB,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { validateDraftSpec } from './api/draft-spec/create-draft-from-spec';
 import { normalizeDraftRenderUrl } from './api/cloud/submit-video-render-task';
+import { installProjectDocs } from './api/setup/install-project-docs';
 import { registerDraftUrl } from './shared/draft-service';
-export { validateDraftSpec, normalizeDraftRenderUrl, registerDraftUrl };
+export { validateDraftSpec, normalizeDraftRenderUrl, registerDraftUrl, installProjectDocs };
 export { CutSdkError, isCutSdkError, normalizeSdkError, parseSdkJson, withSdkErrorContext } from './shared/errors';
 export type { CutSdkErrorCode, CutSdkErrorOptions, SdkErrorContext } from './shared/errors';
 export declare const createDraft: (params?: import("./types").CreateDraftInput | undefined) => Promise<import("./types").CreateDraftOutput>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkD,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAmB5H,OAAO,EAAE,uBAAuB,EAAsD,MAAM,sCAAsC,CAAC;AAMnI,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACnH,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5F,eAAO,MAAM,WAAW,2GAAsD,CAAC;AAC/E,eAAO,MAAM,YAAY;;0CAAwD,CAAC;AAClF,eAAO,MAAM,UAAU,kDAAoD,CAAC;AAC5E,eAAO,MAAM,kBAAkB,4GAAoE,CAAC;AACpG,eAAO,MAAM,mBAAmB,6FAAsE,CAAC;AACvG,eAAO,MAAM,oBAAoB,+GAAwE,CAAC;AAC1G,eAAO,MAAM,WAAW,8FAAsD,CAAC;AAC/E,eAAO,MAAM,WAAW;;8CAAsD,CAAC;AAC/E,eAAO,MAAM,SAAS,0FAAkD,CAAC;AACzE,eAAO,MAAM,SAAS;;4CAAkD,CAAC;AACzE,eAAO,MAAM,SAAS,0FAAkD,CAAC;AACzE,eAAO,MAAM,SAAS;;4CAAkD,CAAC;AACzE,eAAO,MAAM,SAAS,0FAAkD,CAAC;AACzE,eAAO,MAAM,SAAS;;4CAAkD,CAAC;AACzE,eAAO,MAAM,UAAU,4FAAoD,CAAC;AAC5E,eAAO,MAAM,UAAU;;6CAAoD,CAAC;AAC5E,eAAO,MAAM,UAAU,4FAAoD,CAAC;AAC5E,eAAO,MAAM,WAAW;;8CAAsD,CAAC;AAC/E,eAAO,MAAM,YAAY,gGAAwD,CAAC;AAClF,eAAO,MAAM,YAAY;;;+CAAwD,CAAC;AAClF,eAAO,MAAM,QAAQ,wFAAgD,CAAC;AACtE,eAAO,MAAM,QAAQ;;;2CAAgD,CAAC;AACtE,eAAO,MAAM,YAAY,gGAAwD,CAAC;AAClF,eAAO,MAAM,qBAAqB,kHAA0E,CAAC;AAC7G,eAAO,MAAM,WAAW,6FAAsD,CAAC;AAC/E,eAAO,MAAM,WAAW,6FAAsD,CAAC;AAC/E,eAAO,MAAM,oBAAoB;;;sCAAwE,CAAC;AAC1G,eAAO,MAAM,gBAAgB,wGAAgE,CAAC;AAC9F,eAAO,MAAM,kBAAkB,yHAAoE,CAAC;AACpG,eAAO,MAAM,cAAc,iHAA4D,CAAC;AACxF,eAAO,MAAM,aAAa,kGAA0D,CAAC;AAErF,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkD,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAmB5H,OAAO,EAAE,uBAAuB,EAAsD,MAAM,sCAAsC,CAAC;AAMnI,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACnH,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5F,eAAO,MAAM,WAAW,2GAAsD,CAAC;AAC/E,eAAO,MAAM,YAAY;;0CAAwD,CAAC;AAClF,eAAO,MAAM,UAAU,kDAAoD,CAAC;AAC5E,eAAO,MAAM,kBAAkB,4GAAoE,CAAC;AACpG,eAAO,MAAM,mBAAmB,6FAAsE,CAAC;AACvG,eAAO,MAAM,oBAAoB,+GAAwE,CAAC;AAC1G,eAAO,MAAM,WAAW,8FAAsD,CAAC;AAC/E,eAAO,MAAM,WAAW;;8CAAsD,CAAC;AAC/E,eAAO,MAAM,SAAS,0FAAkD,CAAC;AACzE,eAAO,MAAM,SAAS;;4CAAkD,CAAC;AACzE,eAAO,MAAM,SAAS,0FAAkD,CAAC;AACzE,eAAO,MAAM,SAAS;;4CAAkD,CAAC;AACzE,eAAO,MAAM,SAAS,0FAAkD,CAAC;AACzE,eAAO,MAAM,SAAS;;4CAAkD,CAAC;AACzE,eAAO,MAAM,UAAU,4FAAoD,CAAC;AAC5E,eAAO,MAAM,UAAU;;6CAAoD,CAAC;AAC5E,eAAO,MAAM,UAAU,4FAAoD,CAAC;AAC5E,eAAO,MAAM,WAAW;;8CAAsD,CAAC;AAC/E,eAAO,MAAM,YAAY,gGAAwD,CAAC;AAClF,eAAO,MAAM,YAAY;;;+CAAwD,CAAC;AAClF,eAAO,MAAM,QAAQ,wFAAgD,CAAC;AACtE,eAAO,MAAM,QAAQ;;;2CAAgD,CAAC;AACtE,eAAO,MAAM,YAAY,gGAAwD,CAAC;AAClF,eAAO,MAAM,qBAAqB,kHAA0E,CAAC;AAC7G,eAAO,MAAM,WAAW,6FAAsD,CAAC;AAC/E,eAAO,MAAM,WAAW,6FAAsD,CAAC;AAC/E,eAAO,MAAM,oBAAoB;;;sCAAwE,CAAC;AAC1G,eAAO,MAAM,gBAAgB,wGAAgE,CAAC;AAC9F,eAAO,MAAM,kBAAkB,yHAAoE,CAAC;AACpG,eAAO,MAAM,cAAc,iHAA4D,CAAC;AACxF,eAAO,MAAM,aAAa,kGAA0D,CAAC;AAErF,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTextEffect = exports.getTextEffects = exports.getImageAnimations = exports.getAudioDuration = exports.getCloudRenderStatus = exports.renderDraft = exports.uploadDraft = exports.submitVideoRenderTask = exports.addTextStyle = exports.getMasks = exports.addMasks = exports.getKeyframes = exports.addKeyframes = exports.getStickers = exports.addSticker = exports.getEffects = exports.addEffects = exports.getAudios = exports.addAudios = exports.getVideos = exports.addVideos = exports.getImages = exports.addImages = exports.getCaptions = exports.addCaptions = exports.createAndRenderDraft = exports.createDraftFromSpec = exports.easyCreateMaterial = exports.listDrafts = exports.getDraftInfo = exports.createDraft = exports.withSdkErrorContext = exports.parseSdkJson = exports.normalizeSdkError = exports.isCutSdkError = exports.CutSdkError = exports.registerDraftUrl = exports.normalizeDraftRenderUrl = exports.validateDraftSpec = void 0;
+exports.getTextEffect = exports.getTextEffects = exports.getImageAnimations = exports.getAudioDuration = exports.getCloudRenderStatus = exports.renderDraft = exports.uploadDraft = exports.submitVideoRenderTask = exports.addTextStyle = exports.getMasks = exports.addMasks = exports.getKeyframes = exports.addKeyframes = exports.getStickers = exports.addSticker = exports.getEffects = exports.addEffects = exports.getAudios = exports.addAudios = exports.getVideos = exports.addVideos = exports.getImages = exports.addImages = exports.getCaptions = exports.addCaptions = exports.createAndRenderDraft = exports.createDraftFromSpec = exports.easyCreateMaterial = exports.listDrafts = exports.getDraftInfo = exports.createDraft = exports.withSdkErrorContext = exports.parseSdkJson = exports.normalizeSdkError = exports.isCutSdkError = exports.CutSdkError = exports.installProjectDocs = exports.registerDraftUrl = exports.normalizeDraftRenderUrl = exports.validateDraftSpec = void 0;
 const errors_1 = require("./shared/errors");
 const create_draft_1 = require("./api/draft/create-draft");
 const get_draft_info_1 = require("./api/draft/get-draft-info");
@@ -47,6 +47,8 @@ const render_draft_1 = require("./api/cloud/render-draft");
 const get_audio_duration_1 = require("./api/query/get-audio-duration");
 const get_image_animations_1 = require("./api/query/get-image-animations");
 const get_text_effects_1 = require("./api/query/get-text-effects");
+const install_project_docs_1 = require("./api/setup/install-project-docs");
+Object.defineProperty(exports, "installProjectDocs", { enumerable: true, get: function () { return install_project_docs_1.installProjectDocs; } });
 const draft_service_1 = require("./shared/draft-service");
 Object.defineProperty(exports, "registerDraftUrl", { enumerable: true, get: function () { return draft_service_1.registerDraftUrl; } });
 var errors_2 = require("./shared/errors");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "cutsdk",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "CapCut 草稿 Node.js SDK — 用代码批量创建剪映标准草稿，支持字幕/图片/视频/音频/特效/贴纸/关键帧/遮罩",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "cutsdk": "dist/bin/cutsdk.js"
+  },
   "license": "MIT",
   "author": "m007",
   "keywords": [