08-命令参考

# 08 · 命令参考

这是短参考，不代替 `--help` 和 `status --json`。当文档与程序输出不一致时，以当前程序的帮助和可用命令为准；`help --all` 能看到全部命令及其实现状态。

## 8.1 会话与状态

| 命令 | 用途 |
|---|---|
| `session new --name <名>` | 新建或指定会话 |
| `session list` | 列出会话 |
| `session show` | 查看会话详情 |
| `session reset --yes` | 清空当前会话状态 |
| `status --json` | 查看步骤、状态、可用命令和警告 |
| `show` | 查看对象模式设置（仅在步骤 1） |
| `next` / `back --yes` | 前进/后退（后退会清空图元） |
| `help --all` | 查看全部命令，含尚未实现的 |

## 8.2 图片与拟合

| 命令 | 用途 |
|---|---|
| `image add <路径>` | 导入图片 |
| `image info` | 查看尺寸、透明度等输入信息 |
| `image view --grid --out <路径>` | 生成带坐标网格的源图（`--out` 必填） |
| `fit recommend` | 根据输入特征给出参数建议 |
| `fit mode standard 或 transparent` | 选择拟合模式 |
| `fit shapes <n>` | 设置目标图元预算；只增不减 |
| `fit start` | 开始拟合；`--until full` 或 `initial`、`--timeout <秒>`、`--ack-high-res` |
| `fit resume` | 从已有图元继续跑到目标 |
| `fit status` | 查看阶段、数量和任务状态 |
| `fit clear --yes` | 清除拟合结果 |
| `advanced list` / `get` / `set` | 列参数 / 读参数 / 设置参数 |

`advanced set` 中改 `max-dim`、`use-custom-max-dim`、`max-dim-percent` 会清空已经拟合出的图元。`fit.pause` 尚未实现。

## 8.3 检查、区域与导出

| 命令 | 用途 |
|---|---|
| `inspect` | 查看当前拟合结果 |
| `inspect --zoom auto` | 自动放大到可判读尺度 |
| `inspect --compare <图路径,...>` | 与历史结果并排对照（需要取值） |
| `inspect --sheet --grid` | 拼版 / 叠加坐标网格（开关） |
| `region add <名> <x,y,w,h>` | 登记源图像素区域 |
| `region set/remove/clear` | 修改、删除、清空区域 |
| `region list` / `show` | 列出 / 查看区域 |
| `region fit <名> [--shapes n]` | 在区域内追加拟合 |
| `region optimize <名> [--ratio r]` | 区域内只删不补的回收 |
| `region inspect <名>` | 查看区域放大图 |
| `review set <名> --verdict ...` | 记录视觉评审（取值 `ok` 或 `needs-work`） |
| `review status` | 汇总评审进度 |
| `export dataset --out <目录>` | 导出 GEIMG 数据集 |

## 8.4 批量与协助

| 命令 | 用途 |
|---|---|
| `fit-sweep --corpus <目录> --out <目录>` | 批量扫描图元数与观感的关系 |
| `ai begin --note <说明>` / `ai end` | 在界面上显示/关闭“AI 操作中”覆盖层 |
| `gui open` | 把图形界面拉起来便于旁观 |

## 8.5 结构化结果

自动化脚本优先读取：

- `ok`：本次命令是否成功。
- `command`：实际执行的命令。
- `step`：当前流程步骤。
- `data`：命令产生的数据。
- `state`：会话状态快照。
- `available`：当前可执行命令。
- `warnings`：不阻止执行但需要关注的提示。
- `error.code/message/hint`：失败原因和恢复建议。

## 8.6 常见恢复

- **步骤错误**：运行 `status --json`，按 `available` 补齐前置操作。
- **缺少必填参数**：`image view` 需要 `--out`，`review set` 需要 `--verdict`，`export dataset` 需要 `--out`。
- **没有图元**：先确认图片不是全透明，再看 `image info`、模式和 `alternate-bg`。
- **超时**：降低试跑预算、缩短 `--timeout` 后用 `fit resume` 分段。
- **结果视觉不对**：用 `inspect --zoom auto` 和网格图，不要只看 RMSE。
- **命令“尚未实现”**：该命令属于规划项，用 `help --all` 确认状态，换用 `available` 里的等价命令。