企业官网建设流程全解析

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_id=123&status=pending&page=1，而 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.04，Node.js 版本 20.x，Python 3.11。Claude Code 通过 npm 安装，命令是npm install -g @anthropic-ai/claude-code。安装完成后，在项目根目录执行claude命令就能启动交互界面。

配置方面，需要在~/.claude/config.json里设置 API 密钥和默认模型。如果你用的是第三方模型网关，需要额外配置 base URL。这里有个坑要注意：Claude Code 对模型名称的格式有要求，如果配置不对会报 “doesn't 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, tools=registry.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_price=200, max_price=500)”。模型看到示例后，生成正确格式的概率会明显提高。

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%，平均延迟 120ms，P99 延迟 350ms。这个表现对于电商场景来说足够了。

5.4 模型服务连接失败的排查

开发过程中遇到过 “unable to connect to anthropic services” 的错误。排查下来通常是三个原因：API 密钥配置错误、网络代理设置问题、或者模型服务端限流。

排查步骤是：先用 curl 直接测试 API 端点是否可达，确认网络层没问题；然后检查密钥是否过期或额度是否用完；最后看是不是触发了速率限制，如果是就加退避重试。

这里有个经验：在 Claude Code 的配置里，可以设置请求超时时间和重试次数。默认超时是 30 秒，我改成了 60 秒，重试次数从 2 次改成 3 次。这样在网络抖动的情况下，成功率会高很多。

5.5 常见问题速查表

6. 一些实操后的个人体会

这套系统从开始搭到基本可用，大概花了三周时间。其中大部分时间不是在写代码，而是在调提示词和优化工具描述。Agent 系统的开发跟传统后端开发最大的区别在于，你的“代码”有很大一部分是自然语言写的提示词，而这些提示词的调试没有编译器帮你检查，只能靠实际运行来验证。

Claude Code 在这个过程中帮了很大忙。我经常用它来生成工具函数的骨架，然后自己填充业务逻辑。它也帮我写了不少单元测试，特别是那些边界条件的测试用例，它考虑得比我周全。有个技巧是，你可以把工具的描述和 schema 贴给 Claude Code，让它帮你检查有没有歧义或者遗漏的参数。

如果让我给准备入坑的人一个建议，那就是：先把一个场景做透，不要贪多。我最初想一次性把商品、订单、售后、物流全做了，结果每个都做得半吊子。后来聚焦在售后场景，把退换货的流程打磨到能处理 90% 以上的常见情况，再逐步扩展其他域，效果就好很多。

另外，Agent 的评估体系要尽早建立。我建了一个包含 200 条测试用例的评估集，覆盖各种用户表达方式和边界情况。每次修改提示词或工具描述后，都跑一遍评估集，看通过率的变化。这个习惯帮我避免了很多“改了一个问题引入两个新问题”的情况。

最后分享一个关于工具粒度的心得。工具不是越细越好，也不是越粗越好。太细的话，Agent 需要调用很多次才能完成一个任务，上下文消耗大；太粗的话，工具内部逻辑复杂，出错时难以定位。我的经验是，一个工具对应一个完整的业务动作，比如“创建售后申请”是一个工具，“查询售后资格”是另一个工具，但“计算退款金额”就不需要单独的工具，它应该是“创建售后申请”内部的一部分。这个粒度需要根据实际场景反复调整，没有一刀切的标准。