文档: 固化 AgentRun 中文规则

AGENTS.md

@@ -1,39 +1,45 @@
-# AgentRun Agent Index
+# AgentRun Agent 索引
 
-AgentRun is the shared agent execution infrastructure for UniDesk and HWLAB. This repository owns AgentRun architecture, API contracts, runner/backend behavior and runtime implementation. UniDesk only records how distributed development and deployment are coordinated from the UniDesk control center.
+AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓库负责 AgentRun 架构、API 契约、runner/backend 行为和运行时实现。UniDesk 只记录如何从 UniDesk 综合分布式开发中心协调 AgentRun 的开发与部署。
+
+## Critical Chinese Documentation Rule
+
+- P0: AgentRun 的所有长期文档、过程文档、issue、PR 标题、PR 正文、PR 评论和交付说明一律使用中文。
+- P0: 代码标识符、API 路径、命令、配置键、日志字段、协议字段和必要英文专有名词可以保留英文，但解释性文字必须使用中文。
+- P0: 外部英文资料只能作为引用或短摘录出现；落入本仓库的设计结论、验收标准和操作说明必须转写为中文。
 
 ## Critical Source Workspace Rule
 
-- P0: The canonical source workspace is `G14:/root/agentrun`, fixed on branch `master`, with `origin git@github.com:pikasTech/agentrun.git`.
-- P0: Before development, deployment, resumed work or context recovery, run `tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'` from UniDesk and confirm the path, branch, remote and clean state.
-- P0: The fixed workspace is only for precheck, fetch, worktree management and final sync. Normal work must use `/root/agentrun/.worktree/{pr_branch}` created from latest `origin/master`.
-- P0: Do not use UniDesk, HWLAB, D601 workspaces, temporary clones, pod-local copies or runner checkouts as AgentRun source truth.
+- P0: 唯一长期 source workspace 是 `G14:/root/agentrun`，固定使用 `master` 分支，`origin` 固定为 `git@github.com:pikasTech/agentrun.git`。
+- P0: 每次开发、部署、恢复中断或上下文压缩后，都必须先从 UniDesk 执行 `tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'`，确认路径、分支、remote 和 clean 状态。
+- P0: 固定 workspace 只用于预检、fetch、worktree 管理和最终同步。常规修改必须在 `/root/agentrun/.worktree/{pr_branch}` 中完成，并从最新 `origin/master` 创建。
+- P0: 不得把 UniDesk、HWLAB、D601 workspace、临时 clone、pod 内副本或 runner checkout 当作 AgentRun source truth。
 
 ## Critical Runtime Target Rule
 
