AI 智能体构建器

本页是使用 DevUtilities AI 智能体构建器构建 LLM 智能体的权威指南。阅读时可使用上方引导工作流，或跳转到下方主题。Schemas、MCP JSON、提示词与 Token 计数均留在浏览器本地——不会上传用于推理。

AI 智能体构建器是一个客户端工作坊，用于组装生产就绪的智能体配置：面向 OpenAI function calling 的 JSON Schema 工具、面向 Cursor 与 Claude Desktop 的 mcpServers 校验、system prompts、合计 Token 预算，以及可导出的团队交接产物。

你能得到什么

• 四种工作流模式：完整智能体、仅 function calling、MCP 配置、结构化响应
• 入门模板：Filesystem MCP、OpenAI function calling、结构化分类器
• 示例 JSON → JSON Schema 推断，可选严格 additionalProperties: false
• 带 JSON-pointer 错误与警告的本地 MCP lint
• 跨提示词、压缩后的 tools 与 MCP JSON 的合计 Token 预算
• 导出：OpenAI tools JSON、response_format、MCP 配置、markdown 摘要、完整 bundle

在以下情况使用此构建器

• 需要 OpenAI tools JSON，又不想手写 JSON Schema
• 正在接入 Cursor 或 Claude Desktop MCP 服务器，并希望粘贴前先 lint
• 必须证明智能体的 prompt + tools 仍能放入上下文窗口
• 希望一次持久会话串联 schema → MCP → prompt → export

在以下情况优先使用独立工具

• 只需深度编码对比或成本计算 → LLM Token Counter
• 只需无提示词的一次性 MCP lint → MCP Validator
• 只需从样本推断 Schema → Structured Output Generator

定义 tools 之前先选择模式。模式会隐藏无关步骤，避免与空面板纠缠。

完整智能体的首次演练。模板快捷方式会跳过其中若干步骤。

1. 选择完整智能体（或加载 OpenAI function calling 模板）。
2. 在定义 tools 中，为每个工具添加清晰名称、描述与有代表性的示例 JSON 参数。
3. 检查推断出的 JSON Schema——为 OpenAI structured outputs / strict tool calling 启用严格模式。
4. 若智能体将在 Cursor 或 Claude Desktop 中运行，粘贴或编辑 mcpServers JSON；继续前修复所有错误。
5. 编写 system instructions，告诉模型何时调用哪个工具，以及绝不可编造什么。
6. 打开 Token 预算，选择 cl100k_base 或 o200k_base，确认合计适合你的模型。
7. 导出 API 用的 OpenAI tools JSON、桌面客户端用的 MCP 配置，以及团队用的 markdown 摘要。
8. 可选导出完整 bundle JSON，以便其他工程师稍后重新加载同一会话状态。

问题：你需要一个可通过 OpenAI function calling 查询天气与订单的客服智能体，但手写 JSON Schema 仍无法通过严格校验。

本工具如何解决

1. 选择 Function calling 模式，或加载 OpenAI function calling 模板（天气 + 订单查询）。
2. 编辑示例 JSON，使生产所需的每个字段至少出现一次——缺失的键不会成为 required 属性。
3. 启用严格模式，使每个对象都输出 additionalProperties: false。
4. 收紧 system prompt：确认订单 ID，绝不编造工具结果，保持回复简洁。
5. 若部署在 GPT-4o 上，在 o200k_base 下检查 Token 预算。
6. 导出 OpenAI tools JSON，并粘贴到 Chat Completions 或 Responses API 客户端。

结果：严格且可直接用于 API 的 tools 数组，以及与 Schema 匹配的提示词——无需单独的 Schema 编辑器。

问题：Cursor 或 Claude Desktop 拒绝你的 mcp.json，或文件系统服务器以错误目录启动，可见磁盘范围过大。

本工具如何解决

1. 选择 MCP 配置模式，或加载 Filesystem MCP 模板。
2. 将 /path/to/allowed/dir 替换为智能体唯一可访问目录的绝对路径。
3. 运行校验——修复缺失的 command/args、无效 URL，以及非字符串 env 值。
4. 在浏览器中 lint 时使用占位 env 值（非生产密钥）。
5. 将已校验的 mcpServers JSON 导出到 Cursor 或 Claude Desktop 配置。
6. 添加要求在破坏性文件操作前确认的 system instructions。

结果：已 lint 的 MCP 客户端配置，以及在重启桌面应用前与服务器能力匹配的提示词。

问题：你需要模型以 JSON 返回情感、置信度、主题与简短摘要——自由文本会破坏下游解析器。

本工具如何解决

1. 选择结构化响应模式，或加载结构化分类器模板。
2. 编辑示例 JSON，使其精确匹配流水线期望的形状。
3. 启用严格模式，使未声明的键在校验时被拒绝。
4. 编写禁止 JSON 对象之外散文的 system prompt。
5. 导出面向 OpenAI structured outputs 的 response_format json_schema。
6. 确认 Token 预算仍为待分类的输入文档留有空间。

结果：可连同匹配指令一并放入 structured-output API 的单一输出 Schema。

问题：加入三个工具与较长 MCP 配置后，一旦包含聊天历史，智能体合计提示词不再适合 GPT-4o 的实用预算。

