Claude Code 实战心得：用 Java + Vue 从零搭建企业级 Agent 平台的 30 天

1. 30 天从零搭建企业级 Agent 平台我踩过的真实坑Claude Code 实战心得这件事网上大多停留在帮我写个函数的层面。但如果你真要用 Java Spring Boot 做后端、Vue 3 做前端从零搭一个企业级 Agent 平台问题就完全不一样了7 个微服务怎么拆、多 LLM 路由怎么统一、SSE 流式对话怎么联调、Claude Code 生成的代码怎么保证不跑偏。我用 30 天时间把一套覆盖 gateway、auth、agent、skill、mcp、knowledge、frontend 的骨架跑通了后端 Java 19 Spring Boot 3.3 MyBatis-Plus PostgreSQL 16pgvector Redis 7前端 Vue 3 TypeScript Vite Element Plus Pinia。这篇文章不讲空泛的架构图只交付能复制的东西Claude Code 接入 TaoToken 统一 Key/API 通道的 settings.json 配置片段、前后端联调的验证命令、Agent 调用链路的排查步骤。适合已经会 Java 和 Vue、但没系统用过 Claude Code 做全栈项目的开发者。按天推进的节奏我会在关键节点标出来你可以直接对着做。先说结论30 天里真正卡住我的不是业务逻辑而是三件事——Claude Code 的 API 通道没配好导致频繁超时、前后端 SSE 联调时事件流对不上、以及子 Agent 并行改代码后的合并冲突。下面逐个拆。2. 前置准备TaoToken 统一 Key 与 Claude Code 接入2.1 为什么需要一个统一通道Claude Code 默认走官方通道但在企业项目里你往往需要统一管理 Key、统一计费、统一限流。TaoToken 提供的就是这样一个统一 Key/API 通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你在 Claude Code、Coding Plan、以及自建 Agent 后端里复用同一套凭证不用每个服务单独配一遍。对 wagent 这种 7 服务项目来说这一点很关键agent 服务要调 LLM、knowledge 服务要做 embedding、mcp 网关要转发工具调用如果每个服务各配一套 Key轮换和审计会非常痛苦。2.2 拿到 Key 之后先别急着写代码进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完 Key 后建议先在模型对话页面做一次连通性验证地址 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认通道可用再往下走。这一步能帮你排除掉 80% 的代码没问题但请求就是失败的情况。注意Key 只显示一次创建后立刻存进你的密钥管理工具不要直接写进 git 仓库。2.3 Claude Code 的 settings.json 配置片段Claude Code 的配置分两层全局配置和项目级配置。项目级配置放在项目根目录的.claude/settings.json这样团队里每个人拉下来就能用同一套通道。下面是我在 wagent 项目里实际用的片段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-20250514 }, permissions: { allow: [ Read, Write, Edit, Glob, Grep, Bash(mvn *), Bash(npm *), Bash(git status), Bash(git diff *) ], deny: [ Bash(git push *), Bash(rm -rf *) ] } }这里有两个细节值得说。第一ANTHROPIC_BASE_URL指向 TaoToken 的 API 入口不要带任何多余路径Claude Code 会自己拼接/v1/messages。第二permissions.deny里我禁掉了git push因为 Claude Code 在自动执行阶段偶尔会想帮你提交企业项目里这个动作必须人工确认。如果你还想在终端里直接用 Claude Code 的交互模式可以再配一个 Coding Plan地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合长期编码和 Agent 场景额度模型和按次调用不一样。2.4 验证配置是否生效配完之后不要直接开干先跑一条最小验证。在项目根目录执行claude --version claude -p 用一句话说明当前项目根目录下有哪些顶层文件夹如果返回了目录列表说明通道和权限都通了。如果报 401检查ANTHROPIC_AUTH_TOKEN是不是复制时带了空格如果报连接超时检查ANTHROPIC_BASE_URL有没有多写斜杠。3. 可复制配置项目骨架与关键文件3.1 后端骨架的 Maven 依赖wagent 后端用 Java 19 Spring Boot 3.3父 pom 里我锁定了几个关键版本避免 Claude Code 生成代码时引入不兼容的依赖properties java.version19/java.version spring-boot.version3.3.4/spring-boot.version mybatis-plus.version3.5.7/mybatis-plus.version pgvector.version0.1.6/pgvector.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version${mybatis-plus.version}/version /dependency dependency groupIdcom.pgvector/groupId artifactIdpgvector/artifactId version${pgvector.version}/version /dependency /dependenciesWebFlux 是必须的因为 SSE 流式对话用阻塞式 MVC 会很难受。MyBatis-Plus 用 boot3 starter别用老的 boot starter否则启动直接报NoClassDefFoundError。3.2 多 LLM 路由的核心配置agent 服务要支持多 LLM 路由我用一个application-agent.yml来管理agent: llm: providers: - name: default base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} model: claude-sonnet-4-20250514 timeout: 60s - name: fast base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} model: claude-haiku-4-20250514 timeout: 20s routing: default: default intent-classify: fast code-gen: defaultTAOTOKEN_API_KEY从环境变量注入不要写死在 yml 里。路由规则里我把意图分类这种轻量任务丢给 fast 模型代码生成走 default这样成本和延迟都能压下来。3.3 前端 Vite 代理配置Vue 3 前端在开发阶段要跨域访问后端 gatewayvite.config.ts里配代理export default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) }, /sse: { target: http://localhost:8080, changeOrigin: true, ws: false } } } })SSE 的代理要单独配并且ws设为 false否则 Vite 会尝试升级成 WebSocket导致事件流断掉。这个坑我卡了整整一个下午。3.4 Claude Code 的项目记忆文件在项目根目录建一个.claude/memory/project_wagent.md把服务端口、JDK 版本、数据库连接这些固定信息写进去# wagent 项目记忆 ## 服务端口 - gateway: 8080 - auth: 8081 - agent: 8082 - skill: 8083 - mcp: 8084 - knowledge: 8085 - frontend: 5173 ## 环境 - JDK: 19注意 PATH 默认可能是 8需显式指定 - PostgreSQL: 16 pgvector - Redis: 7 ## 当前阶段 Phase 3 - Agent 调用链路联调每次新会话启动Claude Code 会自动加载这个文件你就不用反复解释项目结构了。4. 验证请求与成功结果前后端联调与 Agent 调用链路4.1 后端启动验证先确认 JDK 版本这是最容易翻车的地方java -version # 如果输出 1.8说明 PATH 上是 JDK 8 export JAVA_HOME$(/usr/libexec/java_home -v 19) export PATH$JAVA_HOME/bin:$PATH java -version # 应输出 openjdk version 19.x.x然后启动 gateway 和 agent 两个服务cd wagent-gateway mvn spring-boot:run cd wagent-agent mvn spring-boot:run 看到Started AgentApplication in X seconds就算成功。如果 agent 服务启动时报UnsupportedClassVersionError就是 JDK 版本问题回到上面那步。4.2 SSE 流式对话验证用 curl 直接打 agent 服务的对话接口验证流式返回curl -N -X POST http://localhost:8082/api/v1/agent/chat \ -H Content-Type: application/json \ -H Authorization: Bearer 你的JWT \ -d {sessionId:test-001,message:你好介绍一下你自己}-N参数关闭缓冲你能看到事件一条条吐出来event: message data: {delta:你好} event: message data: {delta:我是} event: done data: {sessionId:test-001,tokens:42}如果只收到一个done而没有中间的message事件说明后端把流式响应缓冲了检查 WebFlux 的produces是不是MediaType.TEXT_EVENT_STREAM_VALUE。4.3 前端联调验证前端启动后打开浏览器控制台在对话页面发一条消息Network 面板里应该能看到一个text/event-stream类型的请求状态是pending而不是200——这是 SSE 的正常表现连接保持打开直到done事件。如果前端收不到事件先检查 Vite 代理的/sse配置再检查后端有没有设置Cache-Control: no-cache和X-Accel-Buffering: no响应头。4.4 Agent 调用链路验证Agent 平台的核心是调用链路用户消息 → 意图识别 → 工具选择 → LLM 调用 → 结果合成。我在 agent 服务里加了一个调试端点返回完整的调用链curl http://localhost:8082/api/v1/agent/trace/test-001返回{ sessionId: test-001, steps: [ {step: intent, model: fast, latency: 320}, {step: tool-select, tool: knowledge.search, latency: 45}, {step: llm, model: default, latency: 1840}, {step: synthesize, latency: 12} ], totalLatency: 2217 }看到这条链路完整说明 Agent 平台的核心能力已经跑通了。如果某一步缺失就针对那一步单独排查。5. 本篇常见错排查5.1 Claude Code 报 401 或 403最常见的原因是ANTHROPIC_AUTH_TOKEN复制时带了换行或空格。用cat -A .claude/settings.json检查有没有隐藏字符。另一个原因是 Key 过期去控制台重新生成一个。5.2 后端启动报 JDK 版本错误UnsupportedClassVersionError: class file version 63.0意思是编译用了 JDK 19但运行用的是 JDK 8。解决方法是显式设置JAVA_HOME和PATH或者在 Maven 的pom.xml里用maven-compiler-plugin锁定版本。5.3 SSE 事件流中断三个检查点后端produces是否为TEXT_EVENT_STREAM_VALUE、响应头是否包含X-Accel-Buffering: no、Vite 代理的/sse是否设了ws: false。这三个都对了事件流就不会断。5.4 子 Agent 并行改代码后合并冲突Claude Code 的子 Agent 如果同时改同一个文件合并时必然冲突。我的做法是在启动子 Agent 前用 Explore Agent 先扫一遍文件依赖确保每个子 Agent 负责的文件集合不重叠。如果实在要改同一个文件就串行执行别图快。5.5 多 LLM 路由选错模型如果发现代码生成任务走了 fast 模型导致质量下降检查routing配置里的code-gen是不是指向了default。路由规则是按任务类型匹配的写错了不会报错只会静默走错模型。5.6 pgvector 查询报维度不匹配embedding 维度必须和建表时的vector(N)一致。如果你换了 embedding 模型维度变了要么改表结构要么在应用层做维度对齐。这个错误在 knowledge 服务里很常见。6. 按天推进的节奏与下一步30 天的节奏我大致这么分第 1-3 天搭骨架和配通道第 4-10 天做 auth 和 gateway第 11-18 天做 agent 和 skill第 19-25 天做 mcp 和 knowledge第 26-30 天联调和压测。Claude Code 在每个阶段的作用不一样——前期主要是生成骨架代码中期是并行实现多个服务后期是排查联调问题。如果你要接着往下做下一步建议先把 Agent 调用链路的 trace 端点补全再接入 RAG 知识库。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 API 说明和参数对照。长期做编码和 Agent 的话Coding Plan 会比按次调用更划算地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后说一个我实测下来最有用的习惯每次让 Claude Code 动手前先让它用 Explore Agent 把相关文件扫一遍把依赖关系列出来。这一步多花两分钟能省掉后面半小时的合并冲突。