-- P0: Default deployment targets are G14 native k3s namespaces `agentrun_dev` and `agentrun_prod`.
-- P0: Kubernetes operations must use UniDesk route syntax `G14:k3s`, for example `tran G14:k3s kubectl get pods -n agentrun_dev`.
-- P0: Do not create durable AgentRun exposure through ad hoc NodePort, host port, direct pod IP, one-off port-forward or provider-gateway business HTTP proxy. Public or cross-service access must be introduced through reviewed repository changes.
+- P0: 默认部署目标是 G14 原生 k3s namespace：`agentrun_dev` 和 `agentrun_prod`。
+- P0: Kubernetes 操作必须使用 UniDesk route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n agentrun_dev`。
+- P0: 不得通过临时 NodePort、host port、pod IP、一次性 port-forward 或 provider-gateway 业务 HTTP proxy 固化 AgentRun 暴露路径。公网或跨服务入口必须通过本仓库审查后的变更引入。
 
 ## Critical MVP Rule
 
-- P0: AgentRun must be developed as a vertical MVP, not as a broad parallel service rewrite.
-- P0: First prove minimal `runner + one backend`; then add `agentrun-mgr` durable facts and manual runner startup; only after that add automatic scheduler.
-- P0: Existing UniDesk Code Queue and HWLAB Code Agent paths are not replaced by default. AgentRun starts as a new shared execution plane with canary integrations.
+- P0: AgentRun 必须按纵向 MVP 开发，不能一开始并行铺开成多服务大重写。
+- P0: 先证明最小 `runner + 一个 backend`；再加入 `agentrun-mgr` 的 durable facts 和手动启动 runner；最后再加入自动 scheduler。
+- P0: 现有 UniDesk Code Queue 和 HWLAB Code Agent 路径默认不被 AgentRun 替换。AgentRun 先作为新的共享执行面，通过 canary 集成逐步验证。
 
 ## Critical RESTful MVP Rule
 
-- P0: The MVP uses short RESTful HTTP/JSON requests only. Do not add SSE, WebSocket, long-polling or long synchronous `turn` calls in the first phase.
-- P0: Long agent work must be represented by asynchronous resources: commands, runs, events, status and leases. Clients observe progress by paged polling.
-- P0: Runner inbound API should stay private and minimal. Clients should call `agentrun-mgr`; manually started runners must still claim and report through the manager.
+- P0: MVP 阶段只使用短 RESTful HTTP/JSON 请求。第一阶段不做 SSE、WebSocket、long-polling 或长同步 `turn` 请求。
+- P0: 长时间 Agent 工作必须表示为异步资源：commands、runs、events、status 和 leases。客户端通过分页轮询观察进度。
+- P0: Runner inbound API 应保持私有且最小。业务客户端调用 `agentrun-mgr`；人工启动的 runner 也必须通过 manager claim 和 report。
 
 ## Critical CLI Spec Rule
 
-- P0: AgentRun CLI and service work must follow the UniDesk `cli-spec` principles: JSON output by default, no empty-success output, no long blocking CLI calls, visible logs, explicit config validation and RESTful service APIs for stable boundaries.
-- P0: Once a CLI is added, keep the entry small and move implementation into `scripts/src/`; long operations must return quickly and expose status/log/event polling.
+- P0: AgentRun CLI 和服务开发必须遵循 UniDesk `cli-spec` 原则：默认 JSON 输出、禁止空输出伪成功、禁止长阻塞 CLI、日志可见、配置显式校验、稳定跨服务边界优先使用 RESTful API。
+- P0: 一旦新增 CLI，入口文件必须保持轻量，具体实现拆入 `scripts/src/`；长任务必须快速返回，并提供 status/log/event 轮询。
 
-## Reference Docs
+## 长期参考文档
 
-- `docs/reference/architecture.md`: AgentRun product boundary, service architecture, MVP phases, RESTful API model and data model.
-- `docs/reference/cli.md`: CLI and service API conventions derived from `cli-spec`.
-- `TEST.md`: manual validation scenarios for the documented CLI/service behavior as it is implemented.
+- `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。
+- `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。
+- `TEST.md`：随实现逐步补齐的人工验收场景。

TEST.md

@@ -1,15 +1,15 @@
-# AgentRun Manual Test Plan
+# AgentRun 人工测试计划
 
-These tests are placeholders until the CLI and services exist. They define how future manual validation should be written.
+这些测试会随着 CLI 和服务实现逐步补齐。当前先定义未来人工验收的写法。
 
-## T1 Minimal Run Lifecycle
+## T1 最小 Run 生命周期
 
-Read `AGENTS.md`, then use the AgentRun CLI to manually test creating a run, starting a runner for that run, polling events, and observing terminal status. Verify every CLI command returns JSON, includes ids and follow-up commands, and never waits for a full model turn in one request.
+阅读 `AGENTS.md`，然后使用 AgentRun CLI 手动测试创建 run、为该 run 启动 runner、轮询 events 并观察 terminal status。确认每个 CLI 命令都返回 JSON，包含 id 和后续命令，并且不会在单个请求中等待完整模型 turn。
 
-## T2 Command And Event Polling
+## T2 Command 与 Event 轮询
 
-Read `AGENTS.md`, then create a run command and poll command status plus run events. Verify command state is visible, event pagination uses `afterSeq`, and repeated polling does not duplicate events.
+阅读 `AGENTS.md`，然后创建 run command，并轮询 command status 与 run events。确认 command state 可见，event pagination 使用 `afterSeq`，重复轮询不会产生重复 event。
 
-## T3 Logs And Failure Visibility
+## T3 日志与失败可见性
 
-Read `AGENTS.md`, then start the local service or runner with an intentionally invalid backend profile. Verify the CLI returns a structured failure, the log path is printed, and the log file contains enough detail to diagnose the failure.
+阅读 `AGENTS.md`，然后用一个故意无效的 backend profile 启动本地服务或 runner。确认 CLI 返回结构化失败，输出 log path，并且日志文件包含足够定位失败原因的信息。

docs/reference/architecture.md

@@ -1,59 +1,59 @@
-# AgentRun Architecture Reference
+# AgentRun 架构参考
 
-AgentRun is a shared agent execution plane for UniDesk and HWLAB. It is not a rename of UniDesk Code Queue and must not replace existing Code Queue behavior by default. Code Queue remains the current UniDesk task queue; AgentRun is a new infrastructure line focused on agent run lifecycle, runner isolation and pluggable execution backends.
+AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行面。它不是 UniDesk Code Queue 的改名，也不能默认替换现有 Code Queue 行为。Code Queue 仍是当前 UniDesk 任务队列；AgentRun 是新的基础设施线，重点是 Agent run 生命周期、runner 隔离和可插拔执行 backend。
 
-## Product Boundary
+## 产品边界
 
-AgentRun owns generic execution infrastructure:
+AgentRun 负责通用执行基础设施：
 
-- creating and tracking runs;
-- accepting durable commands such as `turn`, `steer`, `interrupt` and `resume`;
-- assigning runs to short-lived runners;
-- normalizing backend events, stdout/stderr, assistant messages, tool calls and terminal status;
-- managing leases, heartbeats, retries caused by infrastructure recovery and run visibility;
-- registering backend capabilities and credential injection boundaries.
+- 创建和跟踪 run；
+- 接收 `turn`、`steer`、`interrupt`、`resume` 等 durable command；
+- 将 run 分配给短生命周期 runner；
+- 归一化 backend event、stdout/stderr、assistant message、tool call 和 terminal status；
+- 管理 lease、heartbeat、基础设施恢复导致的 retry 语义和 run 可观测性；
+- 注册 backend capability，并定义 credential 注入边界。
 
-UniDesk and HWLAB are tenants or clients. UniDesk owns platform entrypoints, provider inventory, CLI/frontend integration and existing Code Queue compatibility. HWLAB owns lab-specific task policy, device and hardware semantics, operation/audit/evidence models and HWLAB workspace rules. AgentRun must not decide whether a HWLAB live device mutation is authorized or whether a UniDesk production deployment may proceed; it executes runs whose tenant policy already grants that authority.
+UniDesk 与 HWLAB 是 tenant/client。UniDesk 负责平台入口、provider 清单、CLI/frontend 集成和现有 Code Queue 兼容。HWLAB 负责实验室任务 policy、设备/硬件语义、operation/audit/evidence 模型和 HWLAB workspace 规则。AgentRun 不判断某个 HWLAB live device mutation 是否被授权，也不判断某个 UniDesk production deployment 是否允许执行；它只执行 tenant policy 已授权的 run。
 
-Every run must carry explicit isolation fields:
+每个 run 都必须显式携带隔离字段：
 
-- `tenantId`, such as `unidesk` or `hwlab`;
-- `projectId`, such as `pikasTech/unidesk` or `pikasTech/HWLAB`;
-- `workspaceRef`, identifying the source/worktree/workspace target;
-- `providerId`, such as `G14` or `D601`;
-- `backendProfile`, such as `codex`, `opencode`, `claudecode`, `host-native` or `windows-native`;
-- `executionPolicy`, including sandbox, approval, timeout, network and secret scope;
-- `traceSink`, identifying where standardized events are mirrored.
+- `tenantId`，例如 `unidesk` 或 `hwlab`；
+- `projectId`，例如 `pikasTech/unidesk` 或 `pikasTech/HWLAB`；
+- `workspaceRef`，用于定位 source/worktree/workspace；
+- `providerId`，例如 `G14` 或 `D601`；
+- `backendProfile`，例如 `codex`、`opencode`、`claudecode`、`host-native` 或 `windows-native`；
+- `executionPolicy`，包含 sandbox、approval、timeout、network 和 secret scope；
+- `traceSink`，说明标准化 event 镜像到哪里。
 
-## Service Shape
+## 服务形态
 
-AgentRun should be built as a small service family:
+AgentRun 应构建为小型服务族：
 
 ```text
 agentrun-mgr