本工具如何解决

1. 打开 Token 预算步骤，记录 prompt + 压缩后的 tools + MCP JSON 的合计。
2. 缩短工具描述，并删除会膨胀 required Schema 的未使用示例字段。
3. 将冗长策略文本移出始终开启的 system prompt，改为按需检索。
4. 若只需更深的编码计算，将组装好的 payload 复制到 LLM Token Counter。
5. 仅在预算显示对历史与 completions 有充足余量后再重新导出。

结果：在构建器中捕获溢出——而不是在生产环境第一次 400 错误之后。

示例 JSON 必须是严格 JSON。只有示例中出现的键会成为 required 属性。嵌套对象与数组从样本值推断类型。

经验法则

• 包含模型应被允许发送的每个字段——省略表示“非 required”，不是“带 default 的可选”。
• 用现实的 enum 作为字符串样本，若需要显式 enum 数组再手改 Schema。
• 启用严格模式，使每个对象输出 additionalProperties: false——推荐用于 OpenAI structured outputs 与 strict tool calling。
• 空数组会推断出弱 item 类型——至少添加一个代表性元素。

Stdio 服务器需要 command，通常还需要 args。远程服务器需要有效的 http 或 https url。env 值必须是字符串。错误会阻断导出信心；警告值得人工过一遍。

常见客户端信封

• 顶层键必须是 Cursor 与 Claude Desktop 约定的 "mcpServers"
• 文件系统服务器应使用绝对路径 allow-list
• 在浏览器中编辑时优先使用 env 占位符；仅在本地机器注入真实密钥

Token 计数合并 system prompt、压缩后的工具 Schema 与 MCP JSON。GPT-4 / Claude 近似选 cl100k_base，GPT-4o 选 o200k_base。计数使用本地 tiktoken 表——无 API 调用。

• 将数字视为下限：聊天历史与工具结果会在运行时继续增加
• 每次编辑 Schema 或提示词后重新检查
• 需要边界图或自定义 payload 的月度成本卡时，使用 LLM Token Counter

症状：OpenAI 拒绝 tools payload，或模型无法传递应用实际需要的参数。

原因

严格 Schema 会拒绝未声明的键。若示例 JSON 省略了字段，它永远不会成为属性。若关闭严格模式，OpenAI structured-output 限制仍可能拒绝开放对象。

诊断

将推断 Schema 的 properties 与应用发送的参数对比。面向 OpenAI structured outputs 时确认已启用严格模式。

修复

1. 将缺失键加入示例 JSON 并重新生成 Schema。
2. 启用严格模式，使嵌套对象上的 additionalProperties: false 保持一致。
3. 按 OpenAI structured output 限制缩短不支持的构造（深层嵌套 oneOf、奇特类型）。
4. 重新导出 tools JSON，并用已知正确的参数 payload 重测。

症状：command/url 校验错误、客户端无法启动服务器，或远程传输始终连不上。

原因

缺少 command 的 stdio、缺少 http(s) URL 的远程项、数值型 env，或错误的顶层键会破坏客户端解析器。

诊断

阅读每条 lint 错误的 JSON pointer。确认信封使用 mcpServers，且每个服务器要么是 stdio（command）要么是远程（url），而非损坏的混合体。

修复

1. 为 stdio 服务器添加 command 与 args；将所有 env 值写成字符串。
2. 远程 MCP 传输使用 http:// 或 https:// URL。
3. 将顶层键名修正为 mcpServers。
4. 重新校验直至无错误；上线前处理警告。

症状：API 密钥出现在导出的 JSON、git diff 或构建器截图中。

原因

MCP env 块是纯 JSON。即使是本地浏览器工具，粘贴生产密钥也会通过剪贴板、屏幕共享与误提交增加泄露风险。

诊断

在导出与 MCP 面板中搜索 sk-、Bearer 或厂商密钥模式。确认已提交的配置仅含占位符。

修复

1. 在构建器中用 ${ENV_VAR} 风格占位符替换密钥。
2. 仅在本地桌面客户端或部署密钥库中注入真实值。
3. 轮换曾粘贴到聊天、工单或共享屏幕的任何密钥。
4. 为 mcp.json 与智能体 bundle 文件添加 pre-commit 密钥扫描。

此工作区不会上传你的配置——但剪贴板与 git 仍可能泄露。

• 切勿在 MCP env 块中提交 API 密钥——使用环境变量占位符
• 为文件系统 MCP 服务器使用绝对、最小权限路径
• 向生产提示词添加大型 few-shot 示例前先检查 Token 预算
• 优先使用严格 Schema，防止 tools 接受意外键
• 若导出 bundle 含内部工具名或基础设施主机，按敏感信息处理

• 从模板开始，再删除不需要的 tools——更小的 Schema 更便宜也更安全
• 用与 system prompt 指令匹配的清晰动词命名 tools（lookup_order、get_weather）
• 保持单一事实来源：从此构建器导出，而不是维护分叉的 Schema 副本
• 每次更改路径或 command 后重新校验 MCP
• 在 markdown 导出中记录 Token 预算，让审阅者在 PR 中看到成本影响
• 深度编码差异用 LLM Token Counter；组装好的智能体用此构建器