ADK Python 格式化规范全解pyink、isort 与 pre-commit 驱动的代码风格工作流【免费下载链接】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-pythongoogle-adkAgent Development Kit仓库见本目录根 README.md是一个代码优先的 Python Agent 开发框架源码规模庞大且长期多人协作因此代码风格不是靠口头约定而是通过pre-commit钩子与 CI 双重强制。本文以仓库中的格式化风格指南为骨架逐条拆解 ADK 的缩进、行宽、引号、导入排序规则说明每个钩子到底检查什么、被哪些目录豁免并给出本地一键运行格式化的完整命令最后深入到scripts/与pyproject.toml源码层讲清规则从哪里来、被谁执行、失败时去哪里查。规则的单一事实来源两份配置文件ADK 的格式化规则不是散落在文档里的建议而是被硬编码在仓库根目录的两份配置文件中pyproject.toml所有工具的配置参数都声明在这里包括pyink、isort、ruff、codespell等.pre-commit-config.yaml声明了每个 pre-commit 钩子、其来源仓库、版本号与参数并定义了哪些目录整体豁免。格式指南文档明确指出这两份配置是唯一事实来源source of truth风格指南只是对它们的汇总。因此排查格式化问题时应以这两份文件为准而不是依赖记忆中的规则。修改代码时同样以这两份配置为最终依据。四条核心格式化规则ADK 的格式化基准是 Google 维护的pyinkBlack 的 Google 分支配合isort管理导入规则如下规则配置项含义2 空格缩进pyink-indentation 2见 pyproject.toml永远不使用 Tab80 字符行宽pyinkline-length 80超长行会被重排import 行是唯一例外pyink 格式化 Python格式化器本体所有非 import 的格式问题都由它处理引号跟随文件多数风格pyink-use-majority-quotespyink 不会把x机械改写成x编辑哪个文件就沿用该文件的主流引号避免大规模引号震荡以pyink-use-majority-quotes为例它逐文件统计单引号与双引号的占比选择多数派作为该文件的统一风格。这意味着你新编辑的代码应与文件保持一致而不是强行把整个文件改成自己的偏好——这是 Google 系代码库如src/google/adk/下各模块保持 diff 最小化的关键机制。每个钩子到底强制什么pre-commit的运行顺序本身并不重要重要的是知道是哪个工具拒绝了你的提交。下表完整列出 .pre-commit-config.yaml 中的钩子及其职责钩子作用ruff只移除未使用的导入lint.select [F401]自动修复仅作用于src/。__init__.py豁免因为它的导入是 re-export详见 pyproject.toml 中的per-file-ignoresisort导入的顺序与分组pyink除导入外的所有其他格式化addlicense为.py/.sh文件添加 Apache 2.0 许可证头若本机未安装 Go 版addlicense二进制则以警告跳过但 CI 仍会捕获遗漏check-new-py-prefixsrc/google/adk/下新增的.py文件必须以_开头private-by-default详见 visibility 参考compliance-checks合规检查logger 名称、from __future__ import annotations、cli/包导入方向、mTLS 端点等codespell代码与文档中的拼写检查确属误报的词加入 pyproject.toml 的ignore-words-listpyproject-fmt规范化pyproject.toml自身的格式mdformat仅格式化README.md、CONTRIBUTING.md与contributing/**.md配置见此处check-yaml、end-of-file-fixer、trailing-whitespace空白与 YAML 语法卫生文件尾换行、行尾空白、多文档 YAML 解析update-constraints当pyproject.toml变化时重新生成constraints-3.*.txt需要网络访问来解析依赖版本两个本地钩子的源码细节check-new-py-prefix与compliance-checks都是仓库自带的本地脚本钩子repo: local它们的行为可以由源码精确印证check-new-py-prefix入口是 scripts/check_new_py_files.sh最终调用 scripts/check_new_py_files.py。该脚本除了强制_前缀外从源码看还会要求新文件在docs/guides/下配套 unit guide除非匹配豁免模式或提交信息/环境中带NO_UNIT_GUIDE标签。它支持 git、jj、hg、g4、p4 多种 VCS 检测并定义了退出码 3 表示无法确定新增文件集避免把检查失败误读为检查通过。compliance-checks入口是 scripts/compliance_checks.py采用正则与 AST 双重手段。从源码结构看它实际包含的检查点比文档表格列出的更多logger 名称禁止裸写logger logging.getLogger(__name__)必须带google_adk.前缀check_loggerfrom __future__ import annotations除__init__.py、version.py、tests/、contributing/samples/外强制要求check_future_annotationscli/导入方向cli/包外的任何文件禁止from ...cli... import ...check_cli_importmTLS 端点出现非 scope 的*.googleapis.com硬编码 URL 时必须同时存在.mtls.googleapis.com支持历史遗留文件放在_EXCLUDED_FROM_MTLS白名单中且禁止新增check_mtls内部短链检查禁止go/xxx形式的内部短链接FastAPI 路由装饰器顺序路由装饰器上方的装饰器永远不生效AST 检查会报告这类静默失效的守卫代码check_route_decorator_order。全量豁免目录.pre-commit-config.yaml 在顶层声明了排除规则以下目录/路径不参与任何钩子src/google/adk/cli/browser/ src/google/adk/v1/ v1_tests/此外 pyproject.toml 的[tool.ruff] extend-exclude还单独豁免了几个硬编码 googleapis.com 端点的大查询bigquery相关文件——它们一旦变动就会触发 mTLS 策略检查因此暂时从F401清理中排除待 mTLS 策略解决后再处理。注意这两层豁免的语义不同顶层 exclude 是完全不检查ruff 的 extend-exclude 只是本工具不检查。如何运行格式化器安装 git 钩子一次之后提交时就会自动格式化pre-commit install随后对尚未提交的工作进行检查# 仅检查已暂存staged文件 —— 提交钩子实际运行的就是这个 pre-commit run # 指定文件 pre-commit run --files path/to/file.py # 全量检查 pre-commit run --all-files关键认知CI 运行的是同一份配置.pre-commit-config.yaml所以本地pre-commit run --all-files通过就意味着 lint CI 任务会通过。为了让本地输出与 CI 字节级一致pyproject.toml 的dev可选依赖把会改写文件的格式化工具固定到与 pre-commit 完全相同的版本例如isort8.0.1、pyink25.12、ruff0.15.17、pyproject-fmt2.24、pre-commit-hooks4.6、codespell[toml]2.4.2——安装pip install google-adk[dev]即可获得这套工具链。类型检查是另一条独立流水线务必区分格式化/lint与类型检查格式问题由 pre-commit 与 lint CI 负责而类型错误由独立的 mypy CI 任务负责其配置在 pyproject.toml 的[tool.mypy]strict true、python_version 3.11、使用pydantic.mypy插件。因此pre-commit run --all-files通过只代表格式合格不代表类型检查通过。与导入规则的衔接80 字符的例外格式化指南特别强调 import 行是 80 字符限制的例外这与 imports 参考 完全对应isort配置了line_length 200见 pyproject.tomlpyink 对 import 行原样保留所以超长的from ... import ...保持单行仓库中不存在括号换行的 from-importisort的profile google强制一个名字一行且按大小写不敏感排序、不按类型分组分组固定为三段、空行分隔标准库 → 第三方 → 相对导入测试代码中google.adk经known_third_party声明被归入第三方组仅类型提示需要的导入放入if TYPE_CHECKING:块配合from __future__ import annotations避免运行时循环导入。失败排查速查表风格指南SKILL.md给出了钩子失败去哪里查的对照失败的检查参考文档check-new-py-prefixvisibility 参考_前缀与__init__.py导出规则compliance-checkslogging 参考logger 名称、typing 参考from __future__ import annotations、imports 参考cli/导入方向pyink、isort、ruff、addlicense、codespell本文即 formatting 参考Mypy Check CI 任务typing 参考工具链的安装pre-commit、addlicense等由adk-setup技能负责格式化相关问题则可直接对照本文与 pyproject.toml、.pre-commit-config.yaml 两份配置核查。小结ADK 的格式化体系可以概括为三层pyink isort负责怎么排版一系列 pre-commit 钩子负责提交前拦截CI 与版本固定的 dev 依赖保证本地与线上结果一致。对贡献者而言最实用的三句话是缩进永远 2 空格、行宽 80import 除外、提交前跑一遍pre-commit run --all-files。遇到钩子拒绝时按上表定位到对应参考文档规则细节则以 pyproject.toml 与 .pre-commit-config.yaml 为最终依据。【免费下载链接】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），仅供参考