⚡

StripeAgent stripe-agent

Stripe Agent 是一个管理 Unite-Hub 平台所有 Stripe 计费操作的技能，包括产品和价格管理、结账会话创建、订阅管理、客户管理、发票管理等。它支持双模式（测试/实时）计费系统，确保员工测试和实际客户支付的分离。

支付系统 0 次安装 0 次浏览 更新于 3/3/2026

Stripe Agent 技能

Agent ID: unite-hub.stripe-agent 模型: claude-sonnet-4-5-20250929 MCP服务器: stripe (通过 @stripe/mcp)

角色

管理 Unite-Hub 的所有 Stripe 计费操作，包括产品/价格创建、订阅管理、结账会话、Webhooks，以及员工与客户分离的双模式（测试/实时）计费。

能力

1. 产品和价格管理

创建产品

// 为定价层创建产品
mcp__stripe__create_product({
  name: "Unite Hub Professional",
  description: "完整的 CRM 和 AI 营销自动化",
  metadata: {
    tier: "professional",
    features: "unlimited_contacts,ai_scoring,drip_campaigns"
  }
})

创建价格

// 月度价格（澳元，含 GST）
mcp__stripe__create_price({
  product: "prod_xxx",
  unit_amount: 89500, // $895.00 澳元（分）
  currency: "aud",
  recurring: { interval: "month" },
  metadata: { tier: "professional", billing: "monthly", gst_included: "true" }
})

// 年度价格（澳元，含 GST）
mcp__stripe__create_price({
  product: "prod_xxx",
  unit_amount: 895000, // $8,950.00 澳元（2个月免费）
  currency: "aud",
  recurring: { interval: "year" },
  metadata: { tier: "professional", billing: "annual", gst_included: "true" }
})

2. 结账会话

创建结账会话

mcp__stripe__create_checkout_session({
  mode: "subscription",
  customer_email: "customer@example.com",
  line_items: [{
    price: "price_xxx",
    quantity: 1
  }],
  success_url: "https://synthex.social/dashboard?success=true",
  cancel_url: "https://synthex.social/pricing?cancelled=true",
  metadata: {
    workspace_id: "uuid",
    tier: "professional"
  }
})

3. 订阅管理

列出订阅

mcp__stripe__list_subscriptions({
  customer: "cus_xxx",
  status: "active"
})

更新订阅（升级/降级）

// 通过 API 路由，更新订阅项目
// 从入门版切换到专业版价格

取消订阅

// 通过 API 路由，正确处理
// 选项：立即或在周期结束时

4. 客户管理

创建客户

mcp__stripe__create_customer({
  email: "new@customer.com",
  name: "John Doe",
  metadata: {
    user_id: "uuid",
    workspace_id: "uuid"
  }
})

列出客户

mcp__stripe__list_customers({
  email: "customer@example.com"
})

5. 发票管理

列出发票

mcp__stripe__list_invoices({
  customer: "cus_xxx",
  status: "paid"
})

创建发票

mcp__stripe__create_invoice({
  customer: "cus_xxx",
  auto_advance: true,
  metadata: {
    workspace_id: "uuid"
  }
})

双模式计费架构

Unite-Hub 使用双模式计费系统来分离员工测试和实际客户支付。

模式确定逻辑

// 从 src/lib/billing/stripe-router.ts

// 测试模式触发器：
// 1. 员工角色：founder, staff_admin, internal_team, super_admin
// 2. 注册的沙箱电子邮件（SANDBOX_STAFF_REGISTRY）
// 3. 内部域名：unite-group.in, disasterrecoveryqld.au, carsi.com.au

// 实时模式：
// 所有其他用户（实际客户）

所需环境变量

# 测试模式（员工/内部）
STRIPE_TEST_SECRET_KEY=sk_test_...
STRIPE_TEST_WEBHOOK_SECRET=whsec_test_...
STRIPE_TEST_PRICE_STARTER=price_...
STRIPE_TEST_PRICE_PRO=price_...
STRIPE_TEST_PRICE_ELITE=price_...
NEXT_PUBLIC_STRIPE_TEST_PUBLISHABLE_KEY=pk_test_...

# 实时模式（客户）
STRIPE_LIVE_SECRET_KEY=sk_live_...
STRIPE_LIVE_WEBHOOK_SECRET=whsec_live_...
STRIPE_LIVE_PRICE_STARTER=price_...
STRIPE_LIVE_PRICE_PRO=price_...
STRIPE_LIVE_PRICE_ELITE=price_...
NEXT_PUBLIC_STRIPE_LIVE_PUBLISHABLE_KEY=pk_live_...

定价层级（澳元，含 GST）

层级 每月 每年 功能
入门版 $495 $4,950 基础 CRM, 500 联系人, 电子邮件集成
专业版 $895 $8,950 完整 CRM, 无限联系人, AI 评分, 滴灌活动
精英版 $1,295 $12,950 一切 + 白标, 优先支持, 自定义集成

货币：澳大利亚元（AUD） 税收：所有价格包括 10% GST

此代理执行的任务

任务 1：设置完整的 Stripe 产品

触发器：“设置 Stripe 产品” 或首次计费初始化

步骤：

  1. 创建入门版产品和价格（每月 + 每年）
  2. 创建专业版产品和价格
  3. 创建精英版产品和价格
  4. 在环境变量中存储价格 ID
  5. 配置 Webhook 端点

输出：

{
  "products": {
    "starter": "prod_xxx",
    "professional": "prod_yyy",
    "elite": "prod_zzz"
  },
  "prices": {
    "starter_monthly": "price_xxx",
    "starter_annual": "price_xxy",
    "professional_monthly": "price_yyy",
    "professional_annual": "price_yyz",
    "elite_monthly": "price_zzz",
    "elite_annual": "price_zza"
  }
}

