feat: 新增脚本支持在 uv 安装方式在 macOS 上运行，更新相关安装文档和README文档 (#203)

Rook1ex · web-flow · commit 5ca3bf24d334 · 2026-07-21T09:47:41.000+08:00
diff --git a/INSTALL.md b/INSTALL.md
@@ -84,6 +84,42 @@ source .venv/bin/activate        # Linux / macOS
 pip install -e .
 ```
 
+### uv Installation
+
+[uv](https://docs.astral.sh/uv/) manages the Python toolchain, virtual environment and dependencies based on the repository's `pyproject.toml` for fast, reproducible installs. This project provides a script for one-shot setup on macOS:
+
+```bash
+git clone https://github.com/trpc-group/trpc-agent-python.git
+cd trpc-agent-python
+
+# Install uv on macOS (see https://docs.astral.sh/uv/getting-started/installation/)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# One-shot setup
+bash build_mac_uv.sh
+
+# add optional extras
+EXTRAS="a2a knowledge" bash build_mac_uv.sh
+```
+
+Or run the steps manually:
+
+```bash
+uv venv --python-preference only-system   # use the local Python
+uv sync --extra dev                       # core + dev tooling
+uv sync --extra a2a --extra knowledge     # add optional extras
+uv sync                                   # production install (core only)
+
+# Run commands inside the environment without activating it for evaluation
+uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
+```
+
+To speed up downloads via a mirror, pass `--default-index`, e.g.:
+
+```bash
+uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
+```
+
 ### Optional Dependencies Reference
 
 | Extension        | Purpose                       | Install Command                         |
diff --git a/INSTALL.zh_CN.md b/INSTALL.zh_CN.md
@@ -84,6 +84,42 @@ source .venv/bin/activate        # Linux / macOS
 pip install -e .
 ```
 
+### uv 安装
+
+[uv](https://docs.astral.sh/uv/) 会基于仓库中 `pyproject.toml` 管理 Python 工具链、虚拟环境与依赖，实现快速、可复现的安装，本项目提供脚本在 macOS 上一键安装运行：
+
+```bash
+git clone https://github.com/trpc-group/trpc-agent-python.git
+cd trpc-agent-python
+
+# 在 macOS 上安装 uv（参考 https://docs.astral.sh/uv/getting-started/installation/）
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 一键初始化核心依赖
+bash build_mac_uv.sh
+
+# 按需追加可选扩展
+EXTRAS="a2a knowledge" bash build_mac_uv.sh
+```
+
+或者使用手动执行的方式：
+
+```bash
+uv venv --python-preference only-system   # 使用本地已安装的 Python
+uv sync --extra dev                       # 核心依赖 + 开发工具
+uv sync --extra a2a --extra knowledge     # 按需追加可选扩展
+uv sync                                   # 生产安装（仅核心依赖）
+
+# 无需激活环境即可运行命令验证
+uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
+```
+
+如需使用国内镜像加速，可传入 `--default-index`，例如：
+
+```bash
+uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple
+```
+
 ### 可选依赖对照表
 
 | 扩展名           | 用途                          | 安装命令                                |
diff --git a/README.md b/README.md
@@ -77,6 +77,8 @@ tRPC-Agent-Python provides an end-to-end foundation for agent building, orchestr
 
 ### Installation
 
+#### Install with pip
+
 ```bash
 pip install trpc-agent-py
 ```
@@ -87,6 +89,33 @@ Install optional capabilities as needed:
 pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]"
 ```
 
+#### Install with uv
+
+[uv](https://docs.astral.sh/uv/) provides fast, reproducible installs:
+
+```bash
+uv venv --python-preference only-system   # use the local Python
+uv sync                                   # production install (core only)
+uv sync --extra dev                       # core + dev tooling
+uv sync --extra a2a --extra knowledge     # add optional extras
+
+
+# Run commands inside the environment without activating it for evaluation
+uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)"
+```
+
+This project also provides a script for one-shot setup on macOS：
+```bash
+# One-shot setup
+bash build_mac_uv.sh
+```
+
+Install optional capabilities as needed:
+
+```bash
+EXTRAS="a2a knowledge" bash build_mac_uv.sh
+```
+
 ### Develop Weather Agent
 
 ```python
