Solon AI Skills 实战：用 MCP 把 AI Agent 从工具箱升级为企业级智能管家，TaoToken 统一 Key 打通多模型调用

1. 从工具箱到智能管家企业级 AI Agent 的真实困境很多团队在做 AI Agent 落地时都会经历一个相似的阶段一开始把几个工具函数注册给大模型Agent 能查天气、能算数、能调接口感觉挺美好。可一旦把它放进企业级业务里问题就全冒出来了。我把它总结成一句话工具箱式的 Agent只会被动等指令而企业要的是能主动编排任务的智能管家。先说最典型的三个坑。第一个是上下文噪音。传统 MCP 交互模式下无论用户问什么服务端都会把全部工具的 Schema 一次性塞进 Prompt。一个订单系统可能有查询、取消、退款、改地址、开发票等十几个工具光 Schema 定义就上千行。用户只是问一句你好模型却要先读完这一大堆工具描述Token 白白烧掉推理专注度也被稀释。实测下来工具数量超过 20 个之后模型选错工具的概率会明显上升。第二个是权限真空。模型对工具的可见性是全量的它不知道当前登录的是普通用户还是管理员。普通用户理论上不该看到删除订单这个操作但因为工具全量暴露模型完全可能被诱导去调用它。这在企业场景里是致命的。第三个是行为失控。工具只告诉模型能做什么却没法告诉它在当前背景下该怎么做。比如同样是取消订单VIP 租户和普通租户的规则完全不同但工具本身没有携带这种上下文约束模型只能靠猜。这三个问题的本质是 MCP 的静态化。MCP 协议本身是连接大模型与外部世界的标准桥梁这没错但它的默认交互模式是无状态、全量、被动的。而企业级业务需要的是有状态、按需、主动。Solon AI Skills 就是在这个背景下出现的。它把 MCP 封装成 Skill让技能具备感知能力——能根据 Prompt 上下文决定自己是否激活、注入什么指令、暴露哪些工具。这就从冷冰冰的 API 集合跨越到了具备感知能力的智能技能。这篇文章我会带你完整走一遍落地路径从 TaoToken 统一 Key 的配置到 MCP 服务注册再到 Solon AI Skills 的技能定义最后验证 Agent 的自主决策链路。每一步都有可复制的代码和配置你可以在本地直接复现。2. TaoToken 前置准备统一 Key 打通多模型调用在动手写 Skill 之前得先把模型调用这一层理顺。企业级 Agent 往往不会只用一个模型——复杂推理用强模型简单分类用便宜模型代码生成用专门的模型。如果每个模型都单独配 Key、单独改代码维护成本会非常高。TaoToken 在这里的作用就是提供一个统一的 API 入口用同一个 Key 调用多个模型。你只需要在配置里改 Model ID就能切换底层模型业务代码完全不用动。先拿到 Key。访问控制台创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建完之后你会得到一个以sk-开头的 Key。这个 Key 就是后面所有模型调用的凭证。接下来是 Base URL。TaoToken 的 API 地址是https://taotoken.net/api注意这里不要加 UTM 参数API 调用地址保持干净。现在把它配到 Solon AI 的模型配置里。Solon AI 的 ChatModel 支持自定义 OpenAI 兼容的 endpoint配置片段如下# app.yml solon: ai: chat: openai: api-key: sk-你的TaoToken密钥 base-url: https://taotoken.net/api model: claude-sonnet-4-20250514如果你用的是 Java 代码方式构建 ChatModel可以这样写import org.noear.solon.ai.chat.ChatModel; ChatModel chatModel ChatModel.of(https://taotoken.net/api) .apiKey(sk-你的TaoToken密钥) .model(claude-sonnet-4-20250514) .build();这里有个关键点Base URL、API Key、Model ID 这三件套必须配套出现。很多同学排障时只改了 Model ID 却忘了 Base URL 还指向别处结果一直报 401。我在下面第五节会专门讲这个。TaoToken 支持的主流模型包括 Claude 系列、GPT 系列、Gemini 系列等。你可以在模型对话页面先验证一下 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite在页面上选一个模型发一条测试消息如果能正常返回说明 Key 和 Base URL 都没问题。这一步别跳过后面 Skill 调试时如果出问题你至少能确定模型调用层是通的。对于需要长期跑 Agent 任务的场景建议用 Coding Plan它在长上下文和连续调用上的稳定性更好https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite配置好之后你的 Solon AI 应用就具备了统一调用多模型的能力。接下来我们进入 MCP 服务注册。3. 可复制配置MCP 服务注册与 Solon AI Skills 技能定义这一节是核心我会给出完整的 MCP 服务端和客户端配置。先明确架构服务端实现一个 OrderSkillServer它继承 McpSkillServer通过重写三个方法实现感知、挂载和动态分发客户端用 McpClientProvider 连接服务端再用 McpSkillClient 把它包装成 Solon AI Skill 注入到 ChatModel。先看服务端。这是具备感知力的技能实现import org.noear.solon.ai.annotation.ToolMapping; import org.noear.solon.ai.chat.prompt.Prompt; import org.noear.solon.ai.mcp.McpChannel; import org.noear.solon.ai.mcp.server.McpSkillServer; import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import java.util.ArrayList; import java.util.List; McpServerEndpoint(channel McpChannel.STREAMABLE_STATELESS, mcpEndpoint /skill/order) public class OrderSkillServer extends McpSkillServer { Override public boolean isSupported(Prompt prompt) { // 感知意图只有涉及订单且租户合规时才激活 return prompt.getUserContent().contains(订单) prompt.attr(tenant_id) ! null; } Override public String getInstruction(Prompt prompt) { // 动态指令注入租户特定的业务规则 return 你现在是租户[ prompt.attr(tenant_id) ]的订单助手。 取消订单前必须确认订单状态为待发货。; } Override public ListString getToolsName(Prompt prompt) { // 权限隔离根据用户角色动态下发工具名 ListString tools new ArrayList(); tools.add(OrderQuery); // 基础权限 if (ADMIN.equals(prompt.attr(user_role))) { tools.add(OrderCancel); // 仅管理员可见 } return tools; } ToolMapping(description 查询订单) public String OrderQuery(String id) { return 订单 id 状态待发货; } ToolMapping(description 取消订单) public String OrderCancel(String id) { return 订单 id 已取消; } }这里三个方法各司其职。isSupported决定技能是否激活getInstruction在技能挂载时注入行为准则getToolsName决定给模型看哪些工具。注意getToolsName返回的是工具名列表不是工具对象这样服务端就能根据角色做精准授权。再看客户端。开发者只需要注入业务属性不用操心工具过滤逻辑import org.noear.solon.ai.chat.ChatModel; import org.noear.solon.ai.chat.prompt.Prompt; import org.noear.solon.ai.mcp.McpChannel; import org.noear.solon.ai.mcp.client.McpClientProvider; import org.noear.solon.ai.mcp.client.McpSkillClient; // 构建 mcp 客户端 McpClientProvider mcpClient McpClientProvider.builder() .channel(McpChannel.STREAMABLE) .url(http://localhost:8081/skill/order) .build(); // 构建带有业务属性的提示词 Prompt prompt Prompt.of(帮我取消订单 A001) .attrPut(tenant_id, solon_001) .attrPut(user_role, ADMIN); // 注入技能模型将只看到管理员权限下的工具 chatModel.prompt(prompt) .options(o - o.skillAdd(new McpSkillClient(mcpClient))) .call();如果你用配置文件方式注册 MCP 服务可以写成 TOML[mcp.servers.order] channel STREAMABLE url http://localhost:8081/skill/order skill true或者 JSON 格式{ mcpServers: { order: { channel: STREAMABLE, url: http://localhost:8081/skill/order, skill: true } } }这里要强调三件套的完整性Base URL 指向 MCP 服务地址Key 用于模型调用Model ID 决定用哪个模型推理。三者缺一不可。MCP 服务本身不需要 Key但模型调用需要 TaoToken 的 Key。配置完成后你的 Agent 就具备了动态分发能力。当用户问帮我取消订单 A001时服务端会先判断意图是否涉及订单再根据 tenant_id 和 user_role 决定暴露哪些工具最后注入租户特定的指令。模型看到的工具列表是干净的、权限受控的、带上下文约束的。4. 验证请求跑通 Agent 自主决策链路配置写完了得验证它真的能跑通。这一节我会给出完整的验证步骤和预期结果。第一步启动 MCP 服务端。如果你用的是 Solon 应用直接运行 main 方法即可。服务端启动后会监听 8081 端口MCP endpoint 是/skill/order。第二步用 curl 验证 MCP 服务是否可达curl -X POST http://localhost:8081/skill/order \ -H Content-Type: application/json \ -d {jsonrpc:2.0,method:tools/list,id:1}如果返回工具列表说明服务端正常。注意这里返回的是全量工具因为 curl 请求没有携带 Prompt 上下文getToolsName的过滤逻辑不会生效。真正的过滤发生在模型调用时。第三步跑客户端验证。用下面的代码发起一次带业务属性的请求Prompt prompt Prompt.of(帮我取消订单 A001) .attrPut(tenant_id, solon_001) .attrPut(user_role, ADMIN); String result chatModel.prompt(prompt) .options(o - o.skillAdd(new McpSkillClient(mcpClient))) .call() .getMessage() .getContent(); System.out.println(result);预期结果是模型返回订单 A001 已取消。如果你把user_role改成USER再跑一次模型会告诉你没有权限取消订单因为它看不到OrderCancel这个工具。第四步验证多模型切换。把 Model ID 从claude-sonnet-4-20250514改成gpt-4o其他不变再跑一次。你会发现业务代码完全没动只是底层模型换了。这就是 TaoToken 统一 Key 的价值。第五步验证上下文纯净度。在服务端加一行日志打印getToolsName返回的列表。当user_role是USER时日志应该只显示[OrderQuery]当是ADMIN时显示[OrderQuery, OrderCancel]。这就证明动态分发生效了。实测下来这套链路跑通后Agent 的行为会发生质的变化。它不再是你问什么它查什么的被动工具而是根据你的身份和场景主动决定能做什么、该怎么做的智能管家。比如管理员说处理一下 A001Agent 会自动先查订单状态确认是待发货后再执行取消整个过程不需要你分步指令。如果你在验证过程中遇到模型不调用工具的情况先检查isSupported是否返回了 true。很多时候是 Prompt 里没有包含订单关键词导致技能根本没激活。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错这一节我整理了几个高频报错都是我在实际调试中踩过的坑。报错一401 Unauthorized这是最常见的。原因通常是三件套不匹配。检查清单检查项正确值常见错误Base URLhttps://taotoken.net/api带了 UTM 参数或末尾多了斜杠API Keysk-开头复制时带了空格或换行Model ID如 claude-sonnet-4-20250514拼写错误或用了不支持的模型名特别注意 Base URL 不要写成https://taotoken.net/api/末尾斜杠会导致部分客户端拼接出双斜杠触发 401。报错二local proxy failed这个报错通常出现在 MCP 客户端连接服务端时。原因是 MCP 服务地址不可达。检查服务端是否真的启动了端口是否被占用以及McpChannel.STREAMABLE是否和服务端的STREAMABLE_STATELESS匹配。如果服务端用的是 STATELESS客户端却用 STREAMABLE会握手失败。报错三reading choices 相关错误这个报错说明模型返回的响应格式不符合预期。常见原因是 Model ID 填错了比如把 Claude 的模型名填到了只支持 GPT 的 endpoint 上。TaoToken 虽然统一了入口但 Model ID 还是要和实际模型对应。去模型对话页面确认一下当前可用的模型名。报错四OAuth 相关报错如果你在 Claude Code 或类似工具里配置可能会遇到 OAuth 报错。这是因为工具默认走了 OAuth 流程而你需要改成 API Key 方式。在配置里明确指定{ apiKey: sk-你的TaoToken密钥, baseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514 }如果你用的是 Codex 的 auth.json格式类似{ openai: { apiKey: sk-你的TaoToken密钥, baseURL: https://taotoken.net/api } }报错五技能不激活如果isSupported一直返回 false检查 Prompt 的 attr 是否真的传进去了。attrPut要在Prompt.of之后、call之前调用。另外getUserContent()返回的是用户原始输入如果你在中间做了改写可能匹配不到关键词。排障时建议按这个顺序先确认模型调用通用模型对话页面测再确认 MCP 服务通用 curl 测最后确认 Skill 逻辑通看日志。一层一层来别跳步。6. 语义一致 CTA把统一 Key 接入你的 Agent 工程走到这里你已经有了一个能感知上下文、动态分发工具、按角色授权的 Solon AI Skills 服务。接下来就是把它接入你的实际工程。第一步把 TaoToken 的 Key 配到你的项目里。如果你还没有 Key去控制台创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite第二步参考接入文档把 MCP 服务注册到你的 Agent 框架里。文档里有不同语言的示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite第三步如果你用的是 Claude Code 做开发可以把 TaoToken 配成它的模型后端这样在写 Skill 代码时就能直接调用https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite第四步长期跑 Agent 任务的话Coding Plan 在并发和长上下文上更稳https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后说一个实用技巧。在服务端的getInstruction里你可以注入更复杂的业务规则比如取消订单前必须查询订单状态如果状态是已发货则提示用户联系客服。这样模型的行为就被约束在业务规则内不会乱来。这比在客户端写一堆 if-else 要优雅得多而且规则变更只需要改服务端客户端零改动。把 MCP 升级成 Skill 之后你的 Agent 架构会获得三个实实在在的好处上下文纯净度提升模型只看到该看的工具权限安全天然内建服务端感知角色做动态分发业务演进低耦合规则变更集中在服务端。这三条就是企业级智能管家和工具箱式 Agent 的本质区别。