docs: Queue 输入优先使用 stdin heredoc

2026-06-10 13:07:10 +08:00
parent 85c5e319f4
commit 45df61bd02
3 changed files with 38 additions and 14 deletions
@@ -34,12 +34,12 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 ## 初始命令族

 ```bash
-./scripts/agentrun runs create --json-file <run.json>|--json-stdin
+./scripts/agentrun runs create --json-stdin|--json-file <run.json>
 ./scripts/agentrun runs show <runId>
 ./scripts/agentrun runs events <runId> --after-seq <n> --limit <n> [--summary|--tail-summary] [--tail <n>] [--summary-chars <n>] [--format json|tsv]
 ./scripts/agentrun runs result <runId> [--command-id <commandId>]
 ./scripts/agentrun runs cancel <runId> [--reason <text>]
-./scripts/agentrun commands create <runId> --type turn|steer|interrupt --json-file <payload.json>|--json-stdin
+./scripts/agentrun commands create <runId> --type turn|steer|interrupt --json-stdin|--json-file <payload.json>
 ./scripts/agentrun commands show <commandId> --run-id <runId>
 ./scripts/agentrun commands result <commandId> --run-id <runId>
 ./scripts/agentrun commands cancel <commandId> [--reason <text>]
@@ -59,19 +59,19 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 ./scripts/agentrun server status [--port <port>]
 ./scripts/agentrun server logs [--port <port>] [--tail-bytes <bytes>] [--log-file <path>]
 ./scripts/agentrun server stop [--port <port>]
-./scripts/agentrun queue submit --json-file <task.json>|--json-stdin [--dry-run]
+./scripts/agentrun queue submit --json-stdin|--json-file <task.json> [--dry-run]
 ./scripts/agentrun queue list [--queue <queue>] [--state <state>] [--cursor <cursor>] [--limit <limit>] [--full|--raw]
 ./scripts/agentrun queue show <taskId> [--full|--raw]
 ./scripts/agentrun queue stats [--queue <queue>]
 ./scripts/agentrun queue commander [--queue <queue>] [--reader-id <reader>] [--limit <display-limit>] [--full|--raw]
 ./scripts/agentrun queue read <taskId> [--reader-id <reader>] [--dry-run] [--full|--raw]
 ./scripts/agentrun queue cancel <taskId> [--reason <text>] [--dry-run] [--full|--raw]
-./scripts/agentrun queue dispatch <taskId> [--json-file <dispatch.json>|--json-stdin] [--dry-run] [--full|--raw]
+./scripts/agentrun queue dispatch <taskId> [--json-stdin|--json-file <dispatch.json>] [--dry-run] [--full|--raw]
 ./scripts/agentrun queue refresh <taskId> [--dry-run] [--full|--raw]
 ./scripts/agentrun sessions ps [--state default|running|unread|terminal|idle|all] [--profile codex|deepseek|minimax-m3|dsflash-go|M3] [--reader-id <reader>]
 ./scripts/agentrun sessions show <sessionId> [--reader-id <reader>]
-./scripts/agentrun sessions turn [sessionId] [--json-file <run-base.json>|--json-stdin] [--prompt-file <file>|--prompt-stdin|--prompt <text>] [--profile codex|deepseek|minimax-m3|dsflash-go|M3] [--runner-json-file <job.json>|--runner-json-stdin] [--no-runner-job]
-./scripts/agentrun sessions steer <sessionId> [--prompt-file <file>|--prompt-stdin|--prompt <text>]
+./scripts/agentrun sessions turn [sessionId] [--json-stdin|--json-file <run-base.json>] [--prompt-stdin|--prompt-file <file>|--prompt <text>] [--profile codex|deepseek|minimax-m3|dsflash-go|M3] [--runner-json-stdin|--runner-json-file <job.json>] [--no-runner-job]
+./scripts/agentrun sessions steer <sessionId> [--prompt-stdin|--prompt-file <file>|--prompt <text>]
 ./scripts/agentrun sessions cancel <sessionId> [--reason <text>]
 ./scripts/agentrun sessions trace <sessionId> [--after-seq <n>] [--limit <limit>] [--run-id <runId>] [--include-output] [--seq <n>|--event-id <id>|--item-id <id>] [--detail-scan-pages <n>] [--full|--raw]
 ./scripts/agentrun sessions output <sessionId> [--after-seq <n>] [--limit <limit>] [--run-id <runId>] [--include-output] [--seq <n>|--event-id <id>|--item-id <id>] [--detail-scan-pages <n>] [--full|--raw]
@@ -100,7 +100,7 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 - `queue refresh` 只根据 Queue task 中保存的 Core run/command 引用回写 Queue attempt 状态，不读取 Core trace 反推 commander 或统计；带 `--dry-run` 时不得写回状态。
 - `queue list/show/commander` 默认返回低噪声 summary，只显示 task/attempt/session ids、state、read cursor、stats 相关字段、compact supervisor 和 drill-down 命令；commander 的 supervisor 只能放 `phase`、last activity source seq/id、timeout budget 和恢复动作摘要，不得展开完整 payload、trace、tool command、stdout/stderr 或 runnerTrace。需要完整 task payload、resource bundle 或 metadata 时显式使用 `--full|--raw`；需要 trace/output 细节时继续按返回的 `sessionId`/`sourceSeq` 走 `sessions trace|output --seq/--event-id/--item-id --full`。
 - `queue show` 不得返回或代理完整 output/trace；输出和 trace 只能通过返回的 `sessionPath` 对应 `sessions ...` 命令查询。
- 需要提交较长 Queue task、dispatch body、run base 或 command payload 时，CLI 必须支持 `--json-stdin`，避免为了 heredoc/stdin 内容先写临时 dump 文件再传 `--json-file`；`sessions turn` 的 runner job override 也必须支持 `--runner-json-stdin`。所有 stdin JSON 仍必须解析为 object，并在 dry-run 中只展示有界 body 摘要、bytes 和 keys。
+- 需要提交较长 Queue task、dispatch body、run base 或 command payload 时，CLI 必须把 `--json-stdin` 作为首选入口，避免为了 heredoc/stdin 内容先写临时 dump 文件再传 `--json-file`；`--json-file` 只用于可复用、已受控的输入文件。`queue submit/dispatch --dry-run` 的 `next.confirm` 不得默认推荐 `--json-file`，有 JSON body 时应提示 `--json-stdin`；只有用户显式维护可复用文件时才使用 file fallback。`sessions turn` 的 runner job override 也必须支持 `--runner-json-stdin`。所有 stdin JSON 仍必须解析为 object，并在 dry-run 中只展示有界 body 摘要、bytes 和 keys。
 - `sessions ps` 默认只显示 running 和 unread session；`--state all` 才显示历史 read session，避免旧 session 噪声淹没当前进度。
 - `sessions turn` 是异步 subagent 的受控 CLI 入口：短返回 run、command、runnerJob 和后续 poll/read/steer/cancel 命令，不等待模型完成。`--profile M3` 是 `minimax-m3` 的 CLI alias；profile 仍写入 canonical `backendProfile`，不得 fallback。
 - `sessions steer` 对当前 active run 创建 `type=steer` command；`sessions cancel` 通过 Session control 取消 active command 或 run；`sessions read` 写入 reader cursor，使 terminal session 从默认 ps 中消失。