v0.1 AgentRun CLI 规格

AgentRun CLI 是 v0.1 的受控人工操作和验收入口。它必须遵循 UniDesk cli-spec 原则：默认 JSON 输出、禁止空输出伪成功、禁止长阻塞、日志可见、配置显式校验，并优先通过 agentrun-mgr RESTful API 完成跨服务操作。

在系统中的职责划分

创建 run、查询 run、提交 command、查询 command、分页读取 events。
创建和查询 Queue task，查看 Queue stats/read/commander，并从 Queue task 获取 Session 引用。
查询 Session 输出、trace 和会话控制；Queue 命令不得代理输出或 trace。
手动启动 runner，本地 process 或 Kubernetes Job 均必须快速返回 job/process identity 和 logPath。
查询 backend capability 和 manager health。
为综合联调提供 CLI 交互面；不得替代 RESTful API 合同测试。
不直连 Postgres，不读取 provider Secret 值，不把 debug/mock 路径伪装成正式验收。

CLI 入口

v0.1 固定规划入口：

scripts/agentrun-cli.ts
scripts/src/*.ts

CLI 官方 TypeScript 入口固定为 scripts/agentrun-cli.ts。在 G14 非交互 SSH route、CI task 和人工验收命令中，推荐使用仓库内 launcher：

./scripts/agentrun ...

该 launcher 只负责定位 bun（优先 BUN_BIN、其次 PATH、$HOME/.bun/bin/bun 和 G14 默认 /root/.bun/bin/bun），然后转入同一个 scripts/agentrun-cli.ts。它不实现第二套路由、不读取额外配置、不绕过 TypeScript CLI。bun scripts/agentrun-cli.ts ... 仍可在 PATH 已包含 Bun 的交互 shell 中使用；node、tsx 或其他 wrapper 只能作为本地开发辅助，不能成为 v0.1 综合联调的权威入口。

入口文件只负责参数解析和路由，具体实现拆到 scripts/src/。CLI 命令默认输出 JSON；任何命令无 stdout 都是失败。单次 CLI 调用必须在 60 秒内返回，长时间模型 turn 通过 status/events 后续命令观察。

初始命令族

./scripts/agentrun runs create --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 --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>]
./scripts/agentrun runner start --run-id <runId> --backend <backendProfile>
./scripts/agentrun runner job --run-id <runId> --command-id <commandId> [--idempotency-key <key>]
./scripts/agentrun runner job --dry-run --run-id <runId> --command-id <commandId> --image <image>
./scripts/agentrun runner jobs --run-id <runId> [--command-id <commandId>]
./scripts/agentrun runner job-status [runnerJobId] --run-id <runId>
./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek] [--codex-home <dir>]
./scripts/agentrun backends list
./scripts/agentrun server start|status
./scripts/agentrun queue submit --json-file <task.json>
./scripts/agentrun queue list [--queue <queue>] [--state <state>] [--cursor <cursor>] [--limit <limit>]
./scripts/agentrun queue show <taskId>
./scripts/agentrun queue stats [--queue <queue>]
./scripts/agentrun queue commander [--queue <queue>]
./scripts/agentrun queue read <taskId>
./scripts/agentrun queue cancel <taskId> [--reason <text>]
./scripts/agentrun sessions show <sessionId|sessionPath>
./scripts/agentrun sessions output <sessionId|sessionPath> [--cursor <cursor>] [--limit <limit>]
./scripts/agentrun sessions trace <sessionId|sessionPath> [--cursor <cursor>] [--limit <limit>]
./scripts/agentrun sessions control <sessionId|sessionPath> --json-file <control.json>

具体参数可以在实现时按代码结构微调，但行为必须保持：

创建类命令返回 runId、commandId、status 和下一步 poll command。
runner start 返回 attemptId、job/process identity、logPath 和后续 status/events 命令。
runner jobs / runner job-status 返回 manager 持久化的 runner Job 最小状态摘要，包括 attemptId、runnerId、namespace、jobName、phase、terminalStatus、logPath、retention 和 redacted Kubernetes identity；业务方不需要直连 Kubernetes 才能定位当前 attempt。
查询类命令返回当前 state、terminal_status、failureKind、event cursor 或 logPath。
events 默认分页且有界，必须支持 afterSeq 和 limit。
server logs 返回有界日志摘要，并指向完整日志文件或 Kubernetes pod identity。
secrets codex render --dry-run 返回 Codex stdio profile Secret 创建计划、输入文件 bytes/hash、SecretRef、manifest 摘要和 apply 命令形状；--profile codex 默认 Secret name 为 agentrun-v01-provider-codex，--profile deepseek 默认 Secret name 为 agentrun-v01-provider-deepseek；它不得输出 Secret value 或执行 Kubernetes 写操作。
backends list 必须显示 codex 与 deepseek profile 的 backendKind、protocol、transport、command、requiredSecretKeys 和状态；不得因为 deepseek 尚未配置 Secret 就隐藏 capability。
queue show 必须返回 task/attempt summary、state、read cursor、stats 相关字段和 sessionPath；不得返回或代理完整 output/trace。
sessions output 与 sessions trace 是输出和 trace 的唯一 CLI 查询入口；不得新增 queue output 或 queue trace 兼容命令。

配置与 Secret 边界

CLI 配置必须显式校验；部署关键值不得静默 fallback。
CLI 调用 manager REST API；不得直接连 Postgres 或读 Kubernetes Secret value。
CLI 可以显示 SecretRef 名称、key、credential source 和 readiness，但不得显示 Secret value、Codex auth.json、Codex config.toml、DSN password、token 或 URL credential。
Debug 子命令可以用于开发，但综合联调和测试规格不得用 debug 子命令作为通过证据。

测试规格

T1 CLI run 生命周期

阅读 AGENTS.md、本文和 spec-v01-validation.md，然后用 ./scripts/agentrun 创建 run、提交 turn command、启动 runner、轮询 command 和 events 直到 terminal_status。确认每个命令输出非空 JSON，60 秒内返回，并给出下一步可执行命令或 logPath。若直接执行 bun scripts/agentrun-cli.ts，必须先证明当前 shell 的 PATH 能找到 Bun；G14 route 默认以 ./scripts/agentrun 为准。

T2 CLI 错误可见性

阅读本文，然后用非法 backendProfile、缺失 SecretRef 和无效 runId 分别调用正式 CLI。确认每次失败都有 JSON 输出、failureKind、message、trace correlation 和 logPath 或诊断入口；不得空输出或只输出布尔值。

T3 CLI 日志可见性

阅读本文，然后启动一个会失败的 runner，并通过 CLI 返回的 logPath 或 pod identity 读取实际日志。确认日志包含足够定位失败原因的信息、异常 trace 或错误分类，同时没有 Secret value。

T4 CLI 与 RESTful 一致性

阅读本文和 spec-v01-agentrun-mgr.md，然后对同一个 run 分别使用 CLI 和 RESTful API 查询 run、command、events 和 terminal_status。确认 CLI 不维护独立状态，两种交互面观察结果一致。

T5 Backend profile CLI 切换

阅读本文、spec-v01-backend-codex.md 和 spec-v01-validation.md，然后用正式 CLI 分别创建 backendProfile=codex 与 backendProfile=deepseek 的 run，按 codex -> deepseek -> codex 顺序执行真实 runner。确认 CLI 输出非空 JSON，backend_status 显示正确 profile/backendKind/protocol，缺失 deepseek SecretRef 时返回 secret-unavailable，不会 fallback 到 codex。

T6 Queue 与 Session CLI 分层

阅读本文和 spec-v01-queue.md，然后用正式 CLI 创建一个 Queue task，轮询 queue list/show/stats/commander/read，再使用 queue show 返回的 sessionPath 调用 sessions output/trace。确认 Queue 命令只返回 summary/stats/read/sessionPath，不代理 output/trace；Session 命令能查询输出和 trace。最终交互验收必须使用真实 runtime，不使用 mock，不写自动交互脚本。

规格的实现情况

规格项	状态	说明
AgentRun CLI 规格	已定义	本文为 v0.1 CLI 权威。
`scripts/agentrun-cli.ts`	已实现	已提供 run/command/event/backend/server 基础命令和 JSON envelope；`scripts/agentrun` 是同一入口的 Bun 定位 launcher。
CLI 调 manager REST	已实现	CLI 通过 `ManagerClient` 调 manager REST；自测试可用内存 manager，综合联调必须指向真实 `agentrun-v01` manager。
runner start/job	已实现	`runner start` 可执行 host process runner；`runner job --dry-run` 可渲染 Kubernetes Job JSON；`runner job` 正式路径通过 manager REST 创建 Kubernetes Job，支持 `--idempotency-key` 并快速返回 job identity、SecretRef、retention 和轮询命令。
runner jobs/job-status	已实现	CLI 通过 manager REST 查询 runner Job 持久记录和最小状态摘要，不直连 Kubernetes、不读取 Secret 值。
result/cancel CLI	已实现	`runs result`、`commands result`、`runs cancel` 和 `commands cancel` 均调用 manager REST，不维护独立状态。
Queue CLI	已实现/Q1	已提供 `queue submit/list/show/stats/commander/read/cancel`，通过 manager REST 访问 Queue task 和 stats，不直连 Postgres。
Session CLI	待实现	规格见 spec-v01-queue.md；输出和 trace 进入 Session 命令，Queue 命令不得代理 output/trace。
CLI 测试规格	已定义/已验证主闭环	综合联调见 spec-v01-validation.md；每次发布仍按手动交互验收复跑。
`deepseek` profile CLI	已实现/已通过主闭环	`secrets codex render --profile deepseek`、`backends list`、`runner start --backend`、`runner job` 和 JSON 错误可见性已实现；真实 CLI/RESTful 联调已通过 `codex -> deepseek -> codex` 切换主闭环。

10 KiB Raw Blame History Unescape Escape