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；组装好的智能體用此构建器