★ FEATURED ARTICLE 1. 为什么要在电商系统里引入 AI Native 的思路电商系统这个领域做了十来年的人都有一个共同感受业务逻辑本身并不复杂难的是它太碎了。一个订单从创建到履约中间要经过库存锁定、优惠计算、支付回调、拆单、发货、售后等十几个环节每个环节都有自己的一套规则而且这些规则还在不断变。传统做法是产品经理写需求文档开发翻译成代码测试再验证一遍上线之后发现某个促销规则算错了又得走一遍完整流程。这个链路的瓶颈不在技术在于信息传递的损耗和响应速度。AI Native 这个词最近被聊得很多但很多人把它理解成“在系统里加一个对话入口”或者“接一个大模型 API 做客服”。这其实只是最表层的东西。我理解的 AI Native核心是让 AI 成为系统的第一等公民而不是外挂。具体到电商业务系统意味着订单、商品、库存、营销这些核心域的能力从一开始就设计成可以被 Agent 调用的形态而不是等人去点按钮。Anthropic 在这方面的实践给了我很多启发。他们提出的 Agent 架构思路强调工具调用、上下文管理和多步推理的结合这套东西放到电商场景里特别合适。比如一个售后场景用户说“我上周买的鞋子尺码不对想换货”传统系统需要用户自己找到订单、提交换货申请、等客服审核。而 AI Native 的做法是Agent 直接理解意图调用订单查询工具拿到订单信息调用库存工具确认目标尺码是否有货调用售后政策工具判断是否符合换货条件最后直接完成换货单的创建。整个过程用户只需要说一句话。这篇文章我想聊的是怎么用 Claude Code 这类工具作为开发辅助结合 Agent 架构思想去实现一个 AI Native 的电商业务系统。我会从整体设计思路、核心模块拆解、实操过程、以及踩过的坑这几个方面展开。适合有一定后端开发经验、对 Agent 开发感兴趣、想了解 AI Native 落地路径的读者。即使你之前没接触过 Claude Code也能跟着思路理解整个系统的搭建逻辑。2. 整体架构设计与技术选型考量2.1 核心设计原则能力工具化而非接口化传统电商系统的 API 设计思路是面向页面的。比如“获取订单列表”这个接口返回的数据结构是给前端表格渲染用的包含分页信息、状态码、格式化后的时间字符串。但 Agent 需要的是面向任务的工具它关心的是“我要查一个用户最近一笔待发货的订单”而不是“我要渲染一个列表页”。所以第一个设计决策就是所有核心业务能力都要重新包装成 Agent 可调用的工具。这个包装不是简单地把 REST API 换个名字而是要重新定义输入输出的语义。举个例子传统接口可能是GET /orders?user_id123statuspendingpage1而 Agent 工具应该是find_pending_orders(user_id, time_range)返回的是一个结构化的订单对象列表每个对象包含 Agent 后续推理需要的字段比如订单号、商品明细、当前状态、可执行的操作列表。这个区别很关键。传统接口的返回值是给人看的Agent 工具的返回值是给模型推理用的。前者可以包含大量展示层的信息后者必须精简、语义明确、包含足够的决策依据。2.2 为什么选 Claude Code 作为开发辅助Claude Code 是 Anthropic 推出的命令行编程助手它跟普通的代码补全工具最大的区别在于它能理解整个项目的上下文能直接执行终端命令能读写文件能根据自然语言描述生成完整的代码模块。我在搭建这个电商系统的过程中大量使用了 Claude Code 来生成工具函数的骨架、编写单元测试、甚至调试一些复杂的业务逻辑。选它的原因有几个。第一它对项目结构的理解能力很强你告诉它“在 tools 目录下创建一个库存查询工具”它能自动识别项目使用的语言和框架生成符合规范的代码。第二它支持多步推理你可以让它先分析现有代码结构再给出修改方案最后执行修改。第三它的工具调用机制跟我们要实现的 Agent 架构在理念上是一致的用起来很顺手。安装 Claude Code 的过程不复杂在 Ubuntu 或者 macOS 上通过 npm 全局安装就行。Windows 用户建议用 WSL原生 Windows 环境下有些终端交互会有问题。安装完成后需要配置 API 密钥这个在官方文档里有详细说明。如果你在 VS Code 里工作也可以装 Claude Code 的 VS Code 扩展直接在编辑器里调用。2.3 Agent 框架的选型思路Agent 框架这块市面上选择很多。有偏重编排的有偏重工具调用的有偏重多 Agent 协作的。我的建议是电商业务系统不需要太复杂的多 Agent 协作一个主 Agent 加上若干专用工具就够了。原因是电商的业务流程虽然环节多但大部分是线性的不需要多个 Agent 互相协商。我采用的是“主 Agent 工具注册表”的架构。主 Agent 负责理解用户意图、规划执行步骤、调用工具、处理异常。工具注册表是一个中心化的配置把所有可用的工具及其参数 schema 注册进去Agent 在推理时动态查询可用工具。这种设计的好处是扩展性强新增一个业务能力只需要注册一个新工具不需要改动 Agent 的核心逻辑。上下文管理是另一个关键点。电商场景的对话往往是多轮的用户可能先说“我要退货”然后说“算了改成换货”再说“换成大一号的”。Agent 需要维护一个会话上下文记录用户已经表达过的意图、已经查询到的订单信息、已经执行过的操作。这个上下文不能无限增长需要设计一个合理的截断和摘要机制。3. 核心模块拆解与实操要点3.1 商品域的工具化改造商品域是电商系统的基础。传统商品服务对外暴露的接口包括商品详情查询、SKU 查询、价格查询、库存查询等。在 AI Native 的架构下我们需要把这些能力重新组织成 Agent 友好的工具。我设计的商品域工具包括search_products(keyword, category, price_range)用于根据用户描述搜索商品get_product_detail(product_id)用于获取单个商品的完整信息check_sku_availability(sku_id, quantity)用于检查某个 SKU 是否有足够库存get_price_breakdown(sku_id, quantity, user_level)用于计算包含各种优惠后的实际价格。这里有个细节值得展开。get_price_breakdown这个工具的设计就很有讲究。传统做法是前端拿到原价和优惠信息自己算但 Agent 需要的是一个确定的最终价格。所以这个工具内部要完成所有优惠规则的叠加计算包括平台券、店铺券、会员折扣、满减活动等返回一个结构化的价格明细。这样 Agent 在跟用户沟通时可以直接引用这个计算结果而不需要自己去理解复杂的优惠规则。实操中我发现工具的参数设计要尽量扁平化避免嵌套过深的对象。因为大模型在生成工具调用参数时嵌套结构容易出错。比如search_products的参数我最初设计成{query: {keyword: string, filters: {category: string, price: {min: number, max: number}}}}后来改成了扁平的{keyword, category, min_price, max_price}调用成功率明显提升。3.2 订单域的状态机与 Agent 集成订单域是电商系统里状态最复杂的部分。一个订单可能处于待支付、已支付、待发货、已发货、已完成、已取消、售后中等多种状态状态之间的流转有严格的规则。在 AI Native 架构下订单域的工具设计要特别注意状态校验。我设计的订单工具包括get_order_detail(order_id)获取订单完整信息list_user_orders(user_id, status, time_range)列出用户订单cancel_order(order_id, reason)取消订单confirm_receipt(order_id)确认收货apply_after_sale(order_id, item_id, type, reason)申请售后。每个工具在执行前都要做状态校验。比如cancel_order只能对处于待支付或已支付但未发货的订单执行。这个校验逻辑不能交给 Agent 去判断必须在工具内部硬编码。原因是 Agent 可能会因为上下文理解偏差而做出错误判断但工具内部的校验是确定性的。这里有个实操心得工具的错误返回信息要设计得对 Agent 友好。不要返回“操作失败错误码 4003”这种而要返回“该订单当前状态为已发货无法取消。如需退货请使用售后流程”。这样 Agent 拿到错误信息后可以直接理解并给用户合理的引导而不是卡在那里。3.3 售后域的 Agent 自主决策售后域是 AI Native 最能体现价值的场景。传统售后流程需要用户填写表单、上传凭证、等待审核。而在 AI Native 架构下Agent 可以自主完成大部分判断。我设计的售后工具包括check_after_sale_eligibility(order_id, item_id, type)检查是否符合售后条件create_after_sale_request(order_id, item_id, type, reason, images)创建售后申请query_after_sale_status(request_id)查询售后进度。check_after_sale_eligibility这个工具内部封装了完整的售后政策包括七天无理由的时间计算、商品类目的特殊规则、用户信用等级的差异化处理等。Agent 在收到用户的售后请求时先调用这个工具确认资格如果符合就直接创建申请如果不符合就向用户解释原因并给出替代方案。这个流程里Agent 的自主决策体现在几个地方。第一它能理解用户的自然语言描述判断用户想要的是退货、换货还是维修。第二它能根据订单信息和售后政策判断是否符合条件。第三如果不符合它能给出合理的解释和替代建议。这些在传统系统里都需要人工客服来完成。3.4 库存域的并发安全设计库存是电商系统里对并发最敏感的模块。AI Native 架构下Agent 可能会在短时间内发起多个库存查询和扣减请求这对库存服务的并发安全提出了更高要求。我的做法是在库存工具内部实现乐观锁加队列削峰。具体来说deduct_stock(sku_id, quantity, order_id)这个工具在执行时先尝试用版本号做乐观锁更新如果失败则进入重试队列。同时所有库存扣减请求都先进入一个内存队列由后台 worker 按顺序处理避免瞬时高并发打垮数据库。这里有个参数需要仔细计算队列的容量和 worker 的数量。我的经验值是队列容量设置为峰值 QPS 的 3 到 5 倍worker 数量设置为数据库连接池大小的 70% 左右。比如数据库连接池是 100那 worker 就设 70 个留 30 个连接给其他查询操作。这个比例是在多次压测后得出的太低会导致库存扣减延迟高太高会挤占其他业务的数据库连接。4. 实操过程与核心环节实现4.1 环境搭建与 Claude Code 配置先说环境。我用的开发机是 Ubuntu 22.04Node.js 版本 20.xPython 3.11。Claude Code 通过 npm 安装命令是npm install -g anthropic-ai/claude-code。安装完成后在项目根目录执行claude命令就能启动交互界面。配置方面需要在~/.claude/config.json里设置 API 密钥和默认模型。如果你用的是第三方模型网关需要额外配置 base URL。这里有个坑要注意Claude Code 对模型名称的格式有要求如果配置不对会报 “doesnt look like an anthropic model” 的错误。正确的格式是claude-sonnet-4-20250514这种不要自己乱起名字。VS Code 用户可以在扩展市场搜索 Claude Code 安装官方扩展安装后在设置里填入 API 密钥即可。扩展的好处是能直接在编辑器里选中代码让 Claude 解释或修改不用切换到终端。项目结构我采用的是 monorepo 布局根目录下分packages/agent-core、packages/ecommerce-tools、packages/api-gateway三个包。agent-core放 Agent 的推理循环和上下文管理ecommerce-tools放所有业务工具的实现api-gateway放对外的 HTTP 接口。4.2 Agent 核心循环的实现Agent 的核心是一个 while 循环接收用户输入调用模型推理如果模型返回工具调用请求就执行工具把结果喂回模型继续推理直到模型返回最终回复。用 Python 伪代码表示大概是这样def agent_loop(user_input, context): messages context.get_messages() messages.append({role: user, content: user_input}) while True: response call_model(messages, toolsregistry.get_tool_schemas()) if response.has_tool_calls(): for tool_call in response.tool_calls: result registry.execute(tool_call.name, tool_call.arguments) messages.append({role: tool, content: result}) else: context.update(messages) return response.content这个循环看起来简单但有几个细节需要处理。第一要设置最大循环次数防止 Agent 陷入死循环。我设的是 10 次超过就强制返回当前状态并提示用户。第二每次工具调用的结果要截断到合理长度避免上下文爆炸。第三要记录完整的调用链路方便后续排查问题。上下文管理我采用的是滑动窗口加摘要的方式。保留最近 20 轮对话的完整内容更早的对话生成一个摘要放在系统提示里。摘要是用模型生成的提示词是“用三句话总结以下对话的核心信息和已完成的动作”。4.3 工具注册表的实现细节工具注册表是一个中心化的配置每个工具需要定义名称、描述、参数 schema 和执行函数。描述要写得对模型友好说清楚这个工具做什么、什么时候用、参数怎么填。以search_products为例它的 schema 是这样的{ name: search_products, description: 根据关键词和筛选条件搜索商品。当用户想要查找某类商品时使用此工具。, parameters: { type: object, properties: { keyword: {type: string, description: 搜索关键词如商品名称或类目}, category: {type: string, description: 商品类目可选}, min_price: {type: number, description: 最低价格可选}, max_price: {type: number, description: 最高价格可选} }, required: [keyword] } }执行函数内部就是调用商品服务的搜索接口把结果转换成 Agent 友好的格式。这里要注意返回结果不要包含太多字段只保留 Agent 决策需要的比如商品 ID、名称、价格、库存状态、评分。图片 URL 这种展示层的信息可以不放节省上下文空间。4.4 多轮对话中的意图澄清电商场景里用户的表达往往是不完整的。比如用户说“我要退货”但没说退哪个订单。这时候 Agent 需要主动澄清。我的做法是在系统提示里加入一段引导“当用户意图不明确时优先调用查询工具获取候选信息然后向用户确认。不要假设用户指的是某一个订单。”具体实现上Agent 收到“我要退货”后会先调用list_user_orders拿到用户最近的订单列表然后回复“您最近有以下订单请问您要退哪一个”并列出订单摘要。用户选择后再继续后续流程。这个澄清机制的关键是Agent 不能自己编造订单信息。所有展示给用户的订单数据都必须来自工具调用结果。我在系统提示里明确写了“禁止在未调用工具的情况下向用户展示任何订单、商品或库存信息。”4.5 异常处理与降级策略Agent 系统最怕的是工具调用失败后 Agent 不知道怎么办。我的处理策略是分三层。第一层是工具内部的异常捕获。任何工具执行出错都返回一个结构化的错误对象包含错误类型、错误信息和建议的下一步操作。比如库存不足时返回{error: INSUFFICIENT_STOCK, message: 库存不足, suggestion: 建议用户减少数量或选择其他规格}。第二层是 Agent 循环里的异常处理。如果工具返回错误Agent 会根据错误信息决定是重试、换一个工具、还是向用户说明情况。这个决策是模型做的但我在系统提示里给了明确的指引“遇到工具错误时优先尝试替代方案如果无法解决则如实告知用户。”第三层是系统级的降级。如果模型服务不可用整个 Agent 循环会降级到预设的规则引擎处理最常见的几类请求比如订单查询和物流跟踪。这个降级开关是自动触发的连续三次模型调用失败就切换。5. 常见问题与排查技巧实录5.1 工具调用参数格式错误这是最常见的问题。模型生成的工具调用参数有时候不符合 schema 定义比如该传数字的传了字符串该传数组的传了单个值。排查方法是在工具执行前加一层参数校验用 JSON Schema 验证器检查参数格式。如果校验失败不要直接报错而是把校验错误信息返回给模型让它重新生成。我在实践中的经验是加上这层校验和重试机制后工具调用的成功率从 85% 左右提升到了 97% 以上。还有一个技巧是在工具描述里给出参数示例。比如search_products的描述里加上“示例search_products(keyword运动鞋, min_price200, max_price500)”。模型看到示例后生成正确格式的概率会明显提高。5.2 上下文过长导致推理质量下降电商场景的对话轮次多上下文很容易变得很长。当上下文超过模型窗口的一定比例后推理质量会明显下降表现为 Agent 忘记之前的约定、重复询问已经确认过的信息。我的解决方案是分级上下文管理。最近 5 轮对话保留完整内容第 6 到 20 轮保留用户输入和工具调用的摘要20 轮之前的只保留一个总体摘要。摘要是异步生成的不阻塞主流程。另外工具返回的结果也要做截断。比如list_user_orders返回 50 个订单不能全部塞进上下文只保留最近 5 个其余的用“还有 45 个订单未展示”代替。5.3 并发场景下的库存超卖这个问题在压测时暴露出来的。当多个 Agent 会话同时请求扣减同一 SKU 的库存时出现了超卖。根因是乐观锁的重试机制在高并发下效率太低大量请求在重试中消耗了数据库连接。后来改成了队列削峰方案所有扣减请求先入队后台按顺序处理。队列用 Redis 的 List 实现worker 用 Python 的 asyncio 协程池。调整后的压测结果是在 500 QPS 的并发下库存扣减的准确率是 100%平均延迟 120msP99 延迟 350ms。这个表现对于电商场景来说足够了。5.4 模型服务连接失败的排查开发过程中遇到过 “unable to connect to anthropic services” 的错误。排查下来通常是三个原因API 密钥配置错误、网络代理设置问题、或者模型服务端限流。排查步骤是先用 curl 直接测试 API 端点是否可达确认网络层没问题然后检查密钥是否过期或额度是否用完最后看是不是触发了速率限制如果是就加退避重试。这里有个经验在 Claude Code 的配置里可以设置请求超时时间和重试次数。默认超时是 30 秒我改成了 60 秒重试次数从 2 次改成 3 次。这样在网络抖动的情况下成功率会高很多。5.5 常见问题速查表问题现象可能原因排查方法解决方案工具调用参数格式错误模型未按 schema 生成检查工具描述是否清晰加参数校验和重试补充示例Agent 忘记上下文上下文过长查看消息历史长度启用分级上下文管理库存超卖并发扣减冲突压测复现看数据库日志队列削峰乐观锁改悲观锁模型服务连接失败密钥/网络/限流curl 测试端点检查密钥加超时和重试检查配额Agent 陷入循环工具返回不明确查看调用链路日志设最大循环次数优化错误返回回复内容编造信息系统提示不够严格检查系统提示词明确禁止未调用工具就展示数据6. 一些实操后的个人体会这套系统从开始搭到基本可用大概花了三周时间。其中大部分时间不是在写代码而是在调提示词和优化工具描述。Agent 系统的开发跟传统后端开发最大的区别在于你的“代码”有很大一部分是自然语言写的提示词而这些提示词的调试没有编译器帮你检查只能靠实际运行来验证。Claude Code 在这个过程中帮了很大忙。我经常用它来生成工具函数的骨架然后自己填充业务逻辑。它也帮我写了不少单元测试特别是那些边界条件的测试用例它考虑得比我周全。有个技巧是你可以把工具的描述和 schema 贴给 Claude Code让它帮你检查有没有歧义或者遗漏的参数。如果让我给准备入坑的人一个建议那就是先把一个场景做透不要贪多。我最初想一次性把商品、订单、售后、物流全做了结果每个都做得半吊子。后来聚焦在售后场景把退换货的流程打磨到能处理 90% 以上的常见情况再逐步扩展其他域效果就好很多。另外Agent 的评估体系要尽早建立。我建了一个包含 200 条测试用例的评估集覆盖各种用户表达方式和边界情况。每次修改提示词或工具描述后都跑一遍评估集看通过率的变化。这个习惯帮我避免了很多“改了一个问题引入两个新问题”的情况。最后分享一个关于工具粒度的心得。工具不是越细越好也不是越粗越好。太细的话Agent 需要调用很多次才能完成一个任务上下文消耗大太粗的话工具内部逻辑复杂出错时难以定位。我的经验是一个工具对应一个完整的业务动作比如“创建售后申请”是一个工具“查询售后资格”是另一个工具但“计算退款金额”就不需要单独的工具它应该是“创建售后申请”内部的一部分。这个粒度需要根据实际场景反复调整没有一刀切的标准。
阅读完成 · 觉得有帮助？
