# 初始设置

打开 MiniCut 应用、检查并安装 MiniCut 需要的工具、连接你的 Agent 应用，以及更新或移除 MiniCut 的命令。

本页的每条命令都不用登录就能运行。每条命令都接受的选项和所有退出码，见[全局选项](/zh-cn/docs/cli/global-options)。

MiniCut 主文件夹在 macOS 和 Linux 上是 `~/.minicut`，在 Windows 上是 `%LOCALAPPDATA%\minicut`。设置 `MINICUT_HOME` 可以改用别的文件夹。

## minicut

在浏览器里打开 MiniCut 应用，应用没在运行就先启动它。

### Usage

```text Usage
minicut
```

### 说明

MiniCut 应用在你的电脑上运行，地址是 `http://127.0.0.1:7311/`，或者 `MINICUT_PORT` 里的端口。应用没在运行时，`minicut` 通过登录项启动它。登录项会在你登录电脑时启动应用。命令最多等应用 10 秒，然后打印地址并打开它。

如果已经有一个应用页面开着，它只打印地址，不再开第二个标签页。在 Agent 的沙盒里，命令连不上应用，它会打印地址，由你自己打开。

### 输出

| 信息 | 退出码 | 怎么做 |
|---|---|---|
| `Opened the Minicut app in your browser.` | 0 | 不用做什么 |
| `The Minicut app is already open in your browser.` | 0 | 切到那个标签页 |
| `Open this address in your browser.` | 0 | 打开它上面打印的地址 |
| `The Minicut app is running. Open this address in your browser.` | 0 | 自己打开这个地址 |
| `Port 7311 is used by another program. Set MINICUT_PORT to a free port, then run minicut again.` | 2 | 设置 `MINICUT_PORT`，再运行 `minicut` |
| `The Minicut app did not start.` | 2 | 运行 `minicut doctor`，再运行 `minicut` |

## minicut open

在 MiniCut 应用里打开一个项目的某一集，停在你指定的标签页，并打印这个地址。

### Usage

```text Usage
minicut open PROJECT [--episode EPISODE] [--tab {editor|script|shots|checks|assets}] [--no-open]
```

替换下面的内容：

- `PROJECT`：`minicut new` 给出的项目 id。
- `EPISODE`：集的 id，例如 `ep01`。

### 说明

`minicut open` 像 `minicut` 一样启动应用，然后在你指定的集和标签页打开项目。即使已经有别的应用页面开着，指向项目标签页的链接也会打开。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--episode` | 集的 id | `ep01` | 要打开的集 |
| `--tab` | `editor`、`script`、`shots`、`checks` 或 `assets` | `editor` | 要打开的标签页。`editor` 是 **剪辑** 标签页 |
| `--no-open` | 开关 | 关 | 只打印地址，什么都不打开 |

### 示例

#### 打开第一集的剪辑

```bash Terminal
minicut open snow-bus
```

在没有这个 id 的项目的电脑上：

```text Output
No project snow-bus in ~/.minicut/projects.
```

#### 用不合法的项目 id 打开

```bash Terminal
minicut open "Snow Bus"
```

```text Output
Not a project id: Snow Bus. Use the id from minicut new (letters, digits and -).
```

### 输出

应用打开了或打印了地址时，退出码 0。项目、集或标签页不对，或者应用没有启动时，退出码 2。没有 `PROJECT` 时，它打印用法行，并以退出码 2 结束。

## minicut doctor

显示你的系统、MiniCut 主文件夹、可用磁盘空间，以及 MiniCut 用的每个工具和它的状态、版本。

### Usage

```text Usage
minicut doctor
```

### 说明

`minicut doctor` 只读取你的电脑，什么都不改，也从不下载任何东西。它打印：

1. 你的系统和工具文件夹。
2. 它找到的 Node 和 Python 版本。
3. 可用磁盘空间，和 setup 需要的 5 GB 对比。
4. MiniCut 主文件夹里的每个文件夹，以及它是否存在。
5. 一张工具表，列是 **Tool**、**State**、**Version** 和 **Where**。
6. 缺了多少个工具，以及下一步要运行的命令。

退出码是 0，缺工具时也是。

## minicut setup

建好 MiniCut 主文件夹，然后安装它缺的工具。

### Usage

```text Usage
minicut setup [--china] [--dry-run] [--local-speech] [--no-tools]
```

### 说明

`minicut setup` 建好主文件夹，里面有 `settings.json` 和 `library`、`projects`、`tools`、`cache` 文件夹。然后把每个缺的工具下载到 `tools` 文件夹。已经装好的工具会跳过。

setup 需要 5 GB 可用磁盘。不加 `--china` 时，它先给每个下载站计时，站点 4 秒内没有回应就改用它的镜像站。加上 `--china`，所有下载都用镜像站。如果安装时存的是中国大陆地区，setup 不加这个选项也用镜像站。

setup 不带 Python 3.12 和 ffmpeg。缺其中一个时，它打印一行以 `MISSING:` 开头的信息，带上你所在地区的官方下载网站。它做完其他所有步骤，然后以退出码 4 结束。装好缺的那个，再运行一次 `minicut setup`。

同一时间只运行一个 setup。第二个会等待，然后跳过第一个已经装好的。setup 以 `Done. Run: minicut doctor` 结束。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--china` | 开关 | 关 | 所有下载都用中国大陆镜像站 |
| `--dry-run` | 开关 | 关 | 列出每个下载、它的来源和大小。什么都不下载，什么都不写 |
| `--local-speech` | 开关 | 关 | 同时安装 1 GB 的本地语音模型 |
| `--no-tools` | 开关 | 关 | 只建主文件夹，不安装工具 |

