diff --git a/specs/README.md b/specs/README.md
index fea60173..64c992c3 100644
--- a/specs/README.md
+++ b/specs/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README_zh.md)
 
-This directory contains OpenAPI specification documents for the OpenSandbox project, defining the complete API interfaces and data models.
+This directory contains OpenAPI specification documents for the OpenSandbox project, defining the complete API interfaces and data models. Use the server base URLs defined in each spec (for example, `http://localhost:8080/v1` for the lifecycle API and `http://localhost:8080` for execd) when constructing requests.
 
 ## Specification Files
 
@@ -10,26 +10,26 @@ This directory contains OpenAPI specification documents for the OpenSandbox proj
 
 **Sandbox Lifecycle Management API**
 
-Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments.
+Defines the complete lifecycle interfaces for creating, managing, and destroying sandbox environments directly from container images.
 
 **Core Features:**
-- **Sandbox Management**: Create, list, query, and delete sandbox instances
+- **Sandbox Management**: Create, list, query, and delete sandbox instances with metadata filters and pagination
 - **State Control**: Pause and resume sandbox execution
-- **Lifecycle States**: Support multiple state transitions (Pending → Running → Pausing → Paused → Stopping → Terminated)
-- **Resource Configuration**: CPU, memory, GPU, and other resource limit configurations
-- **Image Support**: Create sandboxes directly from container images, supporting both public and private registries
-- **Timeout Management**: Automatic expiration and manual renewal capabilities
+- **Lifecycle States**: Supports transitions across Pending → Running → Pausing → Paused → Stopping → Terminated, and error handling with `Failed`
+- **Resource & Runtime Configuration**: Specify CPU/memory/GPU resource limits, required `entrypoint`, environment variables, and opaque `extensions`
+- **Image Support**: Create sandboxes from public or private registries, including registry auth
+- **Timeout Management**: Mandatory `timeout` on creation with explicit renewal via API
 - **Endpoint Access**: Retrieve public access endpoints for services running inside sandboxes
 
-**Main Endpoints:**
-- `POST /v1/sandboxes` - Create sandbox
-- `GET /v1/sandboxes` - List sandboxes (with filtering and pagination)
-- `GET /v1/sandboxes/{sandboxId}` - Get sandbox details
-- `DELETE /v1/sandboxes/{sandboxId}` - Delete sandbox
-- `POST /v1/sandboxes/{sandboxId}/pause` - Pause sandbox
-- `POST /v1/sandboxes/{sandboxId}/resume` - Resume sandbox
-- `POST /v1/sandboxes/{sandboxId}/renew-expiration` - Renew sandbox expiration
-- `GET /v1/sandboxes/{sandboxId}/endpoints/{port}` - Get access endpoint
+**Main Endpoints (base path `/v1`):**
+- `POST /sandboxes` - Create a sandbox from an image with timeout and resource limits
+- `GET /sandboxes` - List sandboxes with state/metadata filters and pagination
+- `GET /sandboxes/{sandboxId}` - Get full sandbox details (including image and entrypoint)
+- `DELETE /sandboxes/{sandboxId}` - Delete a sandbox
+- `POST /sandboxes/{sandboxId}/pause` - Pause a sandbox (asynchronous)
+- `POST /sandboxes/{sandboxId}/resume` - Resume a paused sandbox
+- `POST /sandboxes/{sandboxId}/renew-expiration` - Renew sandbox expiration (TTL)
+- `GET /sandboxes/{sandboxId}/endpoints/{port}` - Get an access endpoint for a service port
 
 **Authentication:**
 - HTTP Header: `OPEN-SANDBOX-API-KEY: your-api-key`
@@ -39,15 +39,15 @@ Defines the complete lifecycle interfaces for creating, managing, and destroying
 
 **Code Execution API Inside Sandbox**
 
-Defines interfaces for executing code, commands, and file operations within sandbox environments, providing complete code interpreter and filesystem management capabilities.
+Defines interfaces for executing code, commands, and file operations within sandbox environments, providing complete code interpreter and filesystem management capabilities. All endpoints require the `X-EXECD-ACCESS-TOKEN` header.
 
 **Core Features:**
-- **Code Execution**: Stateful code execution supporting Python, JavaScript, and other languages
-- **Command Execution**: Shell command execution with foreground/background modes
+- **Code Execution**: Stateful code execution supporting Python, JavaScript, and other languages with context lifecycle management
+- **Command Execution**: Shell command execution with foreground/background modes and polling endpoints for status/output
 - **File Operations**: Complete CRUD operations for files and directories
 - **Real-time Streaming**: Real-time output streaming via SSE (Server-Sent Events)
 - **System Monitoring**: Real-time monitoring of CPU and memory metrics
