详细记录Google A2UI 本地调试问题解决方案：
如果你还没装 uv，在 macOS 上推荐用 Homebrew：
brew install uv
安装完成后验证：
uv --version
默认部署会报错：
× Failed to download google-genai==1.55.0
├─▶ Failed to fetch:
│ https://files.pythonhosted.org/packages/3e/86/a5a8e32b2d40b30b5fb20e7b8113fafd1e38befa4d1801abd5ce6991065a/google_genai-1.55.0-py3-none-any.whl
├─▶ Request failed after 3 retries
├─▶ error sending request for url
│ (https://files.pythonhosted.org/packages/3e/86/a5a8e32b2d40b30b5fb20e7b8113fafd1e38befa4d1801abd5ce6991065a/google_genai-1.55.0-py3-none-any.whl)
╰─▶ operation timed out
这个错误本质很清楚了：网络连不上 PyPI 的文件站点，不是环境或 uv 的问题。
operation timed out
files.pythonhosted.org
在 国内网络 / 公司网络 下，这个地址经常超时。
下面给你 几种稳妥解法，从「最快见效」到「长期方案」。
写入你的 ~/.zshrc：
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.zshrc source ~/.zshrc
guoqingzhou@guoqingzhoudeMacBook-Pro A2UI % echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple'
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
guoqingzhou@guoqingzhoudeMacBook-Pro A2UI % uv --version
uv 0.9.18 (Homebrew 2025-12-16)
guoqingzhou@guoqingzhoudeMacBook-Pro A2UI % cd samples
guoqingzhou@guoqingzhoudeMacBook-Pro samples % cd agent/adk/restaurant_finder
guoqingzhou@guoqingzhoudeMacBook-Pro restaurant_finder % uv run .
Built a2ui @ file:///Users/guoqingzhou/Projects/A2UI/A2UI/a2a_agents/python/a2ui_extension
Built a2ui-restaurant-finder @ file:///Users/guoqingzhou/Projects/A2UI/A2UI/samples/agent/adk/restaurant_finder
Updated https://github.com/google/adk-python.git (143ad44f8c5d1c56fc92dd691589aaa0b788e485)
Built watchdog==6.0.0
Built google-adk @ git+https://github.com/google/adk-python.git@143ad44f8c5d1c56fc92dd691589aaa0b788e485
Installed 134 packages in 224ms
ERROR:__main__:Error: GEMINI_API_KEY environment variable not set and GOOGLE_GENAI_USE_VERTEXAI is not TRUE.
guoqingzhou@guoqingzhoudeMacBook-Pro restaurant_finder % export GEMINI_API_KEY="A************nc0"
guoqingzhou@guoqingzhoudeMacBook-Pro restaurant_finder % uv run .
/Users/guoqingzhou/Projects/A2UI/A2UI/samples/agent/adk/restaurant_finder/agent.py:107: UserWarning: [GEMINI_VIA_LITELLM] gemini/gemini-2.5-flash: You are using Gemini via LiteLLM. For better performance, reliability, and access to latest features, consider using Gemini directly through ADK's native Gemini integration. Replace LiteLlm(model='gemini/gemini-2.5-flash') with Gemini(model='gemini-2.5-flash'). Set ADK_SUPPRESS_GEMINI_LITELLM_WARNINGS=true to suppress this warning.
model=LiteLlm(model=LITELLM_MODEL),
INFO:agent:A2UI_SCHEMA successfully loaded and wrapped in an array validator.
INFO:agent:A2UI_SCHEMA successfully loaded and wrapped in an array validator.
INFO: Started server process [1789]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://localhost:10002 (Press CTRL+C to quit)