02-CLI工作流

# 02 · CLI 工作流

## 2.1 四步状态机

GEIMG CLI 将 GUI 的主流程暴露为四步：

| 步骤 | 含义 | 主要操作 |
|---|---|---|
| `setup` | 项目和对象模式 | `set project-name`、`set object-type` |
| `image` | 图片输入 | `image add`、`image info`、`image view --grid --out` |
| `fitting` | 拟合和检查 | `fit`、`advanced`、`inspect`、`region`、`review` |
| `export` | 输出数据集 | `export dataset` |

CLI 对外步骤使用 1-based 编号；实现内部是 0-based。脚本不要混用两套编号。

## 2.2 会话优先

每次命令读取会话状态、执行操作，再写回会话。这样可以在命令超时或进程退出后继续，不必把全部流程塞进一个长进程。

常见会话命令：

```bash
GE_IMG_Tool.exe session new --name demo
GE_IMG_Tool.exe session list
GE_IMG_Tool.exe session show --json
GE_IMG_Tool.exe session reset --yes
GE_IMG_Tool.exe status --json
```

`--session <名>` 或环境变量 `GEIMG_SESSION` 可以指定另一个会话；批量任务建议显式指定 `--session-dir`，避免多个任务互相覆盖同一个会话。

## 2.3 结构化输出

自动化调用优先使用 `--json`。输出通常包含以下信息：

```json
{
  "ok": true,
  "command": "fit start",
  "step": "fitting",
  "data": {},
  "state": {},
  "available": [],
  "warnings": [],
  "error": null
}
```

失败时不要只看进程退出码，也要读取 `error.code`、`error.message` 和 `error.hint`。成功后用 `state` 和 `available` 决定下一条命令。

## 2.4 拟合的可恢复操作

```bash
GE_IMG_Tool.exe fit status --json
GE_IMG_Tool.exe fit start --until full --json
GE_IMG_Tool.exe fit resume --json
GE_IMG_Tool.exe fit clear --yes --json
```

`fit resume` 从会话里已有的图元继续跑到目标，等价于 `fit start --until full`；它要求会话里已经有图元，否则改用 `fit start`。暂停（`fit pause`）、撤销/重做和检查点目前仍是计划中的命令，执行会得到“尚未实现”。

拟合分初步铺色和高精度补图元两个阶段。`fit start --until full` 跑到目标数量，`--until initial` 只完成初步阶段；还接受 `--timeout <秒>` 与 `--ack-high-res`。可用命令始终以 `status --json` 的 `available` 字段为准。

## 2.5 观察和视觉验收

```bash
GE_IMG_Tool.exe inspect --json
GE_IMG_Tool.exe inspect --zoom auto --json
GE_IMG_Tool.exe inspect --sheet --zoom auto --json
GE_IMG_Tool.exe inspect --compare "<历史结果图或结果目录>" --json
GE_IMG_Tool.exe review status --json
```

`--sheet`、`--grid` 是开关，`--compare` 需要一个取值：要并排对照的历史结果图路径，多个用逗号分隔，也可以给结果目录（自动取其中的结果图）；路径不存在时该张对照会被跳过并给出提示。

`inspect` 的图片产物比单个数值更重要。`review` 用于把已经看过的区域和结论记录下来，避免只凭某次终端输出判断完成。

## 2.6 区域拟合

全局拟合跑满后，再为有语义的区域登记坐标并补精度：

```bash
GE_IMG_Tool.exe region add face 120,80,180,220
GE_IMG_Tool.exe region list --json
GE_IMG_Tool.exe region show face --json
GE_IMG_Tool.exe region fit face --shapes 300 --json
GE_IMG_Tool.exe region inspect face --zoom auto --json
```

区域矩形是紧跟在区域名后的位置参数 `x,y,w,h`，单位是源图像素；登记前先用 `image view --grid --out <路径>` 的网格图确认坐标，凭目测估坐标容易整体偏出几十像素。`region fit` 的 `--shapes` 会顺带抬高目标数量。

区域拟合不是把整张图片重新拟合一遍，而是把新增预算放到更值得保留细节的地方。`region optimize` 是只删不补的回收操作，用之前先确认它没有伤到区域内特征。

## 2.7 已废弃与计划中的入口

早期设计里出现过无状态 `render`、`seed`、独立 `refine` 等命令，它们不属于当前工作流。当前结果应从会话状态、`inspect` 和 `export dataset` 获取。

`fit.pause`、`fit.undo`、`fit.redo`、`attempts.*`、`checkpoint.*`、`preview.*`、`settings.*` 等命令已列入规划但尚未实现。用 `help --all` 可以看到全部命令及其状态。