任务 2：为用户创建结账

触发器：用户在定价页面点击 “订阅”

输入：

{
  "email": "user@example.com",
  "tier": "professional",
  "billing": "monthly",
  "workspaceId": "uuid",
  "userId": "uuid"
}

步骤：

  1. 确定计费模式（基于电子邮件测试/实时）
  2. 获取或创建 Stripe 客户
  3. 使用正确的价格创建结账会话
  4. 返回结账 URL

任务 3：处理订阅升级

触发器：用户在计费设置中点击 “升级”

输入：

{
  "currentTier": "starter",
  "targetTier": "professional",
  "subscriptionId": "sub_xxx",
  "workspaceId": "uuid"
}

步骤：

  1. 获取当前订阅
  2. 计算预付款
  3. 更新订阅项目
  4. 处理计费调整
  5. 在数据库中更新工作区层级

任务 4：处理 Webhook 事件

触发器：收到 Stripe Webhook

处理的事件：

  • checkout.session.completed → 激活订阅
  • customer.subscription.created → 创建订阅记录
  • customer.subscription.updated → 更新层级，同步状态
  • customer.subscription.deleted → 停用订阅
  • invoice.paid → 标记为已支付，延长访问
  • invoice.payment_failed → 标记账户，发送通知

任务 5：生成计费报告

触发器：“生成计费报告” 或每月计划

输出：

{
  "period": "2025-11",
  "revenue": {
    "total": 15890.00,
    "byTier": {
      "starter": 4850.00,
      "professional": 8910.00,
      "elite": 2130.00
    }
  },
  "subscriptions": {
    "active": 87,
    "new": 12,
    "churned": 3,
    "mrr": 15890.00
  },
  "trials": {
    "active": 23,
    "converted": 8,
    "expired": 5
  }
}

任务 6：审核 Stripe 配置

触发器：“审核 Stripe 设置” 或健康检查

检查：

  1. 所有环境变量都存在
  2. Stripe 仪表板中存在产品
  3. 价格配置正确
  4. Webhooks 已注册
  5. 测试模式产品与实时模式结构匹配

输出：

{
  "status": "healthy" | "degraded" | "critical",
  "checks": {
    "env_vars": { "status": "pass", "missing": [] },
    "products": { "status": "pass", "count": 3 },
    "prices": { "status": "pass", "count": 6 },
    "webhooks": { "status": "warn", "message": "Live webhook not configured" }
  },
  "recommendations": [
    "Add STRIPE_LIVE_WEBHOOK_SECRET to production environment"
  ]
}

Webhook 端点

测试模式

  • URL: https://your-domain.com/api/webhooks/stripe/test
  • 事件: 所有订阅和发票事件
  • 密钥: STRIPE_TEST_WEBHOOK_SECRET

实时模式

  • URL: https://your-domain.com/api/webhooks/stripe/live
  • 事件: 所有订阅和发票事件
  • 密钥: STRIPE_LIVE_WEBHOOK_SECRET

错误处理

常见错误

错误 原因 解决方案
StripeCardError 卡被拒 通知客户，请求新卡
StripeInvalidRequestError API 调用错误 检查参数，记录日志以调试
StripeAuthenticationError API 密钥无效 验证环境变量
StripeRateLimitError 请求过多 实施指数退避

重试策略

const MAX_RETRIES = 3;
const RETRY_DELAYS = [1000, 2000, 4000]; // 指数退避

async function stripeWithRetry(operation) {
  for (let i = 0; i < MAX_RETRIES; i++) {
    try {
      return await operation();
    } catch (error) {
      if (error.type === 'StripeRateLimitError' && i < MAX_RETRIES - 1) {
        await sleep(RETRY_DELAYS[i]);
        continue;
      }
      throw error;
    }
  }
}

与其他代理的集成

编排器 → Stripe 代理

编排器
  ├─→ [新注册] → Stripe 代理：创建客户
  ├─→ [升级请求] → Stripe 代理：处理升级
  ├─→ [Webhook] → Stripe 代理：处理事件
  └─→ [审核] → Stripe 代理：审核配置

数据库同步

在 Stripe 操作后，同步到 Supabase：

// 在成功的订阅后
await supabase.from('subscriptions').upsert({
  workspace_id: workspaceId,
  stripe_customer_id: customerId,
  stripe_subscription_id: subscriptionId,
  tier: tier,
  status: 'active',
  current_period_end: periodEnd
});

测试

测试卡

卡号 场景
4242424242424242 成功
4000000000000002 拒绝
4000000000009995 资金不足
4000002500003155 需要 3D Secure

手动测试

# 触发测试 Webhook
stripe trigger checkout.session.completed

# 本地监听 Webhooks
stripe listen --forward-to localhost:3008/api/webhooks/stripe/test

文件参考

文件 目的
src/lib/billing/stripe-router.ts 双模式路由逻辑
src/lib/billing/pricing-config.ts 定价层定义
src/lib/payments/stripeClient.ts Stripe 客户端包装器
src/app/api/billing/subscription/route.ts 订阅 API
src/app/api/webhooks/stripe/[mode]/route.ts Webhook 处理器
src/app/api/stripe/checkout/route.ts 结账会话创建

快速命令

# 运行 Stripe 设置脚本（待创建）
npm run stripe:setup

# 审核 Stripe 配置
npm run stripe:audit

# 从 Stripe 同步产品
npm run stripe:sync

# 本地测试 Webhook
npm run stripe:webhook-test

技能文件创建：2025-11-28