文档: 固化 AgentRun 中文规则

docs/reference/cli.md

@@ -1,23 +1,23 @@
-# AgentRun CLI And Service API Reference
+# AgentRun CLI 与服务 API 参考
 
-AgentRun CLI and service APIs follow the UniDesk `cli-spec` principles. This document records the expected shape before the CLI exists so implementation does not drift toward long blocking commands or hidden state.
+AgentRun CLI 与服务 API 遵循 UniDesk `cli-spec` 原则。本文在 CLI 实现前先固化期望形态，避免实现漂移成长阻塞命令或隐藏状态。
 
-## CLI Shape
+## CLI 形态
 
-The future CLI entry should be small and route to implementation modules:
+未来 CLI 入口应保持轻量，并把实现路由到模块：
 
 ```text
 scripts/agentrun-cli.ts
 scripts/src/*.ts
 ```
 
-The CLI should default to JSON output. Empty stdout is a failure, not success. Every command must return enough structured data to continue debugging, including ids, status, log paths or follow-up commands.
+CLI 默认输出 JSON。空 stdout 是失败，不是成功。每个命令都必须返回足够继续排障的结构化信息，包括 id、status、log path 或后续命令。
 
-Long operations must be fire-and-forget or short asynchronous resource operations. CLI calls should return in under 60 seconds. A command that creates a run or starts a runner returns the created resource and polling commands; it does not wait for the model turn to complete.
+长操作必须是 fire-and-forget 或短异步资源操作。CLI 调用应在 60 秒内返回。创建 run 或启动 runner 的命令返回创建出的资源和轮询命令，不等待模型 turn 完成。
 
-## Planned Commands
+## 规划命令
 
-Initial command families:
+初始命令族：
 
 ```bash
 bun scripts/agentrun-cli.ts runs create --json-file <run.json>
@@ -30,32 +30,32 @@ bun scripts/agentrun-cli.ts backends list
 bun scripts/agentrun-cli.ts server start|status|stop|logs
 ```
 
-The exact command names may change when implemented, but the behavior must keep these rules:
+具体命令名可以在实现时调整，但行为必须保持以下规则：
 
-- `runs create` creates durable facts and returns immediately.
-- `runner start` starts a local process or Kubernetes Job and returns process/job identity, log path and poll commands.
-- `events` is paged and bounded by default.
-- `server logs` returns bounded logs and points to full log files.
-- `status` must expose port, process id, health and log paths once a local service exists.
+- `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。
 
-## Config And Logs
+## 配置与日志
 
-AgentRun config must be explicit and validated. Do not silently fall back to deployment-critical defaults. When a local development server is introduced, it should use a fixed port and write real-time logs under:
+AgentRun 配置必须显式且经过校验。部署关键值不得静默 fallback。引入本地开发服务后，应使用固定端口，并把实时日志写入：
 
 ```text
 logs/{YYYYMMDD}/
 ```
 
-Runtime state, pid files and transient job metadata belong under:
+Runtime state、pid files 和临时 job metadata 放入：
 
 ```text
 .state/
 ```
 
-Secrets must not be committed. Credential sources should be represented by references, not values, in CLI output and logs.
+Secret 不得提交。CLI 输出和日志中只能展示 credential source reference，不能展示 credential value。
 
-## RESTful Service Rule
+## RESTful 服务规则
 
-Stable cross-service boundaries use HTTP JSON resource APIs. The MVP does not use SSE, WebSocket or long synchronous requests. Long-running work is represented by runs, commands, leases, status and paged events.
+稳定跨服务边界使用 HTTP JSON resource API。MVP 不使用 SSE、WebSocket 或长同步请求。长时间工作通过 runs、commands、leases、status 和分页 events 表示。
 
-The CLI should call the same REST API paths that production clients use. Debug commands may expose smaller slices of the flow, but they must share implementation with the real path rather than maintaining a parallel mock-only path.
+CLI 应调用与生产 client 相同的 REST API 路径。Debug command 可以暴露流程中的更小切片，但必须复用真实路径实现，不能维护一套平行 mock-only 路径。