Sellbase

为什么选择 Sellbase

• 一切尽在掌握。 你的数据存储在自己的 Postgres 中，收入直接进入自己的 Stripe 账户，代码保留在自己的代码仓库中。没有平台费用、没有供应商锁定，也没有 Sellbase 服务器介入。采用 MIT 许可。
• AI 优先。 sellbase init 会写入 CLAUDE.md/AGENTS.md、技能和 MCP 服务。告诉你的 Agent“搭建我的商店”，它就会创建商品、接入支付并完成测试购买。涉及资金和破坏性操作时，总会先征得所有者同意，并记录所有操作。
• 适用于任何网站。
  • Next.js 和 Vite + React： React 组件。
  • 纯 HTML、WordPress、Webflow、Vue、Svelte、Astro、Angular： <sellbase-*> Web 组件（gzip 压缩后为 13 KB）和静态管理后台。
• 易于使用的管理后台。 商品支持拖放照片和变体，库存管理，带装箱单和退款功能的订单管理，弃购购物车挽回，客户管理，折扣，以及各种连接的设置。此外还有：
  • 命令面板（⌘K），用于搜索和执行操作；
  • 首页上的 AI 副驾驶；
  • 专为商店所有者打造，而非开发者。
• 默认安全。
  • 金额以整数存储。
  • 每张表都启用 RLS，并配有测试。
  • 订单仅通过已验证的支付 Webhook 创建。
  • 写入操作具有幂等性。
  • 第三方密钥存储在 Supabase Vault 中。
  • 出站 Webhook 均经过签名，且绝不会访问私有网络。

选择 Sellbase，还是自己构建？

在 Next.js + Supabase 应用中添加商店，通常需要手动编写：一个 products 表、购物车、用于 Stripe Checkout 的 Server Action，以及一个 webhook 路由。第一次销售时，这样做没问题。Sellbase 使用的就是同一套技术栈（你的 Supabase 和你的 Stripe），其余部分则已构建并测试完毕。

	手动构建（Supabase + Stripe）	Sellbase
设置	需要编写并维护 5–6 个文件	npx sellbase init
在现有应用和 Supabase 中运行	是	是：使用独立的 sellbase schema，无需额外服务
面向所有者的管理后台	Supabase 控制台，或自行构建	/admin：商品、照片、变体、订单、退款、折扣
库存、变体、运费、税费、折扣	每项都要自行构建	已包含
订单仅由经过验证的 webhook 创建，且具备幂等性	由你决定	内置，并附带测试
电子邮件、弃购挽回、退款	每项都要自行构建	已包含
你的 AI Agent 可以管理商店（创建商品、查看订单……）	否	MCP 服务提供 31 个工具；涉及资金和破坏性操作时会征求所有者确认

与 Medusa、Vendure 或 Saleor 等引擎不同，Sellbase 无需单独的后端服务。它与应用一起运行在 Supabase Edge Functions 上，店面组件则会复制到你的代码仓库中，供你自行编辑。

快速开始

要求：Node 20+ 和一个 Supabase 项目（或使用 Docker 运行本地技术栈）。

npx supabase start          # local stack (or pass --supabase-url … for a hosted project)
npx sellbase init --yes     # schema, Edge Functions, store, owner, admin, components, agent files

然后：

• **管理后台：**打开 /admin 并登录。本地环境中，所有者的电子邮件和密码位于 .env.sellbase。
• **设置：**按照首页上的设置指南操作。
• **或者让你的 Agent 来完成：**在项目中打开它，然后说 "Configura mi tienda con Sellbase" / "Set up my store with Sellbase"。它会使用 sellbase MCP 工具，直到成功完成一笔测试购买。

npx sellbase doctor         # checklist with the next step for anything missing
npx sellbase upgrade        # new versions: dry run, backup, migrations, functions, components

从模板开始

npx sellbase create my-store --template nextjs   # Next.js store with the admin at /admin
npx sellbase create my-landing --template html   # plain HTML landing page, no build step

两者都位于 examples/，并提供 Vercel 和 Netlify 部署按钮。

使用 Claude Code

/plugin marketplace add jlgavel011/sellbase
/plugin install sellbase@sellbase
/sellbase:setup I sell handmade candles, $250 MXN each, shipping $120

该插件会将 Sellbase 技能和 MCP 服务带到每个项目中。/sellbase:setup 会安装 Sellbase、创建商品、以测试模式连接 Stripe，并运行一次测试购买。其他任何 MCP 客户端都可以使用 npx sellbase mcp（在 MCP 注册表中的名称为 io.github.jlgavel011/sellbase）。

使用任意 Agent（Cursor、Codex、Copilot、Gemini CLI、Windsurf……）

npx skills add jlgavel011/sellbase    # the Sellbase skills, including add-ecommerce

然后让你的 Agent“为此项目添加一个商店”。add-ecommerce 技能会安装并设置 Sellbase。

使用 shadcn

店面组件也兼容 shadcn 注册表：

npx shadcn add https://jlgavel011.github.io/sellbase/r/store.json          # everything
npx shadcn add https://jlgavel011.github.io/sellbase/r/product-grid.json   # or one component

它们仍需要后端：npx sellbase init --yes。索引位于 /r/registry.json。

上线：部署指南和 使用 Stripe 进行实时支付。

功能

商品目录：

• 实体商品、数字下载内容和可预约的服务；
• 每件商品最多 3 个选项（尺码、颜色……），并支持变体矩阵、划线价和 SEO；
• 商品系列、标签以及每个变体的库存；
• CSV 导入（包括 Shopify 导出文件）和导出；
• 可预览的批量价格调整。

