Chore/doc 1.10

docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.10.x/References/Python SDK References/python_sdk.md

@@ -34,7 +34,12 @@ async def run_sandbox():
     Default admin server port is 8080.
     """
     # Create sandbox configuration
-    config = SandboxConfig(image="python:3.11", memory="8g", cpus=2.0)
+    config = SandboxConfig(
+        image="python:3.11",
+        memory="8g",
+        cpus=2.0,
+        disk="20g",
+    )
 
     # Create sandbox instance
     sandbox = Sandbox(config)
@@ -85,15 +90,83 @@ await sandbox_group.stop()
 
 ### 2.3 配置示例
 
+可通过 `memory`、`cpus` 和 `disk` 指定沙箱资源。`disk` 接受 `"20g"` 这样的
+容量字符串，用于限制沙箱根文件系统和日志目录的磁盘配额。
+
 ```python
 config = SandboxConfig(
     image="python:3.11",
+    memory="8g",
+    cpus=2.0,
+    disk="20g",
     auto_clear_seconds=60 * 20,
     experiment_id="test",
 )
 ```
 
-### 2.4 沙箱加速配置
+### 2.4 归档并重启沙箱
+
+当 stopped 沙箱在本地容器被清理后仍需要恢复时，可以使用 `archive()`。
+ROCK 会将容器文件系统保存为归档镜像，并将沙箱日志目录上传到远端存储。
+对 archived 沙箱调用 `restart()` 时，ROCK 会恢复这些内容并启动新容器。
+
+状态流转如下：
+
+```text
+running --stop--> stopped --archive--> archiving --success--> archived
+                                                        |
+                                                        +--restart--> pending --alive--> running
+
+archiving --failure/timeout--> stopped
+pending（恢复中）--failure/timeout--> archived
+```
+
+`archive()` 只负责发起异步归档任务。只有当
+`get_status(include_all_states=True)` 返回 `state == "archived"` 时，
+才表示远端归档已完成，可用于恢复。
+
+```python
+import asyncio
+
+
+async def wait_until_archived(sandbox, timeout=1800):
+    deadline = asyncio.get_running_loop().time() + timeout
+    while True:
+        status = await sandbox.get_status(include_all_states=True)
+        if status.state == "archived":
+            return
+        if status.state == "stopped":
+            raise RuntimeError("归档失败或超时，可以重试")
+        if asyncio.get_running_loop().time() >= deadline:
+            raise TimeoutError(f"等待归档超时，当前状态: {status.state}")
+        await asyncio.sleep(3)
+
+
+# 运行此示例前，sandbox 应处于 running 状态。
+await sandbox.arun("echo 'keep me' > /tmp/archive-marker.txt")
+await sandbox.stop()
+
+# archive() 只能对 stopped 沙箱调用。
+await sandbox.archive()
+await wait_until_archived(sandbox)
+
+# restart() 会识别 archived 状态并自动恢复沙箱。
+await sandbox.restart()
+result = await sandbox.arun("cat /tmp/archive-marker.txt")
+assert "keep me" in result.output
+```
+
+如果要在另一个进程中恢复，请使用相同的服务地址、集群和认证信息创建
+`Sandbox`，先调用 `await sandbox.attach(sandbox_id)`，再调用
+`await sandbox.restart()`。应将 `startup_timeout` 设置得足够长，以覆盖归档恢复、
+镜像拉取和容器启动的耗时。
+
+:::warning
+ROCK Admin 服务必须已启用并配置归档存储。仍需要归档时请勿调用 `delete()`：
+归档存储已配置时，删除 archived 沙箱也会删除对应的归档内容。
+:::
+
+### 2.5 沙箱加速配置
 
 ROCK 提供沙箱网络加速功能，支持配置 APT、PIP 和 GitHub 镜像源，提升受限网络环境下的包下载速度。
 
@@ -262,4 +335,4 @@ if __name__ == "__main__":
 - [快速开始指南](../../Getting%20Started/quickstart.md) - 了解如何快速开始使用 ROCK SDK
 - [API 文档](../api.md) - 查看 SDK 封装的底层 API 接口
 - [配置指南](../../User%20Guides/configuration.md) - 了解 SDK 相关的配置选项
-- [安装指南](../../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置
+- [安装指南](../../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置

docs/versioned_docs/version-1.10.x/References/Python SDK References/python_sdk.md

@@ -34,7 +34,12 @@ async def run_sandbox():
     Default admin server port is 8080.
     """
     # Create sandbox configuration
