细节命令见 `commands/projects.md`、`commands/node.md`、`node-types/`。本页是画布主链摘要 + 节点数据契约 + 错误对照。

命令编排：Agent 调用 `{baseDir}/bin/drowup.exe`。CLI 没有的命令才读 `references/http.md`。

登录：`drowup login`（官网 OAuth；Desktop 已登录可复用 `oauth.json`）。请求头 `x-token`。会话在 `%APPDATA%\drowup\oauth.json`。

`{baseDir}` 指本技能包所在目录。CLI 入口：

```bash
"{baseDir}/bin/drowup.exe" <命令> --json
```

## 列出与打开画布

用户要**新画布**：不要先 `projects list`。

```bash
"{baseDir}/bin/drowup.exe" projects create 裂变主图 --json
```

立刻把返回的 `projectUrl` 给用户。命令内部 POST `/assetCanvas/workspace/save`，并 `project use` 绑定当前目录。

用户点名**已有画布**：`project use` 或 `-p`，不要全量 list。只有用户没点名、要你找一张时才 `projects list --keyword`。

```bash
"{baseDir}/bin/drowup.exe" projects list --keyword 毛衣 --json
"{baseDir}/bin/drowup.exe" projects get PROJECT_UUID --json
"{baseDir}/bin/drowup.exe" project use PROJECT_UUID --json
```

`projects get` 返回节点 `id / type / data.label|content|prompt|model|modelId` 和边 `source / target / type`。后续 `--left` 用这些 id 或展示名，不要发明 ID。

复制、删除在网页画布页完成。套个人工作流模板用 `drowup workflow apply`，见 `commands/workflow.md`。

## 目录绑定（project use 后免 -p）

```bash
"{baseDir}/bin/drowup.exe" project use PROJECT_UUID --json
"{baseDir}/bin/drowup.exe" project unuse --json
```

`project use` 把画布 UUID 写进当前目录 `.drowup/project.json`（向上逐层查找）。绑定后本目录下 `node list|create|run|delete`、`runs list`、`billing summary` 都免 `-p`。优先级：`-p` 旗标 > 管道 JSON > `DROWUP_PROJECT_UUID` > 目录绑定。

## 选模型

```bash
"{baseDir}/bin/drowup.exe" model search --type image --json
"{baseDir}/bin/drowup.exe" model search --type video --json
"{baseDir}/bin/drowup.exe" model search --type text --json
"{baseDir}/bin/drowup.exe" model <modelKey> --json
```

`model <modelKey|modelName|id>` 跨模态精确匹配并返回该模型的完整条目（含参数 schema 字段，如 ratio/count 等）。模型目录条目：`id`（记录主键）、`modelKey`（上游模型 key）、`modality`、`isDefault`。

## 节点数据契约（model/modelId 从哪来）

- 生成型节点（text/script/image/video/audio）**必须**在 `data` 里带 `model`（= 目录里的 `modelKey`）与 `modelId`（= 目录 `id`/`ID`，**必须 >0，不能是 0**）。
- 模型目录映射：text/script 走 `chat`（LLM），image/video/audio 走同名目录。目录 JSON 可能是 GORM 的 `ID` 大写，CLI 两种都认。
- 缺了这两个字段，或 `modelId` 是 0，服务端生成会报「该模型在当前套餐下尚未配置积分价格」。常见不是真没配价，而是计价时拿到的 modelId 仍是空的（一步式 `--run` 曾在图快照可见之前就 POST `/runs`）。
- `node create` 时：`-s/--model` 传 `modelKey`（或目录 id），CLI 反查目录写回 `model + modelId`；不传则自动取该模态的 `isDefault` 模型。反查不到有效 id 会直接报错，不会写成 0。返回值里带 `model: {model, modelId, source}`，核对 `modelId > 0`。
- `--run` / `node run`：CLI 会重读画布，并用最新 version 调 `/runs`，请求体带 `model`+`modelId`（网页点生成也是这样）。缺模型或 `modelId` 是 0 直接报「节点未指定模型」，不发请求。
- 只有 style/mediaUpload/group 等不生成内容的节点才不需要模型。

## 建节点、连线、生成

语义：`node create` 只新建；`-t` 必填；`--left` 把已有节点连到新节点左侧；`--run` 新建后立即生成，并阻塞到 CLI 退出。

