adk-unit-guide

ADK 代码单元指南

代码单元指南是针对单个代码单元的细粒度使用文档，内容比 adk.dev 上发布的文档更深入，因此可以收录那些会让正式文档过于冗长的细节。读者希望在应用中调用该单元，因此应先展示可运行的代码。

代码单元指南聚焦公共 API 和调用方可见的行为。不要讨论内部实现细节，例如私有方法、内部状态机制或未导出的辅助函数。

语气

写作时应帮助读者理解，而不是居高临下地指示他们。

• 说明原因，而不只是规则。 每当指南说明一项限制、默认设置或建议时，都应说明原因。了解原因的读者可以处理指南未预料到的情况。
• 不要替读者做决定。 “大多数应用永远用不上这个”或“你很少会……”之类的表述是在替读者判断他们需要什么。应说明权衡，让读者自行选择。
• 从调用方的视角解释。 必须说明会发生什么，但不必解释实现这一行为的机制。如果解释必须依赖私有符号才能说清，那就超出了合适的层次。
• 篇幅应服务于理解。 目标不是简洁。读者会追问的地方，就给出答案；句意已经完整的地方，就此打住。
• 先讲问题，再讲语法。 先说明读者想做什么，再展示代码。
• 每个标题下方至少要有一个句子，然后才能出现下一个标题；每个代码块都要有一句介绍，说明它的作用。

句子层面的规则遵循 Google 开发者文档风格指南：使用现在时，不使用缩写，不使用括号插入语，改用逗号；不要以没有明确指代的“This”作主语，不使用 e.g. 或 etc.，不使用最高级，标题采用句首字母大写格式，标题层级不深于 H3。

差异示例

摘自 BaseNode 指南。修改前：

大多数应用从不继承 BaseNode，所以接下来的章节会先介绍设置。

这种表述替读者做了决定，也没有提供任何依据供读者判断自身情况。修改后：

通常应配置节点，而不是继承节点，因为下面的设置涵盖了大多数图所需的功能。如果你需要实现设置无法表达的行为，继承才有意义，这种情况会在最后介绍。

篇幅相同，事实相同。第二种表述说明了原因，让读者能够判断自己属于哪种情况。

再看一个例子，摘自 JoinNode 指南。修改前：

这里有三个任务并行处理同一输入，JoinNode 收集它们的结果。

这种开头偏口语化，不像文档，也没有提到读者可能会搜索的模式名称。修改后：

此示例构建了一个扇出/扇入工作流。三个任务并行处理同一输入，JoinNode 汇总它们的结果，以便最终节点将三者一并呈现。

输入

需要提供源文件，或在源文件中命名的类或方法。也要在文件存在时阅读其单元测试，以便参考其中的示例进行改写；还要阅读其设计文档 docs/design/{topic}/{unit}/index.md。

写作前分析

• 单元的用途和预期用法。
• 哪些类依赖它，以及它依赖哪些类。
• 该单元自身引入的配置选项，不包括继承的选项。
• 已知限制。
• 排除内部实现细节，例如私有方法和属性、内部辅助函数、私有执行状态或内部数据结构。

指南的存放位置

在 docs/guides/ 下镜像源文件路径，每个单元一个目录，指南命名为 index.md。移除私有模块开头的下划线：

源文件	指南
src/google/adk/workflow/_function_node.py	docs/guides/workflow/function_node/index.md
src/google/adk/plugins/reflect_retry_tool_plugin.py	docs/guides/plugins/reflect_retry_tool_plugin/index.md

只有当一个源文件确实有不同的使用模式时，才使用具名文件代替 index.md——docs/guides/agents/llm_agent/ 中的 single_turn.md 和 task.md 就是出于这个原因。

在原有指南中就地更新；对于代码未发生变化的部分，保留现有措辞，以便差异只显示实际改动。

然后在 docs/guides/README.md 的正确类别标题下添加指南，格式为 * [标题](path/index.md) - 单行摘要。。该索引是唯一的目录；未列入其中的指南将无法找到。

不需要编写指南的情况

scripts/check_new_py_files.py 会检查变更在 src/google/adk/ 下新增的 Python 文件是否符合此约定。它会直接跳过其中一部分文件，其余文件则可申请豁免；在编写规则并未要求的指南之前，请先确认属于哪种情况。

