Nadav's 算法之旅

本章以虚构的 FastLLM 服务为例，分三步实现完整的模型适配器：先搭建非流式调用与配套 Formatter，再扩展支持 SSE 流式响应及增量累积解析，最后通过将 Pydantic 模型伪装为工具调用实现结构化输出。全文贯穿 Model 与 Formatter 分离的设计理念，帮助读者掌握接入任意大模型 API 的开发流程。

本章从零构建一个 SQLite 数据库查询工具，分别实现同步返回完整结果的版本和基于 AsyncGenerator 逐行输出的流式版本。工具注册时框架自动从函数签名与 docstring 生成 JSON Schema，通过 preset_kwargs 机制隐藏数据库路径等敏感配置。最后演示工具集成到 ReActAgent 的完整流程，并附带缓存中间件优化练习。

本章手把手搭建 AgentScope 二次开发环境，涵盖仓库克隆与开发模式安装、pre-commit 钩子链配置、测试目录结构与异步测试模式解读，以及代码规范速查。通过三个无需 API Key 的验证步骤确认环境就绪，为后续自定义 Tool、Memory、Agent 等扩展开发提供可靠的工作台基础。

本章讲解 AgentScope 基于 OpenTelemetry 的全链路追踪系统，涵盖五种专用追踪装饰器的层级设计与零开销开关机制，并回顾 StateModule 持久化如何支持断点续跑与状态回放，解决长时间运行 Agent 的排障难题。

解析 MsgHub 实现的发布-订阅广播机制：AgentBase 维护订阅者字典，__call__ 在回复后自动广播并移除思考块防止信息泄漏，MsgHub 作为异步上下文管理器统一注册与清理订阅关系，实现多 Agent 间的松耦合通信。

本章剖析 Toolkit 中间件的洋葱模型实现：_apply_middlewares 在每次调用时动态组装中间件链，先注册的处于最外层，支持日志记录、权限检查和缓存三种典型用法，在不修改工具函数的前提下插入通用逻辑。

详解 _parse_tool_function 如何将 Python 函数签名与 Google 风格 docstring 自动转换为 JSON Schema，利用 inspect 提取类型信息、Pydantic create_model 动态构建验证模型，并支持运行时 Schema 扩展。

以 Formatter 为例讲解策略模式如何将 API 格式转换与模型调用解耦，结合模板方法模式在 TruncatedFormatterBase 中定义格式化骨架，并对比 OpenAI 与 Anthropic 的 JSON 结构差异。

深入解析 Hook 系统的元类实现：_AgentMeta 在类定义时自动包装 reply 等方法，_wrap_with_hooks 提供防重入保护与链式执行，参数归一化让 Hook 能安全修改调用参数，_ReActAgentMeta 进一步扩展 reasoning 与 acting 钩子点。

以"记忆丢失"Bug 为线索，逐层拆解从 StateModule 到 ReActAgent 的四层继承链，解析每层的职责边界与序列化协作机制，帮助读者掌握对象状态持久化的排查思路。