# 项目

新建项目、把图片和版本存进项目，以及显示它的镜头和剧本的命令。

本页的每条命令都需要这台电脑已登录。没登录时，每条命令都会打印 `You are not signed in. Ask your agent to run minicut login.`，并以退出码 10 结束。每条命令都接受的选项和所有退出码，见[全局选项](/zh-cn/docs/cli/global-options)。

## minicut new

新建一个项目文件夹，给项目加一集，或者给某一集写入一条空的时间线。

### Usage

```text Usage
minicut new ID [--title TITLE] [--dir PARENT] [--episodes COUNT]
minicut new ID --add-episode [--dir PARENT] [--json]
minicut new ID --timeline EPISODE [--dir PARENT] [--json]
```

替换下面的内容：

- `ID`：项目 id。小写字母、数字和 `-`，最多 24 个字符，以字母或数字开头。
- `TITLE`：人看的标题。任何语言都行。
- `PARENT`：项目所在的文件夹。
- `COUNT`：你计划做几集，1 到 9999 的整数。
- `EPISODE`：集的 id，例如 `ep01`。

### 说明

一个项目就是一部全剧。`minicut new` 建好项目文件夹，里面有第一集 `ep01`。这一集一开始有一条空的时间线，剪辑器原样打开它。不加 `--dir` 时，项目放在 MiniCut 主文件夹的 `projects` 文件夹里。

`--add-episode` 加上下一个空闲的集（`ep02`、`ep03`，依此类推），并把它列进 `series.json`。`--timeline` 给没有时间线的集文件夹写入一条空时间线。