有三个子目录不受此规则约束，因为其中的内容不会发布： src/google/adk/internal/、src/google/adk/platform/internal/ 和 src/google/adk/v1/。

其他位置的文件可基于以下两个理由之一获得豁免。第一种是文件本身不构成独立单元，适用于 __init__.py 以及路径中包含 cli/ 或 utils/ 的文件。第二种是文件中包含的声明应写入使用它们的单元指南，而非另行编写指南；这适用于文件名以 _utils.py、_helper.py、_helpers.py、_types.py、_errors.py、_exceptions.py 或 _constants.py 结尾的文件。

如果没有任何包的 __init__.py 从某个模块导入内容或引用该模块名称，该模块也可豁免，因为它没有可供指南描述的公共接口。检查脚本会读取 src/google/adk/ 下的所有 __init__.py，惰性重新导出也会计入：包括 if TYPE_CHECKING: 下或 __getattr__ 中的导入，以及惰性导入表中指向该模块的字符串。模块是否以下划线 _ 开头并不影响判断；如果从新模块导出名称，就需要为该模块编写指南。

其他所有情况都需要指南或豁免。豁免标记为 NO_UNIT_GUIDE= 或 SKIP_UNIT_GUIDE=，后面须附上原因，这两个标记的作用完全相同。它们仅豁免单元指南要求；下划线 _ 前缀规则使用相同的钩子和错误报告，但完全没有豁免方式。一个标记会豁免此次变更新增的所有文件，而不仅是原因中提到的文件，因此，新增多个文件时，原因必须涵盖全部文件。

请写出能让审查者对照代码核实的理由，因为该标记将成为缺少指南的唯一记录：

NO_UNIT_GUIDE=InvocationNotFoundError is covered by docs/guides/errors/index.md.

豁免标签应放在哪里

标签通过提交消息或环境变量传递给检查，具体取决于提交是否已经存在。

提交创建后，标签会写入其消息中。持续集成会读取拉取请求所包含提交的消息，因此，贡献者在其中写入的豁免标签可以通过拉取请求的门禁检查。将标签放在行首，且 = 前不要留空格，因为检查会匹配行首内容。缩进的标签或列表项中的标签都不会被找到，而且不会有任何提示说明未能找到标签。

对于尚不存在的提交，标签通过环境变量传递：

NO_UNIT_GUIDE='covered by docs/guides/errors/index.md' git commit ...

如果提交前钩子阻止了提交，请使用这种形式。提交前钩子会在 git 将消息记录到任何位置之前运行，而检查不会改为读取上一次提交的消息，因此环境变量是唯一可用的传递方式。请将原因用引号括起来：未加引号的原因会在第一个空格处结束，shell 会把下一个单词当作要运行的命令，因此提交根本不会发生。也要将标签写入消息中，这样原因才能留在历史记录里，而不只存在于运行提交命令的 shell 中。

无论通过哪种方式传递，没有原因的标签都不会豁免任何内容。原因是这项决定唯一的记录，因此没有原因的豁免也就无从审查。

代码示例

• 在“快速入门”下提供一个简洁示例，并展示足够的周边类，以说明调用应放在哪里。如果存在单元测试，请从单元测试入手。
• 保留 google.adk 导入语句，因为导入路径是读者最容易抄错的内容。省略无关的标准库导入和 asyncio.run(main()) 运行器样板代码；它们对理解单元没有帮助。
• 展示开发者实际会编写的内容。只展示接口形式的示例，或驱动读者通常会通过 Runner 调用的服务的示例，都不适合放在指南中。
• 不要在示例 Agent 上设置 model=——指南应与模型无关，而且 docs/guides/ 中目前没有任何指南固定指定模型。
• 对于工作流节点，请用普通 Python 函数展示逻辑，而不是继承 BaseNode 的子类，除非用例确实需要子类。
• 使用 @node 装饰器将函数包装为节点，而不要直接使用 FunctionNode；演示 FunctionNode 配置本身时除外。

链接相关示例

从指南中使用相对于仓库的路径链接示例，而不是 GitHub URL： [Node Output](../../../../contributing/samples/workflows/node_output/agent.py)。 链接前请确认文件存在。

结构

请按章节遵循 references/guide-template.md。