-- **Access Control**: Token-based API authentication
+- **Access Control**: Token-based API authentication via `X-EXECD-ACCESS-TOKEN`
 
 **Main Endpoint Categories:**
 
@@ -55,27 +55,32 @@ Defines interfaces for executing code, commands, and file operations within sand
 - `GET /ping` - Service health check
 
 **Code Interpreter:**
-- `POST /code/context` - Create code execution context
-- `POST /code` - Execute code in context (streaming output)
+- `GET /code/contexts` - List active code execution contexts (filterable by language)
+- `DELETE /code/contexts` - Delete all contexts for a language
+- `DELETE /code/contexts/{context_id}` - Delete a specific context
+- `POST /code/context` - Create a code execution context
+- `POST /code` - Execute code in a context (streaming output)
 - `DELETE /code` - Interrupt code execution
 
 **Command Execution:**
 - `POST /command` - Execute shell command (streaming output)
 - `DELETE /command` - Interrupt command execution
+- `GET /command/status/{session}` - Get foreground/background command status
+- `GET /command/output/{session}` - Fetch accumulated stdout/stderr for a command
 
 **Filesystem:**
-- `GET /files/info` - Get file metadata
-- `DELETE /files` - Delete files
+- `GET /files/info` - Get metadata for files
+- `DELETE /files` - Delete files (not directories)
 - `POST /files/permissions` - Change file permissions
 - `POST /files/mv` - Move/rename files
 - `GET /files/search` - Search files (supports glob patterns)
 - `POST /files/replace` - Batch replace file content
-- `POST /files/upload` - Upload files
+- `POST /files/upload` - Upload files (multipart)
 - `GET /files/download` - Download files (supports range requests)
 
 **Directory Operations:**
-- `POST /directories` - Create directories
-- `DELETE /directories` - Delete directories
+- `POST /directories` - Create directories with permissions (mkdir -p semantics)
+- `DELETE /directories` - Recursively delete directories
 
 **System Metrics:**
 - `GET /metrics` - Get system resource metrics
diff --git a/specs/README_zh.md b/specs/README_zh.md
index bb9f6ab4..59b2f87f 100644
--- a/specs/README_zh.md
+++ b/specs/README_zh.md
@@ -2,7 +2,7 @@
 
 中文 | [English](README.md)
 
-本目录包含 OpenSandbox 项目的 OpenAPI 规范文档，定义了完整的 API 接口和数据模型。
+本目录包含 OpenSandbox 项目的 OpenAPI 规范文档，定义了完整的 API 接口和数据模型。发起请求时请使用各规范中定义的服务器地址（例如生命周期 API 的 `http://localhost:8080/v1`，execd 的 `http://localhost:8080`）。
 
 ## 规范文件
 
@@ -10,26 +10,26 @@
 
 **沙箱生命周期管理 API**
 
-定义了沙箱环境的创建、管理和销毁的完整生命周期接口。
+定义了沙箱环境的创建、管理和销毁的完整生命周期接口，并可直接从容器镜像启动。
 
 **核心功能：**
-- **沙箱管理**：创建、列表、查询、删除沙箱实例
+- **沙箱管理**：创建、列表、查询、删除沙箱实例，支持元数据过滤与分页
 - **状态控制**：暂停 (Pause)、恢复 (Resume) 沙箱执行
-- **生命周期**：支持多种状态转换（Pending → Running → Pausing → Paused → Stopping → Terminated）
-- **资源配置**：CPU、内存、GPU 等资源限制配置
-- **镜像支持**：从容器镜像直接创建沙箱，支持公共和私有镜像仓库
-- **超时管理**：自动过期和手动续期功能
+- **生命周期**：支持 Pending → Running → Pausing → Paused → Stopping → Terminated，并包含错误态 `Failed`
+- **资源与运行时配置**：指定 CPU/内存/GPU 资源限制、必填 `entrypoint`、环境变量，以及自定义 `extensions`
+- **镜像支持**：从公共或私有镜像仓库创建沙箱，支持私有仓库认证
+- **超时管理**：创建时必填 `timeout`，并可通过 API 续期
 - **端点访问**：获取沙箱内服务的公共访问端点
 
