docs: make Chinese README the default

2026-07-13 10:49:01 +00:00
parent 22ef2c3030
commit 25e728f4ae
1 changed files with 90 additions and 85 deletions
@@ -1,3 +1,9 @@
+<!-- WEHUB_ZH_README -->
+> [!NOTE]
+> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
+> [English](./README.en.md) · [原始项目](https://github.com/opensandbox-group/OpenSandbox) · [上游 README](https://github.com/opensandbox-group/OpenSandbox/blob/HEAD/README.md)  
+> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
+
 <div align="center">
  <img src="docs/public/images/logo.svg" alt="OpenSandbox logo" width="150" />

@@ -20,17 +26,17 @@
  <hr />
 </div>

-OpenSandbox is a **general-purpose sandbox platform** for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes for scenarios like Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training.
+OpenSandbox 是一个面向 AI 应用的**通用沙箱平台（general-purpose sandbox platform）**，提供多语言 SDK、统一的沙箱 API，以及适用于 Coding Agents、GUI Agents、Agent Evaluation、AI Code Execution、RL Training 等场景的 Docker/Kubernetes 运行时。

-## Features
+## 特性

- 🧩 **SDKs, CLI, and MCP**: Provides multi-language SDKs, the osb CLI, and MCP server integration for sandbox creation, command execution, and file operations. See [SDKs](#sdks), [CLI](#cli), and [MCP](#mcp).
- 📜 **Sandbox Protocol**: Defines sandbox lifecycle management APIs and sandbox execution APIs so you can extend custom sandbox runtimes. See [API specs](specs/README.md).
- 🚀 **Sandbox Runtime**: Built-in lifecycle management supporting Docker and high-performance Kubernetes runtime, enabling both local runs and large-scale distributed scheduling. See [Kubernetes runtime](./kubernetes).
- 🖥️ **Sandbox Environments**: Built-in Command, Filesystem, and Code Interpreter implementations. Examples cover Coding Agents (e.g., Claude Code), browser automation (Chrome, Playwright), and desktop environments (VNC, VS Code).
- 🚦 **Network Policy**: Unified ingress gateway with multiple routing strategies plus per-sandbox egress controls. See [Ingress Gateway](components/ingress) and [egress controls](components/egress).
- 🔑 **Credential Vault**: Secure credential injection for sandbox outbound requests without exposing real secrets to workloads. See [Credential Vault](docs/guides/credential-vault.md).
- 🏰 **Strong Isolation**: Supports secure container runtimes like gVisor, Kata Containers, and Firecracker microVM for enhanced isolation between sandbox workloads and the host. See [Secure Container Runtime Guide](docs/guides/secure-container.md) for details.
+- 🧩 **SDK、CLI 与 MCP**：提供多语言 SDK、osb CLI 以及 MCP 服务器集成，用于创建沙箱、执行命令和文件操作。请参阅 [SDK](#sdks)、[CLI](#cli) 和 [MCP](#mcp)。
+- 📜 **沙箱协议（Sandbox Protocol）**：定义沙箱生命周期管理 API 与沙箱执行 API，便于扩展自定义沙箱运行时。请参阅 [API 规范](specs/README.md)。
+- 🚀 **沙箱运行时（Sandbox Runtime）**：内置生命周期管理，支持 Docker 及高性能 Kubernetes 运行时，既可本地运行，也可大规模分布式调度。请参阅 [Kubernetes 运行时](./kubernetes)。
+- 🖥️ **沙箱环境（Sandbox Environments）**：内置 Command、Filesystem 与 Code Interpreter 实现。示例涵盖 Coding Agents（如 Claude Code）、浏览器自动化（Chrome、Playwright）以及桌面环境（VNC、VS Code）。
+- 🚦 **网络策略（Network Policy）**：统一的入口网关，支持多种路由策略，并提供按沙箱粒度的出口（egress）控制。请参阅 [Ingress Gateway](components/ingress) 和 [egress 控制](components/egress)。
+- 🔑 **凭证保险库（Credential Vault）**：为沙箱出站请求安全注入凭证，避免向工作负载暴露真实密钥。请参阅 [Credential Vault](docs/guides/credential-vault.md)。
+- 🏰 **强隔离（Strong Isolation）**：支持 gVisor、Kata Containers、Firecracker microVM 等安全容器运行时，增强沙箱工作负载与宿主机之间的隔离。详情请参阅 [安全容器运行时指南](docs/guides/secure-container.md)。

 ## SDKs

@@ -78,9 +84,9 @@ go get github.com/alibaba/OpenSandbox/sdks/sandbox/go

 ## CLI

-OpenSandbox also provides `osb`, a terminal CLI for the common sandbox workflow: create sandboxes, run commands, move files, inspect diagnostics, and manage runtime egress policy.
+OpenSandbox 还提供 `osb`，一款用于常见沙箱工作流的终端 CLI：创建沙箱、运行命令、移动文件、查看诊断信息以及管理运行时出口策略。

-Install:
+安装：

 ```bash
 pip install opensandbox-cli
@@ -88,7 +94,7 @@ pip install opensandbox-cli
 uv tool install opensandbox-cli
 ```

-Quick start:
+快速开始：

 ```bash
 osb config init
@@ -99,20 +105,20 @@ osb sandbox create --image python:3.12 --timeout 30m -o json
 osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"
 ```

-See the [CLI README](cli/README.md) for the full command reference.
+完整命令参考请参阅 [CLI README](cli/README.md)。

 ## MCP

-The OpenSandbox MCP server exposes sandbox creation, command execution, and text file operations to MCP-capable clients such as Claude Code and Cursor.
+OpenSandbox MCP 服务器向 Claude Code、Cursor 等支持 MCP 的客户端暴露沙箱创建、命令执行以及文本文件操作能力。

-Install and run:
+安装并运行：

 ```bash
 pip install opensandbox-mcp
 opensandbox-mcp --domain localhost:8080 --protocol http
 ```

-Minimal stdio config:
+最小 stdio 配置：

 ```json
 {
@@ -125,16 +131,16 @@ Minimal stdio config:
 }
 ```

-See the [MCP README](sdks/mcp/sandbox/python/README.md) for client-specific setup.
+各客户端的配置说明请参阅 [MCP README](sdks/mcp/sandbox/python/README.md)。

-## Getting Started
+## 快速入门

-Requirements:
+环境要求：

- Docker (required for local execution)
- Python 3.10+ (required for examples and local runtime)
+- Docker（本地执行必需）
+- Python 3.10+（示例与本地运行时必需）

-### Install and Configure the Sandbox Server
+### 安装并配置 Sandbox Server

 ```bash
 uvx opensandbox-server init-config ~/.sandbox.toml --example docker
@@ -145,15 +151,15 @@ uvx opensandbox-server
 # uvx opensandbox-server -h
 ```

-### Create a Code Interpreter and Execute Commands/Codes
+### 创建 Code Interpreter 并执行命令/代码

-Install the Code Interpreter SDK
+安装 Code Interpreter SDK

 ```bash
 uv pip install opensandbox-code-interpreter
 ```

-Create a sandbox and execute commands and codes.
+创建沙箱并执行命令与代码。

 ```python
 import asyncio
@@ -211,90 +217,89 @@ if __name__ == "__main__":
    asyncio.run(main())
 ```

-### More Examples
+### 更多示例

-OpenSandbox provides examples covering SDK usage, agent integrations, browser automation, and training workloads. All example code is located in the `examples/` directory.
+OpenSandbox 提供涵盖 SDK 用法、智能体集成、浏览器自动化与训练工作负载的示例。所有示例代码位于 `examples/` 目录。

-#### 🎯 Basic Examples
+#### 🎯 基础示例

- **[code-interpreter](docs/examples/code-interpreter.md)** - End-to-end Code Interpreter SDK workflow in a sandbox.
- **[aio-sandbox](docs/examples/aio-sandbox.md)** - All-in-One sandbox setup using the OpenSandbox SDK.
- **[agent-sandbox](docs/examples/agent-sandbox.md)** - Example integration for running OpenSandbox workloads on Kubernetes with [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox).
- **Volumes** — [Docker PVC / named volumes](docs/examples/docker-pvc-volume-mount.md), [Docker OSSFS](docs/examples/docker-ossfs-volume-mount.md), [Kubernetes PVC](docs/examples/kubernetes-pvc-volume-mount.md): persistent and shared storage patterns.
+- **[code-interpreter](docs/examples/code-interpreter.md)** - 在沙箱中端到端演示 Code Interpreter SDK 工作流。
+- **[aio-sandbox](docs/examples/aio-sandbox.md)** - 使用 OpenSandbox SDK 的一体化沙箱配置。
+- **[agent-sandbox](docs/examples/agent-sandbox.md)** - 在 Kubernetes 上运行 OpenSandbox 工作负载的集成示例，配合 [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox).
+- **Volumes** — [Docker PVC / named volumes](docs/examples/docker-pvc-volume-mount.md)、[Docker OSSFS](docs/examples/docker-ossfs-volume-mount.md)、[Kubernetes PVC](docs/examples/kubernetes-pvc-volume-mount.md)：持久化与共享存储方案。

-#### 🤖 Coding Agent Integrations
+#### 🤖 编码智能体（Coding Agent）集成

- **Coding CLIs** — [Claude Code](docs/examples/claude-code.md), [Gemini CLI](docs/examples/gemini-cli.md), [OpenAI Codex CLI](docs/examples/codex-cli.md), [Qwen Code](docs/examples/qwen-code.md), [Kimi CLI](docs/examples/kimi-cli.md): run each vendor CLI inside OpenSandbox.
- **[langgraph](docs/examples/langgraph.md)** - LangGraph state-machine workflow that creates/runs a sandbox job with fallback retry.
- **[google-adk](docs/examples/google-adk.md)** - Google ADK agent using OpenSandbox tools to write/read files and run commands.
- **[openclaw](docs/examples/openclaw.md)** - Launch an OpenClaw Gateway inside a sandbox.
+- **Coding CLI** — [Claude Code](docs/examples/claude-code.md)、[Gemini CLI](docs/examples/gemini-cli.md)、[OpenAI Codex CLI](docs/examples/codex-cli.md)、[Qwen Code](docs/examples/qwen-code.md)、[Kimi CLI](docs/examples/kimi-cli.md)：在 OpenSandbox 内运行各厂商 CLI。
+- **[langgraph](docs/examples/langgraph.md)** - 基于 LangGraph 的状态机工作流，用于创建/运行沙箱任务并支持失败重试（fallback retry）。
+- **[google-adk](docs/examples/google-adk.md)** - 使用 OpenSandbox 工具进行文件读写与命令执行的 Google ADK 智能体。
+- **[openclaw](docs/examples/openclaw.md)** - 在沙箱内启动 OpenClaw Gateway。

-#### 🌐 Browser and Desktop Environments
+#### 🌐 浏览器与桌面环境

- **[chrome](docs/examples/chrome.md)** - Chromium sandbox with VNC and DevTools access for automation and debugging.
- **[playwright](docs/examples/playwright.md)** - Playwright + Chromium headless scraping and testing example.
- **[desktop](docs/examples/desktop.md)** - Full desktop environment in a sandbox with VNC access.
- **[vscode](docs/examples/vscode.md)** - code-server (VS Code Web) running inside a sandbox for remote dev.
+- **[chrome](docs/examples/chrome.md)** - 配备 VNC 与 DevTools 访问的 Chromium 沙箱，用于自动化与调试。
+- **[playwright](docs/examples/playwright.md)** - Playwright + Chromium 无头（headless）爬取与测试示例。
+- **[desktop](docs/examples/desktop.md)** - 带 VNC 访问的沙箱完整桌面环境。
+- **[vscode](docs/examples/vscode.md)** - 在沙箱内运行 code-server（VS Code Web）以进行远程开发。

-#### 🧠 Training and Evaluation
+#### 🧠 训练与评估

- **[rl-training](docs/examples/rl-training.md)** - DQN CartPole training in a sandbox with checkpoints and summary output.
- **[harbor-evaluation](docs/examples/harbor-evaluation.md)** - Run a [Harbor](https://github.com/harbor-framework/harbor) agent evaluation on OpenSandbox, one sandbox per trial.
+- **[rl-training](docs/examples/rl-training.md)** - 在沙箱中进行 DQN CartPole 训练，含检查点与摘要输出。
+- **[harbor-evaluation](docs/examples/harbor-evaluation.md)** - 在 OpenSandbox 上运行 [Harbor](https://github.com/harbor-framework/harbor) 智能体评估，每次试验使用一个沙箱。

-For more details, please refer to the [examples documentation](docs/examples/index.md).
+更多详情请参阅[示例文档](docs/examples/index.md)。

-## Project Structure
+## 项目结构

-| Directory | Description                                                      |
+| 目录 | 说明 |
 |-----------|------------------------------------------------------------------|
-| [`sdks/`](sdks/) | Multi-language SDKs (Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET) |
-| [`specs/`](specs/README.md) | OpenAPI specs and lifecycle specifications                      |
-| [`server/`](server/README.md) | Python FastAPI sandbox lifecycle server                          |
-| [`cli/`](cli/README.md) | OpenSandbox command-line interface                               |
-| [`kubernetes/`](kubernetes/README.md) | Kubernetes deployment and examples                               |
-| [`components/execd/`](components/execd/README.md) | Sandbox execution daemon (commands and file operations)          |
-| [`components/ingress/`](components/ingress/README.md) | Sandbox traffic ingress proxy                                    |
-| [`components/egress/`](components/egress/README.md) | Sandbox network egress control                                   |
-| [`sandboxes/`](sandboxes/) | Runtime sandbox implementations                                   |
-| [`examples/`](examples/) | Runnable example code                                            |
-| [`docs/examples/`](docs/examples/index.md) | Example documentation and use cases                              |
-| [`oseps/`](oseps/README.md) | OpenSandbox Enhancement Proposals                                |
-| [`docs/`](docs/) | Architecture and design documentation                            |
-| [`tests/`](tests/) | Cross-component E2E tests                                        |
-| [`scripts/`](scripts/) | Development and maintenance scripts                              |
+| [`sdks/`](sdks/) | 多语言 SDK（Python、Java/Kotlin、TypeScript/JavaScript、C#/.NET） |
+| [`specs/`](specs/README.md) | OpenAPI 规范与生命周期（lifecycle）规范 |
+| [`server/`](server/README.md) | Python FastAPI 沙箱生命周期服务器 |
+| [`cli/`](cli/README.md) | OpenSandbox 命令行界面 |
+| [`kubernetes/`](kubernetes/README.md) | Kubernetes 部署与示例 |
+| [`components/execd/`](components/execd/README.md) | 沙箱执行守护进程（命令与文件操作） |
+| [`components/ingress/`](components/ingress/README.md) | 沙箱流量入口代理 |
+| [`components/egress/`](components/egress/README.md) | 沙箱网络出口控制 |
+| [`sandboxes/`](sandboxes/) | 运行时沙箱实现 |
+| [`examples/`](examples/) | 可运行的示例代码 |
+| [`docs/examples/`](docs/examples/index.md) | 示例文档与用例 |
+| [`oseps/`](oseps/README.md) | OpenSandbox Enhancement Proposals |
+| [`docs/`](docs/) | 架构与设计文档 |
+| [`tests/`](tests/) | 跨组件端到端（E2E）测试 |
+| [`scripts/`](scripts/) | 开发与维护脚本 |

-For detailed architecture, see [Architecture](docs/architecture/).
+有关详细架构，请参阅[架构](docs/architecture/)。

-## Documentation
+## 文档

- [Architecture](docs/architecture/) – Overall architecture & design philosophy
- [Credential Vault](docs/guides/credential-vault.md) - Credential Vault credential injection guide
- [Release Verification](docs/community/release-verification.md) - Release signing and artifact verification
+- [Architecture](docs/architecture/) – 整体架构与设计哲学
+- [Credential Vault](docs/guides/credential-vault.md) - Credential Vault 凭据注入指南
+- [Release Verification](docs/community/release-verification.md) - 发布签名与制品验证
 - [oseps/README.md](oseps/README.md) – OpenSandbox Enhancement Proposals
 - SDK
-  - Sandbox base SDK ([Java/Kotlin SDK](sdks/sandbox/kotlin/README.md), [Python SDK](sdks/sandbox/python/README.md), [JavaScript/TypeScript SDK](sdks/sandbox/javascript/README.md), [C#/.NET SDK](sdks/sandbox/csharp/README.md)), [Go SDK](sdks/sandbox/go/README.md) - includes sandbox lifecycle, command execution, file operations
-  - Code Interpreter SDK ([Java/Kotlin SDK](sdks/code-interpreter/kotlin/README.md), [Python SDK](sdks/code-interpreter/python/README.md), [JavaScript/TypeScript SDK](sdks/code-interpreter/javascript/README.md), [C#/.NET SDK](sdks/code-interpreter/csharp/README.md)) - code interpreter
- [cli/README.md](cli/README.md) - OpenSandbox CLI installation and command reference
- [sdks/mcp/sandbox/python/README.md](sdks/mcp/sandbox/python/README.md) - MCP server installation and client setup
- [specs/README.md](specs/README.md) - OpenAPI definitions for sandbox lifecycle API and sandbox execution API
- [server/README.md](server/README.md) - Sandbox server startup and configuration; supports Docker and Kubernetes runtimes
- [ROADMAP.md](ROADMAP.md) - Lightweight project roadmap and planning process
+  - 沙箱基础 SDK（[Java/Kotlin SDK](sdks/sandbox/kotlin/README.md)、[Python SDK](sdks/sandbox/python/README.md)、[JavaScript/TypeScript SDK](sdks/sandbox/javascript/README.md)、[C#/.NET SDK](sdks/sandbox/csharp/README.md)）、[Go SDK](sdks/sandbox/go/README.md) - 包含沙箱生命周期、命令执行、文件操作
+  - Code Interpreter SDK（[Java/Kotlin SDK](sdks/code-interpreter/kotlin/README.md)、[Python SDK](sdks/code-interpreter/python/README.md)、[JavaScript/TypeScript SDK](sdks/code-interpreter/javascript/README.md)、[C#/.NET SDK](sdks/code-interpreter/csharp/README.md)）- 代码解释器
+- [cli/README.md](cli/README.md) - OpenSandbox CLI 安装与命令参考
+- [sdks/mcp/sandbox/python/README.md](sdks/mcp/sandbox/python/README.md) - MCP 服务器安装与客户端配置
+- [specs/README.md](specs/README.md) - 沙箱生命周期 API 与沙箱执行 API 的 OpenAPI 定义
+- [server/README.md](server/README.md) - 沙箱服务器启动与配置；支持 Docker 与 Kubernetes 运行时
+- [ROADMAP.md](ROADMAP.md) - 轻量级项目路线图与规划流程

-## License
+## 许可证

-This project is open source under the [Apache 2.0 License](LICENSE).
+本项目在 [Apache 2.0 License](LICENSE) 下开源。

-## Roadmap
+## 路线图

-See [ROADMAP.md](ROADMAP.md) for the current project roadmap, planning scope,
-and how roadmap items are managed.
+当前项目路线图、规划范围以及路线图条目管理方式，请参阅 [ROADMAP.md](ROADMAP.md)。

-## Contact and Discussion
+## 联系与讨论

- Issues: Submit bugs, feature requests, or design discussions through GitHub Issues
- Discord: Join the [OpenSandbox Discord community](https://discord.gg/g7FuPs8YeD)
- DingTalk: Join the [OpenSandbox technical discussion group](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11)
+- Issues：通过 GitHub Issues 提交缺陷、功能请求或设计讨论
+- Discord：加入 [OpenSandbox Discord 社区](https://discord.gg/g7FuPs8YeD)
+- DingTalk：加入 [OpenSandbox 技术讨论群](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11)

-## Star History
+## Star 历史

 [![Star History Chart](https://api.star-history.com/svg?repos=opensandbox-group/OpenSandbox&type=date&legend=top-left)](https://www.star-history.com/#opensandbox-group/OpenSandbox&type=date&legend=top-left)