-  public RESTful API, durable facts, tenant/policy/idempotency checks
+  公共 RESTful API、durable facts、tenant/policy/idempotency 检查
 
 agentrun-runner
-  short-lived per-run or per-attempt executor; claims a run, talks to one backend, writes events/status
+  短生命周期 per-run 或 per-attempt executor；claim 一个 run，连接一个 backend，写回 events/status
 
 agentrun-backend-*
-  backend adapters for Codex, Claude Code, OpenCode, host-native or Windows-native execution
+  Codex、Claude Code、OpenCode、host-native 或 Windows-native 执行适配器
 
 agentrun-scheduler
-  later automatic dispatcher; scans pending runs, selects backend/profile/capacity, creates runner Jobs
+  后续自动 dispatcher；扫描 pending runs，选择 backend/profile/capacity，创建 runner Jobs
 ```
 
-The manager is the stable API and audit point. The runner is an executor and should not become a public API that business clients call directly. Operators may manually start a runner process or Kubernetes Job during MVP, but that runner still claims a run from `agentrun-mgr` and writes all facts back to the manager.
+Manager 是稳定 API 和审计点。Runner 是执行者，不应成为业务客户端直接调用的公共 API。MVP 阶段 operator 可以人工启动 runner 进程或 Kubernetes Job，但 runner 仍必须从 `agentrun-mgr` claim run，并把所有事实写回 manager。
 
-Backend adapters hide concrete tool protocols. Codex stdio JSON-RPC, OpenCode JSON events, Claude Code, host-native processes and Windows-native execution may use different internal protocols, but public AgentRun APIs must stay stable and backend-neutral.
+Backend adapter 隐藏具体工具协议。Codex stdio JSON-RPC、OpenCode JSON events、Claude Code、host-native process 和 Windows-native execution 可以使用不同内部协议，但 AgentRun 公共 API 必须保持稳定且与 backend 无关。
 
-## MVP Sequence
+## MVP 顺序
 
-AgentRun should be built as a vertical slice rather than a broad parallel build.
+AgentRun 必须按纵向切片推进，不要一开始大规模并行开发。
 
-### M0: Contract Skeleton
+### M0: 契约骨架
 
-Define only the minimal resource model and state machine:
+只定义最小资源模型和状态机：
 
 - `Run`
 - `Command`
@@ -61,68 +61,68 @@ Define only the minimal resource model and state machine:
 - `Runner`
 - `Backend`
 
-Only `turn`, `interrupt`, `status` and paged `events` are required for the first slice. Do not start with `steer`, `resume`, judge/retry, UI, multi-backend routing or automatic scheduling.
+第一切片只要求 `turn`、`interrupt`、`status` 和分页 `events`。不要一开始就做 `steer`、`resume`、judge/retry、UI、多 backend 路由或自动调度。
 
-### M1: Minimal Runner Plus One Backend
+### M1: 最小 Runner 加一个 Backend
 
-The first executable proof should run without a manager or scheduler. A runner reads a local run spec, calls one backend and emits standardized events.
+第一份可执行证明不依赖 manager 或 scheduler。Runner 读取本地 run spec，调用一个 backend，并输出标准化 events。
 
-Acceptance:
+验收标准：
 
-- one `turn` executes through the backend;
-- assistant/output/error events are normalized;
-- terminal status is written;
-- interrupt has at least a durable cancellation path, with real process interruption added when the backend supports it.
+- 一个 `turn` 能通过 backend 执行；
+- assistant/output/error events 被归一化；
+- terminal status 被写出；
+- interrupt 至少有 durable cancellation 路径，backend 支持时再传播到真实进程中断。
 
-The first backend should be the narrowest backend that proves the real agent primitive. If Codex friction is high, a controlled process backend can be used briefly for contract shape, but the MVP must move to one real agent backend before higher layers are considered validated.
+第一个 backend 应选择能证明真实 Agent 原语的最窄实现。如果 Codex 摩擦过大，可以短暂用 controlled process backend 证明 contract shape，但 MVP 必须尽快回到一个真实 Agent backend，否则不能认为上层已验证。
 
-### M2: Manager Plus Runner Claim
+### M2: Manager 加 Runner Claim
 
-Add `agentrun-mgr` as the durable fact store and public API. A client creates a run; an operator or CLI manually starts a runner with the run id; the runner claims, polls commands, appends events, heartbeats and exits.
+加入 `agentrun-mgr` 作为 durable fact store 和公共 API。Client 创建 run；operator 或 CLI 用 run id 人工启动 runner；runner claim、poll commands、append events、heartbeat 并退出。
 
-Acceptance:
+验收标准：
 
-- run creation and query are durable;
-- runner claim is idempotent and rejects double ownership;
-- events are append-only and paged by sequence;
-- command ack states are visible;
-- heartbeat expiration is observable.
+- run create/query 是 durable 的；
+- runner claim 幂等，并拒绝双 owner；
+- events 是 append-only，并按 seq 分页；
+- command ack state 可见；
+- heartbeat expiration 可观察。
 
-### M3: Manual Dispatch CLI
+### M3: 手动 Dispatch CLI
 
-Add a CLI that starts a local runner process or Kubernetes Job for a selected run. This is manual dispatch, not manager-side synchronous orchestration. The manager still owns the facts; the runner still owns execution.
+增加 CLI，为指定 run 启动本地 runner process 或 Kubernetes Job。这是 manual dispatch，不是 manager 侧同步编排。Manager 仍拥有事实，runner 仍拥有执行。
 
-Acceptance:
+验收标准：
 
-- CLI returns quickly with JSON output;
-- job/process identity and log path are visible;
-- run status can be polled from the manager;
-- failed runner startup is reported as infrastructure failure, not as silent task success.
+- CLI 快速返回 JSON；
+- job/process identity 和 log path 可见；
+- run status 可从 manager 轮询；
+- runner 启动失败被报告为基础设施失败，不能静默写成任务成功。
 
-### M4: Automatic Scheduler
+### M4: 自动 Scheduler
 
-Only after M1-M3 are stable, add `agentrun-scheduler`. The scheduler scans pending runs, applies policy/capacity/backend selection, creates runner Jobs and performs stale lease recovery. It must not directly execute backends.
+只有 M1-M3 稳定后才加入 `agentrun-scheduler`。Scheduler 扫描 pending runs，应用 policy/capacity/backend selection，创建 runner Jobs，并处理 stale lease recovery。Scheduler 不直接执行 backend。
 
-Acceptance:
+验收标准：
 
-- pending runs become running automatically;
-- scheduler restart does not interrupt already running runners;
-- stale leases are recovered with explicit audit events;
-- scheduler rollout does not imply active run failure.
+- pending run 自动变为 running；
+- scheduler restart 不影响已经运行的 runner；
+- stale lease recovery 留下显式 audit event；
+- scheduler rollout 不等同于 active run failure。
 
-### M5: Tenant Canary Integrations
+### M5: Tenant Canary 集成
 
-UniDesk and HWLAB should integrate as canaries after core lifecycle proof:
+核心生命周期证明后，再接入 UniDesk 和 HWLAB canary：
 
-- UniDesk may add `agentrun` CLI/API routes while existing Code Queue remains intact.
-- HWLAB may route a narrow Code Agent canary through AgentRun.
-- Tenant policy, workspace, secret scope and trace sinks must be explicit in every run.
+- UniDesk 可以新增 `agentrun` CLI/API route，同时保持现有 Code Queue 不变。
+- HWLAB 可以把一个窄范围 Code Agent canary 路由到 AgentRun。
+- 每个 run 都必须显式带 tenant policy、workspace、secret scope 和 trace sink。
 
-## RESTful MVP Contract
+## RESTful MVP 契约
 
-The MVP uses only short RESTful HTTP/JSON requests. Long-running agent work is represented by durable command resources, run status and paged event polling. Do not keep an HTTP request open for a full model turn.
+MVP 只使用短 RESTful HTTP/JSON 请求。长时间 Agent 工作用 durable command resource、run status 和分页 event polling 表示。不要让一个 HTTP 请求等待完整模型 turn。
 
-Public manager APIs:
+Manager 公共 API：
 
 ```http
 POST /api/v1/runs
