pikasTech-agentrun/docs/reference/cli.md

AgentRun CLI 与服务 API 参考

v0.1 CLI 的权威规格是 spec-v01-cli.md。本文保留为 CLI 与服务 API 的辅助参考；如果命令、测试规格或实现状态与 spec-v01-cli.md 冲突，以 spec-v01-cli.md 为准。

AgentRun CLI 与服务 API 遵循 UniDesk cli-spec 原则。本文在 CLI 实现前先固化期望形态，避免实现漂移成长阻塞命令或隐藏状态。

CLI 形态

未来 CLI 入口应保持轻量，并把实现路由到模块：

scripts/agentrun-cli.ts
scripts/src/*.ts

CLI 默认输出 JSON。空 stdout 是失败，不是成功。每个命令都必须返回足够继续排障的结构化信息，包括 id、status、log path 或后续命令。

长操作必须是 fire-and-forget 或短异步资源操作。CLI 调用应在 60 秒内返回。创建 run 或启动 runner 的命令返回创建出的资源和轮询命令，不等待模型 turn 完成。

规划命令

初始命令族：

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。引入本地开发服务后，应使用固定端口，并把实时日志写入：

logs/{YYYYMMDD}/

Runtime state、pid files 和临时 job metadata 放入：

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