diff --git a/build_mac_uv.sh b/build_mac_uv.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+#
+# uv-based development setup for trpc-agent-python (macOS).
+#
+# This is a standalone alternative to build_mac.sh (which uses pip).
+# It uses uv to manage the Python toolchain, virtualenv and dependencies.
+#
+# Usage:
+#   bash build_mac_uv.sh                 # core + dev extra
+#   EXTRAS="a2a knowledge" bash build_mac_uv.sh   # also install extras
+#
+set -euo pipefail
+
+# Make sure uv's default install location is on PATH before probing for uv,
+# so a previously installed uv is reused instead of reinstalled every run.
+export PATH="$HOME/.local/bin:$PATH"
+
+# 1. Ensure uv is available.
+if ! command -v uv >/dev/null 2>&1; then
+    echo "[build_mac_uv] uv not found, installing..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    export PATH="$HOME/.local/bin:$PATH"
+fi
+
+echo "[build_mac_uv] uv version: $(uv --version)"
+
+# 2. Create the virtual environment using the user's local Python.
+uv venv --python-preference only-system
+
+# 3. Sync dependencies: core + the `dev` extra, plus any requested extras.
+EXTRA_ARGS=()
+for e in ${EXTRAS:-}; do
+    EXTRA_ARGS+=("--extra" "$e")
+done
+uv sync --extra dev ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}
+
+# 4. Smoke test the installation.
+uv run python -c "import trpc_agent_sdk; from trpc_agent_sdk.version import __version__; print(f'trpc-agent-py {__version__} installed via uv')"
+
+echo "[build_mac_uv] Done. Activate the env with: source .venv/bin/activate"
diff --git a/docs/mkdocs/en/openclaw.md b/docs/mkdocs/en/openclaw.md
@@ -44,7 +44,7 @@ flowchart TD
 
 ### 1) Environment Preparation
 
-- Python `>=3.10` (recommended `3.12`)
+- Python `>=3.11` (recommended `3.12`; requires `nanobot-ai`)
 - Use a virtual environment (`uv` or `venv`)
 
 ```bash
diff --git a/docs/mkdocs/zh/openclaw.md b/docs/mkdocs/zh/openclaw.md
@@ -44,7 +44,7 @@ flowchart TD
 
 ### 1) 环境准备
 
-- Python `>=3.10`（推荐 `3.12`）
+- Python `>=3.11`（推荐 `3.12`；依赖 `nanobot-ai`）
 - 建议使用虚拟环境（`uv` 或 `venv`）
 
 ```bash
diff --git a/pyproject.toml b/pyproject.toml
@@ -66,7 +66,7 @@ langfuse=[
     "opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.28.0",
 ]
 openclaw = [
-    "nanobot-ai>=0.1.4.post5",
+    "nanobot-ai>=0.1.4.post5; python_full_version >= '3.11'",
      "aiofiles",
      "wecom-aibot-sdk-python>=0.1.5",
 ]
@@ -151,7 +151,7 @@ all = [
     "mem0ai>=1.0.3",
     "mempalace>=3.3.3",
     "typer>=0.9.0",
-    "nanobot-ai>=0.1.4.post6",
+    "nanobot-ai>=0.1.4.post6; python_full_version >= '3.11'",
     "aiofiles",
     "wecom-aibot-sdk-python>=0.1.5",
     "a2a-sdk<1.0.0,>=0.3.22",
@@ -172,7 +172,12 @@ Homepage = "https://github.com/trpc-group/trpc-agent-python.git"
 Documentation = "https://github.com/trpc-group/trpc-agent-python.git"
 Repository = "https://github.com/trpc-group/trpc-agent-python.git"
 
-
+# uv project configuration. Defaults to the public PyPI index; the project is
+# installed as an editable package. 
+[tool.uv]
+package = true
+# Keep uv aligned with the package-level Python support. Optional dependencies
+# that require a newer interpreter use dependency-level markers above.
 
 # 可选：添加工具配置
 [tool.black]
