adk-review

ADK 变更审查员

根据以下七个维度审查工作树差异，报告问题，然后停止。仅修复用户随后要求修复的内容。

工作流

1. 运行 git status 和 git diff（对于已暂存的工作，添加 --staged），获取新增、修改和删除文件的准确列表。
2. 根据检查清单逐个审查差异中的文件。
3. 按照下方格式输出报告。
4. 停止。不要编辑任何文件，也不要提出代为编辑。等待用户提出请求。
5. 如果用户要求修复，请应用修复，然后重新运行受影响的测试（pytest tests/unittests/{path}）和 pre-commit run --files {paths}。

第 4 步最容易出错：未经请求就进行修复，会掩盖用户要求指出的问题，并将审查结果与新产生的、尚未审查的修改混在一起。

检查清单

1. 正确性

• 类型：不得引入新的 mypy 错误。CI 会将 mypy 输出与基分支进行比较，并且只会因新引入的错误而失败。因此，已修改文件中的既有错误不构成阻碍，但新错误会。
• 导入：不得存在循环导入；模块已使用绝对导入时，也应使用绝对导入。
• 异常：不得使用裸 except:；应捕获特定类型的异常，并记录足够的上下文以识别调用方。
• 类型判别：读取对象的特定类型属性前，先检查对象类型（例如，检查节点是否为 LlmAgent，再检查 mode），确保遇到意外的节点类型时不会抛出异常。
• 边界情况：通过验证或回退默认值处理 None、空集合、零和空字符串。
• 前置条件：在核心逻辑运行前检查状态不变量。

2. 设计

• 复杂度：将拆分后会更清晰的函数或类拆分开。
• 耦合：保持高内聚、低耦合；不得引入反模式。
• 性能：检查冗余计算、循环中的重复 I/O，以及不必要的随输入规模增长的内存分配。
• 安全性：验证输入；不得记录敏感数据；不得存在注入、资源耗尽或内部状态暴露风险。

3. 风格

按照 adk-style 技能检查差异，而不要在此重复其规则：可见性和 _ 前缀、类型标注、Pydantic v2 模式、延迟日志记录、导入、异步和文件组织。

确认修改的文件通过 pre-commit run --files {paths} 检查。

4. 架构和意外后果

• 公共 API 稳定性：此更改是否修改、移除或缩小了 src/google/adk/ 下的公共接口、类、方法、参数列表或 CLI 表面？破坏性更改必须先经历弃用周期，因为该软件包采用语义化版本控制发布，用户会固定使用次版本。
• Session、Artifact 和 Memory 服务更改：向 Session、ArtifactVersion、MemoryEntry，或 BaseSessionService、BaseArtifactService、BaseMemoryService 及其架构中添加任何新字段，都属于破坏性更改（即使该字段是可选的或有默认值），因为现有的下游存储子类和外部后端不会持久化或反序列化未知字段，从而导致重新加载时状态悄然丢失。
• 执行和恢复：对工作流、节点或状态的更改必须与事件执行生命周期以及会话恢复（人工介入步骤和检查点）保持兼容。请参阅 adk-architecture 技能。
• 并发和生命周期：不得存在竞态条件；插件、导出器和连接在所有路径（包括错误路径）上都必须关闭。
• 数据库和运行时 DDL 安全性：运行时启动路径（例如 DatabaseSessionService.prepare_tables() 和 _ensure_schema_indexes_exist()）绝不能执行破坏性 DDL，例如 DROP INDEX（它会获取 ACCESS EXCLUSIVE 锁，并破坏滚动部署或回滚）。任何增量运行时 DDL 都必须考虑多容器启动竞态（进程内的 asyncio.Lock 无法避免 checkfirst=True 上跨容器的 TOCTOU 竞态），因此创建操作必须包装在 SAVEPOINT（connection.begin_nested()）中，并能容忍并发创建。
• 范围：修复不需要的新公共名称、参数或标志；默认保留错误行为的标志；只在一个调用方需要时却在共享层修复；为匹配新行为而修改现有测试断言。

5. 文档影响

• 面向用户的文档位于单独的 adk-docs 仓库中，因此面向用户的更改也需要在该仓库中提交 PR；请在报告中注明。
• 当公共 API 或工作流模式发生变化时，可能需要更新 docs/guides/ 下的指南。
• 如果更改改变了某个代码单元的设计约定，该单元的设计文档由 adk-unit-design 技能负责维护。

6. 示例

• contributing/samples/ 下的现有示例在此更改后是否仍能运行？
• 新功能是否值得新增示例？如果是，请遵循 adk-sample-creator 约定。

7. 测试

• 每条新增或修改的代码路径都必须在 tests/unittests/ 下有测试。
• 新测试应放在对应代码单元现有的 test_{module}*.py 文件中，而不是放在以更改命名的文件中，以免分散该单元的测试覆盖。
• 测试应遵循 adk-style 测试参考中的规则：每个测试只验证一种行为；测试名称描述行为；不对私有属性进行断言；使用最少的 fixture；遵循 arrange/act/assert 结构。

为每项发现提供依据

报告发现前，应通过基类解析符号（Event 扩展自 LlmResponse）。对于正确性问题，请指出导致失败的输入；对于其他问题，请引用其违反的规则或约定。既不符合这两种情况的发现只是猜测，应予以省略。

报告格式

按优先级对发现分组，并为每项发现提供文件路径和行号。没有内容的类别不要报告。

• 🔴 严重：Bug、类型错误、竞态条件、资源泄漏、安全问题。
• 🟠 设计：复杂性、可读性、性能、架构不一致。
• 🟡 风格：Lint、格式、非惰性日志记录、类型不匹配。
• 🔵 文档、测试、示例：覆盖缺失或过时，指南、示例。