ADK-Python 文件组织规范实战指南目录布局、文件头约定与测试镜像规则【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonADKAgent Development KitPython 代码库在src/google/adk/下维护着数百个模块为了让新增代码在私人可见性、统一文件头、可预测的测试落点三方面保持一致性仓库通过.agents/skills/adk-style/这一风格技能沉淀了一套文件组织规范。本文以 file-organization.md 为骨架结合workflow/、tools/environment/的真实目录、scripts/compliance_checks.py的合规检查实现与.pre-commit-config.yaml的钩子配置讲清楚在 ADK-Python 中新增一个.py文件时应遵循的布局规则、文件头要求以及测试文件镜像源码路径的命名方法论帮助你在提交代码前一次性通过全部机器检查。一、两条核心布局原则原文档将文件组织概括为两条铁律任何新增代码都必须遵守workflow/目录下一文件一类One class per filesrc/google/adk/workflow/中的每个模块文件只承载一个核心类文件与类一一对应。src/google/adk/下新增模块默认私有private by default新文件必须以_下划线前缀命名是否对外暴露由包的__init__.py与可见性规则决定。从仓库实际目录看这两条原则被严格执行。以src/google/adk/workflow/为例目录下几乎全是_前缀文件且每个文件对应一个独立类src/google/adk/workflow/ ├── __init__.py # 公开 API 的出口 ├── _base_node.py # BaseNode / START ├── _graph.py # Graph / Edge / DEFAULT_ROUTE ├── _node.py # Node / node 装饰器 ├── _join_node.py # JoinNode ├── _function_node.py # FunctionNode ├── _retry_config.py # RetryConfig ├── _errors.py # NodeTimeoutError ├── _workflow.py # Workflow └── _node_runner.py # 内部运行器不出现在公开 API而src/google/adk/workflow/__init__.py正是可见性规则的落点它定义了__all__只导出BaseNode、DEFAULT_ROUTE、Edge、FunctionNode、JoinNode、Node、NodeTimeoutError、RetryConfig、START、Workflow、node这些公开符号并通过_LAZY_MEMBERS字典将符号映射到各自的_私有模块做惰性导入外部使用者从包顶层导入永远不需要也不应该触及内部_模块。这与 visibility.md 中文件私有、符号经__init__.py显式导出的约定完全呼应——原文档在 file-organization 中只是点了一句see the visibility reference想要完整理解命名规则与公开符号暴露机制应配合该参考文档阅读。二、文件头三部曲每个src/google/adk/模块的标准开头规范要求src/google/adk/下的每个模块文件都从以下三部分开始顺序固定Apache 2.0 许可证头由addlicense钩子自动补齐from __future__ import annotations延迟注解求值配合类型检查与 Pydantic 模型定义使用导入语句按标准库 → 第三方 → 相对导入三段排列。from __future__ import annotations这一条并非口头约定而是被scripts/compliance_checks.py的check_future_annotations()函数机器化强制任何不在豁免名单内的源码文件缺失该行compliance-checks检查就会失败并阻断提交。豁免范围与文档描述完全一致——__init__.py、version.py、tests/目录以及contributing/samples/目录下的文件无需该语句。以src/google/adk/workflow/__init__.py的真实文件头为例可以看到标准三段的实际形态# Copyright 2026 Google LLC # # Licensed under the Apache License, Version 2.0 (the License); # ...Apache 2.0 许可证头全文 from __future__ import annotations from typing import TYPE_CHECKING from ..utils import _lazy其中from __future__ import annotations位于许可证头之后、所有导入之前标准库导入typing与相对导入..utils分属不同段落符合standard library → third party → relative的顺序约定。想要了解这三段之间更多细节如cli/包的导入方向限制、TYPE_CHECKING的循环导入规避可继续阅读 imports.md 与 typing.md。三、机器强制这些约定由哪些钩子守护原文档指出许可证头由addlicense钩子添加、from __future__ import annotations由scripts/compliance_checks.py检查。仓库根目录的.pre-commit-config.yaml完整揭示了这三道防线- id: addlicense # 自动为文件添加 Google LLC Apache 2.0 许可证头 name: addlicense entry: bash -c ... addlicense -c Google LLC -l apache $ ... - id: check-new-py-prefix # 强制新增 .py 文件必须以下划线前缀命名私有默认 - id: compliance-checks # 调用 scripts/compliance_checks.py 做多项合规检查 entry: scripts/compliance_checks.py其中compliance-checks的实际逻辑位于 scripts/compliance_checks.py与文件组织规范直接相关的检查点包括check_future_annotations(content, filename)校验from __future__ import annotations是否存在豁免条件精确实现为filename.endswith(__init__.py)、filename.endswith(version.py)、路径含tests/、路径含contributing/samples/四类同一脚本还顺带检查 logger 命名必须是google_adk.前缀、禁止cli/包外反向导入、mTLS 端点、内部短链与 FastAPI 路由装饰器顺序等任一失败都会sys.exit(1)阻断流程。因此在 ADK-Python 中文件放哪里、叫什么名字、文件头长什么样不再是评审意见而是 PR 之前就必须通过的机器门槛。相关钩子的完整清单与各自检查内容可以对照 SKILL.md 末尾的 A check failed — where to look 速查表逐项定位。四、测试文件放哪里镜像源码路径规范对测试落点的要求只有一句话在tests/unittests/下镜像源码的目录结构。文档给出的第一组示例在仓库中真实存在src/google/adk/tools/environment/_edit_file_tool.py tests/unittests/tools/environment/test_edit_file_tool.py对应到仓库源码位于 src/google/adk/tools/environment/_edit_file_tool.py测试位于 tests/unittests/tools/environment/test_edit_file_tool.py。同一目录下还有配套的_read_file_tool.py→test_read_file_tool.py、_write_file_tool.py、_execute_tool.py等镜像关系一一对应、目录层级完全一致。这条规则的工程价值在于可推导性看到任意一个src/google/adk/下的源码文件任何人都能零成本推算出它的测试文件路径反过来测试失败时也能沿镜像路径立即定位到被测实现。注意镜像时只保留源码文件名的去下划线、去扩展名部分——_edit_file_tool.py对应test_edit_file_tool.py前缀统一为test_而不是test__edit_file_tool。五、一对多测试以源码文件名作为共享前缀当一个源文件需要拆分成多个测试文件时规范给出的命名技巧是使用源码文件名去掉前导下划线与扩展名作为共享前缀后缀表达测试关注的不同维度。文档示例在workflow/目录下同样真实存在src/google/adk/workflow/_workflow.py tests/unittests/workflow/test_workflow.py tests/unittests/workflow/test_workflow_hitl.py tests/unittests/workflow/test_workflow_nested.py对照仓库 tests/unittests/workflow/ 目录这套命名体系被大规模执行围绕_workflow.py一个源文件测试族扩展到了test_workflow.py基础行为、test_workflow_hitl.py人工介入场景、test_workflow_nested.py嵌套工作流、test_workflow_concurrency.py并发、test_workflow_dynamic_nodes.py动态节点、test_workflow_failures.py失败路径、test_workflow_parallel_worker.py并行执行、test_workflow_routes.py路由等十余个文件而_base_node.py、_graph.py、_join_node.py等同样各自拥有test_base_node.py、test_graph.py、test_join_node.py一一对应的测试。这种前缀 维度后缀模式的好处是用test_workflow_*一个 glob 就能搜出某个类的全部测试场景源码变更时按前缀即可定位所有需要同步更新的测试文件也方便 CI 按模块粒度并行分发测试任务。六、实操自查清单在 ADK-Python 中新增或移动一个.py文件前对照以下清单逐项确认检查项要求强制方式文件位置功能模块放入src/google/adk/子包/对应目录人工 评审文件命名新文件默认私有必须以_前缀开头如_workflow.pycheck-new-py-prefix钩子workflow/内聚性一个文件只放一个核心类人工 评审许可证头文件头包含 Apache 2.0 许可证Google LLCaddlicense钩子自动补齐延迟注解非豁免文件必须含from __future__ import annotationscompliance-checkscompliance_checks.py导入顺序标准库 → 第三方 → 相对导入isort/ruff钩子公开符号暴露仅在包__init__.py中导入并写入__all__配合 visibility.md人工 评审测试镜像测试置于tests/unittests/同构路径/test_源码名.py人工 评审一对多测试多测试文件共享test_源码名_前缀后缀表达场景维度人工 评审需要说明的是__init__.py、version.py、tests/与contributing/samples/四类文件享有豁免——它们无需from __future__ import annotations但其余规则如测试镜像依然适用。若新增文件需要对外提供公开 API请务必先阅读可见性参考文档理解文件私有、符号公开的完整暴露链路再动手提交。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ADK-Python 文件组织规范实战指南目录布局、文件头约定与测试镜像规则【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonADKAgent Development KitPython 代码库在src/google/adk/下维护着数百个模块为了让新增代码在私人可见性、统一文件头、可预测的测试落点三方面保持一致性仓库通过.agents/skills/adk-style/这一风格技能沉淀了一套文件组织规范。本文以 file-organization.md 为骨架结合workflow/、tools/environment/的真实目录、scripts/compliance_checks.py的合规检查实现与.pre-commit-config.yaml的钩子配置讲清楚在 ADK-Python 中新增一个.py文件时应遵循的布局规则、文件头要求以及测试文件镜像源码路径的命名方法论帮助你在提交代码前一次性通过全部机器检查。一、两条核心布局原则原文档将文件组织概括为两条铁律任何新增代码都必须遵守workflow/目录下一文件一类One class per filesrc/google/adk/workflow/中的每个模块文件只承载一个核心类文件与类一一对应。src/google/adk/下新增模块默认私有private by default新文件必须以_下划线前缀命名是否对外暴露由包的__init__.py与可见性规则决定。从仓库实际目录看这两条原则被严格执行。以src/google/adk/workflow/为例目录下几乎全是_前缀文件且每个文件对应一个独立类src/google/adk/workflow/ ├── __init__.py # 公开 API 的出口 ├── _base_node.py # BaseNode / START ├── _graph.py # Graph / Edge / DEFAULT_ROUTE ├── _node.py # Node / node 装饰器 ├── _join_node.py # JoinNode ├── _function_node.py # FunctionNode ├── _retry_config.py # RetryConfig ├── _errors.py # NodeTimeoutError ├── _workflow.py # Workflow └── _node_runner.py # 内部运行器不出现在公开 API而src/google/adk/workflow/__init__.py正是可见性规则的落点它定义了__all__只导出BaseNode、DEFAULT_ROUTE、Edge、FunctionNode、JoinNode、Node、NodeTimeoutError、RetryConfig、START、Workflow、node这些公开符号并通过_LAZY_MEMBERS字典将符号映射到各自的_私有模块做惰性导入外部使用者从包顶层导入永远不需要也不应该触及内部_模块。这与 visibility.md 中文件私有、符号经__init__.py显式导出的约定完全呼应——原文档在 file-organization 中只是点了一句see the visibility reference想要完整理解命名规则与公开符号暴露机制应配合该参考文档阅读。二、文件头三部曲每个src/google/adk/模块的标准开头规范要求src/google/adk/下的每个模块文件都从以下三部分开始顺序固定Apache 2.0 许可证头由addlicense钩子自动补齐from __future__ import annotations延迟注解求值配合类型检查与 Pydantic 模型定义使用导入语句按标准库 → 第三方 → 相对导入三段排列。from __future__ import annotations这一条并非口头约定而是被scripts/compliance_checks.py的check_future_annotations()函数机器化强制任何不在豁免名单内的源码文件缺失该行compliance-checks检查就会失败并阻断提交。豁免范围与文档描述完全一致——__init__.py、version.py、tests/目录以及contributing/samples/目录下的文件无需该语句。以src/google/adk/workflow/__init__.py的真实文件头为例可以看到标准三段的实际形态# Copyright 2026 Google LLC # # Licensed under the Apache License, Version 2.0 (the License); # ...Apache 2.0 许可证头全文 from __future__ import annotations from typing import TYPE_CHECKING from ..utils import _lazy其中from __future__ import annotations位于许可证头之后、所有导入之前标准库导入typing与相对导入..utils分属不同段落符合standard library → third party → relative的顺序约定。想要了解这三段之间更多细节如cli/包的导入方向限制、TYPE_CHECKING的循环导入规避可继续阅读 imports.md 与 typing.md。三、机器强制这些约定由哪些钩子守护原文档指出许可证头由addlicense钩子添加、from __future__ import annotations由scripts/compliance_checks.py检查。仓库根目录的.pre-commit-config.yaml完整揭示了这三道防线- id: addlicense # 自动为文件添加 Google LLC Apache 2.0 许可证头 name: addlicense entry: bash -c ... addlicense -c Google LLC -l apache $ ... - id: check-new-py-prefix # 强制新增 .py 文件必须以下划线前缀命名私有默认 - id: compliance-checks # 调用 scripts/compliance_checks.py 做多项合规检查 entry: scripts/compliance_checks.py其中compliance-checks的实际逻辑位于 scripts/compliance_checks.py与文件组织规范直接相关的检查点包括check_future_annotations(content, filename)校验from __future__ import annotations是否存在豁免条件精确实现为filename.endswith(__init__.py)、filename.endswith(version.py)、路径含tests/、路径含contributing/samples/四类同一脚本还顺带检查 logger 命名必须是google_adk.前缀、禁止cli/包外反向导入、mTLS 端点、内部短链与 FastAPI 路由装饰器顺序等任一失败都会sys.exit(1)阻断流程。因此在 ADK-Python 中文件放哪里、叫什么名字、文件头长什么样不再是评审意见而是 PR 之前就必须通过的机器门槛。相关钩子的完整清单与各自检查内容可以对照 SKILL.md 末尾的 A check failed — where to look 速查表逐项定位。四、测试文件放哪里镜像源码路径规范对测试落点的要求只有一句话在tests/unittests/下镜像源码的目录结构。文档给出的第一组示例在仓库中真实存在src/google/adk/tools/environment/_edit_file_tool.py tests/unittests/tools/environment/test_edit_file_tool.py对应到仓库源码位于 src/google/adk/tools/environment/_edit_file_tool.py测试位于 tests/unittests/tools/environment/test_edit_file_tool.py。同一目录下还有配套的_read_file_tool.py→test_read_file_tool.py、_write_file_tool.py、_execute_tool.py等镜像关系一一对应、目录层级完全一致。这条规则的工程价值在于可推导性看到任意一个src/google/adk/下的源码文件任何人都能零成本推算出它的测试文件路径反过来测试失败时也能沿镜像路径立即定位到被测实现。注意镜像时只保留源码文件名的去下划线、去扩展名部分——_edit_file_tool.py对应test_edit_file_tool.py前缀统一为test_而不是test__edit_file_tool。五、一对多测试以源码文件名作为共享前缀当一个源文件需要拆分成多个测试文件时规范给出的命名技巧是使用源码文件名去掉前导下划线与扩展名作为共享前缀后缀表达测试关注的不同维度。文档示例在workflow/目录下同样真实存在src/google/adk/workflow/_workflow.py tests/unittests/workflow/test_workflow.py tests/unittests/workflow/test_workflow_hitl.py tests/unittests/workflow/test_workflow_nested.py对照仓库 tests/unittests/workflow/ 目录这套命名体系被大规模执行围绕_workflow.py一个源文件测试族扩展到了test_workflow.py基础行为、test_workflow_hitl.py人工介入场景、test_workflow_nested.py嵌套工作流、test_workflow_concurrency.py并发、test_workflow_dynamic_nodes.py动态节点、test_workflow_failures.py失败路径、test_workflow_parallel_worker.py并行执行、test_workflow_routes.py路由等十余个文件而_base_node.py、_graph.py、_join_node.py等同样各自拥有test_base_node.py、test_graph.py、test_join_node.py一一对应的测试。这种前缀 维度后缀模式的好处是用test_workflow_*一个 glob 就能搜出某个类的全部测试场景源码变更时按前缀即可定位所有需要同步更新的测试文件也方便 CI 按模块粒度并行分发测试任务。六、实操自查清单在 ADK-Python 中新增或移动一个.py文件前对照以下清单逐项确认检查项要求强制方式文件位置功能模块放入src/google/adk/子包/对应目录人工 评审文件命名新文件默认私有必须以_前缀开头如_workflow.pycheck-new-py-prefix钩子workflow/内聚性一个文件只放一个核心类人工 评审许可证头文件头包含 Apache 2.0 许可证Google LLCaddlicense钩子自动补齐延迟注解非豁免文件必须含from __future__ import annotationscompliance-checkscompliance_checks.py导入顺序标准库 → 第三方 → 相对导入isort/ruff钩子公开符号暴露仅在包__init__.py中导入并写入__all__配合 visibility.md人工 评审测试镜像测试置于tests/unittests/同构路径/test_源码名.py人工 评审一对多测试多测试文件共享test_源码名_前缀后缀表达场景维度人工 评审需要说明的是__init__.py、version.py、tests/与contributing/samples/四类文件享有豁免——它们无需from __future__ import annotations但其余规则如测试镜像依然适用。若新增文件需要对外提供公开 API请务必先阅读可见性参考文档理解文件私有、符号公开的完整暴露链路再动手提交。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 在交互式笔记本中构建强调内容)
