用途：为使用 Spree Commerce（BSD-3 开源、基于 Ruby on Rails 的无头电商框架）的开发者提供平台级帮助，涵盖 B2B、marketplace 与多店铺场景，包括 API 集成与调试、Webhook 事件响应、AI 智能体工具使用、版本升级、自托管及社区版与企业版选型、结账转化等问题。若问题属于跨平台销售策略，则路由到对应技能（如 /sales-checkout、/sales-merchant-of-record、/sales-email-marketing）。
主要能力：区分并指导三类 API——Store API（/api/v3/store，面向店面，使用 publishable key pk_xxx 加每个购物车的订单令牌，公开目录读取无需密钥）、Platform API（/api/v2/platform，机器对机器，使用 OAuth2）、Admin API（/api/v3/admin，5.5 起开源，使用限定范围的密钥）、旧版 Storefront API v2（/api/v2/storefront）。支持原生出站 Webhook 订阅与投递日志查询。介绍 5.5+ 的 AI 智能体工具面，包括约 25 个可安装 agent skills、文档 MCP 服务器（https://spreecommerce.org/docs/mcp）、Admin API CLI，以及脚手架项目中自动生成的 CLAUDE.md/AGENTS.md。
使用方式：Platform API 认证走 OAuth2 两步——先在 Admin → Apps → OAuth Applications 创建 OAuth 应用并复制 Client ID 与 Secret，再 POST {store_url}/spree_oauth/token，参数为 grant_type=client_credentials、client_id、client_secret、scope=admin，返回的 access_token 以 Authorization: Bearer {access_token} 发送，令牌会过期需重新获取。注册 Webhook 订阅者通过 Platform API 的 /api/v2/platform/webhooks/subscribers，提交 url 与 subscriptions 数组（['*'] 表示全部事件，或 order.canceled 等具体事件名）；每次投递记录为 Webhook Event（name、response_code、success、request_errors）以便排查失败。
适用场景：编写订单同步等后端集成脚本、订阅订单取消等事件通知、用 AI 智能体构建或运维 Spree、规划版本升级、评估自托管与企业版。
限制与注意：不要混淆 API 与令牌类型，401 通常意味着用了与目标 API 不匹配的令牌。Webhook 签名/HMAC 方案需在正式依赖前对照线上文档核实。历史上升级易破坏定制与扩展，应将定制保持为薄装饰器/覆盖而非 fork 核心。自助托管需具备 Rails 运维能力（Postgres、Redis、Sidekiq worker、MeiliSearch），并非一键托管。Spree 不是 Merchant of Record，税款申报需自行负责。资料为 2026-06 研究所得，版本门槛、费用、认证与 API 形态应另行核实。