@@ -133,7 +133,7 @@ GET  /api/v1/runs/:runId/commands/:commandId
 GET  /api/v1/backends
 ```
 
-Runner-to-manager APIs:
+Runner 到 manager 的私有 API：
 
 ```http
 POST  /api/v1/runners/register
@@ -145,20 +145,20 @@ PATCH /api/v1/runs/:runId/status
 POST  /api/v1/commands/:commandId/ack
 ```
 
-Runner inbound APIs should stay local/private and minimal:
+Runner inbound API 应保持本地/私有且最小：
 
 ```http
 GET /health
 GET /debug/status
 ```
 
-Do not depend on clients calling transient runner Pod addresses. That breaks across Jobs, namespaces, host-native backends and restarts.
+不要依赖客户端调用短生命周期 runner Pod 地址。该方式在 Job、namespace、host-native backend 和重启场景下都会变脆。
 
-## Command State
+## Command 状态
 
-Commands are durable resources. `turn`, `steer`, `interrupt` and `resume` must not be implemented as synchronous process calls from a client to a runner.
+Command 是 durable resource。`turn`、`steer`、`interrupt` 和 `resume` 不能实现为 client 到 runner 的同步进程调用。
 
-The initial command state machine is:
+初始 command 状态机：
 
 ```text
 accepted -> delivered -> confirmed
