企业官网建设流程全解析

AgentX 是一个让小白也能无门槛通过自然语言打造 Agent 的开源平台，内置自研 MCP 网关与模型高可用组件。本文带你快速搞懂 AgentX 的计费系统：Token 消耗如何计费、订单状态如何流转、如何用支付宝或 Stripe 完成充值，适合刚接触 AgentX 的新手和普通用户。

一、AgentX 计费是怎么运作的？先搞懂这 4 个概念

AgentX 的计费系统设计非常"透明"，核心是把**商品（Product）与计费规则（Rule）**解耦，任何一次扣费都能追溯到具体算法。理解下面 4 个概念，就看懂了整个系统：

运行时流程是一条闭环：触发事件 → 找到商品 → 匹配规则 → 执行策略计算 → 记账扣费。比如你调用一次模型，系统会按输入Token ÷ 100万 × 输入单价 + 输出Token ÷ 100万 × 输出单价计算费用，从余额中扣除，并写入用量记录。

💡 官方示例：某模型输入单价 5 元/百万 Token、输出单价 15 元/百万 Token，一次消耗 1000 输入 + 500 输出 Token，费用约为0.005 + 0.0075 = 0.0125元。

设计细节可参考 docs/billing/计费.md，其中service_id的语义规范解释了为什么模型调用、Agent 创建、API 调用能共用同一套计费框架。

二、Token 消耗发生在哪？对话计费流程拆解

对普通用户来说，Token 消耗几乎全部发生在对话环节。AgentX 在消息处理器中集成了透明计费，流程如下：

1. 发起对话→ 系统先做余额预检查：余额为负时阻止本次对话，并提示充值；
2. 模型返回响应→ 统计本次的输入 Token 与输出 Token 数量；
3. 自动扣费→ 生成唯一requestId（基于会话 ID、用户 ID 和时间戳），保证幂等，不会重复扣费；
4. 记账→ 用量和费用写入用量记录表，账户余额实时更新。

几个值得新手放心的设计：

• ✅透明计费：扣费不打断对话流程，同步对话和流式对话都支持；
• ✅优雅降级：余额不足时不会报错崩溃，而是收到一条"账户余额不足，请充值后继续使用"的友好提示；
• ✅允许短暂透支：预检查通过后，计费时余额允许变为负数，负数会触发低余额提醒。

集成细节见 docs/billing/对话模块计费集成说明.md，核心服务实现位于 BillingService.java。

三、订单管理：5 种状态看懂每一笔充值

充值在 AgentX 中就是一笔"订单"。订单状态定义在 OrderStatus.java，共 5 种状态：

订单管理的关键能力：

• 用户端：通过GET /orders分页查询自己的订单，GET /orders/{orderId}查看单笔详情（对应 OrderController.java）；
• 管理端：管理员可查看全部订单、筛选退款，前端管理页面在 app/(main)/admin/orders/page.tsx/admin/orders/page.tsx)；
• 订单类型：区分充值订单与商品订单，枚举见 OrderType.java。

四、3 步完成充值：支付宝 / 微信支付 / Stripe

AgentX 通过统一的支付抽象层接入多个平台，支付宝、微信支付、Stripe 各有一个 Provider 实现（AlipayProvider.java、StripeProvider.java），支持二维码、网页、H5 等多种支付形式。

第 1 步：选择充值金额

进入 设置 → 计费 页面（billing 页面/settings/billing/page.tsx)），选择预设金额或自定义：

• 预设档位：10 / 50 / 100 / 200 / 500 / 1000元；
• 自定义范围：最小¥0.01，单笔上限¥100,000。

第 2 步：选择支付平台与方式

• 支付宝 / 微信支付：支持二维码支付（QR_CODE）、网页支付等，扫码即付；
• Stripe：面向海外用户，走网页支付，并支持退款；
• 可用方式由后端GET /payments/methods动态返回，未配置的平台不会展示。

第 3 步：等待支付确认

前端会创建充值订单（POST /payments/recharge），生成二维码或跳转链接，然后自动轮询GET /payments/orders/{orderNo}/status查询支付状态；同时支付平台会异步回调POST /payments/callback/{platform}确认到账。余额到账后，页面会显示"充值成功"的动画与 Toast 提示，账户数据即时刷新。

整个充值流程的交互实现可参考 RechargeFlow.tsx（含选金额 → 选方式 → 出二维码 → 等待支付的状态机）。

五、常见问题 FAQ

Q1：余额不足会发生什么？对话前会预检查余额，为负时阻止新对话并提示充值；已进行中的对话不会中途报错，而是收到友好提醒。

Q2：为什么我的余额可能是负数？预检查通过后模型才响应，若单次费用超过余额，允许透支为负。负数余额会触发低余额提醒，充值后即可恢复使用。

Q3：会重复扣费吗？不会。每次计费都带唯一requestId做幂等校验，同一请求重复提交只会计费一次。

Q4：支持退款吗？支付宝与 Stripe 订单支持退款，微信支付暂不支持；退款操作由管理端发起，订单状态会变为"已退款"。

Q5：怎么查我的消费明细？计费页面内置用量明细页，支持按商品、requestId、时间范围筛选并分页查看，接口实现在 PortalUsageRecordController.java。

六、想深入？源码与文档地图

除了 Token 计费，系统还预留了按次（cost_per_unit）、按时长、分层阶梯、存储用量等多种价格配置键，未来 Agent 创建计费、API 调用计费都会复用这套框架，无需改动核心业务表。

七、加入交流社区

对 AgentX 的计费、充值或 Agent 搭建有疑问，可以扫码加入 AgentX 交流群，和其他开发者一起讨论：

掌握 Token 消耗、订单状态与充值流程后，你就可以放心地在 AgentX 上用自然语言构建自己的 Agent 了——余额够、账单透明、随时可查。