1. 为什么你的 Agent 越写越像 2015 年的 Servlet如果你正在用 Spring AI 做 Java Agent大概率经历过这个阶段一开始写个 ChatService 调模型觉得挺爽然后加 Function Calling函数越堆越多接着开始写 if-else 判断该调哪个工具再后来接 MCP、接外部 API代码彻底变成一团乱麻。改一个功能牵一发动全身。Anthropic 发布的 Agent Skills 规范给了另一条路Agent 的能力不该靠代码逻辑驱动应该靠文件驱动。一个 Skill 就是一个文件夹核心是SKILL.md里面写清楚这个技能做什么、审查哪些维度、输出什么格式、参考哪些规范。Agent 运行时读取SKILL.md理解任务调用脚本执行按格式输出。整个过程不需要你硬编码任何编排逻辑。Spring AI 的 Agentic Patterns 把这套规范融进了 Spring 生态对 Java 开发者来说意味着可以用Service管理 Skill 生命周期同时保留文件驱动的执行方式。但真正消耗 Token 的地方是 Spring AI 侧驱动SKILL.md执行时的那次模型调用。这一步需要模型通道也就是 Base URL 和 API Key。这篇就围绕这个接入配置槽来写把原文里“去各家模型平台申请 Key、拼模型地址”那一步换成 TaoToken 通道然后在 Spring AI 的模型客户端里配好 Base URL 和 Key跑通 CodeReviewSkill 的SKILL.md执行流程。文件驱动执行仍然由 Spring AI/Skills 负责TaoToken 只提供 Key 和 Base URL。2. TaoToken 通道前置准备Key 和 Base URL 怎么拿在改 Spring AI 配置之前先把通道准备好。这一步不复杂但有两个细节容易踩坑Base URL 不要加/v1也不要用带 UTM 的官网地址。2.1 注册并创建 TaoToken Key打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册登录后进入控制台创建 API Key。创建入口在https://taotoken.net/consoleKey 的管理页面在https://taotoken.net/api-keys创建时建议给 Key 起一个能识别的名字比如spring-ai-agent-skill方便后面在多个环境里区分。创建完成后复制 Key只显示一次丢了就重新建一个。2.2 Base URL 的正确写法Spring AI 的模型客户端配置里Base URL 填https://taotoken.net/api注意两点不要在后面加/v1也不要用带 UTM 参数的官网地址。官网地址是给人看的落地页API 地址是给程序调用的两者不要混。如果你在配置文件里写了https://taotoken.net/api/v1请求路径会拼错模型调用直接失败。提示TaoToken 的 API 地址统一用https://taotoken.net/api不要带任何查询参数。UTM 只用于官网落地页统计不要写进代码或配置文件。2.3 模型对话和文档入口如果你想先在网页上验证 Key 是否可用可以用模型对话页面https://taotoken.net/model-chat接入文档在https://taotoken.net/doc如果你后面要做长期编码或 Agent 任务可以了解 Coding Planhttps://taotoken.net/coding-plan3. Spring AI 侧的可复制配置把模型通道接进 Agent Skill这一章是核心。Spring AI 的模型客户端配置方式取决于你用的版本和 starter下面给一套通用的application.yml配置以及对应的 Java 配置类写法。你按自己的 Spring AI 版本微调即可。3.1 application.yml 配置spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.2这里把base-url指向 TaoToken 的 API 地址api-key从环境变量读取避免把 Key 硬编码进仓库。model按你实际可用的模型名填temperature在代码审查场景建议低一点输出更稳定。环境变量在启动前设置export TAOTOKEN_API_KEY你的 TaoToken KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的 TaoToken Key3.2 Java 配置类显式构建 ChatClient如果你不想依赖自动配置或者需要多个模型客户端可以显式构建import org.springframework.ai.openai.OpenAiChatModel; import org.springframework.ai.openai.OpenAiChatOptions; import org.springframework.ai.openai.api.OpenAiApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class ModelConfig { Bean public OpenAiApi openAiApi() { return OpenAiApi.builder() .baseUrl(https://taotoken.net/api) .apiKey(System.getenv(TAOTOKEN_API_KEY)) .build(); } Bean public OpenAiChatModel openAiChatModel(OpenAiApi openAiApi) { return OpenAiChatModel.builder() .openAiApi(openAiApi) .defaultOptions(OpenAiChatOptions.builder() .model(gpt-4o-mini) .temperature(0.2) .build()) .build(); } }这段配置的作用是Spring AI 在驱动 Skill 执行时所有模型调用都会走https://taotoken.net/apiKey 用你创建的 TaoToken Key。Skill 的文件读取、SKILL.md解析、脚本调用仍然由 Spring AI/Skills 负责TaoToken 只承担模型通道。3.3 CodeReviewSkill 的 SKILL.md 结构在src/main/resources/skills/code-review/下放一个SKILL.md# Code Review Skill ## 描述 审查 Java 代码的安全性和性能问题。 ## 审查维度 - SQL 注入风险 - 空指针异常 - 线程安全问题 - 资源未关闭 ## 输出格式 Markdown 报告包含问题列表、严重级别、修复建议。 ## 参考规范 见 references/java-security.mdSpring AI 侧读取这个文件后会把内容作为上下文传给模型模型按SKILL.md里的要求执行审查。你不需要在 Java 代码里写“如果发现 SQL 注入就输出什么”这些都在 Markdown 里声明。3.4 Skill 执行入口的 Java 写法import org.springframework.ai.chat.client.ChatClient; import org.springframework.stereotype.Service; Service public class CodeReviewSkill { private final ChatClient chatClient; public CodeReviewSkill(ChatClient.Builder builder) { this.chatClient builder.build(); } public String review(String javaCode) { String skillMd SkillLoader.load(skills/code-review/SKILL.md); return chatClient.prompt() .system(skillMd) .user(请审查以下 Java 代码\n javaCode) .call() .content(); } }SkillLoader负责从 classpath 读取SKILL.md你可以用ClassPathResource实现。核心点是模型调用走的是上面配置的 TaoToken 通道Skill 的执行逻辑由SKILL.md驱动。4. 验证请求跑通 CodeReviewSkill 并确认模型通道生效配置写完后不要直接上生产先用一个最小请求验证通道是否通。4.1 写一个测试用例import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; SpringBootTest class CodeReviewSkillTest { Autowired private CodeReviewSkill codeReviewSkill; Test void shouldReviewJavaCode() { String code public class Demo { public String findUser(String name) { String sql SELECT * FROM users WHERE name name ; return sql; } } ; String result codeReviewSkill.review(code); System.out.println(result); } }4.2 预期结果运行测试后控制台应该输出一段 Markdown 格式的审查报告里面会提到 SQL 注入风险、建议使用参数化查询等。这说明三件事都通了Spring AI 读取了SKILL.md模型调用走了 TaoToken 通道Agent 按文件驱动的方式完成了代码审查。如果你在日志里看到请求地址是https://taotoken.net/api/chat/completions这类路径说明 Base URL 配置正确。如果看到的是带/v1的路径回去检查配置。4.3 用 curl 单独验证通道在跑 Spring AI 之前也可以先用 curl 确认 Key 和地址没问题curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回正常内容说明通道可用。这一步能帮你把“Key 问题”和“Spring AI 配置问题”分开排查。5. 本篇常见错排查Base URL、Key、Skill 路径这一章列几个实际配置时容易遇到的问题按出现频率排序。5.1 Base URL 加了 /v1 或带了 UTM最常见的错误。Spring AI 的 OpenAI 兼容客户端会在 Base URL 后面拼接/chat/completions如果你写成https://taotoken.net/api/v1最终路径变成/api/v1/chat/completions和实际接口不匹配。正确写法就是https://taotoken.net/api。另一个变体是把官网地址复制进来带了?utm_source...这会导致请求 URL 里混入查询参数同样失败。配置文件里只写纯 API 地址。5.2 Key 没读到报 401先确认环境变量在当前 shell 里生效echo $TAOTOKEN_API_KEY如果为空说明启动应用的那个终端没有设置。IDEA 里运行的话要在 Run Configuration 的 Environment variables 里加。Docker 里运行的话用-e TAOTOKEN_API_KEY...传入。5.3 SKILL.md 路径读不到SkillLoader.load(skills/code-review/SKILL.md)用的是 classpath 相对路径文件要放在src/main/resources/skills/code-review/SKILL.md。如果你放在项目根目录打包后不会进 jar运行时报文件不存在。用ClassPathResource读取时路径前面不要加/。5.4 模型名写错报 model not foundspring.ai.openai.chat.options.model要填通道支持的模型名。如果你不确定先用模型对话页面确认可用模型再填进配置。模型名大小写和连字符都要一致。5.5 Skill 执行结果不符合预期如果模型返回的内容没有按SKILL.md里的格式来优先检查SKILL.md是否写得太抽象。“请审查代码质量”这种描述模型很难执行要具体到审查维度、输出格式、参考规范。越具体执行越稳定。6. 接入文档与后续步骤配通之后你的 Spring AI Agent 就具备了文件驱动的 Skill 执行能力模型调用走 TaoToken 通道。后续如果要加新的 Skill只需要新建文件夹、写SKILL.md不需要改 Java 编排代码。接入过程中如果遇到报错优先看接入文档https://taotoken.net/docKey 的管理和重新创建在https://taotoken.net/api-keys如果你要长期跑编码类 Agent 任务可以了解 Coding Planhttps://taotoken.net/coding-plan想先在网页上验证模型输出用模型对话https://taotoken.net/model-chat整个链路里TaoToken 只负责 Key 和 Base URLSkill 的读取、解析、执行仍然由 Spring AI 和你的SKILL.md文件驱动。把这两层分清楚后面加 Skill 就是加文件的事不用再动 Java 代码。