```bash
"{baseDir}/bin/drowup.exe" node create 卖点 -t text --prompt "15分钟出冰" -p PROJECT_UUID --json
"{baseDir}/bin/drowup.exe" node create 主图 -t image --prompt "白底主图，棚拍居中" -p PROJECT_UUID --left 卖点 --run --json
"{baseDir}/bin/drowup.exe" node create 主图 -t image -s <modelKey> --prompt "白底主图" -p PROJECT_UUID --run --json
"{baseDir}/bin/drowup.exe" node create 成片 -t video --prompt "15秒展示" -p PROJECT_UUID --left 主图 --run --json
"{baseDir}/bin/drowup.exe" node run 主图 -p PROJECT_UUID --json
"{baseDir}/bin/drowup.exe" node delete 主图 -p PROJECT_UUID --json
```

`--left` 可重复。CLI 按网页边规则选择：

- 文本 / 风格 → 图、视频、文本、音频：`promptOrder`
- 图 → 图 / 文本：`imageOrder`
- 图 → 视频：`imageRole`

不要靠把结果 URL 写进下一句提示词来连线。一次 `node create` 只建一个节点；用户要 N 张可独立编辑的图，就调用 N 次。

## 管道串联

`node create --run --json` 输出一行 JSON（含 `projectUuid` / `nodeId` / 生成结果）。把这一行喂给下一个命令，它自动接上下文——下一个 `node create` 不写 `-p` 和 `--left` 也能连到上一个节点：

```bash
"{baseDir}/bin/drowup.exe" node create 主图 -t image --prompt "白底主图" -p P --run --json |
  "{baseDir}/bin/drowup.exe" node create 详情图 -t image --prompt "细节特写" --run --json
```

## 下载产物

```bash
"{baseDir}/bin/drowup.exe" download -n 主图 -p PROJECT_UUID --out ./out --json
```

按节点 id 或展示名取生成产物（读 data.url/remoteUrl/imageUrl/outputUrl/poster 与 urls/outputUrls/images/videos 数组）。单文件直存为 `<节点名>.<扩展名>`，多文件加序号。缺 `--out` 存当前目录。没有产物时报错并指路 `node run`。

## 上传参考图

```bash
"{baseDir}/bin/drowup.exe" upload ./ref.png --json
```

## 错误对照

| 报错 | 原因 | 处置 |
| --- | --- | --- |
| 节点「X」未指定模型（model/modelId 缺失或 modelId 不能是 0） | 节点没模型，或 modelId 是 0 | `node <名> -s model=<模型>` 重查目录 |
| 该模型在当前套餐下尚未配置积分价格 | 计价时 modelId 为空（一步式 `--run` 曾早于图快照），或节点没模型，或该模型确实没配价 | 先看 data.modelId 是不是 >0；有就 `node run <id>`；仍报错才去查套餐定价 |
| 找不到模型「X」。可用：… | -s 传了不存在的 key | 按可用清单或 `model search` 结果重传 |
| 找不到节点：X / 有多个同名节点 | --left 或 node run 的展示名不准 | 用 `projects get` 里的节点 id |

## 命令速查表（画布域）

| 动作 | 命令 |
| --- | --- |
| 新建个人画布 | `projects create <名>` |
| 绑定画布到目录 | `project use <uuid>` / `project unuse` |
| 新建节点 | `node create <名> -t <type> [-s 模型] [--prompt] [--left] [-g 组] [--run]` |
| 改已有节点 | `node <名> [--prompt] [--name] [-s k=v] [-u k=v] [--left/--right/--left-add/--left-rm/--right-add/--right-rm] [--run]` |
| 列出节点 | `node list [-g 组]` |
| 删除节点 | `node delete <名>` |
| 单独生成 | `node run <名>` |
| 分组 | `group create <名>` / `group list` / `group use <名>` / `group unuse` |
| 模型目录 | `model search --type <type> [关键词]` / `model <名>`（schema） |
| 上传素材 | `upload <文件>` / `upload <文件> --as-node <显示名>`（建素材节点） |
| 下载产物 | `download -n <节点名> [--out 目录]` |
| 运行记录 / 账单 | `runs list\|get\|cancel` / `billing summary` |

## 已下线

不要使用 `session create` / `session graph` / `session run` / `session query` / `run` / `models list`，也不要运行任何 `*.py`。产物落地用 `download -n`。
