AI Agent Engineer

AI Agent Engineer

综合扩展设计评审

6 min read

综合扩展设计评审

实践目标

针对一个真实扩展需求，先完成源码证据驱动的设计评审，再决定是否实施。重点是证明“为什么放在这里”和“最小修改面是什么”。

前置知识

  • 已完成只读 Tool plugin；
  • 已读全部扩展开发文档；
  • 能从源码和测试区分已确认事实、推断和未知。

选择一个题目

推荐三选一：

A. 企业内部知识查询

需求：查询一个已有 HTTP 服务中的内部文档。

要判断：

  • 原生 Tool 还是 MCP；
  • 私网 SSRF allowlist；
  • token 配置；
  • read-only 与 rate limit；
  • 结果截断和引用。

B. 新的 OpenAI-compatible 模型平台

需求：接入一个还未注册、但声称兼容 OpenAI 的 Provider。

要判断：

  • custom 是否已经足够；
  • 是否需要 ProviderSpec；
  • Tool Call/stream/reasoning 的真实兼容度；
  • retry metadata；
  • registry 顺序。

C. Webhook 聊天平台

需求：接收 HTTP POST 并把结果回调到外部系统。

要判断：

  • Channel plugin；
  • sender/chat/session identity；
  • authentication、pairing 和 replay；
  • start/stop；
  • delivery retry 与幂等性；
  • SSRF 和 callback allowlist。

必须阅读的代码

根据题目选择：

题目核心源码对照测试
Aagent/tools/web.py、agent/tools/mcp.py、security/network.pytests/tools/test_web_fetch_security.py、test_mcp_tool.py
Bproviders/registry.py、openai_compat_provider.py、factory.py一个简单 Provider test + test_provider_retry.py
Cchannels/base.py、registry.py、manager.pytest_base_channel.py、test_channel_plugins.py

预期观察

完成阅读后，你通常应观察到：

  • 大多数扩展首先落在边缘 adapter、registry 或 plugin contract，而不是 AgentLoop；
  • “能连接”只证明 transport，schema、生命周期、取消、重试和安全仍是独立契约；
  • 配置、发现、运行和展示可能由不同模块负责，修改矩阵不会只有一个文件；
  • 需求描述中会存在源码无法证明的外部协议事实，这些必须保留为“待确认”；
  • 一个可靠方案应能用纯函数/contract test 覆盖大部分行为，只把真实服务留给最后的 smoke test。

交付物一：边界决策

填写：

问题结论源码/文档证据未知
扩展类型
谁发现它
输入契约
输出契约
配置位置
生命周期
安全边界

至少列出一个被否决的替代方案和具体原因。

交付物二：调用链

画一张 Mermaid 图，至少包含：

  • 外部入口；
  • adapter；
  • nanobot core 边界；
  • 状态/消息变化；
  • 结果返回；
  • 错误路径。

不要画不存在的 service。无法从代码确认的节点标“待确认”。

交付物三：最小修改矩阵

文件/包修改目的必须/可选对应测试

要求：

  • core loop.py/runner.py 若要修改，必须解释为什么 edge adapter 无法解决；
  • 配置、注册、测试和文档必须成对；
  • 不因“以后可能用到”新增抽象层。

交付物四：失败模式

至少分析：

  1. 参数不合法；
  2. 认证失败；
  3. timeout/cancel；
  4. 重复请求；
  5. 部分输出后失败；
  6. 进程关闭；
  7. secret 泄漏；
  8. 越权或 SSRF；
  9. 版本/协议不兼容。

对每项写：

  • 可观察现象；
  • 处理层；
  • 是否重试；
  • 是否幂等；
  • 测试方法。

交付物五：测试金字塔

flowchart BT
    A["纯函数 / schema tests"] --> B["Adapter contract tests"]
    B --> C["AgentLoop / Registry integration"]
    C --> D["一个真实 smoke test"]

真实服务只放在顶部，不让网络替代底层确定性测试。

完成条件

  • 五份交付物齐全；
  • 每个实现事实有源码、测试或官方文档位置；
  • 未知项明确列出；
  • 修改范围能在一次小 PR 中完成；
  • 安全和回滚方案可操作；
  • 同行只看设计即可复述完整调用链。

验证方法

用以下问题做自我评审：

  • 删除一个拟新增文件，方案还能成立吗？
  • 不修改 AgentLoop，是否有 edge 实现？
  • 是否把真实服务错误与模型错误混在一起？
  • 是否考虑了已有 streaming/cancellation/fallback？
  • 测试是否会意外访问网络或真实账号？
  • 文档是否说明了用户需要配置什么，而非只列代码类名？

复盘问题

  1. 你最初选择的扩展类型是否改变？证据是什么？
  2. 哪个未知项会真正改变设计？
  3. 哪个测试最早暴露契约错误？
  4. 哪个修改最可能导致 core 与运行表面耦合？

完成后进入 速查参考，把常用入口固化为自己的源码索引。

Backlinks