# 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
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 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 生成视频草稿、本地素材拼接、批量混剪和 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,
});
```

创建草稿后还需要补充高级操作时，优先使用 `createAndRenderDraft` 的 `afterCreate`，或直接调用低层 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`。

## 当前 Draft Spec 限制

- 同一个 Spec 内，图片/视频 `transform` 会整批应用，不能每段素材独立设置不同 scale/position。
- 同一个 Spec 内，字幕 `style` 和 `position` 会整批应用，不能每条字幕完全不同位置样式。
- 转场、花字、动画、特效名不要凭空编造。当前可用 `cutcli query image-animations`、`cutcli query text-effects` 查询部分素材；转场请先用 `material-browser.html` 挑选名称。