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