# 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 路径。