diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7c5c3f2..a38e00a 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -15,6 +15,8 @@ scripts/src/*.ts CLI 默认输出 JSON。空 stdout 是失败，不是成功。每个命令都必须返回足够继续排障的结构化信息，包括 id、status、log path 或后续命令。 +一次性 JSON body 优先通过 `--json-stdin` 和 quoted heredoc 输入；不要为了把 heredoc/stdin 内容传给 CLI 而先落临时 JSON dump 文件。`--json-file` 只用于可复用、已受控的输入文件。 + 长操作必须是 fire-and-forget 或短异步资源操作。CLI 调用应在 60 秒内返回。创建 run 或启动 runner 的命令返回创建出的资源和轮询命令，不等待模型 turn 完成。 ## 常用命令 @@ -22,12 +24,12 @@ CLI 默认输出 JSON。空 stdout 是失败，不是成功。每个命令都必 `v0.1` 常用命令族： ```bash -./scripts/agentrun runs create --json-file +./scripts/agentrun runs create --json-stdin|--json-file ./scripts/agentrun runs show ./scripts/agentrun runs events --after-seq --limit ./scripts/agentrun runs result [--command-id ] ./scripts/agentrun runs cancel [--reason ] -./scripts/agentrun commands create --type turn|steer|interrupt --json-file +./scripts/agentrun commands create --type turn|steer|interrupt --json-stdin|--json-file ./scripts/agentrun commands show --run-id ./scripts/agentrun commands result --run-id ./scripts/agentrun commands cancel [--reason ] diff --git a/docs/reference/spec-v01-cli.md b/docs/reference/spec-v01-cli.md index 7d41616..10b014f 100644 --- a/docs/reference/spec-v01-cli.md +++ b/docs/reference/spec-v01-cli.md @@ -34,12 +34,12 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交 ## 初始命令族 ```bash -./scripts/agentrun runs create --json-file |--json-stdin +./scripts/agentrun runs create --json-stdin|--json-file ./scripts/agentrun runs show ./scripts/agentrun runs events --after-seq --limit [--summary|--tail-summary] [--tail ] [--summary-chars ] [--format json|tsv] ./scripts/agentrun runs result [--command-id ] ./scripts/agentrun runs cancel [--reason ] -./scripts/agentrun commands create --type turn|steer|interrupt --json-file |--json-stdin +./scripts/agentrun commands create --type turn|steer|interrupt --json-stdin|--json-file ./scripts/agentrun commands show --run-id ./scripts/agentrun commands result --run-id ./scripts/agentrun commands cancel [--reason ] @@ -59,19 +59,19 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交 ./scripts/agentrun server status [--port ] ./scripts/agentrun server logs [--port ] [--tail-bytes ] [--log-file ] ./scripts/agentrun server stop [--port ] -./scripts/agentrun queue submit --json-file |--json-stdin [--dry-run] +./scripts/agentrun queue submit --json-stdin|--json-file [--dry-run] ./scripts/agentrun queue list [--queue ] [--state ] [--cursor ] [--limit ] [--full|--raw] ./scripts/agentrun queue show [--full|--raw] ./scripts/agentrun queue stats [--queue ] ./scripts/agentrun queue commander [--queue ] [--reader-id ] [--limit ] [--full|--raw] ./scripts/agentrun queue read [--reader-id ] [--dry-run] [--full|--raw] ./scripts/agentrun queue cancel [--reason ] [--dry-run] [--full|--raw] -./scripts/agentrun queue dispatch [--json-file |--json-stdin] [--dry-run] [--full|--raw] +./scripts/agentrun queue dispatch [--json-stdin|--json-file ] [--dry-run] [--full|--raw] ./scripts/agentrun queue refresh [--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 ] ./scripts/agentrun sessions show [--reader-id ] -./scripts/agentrun sessions turn [sessionId] [--json-file |--json-stdin] [--prompt-file |--prompt-stdin|--prompt ] [--profile codex|deepseek|minimax-m3|dsflash-go|M3] [--runner-json-file |--runner-json-stdin] [--no-runner-job] -./scripts/agentrun sessions steer [--prompt-file |--prompt-stdin|--prompt ] +./scripts/agentrun sessions turn [sessionId] [--json-stdin|--json-file ] [--prompt-stdin|--prompt-file |--prompt ] [--profile codex|deepseek|minimax-m3|dsflash-go|M3] [--runner-json-stdin|--runner-json-file ] [--no-runner-job] +./scripts/agentrun sessions steer [--prompt-stdin|--prompt-file |--prompt ] ./scripts/agentrun sessions cancel [--reason ] ./scripts/agentrun sessions trace [--after-seq ] [--limit ] [--run-id ] [--include-output] [--seq |--event-id |--item-id ] [--detail-scan-pages ] [--full|--raw] ./scripts/agentrun sessions output [--after-seq ] [--limit ] [--run-id ] [--include-output] [--seq |--event-id |--item-id ] [--detail-scan-pages ] [--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 中消失。 diff --git a/docs/reference/spec-v01-queue.md b/docs/reference/spec-v01-queue.md index 73a6f29..921f50e 100644 --- a/docs/reference/spec-v01-queue.md +++ b/docs/reference/spec-v01-queue.md @@ -77,14 +77,14 @@ Queue task 详情必须返回 session 引用，而不是代理输出或 trace： AgentRun CLI 必须提供 Queue 和 Session 两组命令。Queue 命令只操作队列资源： ```bash -./scripts/agentrun queue submit --json-file [--dry-run] +./scripts/agentrun queue submit --json-stdin|--json-file [--dry-run] ./scripts/agentrun queue list [--queue ] [--state ] [--cursor ] [--limit ] [--full|--raw] ./scripts/agentrun queue show [--full|--raw] ./scripts/agentrun queue stats [--queue ] ./scripts/agentrun queue commander [--queue ] [--reader-id ] [--limit ] [--full|--raw] ./scripts/agentrun queue read [--reader-id ] [--dry-run] [--full|--raw] ./scripts/agentrun queue cancel [--reason ] [--dry-run] [--full|--raw] -./scripts/agentrun queue dispatch [--json-file ] [--dry-run] [--full|--raw] +./scripts/agentrun queue dispatch [--json-stdin|--json-file ] [--dry-run] [--full|--raw] ./scripts/agentrun queue refresh [--dry-run] [--full|--raw] ``` @@ -93,15 +93,37 @@ Session 命令负责输出、trace 和会话控制： ```bash ./scripts/agentrun sessions ps [--state default|running|unread|terminal|idle|all] [--profile codex|deepseek|minimax-m3|M3] [--reader-id ] ./scripts/agentrun sessions show [--reader-id ] -./scripts/agentrun sessions turn [sessionId] --json-file --prompt-file [--profile codex|deepseek|minimax-m3|M3] -./scripts/agentrun sessions steer --prompt-file +./scripts/agentrun sessions turn [sessionId] [--json-stdin|--json-file ] [--prompt-stdin|--prompt-file |--prompt ] [--profile codex|deepseek|minimax-m3|M3] +./scripts/agentrun sessions steer [--prompt-stdin|--prompt-file |--prompt ] ./scripts/agentrun sessions cancel [--reason ] ./scripts/agentrun sessions output [--after-seq ] [--limit ] ./scripts/agentrun sessions trace [--after-seq ] [--limit ] ./scripts/agentrun sessions read [--reader-id ] ``` -不得新增 `queue output`、`queue trace` 或 `queue session/*` 这类子路径代理。`queue list/show/commander` 默认输出低噪声 summary，最多打印 task/attempt/session ids、状态、统计、`sessionPath`、compact supervisor 和下一步 `sessions ...` 命令；supervisor 只允许披露 phase、last activity source seq/id、timeout budget 和恢复动作摘要，不得展开完整 payload、trace、tool command、stdout/stderr 或 runnerTrace。完整 payload/resource bundle/metadata 只能通过显式 `--full|--raw` 展开；trace/output 细节继续按 `sessionId` + `sourceSeq/eventId/itemId` 走 Session CLI 渐进披露。Queue mutation 命令带 `--dry-run` 时必须只返回 `mutation=false` 的计划，不得写 Queue、Core run/command 或 runner job。 +不得新增 `queue output`、`queue trace` 或 `queue session/*` 这类子路径代理。`queue list/show/commander` 默认输出低噪声 summary，最多打印 task/attempt/session ids、状态、统计、`sessionPath`、compact supervisor 和下一步 `sessions ...` 命令；supervisor 只允许披露 phase、last activity source seq/id、timeout budget 和恢复动作摘要，不得展开完整 payload、trace、tool command、stdout/stderr 或 runnerTrace。完整 payload/resource bundle/metadata 只能通过显式 `--full|--raw` 展开；trace/output 细节继续按 `sessionId` + `sourceSeq/eventId/itemId` 走 Session CLI 渐进披露。Queue mutation 命令带 `--dry-run` 时必须只返回 `mutation=false` 的计划，不得写 Queue、Core run/command 或 runner job。一次性 Queue task、dispatch body、run base 或 command payload 必须优先用 `--json-stdin` 接 quoted heredoc；禁止为了把 heredoc/stdin 内容交给 CLI 而先写临时 JSON dump 文件再传 `--json-file`。`--json-file` 只用于可复用、已受控的输入文件。 + +推荐 Queue task 提交形态： + +```bash +./scripts/agentrun queue submit --json-stdin <<'JSON' +{ + "tenantId": "unidesk", + "projectId": "pikasTech/agentrun", + "queue": "dev", + "title": "短标题", + "payload": { "prompt": "任务正文" } +} +JSON +``` + +推荐 dispatch dry-run/确认形态： + +```bash +./scripts/agentrun queue dispatch --json-stdin --dry-run <<'JSON' +{ "attemptId": "attempt_manual" } +JSON +``` Queue task 的 `resourceBundleRef` 在 dispatch 时原样进入 Core run。若其中声明 `requiredSkills`，Queue 只展示声明和终态摘要，不能自行判定可用；runner 必须在 gitbundle materialization 后、backend 启动前校验 `.agents/skills//SKILL.md`，缺失时以 `required-skill-unavailable` 写入 command/run result 和 events。