retail-product-search 技能依赖清单全解从 pyproject.toml 到 bootstrap.sh 的安装避坑指南【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本篇指南以 dependencies.md 为骨架系统梳理retail-product-search基于 ADK 的零售商品语义搜索技能底层使用 Vertex AI Vector Search、BigQuery 与 embeddings的全部 Python 依赖、版本约束与安装注意事项并结合 pyproject.toml、bootstrap.sh 等仓库源码讲清楚为什么这些依赖必须这样装路径含空格、PATH 被裁剪等环境怪癖是如何被逐一化解的。读完你不仅能独立安装并运行该技能还能理解 ADK 技能在沙箱化 Agent 终端中正确落地的底层机制。依赖总览一条命令解决一切dependencies.md 开篇就给出一个关键结论你不需要手动逐个安装依赖。在安装目录install dir下执行pip install -e .pip会读取pyproject.toml中的[project].dependencies字段把全部运行时依赖一次性解析并安装到当前虚拟环境。该技能采用 hatchling 作为构建后端见 pyproject.toml并以 editable-e方式安装使得技能目录下的scripts包可以直接被import且对源码的修改即时生效无需重装。Required九大核心依赖及各自职责依据 dependencies.md 的 Required 清单并结合 pyproject.toml 中的逐行注释各依赖的用途与版本约束如下依赖版本约束用途google-adk2.2.0Agent 运行时与adk webWeb UI。注意它是无条件依赖——旧文档中的[adk]extra 选择器已废弃google-cloud-aiplatform1.30Vertex AI 平台 SDK用于vertexai.init()初始化见 scripts/agent.pygoogle-cloud-bigquery3.0商品目录入库 BigQuery见 scripts/ingest_bigquery.py 中的bigquery.Client、LoadJobConfig等google-cloud-storage2.0读取gs://数据源storage.Client().bucket(...).blob(...)下载 CSV/JSONgoogle-cloud-vectorsearch0.5,1.0预览版preview依赖被钉死在已知可用区间。retrievers.py通过vectorsearch.DataObjectSearchServiceClient()做语义检索见 scripts/retrievers.pygoogle-genai1.0Google Gen AI SDK供config.py启动 Vertex AI 客户端设置GOOGLE_GENAI_USE_VERTEXAITruepyOpenSSL23.0部分环境下 BigQuery / Vector Search 认证所需的 mTLS 支持python-dotenv1.0在 import 时通过scripts/config.py加载.env环境变量pyyaml6.0解析design-spec.md的 YAML frontmatter 配置requests2.28HTTP 客户端供部分脚本调用外部接口两个值得注意的钉死策略google-cloud-vectorsearch的上限约束1.0Vector Search 2.0 SDK 仍处于 preview/beta 阶段主版本升级可能引入破坏性 API 变更例如DataObjectSearchServiceClient的接口变化。钉死版本区间意味着可复现、可回归的环境这正是技能作为可交付产物所必需的稳定性。google-adk从可选变为必选install-paths.md 记载了这一演进早期版本通过pip install -e $SKILL_DIR[adk]拉取可选 extra而现在google-adk已是pyproject.toml中的无条件依赖。如果你在过时文档中看到[adk]后缀直接去掉即可正常安装。开发依赖dev group除运行时依赖外pyproject.toml 还声明了[dependency-groups].devpytest8.0、pytest-mock3.14、pytest-cov4.1pytest 配置了testpaths [tests]、-s -v输出与 INFO 级别日志并定义了livemarker用于标记会真实访问 GCP 的集成测试需LIVE_EVAL1与全新 GCP 项目。环境要求Python 3.11 是硬性下限pyproject.toml 声明requires-python 3.11。这个下限贯穿了整个技能工具链bootstrap.sh 的 Python 解释器探测逻辑只接受3.11、3.12、3.13三个版本其余版本含更老的 3.9/3.10一律跳过并回退若最终找不到合法解释器bootstrap 会明确报错need Python 3.11并提示brew install python3.12若用系统自带的 Python 3.9 创建 venv安装时会出现Package requires Python: 3.9.X报错README.md 的处置方式是python3.12 -m venv .venv重建。Install quirksbootstrap.sh 化解的三个环境怪癖dependencies.md 的 Install quirks 一节记录了三个由 bootstrap.sh 处理的已知问题。下面逐一展开其原理。怪癖一路径含空格若技能安装在含空格的路径下例如 macOS 用户目录/Users/name with space/.claude/skills/...裸写pip install -e $SKILL_DIR会让 shell 把路径按空格拆成多个参数导致 pip 解析失败。解法是 bootstrap.sh 中这一行bash -c pip install -e $SKILL_DIR用bash -c将整个命令作为单个字符串交给新的 shell 执行单引号包裹保证 pip 只看到一个完整路径。这是 Agent 场景下最稳妥的引用方式。怪癖二Agent 的 shell 工具会在两次调用间重置状态AI 编码 Agent 的 shell 工具每次调用都是独立进程cwd 会被重置、环境变量会被清空。如果在第 1 次调用里export SKILL_DIR...、第 2 次调用才执行pip install -e $SKILL_DIR第 2 次调用时$SKILL_DIR早已为空安装命令退化成pip install -e非法。因此 SKILL.md 明确要求工作区初始化必须作为单条 shell 命令一次执行SKILL_DIR$(for d in ~/.claude/skills ~/.agents/skills ~/.gemini/skills ~/.cursor/skills; do [ -f $d/retail-product-search/SKILL.md ] echo $d/retail-product-search break done) bash $SKILL_DIR/scripts/bootstrap.sh其中SKILL_DIR的探测顺序与 bootstrap.sh 内置的候选路径一致~/.claude/skills、~/.agents/skills、~/.gemini/skills、~/.cursor/skills。若以上均未命中bootstrap 还会根据自身绝对路径$0反推安装目录作为最终兜底bootstrap.sh。怪癖三沙箱终端的 PATH 被裁剪沙箱化终端常常只保留最小 PATH导致command -v python3找不到 brew/pyenv 安装的 Python。bootstrap 的应对分三档bootstrap.sh优先使用外部传入的PYTHON_BIN若已在环境中导出且版本合法3.11/3.12/3.13直接采用——这为 conda、asdf 等自定义布局留了出口按 PATH 查找依次尝试python3.13 python3.12 python3.11 python3回退到绝对路径硬编码探测/opt/homebrew/bin/python3.13、/usr/local/bin/python3.12、$HOME/.pyenv/shims/python3.11等常见安装位置逐个验证版本后选用。依赖与配置的联动.env是下游模块的唯一配置入口理解依赖之后还需要明白这些包在运行时是如何被组织起来的。整个技能的配置链路见 scripts/config.py依赖python-dotenv模块顶部load_dotenv()在 import 时加载.env随后os.environ.setdefault(GOOGLE_GENAI_USE_VERTEXAI, True)确保所有 genai 客户端走 Vertex AI 通道config对象通过 property 对每个属性做惰性读取每次访问都重新os.getenv()因此setup.py等脚本在运行中途写入.env后下一次属性读取即可拿到新值无需重启进程。关键环境变量及默认值如下scripts/config.py环境变量默认值说明GOOGLE_CLOUD_PROJECT必填GCP 项目 IDGOOGLE_CLOUD_LOCATIONglobalVertex AI 全局 locationVECTOR_SEARCH_LOCATIONus-central1Vector Search 区域当前仅此区域确认支持 Vector Search 2.0VECTOR_SEARCH_COLLECTION集合完整路径为空则从其他配置推导GEMINI_MODELgemini-3.5-flash生成式模型EMBEDDING_MODELgemini-embedding-001embedding 模型VECTOR_SEARCH_COLLECTION的坑值得单独强调它必须在一行内导出且无换行否则retrievers.py中用于校验路径格式的正则^projects/[^/\s]/locations/[^/\s]/collections/[^/\s]$scripts/retrievers.py会匹配失败进而触发 Vector Search 的MethodNotImplemented: 501。从pip install -e .到跑通检索的完整链路将依赖、安装与运行串起来整个技能的生命周期如下详见 README.md 与 SKILL.md安装技能npx skills add google/adk-samples --skill retail-product-search安装到~/.claude/skills/或~/.agents/skills/开发者调试场景则进入skills/retail/product-search目录执行uv sync初始化工作区Agent 以单条 shell 命令运行bootstrap.sh完成探测安装目录 → 找 Python 3.11 → 建.venv→pip install -e解析全部依赖 → 拷贝 design-spec 模板填写配置并运行流水线.venv/bin/python $SKILL_DIR/scripts/setup.py --config ./design-spec.md内部依次执行 schema 校验scripts/validate_schema.py、BigQuery 入库幂等的if_existsskip见 scripts/ingest_bigquery.py、Vector Search 集合创建与 embedding 索引scripts/ingest_vertex_search.py最后把解析出的配置写入.env启动 Web UI.venv/bin/adk web $SKILL_DIR/scripts --port 8765注意必须指向安装目录下的scriptsAgent 代码在那里且使用工作区 venv 中的adk否则会出现/list-apps返回[]的空应用列表问题验证检索export VECTOR_SEARCH_COLLECTIONprojects/$GOOGLE_CLOUD_PROJECT/locations/us-central1/collections/retail-skill-products-collection后在 Web UI 提问或用from scripts.retrievers import search; print(search(laptop for video editing, top_k3))做无 UI 冒烟测试。常见安装故障速查结合 dependencies.md、README.md 与 SKILL.md常见故障与处置如下错误根因修复ModuleNotFoundError: google.adk用了旧的[adk]extra 或未 editable 安装pip install -e $SKILL_DIRgoogle-adk 已是无条件依赖Package requires Python: 3.9.Xvenv 基于系统 Python 3.9 创建python3.12 -m venv .venv重建MethodNotImplemented: 501VECTOR_SEARCH_COLLECTION含换行或区域不支持单行重新 export确认区域为us-central1adk web启动但/list-apps返回[]裸adk解析到了全局 Python缺少 editable 安装改用.venv/bin/adk web $SKILL_DIR/scripts --port 8765setup.py报NoneType object has no attribute getdesign-spec.md被整体重写为纯 Markdown丢失 YAML frontmatter等待 bootstrap 完成后用编辑方式修改 frontmatter 内的字段值BILLING_DISABLED/PERMISSION_DENIEDGCP 项目未开通计费或 API见 references/troubleshooting.md小结retail-product-search的依赖管理遵循单一事实来源原则所有版本约束集中在 pyproject.toml一条pip install -e .即可全部解析而三个已知的环境怪癖路径含空格、Agent shell 状态重置、PATH 被裁剪则由 bootstrap.sh 用bash -c引用、单次 shell 调用、绝对路径回退三招化解。理解这套机制不仅能让技能在任何沙箱化 Agent 环境中稳定落地也为自行封装 ADK 技能时的依赖设计提供了可复用的范本。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 retail-product-search 技能依赖清单全解：从 pyproject.toml 到 bootstrap.sh 的安装避坑指南
retail-product-search 技能依赖清单全解从 pyproject.toml 到 bootstrap.sh 的安装避坑指南【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本篇指南以 dependencies.md 为骨架系统梳理retail-product-search基于 ADK 的零售商品语义搜索技能底层使用 Vertex AI Vector Search、BigQuery 与 embeddings的全部 Python 依赖、版本约束与安装注意事项并结合 pyproject.toml、bootstrap.sh 等仓库源码讲清楚为什么这些依赖必须这样装路径含空格、PATH 被裁剪等环境怪癖是如何被逐一化解的。读完你不仅能独立安装并运行该技能还能理解 ADK 技能在沙箱化 Agent 终端中正确落地的底层机制。依赖总览一条命令解决一切dependencies.md 开篇就给出一个关键结论你不需要手动逐个安装依赖。在安装目录install dir下执行pip install -e .pip会读取pyproject.toml中的[project].dependencies字段把全部运行时依赖一次性解析并安装到当前虚拟环境。该技能采用 hatchling 作为构建后端见 pyproject.toml并以 editable-e方式安装使得技能目录下的scripts包可以直接被import且对源码的修改即时生效无需重装。Required九大核心依赖及各自职责依据 dependencies.md 的 Required 清单并结合 pyproject.toml 中的逐行注释各依赖的用途与版本约束如下依赖版本约束用途google-adk2.2.0Agent 运行时与adk webWeb UI。注意它是无条件依赖——旧文档中的[adk]extra 选择器已废弃google-cloud-aiplatform1.30Vertex AI 平台 SDK用于vertexai.init()初始化见 scripts/agent.pygoogle-cloud-bigquery3.0商品目录入库 BigQuery见 scripts/ingest_bigquery.py 中的bigquery.Client、LoadJobConfig等google-cloud-storage2.0读取gs://数据源storage.Client().bucket(...).blob(...)下载 CSV/JSONgoogle-cloud-vectorsearch0.5,1.0预览版preview依赖被钉死在已知可用区间。retrievers.py通过vectorsearch.DataObjectSearchServiceClient()做语义检索见 scripts/retrievers.pygoogle-genai1.0Google Gen AI SDK供config.py启动 Vertex AI 客户端设置GOOGLE_GENAI_USE_VERTEXAITruepyOpenSSL23.0部分环境下 BigQuery / Vector Search 认证所需的 mTLS 支持python-dotenv1.0在 import 时通过scripts/config.py加载.env环境变量pyyaml6.0解析design-spec.md的 YAML frontmatter 配置requests2.28HTTP 客户端供部分脚本调用外部接口两个值得注意的钉死策略google-cloud-vectorsearch的上限约束1.0Vector Search 2.0 SDK 仍处于 preview/beta 阶段主版本升级可能引入破坏性 API 变更例如DataObjectSearchServiceClient的接口变化。钉死版本区间意味着可复现、可回归的环境这正是技能作为可交付产物所必需的稳定性。google-adk从可选变为必选install-paths.md 记载了这一演进早期版本通过pip install -e $SKILL_DIR[adk]拉取可选 extra而现在google-adk已是pyproject.toml中的无条件依赖。如果你在过时文档中看到[adk]后缀直接去掉即可正常安装。开发依赖dev group除运行时依赖外pyproject.toml 还声明了[dependency-groups].devpytest8.0、pytest-mock3.14、pytest-cov4.1pytest 配置了testpaths [tests]、-s -v输出与 INFO 级别日志并定义了livemarker用于标记会真实访问 GCP 的集成测试需LIVE_EVAL1与全新 GCP 项目。环境要求Python 3.11 是硬性下限pyproject.toml 声明requires-python 3.11。这个下限贯穿了整个技能工具链bootstrap.sh 的 Python 解释器探测逻辑只接受3.11、3.12、3.13三个版本其余版本含更老的 3.9/3.10一律跳过并回退若最终找不到合法解释器bootstrap 会明确报错need Python 3.11并提示brew install python3.12若用系统自带的 Python 3.9 创建 venv安装时会出现Package requires Python: 3.9.X报错README.md 的处置方式是python3.12 -m venv .venv重建。Install quirksbootstrap.sh 化解的三个环境怪癖dependencies.md 的 Install quirks 一节记录了三个由 bootstrap.sh 处理的已知问题。下面逐一展开其原理。怪癖一路径含空格若技能安装在含空格的路径下例如 macOS 用户目录/Users/name with space/.claude/skills/...裸写pip install -e $SKILL_DIR会让 shell 把路径按空格拆成多个参数导致 pip 解析失败。解法是 bootstrap.sh 中这一行bash -c pip install -e $SKILL_DIR用bash -c将整个命令作为单个字符串交给新的 shell 执行单引号包裹保证 pip 只看到一个完整路径。这是 Agent 场景下最稳妥的引用方式。怪癖二Agent 的 shell 工具会在两次调用间重置状态AI 编码 Agent 的 shell 工具每次调用都是独立进程cwd 会被重置、环境变量会被清空。如果在第 1 次调用里export SKILL_DIR...、第 2 次调用才执行pip install -e $SKILL_DIR第 2 次调用时$SKILL_DIR早已为空安装命令退化成pip install -e非法。因此 SKILL.md 明确要求工作区初始化必须作为单条 shell 命令一次执行SKILL_DIR$(for d in ~/.claude/skills ~/.agents/skills ~/.gemini/skills ~/.cursor/skills; do [ -f $d/retail-product-search/SKILL.md ] echo $d/retail-product-search break done) bash $SKILL_DIR/scripts/bootstrap.sh其中SKILL_DIR的探测顺序与 bootstrap.sh 内置的候选路径一致~/.claude/skills、~/.agents/skills、~/.gemini/skills、~/.cursor/skills。若以上均未命中bootstrap 还会根据自身绝对路径$0反推安装目录作为最终兜底bootstrap.sh。怪癖三沙箱终端的 PATH 被裁剪沙箱化终端常常只保留最小 PATH导致command -v python3找不到 brew/pyenv 安装的 Python。bootstrap 的应对分三档bootstrap.sh优先使用外部传入的PYTHON_BIN若已在环境中导出且版本合法3.11/3.12/3.13直接采用——这为 conda、asdf 等自定义布局留了出口按 PATH 查找依次尝试python3.13 python3.12 python3.11 python3回退到绝对路径硬编码探测/opt/homebrew/bin/python3.13、/usr/local/bin/python3.12、$HOME/.pyenv/shims/python3.11等常见安装位置逐个验证版本后选用。依赖与配置的联动.env是下游模块的唯一配置入口理解依赖之后还需要明白这些包在运行时是如何被组织起来的。整个技能的配置链路见 scripts/config.py依赖python-dotenv模块顶部load_dotenv()在 import 时加载.env随后os.environ.setdefault(GOOGLE_GENAI_USE_VERTEXAI, True)确保所有 genai 客户端走 Vertex AI 通道config对象通过 property 对每个属性做惰性读取每次访问都重新os.getenv()因此setup.py等脚本在运行中途写入.env后下一次属性读取即可拿到新值无需重启进程。关键环境变量及默认值如下scripts/config.py环境变量默认值说明GOOGLE_CLOUD_PROJECT必填GCP 项目 IDGOOGLE_CLOUD_LOCATIONglobalVertex AI 全局 locationVECTOR_SEARCH_LOCATIONus-central1Vector Search 区域当前仅此区域确认支持 Vector Search 2.0VECTOR_SEARCH_COLLECTION集合完整路径为空则从其他配置推导GEMINI_MODELgemini-3.5-flash生成式模型EMBEDDING_MODELgemini-embedding-001embedding 模型VECTOR_SEARCH_COLLECTION的坑值得单独强调它必须在一行内导出且无换行否则retrievers.py中用于校验路径格式的正则^projects/[^/\s]/locations/[^/\s]/collections/[^/\s]$scripts/retrievers.py会匹配失败进而触发 Vector Search 的MethodNotImplemented: 501。从pip install -e .到跑通检索的完整链路将依赖、安装与运行串起来整个技能的生命周期如下详见 README.md 与 SKILL.md安装技能npx skills add google/adk-samples --skill retail-product-search安装到~/.claude/skills/或~/.agents/skills/开发者调试场景则进入skills/retail/product-search目录执行uv sync初始化工作区Agent 以单条 shell 命令运行bootstrap.sh完成探测安装目录 → 找 Python 3.11 → 建.venv→pip install -e解析全部依赖 → 拷贝 design-spec 模板填写配置并运行流水线.venv/bin/python $SKILL_DIR/scripts/setup.py --config ./design-spec.md内部依次执行 schema 校验scripts/validate_schema.py、BigQuery 入库幂等的if_existsskip见 scripts/ingest_bigquery.py、Vector Search 集合创建与 embedding 索引scripts/ingest_vertex_search.py最后把解析出的配置写入.env启动 Web UI.venv/bin/adk web $SKILL_DIR/scripts --port 8765注意必须指向安装目录下的scriptsAgent 代码在那里且使用工作区 venv 中的adk否则会出现/list-apps返回[]的空应用列表问题验证检索export VECTOR_SEARCH_COLLECTIONprojects/$GOOGLE_CLOUD_PROJECT/locations/us-central1/collections/retail-skill-products-collection后在 Web UI 提问或用from scripts.retrievers import search; print(search(laptop for video editing, top_k3))做无 UI 冒烟测试。常见安装故障速查结合 dependencies.md、README.md 与 SKILL.md常见故障与处置如下错误根因修复ModuleNotFoundError: google.adk用了旧的[adk]extra 或未 editable 安装pip install -e $SKILL_DIRgoogle-adk 已是无条件依赖Package requires Python: 3.9.Xvenv 基于系统 Python 3.9 创建python3.12 -m venv .venv重建MethodNotImplemented: 501VECTOR_SEARCH_COLLECTION含换行或区域不支持单行重新 export确认区域为us-central1adk web启动但/list-apps返回[]裸adk解析到了全局 Python缺少 editable 安装改用.venv/bin/adk web $SKILL_DIR/scripts --port 8765setup.py报NoneType object has no attribute getdesign-spec.md被整体重写为纯 Markdown丢失 YAML frontmatter等待 bootstrap 完成后用编辑方式修改 frontmatter 内的字段值BILLING_DISABLED/PERMISSION_DENIEDGCP 项目未开通计费或 API见 references/troubleshooting.md小结retail-product-search的依赖管理遵循单一事实来源原则所有版本约束集中在 pyproject.toml一条pip install -e .即可全部解析而三个已知的环境怪癖路径含空格、Agent shell 状态重置、PATH 被裁剪则由 bootstrap.sh 用bash -c引用、单次 shell 调用、绝对路径回退三招化解。理解这套机制不仅能让技能在任何沙箱化 Agent 环境中稳定落地也为自行封装 ADK 技能时的依赖设计提供了可复用的范本。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考