docs: maintain bilingual documentation and localize website navigation

AGENTS.md

@@ -63,7 +63,7 @@ OpenAgentCore is pre-release. Replace superseded interfaces, execution paths and
 - Do not hard-wrap prose. Write each paragraph, list item and blockquote on one line; editors wrap it for display.
 - User-facing documentation uses Web's exact page and action names.
 - Application examples read the endpoint and key from `OPENAI_BASE_URL` and `OPENAI_API_KEY`.
-- Write documentation and code comments in English. The root README also has a Chinese version; user-facing product copy may be bilingual.
+- Maintain authored documentation under `docs/` and `contracts/agents-api/` in English and Simplified Chinese in the same change. English files keep their paths; Chinese translations mirror them under `docs/zh/` and `contracts/agents-api/zh/`. Preserve protocol identifiers, executable examples and English heading anchors. Each translation records its English `source` and SHA-256 `source_hash` in frontmatter; website checks reject missing or stale translations. Generated references remain owned by their generators and are excluded from manual translation. Keep code comments in English. The root README also has a Chinese version; user-facing product copy may be bilingual.
 - Markdown in `docs/`, component guides and `contracts/` is the authored source. Generated files, such as the OpenAPI documents and the [Harness catalog reference](contracts/agents-api/harness-catalog.md), are never edited by hand: change the source and regenerate.
 - Update the owning document in the same branch as the rule, workflow or generated contract it describes.
 

CONTRIBUTING.md

@@ -31,7 +31,7 @@ This guide owns how to work in the repository: documentation ownership, the repo
 | Runtime telemetry responses | [Runtime telemetry API](contracts/agents-api/runtime-observability-api.md) |
 | Runtime observation, sampling, retention and export | [Runtime observability](contracts/agents-api/runtime-observability.md) |
 | Distribution builds, Runtime image builds, CI and publication | [Maintainer guide](docs/maintainers.md) |
-| Website: landing page, documentation site build and GitHub Pages publication | [Website guide](website/README.md) |
+| Website: landing page, bilingual documentation maintenance, documentation site build and GitHub Pages publication | [Website guide](website/README.md) |
 | Self-hosted Runtime installation, recovery and local operation | [Self-hosted execution](docs/getting-started/self-hosted.md) |
 | Installer lifecycle, locking, generated state, managed HTTPS and downloads | [Installer design rules](deploy/install/README.md) |
 | Operator installation and alternatives | [Installation](docs/getting-started/install.md), [installation options](docs/getting-started/install-options.md) |

contracts/agents-api/zh/core-errors.md

