diff --git a/README.md b/README.md
index cddcb85..22a4bf6 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,35 @@ contracts.
 - `runtime/`: planning and execution orchestration.
 - `api/`: REST/MCP transport adapters.
 - `storage/`: timeline, task, and device configuration persistence.
+- `packages/cloud-platform/`: cloud scheduling, device pooling, plugins, and
+  the Python cloud SDK as the `device-cloud-platform` workspace member.
+
+## Python Workspace
+
+The repository uses a uv workspace with one committed lockfile. From the
+repository root, synchronize every Python member with:
+
+```bash
+uv sync --locked --all-packages
+```
+
+Run the complete local test suite in a workspace environment:
+
+```bash
+uv run --all-packages pytest -m "not integration"
+```
+
+Select one member when running package-specific commands:
+
+```bash
+uv run --package device-agent-runtime python -c "import runtime"
+uv run --package device-cloud-platform python -c "import cloud"
+uv build --package device-agent-runtime
+uv build --package device-cloud-platform
+```
+
+The Vue/Vite application under `console/` remains an independent npm project;
+uv does not install or modify its JavaScript dependencies.
 
 ## Project Direction
 
diff --git a/docs/MACOS_IPHONE_SETUP.md b/docs/MACOS_IPHONE_SETUP.md
index a3e4f6c..77fe0f3 100644
--- a/docs/MACOS_IPHONE_SETUP.md
+++ b/docs/MACOS_IPHONE_SETUP.md
@@ -117,17 +117,22 @@ npm --version
 确认 Node.js/npm 满足上面的版本范围。Apple Silicon 和 Intel Mac 都应使用本机
 架构的 Homebrew，不要在 Rosetta shell 与原生 shell 之间混用 Python/Node。
 
-### 4.2 创建 Python 环境
+### 4.2 同步 Python workspace
 
 在仓库根目录执行：
 
 ```bash
 uv python install 3.14
-uv venv --python 3.14
-source .venv/bin/activate
-python --version
-uv pip install -e .
-uv pip install "pytest>=8.3.0"
+uv sync --locked --all-packages
+uv run --package device-agent-runtime python --version
+uv run --package device-cloud-platform python -c "import cloud"
+```
+
+uv 会在仓库根目录管理 `.venv`，共享 `uv.lock` 同时锁定本地 Runtime 和 cloud
+platform 两个 Python member。运行完整的非实机测试使用：
+
+```bash
+uv run --all-packages pytest -m "not integration"
 ```
 
 如果 Apple Silicon 上安装 `paddleocr` 或其底层推理依赖失败，可以先安装不带 OCR
@@ -257,7 +262,7 @@ PY
 验证通过后，可以运行仓库的实机 integration test：
 
 ```bash
-pytest -m integration tests/test_wda_integration.py -v
+uv run --package device-agent-runtime pytest -m integration tests/test_wda_integration.py -v
 ```
 
 该测试只从环境变量读取 server URL、UDID 和 device name，不传签名 capabilities，
diff --git a/openspec/changes/uv-workspace-packaging/tasks.md b/openspec/changes/uv-workspace-packaging/tasks.md
index ce01415..31d9a0f 100644
--- a/openspec/changes/uv-workspace-packaging/tasks.md
+++ b/openspec/changes/uv-workspace-packaging/tasks.md
@@ -19,7 +19,7 @@
 - [x] 3.2 Verify clean `uv sync --locked` and lock consistency checks from the workspace root.
   - Verified with a fresh temporary environment using `uv sync --locked --all-packages` followed by `uv lock --check`.
 - [x] 3.3 Verify member-scoped uv commands for both `device-agent-runtime` and `device-cloud-platform`.
-- [ ] 3.4 Update README and relevant setup documentation with workspace synchronization, test, build, and package-selection commands while leaving console npm commands unchanged.
+- [x] 3.4 Update README and relevant setup documentation with workspace synchronization, test, build, and package-selection commands while leaving console npm commands unchanged.
 
 ## 4. Build And Compatibility Verification