maoda-commander-tt 0.0.56 → 0.0.58

package/README.md

@@ -1,7 +1,7 @@
 # tt-cli (`tt`)
 
-一个 AI-native 的通用 CLI：默认调用方是 AI agent。每个命令在 stdout 只输出一行
-JSON envelope，诊断与进度走 stderr，失败退出码为 1，`--help` 自带面向 agent 的调用契约。
+一个 AI-native 的通用 CLI：默认调用方是 AI agent。JSON 模式的命令在 stdout 只输出
+一行 envelope，诊断与进度走 stderr，失败退出码为 1；透传命令在 `--help` 中声明输出模式。
 基于 [commander](https://github.com/tj/commander.js) 与 [rockbed](https://www.npmjs.com/package/rockbed)
 （`Result` / `Disposable` / `Emitter`）。
 
@@ -12,7 +12,7 @@ JSON envelope，诊断与进度走 stderr，失败退出码为 1，`--help` 自
 - **命令只返回 `Result<TData>`** — `ok(data)` / `fail(code, msg, { stage, nextCommand, ... })`，
   基类负责输出与退出码；`passthrough` 模式用于透传 git、开发服务器等面向人的场景
 - **清晰分层** — `core`（框架）→ `commands`（表现）→ `modules`（领域）→ `bedrock`（基础设施）
-- **可发现性** — `tt --help` 列公开命令，`tt -hh` 含隐藏命令；每个命令 `--help` 含示例与契约
+- **命令帮助** — `tt --help` 只列公开命令且不提示隐藏入口；显式 `tt -hh` 查看完整列表
 - **Disposable / 事件** — 命令与服务继承 `Disposable`，提供 `onBeforeExecute` / `onAfterExecute`
 - **TypeScript strict + node:test** — 全量 strict，测试与源文件同目录
 
@@ -370,11 +370,8 @@ tt sc w2
 `wait` 等待已有任务，`--output` 隐含 `--wait`。生成是否成功以 `data.state` 为准，
 不能只看查询命令的 `code=0`；超时返回 `data.timedOut=true`，不会取消生成。
 
-`ai image` 根据 cross-app settings 的 `imagegen.source` 选择实现：未配置、为空或值为
-`xyq`（忽略大小写和首尾空格）时，通过 XYQ HTTP 提交；显式配置其他值时使用
-原来的本地 Codex 后台任务。两种实现都返回 `taskId`、当前 `state` 和
-`nextCommand`。图片 ID 分别为 `xyq-image:<threadId>` 和 `local-image:<uuid>`；
-后续 `status` / `wait` 根据 ID 前缀回到原 provider，不受配置后来切换影响。
+提交返回 `taskId`、当前 `state`、`outputs` 和适用时的 `nextCommand`。
+后续查询或等待直接复用返回的完整 `taskId`。
 
 ```bash
 # 默认仅提交；后台继续生成
@@ -385,51 +382,38 @@ tt ai image --images ./composition.png --images ./palette.png \
   --aspect-ratio 16:9 --model-id gpt_image_2 \
   '使用图1的构图和图2的配色'
 
-# 一次调用等待并保存；也可仅用 --wait 返回归档图片路径
+# 一次调用等待并保存；仅用 --wait 时返回产物链接或已有本地路径
 tt ai image --output ./result.png '画一片绿色树叶'
 
 # 查询、等待同一个任务，不会重新生成
-tt ai image status --task-id 'local-image:<uuid>'
-tt ai image wait --task-id 'local-image:<uuid>' --timeout-seconds 600 --output ./result.png
+tt ai image status --task-id '<task-id>'
+tt ai image wait --task-id '<task-id>' --timeout-seconds 600 --output ./result.png
 
 # 没收到提交输出或丢失 ID 时，查看本机持久记录
 tt ai image list
 ```
 
-等待默认 360 秒，上限 600 秒。本地实现完成时会返回 `outputs[].localPath`；
-XYQ 优先使用 artifact 的 `image.url` 无水印原图，缺失时才回退到 `scene_urls`。
-`status` / `--wait` 会在 `outputs[]` 返回
-`downloadUrl`、`assetId`、`pippitAssetId` 和尺寸等槽位元数据。
-使用 `--output` 会把 XYQ 产物下载到本地，并用 `localPath` 取代 `downloadUrl`；再次
-`wait --output` 只下载或复制已有产物。
-
-参考图的跨 provider 稳定契约是可重复的 `--images <path>`：本地实现把有序绝对路径
-写入生成上下文，XYQ 实现先上传图片，再把对应 `pippitAssetId` 按顺序放进
-`pippit_asset_ids` 槽位。因此切换 source 时调用命令和“图1/图2”提示词都不用变化。
-旧的“直接把绝对路径写进提示词”仍只作为本地实现的兼容用法。
-两种实现都提供 2K 图片，无需在 prompt 中声明分辨率。XYQ 推理强度默认
-`medium`，通常无需设置 `--effort`。支持的比例为 `21:9`、`16:9`、`3:2`、
-`4:3`、`1:1`、`3:4`、`2:3`、`9:16` 和 `auto`。XYQ 未设置时默认 `16:9`；
-非 XYQ 未设置时不追加比例。修图时使用
-`--aspect-ratio auto`，无需在 prompt 重复比例；需要枚举外的特殊比例时使用
-`auto`，并在 prompt 中描述目标比例。非 XYQ 实现会把显式设置的具体比例加入生成
-上下文，`auto` 不追加。
-`--quiet` 关闭提交进度；stdout 始终只有一个最终 JSON envelope。
+等待时间为 1–600 的整数秒，默认 360 秒。`outputs[]` 中每项含 `downloadUrl` 或
+绝对 `localPath`，两者互斥；无可用产物时为 `[]`。使用 `--output` 后返回本地路径，
+再次 `wait --output` 只保存已有产物。参考图使用可重复的 `--images <path>` 传入，
+提示词按顺序以“图1、图2”引用。
+
+支持模型参数的生成方式默认使用 `gpt_image_2_5_sunburst`；其他生成方式忽略
+`--model-id` 和 `--effort`。已知模型的 effort 范围如下：
 
-本地任务记录默认位于 `~/.tt/ai/image-tasks`，可用 `TT_AI_IMAGE_TASKS_DIR` 指定持久目录。
-每个任务独立保存请求、内部 Codex 会话 ID 和产物；`list` 返回任务状态，
-不会暴露提示词和会话内容。图片经完整 PNG 校验后原子归档，查询仅认已归档产物。
-这些记录不会随 `ai video cache clear` 清理。`ai image list` 只枚举本地记录；XYQ
-任务可用提交时返回的 taskId 跨进程查询。
+| `--model-id` | `--effort` 可选值 | 默认 effort |
+| --- | --- | --- |
+| `gpt_image_2`（image2） | `medium`、`high` | `high` |
+| `gpt_image_2_5_sunburst`（image2.5 Sunburst，默认模型） | `high`、`xhigh`、`max` | `max` |
 
-后台任务可以在提交命令退出后继续执行；机器重启或 worker 失联后，若无完整归档
-图片，会报告 `state=unknown`，不会隐式 `codex exec resume` 或重新生成。
-仅存在临时文件不代表完成。新命令不是跨机器任务服务，也不保证生图工具中断后
-能接回同一次远端生成。Codex 会话会保留，便于后续诊断。
+其他图片模型 ID 允许透传，其 effort 不校验，省略时沿用 `medium`。
+支持的比例为 `21:9`、`16:9`、`3:2`、`4:3`、`1:1`、`3:4`、`2:3`、`9:16` 和 `auto`。
+省略时由生成方式决定默认比例；需要固定比例时显式传入，自动选择比例用 `auto`。
+`--quiet` 关闭提交进度；stdout 始终只有一个最终 JSON envelope。
 
-迁移旧调用：`tt ai image '...'` 若需要直接拿文件，改为
-`tt ai image --output ./result.png '...'`，读取 `data.outputs[0].localPath`，不再读取旧 `imagePath`。
-外部 `generate` 技能中依赖同步行为的命令也需在升级 tt 时加 `--wait`。
+`ai image list` 只返回本机保存的图片任务记录，不包含全部远端任务，调用方应保存
+提交返回的 ID。任务可在提交命令退出后继续；重启或中断后的 `unknown` 表示无法确认
+结果，应先查询原任务和产物。`status` / `wait` 不会重新生成。
 
 ## AI 音频生成
 
@@ -467,10 +451,15 @@ tt ai audio wait --task-id 'xyq:<threadId>' --timeout-seconds 600 --output ./res
 
 ## AI 视频生成
 
-`ai video` 同步完成会话初始化、素材上传与远端任务创建后返回 `taskId`，生成本身
-异步进行（通常约 5 分钟）。提交期间 stderr 每 10 秒输出一次 `progress` 事件。
-视频 `taskId` 直接等于后端 `thread_id`，不再带 `xyq:` 前缀；`status/wait` 仍接受旧的
-`xyq:<threadId>`，返回结果使用不带前缀的 ID。
+`ai video` 完成素材上传与任务提交后返回 `taskId`，生成异步进行（通常约 5 分钟）。
+查询和等待复用返回的完整任务 ID。
+
+`--model-id` 仅接受 `seedance2.0`、`seedance2.0_fast`、`seedance2.5`、`wan3.0`、
+`minimax-h3`，默认 `seedance2.5`；未知值在提交前报输入错误。
+`--duration-seconds` 必填，为 4–30 的整数；`--output-count` 接受正整数，当前实际生成
+1 个。`--resolution` 接受 `480p`、`720p`、`1080p`、`2k`、`4k`，默认 `720p`；
+除 `minimax-h3` 外，`2k/4k` 会调整为 `1080p`。`minimax-h3` 的输出分辨率不由此参数
+控制，实际尺寸以产物为准。参数调整在 `appliedParameters` 和 `adjustments` 中返回。
 
 ```bash
 # 提交并立即返回 taskId 与 nextCommand
@@ -480,18 +469,16 @@ tt ai video --duration-seconds 8 --images ./ref.png '图1 中的角色转身微
 tt ai video --duration-seconds 8 --output ./result.mp4 '海边日出，慢镜头'
 
 # 用 taskId 查询/等待既有任务
-tt ai video status --task-id '<threadId>'
-tt ai video wait --task-id '<threadId>' --timeout-seconds 600 --output ./result.mp4
+tt ai video status --task-id '<task-id>'
+tt ai video wait --task-id '<task-id>' --timeout-seconds 600 --output ./result.mp4
 ```
 
 等待超时不是失败：`wait` 返回 `timedOut: true` 与当前 `state`，可用同一 `taskId`
 继续等待；`ai video --wait` 和 `--output` 同样在 `data` 中返回当前状态与 `timedOut`。
 查询或下载异常时，`error` 中保留 `taskId`、`recoverable` 和恢复命令。
 
-保存 `taskId` 后可在新的 CLI 进程中再次查询，包括隔天查询；客户端没有任务 ID 过期时间，
-也不依赖原提交进程或本地任务记录。查询仍需要有效登录态和该任务的访问权限，服务端任务
-保留期限及产物链接有效期由后端决定。此 ID 定位的是 thread；当前查询未指定 runId，
-会取后端返回列表的最后一个 run。tt 每次提交都会新建 thread，因此普通提交对应独立任务。
+保存 `taskId` 后可跨进程查询；仍需有效登录态及任务访问权限，任务和产物链接的
+保留期限由服务端决定。
 
 ## 联网搜索