-**主要端点：**
-- `POST /v1/sandboxes` - 创建沙箱
-- `GET /v1/sandboxes` - 列出沙箱（支持过滤和分页）
-- `GET /v1/sandboxes/{sandboxId}` - 获取沙箱详情
-- `DELETE /v1/sandboxes/{sandboxId}` - 删除沙箱
-- `POST /v1/sandboxes/{sandboxId}/pause` - 暂停沙箱
-- `POST /v1/sandboxes/{sandboxId}/resume` - 恢复沙箱
-- `POST /v1/sandboxes/{sandboxId}/renew-expiration` - 续期沙箱
-- `GET /v1/sandboxes/{sandboxId}/endpoints/{port}` - 获取访问端点
+**主要端点（基础路径 `/v1`）：**
+- `POST /sandboxes` - 从镜像创建沙箱，设置超时与资源限制
+- `GET /sandboxes` - 列出沙箱，支持状态/元数据过滤与分页
+- `GET /sandboxes/{sandboxId}` - 获取完整沙箱详情（包含镜像与 entrypoint）
+- `DELETE /sandboxes/{sandboxId}` - 删除沙箱
+- `POST /sandboxes/{sandboxId}/pause` - 异步暂停沙箱
+- `POST /sandboxes/{sandboxId}/resume` - 恢复已暂停的沙箱
+- `POST /sandboxes/{sandboxId}/renew-expiration` - 续期沙箱 TTL
+- `GET /sandboxes/{sandboxId}/endpoints/{port}` - 获取指定端口的访问端点
 
 **认证方式：**
 - HTTP Header: `OPEN-SANDBOX-API-KEY: your-api-key`
@@ -39,15 +39,15 @@
 
 **沙箱内代码执行 API**
 
-定义了在沙箱环境内执行代码、命令和文件操作的接口，提供完整的代码解释器和文件系统管理能力。
+定义了在沙箱环境内执行代码、命令和文件操作的接口，提供完整的代码解释器和文件系统管理能力。所有端点需要 `X-EXECD-ACCESS-TOKEN` 认证头。
 
 **核心功能：**
-- **代码执行**：支持 Python、JavaScript 等多语言的有状态代码执行
-- **命令执行**：Shell 命令执行，支持前台/后台模式
+- **代码执行**：支持 Python、JavaScript 等多语言的有状态代码执行，并提供上下文生命周期管理
+- **命令执行**：Shell 命令执行，支持前台/后台模式，并可通过轮询端点查看状态和输出
 - **文件操作**：完整的文件和目录 CRUD 操作（创建、读取、更新、删除）
 - **实时流式输出**：基于 SSE (Server-Sent Events) 的实时输出流
 - **系统监控**：CPU 和内存指标的实时监控
-- **访问控制**：基于 Token 的 API 认证
+- **访问控制**：通过 `X-EXECD-ACCESS-TOKEN` 进行 Token 认证
 
 **主要端点分类：**
 
@@ -55,6 +55,9 @@
 - `GET /ping` - 服务健康检查
 
 **代码解释器：**
+- `GET /code/contexts` - 列出活跃的代码执行上下文（可按语言过滤）
+- `DELETE /code/contexts` - 按语言批量删除上下文
+- `DELETE /code/contexts/{context_id}` - 删除指定上下文
 - `POST /code/context` - 创建代码执行上下文
 - `POST /code` - 在上下文中执行代码（流式输出）
 - `DELETE /code` - 中断代码执行
@@ -62,20 +65,22 @@
 **命令执行：**
 - `POST /command` - 执行 Shell 命令（流式输出）
 - `DELETE /command` - 中断命令执行
+- `GET /command/status/{session}` - 查询前台/后台命令状态
+- `GET /command/output/{session}` - 获取命令的累积 stdout/stderr
 
 **文件系统：**
 - `GET /files/info` - 获取文件元数据
-- `DELETE /files` - 删除文件
+- `DELETE /files` - 删除文件（不包含目录）
 - `POST /files/permissions` - 修改文件权限
 - `POST /files/mv` - 移动/重命名文件
 - `GET /files/search` - 搜索文件（支持 glob 模式）
 - `POST /files/replace` - 批量替换文件内容
-- `POST /files/upload` - 上传文件
+- `POST /files/upload` - 上传文件（multipart）
 - `GET /files/download` - 下载文件（支持断点续传）
 
 **目录操作：**
-- `POST /directories` - 创建目录
-- `DELETE /directories` - 删除目录
+- `POST /directories` - 按权限配置创建目录（mkdir -p 语义）
+- `DELETE /directories` - 递归删除目录
 
 **系统指标：**
 - `GET /metrics` - 获取系统资源指标