### 示例

#### 看 setup 会下载什么

```bash Terminal
minicut setup --dry-run
```

最后会打印已知下载的总大小，和 `Dry run: nothing downloaded, nothing written.`

#### 在中国大陆安装工具

```bash Terminal
minicut setup --china
```

### 输出

| 退出码 | 含义 | 怎么做 |
|---|---|---|
| 0 | 每个工具都装好了 | 运行 `minicut doctor` |
| 1 | 有下载失败。那一行以 `FAILED` 开头，写明是哪个工具 | 再运行一次 `minicut setup` |
| 2 | 在这里写不了工具文件夹，比如在 Agent 的沙盒里。setup 会打印要你运行的命令 | 在你自己的终端里运行那条命令 |
| 3 | `REFUSED: under 5 GB free. Free some space and run again.` | 腾出磁盘空间，再运行 setup |
| 4 | 缺 Python 3.12 或 ffmpeg。`MISSING:` 那一行写明下载网站 | 装好它，再运行 setup |

## minicut update

在你现有的版本旁边，安装最新的 MiniCut 版本。

### Usage

```text Usage
minicut update
```

### 说明

`minicut update` 按安装时保存的地区下载最新版本，装在当前版本旁边。MiniCut 应用会用新文件重启。已经在运行的命令会用旧文件跑完。

MiniCut 也会自己检查更新，最多每天一次，由一个没有命令会等它的单独程序来做。应用页面在使用时，它从不更新。更新之后，下一条命令会在 stderr 上打印一行。要关闭自动更新，见[全局选项](/zh-cn/docs/cli/global-options#环境变量)。

### 输出

更新一边运行一边打印进度。完成时退出码 0。如果另一个更新正在运行，它打印下面这一行，并以退出码 75 结束：

```text Output
Another Minicut update is running on this computer. Run minicut update again when it has finished.
```

## minicut network

保存一个每条命令和 MiniCut 应用都使用的代理，或者把它删掉。

### Usage

```text Usage
minicut network [--proxy URL | --direct] [--json]
```

替换下面的内容：

- `URL`：代理地址，格式是 `http://HOST:PORT`。

### 说明

`minicut network --proxy` 把代理存进 `settings.json`。地址里的密码放进密钥存储，不放进这个文件。`--direct` 删除代理。不加选项时，它显示已保存的代理。如果安装 MiniCut 时设了 `HTTPS_PROXY`，安装会替你保存那个代理。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--proxy` | URL | 无 | 保存这个代理 |
| `--direct` | 开关 | 关 | 删除已保存的代理，直接连接 |
| `--json` | 开关 | 关 | 打印一个 JSON 对象 |

### 示例

#### 保存代理

```bash Terminal
minicut network --proxy http://192.0.2.10:8080
```

```text Output
Proxy saved: http://192.0.2.10:8080
```

#### 显示已保存的代理

```bash Terminal
minicut network
```

```text Output
Proxy: http://192.0.2.10:8080
```

#### 删除代理

```bash Terminal
minicut network --direct
```

```text Output
No proxy: every command connects directly.
```

### 输出

加上 `--json` 且没有其他选项时，它打印 `{"proxy":null}` 或已保存的地址。退出码 0；地址不是 `http://HOST:PORT` 的格式时是 5：

```text Output
a proxy is http://host:port, got ftp://x
```

## minicut uninstall

让这台电脑退出登录，停止 MiniCut 应用，并移除 MiniCut。你的项目和素材库会留下。

### Usage

```text Usage
minicut uninstall [--all] [--json]
```

### 说明

`minicut uninstall` 按顺序做这些步骤：

1. 在 minicut.ai 上让这台电脑退出登录，并删除它的密钥。
2. 停止 MiniCut 应用，并移除登录项，这样就没有东西会再启动它。
3. 从每个 Agent 应用里移除 MiniCut 技能文件夹，以及 Claude Code 和 Codex 里的 MiniCut 钩子。其他技能和钩子保持不变。
4. 从你的 shell 配置文件里移除 `minicut`，在 Windows 上是从你的 Path 里移除。
5. 从 MiniCut 主文件夹里移除工具和应用。

它保留 `projects`、`library`、`canvas` 和 `settings.json`。加上 `--all`，这些也一起移除。它只移除 MiniCut 自己做出来的文件，并告诉你留下了多少个别的文件。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--all` | 开关 | 关 | 同时移除你的项目、素材库、画布和设置 |
| `--json` | 开关 | 关 | 打印一个 JSON 对象 |

### 输出

它为做过的每一步打印一行。加上 `--json`：

```json JSON shape
{"state": "uninstalled", "revoked": true, "kept": ["projects", "library", "canvas", "settings.json"], "home": "~/.minicut"}
```

加上 `--all` 时，`kept` 是 `[]`。退出码：

| 退出码 | 含义 |
|---|---|
| 0 | MiniCut 已移除 |
| 1 | 主文件夹里没有 MiniCut 的安装标记（`minicut-home.json`）。什么都没移除 |
| 7 | MiniCut 已移除，但 minicut.ai 没有回答。到你账号的 **设备** 页面里移除这台电脑 |

## minicut install-skill

把 MiniCut 技能包复制到某个 Agent 应用的技能文件夹，让你的编程 Agent 知道怎么运行 MiniCut。

### Usage

```text Usage
minicut install-skill --app APP [--force]
minicut install-skill --all-found [--force]
minicut install-skill --status [--json]
```

替换下面的内容：

- `APP`：下表里的 Agent 应用 id。

### 说明

技能包放在应用技能文件夹里一个叫 `miniharness-short-drama` 的文件夹中。对 Claude Code 和 Codex，它还会把 MiniCut 的环节钩子加进应用的设置。如果 Agent 应用开着，请重启它，让它加载这个技能。

不加任何选项时，命令列出各个应用和它们的文件夹，并以退出码 2 结束。

| `APP` | Agent 应用 | 技能文件夹 |
|---|---|---|
| `claude-code` | Claude Code | `~/.claude/skills/miniharness-short-drama` |
| `codex` | Codex | `~/.agents/skills/miniharness-short-drama` |
| `opencode` | OpenCode | `~/.agents/skills/miniharness-short-drama` |
| `codebuddy` | CodeBuddy Code | `~/.codebuddy/skills/miniharness-short-drama` |
| `trae` | TRAE | `~/.trae-cn/skills/miniharness-short-drama` |
| `qoder` | Qoder 和 Qoder CN | `~/.qoder/skills/miniharness-short-drama` |
| `qwen` | Qwen Code | `~/.qwen/skills/miniharness-short-drama` |
| `kimi` | Kimi Code | `~/.agents/skills/miniharness-short-drama` |
| `cursor` | Cursor | `~/.agents/skills/miniharness-short-drama` |
| `cline` | Cline | `~/.cline/skills/miniharness-short-drama` |

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--app` | 应用 id | 无 | 只装进这一个应用 |
| `--all-found` | 开关 | 关 | 装进主文件夹在这台电脑上的每个应用 |
| `--status` | 开关 | 关 | 显示找到了哪些应用，哪些已经有这个技能 |
| `--force` | 开关 | 关 | 替换已经存在的 MiniCut 技能文件夹 |
| `--json` | 开关 | 关 | 配合 `--status`，打印一个 JSON 对象 |

### 示例

#### 给 Claude Code 安装技能

```bash Terminal
minicut install-skill --app claude-code
```

```text Output
Claude Code: copied the skill pack to ~/.claude/skills/miniharness-short-drama
Claude Code: added the loop hooks (Stop, PreToolUse) to ~/.claude/settings.json
```

#### 显示哪些应用有这个技能

```bash Terminal
minicut install-skill --status
```

```text Output
Claude Code: installed, ~/.claude/skills/miniharness-short-drama
Codex: not installed. Run: minicut install-skill --app codex
```

### 输出

技能装好了，或者状态打印出来了，退出码 0。下面这些情况退出码 2：

| 信息 | 怎么做 |
|---|---|
| `<folder> already exists. Add --force to copy the pack over it.` | 加上 `--force` |
| `No agent app home folder found under ~. Nothing written.` | 先安装你的 Agent 应用，或者使用 `--app` |
| `unknown app "<name>".` | 使用上表里的 id |

## minicut agent-rules

写下规则，让 Claude Code 或 Codex 可以运行 `minicut` 命令，其中要花钱或要移除东西的命令会先问你。

### Usage

```text Usage
minicut agent-rules [--app {claude-code|codex}] [--dry-run] [--json]
```

### 说明

对 Claude Code，`minicut agent-rules` 把规则加进 `~/.claude/settings.json`。对 Codex，加进 `~/.codex/rules/default.rules`。不加 `--app` 时，这两个应用中在这台电脑上的每一个它都会写。每条规则都写明这台电脑上 `minicut` 启动器的完整路径。已经有的规则不会重复添加，其他所有规则保持不变。

规则写好后重启 Codex，让它读到这些规则。

### 选项

| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `--app` | `claude-code` 或 `codex` | 找到的两个都写 | 要写规则的 Agent 应用 |
| `--dry-run` | 开关 | 关 | 打印它会添加的规则，什么都不写 |
| `--json` | 开关 | 关 | 打印一个 JSON 对象 |

### 示例

#### 看 Claude Code 的规则

```bash Terminal
minicut agent-rules --app claude-code --dry-run
```

```text Output
Claude Code: would add to ~/.claude/settings.json:
  permissions.allow: Bash(~/.minicut/bin/minicut *)
  permissions.ask: Bash(~/.minicut/bin/minicut uninstall*)
  permissions.ask: Bash(~/.minicut/bin/minicut * --yes*)
  sandbox.excludedCommands: ~/.minicut/bin/minicut *
```

### 输出

规则写好了，或者本来就有，退出码 0。这台电脑上两个应用都没有，或者设置文件不是合法的 JSON 时，退出码 2。后一种情况下，命令会打印要你手动添加的规则。两个应用都没有时，它打印：

```text Output
No Claude Code (~/.claude) or Codex (~/.codex) on this computer. Nothing written.
```

## 另见

[账号](/zh-cn/docs/cli/account) [全局选项](/zh-cn/docs/cli/global-options) [用 Agent 安装](/zh-cn/docs/cli/install-with-your-agent) [在终端安装](/zh-cn/docs/cli/install-in-a-terminal)