结账：

• Stripe Checkout（银行卡、Apple Pay、Google Pay；测试和正式模式）；
• 运费、免运费门槛和本地自取；
• 含税或不含税；
• 折扣码和自动折扣；
• 服务定金；
• 必选的同意复选框（例如，购买酒类需年满 18 周岁），由服务端强制执行并随订单存储。

订单：

• 付款和履约状态；
• 包含承运商和追踪信息的配送；
• 全额或部分退款；
• 取消订单并恢复库存；
• 带评论的时间线；
• 可打印的装箱单；
• 手动订单（现金、转账、WhatsApp）和付款链接。

业务增长：

• 针对弃置结账的一键或自动召回邮件，可恢复购物车；
• 包含历史记录的客户信息；
• 销售指标和畅销商品。

服务：

• 配有每周营业时间和例外安排的资源；
• 可预约时间；
• 预约及提醒（提前 24 小时和 2 小时）和日历邀请。

邮件（Resend）： 订单确认（附下载链接）、配送更新、退款、取消、预约通知和购物车召回。所有邮件都会显示你的徽标和品牌颜色。

团队与 AI：

• 员工角色和邀请；
• 面向 Agent 的带作用域 API 令牌（资金和数据导出作用域需主动启用）；
• 活动日志；
• 带签名的出站 Webhook，支持重试，可对接 ERP、电子表格或 Zapier。

店面：

• 复制到你的代码库中的 React 组件（可自由编辑）；
• 无头 Hooks；
• 适用于任何网站的 Web 组件；
• SEO 辅助工具（JSON-LD、站点地图）；
• 订单查询和下载页面；
• 无障碍标记（使用 axe 检查）。

工作原理

your site ──(@sellbase/react or <sellbase-*> web components)──┐
/admin (@sellbase/admin) ─────────────────────────────────────┤
your AI agent ──(sellbase MCP server)─────────────────────────┤
                                                              ▼
                    Supabase: Edge Functions (sellbase-api, -webhooks, -jobs)
                              Postgres schema `sellbase` (RLS) · Vault · Storage · pg_cron
                                                              │
                                   Stripe · Resend · your webhooks

• 统一的 API 契约。 每条路由都在 @sellbase/core 中使用 Zod 声明一次。Hono 服务通过它进行验证，OpenAPI 规范和类型化 SDK 由此生成，MCP 工具也会复用它。
• 快照。 订单会保存价格、标题和地址的副本，因此之后的商品目录变更不会影响历史订单。
• Outbox。 业务事件与变更在同一事务中写入；后台任务会据此发送邮件和 Webhook。

Package	What it is
sellbase	命令行工具：init、doctor、upgrade、add、seed、token、mcp
@sellbase/admin	管理后台（React），也可作为静态页面提供
@sellbase/react	面向店面的 Provider 和 Hooks
@sellbase/web	适用于任何网站的 Web 组件
@sellbase/sdk	类型化 API 客户端和 SEO 辅助工具
@sellbase/mcp	面向 AI Agent 的 MCP 服务
@sellbase/core	Schema、API 契约、定价和状态机

文档

• 入门指南（西班牙语）
• 使用 Supabase 为 Next.js 应用添加电商商店（西班牙语）
• 部署到生产环境
• 自定义管理后台
• 使用 Stripe 收取真实款项（西班牙语）
• API 参考，以及供 Agent 使用的 llms.txt 和 llms-full.txt
• 规范和架构决策
• 更新日志

开发

pnpm i
pnpm exec supabase start && node scripts/seed-demo.mjs
pnpm dev                    # playground on http://localhost:3100 (admin at /admin)
pnpm lint && pnpm typecheck && pnpm test
pnpm test:db                # pgTAP
pnpm test:integration       # API against the local database
pnpm test:e2e               # Playwright
node scripts/acceptance.mjs # clean project → init → agent over MCP → test purchase

请参阅 CONTRIBUTING.md。安全问题请参阅 SECURITY.md。

状态

Sellbase 当前为 0.3 版，虽还年轻，但功能完整。每次提交都会通过 CI 覆盖完整流程：

• pgTAP；
• API 集成测试；
• Playwright 端到端测试；
• 使用真实 Agent 通过 MCP 进行的全新安装验收测试。

路线图中的后续计划：

• 为各托管服务提供商编写安装指南；
• 支持更多支付服务提供商（Mercado Pago、通过 Stripe 接入 OXXO）；
• 集成运输标签；
• 开具发票（CFDI）。

西班牙语版

Sellbase 是一套开源电商工具包，可安装在你的项目中（你的代码仓库和 Supabase），并可由你的 AI Agent 配置和操作。

包含内容：

• 带照片和变体的商品目录；
• Stripe 结账；
• 订单、库存和弃置购物车；
• 折扣、预约和电子邮件；
• 位于 /admin 的完整管理后台；
• 一个 API 和一个 MCP 服务。

它适用于 Next.js、Vite + React，也适用于任何网站（纯 HTML、WordPress、Webflow……），并通过 Web Components 集成。

npx supabase start
npx sellbase init --yes

接着访问 /admin（在本地环境中，用户名和密码保存在 .env.sellbase 中），或者告诉你的 Agent：“使用 Sellbase 配置我的商店”。

指南：入门指南、使用 Stripe 收取真实款项和部署。

许可证

MIT