anycodes · Oct 24, 2026 · Oct 24, 2026 · Oct 24, 2026
diff --git a/.agents/evidence/verify/2026-10-24-package-installation-docs.md b/.agents/evidence/verify/2026-10-24-package-installation-docs.md
@@ -0,0 +1,27 @@
+# Verification: packaged Python installation guidance
+
+- Date: 2026-10-24
+- Change: [Issue #101](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/101), based on `8b77f789111a92713de51573cbb7e8ff7411e9c4`.
+- Result: PASS for local packaging and document changes; public a5 publication is not included in this result.
+- Packages: matching 0.3.1a5 client/server built locally on Python 3.12.
+
+## What was verified
+
+The actual wheel METADATA and source-archive README for both distributions contain corrected prerelease installation instructions and no old a2 pin. Client metadata requires exactly `agent-sandbox-server==0.3.1a5`. Apart from the version declarations, application runtime code is unchanged from the real proxy-tested a4 candidate.
+
+## Commands run and results
+
+- `python -m pytest client-sdk/tests/test_release_validation.py client-sdk/tests/test_packaging.py -q`: 9 passed in 3.85 seconds.
+- `python -m pytest server-sdk/tests/test_packaging.py -q`: 5 passed in 0.74 seconds.
+- `make build dist-check`: passed; both wheel/sdist pairs, twine, py.typed and combined clean installation/imports.
+- Inspected each wheel's METADATA with `zipfile` and `email`, and each sdist README with `tarfile`: matching a5 versions and dependency, corrected descriptions in all four artifacts.
+- `git diff --check` and repository health passed (106 PASS, 1 existing warning, 0 failures).
+- Initial [CI 40112322302](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40112322302) failed hygiene because the new guide creates and activates `.venv`, which matched the broad virtualenv assumption guard. Added narrowly anchored allowlist entries for that exact activation command in the two installation guides; the environment is explicitly created immediately above. The guard itself and credential rules are unchanged. Corrected `make hygiene` passed; current-head full CI and links remain required before merge.
+
+## Preserved publication history
+
+[a4 publication run 40111654824](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40111654824) was intentionally cancelled during validation after the stale packaged instructions were found. Its Build & Publish job ended cancelled with an empty steps list: no upload step executed. Both exact a4 PyPI JSON endpoints returned 404 at readback. The immutable `v0.3.1a4` tag remains at `8b77f789111a92713de51573cbb7e8ff7411e9c4`; release metadata clearly says it was not published to PyPI. Cancellation is not a test pass.
+
+## Real runtime evidence and limits
+
+[OpenSandbox T4 40110372103](https://github.com/Alibaba-Agent-Sandbox/awesome-providers/actions/runs/40110372103) verified the unchanged runtime through default/direct, portable/direct and default/proxy application paths with independent cleanup. This documentation/package correction creates no cloud resources and does not repeat that cloud test. Public a5 readback and the complete template matrix remain separate follow-up gates; no all-template or real-model claim is made here.
diff --git a/.agents/notes/proposed/process/2026-10-24-package-installation-docs.md b/.agents/notes/proposed/process/2026-10-24-package-installation-docs.md
@@ -0,0 +1,43 @@
+# Decision: Keep packaged installation guidance accurate
+
+Status: proposed
+
+## Problem
+
+The package READMEs and installation guide still instructed users to install 0.3.1a2 and described publication as pending. A new wheel would carry these obsolete instructions into its PyPI description even if the website were corrected.
+
+## Decision
+
+Use an explicit prerelease opt-in command in package and root READMEs, and a fixed current version in the bilingual installation guide. Start the guide with public package installation; put development checkout instructions later and move publication mechanics into CONTRIBUTING. Keep the exact client/server dependency.
+
+Stop the a4 publication before upload and preserve its tag. Package the corrected descriptions as matching 0.3.1a5 distributions; do not replace existing version contents. No application runtime behavior changes from a4.
+
+## API Design
+
+No public API change. The local client and server distributions remain versioned in lockstep.
+
+## Alternatives considered
+
+- Correct only the website: leaves obsolete commands in PyPI descriptions.
+- Move the a4 tag or upload modified artifacts under it: breaks the tag-to-artifact relationship.
+- Keep publication and verification state prose in the installation path: makes ordinary installation needlessly confusing.
+
+## Dependencies
+
+Existing package READMEs, release validator, build pipeline and exact same-version dependency.
+
+## Test Strategy
+
+Run package/release regressions and build/dist-check. Inspect the wheel metadata and source archive README for both distributions. Require full current-head CI, then verify public artifact digests, a fresh exact-version install, imports and pip check. Existing real proxy evidence applies to unchanged runtime code; final public-package template acceptance remains separately recorded.
+
+## Acceptance criteria
+
+- Both built descriptions give accurate installation commands.
+- Bilingual guides use the public pair with no stale candidate state prose.
+- a4 tag remains unchanged and no a4 upload occurred.
+- a5 public distribution readback and fresh installation succeed.
+
+## Evidence
+
+- [Issue #101](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/101)
+- [Local packaging and stopped upload](../../../evidence/verify/2026-10-24-package-installation-docs.md)
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -241,3 +241,9 @@ requirements still apply.
 须确认最新提交的运行、类型、测试和构建任务实际完成；仅 Markdown 检查通过
 不能证明产品验证完成。直接推送仍仅在 `main` 触发；真实组件证据和其余完成
 标准继续适用。
+
+## Publishing the Python pair
+
+Publish both distributions from a matching `v<version>` tag. The publication workflow runs the full reusable CI suite at that tag, builds and preserves one wheel/sdist pair per distribution, and verifies a combined clean installation. Manual runs default to dry-run. Before upload, existing PyPI files must match the candidate SHA-256; `skip-existing` is not sufficient verification. Upload server before client, then verify public digests and a fresh exact-version client installation with its automatic server dependency and `pip check`. Inspect the README embedded in both packages: it must not send users to an obsolete version. Preserve tags and artifacts; a content change uses a new version.
+
+两个发行包从匹配的 `v<version>` 标签发布，先执行完整 CI，再构建、保存并检查配套产物。手动运行默认 dry-run。上传前核对 PyPI 已有文件的 SHA-256，不能只依赖 `skip-existing`。先上传服务端，再上传客户端；随后检查公开摘要、新环境精确版本安装、自动服务端依赖和 `pip check`。检查双包内的 README，避免把用户导向旧版本。保留既有标签与产物，内容变更使用新版本号。
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 - Native `ProviderSandbox.commands.run/start/stream(user=...)` now selects the requested envd OS account per request, preserving gateway credentials and concurrent/default identities. Prepare the matching client/server 0.3.1a2 alpha pair; publication is separate. / 原生进程调用按请求选择指定操作系统账号，保留网关凭据以及并发、默认身份；准备配套 0.3.1a2 alpha 双包，发布独立执行。
 - Clarify provider-native application clients, published alpha installation, separate gateway/application credentials, and explicit readiness checks after cloud-steps submission in bilingual guides.
 
+## [0.3.1a5] - 2026-10-24
+
+### Fixed
+
+- Correct package README installation commands and simplify bilingual installation guides. Both distributions include the application proxy fix from the a4 source candidate; its PyPI upload was stopped before publication to correct stale package metadata. / 修正随包发布的安装说明，简化中英文安装指南。双包包含 a4 源码候选的应用代理修复；a4 在上传前停止，以修正陈旧的包说明。
+
 ## [0.3.1a4] - 2026-10-24
 
 ### Fixed

diff --git a/README.md b/README.md
@@ -63,34 +63,16 @@ Provider management operations are available through `agent_sandbox.providers.co
 
 ## Installation
 
-The [installation guide](docs/en/guide/install-python.md) provides a tested 0.3.0 Git source pair and explicit opt-in instructions for the 0.3.1a2 alpha once its publication is verified. Both source URLs must use the same commit.
+Use Python 3.10 or newer in a virtual environment. The client installs its matching server dependency automatically. See the [installation guide](docs/en/guide/install-python.md) for a pinned version, optional extras and development setup.
 
 ```bash
-# Client and matching runtime
-python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk"
-
-# Optional extras (MCP + fast JSON + sessions + declarative)
-python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk"
-
-# Container-side runtime (install this inside your sandbox image)
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk"
-pip install playwright                       # only if you enable the browser capability group
-
-# Development (from the repository root; includes test & lint tooling for both packages)
-pip install -e ./server-sdk -e "./client-sdk[dev]"
+python -m pip install --upgrade --pre agent-sandbox-client
+python -m pip check
 ```
 
-Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project. This client is `agent-sandbox-client`.
+`--pre` opts into alpha releases. The command-line tool is installed separately: see [the abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox).
 
-`agent-sandbox-client` depends on `agent-sandbox-server` of the same version, so installing the [paired sources](docs/en/guide/install-python.md) also provides `agent_sandbox.server` (needed locally by the `@sandbox` decorator's server proxy).
-
-The `abx` CLI is no longer part of the Python package (there is no `[cli]` extra and no `abx`
-console script); it is distributed from the [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository
-(see [Related: the abx CLI](#related-the-abx-cli)).
+Do not run `pip install agent-sandbox`; that PyPI name belongs to an unrelated project.
 
 ## Quick Start
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -61,33 +61,16 @@ Node.js 项目，位于 [`agent-sandbox`](https://github.com/alibaba-agent-sandb
 
 ## 安装
 
-[安装指南](docs/zh/guide/install-python.md)提供已验证的0.3.0 Git 配套源码，以及0.3.1a2 alpha 在公开发布验证完成后的显式安装方式。两个源码 URL 必须固定同一提交。
+使用 Python 3.10 或更高版本及虚拟环境。客户端会自动安装同版本的服务端依赖。固定版本、可选依赖及开发安装见[安装指南](docs/zh/guide/install-python.md)。
 
 ```bash
-# 仅核心客户端 SDK
-python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk"
-
-# 完整安装（MCP + 快速 JSON + 会话 + 声明式 + server）
-python -m pip install \
-  "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" \
-  "agent-sandbox-client[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk"
-
-# 容器侧运行时（安装到你的沙箱镜像内）
-python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk"
-pip install playwright                       # 仅在启用 browser 能力组时需要
-
-# 开发环境（在仓库根目录执行；含两个包的测试与 lint 工具）
-pip install -e ./server-sdk -e "./client-sdk[dev]"
+python -m pip install --upgrade --pre agent-sandbox-client
+python -m pip check
 ```
 
-不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。安装本客户端请使用 [配套源码安装指南](docs/zh/guide/install-python.md)。
+`--pre` 表示选择 alpha 预发布版本。命令行工具独立安装，见 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox)。
 
-`agent-sandbox-client` 依赖同版本的 `agent-sandbox-server`，因此 [配套源码安装指南](docs/zh/guide/install-python.md) 同样会提供 `agent_sandbox.server`（`@sandbox` 装饰器的 server 代理在本地需要它）。
-
-`abx` CLI 不再属于 Python 包（不再有 `[cli]` extra，也没有 `abx` 控制台脚本），由
-[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库分发（见[相关：abx CLI](#相关abx-cli)）。
+不要执行 `pip install agent-sandbox`；该 PyPI 名称属于另一个无关项目。
 
 ## 快速开始
 

diff --git a/client-sdk/README.md b/client-sdk/README.md
@@ -2,7 +2,7 @@
 
 Provider extensions use [explicit template workflows](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/template-workflows.md) ([中文](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/zh/guide/template-workflows.md)); application HTTP, stateless execution and context operations are independent.
 
-This package is the opt-in **0.3.1a2 alpha** candidate. Use its exact PyPI version after verified publication; before that, use the [tested paired source recipe](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md). Alpha publication does not establish every provider or template as production-ready.
+Install the current alpha with `--pre`; use the [installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md) for a pinned version and environment setup.
 
 **Client SDK.** The product is Agent Sandbox. The import path is `agent_sandbox`. This package runs on your machine: create a sandbox, use it, and kill it. The HTTP service inside the image is [`agent-sandbox-server`](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/server-sdk/README.md). Guide: [Client SDK](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/client-sdk.md).
 
@@ -19,9 +19,9 @@ The command-line tool (`abx`) is a separate Node.js project that lives in the [`
 ## Install
 
 ```bash
-python -m pip install 'agent-sandbox-client==0.3.1a2'
+python -m pip install --upgrade --pre agent-sandbox-client
 # Optional extras:
-python -m pip install 'agent-sandbox-client[all]==0.3.1a2'
+python -m pip install --upgrade --pre 'agent-sandbox-client[all]'
 python -m pip check
 ```
 

diff --git a/client-sdk/pyproject.toml b/client-sdk/pyproject.toml
@@ -44,7 +44,7 @@ dependencies = [
     "tomli>=2.0; python_version < '3.11'",
     # The client uses the matching local server runtime for its server/declarative helpers.
     # Keep the required distribution version equal to ``_version.py``.
-    "agent-sandbox-server==0.3.1a4",
+    "agent-sandbox-server==0.3.1a5",
 ]
 
 [project.optional-dependencies]

diff --git a/client-sdk/src/agent_sandbox/_version.py b/client-sdk/src/agent_sandbox/_version.py
@@ -1 +1 @@
-__version__ = "0.3.1a4"
+__version__ = "0.3.1a5"