企业官网建设流程全解析

Spring AI 2.0、Agent Utils、Claude Code，这三个词放在一起，就是一条非常典型的企业级 AI Agent 落地链路。这次我们不看空泛概念，直接过一遍：这套组合能做什么、环境要准备哪些东西、工程骨架怎么搭、Agent 工具怎么封装、Claude Code 怎么接入日常研发、批量任务和接口怎么设计、上线前要避哪些坑。

先给结论：这套玩法适合 Java 团队。Spring AI 2.0 负责屏蔽大模型接入差异，把 OpenAI、Anthropic、DeepSeek、通义这类模型统一成一套 Java API；Agent Utils 这类工具层负责把 Agent 的工具注册、任务编排、上下文管理、结构化输出封装好；Claude Code 是终端侧的编程 Agent，把它和 Spring AI 服务端接在一起，基本就是一套“企业级 AI 编程助手 + Agent 服务平台”的雏形。文章会从环境检查开始，一路写到 Spring Boot 工程搭建、工具调用、REST 接口、批量任务、性能观察和排错清单。如果你正准备在公司内部做 AI 编程助手或 Agent 应用，这篇值得收藏。

文章不会只讲理论。后半部分会给出可复制的 Maven 依赖、配置文件、Java 工具类、curl 调用示例和 Claude Code 安装配置命令。由于 Spring AI 2.0 仍在快速迭代，文中所有版本号和数据都以你本机实际下载到的版本为准。

1. 核心能力速览

先把这套技术栈的关键信息汇总成一张表，方便快速判断值不值得投入。

这里要说明一点：如果没有本地大模型需求，整套方案跑在 CPU 服务器上即可，不涉及显存占用。如果你想把底层大模型替换成本地部署模型，再考虑 GPU 显存，通常 7B 到 14B 量化模型需要 6G 到 12G 显存，但实际占用要按模型版本和推理框架测试。

2. 这套组合能做什么：适用场景与使用边界

2.1 适用场景

这套组合最典型的落地场景有三类。

第一类是企业级 AI 编程助手。Claude Code 负责在终端里理解项目结构、按任务要求改代码、跑测试、提交变更；Spring AI 2.0 服务端负责统一处理模型调用、权限控制、日志审计和工具权限。前后端配合，就是一套带可控权限的研发 Agent。

第二类是内部知识库与文档 Agent。用 Spring AI 2.0 的向量库、文档加载器和结构化输出能力，把团队内部知识库、接口文档、运维手册接进来。用户通过对话提问，Agent 自动检索、归纳、引用源文档，比纯 RAG 更接近真实业务使用。

第三类是自动化任务编排。把“读取需求 -> 拆分任务 -> 调用工具 -> 输出结果 -> 人工确认”这条链路用 Agent Utils 这类工具层封装成标准模板。批量生成测试用例、批量扫描代码规范、批量生成接口文档，都能在这种模式下做。

2.2 使用边界与合规提醒

不管能力多强，使用边界必须提前定清楚。

• 模型生成的代码只能视为初稿，提交前必须由开发人员 review。生成代码可能包含错误、过期 API 或安全漏洞。
• 不要把生产数据库密码、云厂商密钥、源代码完整库直接塞给模型。需要脱敏或使用密钥管理服务注入后再提供给 Agent。
• 涉及版权代码、开源许可证、客户敏感数据时，要确认模型服务商的隐私条款和企业合规要求。
• Claude Code 的可用地区以 Anthropic 官方支持范围为准。如果企业有合规要求，需要在合规前提下选择可用的服务端点或自建兼容网关。
• 企业内部接入时，建议给 Agent 配置只读权限，工具执行前保留人工确认环节。

3. 环境准备与前置条件

在写代码之前，先把环境过一遍。下面是通用检查清单。

环境验证命令：

java -version mvn -version node -v npm -v

如果在 Windows 上使用 PowerShell，注意环境变量设置方式不同。后面 Claude Code 部分会给出 Windows、macOS、Ubuntu 的常用配置方式。

如果之前装过旧版本 Spring AI 或 Claude Code，建议先确认版本。Claude Code 升级用npm update -g @anthropic-ai/claude-code，Spring AI 版本以 Maven Central 上可拉取的 2.0.x 为准。版本不一致会导致很多诡异问题，下面排错章节会专门说。

4. Spring AI 2.0 工程骨架搭建

4.1 创建 Spring Boot 项目

这里以 Maven 为例。先创建一个 spring-ai-agent-demo 工程，pom.xml 核心依赖如下。

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.3.5</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-spring-boot-starter</artifactId> <version>2.0.0</version> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> <version>2.0.0</version> </dependency> </dependencies>

