mirrors/pikasTech-agentrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Queue 输入优先使用 stdin heredoc

Browse Source
This commit is contained in:
Codex
2026-06-10 13:07:10 +08:00
parent 85c5e319f4
commit 45df61bd02
3 changed files with 38 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/cli.md
+4 -2
View File
@@ -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 <run.json>
./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>
./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>
./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>]
docs/reference/spec-v01-cli.md
+7 -7
View File
@@ -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 中消失。
docs/reference/spec-v01-queue.md
+27 -5
View File
@@ -77,14 +77,14 @@ Queue task 详情必须返回 session 引用，而不是代理输出或 trace：
AgentRun CLI 必须提供 Queue 和 Session 两组命令。Queue 命令只操作队列资源：
```bash
./scripts/agentrun queue submit --json-file <task.json> [--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>] [--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]
```
@@ -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 <reader>]
./scripts/agentrun sessions show <sessionId> [--reader-id <reader>]
./scripts/agentrun sessions turn [sessionId] --json-file <run-base.json> --prompt-file <file> [--profile codex|deepseek|minimax-m3|M3]
./scripts/agentrun sessions steer <sessionId> --prompt-file <file>
./scripts/agentrun sessions turn [sessionId] [--json-stdin|--json-file <run-base.json>] [--prompt-stdin|--prompt-file <file>|--prompt <text>] [--profile codex|deepseek|minimax-m3|M3]
./scripts/agentrun sessions steer <sessionId> [--prompt-stdin|--prompt-file <file>|--prompt <text>]
./scripts/agentrun sessions cancel <sessionId> [--reason <text>]
./scripts/agentrun sessions output <sessionId> [--after-seq <seq>] [--limit <limit>]
./scripts/agentrun sessions trace <sessionId> [--after-seq <seq>] [--limit <limit>]
./scripts/agentrun sessions read <sessionId> [--reader-id <reader>]
```
不得新增 `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 <taskId> --json-stdin --dry-run <<'JSON'
{ "attemptId": "attempt_manual" }
JSON
```
Queue task 的 `resourceBundleRef` 在 dispatch 时原样进入 Core run。若其中声明 `requiredSkills`，Queue 只展示声明和终态摘要，不能自行判定可用；runner 必须在 gitbundle materialization 后、backend 启动前校验 `.agents/skills/<name>/SKILL.md`，缺失时以 `required-skill-unavailable` 写入 command/run result 和 events。