项目

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

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

minicut new

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

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 存进你的素材库，项目按 id 列出它们。

选项

示例

新建一个带标题的项目

minicut new rain-shop --title "Rain shop"

加下一集

minicut new rain-shop --add-episode

输出

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

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

created 是 episode 或 timeline。

文件

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

错误

另见

minicut save、minicut shots、概览

minicut save

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

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，没给就用分镜表上这个镜头的时长。

选项

示例

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

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

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

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

输出

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

错误

另见

minicut asset、minicut new

minicut asset

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

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 设定镜头用的版本。

选项

示例

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

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

3 号镜头用第 2 版

minicut asset pick rain-shop ep01 c03 t02

输出

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

另见

minicut save、minicut shots

minicut shots

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

Usage

minicut shots [--episode EPISODE] [--project PROJECT] [--json]

替换下面的内容：

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

说明

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

选项

示例

列出第 1 集的镜头

minicut shots --episode ep01

输出

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

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

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

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

错误

另见

minicut now、minicut asset

minicut now

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

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 一样，给出镜头文件夹的路径就同时给出了两者。

选项

示例

显示 Agent 正在写 3 号镜头

minicut now 6 c03 --episode ep01

输出

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

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

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

另见

minicut shots、minicut script

minicut script

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

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 检查那个文件。什么都不上传，也不同步：这一集文件夹里的文件是唯一的一份。你的 Agent 改了文件，页面会重新读取它。

选项

示例

打开第 1 集的编辑器

minicut script rain-shop --episode ep01

输出

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

文件

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、检查和环节