注意：具体 Starter 模块和版本号需要以 Spring AI 2.0 官方发布为准。如果是接 Anthropic，就引入 anthropic 的 Spring AI Starter；如果是接 DeepSeek 这类 OpenAI 兼容端点，引入 openai Starter，再把 base-url 指向兼容端点即可。

4.2 配置文件

application.yml 配置不要硬编码 Key，用环境变量替换。

server: port: 8080 spring: application: name: spring-ai-agent-demo ai: openai: api-key: ${AI_API_KEY} base-url: ${AI_BASE_URL:https://api.openai.com} chat: options: model: ${AI_MODEL:gpt-4o-mini} temperature: 0.7

实际项目中，密钥建议通过环境变量、K8s Secret 或 Vault 注入，不要提交到 Git。如果接 Anthropic，配置键会变成spring.ai.anthropic.api-key和spring.ai.anthropic.chat.options.model。不同模块差异较大，以你引入的 Starter 官方文档为准。

4.3 最小可运行 ChatClient

Spring AI 2.0 最常用的 API 是 ChatClient。先注入 Bean，然后写一个最简单的对话接口。

@Service public class AgentService { private final ChatClient chatClient; public AgentService(ChatClient.Builder builder) { this.chatClient = builder.build(); } public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }

@RestController @RequestMapping("/api/agent") public class AgentController { private final AgentService agentService; public AgentController(AgentService agentService) { this.agentService = agentService; } @PostMapping("/chat") public String chat(@RequestBody ChatRequest request) { return agentService.chat(request.message()); } }

启动项目：

AI_API_KEY=your-api-key mvn spring-boot:run

启动后先访问健康检查，确认进程正常。

5. Agent Utils 封装：把 Agent 工具调用的工程细节标准化

5.1 Agent 工具层的核心职责

Spring AI 提供了底层的函数调用能力，但企业级项目里不能直接在业务代码里散落模型调用、Token 统计、日志、工具白名单。Agent Utils 这类工具层的价值，是把下面这些环节标准化。

• 工具注册：哪些 Java 方法允许被模型调用，需要显式声明，而不是任意反射。
• 参数校验：模型生成的工具参数不可信，进入真实业务方法前必须校验。
• 上下文管理：多轮对话、任务状态、中间结果放在同一个上下文对象里。
• 任务编排：把“拆解问题 -> 计算 -> 调用工具 -> 汇总”定义成可复用流程。
• 审计日志：每次模型调用、工具调用、人审操作都要留痕。

5.2 用 @Tool 注册一个工具方法

Spring AI 支持通过注解把 Java 方法暴露成模型可调用的工具。下面是一个模拟代码评审工具。

@Component public class CodeReviewTools { @Tool(description = "对指定代码文件做静态扫描，返回问题列表") public String scanFile(String filePath, String ruleSet) { // 真实场景里可以接 PMD、Checkstyle、SonarQube API return "[" + filePath + "] 使用规则集 [" + ruleSet + "] 扫描完成，发现 2 个潜在问题"; } }

把工具列表传给 ChatClient：

@Service public class AgentOrchestrator { private final ChatClient chatClient; public AgentOrchestrator(ChatClient.Builder builder, CodeReviewTools reviewTools) { this.chatClient = builder .defaultTools(reviewTools) .build(); } public String run(String task) { return chatClient.prompt() .user(task) .call() .content(); } }

这样，模型收到“扫描 src/main/java/Application.java，用默认规则”的问题时，会自己决定调用scanFile工具，再把工具返回值组织成自然语言回答给你。

5.3 一个轻量的 Agent 编排模板

如果不想引入重量级编排框架，可以自己在 Java 里维护一个最小的 Agent 执行管线。核心接口可以这样设计。

public interface AgentTask { void execute(AgentContext context); }

public class AgentContext { private final Map<String, Object> state = new ConcurrentHashMap<>(); public void put(String key, Object value) { state.put(key, value); } public Object get(String key) { return state.get(key); } }

@Component public class TaskOrchestrator { private final List<AgentTask> pipeline; public TaskOrchestrator(List<AgentTask> pipeline) { this.pipeline = pipeline; } public AgentContext run(AgentContext context) { for (AgentTask task : pipeline) { task.execute(context); } return context; } }

这里的重点是：工具注册、上下文、编排逻辑、审计日志各司其职。真实项目里再补上“人工审批节点”——模型生成的内容先落到草稿表，人工确认后再执行后续写操作。这条边界是企业和个人玩 Agent 的核心区别。

6. Claude Code 实战：安装、配置与日常使用

6.1 环境准备

Claude Code 是一个面向开发者的 Agent 类 CLI 工具。它可以直接在终端里读取项目代码、修改文件、执行命令，也可以作为 VS Code 扩展使用。安装前确认 Node.js 版本，推荐用较新的 LTS 版本。

6.2 安装 Claude Code

先看当前是否已经安装：

claude --version

没有安装时，用 npm 全局安装 Anthropic 官方 CLI 包。这是目前最通用的安装方式：

npm install -g @anthropic-ai/claude-code claude --version

安装完成后，需要配置 API 凭证。Claude Code 默认读取环境变量。在 macOS 和 Linux 下使用 export，在 Windows PowerShell 下使用$env:方式。

export ANTHROPIC_API_KEY="your-anthropic-api-key"

$env:ANTHROPIC_API_KEY="your-anthropic-api-key"

配置好之后，在项目目录执行claude即可进入对话界面：

cd /path/to/your/project claude

6.3 切换模型供应商：DeepSeek 等兼容端点

Claude Code 默认面向 Anthropic 模型，但社区里大量用户的真实做法，是通过环境变量或第三方切换工具，把请求转发到其他兼容 Anthropic 协议的模型服务商。常见做法是同时指定 base-url、api-key、model 三个环境变量：

export ANTHROPIC_BASE_URL="https://your-compatible-endpoint" export ANTHROPIC_API_KEY="your-compatible-api-key" export ANTHROPIC_MODEL="deepseek-chat"

需要注意，这行配置只有在你的模型服务商提供 Anthropic 兼容协议时才有效。如果工具提示xxx is not a model this version of Claude Code recognizes，说明模型名和当前版本不匹配，需要确认模型名写法或升级 Claude Code。

社区还流行用 CC Switch 这类 GUI 工具管理多套 Claude Code 配置。它的作用是帮助我们在一套配置和另一套配置之间快速切换，适合同时使用多家模型服务的开发场景。切换后记得重启 Claude Code 进程，配置才会生效。

6.4 VS Code 插件使用

热词里频繁出现 “vscode 配置 claude code”。在 VS Code 扩展市场搜索 Claude Code for VS Code，安装后通常是作为侧边栏面板使用。前提是 CLI 已经配置好登录凭证，否则面板会提示需要先配置 API 密钥。

可以设置登录：

claude /login

VS Code 插件的主要使用方式：选中代码后让 Claude Code 解释，或者直接输入任务让它修改当前工作区文件。它的能力和 CLI 基本一致，只是交互方式变成了编辑器面板。

6.5 用 skill 和 CLAUDE.md 约束行为

在项目根目录创建CLAUDE.md文件，给 Claude Code 提供项目级上下文。内容包括项目简介、技术栈、目录结构、编码规范、常用命令。这样新开对话时，Claude Code 会自动读取并遵守这些约定。

更进阶的用法是在.claude/skills目录下定义可复用技能。每个技能目录包含描述文件和示例，让 Claude Code 在接到特定任务时套用固定流程。比如“写接口文档”技能、“生成单元测试”技能。

CLAUDE.md 示例：

# 项目上下文 - 技术栈：Spring Boot 3 + Spring AI 2.0 - 编码规范：Controller 层不写业务逻辑，工具类统一放在 agent/tools 包 - 常用命令：mvn spring-boot:run 启动服务，mvn test 跑单测 - 修改代码后必须检查 import，避免引入未使用依赖

这些文件虽然只是 Markdown，但在企业落地时非常有用。它相当于把团队规范沉淀给了 Agent，减少了模型每次重复试探的成本。

7. 功能测试与效果验证

7.1 服务端 ChatClient 基础对话测试

用 curl 调本地 Spring Boot 接口。

curl -X POST http://127.0.0.1:8080/api/agent/chat \ -H "Content-Type: application/json" \ -d '{"message":"用一句话解释什么是 Spring AI 2.0"}'

预期返回一段自然语言文本。判断成功的标准有两个：接口状态码 200，返回内容不是报错堆栈。如果返回 401 或 500，先检查 API Key 和模型名配置。

7.2 工具调用测试

给模型一个需要调用工具的问题，例如“扫描 code-review-tool/src/main/java/RetryUtil.java，并给出问题列表”。这种任务在没有工具时会直接拒绝或给出泛泛建议，在工具注册正确时会输出具体文件路径和规则集，这是验证函数调用链路是否打通的关键实验。

7.3 多轮上下文测试

在 Postman 或 curl 里连续发两条消息，第一条说“记住，团队的接口文档规范是 POST 开头”，第二条问“下次写接口时要注意什么”，看模型能否记住上文。如果第二条回答完全不相关，检查 ChatClient 是否开启了 Memory Advisor。

7.4 批量生成测试

准备好一批测试需求文件，写一个简单任务脚本，批量交给服务端接口处理。这一步可以先用 shell 循环验证。

for file in tasks/*.md; do content=$(cat "$file" | jq -Rs .) curl -X POST http://127.0.0.1:8080/api/agent/chat \ -H "Content-Type: application/json" \ -d "{\"message\": $content}" >> results.txt echo "$file done" done

批量任务要注意速率限制，服务端最好加队列和重试，后面章节会展开。

7.5 判断成功与失败排查

8. 接口 API 与批量任务设计

8.1 接口分层

企业级项目不要只暴露一个 chat 接口。建议拆分：

• /api/agent/chat：单轮对话
• /api/agent/stream：流式输出
• /api/agent/tool/scan：指定工具调用
• /api/agent/task/submit：提交批量任务
• /api/agent/task/{id}：查询任务状态

8.2 流式输出示例

SSE 流式输出是 ChatClient 的常用能力，前端能像打字机一样实时显示模型输出。代码需要使用stream()而不是call()。

@PostMapping(value = "/stream", produces = "text/event-stream") public Flux<String> stream(@RequestBody ChatRequest request) { return chatClient.prompt() .user(request.message()) .stream() .content(); }

调用端可以用 curl 观察：

curl -N -X POST http://127.0.0.1:8080/api/agent/stream \ -H "Content-Type: application/json" \ -d '{"message":"写一首关于 Agent 的短诗"}'

8.3 批量任务队列

批量任务建议用 Spring 自带的TaskExecutor加一个任务状态表实现，不一定要引入消息队列。最小设计如下。

@Configuration public class AsyncConfig { @Bean("agentTaskExecutor") public Executor agentTaskExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); executor.setMaxPoolSize(8); executor.setQueueCapacity(100); executor.setThreadNamePrefix("agent-task-"); executor.initialize(); return executor; } }

提交任务时，把任务描述、输入文件列表、参数存数据库，状态是 PENDING；异步线程开始处理后改成 RUNNING；有异常时改成 FAILED 并记录错误信息。重试可以用简单计数器，超过 3 次直接置 FAILED。

8.4 通用重试建议

调用模型 API 时，429（限流）、5xx（服务端过载）、529（模型服务过载）都适合短暂退避重试。不要对 401（密钥错误）做重试，那是配置问题，重试只会浪费配额。Java 里可以用 Spring Retry 或 Resilience4j。

# 伪配置示例，实际需按项目依赖调整 spring: ai: retry: max-attempts: 3 backoff-initial-interval: 1000ms backoff-multiplier: 2

9. 资源占用与性能观察

9.1 观察什么

Spring AI 服务端是典型的 CPU 加内存加网络型负载。启动后主要看三件事：JVM 内存、线程池状态、模型 API 响应时延。

• JVM 内存：用jstat -gc <pid>或本地直接开jconsole观察堆内存变化。大并发长文本任务会明显拉高堆占用。
• 线程池：开启 executor 日志，看任务是否积压。
• 模型时延：在日志里打印模型响应耗时和 Token 用量。

9.2 性能瓶颈通常在哪里

一个是模型服务端限流。你的服务再快，模型 API 有 RPM 和 TPM 限制时，批量任务一样会被 429 打回来。另一个是长文本上下文。每次对话都携带累计上下文，Token 成本会非线性上涨。建议在 Agent 上下文管理里定期裁剪历史消息，只保留最近的对话摘要。

9.3 降低服务端压力

• 对话开启流式输出，用户体验更好，也降低单次请求等待时间。
• 批量任务控制并发数，4 到 8 个并发是相对稳妥的起始值。
• 对相同问题做缓存，减少重复计费。
• 模型选择上，简单任务用便宜小模型，复杂任务才切大模型。

9.4 端侧 Claude Code 的资源占用

Claude Code 本身是 Node.js 进程，内存占用随着项目文件读取和上下文增加而上升。大型仓库里建议把目标目录精确到模块级，或者用忽略规则避免它扫描 node_modules、target 等目录。日常使用中如果发现终端卡顿，先确认是否扫描了超大目录。

10. 常见问题与排查方法

这一段直接给排错表，遇到问题按表查。

| 问题现象 | 可能原因 | 排查方式 | 解决方案