Codex
69 lines
3.0 KiB
Markdown
69 lines
3.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 或后续命令。
|
|
|
|
长操作必须是 fire-and-forget 或短异步资源操作。CLI 调用应在 60 秒内返回。创建 run 或启动 runner 的命令返回创建出的资源和轮询命令，不等待模型 turn 完成。
|
|
|
|
## 常用命令
|
|
|
|
`v0.1` 常用命令族：
|
|
|
|
```bash
|
|
./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 backends list
|
|
./scripts/agentrun server start|status
|
|
```
|
|
|
|
行为必须保持以下规则：
|
|
|
|
- `runs create` 创建 durable facts 并立即返回。
|
|
- `runner start` 启动本地进程或 Kubernetes Job，并返回 process/job identity、log path 和 poll commands。
|
|
- `events` 默认分页且有界。
|
|
- `server logs` 返回有界日志，并指向完整日志文件。
|
|
- `status` 在本地服务存在后必须暴露 port、process id、health 和 log paths。
|
|
|
|
## 配置与日志
|
|
|
|
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 路径。
|