Codex
78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
# AgentRun CLI 与服务 API 参考
|
||
|
||
`v0.1` CLI 的权威规格是 [spec-v01-cli.md](spec-v01-cli.md)。本文保留为 CLI 与服务 API 的辅助参考；如果命令、测试规格或实现状态与 `spec-v01-cli.md` 冲突，以 `spec-v01-cli.md` 为准。
|
||
|
||
AgentRun CLI 与服务 API 遵循 UniDesk `cli-spec` 原则。本文只保留辅助索引，完整命令与测试规格见 [spec-v01-cli.md](spec-v01-cli.md)。
|
||
|
||
## CLI 形态
|
||
|
||
未来 CLI 入口应保持轻量，并把实现路由到模块：
|
||
|
||
```text
|
||
scripts/agentrun-cli.ts
|
||
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 完成。
|
||
|
||
## 常用命令
|
||
|
||
`v0.1` 常用命令族：
|
||
|
||
```bash
|
||
./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-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>]
|
||
./scripts/agentrun runner start --run-id <runId> --backend <backendProfile>
|
||
./scripts/agentrun runner job --run-id <runId> --command-id <commandId> [--idempotency-key <key>]
|
||
./scripts/agentrun backends list
|
||
./scripts/agentrun server start [--port <port>] [--host <host>] [--foreground]
|
||
./scripts/agentrun server status [--port <port>]
|
||
./scripts/agentrun server logs [--port <port>] [--tail-bytes <bytes>] [--log-file <path>]
|
||
./scripts/agentrun server stop [--port <port>]
|
||
```
|
||
|
||
行为必须保持以下规则：
|
||
|
||
- `runs create` 创建 durable facts 并立即返回。
|
||
- `commands create` 创建 durable command；`turn` 启动一轮对话，`steer` 只在同 run 有 active turn 时由 runner 转发到 Codex `turn/steer`，迟到 steer 返回结构化 blocked，不终结 run。
|
||
- `runner start` 启动本地进程或 Kubernetes Job，并返回 process/job identity、log path 和 poll commands。
|
||
- `events` 默认分页且有界。
|
||
- `server logs` 返回有界日志，并指向完整日志文件。
|
||
- `server start` 默认后台启动本地 manager，短返回 pid、pidFile、logPath 和后续 status/stop 命令；`--foreground` 仅用于容器入口或显式调试。
|
||
- `server status` 暴露 port、process id、health 和 log paths；health 不通时仍返回结构化 JSON。
|
||
- `server logs` 返回有界日志尾部和截断元数据，不能要求人工直接打开日志文件排障。
|
||
- `server stop` 通过 pidFile 和端口进程清理本地 manager，返回 before/after 状态。
|
||
|
||
## 配置与日志
|
||
|
||
AgentRun 配置必须显式且经过校验。部署关键值不得静默 fallback。引入本地开发服务后，应使用固定端口，并把实时日志写入：
|
||
|
||
```text
|
||
logs/{YYYYMMDD}/
|
||
```
|
||
|
||
Runtime state、pid files 和临时 job metadata 放入：
|
||
|
||
```text
|
||
.state/
|
||
```
|
||
|
||
Secret 不得提交。CLI 输出和日志中只能展示 credential source reference，不能展示 credential value。
|
||
|
||
## RESTful 服务规则
|
||
|
||
稳定跨服务边界使用 HTTP JSON resource API。MVP 不使用 SSE、WebSocket 或长同步请求。长时间工作通过 runs、commands、leases、status 和分页 events 表示。
|
||
|
||
CLI 应调用与生产 client 相同的 REST API 路径。Debug command 可以暴露流程中的更小切片，但必须复用真实路径实现，不能维护一套平行 mock-only 路径。
|