-    config = SandboxConfig(image="python:3.11", memory="8g", cpus=2.0)
+    config = SandboxConfig(
+        image="python:3.11",
+        memory="8g",
+        cpus=2.0,
+        disk="20g",
+    )
 
     # Create sandbox instance
     sandbox = Sandbox(config)
@@ -85,15 +90,86 @@ await sandbox_group.stop()
 
 ### 2.3 Configuration Example
 
+Use `memory`, `cpus`, and `disk` to request the sandbox resources. `disk` accepts a
+size string such as `"20g"` and sets the quota for both the sandbox root filesystem
+and its log directory.
+
 ```python
 config = SandboxConfig(
     image="python:3.11",
+    memory="8g",
+    cpus=2.0,
+    disk="20g",
     auto_clear_seconds=60 * 20,
     experiment_id="test",
 )
 ```
 
-### 2.4 Sandbox Speedup Configuration
+### 2.4 Archive and Restart a Sandbox
+
+Use `archive()` when a stopped sandbox must remain recoverable after its local
+container is removed. ROCK saves the container filesystem as an archive image and
+uploads the sandbox log directory to remote storage. Calling `restart()` on the
+archived sandbox restores that content and starts a new container.
+
+The lifecycle is:
+
+```text
+running --stop--> stopped --archive--> archiving --success--> archived
+                                                        |
+                                                        +--restart--> pending --alive--> running
+
+archiving --failure/timeout--> stopped
+pending (during restore) --failure/timeout--> archived
+```
+
+`archive()` only starts the asynchronous archive task. The archive is ready for
+remote recovery only after `get_status(include_all_states=True)` returns
+`state == "archived"`.
+
+```python
+import asyncio
+
+
+async def wait_until_archived(sandbox, timeout=1800):
+    deadline = asyncio.get_running_loop().time() + timeout
+    while True:
+        status = await sandbox.get_status(include_all_states=True)
+        if status.state == "archived":
+            return
+        if status.state == "stopped":
+            raise RuntimeError("Archive failed or timed out; it can be retried")
+        if asyncio.get_running_loop().time() >= deadline:
+            raise TimeoutError(f"Timed out waiting for archive; current state: {status.state}")
+        await asyncio.sleep(3)
+
+
+# The sandbox must be running before this example starts.
+await sandbox.arun("echo 'keep me' > /tmp/archive-marker.txt")
+await sandbox.stop()
+
+# archive() is only valid for a stopped sandbox.
+await sandbox.archive()
+await wait_until_archived(sandbox)
+
+# restart() detects the archived state and restores the sandbox automatically.
+await sandbox.restart()
+result = await sandbox.arun("cat /tmp/archive-marker.txt")
+assert "keep me" in result.output
+```
+
+To restore in another process, create a `Sandbox` with the same endpoint, cluster,
+and credentials, call `await sandbox.attach(sandbox_id)`, and then call
+`await sandbox.restart()`. Set `startup_timeout` high enough to cover image restore,
+pull, and startup time.
+
+:::warning
+The ROCK Admin service must enable and configure archive storage. Do not call
+`delete()` while the archive is still needed: deleting an archived sandbox also
+removes its archive artifacts when archive storage is configured.
+:::
+
+### 2.5 Sandbox Speedup Configuration
 
 ROCK provides sandbox network acceleration capabilities, supporting configuration of APT, PIP, and GitHub mirror sources to improve package download speeds in restricted network environments.
 
@@ -262,4 +338,4 @@ if __name__ == "__main__":
 - [Quick Start Guide](../../Getting%20Started/quickstart.md) - Learn how to quickly get started with the ROCK SDK
 - [API Documentation](../api.md) - View the underlying API interfaces encapsulated by the SDK
 - [Configuration Guide](../../User%20Guides/configuration.md) - Learn about SDK-related configuration options
-- [Installation Guide](../../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup
+- [Installation Guide](../../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup