# 参考 · 模型与感知

本页讲模型、视觉、语音、视频、建模和 Engine 的命令。这些命令通常要求该组织的 developer。运行前先登录。

member 也能运行以下命令：

| 命令 | 做什么 |
| --- | --- |
| `aidc models` | 看模型目录 |
| `aidc modeling models` | 看建模模型目录 |
| `aidc modeling estimate` | 估算建模费用 |
| `aidc video frames` | 从视频抽帧 |

每个 SDK 的概念和浏览器写法见 [模型 SDK](model.md)、[视觉 SDK](vision.md)、[语音 SDK](voice.md)、[视频 SDK](video.md) 和 [建模 SDK](modeling.md)。

> [!NOTE]
> 用法里的 `<模型>` 是模型的 id，用 `aidc models` 查。`<图>`、`<文件>` 和 `<视频>` 是本机的文件。`<名字>` 是摄像机的名字。`<世界 id>` 是世界的 id。`<智能体>` 是智能体的 id。`[…]` 是可选项，`a | b` 是二选一。
> member 运行要 developer 的命令时，服务端返回 403，退出码是 4。`aidc engine` 的命令返回 401，退出码是 3。
> 通用参数（`--json`、`--dry-run`、`-n`）见 [通用参数与环境变量](cli.md#通用参数与环境变量)。退出码见 [退出码](cli.md#退出码)。

| 命令 | 做什么 |
| --- | --- |
| [`aidc models`](#aidc-models) | 看模型目录，哪些模型能用 |
| [`aidc model chat`](#aidc-model-chat) | 用一个模型回答一句话 |
| [`aidc model decide`](#aidc-model-decide) | 在给定的选项里选一个，做分类或路由 |
| [`aidc vision inspect`](#aidc-vision-inspect) | 看图判断合格或不合格 |
| [`aidc vision detect`](#aidc-vision-detect) | 在图里找出物体，给出位置框 |
| [`aidc vision camera`](#aidc-vision-camera) | 管理组织的网络摄像机 |
| [`aidc vision camera list`](#aidc-vision-camera-list) | 列出摄像机 |
| [`aidc vision camera show`](#aidc-vision-camera-show) | 看一台摄像机 |
| [`aidc vision camera add`](#aidc-vision-camera-add) | 登记一台摄像机 |
| [`aidc vision camera probe`](#aidc-vision-camera-probe) | 连上摄像机，检查连接和编码 |
| [`aidc vision camera snapshot`](#aidc-vision-camera-snapshot) | 截一帧画面，保存成图片 |
| [`aidc vision camera remove`](#aidc-vision-camera-remove) | 删除一台摄像机 |
| [`aidc voice transcribe`](#aidc-voice-transcribe) | 把音频或视频里的话转成文字 |
| [`aidc voice translate`](#aidc-voice-translate) | 把一句话译成多种语言 |
| [`aidc voice minutes`](#aidc-voice-minutes) | 把逐字稿整理成会议纪要 |
| [`aidc video frames`](#aidc-video-frames) | 每隔几秒抽一帧 |
| [`aidc video inspect`](#aidc-video-inspect) | 逐帧检查视频，可以同时转写音轨 |
| [`aidc modeling`](#aidc-modeling) | 生成 3D 世界，管理锚点、导出和下载 |
| [`aidc engine`](#aidc-engine) | 管理智能体的回复规范、模型和 skill |

## aidc models

看模型目录：每个模型的类型和用途，以及现在能不能用。member 和 developer 都能用。

```bash
aidc models [--json]
```

```terminal title="看模型目录"
$ aidc models
● deepseek-flash           llm              最快、最省的通用文本模型：翻译、摘要、抽取、分类。默认关闭思考。
…
● gpt-6-luna               vision           多模态视觉模型：看图判断——质检、识别、读表。
● gpt-transcribe           speech           音频文件转文字，自带标点与语种识别；按秒计量。
…
● gpt-live-transcribe      realtime-speech  实时流式转写（WebRTC 浏览器直连，边说边出字）。
…
```

- `●` 表示模型现在能用。`○` 表示上游还没配置。
- 第二列是类型：`llm` 是文本模型，`vision` 是视觉模型，`speech` 是转写，`realtime-speech` 是实时转写，`router` 是决策模型。
- `--json` 输出 `models` 列表。

## aidc model chat

用一个模型回答一句话。可以带图片。要这家公司的 developer。

```bash
aidc model chat [-m <模型>] "<提示>" [--system "<指令>"] [--image <图>]… [--json-object] [--stream] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `-m`、`--model <模型>` | 用哪个模型 | `deepseek-flash` |
| `"<提示>"` | 要问的话。没有给提示时，从标准输入读 | — |
| `--system "<指令>"` | 系统指令，放在对话最前面 | — |
| `--image <图>` | 随提示发送的图片。可以重复。支持 jpg、jpeg、png、webp 和 gif | — |
| `--json-object` | 要求模型输出 JSON 对象 | 关 |
| `--stream` | 边生成边输出。加 `--json` 时不生效 | 关 |

```terminal title="翻译一句话"
$ aidc model chat "把「你好」翻成日语"
こんにちは
```

```terminal title="看一张图"
$ aidc model chat -m gpt-6-luna "图里有几个人？" --image photo.jpg
图里有两个人。
```

- 没有给提示时，命令从标准输入读。例如 `cat notes.txt | aidc model chat -m deepseek-flash`。
- `--json` 输出完整的响应。回复在 `choices[0].message.content`。
- 提示为空，或图片不存在，或图片格式不对：退出码 2。
- 用量记在组织名下。见 [用量与账单](billing.md)。

## aidc model decide

在给定的选项里选一个。用来做分类和路由。这个命令只选，不写任何东西。要这家公司的 developer。

```bash
aidc model decide --state "<文本>" --question <编号>=<说明> [--question …] --choice <编号>:<选项>=<判据> [--choice …] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--state "<文本>"` | 要判断的内容。必填 | — |
| `--question <编号>=<说明>` | 声明一个问题：编号和说明。可以重复。至少一个 | — |
| `--choice <编号>:<选项>=<判据>` | 给一个问题加一个选项。判据说明什么情况选它。可以重复。问题要先用 `--question` 声明 | — |

```terminal title="判断交给谁"
$ aidc model decide --state "发票什么时候开" --question route=交给谁 --choice route:finance=财务问题 --choice route:sales=销售问题
route: finance（置信度 93%）
```

- 每个问题的结果有三项：`choice`（选中的选项）、`confidence`（把握，0 到 1）和 `probabilities`（每个选项的概率）。
- `--json` 输出 `answers`。每个问题一项。
- 缺少 `--state` 或 `--question`，或者 `--choice` 指向没有声明的问题：退出码 2。

## aidc vision inspect

看图判断合格或不合格。按 `--task` 检查，按 `--criteria` 判定。要这家公司的 developer。

```bash
aidc vision inspect <图>… --task "<检查什么>" [--criteria "<判定标准>"] [-m <模型>] [--fail-on-defect] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<图>…` | 要检查的图片。可以写多张。支持 jpg、jpeg、png、webp 和 gif | — |
| `--task "<检查什么>"` | 要检查什么。必填 | — |
| `--criteria "<判定标准>"` | 什么算不合格。写清楚，判断更稳 | — |
| `-m`、`--model <模型>` | 视觉模型 | `gpt-6-luna` |
| `--fail-on-defect` | 有一张不合格，命令以退出码 1 结束 | 关 |

```terminal title="检查布面"
$ aidc vision inspect cloth-01.jpg cloth-02.jpg --task "布面有没有污渍、破洞" --criteria "任何肉眼可见的污渍或破损都判不合格"
✓ 合格  cloth-01.jpg
  布面平整，没有污渍和破洞。

✗ 不合格  cloth-02.jpg
  左下角有一处油污。
  1. 油污（high，置信度 91%） —— 左下角
```

- 结论有三种：`✓ 合格`、`✗ 不合格` 和 `? 拿不准`。图片模糊时，模型给出「拿不准」，不会硬判合格。
- 不合格的图，每处问题列在下面，带严重度（`low`、`medium` 或 `high`）和把握。
- 加 `--fail-on-defect` 时，有一张不合格，命令以退出码 1 结束。脚本里用它判断。
- `--json` 输出 `results`。每项有 `file`、`verdict`（`pass`、`fail` 或 `uncertain`）、`summary`、`findings` 和 `model`。

## aidc vision detect

在图里找出物体。每个物体给出类别、把握和位置框。要这家公司的 developer。

```bash
aidc vision detect <图>… [--labels <类别,…>] [--prompt "<说明>"] [--max <个数>] [-m <模型>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<图>…` | 要检测的图片。可以写多张 | — |
| `--labels <类别,…>` | 只找这些类别，用逗号分隔，最多 40 个 | 找出画面里所有显著的物体 |
| `--prompt "<说明>"` | 场景和类别的补充说明 | — |
| `--max <个数>` | 最多返回几个，1 到 100。按把握从高到低排 | 50 |
| `-m`、`--model <模型>` | 视觉模型 | `gpt-6-luna` |

```terminal title="检测仓库画面"
$ aidc vision detect warehouse.jpg --labels 人,叉车,托盘 --max 3
warehouse.jpg  3 个物体 —— 仓库通道，一台叉车载着托盘
  1. 叉车  92%  [0.612, 0.381, 0.884, 0.790]
  2. 托盘  87%  [0.700, 0.620, 0.830, 0.760]  载着纸箱
  3. 人  64%  [0.120, 0.300, 0.190, 0.640]
```

- 位置框是归一化坐标 `[x0, y0, x1, y1]`。左上角是 (0, 0)，右下角是 (1, 1)。换算成像素时，乘以图片的宽和高。
- 位置框是近似位置。适合计数和找位置，不是逐像素的分割。
- `--json` 输出 `results`。每项有 `file`、`objects`、`count`、`summary` 和 `model`。

## aidc vision camera

管理组织登记的网络摄像机（NVR 或 IP 摄像机）：列出、登记、探测、截图和删除。要该组织的 developer。

- 摄像机用 RTSP 协议，由平台代为连接。命令只连接摄像机取需要的数据，用完就断开。
- 摄像机的主机必须是公网地址。NVR 的端口要在路由器上映射到公网。
- 口令加密保存在平台里，任何接口都不回显。命令只从环境变量 `AIDC_CAMERA_PASSWORD` 或标准输入读口令。把口令写在命令行参数里，命令会拒绝。

### aidc vision camera list

列出组织登记的摄像机。要该组织的 developer。

```bash
aidc vision camera list [--json]
```

```terminal title="列出摄像机"
$ aidc vision camera list
nvr  演示 NVR  dahua  通道 1:大门,2:仓库  缺省 sub  上限 4 路  ✓ H264 25fps  nvr.example.com:554  用户 viewer  口令已存
```

- 每行依次是：名字、显示名、品牌、通道、缺省码流、同时观看的上限、最近一次探测的结果、连接地址、用户名和口令状态。
- 探测结果有三种：`✓ H264 25fps` 表示连接成功，`✗` 后面是错误，`· 未连接过` 表示还没有探测过。
- 口令状态只有两种：`口令已存` 和 `无口令`。
- 还没有登记摄像机时，命令提示用 `aidc vision camera add` 登记。
- `--json` 输出 `cameras` 列表。

### aidc vision camera show

看一台摄像机的设置和最近一次探测的结果。要这家公司的 developer。

```bash
aidc vision camera show <名字> [--json]
```

```terminal title="看一台摄像机"
$ aidc vision camera show nvr
nvr  演示 NVR  dahua  通道 1:大门,2:仓库  缺省 sub  上限 4 路  ✓ H264 25fps  nvr.example.com:554  用户 viewer  口令已存
```

- 口令被摄像机拒绝时，这一行的末尾显示「⚠️ 口令被拒」和时间。
- `--json` 输出 `camera`。

### aidc vision camera add

登记一台摄像机。命令整体替换同名摄像机的设置。要这家公司的 developer。

```bash
aidc vision camera add <名字> --host <地址> [--port <端口>] [--vendor dahua|hikvision|generic] [--path "<模板>"] [--username <用户名>] [--channels <通道>] [--title "<显示名>"] [--default-stream sub|main] [--max-viewers <人数>] [--allow-main-live] [--password-stdin] [--dry-run] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<名字>` | 摄像机的名字。小写字母开头，后面是字母、数字或连字符，2 到 48 个字符 | — |
| `--host <地址>` | 摄像机或 NVR 的外网地址或域名。不带 `rtsp://`。必填 | — |
| `--port <端口>` | 端口，1 到 65535 | 554 |
| `--vendor` | 品牌：`dahua`（大华）、`hikvision`（海康）或 `generic`（其他） | `dahua` |
| `--path "<模板>"` | 视频地址的路径模板。`generic` 必须写。可以用 `{channel}`（通道号）和 `{stream}`（码流） | 内置的路径 |
| `--username <用户名>` | 登录摄像机的用户名。建议用只读账号 | — |
| `--channels <通道>` | 通道。写法有 `1,2,3`、`1:大门,2:仓库` 和 `1-8`。通道号 1 到 256 | 通道 1，标题为空。更新时也使用此默认值 |
| `--title "<显示名>"` | 在列表里显示的名字 | 同 `<名字>` |
| `--default-stream` | 默认码流：`sub`（子码流，远程流畅）或 `main`（主码流，高清） | `sub` |
| `--max-viewers <人数>` | 同时观看的上限，1 到 16。用来保护 NVR 的带宽 | 4 |
| `--allow-main-live` | 允许实时观看主码流。不加时，只能看子码流 | 不允许 |
| `--password-stdin` | 从标准输入读口令。读取时去掉末尾的换行 | 读环境变量 `AIDC_CAMERA_PASSWORD` |
| `--dry-run` | 只显示计划，不保存。计划里不显示口令 | — |

```terminal title="登记摄像机"
$ AIDC_CAMERA_PASSWORD='<口令>' aidc vision camera add nvr --host nvr.example.com --username viewer --channels 1:大门,2:仓库 --title "演示 NVR"
已登记：nvr  演示 NVR  dahua  通道 1:大门,2:仓库  缺省 sub  上限 4 路  · 未连接过  nvr.example.com:554  用户 viewer  口令已存
下一步：aidc vision camera probe nvr
```

- 口令不回显。命令只显示「口令已存」或「无口令」。
- 没给口令时，保留已登记的口令。新登记的摄像机没有口令。
- 改了连接参数（地址、端口、用户名或口令），之前的探测结果和口令被拒后的冷却都会清掉。
- 内置的路径：大华是 `/cam/realmonitor?channel={channel}&subtype={stream}`，海康是 `/Streaming/Channels/{channel}0{stream}`。
- 实时观看主码流要开 `--allow-main-live`。截图用主码流，不需要这个选项。
- 给 `--password` 会被拒绝，退出码 2。

### aidc vision camera probe

连上摄像机，认证，读出编码和帧率。不拉流。要这家公司的 developer。

```bash
aidc vision camera probe <名字> [--channels <通道>] [--main | --sub] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--channels <通道>` | 要探测的通道。写法同 `aidc vision camera add`。一次最多 32 个 | 登记的第一个通道；没有登记时是 1 |
| `--main` | 探测主码流 | — |
| `--sub` | 探测子码流 | 子码流 |

```terminal title="探测通道"
$ aidc vision camera probe nvr --channels 1-2
✓ 通道 1  H265  25fps  320 ms
✓ 通道 2  H265  25fps  298 ms
```

- 口令被拒或连不上时，立即停止，不再试其他通道。摄像机会在多次失败后锁定账号，所以 aidc 不重试。
- 口令被拒后，这台摄像机 10 分钟内不再尝试。重新登记口令会解除这段冷却。
- 码流用 `--main` 或 `--sub`。`--stream` 不能用。
- 至少一个通道成功时，退出码是 0。无成功通道且发生认证失败时，退出码是 8。其他探测结果失败时，退出码是 1。
- `--json` 输出 `results`。每项有 `channel`、`ok`、`codec`、`framerate`、`elapsedMs` 和 `error`。

### aidc vision camera snapshot

截一帧画面，保存成图片。要这家公司的 developer。

```bash
aidc vision camera snapshot <名字> [--channel <通道>] [--main | --sub] [-o <文件>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--channel <通道>` | 通道号 | 登记的第一个通道；没有登记时是 1 |
| `--main` | 主码流，高清 | 主码流 |
| `--sub` | 子码流 | — |
| `-o`、`--out <文件>` | 保存到哪个文件。以 `.jpg`、`.jpeg` 或 `.png` 结尾，就转成图片。其他扩展名保存原始码流 | 当前目录下的 `<名字>-ch<通道>-<时间>.jpg` |

```terminal title="截图"
$ aidc vision camera snapshot nvr --channel 1 -o gate.jpg
/home/demo/gate.jpg  （H265 关键帧 412 KB，通道 1 main，1830 ms）
```

- 转成图片需要 ffmpeg。没有 ffmpeg 时，命令把原始码流存成 `.h264` 或 `.h265` 文件，退出码 1。装好 ffmpeg 后，用输出里的命令转换。
- ffmpeg 不在 `PATH` 上时，用环境变量 `AIDC_FFMPEG` 指定路径。
- `--json` 输出 `file`、`codec`、`channel`、`stream`、`bytes`、`elapsedMs` 和 `image`。

### aidc vision camera remove

删除一台摄像机，连同它的观看记录。要这家公司的 developer。

```bash
aidc vision camera remove <名字> [--yes] [--dry-run] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--yes` | 确认实际删除。实际删除时不加，命令报错，退出码 2。使用 `--dry-run` 时无需确认 | — |
| `--dry-run` | 只显示会删什么，不删 | — |

```terminal title="删除摄像机"
$ aidc vision camera remove nvr --yes
已删除 cell-demo/nvr（演示 NVR，观看留痕 12 条）
```

- 删除后，摄像机和它的观看记录都没有了。先用 `--dry-run` 看一看。

## aidc voice transcribe

把音频或视频里的话转成文字。要这家公司的 developer。

```bash
aidc voice transcribe <文件> [--language <语言>] [-m <模型>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<文件>` | 音频或视频文件。格式为 webm、ogg、mp3、m4a、mp4、wav 或 flac，且不超过 3.8 MB，可以直接传 | — |
| `--language <语言>` | 语言代码，例如 `zh`、`en` | 自动判断 |
| `-m`、`--model <模型>` | 转写模型 | `gpt-transcribe` |

```terminal title="转写会议录音"
$ aidc voice transcribe meeting.m4a --language zh
用 ffmpeg 转码 / 分段…
转写第 1/2 段…
转写第 2/2 段…
今天的议题有三个。
第一个是交付时间。
```

- 超过 3.8 MB 的音频，或格式不在上面列表里的文件，先用 ffmpeg 转码。转码后按每段 600 秒切段，每段分别转写，结果按顺序合在一起。
- 需要 ffmpeg 时，用环境变量 `AIDC_FFMPEG` 和 `AIDC_FFPROBE` 指定路径。
- `--json` 输出 `text` 和 `parts`（段数）。

## aidc voice translate

把一句话同时译成多种语言。要这家公司的 developer。

```bash
aidc voice translate "<文本>" --to <语言,…> [-m <模型>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `"<文本>"` | 要译的话 | — |
| `--to <语言,…>` | 目标语言的代码，用逗号分隔，例如 `ja,en,ar-EG`。必填 | — |
| `-m`、`--model <模型>` | 翻译用的模型 | `deepseek-flash` |

```terminal title="译成两种语言"
$ aidc voice translate "下周一上线新版本" --to ja,en
ja: 来週の月曜日に新バージョンを公開します。
en: We will release the new version next Monday.
```

- 语言代码的列表见 [语音 SDK](voice.md)。`ar-EG` 是埃及阿拉伯语。
- `--json` 输出 `translations`，键是语言代码，值是译文。

## aidc voice minutes

把会议逐字稿整理成会议纪要：议题、决议和待办。要这家公司的 developer。

```bash
aidc voice minutes <逐字稿.txt> [--title "<会议名>"] [-m <模型>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<逐字稿.txt>` | 逐字稿文件，UTF-8 文本 | — |
| `--title "<会议名>"` | 会议名，写进纪要的标题 | 模型根据内容起名 |
| `-m`、`--model <模型>` | 整理用的模型 | `deepseek-flash` |

```terminal title="整理纪要"
$ aidc voice minutes transcript.txt --title 周例会
# 周例会

本周讨论了交付时间。
```

- 输出是 Markdown 格式的纪要。
- 逐字稿超过 60,000 个字符时，只整理最后的 60,000 个字符。
- 没提到负责人或期限的待办，负责人和期限写空。
- `--json` 输出 `title`、`summary`、`decisions`、`actionItems`、`topics` 和 `markdown`。

## aidc video frames

每隔几秒抽一帧，保存成 JPEG 图片。这个命令不调用模型。member 和 developer 都能用，但要装 ffmpeg。

```bash
aidc video frames <视频> [--every <秒>] [--out <目录>] [--max <张数>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<视频>` | 视频文件 | — |
| `--every <秒>` | 每隔几秒抽一帧。要正数 | 5 |
| `--out <目录>` | 保存帧的目录。没有就建 | 系统临时目录里的新目录 |
| `--max <张数>` | 最多抽几张。不给，或给 0，就不限 | 不限 |

```terminal title="每 2 秒抽一帧"
$ aidc video frames line3.mp4 --every 2 --out frames
0.0s  frames/frame-0001.jpg
2.0s  frames/frame-0002.jpg
4.0s  frames/frame-0003.jpg
```

- 帧图片的长边不超过 1280 像素。
- 需要 ffmpeg。用 `AIDC_FFMPEG` 和 `AIDC_FFPROBE` 指定路径。没有 ffmpeg 时，命令给出安装方法，退出码 1。
- `--json` 输出 `frames` 列表。每项有 `time`（秒）和 `path`。

## aidc video inspect

每隔几秒抽一帧，逐帧让视觉模型检查。可以同时转写音轨。要这家公司的 developer，还要装 ffmpeg。

```bash
aidc video inspect <视频> --task "<检查什么>" [--every <秒>] [--max <张数>] [--criteria "<判定标准>"] [-m <模型>] [--transcribe] [--language <语言>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<视频>` | 视频文件 | — |
| `--task "<检查什么>"` | 要检查什么。必填 | — |
| `--every <秒>` | 每隔几秒抽一帧。要正数 | 5 |
| `--max <张数>` | 最多检查几帧 | 24 |
| `--criteria "<判定标准>"` | 什么算不合格 | — |
| `-m`、`--model <模型>` | 视觉模型 | `gpt-6-luna` |
| `--transcribe` | 同时转写音轨 | 不转写 |
| `--language <语言>` | 音轨的语言代码 | 自动判断 |

```terminal title="逐帧检查"
$ aidc video inspect line3.mp4 --every 5 --task "包装有没有破损"
检查 0.0s…
检查 5.0s…
…
24 帧，其中 1 帧不合格（35s）
0.0s  pass  包装完好
…
35.0s  fail  右侧纸箱破损
```

- 不论检查结果如何，这个命令都以退出码 0 结束。要用结果判断，读 `--json` 输出的 `failedFrames`。
- 视频超过「每隔几秒 × 张数」的时长时，后面的部分不检查。
- `--json` 输出 `frames`（每帧的结果）、`failedFrames`（不合格帧的时间）和 `transcript`。转写时，`transcript` 为 `{ text, parts }`，文字在 `transcript.text`。未转写时，`transcript` 为 `null`。

## aidc modeling

用世界模型把文字、一张或几张图、一张全景图或一段视频，变成可以走进去的 3D 世界。上游是 World Labs 的 Marble。额度、并发和账单都在平台一侧。

生成、上传、导出、设置锚点和删除，都要这家公司的 developer。登记（`aidc modeling import`）只对 AIDC 平台账号开放。`aidc modeling models` 和 `aidc modeling estimate` 登录后 member 也能用。花钱的命令先加 `--dry-run` 看估价和额度。

世界有四种状态：`queued`（排队）、`running`（生成中）、`succeeded`（完成）和 `failed`（失败）。列表里对应的符号是 `·`、`…`、`✓` 和 `✗`。

| 命令 | 做什么 |
| --- | --- |
| [`aidc modeling models`](#aidc-modeling-models) | 看模型、价目和当前策略 |
| [`aidc modeling estimate`](#aidc-modeling-estimate) | 算一次生成最少和最多花多少，在本机算 |
| [`aidc modeling budget`](#aidc-modeling-budget) | 看本月额度 |
| [`aidc modeling generate`](#aidc-modeling-generate) | 生成一个世界（花钱） |
| [`aidc modeling list`](#aidc-modeling-list) | 列出世界 |
| [`aidc modeling get`](#aidc-modeling-get) | 看一个世界的详情 |
| [`aidc modeling wait`](#aidc-modeling-wait) | 等一个世界生成完 |
| [`aidc modeling upload`](#aidc-modeling-upload) | 上传图片或视频，拿到 `mediaId` |
| [`aidc modeling anchors`](#aidc-modeling-anchors) | 设置世界里的锚点，绑到业务对象上 |
| [`aidc modeling export`](#aidc-modeling-export) | 导出 PLY 或 HQ 网格（花钱） |
| [`aidc modeling download`](#aidc-modeling-download) | 把世界的文件下载到本机 |
| [`aidc modeling import`](#aidc-modeling-import) | 登记已有的世界（AIDC 平台账号） |
| [`aidc modeling delete`](#aidc-modeling-delete) | 删除一个世界 |

### aidc modeling models

看模型、价目、当前策略，以及上游是否已配置。登录后 member 也能用。

```bash
aidc modeling models [--json]
```

```terminal title="看模型和价目"
$ aidc modeling models
上游：World Labs Marble（已配置）  1 USD = 1250 credits
● marble-1.0-draft   最快、最省：试提示词、看构图，每个世界约 US$0.12–0.20。
● marble-1.1         推荐的正式质量，价格固定，每个世界约 US$1.20–1.28。
○ marble-1.1-plus    最大的世界：按规模加收 0–1,500 credits，每个世界约 US$1.20–2.48。
○ marble-1.0         旧版模型，仅为兼容保留。
当前策略：单次上限 1600 credits · HQ 网格导出关闭 · 每公司每小时 10 次
```

- `●` 表示模型在当前策略里开放。`○` 表示没有开放。
- 上游显示「未配置」时，平台还不能生成世界。
- `--json` 输出完整的目录，包括价目表。

### aidc modeling estimate

算一次生成最少和最多花多少 credits。在本机算，不调用服务器。登录后 member 也能用。

```bash
aidc modeling estimate [-m <模型>] [--input <输入类型>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `-m`、`--model <模型>` | `marble-1.0-draft`、`marble-1.1`、`marble-1.1-plus` 或 `marble-1.0` | `marble-1.0-draft` |
| `--input <输入类型>` | `text`（文字）、`image`（单张图）、`pano`（全景图）、`multi-image`（多张图）或 `video`（视频） | `text` |

```terminal title="估价：试稿，文字"
$ aidc modeling estimate
  全景生成（文字）                 80 credits
  试稿世界生成                  150 credits
  合计 230 credits ≈ US$0.184
```

```terminal title="估价：Plus，文字"
$ aidc modeling estimate -m marble-1.1-plus --input text
  全景生成（文字）                 80 credits
  世界生成                   1500 credits
  按世界大小加收（上限）            1500 credits（按世界大小，最多）
  合计 1580–3080 credits ≈ US$1.26–US$2.46
```

- 「（按世界大小，最多）」表示这一项是上限。实际花的可能更少。
- 估价按最坏情况算。生成时预留的额度，也按这个最大值算。
- 1 美元等于 1250 credits。

### aidc modeling budget

看本月额度：组织上限、已结算、进行中的预留和剩余。按 UTC 的自然月算。要该组织的 developer。

```bash
aidc modeling budget [-n <cellId>] [--json]
```

```terminal title="看本月额度"
$ aidc modeling budget
2026-10  公司额度 6250 credits（US$5.00）：已结算 230 · 进行中预留 0 · 剩余 6020
```

- 「进行中预留」是还在生成的世界，按最坏情况占用的额度。
- 额度不够时，`aidc modeling generate` 以退出码 7 结束。
- 平台账号还会看到「全平台」一行，显示全平台的剩余额度。

### aidc modeling generate

生成一个 3D 世界。这个命令花钱。先用 `--dry-run` 看估价和额度。要这家公司的 developer。

```bash
aidc modeling generate (--text "<描述>" | --image <图> [--image <图>…] | --pano <全景图> | --video <视频>) \
  [--azimuth <角度,…>] [--reconstruct] [-m <模型>] [--name "<名字>"] [--seed <数字>] [--tag <标签>]… \
  [--max-credits <数字>] [--no-recaption] [--regenerate] [--idempotency-key <键>] [--dry-run] [--no-wait] \
  [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--text "<描述>"` | 用文字描述场景。可以单独用，也可以和图片、全景图或视频一起用，作为引导 | — |
| `--image <图>` | 图片。写一张是单张图生成；写多张是多张图生成。支持 jpg、jpeg、png 和 webp | — |
| `--azimuth <角度,…>` | 多张图时，每张图的方位角（度），用逗号分隔。数量要和图片一样多 | — |
| `--reconstruct` | 多张图时，按同一个空间重建 | 关 |
| `--pano <全景图>` | 360° 全景图，2:1 的等距柱状图 | — |
| `--video <视频>` | 视频，支持 mp4、webm、mov 和 avi。不超过 100 MB，时长不超过 30 秒。也可以写 https 地址 | — |
| `-m`、`--model <模型>` | `marble-1.0-draft` 是试稿，最便宜；`marble-1.1` 是正式质量 | `marble-1.0-draft` |
| `--name "<名字>"` | 世界的显示名 | — |
| `--seed <数字>` | 随机种子，非负整数。固定种子，结果更稳定 | — |
| `--tag <标签>` | 标签。可以重复，也可以用逗号分隔 | — |
| `--max-credits <数字>` | 这一次最多花多少 credits。最坏情况超过它，就拒绝，不调用上游 | 不设 |
| `--no-recaption` | 文字原样使用，不让模型改写 | 关，模型可以改写 |
| `--regenerate` | 同样的请求已有结果时，重新生成。会再花钱 | 关，直接复用已有结果 |
| `--idempotency-key <键>` | 幂等键，8 到 128 位，只用字母、数字和 `_ . : -`。网络重试时用同一个键 | 自动生成 |
| `--dry-run` | 只看估价和额度，不生成，不上传 | — |
| `--no-wait` | 提交后立即返回，不等完成 | 等到完成，约 5 分钟 |

输入只能选一种：`--image`、`--pano` 和 `--video` 不能同时用。`--text` 可以和它们一起用。

```terminal title="先看估价"
$ aidc modeling generate --text "一个整洁的装配工位" --dry-run
dry-run：marble-1.0-draft · text  最多 230 credits（US$0.184）  额度够，会放行
```

```terminal title="生成一个世界"
$ aidc modeling generate --text "一个整洁的装配工位" --name 装配工位
已提交 cm2k9f3a70001qz7d5w1b8x4n（最多 230 credits），通常 5 分钟左右…
running
succeeded
✓ cm2k9f3a70001qz7d5w1b8x4n  装配工位  marble-1.0-draft · text  230 credits（US$0.184）
```

- 同样的请求已有结果时，命令直接返回那个世界，不再花钱。要重新生成，加 `--regenerate`。
- 本地的图片、全景图和视频，直接上传到 World Labs，不经过 AIDC。上传前，确认你有权提供这些内容。
- 生成的是「看起来合理」的空间，不是测绘。尺寸验收、碰撞安全和机器人离线编程，不能只靠它。
- 退出码：额度不够，或每小时次数到上限，是 7。平台没有配置 World Labs，或生成失败，是 8。

### aidc modeling list

列出组织的世界，可以按状态筛选。要该组织的 developer。

```bash
aidc modeling list [--status queued|running|succeeded|failed] [--limit <数量>] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--status` | 只看一种状态 | 全部 |
| `--limit <数量>` | 最多列出几个 | 服务端的缺省 |

```terminal title="列出完成的世界"
$ aidc modeling list --status succeeded
✓ cm2k9f3a70001qz7d5w1b8x4n  装配工位  marble-1.0-draft · text  230 credits（US$0.184）
```

- 没有世界时，命令显示「还没有世界。」
- `--json` 输出 `worlds` 列表。

### aidc modeling get

看一个世界的详情：状态、资产、坐标系、锚点和导出。要这家公司的 developer。

```bash
aidc modeling get <世界 id> [-n <cellId>] [--json]
```

```terminal title="看一个世界"
$ aidc modeling get cm2k9f3a70001qz7d5w1b8x4n
✓ cm2k9f3a70001qz7d5w1b8x4n  装配工位  marble-1.0-draft · text  230 credits（US$0.184）
描述：一个整洁的装配工位，右侧是白色六轴机械臂
资产：SPZ 500k · 碰撞网格 GLB · 全景
坐标系：米、Y 向上、地面 y = 0（scale 0.412，地面偏移 -1.250）
锚点（rev 1）：焊接机械臂 R-01→production.equipment/R-01
```

- 「坐标系」一行说明单位和方向。位置单位是米，Y 轴朝上，地面是 y = 0。
- 「锚点」一行的 `rev` 是锚点的版本号。保存锚点时，用它做 `--if-rev`。
- `--json` 输出 `world`。

### aidc modeling wait

等一个世界生成完。每 5 秒查一次，最长等 20 分钟。要这家公司的 developer。

```bash
aidc modeling wait <世界 id> [--json]
```

```terminal title="等待完成"
$ aidc modeling wait cm2k9f3a70001qz7d5w1b8x4n
running
succeeded
✓ cm2k9f3a70001qz7d5w1b8x4n  装配工位  marble-1.0-draft · text  230 credits（US$0.184）
```

- 世界生成成功时，退出码 0。世界生成失败，退出码 8。
- 超过 20 分钟还没完成，命令报超时，退出码 1。之后用 `aidc modeling get` 查看。

### aidc modeling upload

把图片或视频上传到 World Labs，打印 `mediaId`。要这家公司的 developer。

```bash
aidc modeling upload <文件> [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<文件>` | 图片（jpg、jpeg、png 或 webp）或视频（mp4、webm、mov 或 avi）。视频不超过 100 MB | — |
| `--dry-run` | 不上传 | — |

```terminal title="上传图片"
$ aidc modeling upload cell.jpg
上传 cell.jpg（2.4 MB，直传 World Labs）…
mediaId 3f9a1c07d2e44b8a（生成时写 --image / --video 同一个文件会重新上传；用 API 可直接引用 mediaId）
```

- 文件直接传到 World Labs，不经过 AIDC。
- `mediaId` 只在上传它的组织里有效。
- `aidc modeling generate --image` 也会自动上传。不必先用这个命令。

### aidc modeling anchors

在世界里设置锚点。锚点把世界里的位置绑到业务对象上。整组替换这个世界的锚点。要这家公司的 developer。

```bash
aidc modeling anchors <世界 id> --file <锚点.json> [--if-rev <版本号>] [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--file <锚点.json>` | 锚点文件。内容是锚点的数组，或 `{ "anchors": [...] }`。必填 | — |
| `--if-rev <版本号>` | 上次读到的锚点版本号（`rev`）。别人改过，命令报冲突，退出码 6 | 不检查 |
| `--dry-run` | 不保存 | — |

锚点文件的例子：

```json
[
  {
    "id": "robot-1",
    "label": "焊接机械臂 R-01",
    "kind": "equipment",
    "position": [1.2, 0.8, -3.4],
    "object": { "type": "production.equipment", "pk": "R-01" },
    "meta": { "型号": "ER20" },
    "verified": true
  }
]
```

| 字段 | 说明 |
| --- | --- |
| `id` | 锚点的编号。同一个世界里不能重复 |
| `label` | 锚点的名字 |
| `kind` | 类型：`equipment`、`sensor`、`zone`、`camera` 或 `note` |
| `position` | 位置，三个数字，单位是米，格式为 `[x, y, z]` |
| `object` | 绑定的业务对象：`type` 是 Object Type，`pk` 是主键。Object Type 要存在于该组织的语义层里 |
| `verified` | 人已经核对过位置和身份，填 `true`。未核对的锚点只能当示意 |
| `meta` | 静态属性，例如型号、编号 |

一个世界最多 200 个锚点。

```terminal title="保存锚点"
$ aidc modeling anchors cm2k9f3a70001qz7d5w1b8x4n --file anchors.json --if-rev 0
1 个锚点已保存（rev 1）
```

- 加 `--dry-run` 时，输出是「dry-run：1 个锚点（未保存）」。
- 锚点没有变化时，输出「锚点没有变化」。

### aidc modeling export

导出世界的文件。PLY 是高斯溅射格式，免费。HQ 网格是 GLB 格式，要 3,500 credits。要这家公司的 developer。

```bash
aidc modeling export <世界 id> --ply [--resolution <质量>] [--json]
aidc modeling export <世界 id> --mesh [--variant textured|vertex_colored] [--dry-run] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--ply` | 导出高斯溅射 PLY。免费，立即完成 | — |
| `--resolution <质量>` | PLY 的质量：`100k`、`150k`、`500k` 或 `full_res` | 服务端的缺省 |
| `--mesh` | 导出 HQ 网格（GLB）。要 3,500 credits，同一个世界只收一次 | — |
| `--variant` | 网格类型：`textured`（带贴图）或 `vertex_colored`（顶点颜色） | 服务端的缺省 |
| `--dry-run` | 只看计划和估价，不导出 | — |

`--ply` 和 `--mesh` 只能选一个。两个都不写，或都写，命令报错，退出码 2。

```terminal title="HQ 网格被策略关闭"
$ aidc modeling export cm2k9f3a70001qz7d5w1b8x4n --mesh
错误：HQ 网格导出每个世界 3500 credits（约 US$2.8），当前策略里关闭；免费的替代：碰撞网格 assets.collider（GLB）或 PLY 高斯溅射导出。
$ echo $?
4
```

- 当前策略关闭 HQ 网格时，退出码 4。
- HQ 网格是异步生成的。命令打印「（HQ 网格异步生成，稍后 aidc modeling get 查看）」时，用 `aidc modeling get` 看进度。
- 世界还没生成完成时，不能导出：退出码 6。

### aidc modeling download

把一个已完成世界的文件下载到本机：高斯溅射 SPZ、碰撞网格、缩略图和 `world.json`。要这家公司的 developer。

```bash
aidc modeling download <世界 id> [--out <目录>] [--quality 100k|150k|500k|full_res] [--with-pano] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--out <目录>` | 保存到哪个目录。没有就建 | 以世界 id 为名的目录 |
| `--quality` | SPZ 的质量。质量越高，文件越大 | `500k` |
| `--with-pano` | 也下载全景图 `panorama.png` | 不下载 |

```terminal title="下载到本机"
$ aidc modeling download cm2k9f3a70001qz7d5w1b8x4n --out cell-01
下载 scene.spz…
下载 collider.glb…
下载 thumbnail.webp…
已存到 /home/demo/cell-01：scene.spz 3.1 MB、collider.glb 0.4 MB、thumbnail.webp 0.1 MB + world.json（坐标系与锚点在里面）
```

- 世界还没有生成完成时，退出码 6。
- 没有的资产不下载。
- `world.json` 里有坐标系和锚点。
- 资产的地址由 World Labs 的 CDN 提供，地址本身就是访问凭证。只把它交给有权看这个世界的人。

### aidc modeling import

登记一个已经在 World Labs 上的世界。登记不花钱。只有 AIDC 平台账号能用。

```bash
aidc modeling import (--world-id <world_id> | --snapshot <world.json>) [--name "<名字>"] [-m <模型>] [--input-kind <类型>] [--text "<描述>"] [--tag <标签>]… [--dry-run] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--world-id <world_id>` | World Labs 上的世界 id。与 `--snapshot` 二选一 | — |
| `--snapshot <world.json>` | 世界的快照文件，内容是 World API 返回的世界对象。与 `--world-id` 二选一 | — |
| `--name "<名字>"` | 显示名 | — |
| `-m`、`--model <模型>` | 世界用的模型 | 服务端的缺省 |
| `--input-kind <类型>` | 输入类型：`text`、`image`、`pano`、`multi-image` 或 `video` | — |
| `--text "<描述>"` | 输入的文字描述 | — |
| `--tag <标签>` | 标签。可以重复 | — |
| `--dry-run` | 只预演，不登记 | — |

```terminal title="登记已有的世界"
$ aidc modeling import --snapshot world.json --name 仓库一区
已登记：✓ cm2k9f3a70001qz7d5w1b8x4n  仓库一区  marble-1.1 · text  0 credits（US$0.000）  （登记）
```

- 不是 AIDC 平台账号时，命令返回 403，退出码 4。
- 同一个 `world_id` 在同一个组织里只能登记一次。再登记，返回已有的世界，输出「已存在」。

### aidc modeling delete

删除一个世界。平台记录打上删除标记。加 `--purge` 时，World Labs 上的原件也删除。要这家公司的 developer。

```bash
aidc modeling delete <世界 id> [--purge] [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--purge` | 同时删除 World Labs 上的原件。只对经平台生成的世界有效 | 不删原件 |
| `--dry-run` | 只预演，不删 | — |

```terminal title="删除世界"
$ aidc modeling delete cm2k9f3a70001qz7d5w1b8x4n --purge
已删除 cm2k9f3a70001qz7d5w1b8x4n（World Labs 上的原件也删除）
```

- 删除前，先用 `aidc modeling get` 看一看世界的内容。

## aidc engine

管理组织里智能体的配置：回复规范、模型、推理强度和 skill。要这家公司的 developer。member 运行时，服务端返回 401，退出码 3。

这些词的意思：

- **回复规范**（prompt）：规范正文加回复模板。有版本。
- **组织默认**：全部智能体都用的配置。一个智能体可以有自己的覆盖。
- **来源**：每项配置都写明来源：`自己`、`组织默认` 或 `运行时`。
- **试运行**：`aidc engine test` 用草稿和智能体聊一轮。草稿只对这一轮生效，不改配置。
- **应用**：`aidc engine apply` 把配置写进组织默认，或点名的智能体。先加 `--dry-run` 看计划。
- **变更**：配置发生变化时生成变更编号。无变化时不生成。`aidc engine revert` 用它撤销。
- **箱上原生的智能体**：运行在客户自己的服务器上的智能体。`aidc engine box` 管理它们。

| 命令 | 做什么 |
| --- | --- |
| [`aidc engine agents`](#aidc-engine-agents) | 看智能体和它们生效的配置 |
| [`aidc engine show`](#aidc-engine-show) | 看一个智能体的配置和来源 |
| [`aidc engine test`](#aidc-engine-test) | 用草稿试运行一轮，不改配置 |
| [`aidc engine apply`](#aidc-engine-apply) | 应用配置到组织默认或点名的智能体 |
| [`aidc engine prompts`](#aidc-engine-prompts) | 列出回复规范 |
| [`aidc engine prompt`](#aidc-engine-prompt) | 看一个回复规范的正文和版本 |
| [`aidc engine prompt create`](#aidc-engine-prompt-create) | 新建回复规范 |
| [`aidc engine prompt save`](#aidc-engine-prompt-save) | 给回复规范存一个新版本 |
| [`aidc engine prompt rename`](#aidc-engine-prompt-rename) | 给回复规范改名 |
| [`aidc engine prompt archive`](#aidc-engine-prompt-archive) | 归档回复规范 |
| [`aidc engine prompt unarchive`](#aidc-engine-prompt-unarchive) | 取消归档 |
| [`aidc engine templates`](#aidc-engine-templates) | 列出内置的回复规范模板 |
| [`aidc engine skills`](#aidc-engine-skills) | 列出平台下发的 skill |
| [`aidc engine models`](#aidc-engine-models) | 列出可用的模型 |
| [`aidc engine changes`](#aidc-engine-changes) | 列出变更记录 |
| [`aidc engine change`](#aidc-engine-change) | 看一条变更改了什么 |
| [`aidc engine revert`](#aidc-engine-revert) | 撤销一条变更 |
| [`aidc engine box`](#aidc-engine-box) | 看箱上原生的智能体和最近一次下发 |
| [`aidc engine box --sync`](#aidc-engine-box---sync) | 手动下发到箱上 |

### aidc engine agents

看组织的智能体和它们生效的配置。要这家公司的 developer。

```bash
aidc engine agents [-n <cellId>] [--json]
```

```terminal title="看智能体"
$ aidc engine agents
Demo Company（cell-demo）· 2 个智能体（共享池上 2、箱上原生 0）
运营助手（ops） · 已生效
    回复规范 简单明了 v2 [组织默认] · 模型 deepseek/deepseek-v4-pro [组织默认] · 推理 low [组织默认]
客服助手（service） · 下一轮生效 · 下一轮重起沙箱
    回复规范 客服答复 v1 [自己] · 模型 deepseek/deepseek-flash [组织默认] · 推理 — [运行时]
```

- 「未配置」表示智能体没有任何配置，用的是运行时的缺省。
- 「下一轮生效」表示下一轮对话才用上新配置。「下一轮重起沙箱」表示下一轮会重新启动沙箱。
- 箱上没找到的智能体，列在最后一行。
- `--json` 输出 `agents` 列表，和箱上没找到的智能体（`unmanaged`）。

### aidc engine show

看一个智能体的配置，以及每一项的来源。要这家公司的 developer。

```bash
aidc engine show <智能体> [--full] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<智能体>` | 智能体的 id。`aidc engine agents` 的括号里就是它 | — |
| `--full` | 打印下一轮带给智能体的回复规范全文 | 不打印全文 |

```terminal title="看一个智能体"
$ aidc engine show ops
运营助手（ops） · 已生效
    回复规范 简单明了 v2 [组织默认] · 模型 deepseek/deepseek-v4-pro [组织默认] · 推理 low [组织默认]
    补充 [自己]：周报用表格
```

### aidc engine test

用草稿和一个智能体聊一轮，看效果。草稿只对这一轮生效，不改配置。要这家公司的 developer。

```bash
aidc engine test <智能体> "<消息>" [--template <模板>] [--instructions-file <规则.md>] [--reply-template <模板.md>] [--extra "<补充>"] [--model <通道/模型>] [--reasoning <强度>] [--session <编号>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<智能体>` | 智能体的 id | — |
| `"<消息>"` | 要发的话 | — |
| `--template <模板>` | 用内置模板做草稿。模板名和说明见 [aidc engine prompt create](#aidc-engine-prompt-create) | — |
| `--instructions-file <规则.md>` | 用文件里的规范正文做草稿。比 `--template` 优先 | — |
| `--reply-template <模板.md>` | 用文件里的回复模板做草稿 | — |
| `--extra "<补充>"` | 只给这个智能体的补充说明 | — |
| `--model <通道/模型>` | 换一个模型做草稿，例如 `deepseek/deepseek-v4-pro`。只能选智能体现有通道里的模型 | 智能体当前的模型 |
| `--reasoning <强度>` | 推理强度：`none`、`low`、`medium`、`high` 或 `xhigh` | 智能体当前的强度 |
| `--session <编号>` | 续接同一段试运行的对话 | 新开一段 |

```terminal title="试运行一轮"
$ aidc engine test ops "这周的报表怎么写？" --template report
这周的报表分四段：结论、依据、风险、下一步。
（4.2 秒；续聊：--session cli-7c1e0a9b2d4f）
```

- 「草稿」指 `--template`、`--instructions-file`、`--reply-template`、`--extra`、`--model` 和 `--reasoning`。
- 同一个 `--session` 续接同一段对话。
- 输出里有「注意：这一轮走了兜底通道，草稿没有生效」时，这一轮的回复不是按草稿生成的。
- 试运行失败时，命令显示「试运行失败：…」，退出码 1。
- `--json` 输出 `session`、`reply`、`event` 和其他字段。

### aidc engine apply

把回复规范、模型、推理强度或 skill 应用到组织默认，或点名的智能体。要这家公司的 developer。先用 `--dry-run` 看计划。

```bash
aidc engine apply (--org [--all] | --agents <智能体,…>) [--prompt <id>[@版本] | --no-prompt] [--extra "<补充>"] [--extra-file <文件>] [--model <通道/模型>] [--reasoning <强度>] [--preload <skill,…>] [--enable <skill,…>] [--disable <skill,…>] [--inherit <skill,…>] [--unset <键,…>] [--note "<说明>"] [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--org` | 写进组织默认。全部智能体都用它，除非智能体有自己的覆盖。和 `--agents` 二选一 | — |
| `--all` | 和 `--org` 一起用。只撤掉本次修改的键和 skill 的覆盖。保留通道不同的模型覆盖 | 不撤 |
| `--agents <智能体,…>` | 只写点名的智能体。和 `--org` 二选一 | — |
| `--prompt <id>[@版本]` | 用哪个回复规范。写 `@版本` 用指定版本，例如 `p1@2`。不写版本，用最新版 | — |
| `--no-prompt` | 不用回复规范。和 `--prompt` 二选一 | — |
| `--extra "<补充>"` | 补充说明 | — |
| `--extra-file <文件>` | 从文件读补充说明。同时提供时，以 `--extra-file` 为准 | — |
| `--model <通道/模型>` | 模型，例如 `deepseek/deepseek-v4-pro` | 不改 |
| `--reasoning <强度>` | 推理强度：`none`、`low`、`medium`、`high` 或 `xhigh` | 不改 |
| `--preload <skill,…>` | 预载的 skill | 不改 |
| `--enable <skill,…>` | 打开的 skill | 不改 |
| `--disable <skill,…>` | 停用的 skill | 不改 |
| `--inherit <skill,…>` | 撤掉这些 skill 的覆盖，回到继承 | 不改 |
| `--unset <键,…>` | 撤掉这些键的值，回到继承 | 不改 |
| `--note "<说明>"` | 写进变更记录的说明 | — |
| `--dry-run` | 只看计划，不写 | — |

```terminal title="先看计划"
$ aidc engine apply --agents ops --model deepseek/deepseek-v4-pro --dry-run
…
  运营助手：模型 deepseek/deepseek-flash → deepseek/deepseek-v4-pro
```

```terminal title="应用到组织默认"
$ aidc engine apply --org --all --prompt p1 --note "统一汇报格式"
已应用（变更 cm2m1q8b30003qz7d5w1b8x4n，撤销：aidc engine revert cm2m1q8b30003qz7d5w1b8x4n）：…
```

- 计划的第一行是服务端写的摘要。这里用 `…` 代替。
- 加 `--dry-run` 时，不写任何东西。
- 别人在同一时间改了同一项，命令返回 409 冲突，退出码 6。这次不写。
- 配置发生变化时生成变更编号。无变化时不生成。要撤销，用 `aidc engine revert <变更编号>`。
- 输出里有「下一轮重起沙箱」的智能体，它的沙箱在下一轮会重新启动。

### aidc engine prompts

列出组织的回复规范：名字、最新版本和正在用它的智能体数。要这家公司的 developer。

```bash
aidc engine prompts [--archived] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--archived` | 也列出已归档的回复规范 | 不列 |

```terminal title="列出回复规范"
$ aidc engine prompts
p1  简单明了 · 第 2 版 · 3 个在用
p2  客服答复 · 第 1 版 · 1 个在用
```

- 还没有回复规范时，命令提示用 `aidc engine prompt create` 新建一个。
- `--json` 输出 `data` 列表。

### aidc engine prompt

看一个回复规范的正文和版本。要这家公司的 developer。

```bash
aidc engine prompt <id> [--version <版本号>] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<id>` | 回复规范的 id。`aidc engine prompts` 的第一列 | — |
| `--version <版本号>` | 看一个指定的版本的正文和回复模板 | 最新版 |

```terminal title="看回复规范"
$ aidc engine prompt p1
简单明了（p1）· 第 2 版 · 3 个智能体在用
先给结论，五句以内说完。适合日常问答、IM 里的快速答复。

…（规范正文）
版本：1、2（缩短开头）
```

- 「版本」一行列出所有版本。有说明的版本，后面带括号。

### aidc engine prompt create

新建一个回复规范。可以用内置模板，也可以用自己写的规范文件。要这家公司的 developer。

```bash
aidc engine prompt create "<名字>" [--template <模板>] [--file <规则.md>] [--reply-template <模板.md>] [--description "<说明>"] [--note "<说明>"] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `"<名字>"` | 回复规范的名字 | — |
| `--template <模板>` | 内置模板，见下表。与 `--file` 至少提供一个 | — |
| `--file <规则.md>` | 规范正文文件。与 `--template` 至少提供一个。同时提供时，非空文件正文覆盖模板正文 | — |
| `--reply-template <模板.md>` | 回复模板文件 | 模板自带的 |
| `--description "<说明>"` | 一句话说明 | — |
| `--note "<说明>"` | 第一版的版本说明 | — |

内置模板：

| 模板 | 名字 | 适合什么 |
| --- | --- | --- |
| `ste100` | ASD-STE100 简化技术语言 | 一句一事、主动句、一词一义。适合操作说明、技术答复和给一线员工的回复 |
| `concise` | 简单明了 | 先给结论，五句以内说完。适合日常问答和 IM 里的快速答复 |
| `report` | 结构化汇报 | 结论、依据、风险、下一步四段。适合给管理层的汇报和周报 |
| `service` | 客服答复 | 先确认问题，再给步骤，最后问是否解决。适合对客户和员工的服务类回复 |
| `data` | 数据回答 | 数字带口径和来源，多行数据用表格。适合回答业务数字 |

```terminal title="用模板新建"
$ aidc engine prompt create "简单明了" --template concise
已建回复规范「简单明了」（p1，第 1 版）。应用：aidc engine apply --org --all --prompt p1 --dry-run
```

- 新建的规范还没有用在任何智能体上。用 `aidc engine apply` 应用。

### aidc engine prompt save

给一个回复规范存一个新版本。跟着最新版的智能体，下一轮就用新版本。要这家公司的 developer。

```bash
aidc engine prompt save <id> --file <规则.md> [--reply-template <模板.md>] [--note "<说明>"] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--file <规则.md>` | 新版本的规范正文。必填 | — |
| `--reply-template <模板.md>` | 新版本的回复模板 | 沿用最新版的模板 |
| `--note "<说明>"` | 这一版的说明 | — |

```terminal title="存新版本"
$ aidc engine prompt save p1 --file 规则.md --note "缩短开头"
已存第 3 版。跟最新版的 3 个智能体下一轮就用它。
```

### aidc engine prompt rename

给回复规范改名。要这家公司的 developer。

```bash
aidc engine prompt rename <id> "<新名字>" [--json]
```

```terminal title="改名"
$ aidc engine prompt rename p2 "客服答复（新）"
已改名：客服答复（新）
```

### aidc engine prompt archive

归档一个回复规范。归档后，新的智能体不能引用它。已经在用的智能体照旧生效。要这家公司的 developer。

```bash
aidc engine prompt archive <id> [--json]
```

```terminal title="归档"
$ aidc engine prompt archive p2
已归档「客服答复」：不能再被新引用，已引用的 1 个照旧生效。
```

### aidc engine prompt unarchive

取消归档一个回复规范。要这家公司的 developer。

```bash
aidc engine prompt unarchive <id> [--json]
```

```terminal title="取消归档"
$ aidc engine prompt unarchive p2
已取消归档「客服答复」。
```

### aidc engine templates

列出内置的回复规范模板。要这家公司的 developer。

```bash
aidc engine templates [--json]
```

```terminal title="看内置模板"
$ aidc engine templates
ste100    ASD-STE100 简化技术语言 —— 一句一事、主动句、一词一义。适合操作说明、技术答复、给一线员工的回复。
concise   简单明了 —— 先给结论，五句以内说完。适合日常问答、IM 里的快速答复。
…
```

- 完整的五个模板，见 [aidc engine prompt create](#aidc-engine-prompt-create)。

### aidc engine skills

列出平台下发给这个组织的 skill。每个 skill 显示预载和停用的智能体数。要这家公司的 developer。

```bash
aidc engine skills [-n <cellId>] [--json]
```

```terminal title="列出 skill"
$ aidc engine skills
semantic-loops@1.2.0 · 预载 2 · 停用 0
    查询 Semantic 里的对象，按自然语言回答业务问题。
```

- skill 目录暂时读不到时，命令显示「skill 目录暂时读不到，稍后再试。」
- `--json` 输出 `available` 和 `skills`。

### aidc engine models

列出可用的模型通道和模型，以及每个模型有几个智能体在用。要这家公司的 developer。

```bash
aidc engine models [-n <cellId>] [--json]
```

```terminal title="列出模型"
$ aidc engine models
DeepSeek（通道 deepseek）
    ● deepseek/deepseek-v4-pro  2 个在用
    ○ deepseek/deepseek-flash
```

- `●` 表示有智能体在用。`○` 表示没有。
- 「通道/模型」是 `--model` 的写法。

### aidc engine changes

列出最近的变更：编号、时间、操作人和摘要。要这家公司的 developer。

```bash
aidc engine changes [-n <cellId>] [--json]
```

```terminal title="列出变更"
$ aidc engine changes
cm2m1q8b30003qz7d5w1b8x4n  2026-10-08 13:41  zhang.san  统一汇报格式
cm2m0x3k20001qz7d5w1b8x4n  2026-10-08 10:05  zhang.san  组织默认：推理 low（已撤销）
```

- 撤销过的变更，行尾有「（已撤销）」。
- 还没有变更时，命令显示「还没有变更。」

### aidc engine change

看一条变更改了什么：每一项改前和改后的值。要这家公司的 developer。

```bash
aidc engine change <变更编号> [-n <cellId>] [--json]
```

```terminal title="看一条变更"
$ aidc engine change cm2m1q8b30003qz7d5w1b8x4n
统一汇报格式
  组织默认
    之前 {"model":"deepseek/deepseek-flash"}
    之后 {"model":"deepseek/deepseek-v4-pro"}
```

### aidc engine revert

撤销一条变更，恢复变更前的值。撤销本身也是一条新变更。要这家公司的 developer。

```bash
aidc engine revert <变更编号> [-n <cellId>] [--json]
```

```terminal title="撤销变更"
$ aidc engine revert cm2m1q8b30003qz7d5w1b8x4n
已撤销（新变更 cm2m2b7d90004qz7d5w1b8x4n）：…
  组织默认：模型 deepseek/deepseek-v4-pro → deepseek/deepseek-flash
```

### aidc engine box

看箱上原生的智能体，以及最近一次下发到箱上的结果。要这家公司的 developer。

```bash
aidc engine box [-n <cellId>] [--json]
```

```terminal title="看下发结果"
$ aidc engine box
箱上原生的智能体 2 个 · 最近请求 2026-10-08 13:41（zhang.san，重启方式 safe）
最近一次 2026-10-08 13:42 · 成功
智能体：ok 2
  hermes-ops：重启 safe
```

- 应用或撤销配置后，平台会自动下发到箱上。手动下发，用 `aidc engine box --sync`。
- 还没有下发过时，命令显示「箱上原生的智能体 N 个，还没下发过。」

### aidc engine box --sync

手动补一次下发到箱上。只记下请求。平台的心跳会在 1 到 2 分钟内下发。要这家公司的 developer。

```bash
aidc engine box --sync [--restart safe|never] [--reason "<原因>"] [--dry-run] [-n <cellId>] [--json]
```

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `--restart safe\|never` | 下发后怎样重启箱上的单元。两种取值的区别见下面 | `safe` |
| `--reason "<原因>"` | 写进请求记录的原因 | — |
| `--dry-run` | 只看要下发的摘要，不记请求 | — |

```terminal title="手动下发"
$ aidc engine box --sync --restart safe --reason "更新回复规范"
已记下发请求（2 个箱上智能体，重启方式 safe）：平台心跳 1–2 分钟内下发。看结果：aidc engine box
```

- `safe`：避开整点前后 5 分钟。保护正在执行的任务，以及计划时间在过去 30 分钟至未来 10 分钟内的低频任务。每小时一次或更频繁的待执行任务不阻止重启。一次最多重启 4 个单元，其余下一拍再试。
- `never`：只写配置，不重启。
- 立刻重启不开放给这个命令。它会打断定时任务和对话，只走运维通道。
- `--restart` 只能是 `safe` 或 `never`。写别的值，命令报错，退出码 2。
- `--dry-run` 的输出是「计划（没有记请求）」，列出每个箱上智能体的回复规范、预载和停用的 skill。

## 下一步

- [参考 · 账号与环境](cli-account.md)：登录、退出、个人工作台和更新。
- [参考 · 应用与界面](cli-apps.md)：应用的校验、部署和发布。
- [模型 SDK](model.md)、[视觉 SDK](vision.md)、[语音 SDK](voice.md)、[视频 SDK](video.md)、[建模 SDK](modeling.md)：每个 SDK 的概念和浏览器写法。
- [交互界面](cli-chat.md)：直接敲 `aidc`，在终端里和智能体对话。