@@ -0,0 +1,110 @@
+---
+title: "Core 管理错误"
+source: contracts/agents-api/core-errors.md
+source_hash: d5c4450c0c74927115c79dca70d29372a7316d5d2591c7e18af688d08257a98c
+---
+
+`/core/v1` 上的错误使用此封装结构。`message` 是安全的英文文本；`code` 和 `param` 可以为 null。客户端依据稳定的 `code` 和可选的 `param` 进行处理，对未知代码显示 `message`，绝不解析消息，也绝不自动重试被拒绝的写操作。
+
+```json
+{"error":{"message":"A valid Core key is required as the bearer credential.","type":"invalid_request_error","code":"invalid_admin_key","param":null}}
+```
+
+`/v1` 和 `/api/v1` 上的错误仍使用各自的封装结构，且绝不包含 `details`。
+
+## 可选详细信息 {#optional-details}
+
+存在时，`error.details` 是一个非空的扁平对象。其值可以是字符串、有限数值、null 或字符串数组（数组可以为空）。它仅包含 Core 自身的事实；绝不包含已提交的名称、URL 或密钥、回显的请求值、原生错误文本或提供商响应正文。每个包含详细信息的代码都在下表列出了其确切键名。
+
+| 代码 | 详细信息 |
+| --- | --- |
+| `sandbox_generation_stale` | `current_generation` |
+| `sandbox_in_use` | `allocations`、`pending` |
+| `sandbox_reset_required` | `current_provider`、`requested_provider` |
+| 操作验证代码 | 请参阅 [operation validation](#operation-validation) |
+
+在 TypeScript 客户端中，`AgentCoreError.details` 是可选的 `CoreErrorDetails`。Core 客户端仅接受上述值类型，会复制字符串数组，并忽略格式错误或为空的 `details`，且不会改变错误的 message、status、code、param 或 type。公开的 `OpenAIAgentsClient` 不读取 `details`。
+
+## 控制台自身故障 {#console-generated-failures}
+
+Web 的控制台服务器在 `/core` 路径上发生自身故障时使用此封装结构（[request boundary](../../../docs/zh/web/console-server.md#request-boundary)）。它绝不暴露请求值或传输层异常，并原样透传 Core 的响应。
+
+| HTTP 状态 | 代码 | 含义 | `type` |
+| --- | --- | --- | --- |
+| 401 | `console_sign_in_required` | 控制台会话缺失或已过期 | `invalid_request_error` |
+| 403 | `console_origin_rejected` | Host、Origin 或 Fetch Metadata 检查失败 | `invalid_request_error` |
+| 400 | `console_request_invalid` | 路径、方法或升级不安全 | `invalid_request_error` |
+| 502 | `core_unreachable` | 无法连接 Core，或 Core 返回了重定向 | `server_error` |
+
+这些错误的 `param` 为 null，且没有 `details`。因此，Core 的 `401 invalid_admin_key` 仍可与缺少 console sign-in 区分开来。Console sign-in 路由保留其 `{"error":"…"}` 错误（[sign-in](../../../docs/zh/web/console-server.md#sign-in)）。
+
+## 沙箱提供商验证 {#sandbox-provider-verification}
+
+当 `POST` 或 `PUT /core/v1/sandbox/deployment`（[sandbox deployment](sandbox-deployment.md#reset)）的提供商像 E2B 一样验证凭据或配置时，请求会因以下固定错误而失败。这些错误均不会返回提供商文本、模板名称、密钥或资源数量。
+
+| HTTP | 代码 | 含义 | `param` |
+| --- | --- | --- | --- |
+| 400 | `sandbox_credential_invalid` | 提供商拒绝了候选凭据 | `credential` |
+| 400 | `sandbox_configuration_invalid` | 候选配置（例如 E2B 模板构建）未同时满足就绪和不可变要求，或者与资源不匹配 | `configuration` |
+| 409 | `sandbox_credential_ownership` | 候选凭据无法管理保留的部署；更换账户前必须重置 | `credential` |
+| 503 | `sandbox_verification_unconfirmed` | 无法确认验证结果、回执结算结果或凭据隔离状态 | null |
+
+每次写入部署时，类型化客户端都会将上述代码及其他 `sandbox_*` 部署代码的消息替换为固定的本地文本。`details` 中仅保留 `current_generation`、`allocations`、`pending`、`min` 和 `max`，并且仅当 status、code 和 param 与上表或下方 `invalid_sandbox_configuration` 各行完全匹配时，才保留 `param`。`409 sandbox_configuration_error` 会转换为有关公开 URL 的固定指引，并将 `param` 设为 null，即使对于未提供密钥的 `PUT` 也是如此。其他任何错误都会转换为 `sandbox_configuration_unconfirmed` 且不会重新发送，因为拒绝响应可能会回显密钥。
+
+## 操作验证 {#operation-validation}
+
+每个代码均返回 HTTP 400，并带有 `type: "invalid_request_error"`。如果模型提供商配置包缺失、格式错误或类型错误，系统会在检查任何字段之前返回 `invalid_model_provider`。JSON 正文解析保留其自身错误；其他格式错误的管理请求返回 `invalid_request`。
+
+| 代码 | Param | 详细信息 | 含义 |
+| --- | --- | --- | --- |
+| `invalid_name` | `name` | `max_length`：Projects 和节点为 128，Project 键为 80 | 名称未通过相应资源的验证器 |
+| `invalid_node_capacity` | `max_active` 或 `max_retained` | `min`：1，`max`：1000000 | 容量无效；保留容量还必须至少等于活动容量 |
+| `invalid_model_provider` | null | 省略 | 必须提供完整的模型提供商配置包 |
+| `model_provider_base_url_invalid` | `base_url` | 省略 | 必须使用 HTTPS，且不得包含凭据、查询或片段 |
+| `model_provider_protocol_unsupported` | `protocol` | `harness` 和 `allowed_protocols`，来自该构建的适配器目录 | 协议未知，或所选 Harness 不支持该协议 |
+| `model_provider_api_key_invalid` | `api_key` | `max_length`：16384 | 密钥为空、过长或包含禁止字符 |
+| `model_provider_token_limits_invalid` | `context_window` 或 `max_output_tokens` | 省略 | 限制无效，或 Harness 要求的正数限制缺失 |
+| `model_configuration_model_invalid` | `model` | 省略 | 部署默认配置的 model 不是非空模型标识符 |
+| `harness_config_invalid` | `harness_config` | 省略 | 部署默认配置的原生参数不受支持或无效 |
+| `invalid_sandbox_configuration` | `resources.cpus` | `min`：1，`max`：255 | CPU 数量超出支持范围 |
+| `invalid_sandbox_configuration` | `resources.memory_mib` | `min`：512，`max`：1048576 | 内存超出支持范围 |
+| `invalid_sandbox_configuration` | `resources.root_disk_mib` 或 `resources.environment_disk_mib` | `min`：microsandbox 为 1024；Docker 和 E2B 的 `min`：0，`max`：0 | 磁盘容量缺失或提供商不支持 |
+| `invalid_sandbox_configuration` | `runtime` | 省略 | Runtime release 缺失、可变、无效或 E2B 不允许 |
+
+这些边界是验证常量，绝不是提交的值。节点名称按字节数限制；Project 名称和键名称按去除首尾空白后的 Unicode 字符数限制，且不得包含控制字符。系统仅按以下顺序报告第一个失败项：模型提供商 URL、协议、密钥、常规限制、Harness 协议，然后是 Harness 的必需限制；沙箱资源依次为 CPU、内存、磁盘，然后是 Runtime。`model_provider` 对象内的模型提供商字段错误仍以该对象的相应字段作为 `param`。未知的沙箱提供商返回一个不含这些字段的错误。
+
+## 诊断失败类别 {#diagnostic-failure-categories}
+
+[Session and Turn diagnostics reads](session-diagnostics.md) 会在成功的 200 快照内返回以下类别，而不是以错误封装的形式返回。公开 `/v1` 的 Turn 错误保持不变。除非表格另有说明，否则 `params` 为 `{}`。
+
+| 代码 | 存储原因或安全含义 |
+| --- | --- |
+| `harness_error` | `engine_failed`，且没有原生分类 |
+| `authentication_error` | 原生提供商拒绝了身份验证 |
+| `rate_limit_exceeded` | 原生速率限制分类 |
+| `usage_limit_exceeded` | 原生计费或使用量限制分类 |
+| `server_overloaded` | 原生过载分类 |
+| `server_error` | 原生服务器故障分类 |
+| `invalid_request` | 原生请求被拒绝 |
+| `resource_not_found` | 未找到原生资源或模型 |
+| `request_timeout` | 保留的中性超时类别；当前没有适配器生成该类别 |
+| `context_length_exceeded` | 原生上下文限制分类 |
+| `cyber_policy` | 原生网络安全策略拒绝 |
+| `connection_failed` | 原生连接故障；params 包含 `http_status`，其值为 100–599 范围内的整数或 null |
+| `model_provider_required` | 缺少已冻结的模型提供商 |
+| `runtime_unavailable` | `execution_device_unavailable`、`execution_unavailable` |
+| `runtime_disconnected` | `device_disconnected`、`event_stream_incomplete` |
+| `runtime_preparation_failed` | `preparation_start_failed`、`preparation_interrupted` |
+| `execution_interrupted` | Core 执行被中断 |
+| `delivery_unconfirmed` | `delivery_unknown`、`input_outcome_unknown`、`cancel_unconfirmed`、`cancel_outcome_unavailable`、`function_result_unconfirmed` |
+| `input_rejected` | `invalid_input`、`input_not_applied`、`message_input_unsupported`，以及确切的 steering 结果 `input_invalid_input`、`input_run_inactive`、`input_input_conflict`、`input_input_limit`、`input_unsupported`、`input_rejected`、`input_not_ready`、`input_busy` |
+| `executor_protocol_error` | `invalid_executor_result`、`interaction_not_supported`、`execution_state_unavailable`、`execution_state_changed`、`function_call_invalid`、`function_result_invalid` |
+| `core_storage_failed` | `event_persistence_failed`、`artifact_capture_failed` |
+| `internal_error` | 结果未知或格式错误；不返回原始值 |
+| `environment_connection_timeout` | 初始输入连接截止时间已过 |
+| `environment_unavailable` | 初始输入所需环境不可用 |
+| `environment_provisioning_failed` | 托管预置失败；params 包含来自已清理回执的可空 `step`、`index`、`exit_code` |
+
+数据库故障属于错误，绝不会产生空快照或健康快照。绝不会解析预置原因或原生消息以确定类别或参数。
+
+原生类别仅适用于 outcome 中含有 `error_code: engine_failed` 的失败 Turn。Core 仅接受列出的 `engine_error_code` 值；如果该值未知、格式错误或缺失，则仍归为 `harness_error`。只有 `connection_failed` 使用 `engine_http_status`。绝不会根据嵌套元数据或提供商文本来划分失败类别。Core 存储、流不完整和取消故障具有更高优先级；已取消或已完成的 Turn 没有故障。[Native error classification](../../../docs/zh/runtime-protocol.md#native-failure-classification) 列出了各适配器会报告哪些类别。

contracts/agents-api/zh/core-metrics.md

@@ -0,0 +1,67 @@
+---
+title: "Core 运行指标"
+source: contracts/agents-api/core-metrics.md
+source_hash: 08ac6802f0da2eb5138dc7706a995754a69e7c864e034cf412f75dcc4950c679
+---
+
+`GET /core/v1/metrics?range=1h|6h|24h|7d` 报告 Core 自身的健康状况：进程、执行队列与槽位、PostgreSQL 和后台任务。它要求 Core 密钥（[Core 管理 API](admin-api.md)）。
+
+`range` 是唯一参数，最多发送一次，默认为 `1h`。空值、重复或不支持的值以及任何其他参数均返回 400 `invalid_request`。Core 无法读取指标时，路由返回 503 `core_metrics_unavailable`。仅部分测量失败时，响应仍为 `200`，`service.status` 为 `degraded`，每个缺失值为 null。响应不会包含数据库或原生错误文本、凭据、响应体、资源 ID 或租户标签。
+
+## 时间与缺失数据 {#time-and-missing-data}
+
+响应中的 `range` 包含 UTC RFC 3339 格式的 `start` 和 `end`，以及 `resolution_seconds`。`end` 为最近的完整桶边界；区间为 `[start, end)`，因此不包含当前未完成的桶。
+
+| 范围 | 桶大小 | 桶数 |
+| --- | --- | --- |
+| 1h | 60 秒 | 60 |
+| 6h | 300 秒 | 72 |
+| 24h | 900 秒 | 96 |
+| 7d | 7200 秒 | 84 |
+
+- 执行槽位、已连接 daemon、连接池、Go 堆和 goroutine 在请求到达时读取。进程 CPU、RSS 与限制、队列数量和数据库大小来自 Core 每 30 秒采集的样本；超过 60 秒的样本不会作为当前值报告。
+- 每个序列桶报告其中观察到的最高值，而非每一个中间峰值。缺失观测和进程启动时不完整的首个桶为 null。
+- 样本和拒绝计数在内存中保留七天，另加两小时用于桶对齐。重启会丢失它们；Core 不回填。Turn 历史来自 PostgreSQL，重启后仍保留。
+- 如果区间开始早于该进程开始观察的时间，`execution.unavailable` 为 null；完整观察且没有拒绝的区间为零。
+- 空队列的数量为零，最老年龄为 null。没有已开始 Turn 或成功 ping 样本时，百分位数为 null，而非零延迟。周期 ping 的百分位数（p50、p95）采用线性插值；请求不会触发 ping。
+
+## 字段 {#fields}
+
+响应包含 `object: "core.metrics"`、`range`、`service`、`execution`、`database`、`jobs` 和 `process`。所有数值和 `service.execution_owner` 均可为 null；每个 `series` 始终列出范围内的所有完整桶。
+
+| 字段 | 含义 |
+| --- | --- |
+| `service.status` | 通常为 `running`；测量或任务失败、最新样本缺失或过期、执行所有权未知，或 Core 有执行槽位却未持有执行租约时为 `degraded`。沙箱重置由[部署](sandbox-deployment.md)报告，不在此处报告 |
+| `service.revision` | 构建时注入的完整源代码提交；未注入时为 null |
+| `service.started_at` | 进程初始化时间 |
+| `service.execution_owner` | 此进程是否持有执行 worker 的数据库租约 |
+| `execution.slots_in_use`, `execution.slots_total` | 执行 worker 的活动 Session 预留数量及容量：[`core.execution_concurrency`](../../../docs/zh/configuration.md#settings)，默认为 4。Environment 输入、Turn 和文件工作共享槽位；不统计原生 Harness 子进程。没有 worker 时两者均为 0 |
+| `execution.queued_turns`, `execution.in_progress_turns` | 处于相应状态的根 Turn，包括已删除 Session 的 Turn。不统计 Subagent Turn 和为准备中 Environment 预留的输入 |
+| `execution.waiting_for_daemon` | Session 设备未连接的排队 Turn；无网关时为 null |
+| `execution.oldest_queued_seconds` | 最早排队 Turn 自 `created_at` 起的年龄 |
+| `execution.connected_daemons` | 连接到 Core 网关的 Runtime daemon 数量；无网关时为 null |
+| `execution.queue_wait_ms` | 区间内开始的 Turn 的 `started_at - created_at` 的 p50 和 p95，使用 PostgreSQL `percentile_cont` |
+| `execution.interrupted` | 错误代码为 `execution_interrupted` 且 `completed_at` 在区间内的失败 Turn |
+| `execution.unavailable` | 使用错误代码 `execution_unavailable` 发送的 HTTP 响应，每个计一次。不统计其他 503 代码或流开始后的错误 |
+| `execution.series` | 每桶：`queued`、`in_progress` 和 `queue_wait_p95_ms` |
+| `database.ping_ms` | 周期连接池 ping 的 p50 和 p95，包括获取连接的时间 |
+| `database.pool` | 连接池的 `in_use`、`idle` 和 `max` 连接数量 |
+| `database.size_bytes` | `pg_database_size(current_database())`，不是主机磁盘使用量 |
+| `database.series` | 每桶：`ping_p95_ms` 和 `pool_in_use` |
+| `process.memory_bytes`, `process.goroutines` | Go `runtime.MemStats.Alloc`（已分配堆，不是 RSS）和 `runtime.NumGoroutine()` |
+| `process.cpu_cores` | 进程用户态与系统态 CPU 时间增量除以采样经过时间（Linux `getrusage(RUSAGE_SELF)`），不包括子进程。首个区间为 null；计数器缺失或重置、区间非正或间隔超过 60 秒时重建基线 |
+| `process.rss_bytes` | Linux `/proc/self/status` 的 `VmRSS`，单位为字节 |
+| `process.cpu_limit_cores` | 进程 cgroup v2 的 `cpu.max` 配额除以周期；配额为 `max` 或 cgroup 无配额接口时为 `GOMAXPROCS` |
+| `process.memory_limit_bytes` | 进程 cgroup 的 `memory.max`；为 `max` 时返回 null |
+| `process.series` | 每桶：`cpu_cores` 和 `rss_bytes` |
+
+Core 解析自身的 cgroup，包括嵌套与子树挂载，并报告该 cgroup 的限制，而非主机或祖先的限制。无法读取或格式错误的值为 null。非 Linux 构建报告 null CPU、RSS 和内存限制，CPU 限制为 `GOMAXPROCS`。仅缺失进程测量不会使服务变为 `degraded`。
+
+## 后台任务 {#background-jobs}
+
+`jobs` 列出 `scheduler`、`runtime_sampler`、`history_cleanup` 和 `audit_cleanup`。每项包含 `status`（首次运行前为 `unknown`，之后为 `ok`、`failing`，循环禁用或结束时为 `stopped`）、`last_run_at`（上次一轮结束时间）、`processed` 和 `failed`，后两者描述上次一轮。
+
+- scheduler 的 `processed` 统计上次轮询选中的 Turn 和 Environment 工作。
+- Runtime sampler 的 `processed` 和 `failed` 统计上次扫描成功观察和未能观察的目标。
+- 清理任务的 `processed` 统计删除的行数。
+- scheduler 和清理任务失败时，`processed` 为 null，`failed` 为 1；`failed` 不估算丢失行数或失败 Turn 数量。