# tool_schema_generator：Dart LLM工具Schema自动生成器，零样板代码对接OpenAI/Claude/Gemini

> Dart开发者构建AI Agent的利器，通过注解自动从Dart函数生成OpenAI、Anthropic、Gemini兼容的JSON Schema工具定义，支持类型推断、运行时注入和完整类型安全。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-04T15:44:16.000Z
- 最近活动: 2026-06-04T15:52:52.256Z
- 热度: 154.9
- 关键词: Dart, 代码生成, LLM, AI Agent, JSON Schema, OpenAI, Claude, Gemini, 工具调用, GitHub
- 页面链接: https://www.zingnex.cn/forum/thread/tool-schema-generator-dart-llmschema-openai-claude-gemini
- Canonical: https://www.zingnex.cn/forum/thread/tool-schema-generator-dart-llmschema-openai-claude-gemini
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：joedexdev
- 来源平台：github
- 原始标题：tool_schema_generator
- 原始链接：https://github.com/joedexdev/tool_schema_generator
- 来源发布时间/更新时间：2026-06-04T15:44:16Z

## 原作者与来源\n\n- **原作者/维护方**: joedexdev\n- **来源平台**: GitHub\n- **原始标题**: tool_schema_generator\n- **原始链接**: https://github.com/joedexdev/tool_schema_generator\n- **发布时间**: 2026年6月4日\n- **Pub.dev**: https://pub.dev/packages/tool_schema_generator\n\n---\n\n## 项目概述\n\ntool_schema_generator 是一个专为 Dart 开发者设计的代码生成工具，用于解决 AI Agent 开发中一个常见但繁琐的问题：为大型语言模型(LLM)编写和维护工具调用的 JSON Schema 定义。\n\n当你使用 Gemini、OpenAI、Claude 或其他 LLM 构建 AI Agent 时，通常需要向模型提供可调用的工具(函数)描述。传统做法是手动编写和维护特定厂商格式的 JSON 映射，这不仅枯燥而且容易出错。tool_schema_generator 让你只需编写标准的 Dart 函数并添加注解，即可自动生成精确的 LLM 工具 Schema。\n\n---\n\n## 核心特性解析\n\n### 1. 零样板代码\n\n工具自动从 Dart 语法推断类型、名称和可空性，无需手动编写重复的 Schema 定义。你的 Dart 函数签名本身就是 Schema 的单一事实来源。\n\n### 2. 完整的分析器支持\n\n支持 Dart 的所有常用类型：\n- 基础类型：`String`、`int`、`double`、`bool`\n- 集合类型：`List`、`Map`\n- 枚举类型：自动转换为 JSON Schema 字符串枚举\n- 自定义类：通过构造函数参数内省生成嵌套对象 Schema\n\n### 3. 多厂商 Schema 支持\n\n同一套 Dart 函数可同时生成三种主流 LLM 平台的工具定义：\n- **OpenAI**: 标准 function tool schema\n- **Anthropic**: 使用 input_schema 格式的 tool schema\n- **Gemini**: function declarations 格式\n\n### 4. 无缝集成\n\n使用 Dart 生态标准的 source_gen 组合构建器，输出到标准的 `.g.dart` 文件，可与 json_serializable 等其他代码生成器共存。\n\n### 5. 高度可定制\n\n- 通过 `@Tool()` 注解覆盖工具名称和描述\n- 自动从 Dart 文档注释提取描述\n- 使用 `@Describe()` 为参数添加详细说明\n- 通过 `@Inject()` 隐藏应用控制的参数，不让其出现在 LLM Schema 中\n\n---\n\n## 快速开始\n\n### 安装依赖\n\n在 `pubspec.yaml` 中添加：\n\n```yaml\ndependencies:\n  tool_schema_generator: ^0.4.0\n\ndev_dependencies:\n  build_runner: ^2.4.0\n```\n\n### 定义工具函数\n\n创建 Dart 文件并使用 `@Tool()` 注解标记顶层函数：\n\n```dart\n// lib/tools.dart\nimport 'package:tool_schema_generator/tool_schema_generator.dart';\n\n// 重要：声明 part 文件\npart 'tools.g.dart';\n\n/// 向特定用户发送邮件。\n@Tool()\nvoid sendEmail(\n  @Describe('收件人邮箱地址') String to,\n  @Describe('邮件主题') String subject, {\n  @Describe('邮件正文内容') required String body,\n  bool isHtml = false,\n}) {\n  // 你的业务逻辑\n}\n```\n\n### 运行代码生成\n\n```bash\ndart run build_runner build\n```\n\n生成器会创建 `tools.g.dart` 文件，其中包含 `toolRegistry` 实例。该注册表包含所有 Schema，并能自动将 LLM 的工具调用路由回你的 Dart 函数。\n\n---\n\n## 使用模式详解\n\n### 获取厂商特定 Schema\n\n```dart\n// OpenAI 格式\nfinal openAiTools = toolRegistry.schemasFor(SchemaFlavor.openAi);\n\n// Anthropic 格式\nfinal anthropicTools = toolRegistry.schemasFor(SchemaFlavor.anthropic);\n\n// Gemini 格式\nfinal geminiTools = toolRegistry.schemasFor(SchemaFlavor.gemini);\n\n// 获取单个工具的 OpenAI 格式 Schema\nfinal sendEmailSchema = toolRegistry.sendEmail;\n```\n\n### 执行工具调用\n\n当 LLM 返回工具调用请求时：\n\n```dart\nfinal value = await toolRegistry.call(\n  toolCall.name,      // LLM 返回的工具名称\n  toolCall.arguments  // LLM 返回的参数映射\n);\n```\n\n注册表会自动：\n1. 根据名称找到对应的 Dart 函数\n2. 验证所有参数类型和可空性\n3. 调用你的函数并等待结果\n4. 返回原始结果\n\n### 完整的 Agent 循环示例\n\n```dart\nimport 'tools.dart';\n\nvoid main() async {\n  // 1. 将 Schema 传递给 LLM\n  final response = await llm.generate(\n    prompt: \"向 hello@example.com 发送邮件说你好！\",\n    tools: toolRegistry.schemasFor(SchemaFlavor.openAi),\n  );\n\n  // 2. 当 LLM 决定调用工具时，分发执行\n  for (final toolCall in response.toolCalls) {\n    try {\n      final value = await toolRegistry.call(\n        toolCall.name,\n        toolCall.arguments,\n      );\n      print(\"工具返回: $value\");\n    } on ToolCallException catch (error) {\n      print(\"工具调用失败: ${error.message}\");\n    }\n  }\n}\n```\n\n---\n\n## 高级功能\n\n### 枚举类型处理\n\n枚举自动转换为 JSON Schema 字符串枚举：\n\n```dart\nenum Priority { low, normal, high }\n\n@Tool()\nvoid setTaskPriority(Priority priority) {}\n\n// 生成: {\"type\": \"string\", \"enum\": [\"low\", \"normal\", \"high\"]}\n```\n\n### 自定义类嵌套\n\n自定义类会被内省，生成器查看类的构造函数参数来构建嵌套 JSON Schema：\n\n```dart\nclass Location {\n  final double lat;\n  final double lng;\n  Location({required this.lat, required this.lng});\n}\n\n@Tool()\nvoid updateLocation(Location location) {}\n\n// 生成嵌套对象，包含 lat 和 lng 属性(均为必需)\n```\n\n### 覆盖工具元数据\n\n如果不希望使用 Dart 函数名或文档注释，可直接在注解中覆盖：\n\n```dart\n@Tool(\n  name: 'custom_search_tool',\n  description: '一个高度特定的搜索工具描述。'\n)\nvoid search(String query) {}\n```\n\n### 限制厂商支持\n\n默认情况下每个工具会为所有厂商生成。可以限制为特定厂商：\n\n```dart\n@Tool(flavors: [SchemaFlavor.anthropic])\nFuture<String> searchClaudeOnly(String query) async => '...';\n```\n\n### 运行时参数注入\n\n使用 `@Inject()` 注解标记应用控制的命名参数，这些参数不会出现在发给 LLM 的 Schema 中，但在调用时仍然可以从参数映射中读取：\n\n```dart\n@Tool()\nFuture<void> createTask(\n  @Describe('任务标题') String title, {\n  @Inject() String? userId,\n  @Inject() String locale = 'en',\n}) async {\n  // userId 和 locale 在这里可用，但只有 title 会出现在 Schema 中\n}\n\n// 调用时注入应用上下文\nfinal value = await toolRegistry.call(toolCall.name, {\n  ...toolCall.arguments,\n  'userId': currentUser.id,\n  'locale': request.locale,\n});\n```\n\n注入参数必须是可选的：可空、有 Dart 默认值，或两者兼有。\n\n---\n\n## 异常处理\n\n工具调用过程中的错误会被包装为类型化异常：\n\n- **ToolNotFoundException**: 找不到指定名称的工具\n- **MissingToolArgumentException**: 缺少必需参数\n- **InvalidToolArgumentException**: 参数类型无效\n- **ToolExecutionException**: 工具执行过程中出错\n\n这种设计让你可以精确处理不同类型的失败场景，向 LLM 提供有意义的错误反馈。\n\n---\n\n## 技术架构与设计理念\n\n### 类型安全优先\n\ntool_schema_generator 的核心设计哲学是"类型即契约"。通过利用 Dart 的静态类型系统，工具在编译期就能捕获大量潜在错误，而不是等到运行时才发现 Schema 不匹配。\n\n### 单一事实来源\n\n你的 Dart 函数定义同时是：\n- 业务逻辑的实现\n- API 契约的定义\n- LLM Schema 的模板\n\n这种统一消除了传统方案中函数签名、文档、Schema 定义三者不一致的问题。\n\n### 渐进式采用\n\n工具设计为可渐进式采用：\n- 可以从单个工具开始，逐步扩展\n- 可以与现有的代码生成器共存\n- 可以选择性使用高级功能如参数注入\n\n---\n\n## 适用场景与价值\n\n### 典型应用场景\n\n1. **AI 助手开发**: 为聊天机器人添加发送邮件、查询数据库、调用 API 等能力\n2. **自动化工作流**: 让 LLM 驱动复杂的业务操作序列\n3. **智能客服系统**: 集成订单查询、退款处理、知识库检索等工具\n4. **内部工具平台**: 构建自然语言驱动的企业工具调用层\n\n### 核心价值主张\n\n- **开发效率**: 消除手写和维护 JSON Schema 的重复劳动\n- **类型安全**: 编译期保证 Dart 代码与 LLM Schema 的一致性\n- **跨平台**: 一套 Dart 代码同时支持三大主流 LLM 平台\n- **可维护性**: 代码即文档，函数签名变更自动同步到 Schema\n\n---\n\n## 关键要点总结\n\ntool_schema_generator 为 Dart 生态填补了 AI Agent 开发的重要拼图：\n\n1. **问题定位精准**: 解决 Dart 开发者在 LLM 工具集成中的样板代码痛点\n2. **技术方案优雅**: 利用 Dart 注解和代码生成实现声明式工具定义\n3. **生态集成完善**: 与 source_gen、build_runner 等标准工具无缝协作\n4. **多平台支持**: 同时覆盖 OpenAI、Anthropic、Gemini 三大主流平台\n5. **生产就绪**: 提供完整的异常处理、参数注入和类型安全保证\n\n对于使用 Dart/Flutter 构建 AI 应用的开发者，这是目前最成熟的 LLM 工具 Schema 生成方案。