maoda-commander-tt 0.0.50 → 0.0.52

package/README.md

@@ -1,4 +1,4 @@
-# template-commander (`tt`)
+# tt-cli (`tt`)
 
 一个 AI-native 的通用 CLI：默认调用方是 AI agent。每个命令在 stdout 只输出一行
 JSON envelope，诊断与进度走 stderr，失败退出码为 1，`--help` 自带面向 agent 的调用契约。
@@ -42,7 +42,7 @@ exit=1
 ## 目录结构
 
 ```
-template-commander/
+tt-cli/
 ├── src/
 │   ├── main.ts                 # 可执行入口：注册 createRootCommands() 并运行 CliApp
 │   ├── index.ts                # 库入口：导出 core 与内置命令
@@ -96,7 +96,7 @@ pnpm build && pnpm test:dist
 
 发布采用 GitHub Actions + npm Trusted Publishing（OIDC）。本地 `pnpm pub` 负责
 检查、递增 patch 版本、提交版本和推送 `tt-v<版本>` 标签；GitHub Actions 在
-`template-commander/` 中重新安装依赖、测试、构建，再发布 `maoda-commander-tt`。
+`tt-cli/` 中重新安装依赖、测试、构建，再发布 `maoda-commander-tt`。
 
 ### 首次配置
 
@@ -142,7 +142,7 @@ npm provenance；这不影响 OIDC 发布。
 本地 `main` 可以有尚未推送的提交，但不能落后于远端或与远端分叉。
 
 ```bash
-cd ~/work/local-multi-repo/template-commander
+cd ~/work/local-multi-repo/tt-cli
 pnpm pub
 ```
 
@@ -319,14 +319,21 @@ tt sc w2
 `wait` 等待已有任务，`--output` 隐含 `--wait`。生成是否成功以 `data.state` 为准，
 不能只看查询命令的 `code=0`；超时返回 `data.timedOut=true`，不会取消生成。
 
-`ai image` 保存本机任务并启动独立后台进程，确认接管后返回
-`taskId`、当前 `state` 和 `nextCommand`。图片 ID 格式为 `local-image:<uuid>`；
-`submitted` 表示本地任务已受理，`working` 表示后台进程正在执行。
+`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，不受配置后来切换影响。
 
 ```bash
 # 默认仅提交；后台继续生成
 tt ai image '画一片绿色树叶'
 
+# 统一参考图入口；提示词按传入顺序使用图1、图2
+tt ai image --images ./composition.png --images ./palette.png \
+  --aspect-ratio 16:9 --model-id gpt_image_2 \
+  '使用图1的构图和图2的配色'
+
 # 一次调用等待并保存；也可仅用 --wait 返回归档图片路径
 tt ai image --output ./result.png '画一片绿色树叶'
 
@@ -338,14 +345,30 @@ tt ai image wait --task-id 'local-image:<uuid>' --timeout-seconds 600 --output .
 tt ai image list
 ```
 
-等待默认 360 秒，上限 600 秒。完成时 `outputs[].localPath` 为绝对路径；再次
-`wait --output` 只复制已有产物。参考图继续通过提示词中的绝对路径提供。
+等待默认 360 秒，上限 600 秒。本地实现完成时会返回 `outputs[].localPath`；
+XYQ 的 `status` / `--wait` 会在 `outputs[]` 返回
+`remoteUrl`、`assetId`、`pippitAssetId` 和尺寸等槽位元数据。再次
+使用 `--output` 才会把 XYQ 产物下载到本地并补充 `localPath`；再次
+`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。
 
-任务记录默认位于 `~/.tt/ai/image-tasks`，可用 `TT_AI_IMAGE_TASKS_DIR` 指定持久目录。
+本地任务记录默认位于 `~/.tt/ai/image-tasks`，可用 `TT_AI_IMAGE_TASKS_DIR` 指定持久目录。
 每个任务独立保存请求、内部 Codex 会话 ID 和产物；`list` 返回任务状态，
 不会暴露提示词和会话内容。图片经完整 PNG 校验后原子归档，查询仅认已归档产物。
-这些记录不会随 `ai video cache clear` 清理。
+这些记录不会随 `ai video cache clear` 清理。`ai image list` 只枚举本地记录；XYQ
+任务可用提交时返回的 taskId 跨进程查询。
 
 后台任务可以在提交命令退出后继续执行；机器重启或 worker 失联后，若无完整归档
 图片，会报告 `state=unknown`，不会隐式 `codex exec resume` 或重新生成。
@@ -353,7 +376,7 @@ tt ai image list
 能接回同一次远端生成。Codex 会话会保留，便于后续诊断。
 
 迁移旧调用：`tt ai image '...'` 若需要直接拿文件，改为
-`tt ai image --wait '...'`，读取 `data.outputs[0].localPath`，不再读取旧 `imagePath`。
+`tt ai image --output ./result.png '...'`，读取 `data.outputs[0].localPath`，不再读取旧 `imagePath`。
 外部 `generate` 技能中依赖同步行为的命令也需在升级 tt 时加 `--wait`。
 
 ## AI 音频生成