@@ -166,18 +166,18 @@ accepted -> delivered -> failed
 accepted -> expired
 ```
 
-All command writes should support idempotency keys. Duplicate commands with the same idempotency key and payload hash should return the existing command. Duplicate keys with different payload hashes should fail visibly.
+所有 command 写入都应支持 idempotency key。相同 idempotency key 且 payload hash 相同的重复请求返回既有 command；相同 key 但 payload hash 不同必须显式失败。
 
-## Event Model
+## Event 模型
 
-Events are append-only and paged by sequence:
+Event 是 append-only，并按 seq 分页：
 
-- `seq` is monotonic per run.
-- `eventId` or `(runId, seq)` is idempotent.
-- `GET /events?afterSeq=N&limit=M` is the first observation API.
-- Later SSE may stream the same events, but must not replace the REST polling contract.
+- `seq` 在单个 run 内单调递增。
+- `eventId` 或 `(runId, seq)` 支持幂等去重。
+- `GET /events?afterSeq=N&limit=M` 是第一阶段观察 API。
+- 后续 SSE 可以流式传输相同 event resource，但不能替代 REST polling contract。
 
-Minimum event categories:
+最小 event 类别：
 
 - `system`
 - `assistant_message`
@@ -188,36 +188,36 @@ Minimum event categories:
 - `backend_status`
 - `terminal_status`
 
-## Data Model Direction
+## 数据模型方向
 
-The first implementation may use a compact schema, but it should not hide all facts in one JSON blob. The stable direction is:
+第一版实现可以使用紧凑 schema，但不应把所有事实都隐藏在一个 JSON blob 中。稳定方向是：
 
-- `agentrun_runs`: run identity, tenant/project/workspace/backend policy, status and timestamps;
-- `agentrun_commands`: command type, idempotency key, payload hash, state and ack timestamps;
-- `agentrun_events`: append-only event records keyed by run and sequence;
-- `agentrun_runners`: registered runner identity, placement and heartbeat;
-- `agentrun_backends`: backend profile, capabilities, capacity and health;
-- `agentrun_leases`: current ownership and expiry.
+- `agentrun_runs`：run identity、tenant/project/workspace/backend policy、status 和 timestamps；
+- `agentrun_commands`：command type、idempotency key、payload hash、state 和 ack timestamps；
+- `agentrun_events`：按 run 和 seq 索引的 append-only event records；
+- `agentrun_runners`：registered runner identity、placement 和 heartbeat；
+- `agentrun_backends`：backend profile、capabilities、capacity 和 health；
+- `agentrun_leases`：当前 ownership 和 expiry。
 
-## Deployment Direction
+## 部署方向
 
-Default runtime targets are G14 native k3s namespaces `agentrun_dev` and `agentrun_prod`. Control-plane services should be long-lived; runners should be short-lived Jobs or controlled host-native processes. Backend adapters may run as pods or host-native services, but they must register capabilities and health through AgentRun rather than being called through ad hoc addresses.
+默认运行目标是 G14 原生 k3s namespace `agentrun_dev` 和 `agentrun_prod`。Control-plane service 应是长驻服务；runner 应是短生命周期 Job 或受控 host-native process。Backend adapter 可以作为 pod 或 host-native service 运行，但必须通过 AgentRun 注册 capability 和 health，不能通过临时地址被 ad hoc 调用。
 
-Namespace isolation, RBAC, Secret scope, NetworkPolicy and ResourceQuota should be introduced before broad tenant use. A separate cluster is a later maturity option; the first implementation should prove the service inside G14 k3s namespaces unless a concrete isolation blocker requires a dedicated cluster.
+广泛 tenant 使用前，需要先设计 namespace isolation、RBAC、Secret scope、NetworkPolicy 和 ResourceQuota。独立 cluster 是后续成熟选项；第一版应优先在 G14 k3s namespace 内证明服务，除非出现明确隔离 blocker。
 
-## Non-Goals For MVP
+## MVP 非目标
 
-Do not include these in the first MVP:
+第一版 MVP 不包含：
 
-- migrating UniDesk Code Queue;
-- replacing HWLAB Code Agent globally;
-- multi-backend routing;
-- UI beyond minimal diagnostics;
-- judge/retry automation;
-- automatic scaling;
-- cross-cluster placement;
-- SSE/WebSocket streaming;
-- complete permission system;
-- production rollout automation.
+- 迁移 UniDesk Code Queue；
+- 全局替换 HWLAB Code Agent；
+- 多 backend 路由；
+- 最小诊断之外的 UI；
+- judge/retry 自动化；
+- 自动扩缩容；
+- 跨集群调度；
+- SSE/WebSocket 流式输出；
+- 完整权限系统；
+- production rollout 自动化。
 
-The first goal is one stable vertical run lifecycle: create run, manually start runner, execute one backend turn, append events, observe final status and issue a visible interrupt/cancel command.
+第一目标是稳定跑通一条纵向 run 生命周期：create run、人工启动 runner、执行一个 backend turn、append events、观察 final status，并能发出可见的 interrupt/cancel command。

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