Codex
79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# v0.1 AgentRun CLI 规格
|
||
|
||
AgentRun CLI 是 `v0.1` 的受控人工操作和验收入口。它必须遵循 UniDesk `cli-spec` 原则：默认 JSON 输出、禁止空输出伪成功、禁止长阻塞、日志可见、配置显式校验，并优先通过 `agentrun-mgr` RESTful API 完成跨服务操作。
|
||
|
||
## 在系统中的职责划分
|
||
|
||
- 创建 run、查询 run、提交 command、查询 command、分页读取 events。
|
||
- 手动启动 runner，本地 process 或 Kubernetes Job 均必须快速返回 job/process identity 和 logPath。
|
||
- 查询 backend capability 和 manager health。
|
||
- 为综合联调提供 CLI 交互面；不得替代 RESTful API 合同测试。
|
||
- 不直连 Postgres，不读取 provider Secret 值，不把 debug/mock 路径伪装成正式验收。
|
||
|
||
## CLI 入口
|
||
|
||
`v0.1` 固定规划入口：
|
||
|
||
```text
|
||
scripts/agentrun-cli.ts
|
||
scripts/src/*.ts
|
||
```
|
||
|
||
CLI 官方运行方式固定为 Bun + TypeScript：`bun scripts/agentrun-cli.ts ...`。`node`、`tsx` 或 shell wrapper 只能作为本地开发辅助，不能成为 `v0.1` 用户文档、CI/CD 或综合联调的权威入口。入口文件只负责参数解析和路由，具体实现拆到 `scripts/src/`。CLI 命令默认输出 JSON；任何命令无 stdout 都是失败。单次 CLI 调用必须在 60 秒内返回，长时间模型 turn 通过 status/events 后续命令观察。
|
||
|
||
## 初始命令族
|
||
|
||
```bash
|
||
bun scripts/agentrun-cli.ts runs create --json-file <run.json>
|
||
bun scripts/agentrun-cli.ts runs show <runId>
|
||
bun scripts/agentrun-cli.ts runs events <runId> --after-seq <n> --limit <n>
|
||
bun scripts/agentrun-cli.ts commands create <runId> --type turn --json-file <payload.json>
|
||
bun scripts/agentrun-cli.ts commands show <commandId>
|
||
bun scripts/agentrun-cli.ts runner start --run-id <runId> --backend <backendProfile>
|
||
bun scripts/agentrun-cli.ts backends list
|
||
bun scripts/agentrun-cli.ts server start|status|stop|logs
|
||
```
|
||
|
||
具体参数可以在实现时按代码结构微调，但行为必须保持：
|
||
|
||
- 创建类命令返回 `runId`、`commandId`、status 和下一步 poll command。
|
||
- `runner start` 返回 attemptId、job/process identity、logPath 和后续 status/events 命令。
|
||
- 查询类命令返回当前 state、terminal_status、failureKind、event cursor 或 logPath。
|
||
- `events` 默认分页且有界，必须支持 `afterSeq` 和 `limit`。
|
||
- `server logs` 返回有界日志摘要，并指向完整日志文件或 Kubernetes pod identity。
|
||
|
||
## 配置与 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](spec-v01-validation.md)，然后用正式 AgentRun CLI 创建 run、提交 `turn` command、启动 runner、轮询 command 和 events 直到 terminal_status。确认每个命令输出非空 JSON，60 秒内返回，并给出下一步可执行命令或 logPath。
|
||
|
||
### 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](spec-v01-agentrun-mgr.md)，然后对同一个 run 分别使用 CLI 和 RESTful API 查询 run、command、events 和 terminal_status。确认 CLI 不维护独立状态，两种交互面观察结果一致。
|
||
|
||
## 规格的实现情况
|
||
|
||
| 规格项 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| AgentRun CLI 规格 | 已定义 | 本文为 v0.1 CLI 权威。 |
|
||
| `scripts/agentrun-cli.ts` | 部分实现 | 已提供 run/command/event/backend/server 基础命令和 JSON envelope。 |
|
||
| CLI 调 manager REST | 部分实现 | CLI 通过 `ManagerClient` 调 manager REST；当前自测试使用内存 manager。 |
|
||
| runner start | 部分实现 | `runner start` 可执行 host process runner；`runner job --dry-run` 可渲染 Kubernetes Job JSON，尚不执行 create/apply。 |
|
||
| CLI 测试规格 | 已定义 | 综合联调见 [spec-v01-validation.md](spec-v01-validation.md)。 |
|