角色、场景、道具和风格不放在项目文件夹里。它们用 [minicut save](#minicut-save) 存进你的素材库，项目按 id 列出它们。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--title` | 文字 | id | 人看的标题，存在 `series.json` 里 |
| `--dir` | 文件夹 | `projects` 文件夹 | 项目所在的文件夹 |
| `--episodes` | 数字 | 无 | 你计划做几集。超过 99 时，集 id 用三位数，例如 `ep001` |
| `--add-episode` | 开关 | 关 | 给已有的项目加下一集 |
| `--timeline` | 集 id | 无 | 给这一集写入空时间线 |
| `--json` | 开关 | 关 | 打印一个 JSON 对象。配合 `--add-episode` 和 `--timeline` 使用 |

### 示例

#### 新建一个带标题的项目

```bash Terminal
minicut new rain-shop --title "Rain shop"
```

#### 加下一集

```bash Terminal
minicut new rain-shop --add-episode
```

### 输出

`minicut new` 打印项目文件夹和它建出来的文件。加上 `--json`，`--add-episode` 和 `--timeline` 打印：

```json JSON shape
{"ok": true, "project": "rain-shop", "episode": "ep02", "dir": "~/.minicut/projects/rain-shop/episodes/ep02", "created": "episode"}
```

`created` 是 `episode` 或 `timeline`。

| 退出码 | 含义 |
|---|---|
| 0 | 文件夹建好了 |
| 2 | id、集或数量不对，或者文件夹已经存在 |
| 5 | `--dir` 在你的工作文件夹之外 |

### 文件

```text Project
rain-shop/
  series.json            title, id, screen shape, episodes and library ids
  source/
    sources.json         the sources the story comes from, empty at first
  episodes/
    ep01/
      clips/             one folder per shot, with its takes
      music/             the episode's music
      index.html         the episode timeline, empty until the first cut
      minicut.json       the editor settings for this episode
```

### 错误

| 信息 | 怎么做 |
|---|---|
| `"<id>" cannot be a project id.` | 用小写字母、数字和 `-`，最多 24 个，真正的标题写在 `--title` 里 |
| `already exists: <folder>` | 换一个 id，或者在已有的那个项目里做 |
| `--episodes is the planned episode count, a number.` | 给一个整数，例如 `--episodes 12` |
| `no project at <folder> (no readable series.json)` | 检查 id，或者加上 `--dir` 指向项目所在的文件夹 |
| `--timeline needs an episode id such as ep01.` | 在 `--timeline` 后面给集 id |
| `<episode> already has a timeline` | 不用做什么：这一集已经有时间线 |

### 另见

[minicut save](#minicut-save)、[minicut shots](#minicut-shots)、[概览](/zh-cn/docs/cli/overview)

## minicut save

把一张图片存进你的素材库，或者把生成的文件存成某个镜头的一个版本。

### Usage

```text Usage
minicut save KIND FILE --id ID [--name NAME] [--as STEM] [--project PROJECT]
minicut save take FILE --project PROJECT --episode EPISODE --clip CLIP [--kind {model|code|placeholder}] [--model MODEL] [--seconds SECONDS]
```

替换下面的内容：

- `KIND`：`character`、`location`、`prop` 或 `style`。
- `FILE`：要存的文件。图片是 `.png`、`.jpg`、`.jpeg` 或 `.webp`。版本是 `.mp4`、`.mov`、`.webm`、`.wav`、`.mp3` 或 `.m4a`。
- `ID`：这一项的 id。小写字母、数字和 `-`，最多 32 个字符，例如 `lin-xia`。
- `NAME`：人看的这一项的名字。
- `STEM`：图片存成的文件名，不带扩展名，例如 `face-01`。
- `PROJECT`：项目 id，或者项目文件夹的路径。
- `EPISODE`：集的 id，例如 `ep01`。
- `CLIP`：镜头 id，例如 `c01`。
- `MODEL`：做出这个版本的模型的名字。
- `SECONDS`：占位图片变成的片段的长度。

### 说明

你的素材库里放着角色、场景、道具和风格，每个项目都能用。`minicut save KIND` 把图片复制到素材库里这一项的文件夹。加上 `--project`，它还会把这一项的 id 列进那个项目的 `series.json`。它从不覆盖素材库里已有的文件。

`minicut save take` 把一个文件存成这个镜头的下一个版本：`t01`、`t02`，依此类推。文件放进素材库，镜头文件夹里得到同一个文件，磁盘允许时用硬链接。旁边会放一条版本记录。一个镜头的第一个版本会成为它选中的版本。

加上 `--kind placeholder`，一张 `.png` 或 `.jpg` 图片会变成一段和镜头一样长的片段。长度是 `--seconds`，没给就用分镜表上这个镜头的时长。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--id` | id | 无 | 这一项的 id。素材库里的图片必须给 |
| `--name` | 文字 | id | 人看的这一项的名字 |
| `--as` | 名称 | 角色是 `sheet-NN`，其他是 `image-NN` | 图片存成的文件名 |
| `--project` | id 或文件夹 | 无 | 要把这一项列进去的项目。版本必须给 |
| `--episode` | 集 id | 无 | 镜头所在的集。版本必须给 |
| `--clip` | 镜头 id | 无 | 这个版本属于的镜头。版本必须给 |
| `--kind` | `model`、`code` 或 `placeholder` | `model` | 版本是怎么做出来的：模型做的、代码做的，还是用一张静帧图片做的 |
| `--model` | 名称 | 无 | 做出这个版本的模型 |
| `--seconds` | 数字 | 镜头的时长 | `--kind placeholder` 时的片段长度 |

### 示例

#### 存一张角色图片并列进项目

```bash Terminal
minicut save character lin-xia.png --id lin-xia --name "Lin Xia" --project rain-shop
```

#### 把一个视频存成 3 号镜头的版本

```bash Terminal
minicut save take take.mp4 --project rain-shop --episode ep01 --clip c03
```

### 输出

`minicut save` 打印 `Saved` 和存好的文件的路径，然后是它改动的每个项目文件。

| 退出码 | 含义 |
|---|---|
| 0 | 文件存好了 |
| 2 | 某个选项或文件不对，或者文件已经在素材库里 |
| 5 | 文件在你的工作文件夹之外 |

### 错误

| 信息 | 怎么做 |
|---|---|
| `no such file: <file>` | 检查文件路径 |
| `--id must be a short ASCII id` | 用小写字母、数字和 `-`，最多 32 个 |
| `already in the library, not overwritten: <file>` | 用另一个 `--as` 存，或者用已有的那个文件 |
| `--episode is ep01 (or ep001) and --clip is c01 (or c001).` | 两个 id 都按这个格式给 |
| `no episode folder <folder>.` | 用 `series.json` 里列出的集 |
| `no length for <clip>: add --seconds S` | 加上 `--seconds`，或者在分镜表上给这个镜头一个时长 |

### 另见

[minicut asset](#minicut-asset)、[minicut new](#minicut-new)

## minicut asset

在项目里添加、重命名、设置封面或移除一项，并选定某个镜头的版本。

### Usage

```text Usage
minicut asset add PROJECT {characters|locations|props} NAME [--note NOTE] [PICTURE ...]
minicut asset rename PROJECT KIND ITEM NEW_NAME
minicut asset cover PROJECT KIND ITEM PICTURE_NAME
minicut asset remove PROJECT KIND ITEM
minicut asset pick PROJECT EPISODE CLIP TAKE
```

替换下面的内容：

- `PROJECT`：项目 id，`.` 表示你所在的项目，或者项目文件夹的路径。
- `NAME`：新一项的名字。
- `NOTE`：这一项的简短描述。
- `PICTURE`：这一项的图片文件。给多个就加多张。
- `KIND`：`characters`、`locations` 或 `props`。
- `ITEM`：要改的那一项。
- `NEW_NAME`：这一项的新名字。
- `PICTURE_NAME`：这一项的某张图片的文件名。
- `EPISODE`、`CLIP`、`TAKE`：集、镜头和版本，例如 `ep01 c03 t02`。

### 说明

这些动作和 MiniCut 应用里的 **资产** 标签页做的一样，规则也一样。已被占用的名字会被拒绝。`rename` 会改掉项目里这一项的每一处 `@名字` 提及。`remove` 把这一项的文件夹移进系统废纸篓。`pick` 设定镜头用的版本。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--note` | 文字 | 无 | 这一项的简短描述。配合 `add` 使用 |

### 示例

#### 添加一个带一张图片的角色

```bash Terminal
minicut asset add rain-shop characters "Lin Xia" --note "shop owner" lin-xia.png
```

#### 3 号镜头用第 2 版

```bash Terminal
minicut asset pick rain-shop ep01 c03 t02
```

### 输出

`minicut asset` 打印一行 JSON：动作的结果，或者一个 `error`。

| 退出码 | 含义 |
|---|---|
| 0 | 动作运行了 |
| 1 | 动作被拒绝 |
| 2 | `asset` 后面的词不对 |
| 5 | 某张图片在你的工作文件夹之外 |

### 另见

[minicut save](#minicut-save)、[minicut shots](#minicut-shots)

## minicut shots

列出一集的每个镜头和它的状态，状态和应用里分镜表显示的一样。

### Usage

```text Usage
minicut shots [--episode EPISODE] [--project PROJECT] [--json]
```

替换下面的内容：

- `EPISODE`：集的 id，例如 `ep01`。
- `PROJECT`：项目 id，或者项目文件夹的路径。

### 说明

项目是 `--project`，没给就是你运行命令时所在的项目文件夹。集是 `--episode`，没给就是项目里唯一的一集。命令读取这一集的文件，什么都不改。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--episode` | 集 id | 唯一的一集 | 要列出的集 |
| `--project` | id 或文件夹 | 你所在的文件夹 | 要读取的项目 |
| `--json` | 开关 | 关 | 打印一个 JSON 列表 |

### 示例

#### 列出第 1 集的镜头

```bash Terminal
minicut shots --episode ep01
```

### 输出

每一行是一个镜头：它的 id、它的状态，有的话再加上它的版本、任务 id 和原因。状态用中文打印，和应用里一样。

加上 `--json`，命令打印一个列表，每个镜头一个对象：

```json JSON shape
[{"clip": "c01", "state": "done", "take": "t01", "job_id": null, "reason": null}]
```

| 状态 | 含义 |
|---|---|
| `sheet` | 在分镜表上，还没有提示词 |
| `writing` | Agent 正在写提示词 |
| `promptFail` | 提示词没有通过检查 |
| `ready` | 可以生成了 |
| `queued` | 任务在等待开始 |
| `running` | 任务正在运行 |
| `saving` | 结果正在保存 |
| `failed` | 任务失败了 |
| `stopped` | 任务被停止了 |
| `unchecked` | 版本还没检查 |
| `fail` | 版本没有通过检查 |
| `done` | 版本已做好 |

退出码：列出了镜头是 0，找不到项目或集是 5。

### 错误

| 信息 | 怎么做 |
|---|---|
| `No project here: run this inside a series folder, or add --project <id or folder>.` | 在项目文件夹里运行，或者加上 `--project` |
| `Which episode? Add --episode epNN` | 加上 `--episode`，用它列出的某一集 |

### 另见

[minicut now](#minicut-now)、[minicut asset](#minicut-asset)

## minicut now

告诉应用里的分镜表，你的 Agent 正在写哪个镜头。应用会显示 120 秒。

### Usage

```text Usage
minicut now STEP CLIP [--episode EPISODE] [--project PROJECT] [--json]
```

替换下面的内容：

- `STEP`：你的 Agent 正在做的步骤的编号，从 1 开始的整数。
- `CLIP`：镜头 id，例如 `c03`，或者镜头文件夹的路径。
- `EPISODE`：集的 id，例如 `ep01`。
- `PROJECT`：项目 id，或者项目文件夹的路径。

### 说明

命令在这一集的文件夹里写一个很小的文件。应用读它，显示 Agent 正在做哪个镜头。120 秒后，这条提示自己消失。找项目和集的方式和 [minicut shots](#minicut-shots) 一样，给出镜头文件夹的路径就同时给出了两者。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--episode` | 集 id | 镜头文件夹所在的集，否则是唯一的一集 | 镜头所在的集 |
| `--project` | id 或文件夹 | 你所在的文件夹 | 项目 |
| `--json` | 开关 | 关 | 打印一个 JSON 对象 |

### 示例

#### 显示 Agent 正在写 3 号镜头

```bash Terminal
minicut now 6 c03 --episode ep01
```

### 输出

命令打印步骤、镜头编号和集，并说明它会显示接下来的 120 秒。加上 `--json` 时它打印：

```json JSON shape
{"type": "mh.now", "step": 6, "clip": "c03", "at": "2026-10-29T10:00:00.000Z"}
```

退出码：写好了提示是 0，`STEP` 或 `CLIP` 不对是 2，找不到项目或集是 5。

### 另见

[minicut shots](#minicut-shots)、[minicut script](#minicut-script)

## minicut script

在你自己的电脑上，打开某一集的剧本和分镜表编辑器。

### Usage

```text Usage
minicut script PROJECT [--episode EPISODE] [--port PORT] [--no-open]
```

替换下面的内容：

- `PROJECT`：项目 id，或者项目文件夹的路径。
- `EPISODE`：集的 id，例如 `ep01`。
- `PORT`：编辑器页面在你电脑上用的端口号。

### 说明

编辑器是你浏览器里的一个页面，直接读写这一集自己的文件。它编辑 `script.md` 和 `shots.md`，并显示 `assets.md` 和 `prompts.md`。每次保存，都会用 [minicut check](/zh-cn/docs/cli/checks-and-loops#minicut-check-step) 检查那个文件。什么都不上传，也不同步：这一集文件夹里的文件是唯一的一份。你的 Agent 改了文件，页面会重新读取它。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--episode` | 集 id | `ep01` | 要打开的集 |
| `--port` | 数字 | 一个空闲端口 | 编辑器页面用的端口 |
| `--no-open` | 开关 | 关 | 打印地址，不打开浏览器 |

### 示例

#### 打开第 1 集的编辑器

```bash Terminal
minicut script rain-shop --episode ep01
```

### 输出

命令打印这一集的文件夹、四个文件各自是否已经写好，然后是 `URL:` 和编辑器的地址。它一直运行，直到你按 Ctrl+C 停止。

### 文件

```text Episode
ep01/
  script.md       the episode script
  shots.md        the shot sheet
  assets.md       the characters, places and props the shots use
  prompts.md      the prompt for each shot
```

### 另见

[minicut shots](#minicut-shots)、[检查和环节](/zh-cn/docs/cli/checks-and-loops)