Codex
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# AgentRun CLI 与服务 API 参考
|
|
|
|
AgentRun CLI 与服务 API 遵循 UniDesk `cli-spec` 原则。本文在 CLI 实现前先固化期望形态，避免实现漂移成长阻塞命令或隐藏状态。
|
|
|
|
## 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 完成。
|
|
|
|
## 规划命令
|
|
|
|
初始命令族：
|
|
|
|
```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
|
|
```
|
|
|
|
具体命令名可以在实现时调整，但行为必须保持以下规则：
|
|
|
|
- `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 路径。
|