Hexclave 用户基础设施平台详解:从一行 AI 提示词到认证、团队、支付、邮件与分析的完整应用目录
Hexclave 用户基础设施平台详解:从一行 AI 提示词到认证、团队、支付、邮件与分析的完整应用目录
Hexclave 定位为 "The user infrastructure platform"——它接管用户相关的一切底层设施:认证、团队、RBAC、支付、邮件、分析与 Webhooks。本文以仓库中的 packages/template/README.md 为骨架,结合 @hexclave/template 包的源码与配置实现,完整解读这份官方 README 的每一项能力:从"一行提示词接入"的 AI 工作流,到十个可插拔应用各自的技术实质,再到配置即代码与多平台 SDK 的构建机制。读完本文,你将掌握 Hexclave 的应用目录全貌、AI Agent 集成方式、真实配置文件的写法,以及底层源码对应的实现位置,可直接用于评估与上手。
Hexclave 是什么:一款"用户基础设施"平台
Hexclave handles everything around your users: authentication, teams, payments, emails, analytics, and much more.
README 开篇即给出了定位:你自由选择前端框架、后端与数据库,Hexclave 负责其余部分。它不是一个把 UI 强绑定的全家桶,而是一套围绕"用户"这个统一数据模型的横向能力平台——认证、团队、支付、邮件、分析等都以可插拔"应用(app)"的形式交付,开发者按产品阶段按需开启。
从仓库结构看,这一理念落地的证据非常直接:packages/template 是 SDK 的统一源码模板,通过 package-template.json 中的平台标记(IF_PLATFORM next、IF_PLATFORM react、IF_PLATFORM js、IF_PLATFORM tanstack-start)编译产出 @hexclave/next、@hexclave/react、@hexclave/js、@hexclave/tanstack-start 等多个框架包,而 packages/template/src/index.ts 作为统一入口,导出了 HexclaveProvider、HexclaveHandler、useHexclaveApp、useUser 以及整套 SignIn/SignUp/AccountSettings 等组件。仓库根 README.md 与 packages/template/README.md 内容一致,是项目对外介绍的权威来源。
快速开始:从一行提示词到可用项目
面向开发者:把提示词交给你的编码 Agent
README 给出的起步方式极简——把下面这行提示词粘贴给你选择的编码 Agent(如 Cursor、Claude Code 等):
Read skill.hexclave.com and help me setup hexclave in this project
仓库中 skills/hexclave/SKILL.md 正是这一流程的服务端支撑:它定义了一个名为 hexclave 的 skill,每次调用都会拉取 https://skill.hexclave.com 上最新的、独立的规范说明,并明确"远程文档优先于模型训练记忆",从而保证集成指令始终最新。
面向 AI Agent:curl 即文档
如果你本身就是编码 Agent,README 给出了可直接执行的取文档命令:
curl -sSL "https://skill.hexclave.com?question=<your-question>&context=<your-context>"
其中 question 携带你的具体问题,context 携带当前项目的上下文信息,服务端返回对应的集成指令。这个端点同时被 SKILL.md 作为 WebFetch 的目标源使用,是 Hexclave 保持"指令单一可信源(single source of truth)"的关键设计。
接入后会发生什么:CLI 与配置即代码
接入 Hexclave 并非只有"云端"一条路。从源码中的错误提示可以还原完整的本地开发链路:在 packages/template/src/lib/hexclave-app/apps/implementations/common.ts 中,当缺少项目 ID 时会抛出欢迎引导错误,其中明确给出了两种启动方式:
-
本地开发:用 Hexclave CLI 包裹启动命令:
npx @hexclave/cli dev --config-file <file> -- <command> -
连接云端:在 Hexclave dashboard 创建项目后,将项目信息写入
HEXCLAVE_PROJECT_ID环境变量。
同一个文件中还定义了其他关键环境变量,优先级与用途如下:
| 环境变量 | 用途 | 缺失时的行为 |
|---|---|---|
HEXCLAVE_PROJECT_ID |
项目标识 | 直接抛错并提示接入方式(见 common.ts) |
HEXCLAVE_PUBLISHABLE_CLIENT_KEY |
客户端可发布的公钥 | 可缺省(getDefaultPublishableClientKey) |
HEXCLAVE_SECRET_SERVER_KEY |
服务端密钥 | 抛错,提示从 dashboard 复制(common.ts) |
HEXCLAVE_SUPER_SECRET_ADMIN_KEY |
管理员超级密钥 | 抛错,提示从 dashboard 复制(common.ts) |
HEXCLAVE_API_URL / HEXCLAVE_API_URL_BROWSER / HEXCLAVE_API_URL_SERVER |
API 基地址(浏览器端/服务端/默认) | 回退到默认值 https://api.hexclave.com(common.ts) |
也就是说,"一行提示词"背后完成的是:拉取最新集成指令 → 生成本地配置文件 → 通过 CLI 将项目与 Hexclave 后端对接。这套流程的产物就是下面要讲的"配置即代码"文件。
应用目录:在同一个用户模型之上按需点亮
README 反复强调的核心心智模型是:
Hexclave ships as a catalog of apps you switch on as your product needs them. Each one is built on the same user model, and new apps land regularly.
即 Hexclave 交付的不是"一个 Auth 服务",而是一组共享同一套用户/团队/权限数据模型的可插拔应用。下面逐项展开十个应用,每项都保留 README 原始描述,并给出仓库内的实现位置作验证。
Authentication:认证开箱即用
Authentication that just works with passkeys, OAuth, and CLI auth. Drop in one component and ship the whole flow; auth methods toggle from the dashboard with no code changes needed.
认证应用覆盖密码(password)、一次性验证码(OTP/MFA)、Passkey(WebAuthn)、OAuth 社交登录、Magic Link 与 CLI 认证。源码侧对应组件均在 packages/template/src/components-page 下:sign-in.tsx、sign-up.tsx、credential-sign-in.tsx、oauth-button-group.tsx、passkey-button.tsx、magic-link-sign-in.tsx、mfa.tsx、forgot-password.tsx、password-reset.tsx、email-verification.tsx 以及 CLI 认证确认页 cli-auth-confirm.tsx。
"一个组件交付整个流程"的落点在于 SignIn / SignUp 等单一组件即可渲染出当前项目所有已启用的登录方式;"从 dashboard 切换、无需改代码"则由配置驱动,见下文 配置即代码 中 auth 段的 allowSignIn 开关。
Teams:面向团队而非单一用户
Build for teams, not just users, with workspaces, email invites, and roles that actually gate the work. The workspace switcher remembers selection, invites auto sign up new users, and permissions hold up under audit.
团队应用提供工作区、邮件邀请、角色门禁。前端组件包括 team-switcher.tsx、selected-team-switcher.tsx(记忆工作区选择)以及账号设置页中的 team-member-invitation-section.tsx、team-member-list-section.tsx、leave-team-section.tsx、team-creation-page.tsx 等(见 packages/template/src/components-page/account-settings/teams)。"邀请自动注册新用户"与"权限经得起审计"的服务端逻辑对应 packages/template/src/lib/hexclave-app/teams 与 packages/template/src/lib/hexclave-app/team-user-permissions。
RBAC:角色嵌套 + 单一权限检查
Permissions, sorted: roles that nest and one permission check that works the same on server or client. Define them in the dashboard, check them anywhere in your code.
RBAC 的关键卖点是角色可嵌套,以及同一套权限检查 API 在服务端与客户端行为一致。实现集中在 packages/template/src/lib/hexclave-app/permissions,权限定义通过 dashboard 落库,代码侧用统一 API 查询,服务端与客户端走同一条数据链路。
API Keys:没有踩坑点的密钥管理
API keys without the footguns: leaked keys get auto-revoked, work for users and teams, and show the full secret only once. We never keep the plaintext after creation.
API Key 应用支持用户级与团队级密钥、泄露自动吊销、明文仅展示一次、服务端不落明文。UI 组件为 api-key-table.tsx 与 api-key-dialogs.tsx(见 packages/template/src/components/api-key-table.tsx),服务端模型见 packages/template/src/lib/hexclave-app/api-keys 与内部管理密钥 packages/template/src/lib/hexclave-app/internal-api-keys。
Payments:订阅、单次扣费与用量计费一模型覆盖
Payments without the plumbing for subscriptions, one-time charges, and usage metering with credits. Bill a person or a whole team with one model, no separate codepath.
支付应用支持订阅、一次性扣费、基于积分(credits)的用量计量,且个人计费与团队计费共用同一模型、无需双代码路径。前端见 packages/template/src/components-page/account-settings/payments 下的 payments-page.tsx 与 payments-panel.tsx;服务端支付核心在 apps/bulldozer-js/src/payments,依赖 @stripe/stripe-js 与 @stripe/react-stripe-js(见 packages/template/package.json)。
Emails:事务邮件 + 营销邮件一体 API
Email that delivers and tells you so, handling transactional and marketing sends from one API. Edit templates with an AI editor, theme once, and track every open and click.
邮件应用把事务邮件与营销邮件统一到一套 API,内置 AI 模板编辑器、一次主题化与打开/点击追踪。SDK 客户端见 packages/template/src/lib/hexclave-app/email 与 email-templates。
Analytics:免数据栈的用户洞察
Know your users with no data stack required, with live active user counts and session replays out of the box. Ask in plain English to build dashboards or write SQL to save queries, all with one flag enabled.
分析应用开箱提供实时活跃用户数与会话回放(session replay),支持自然语言建 dashboard 与 SQL 存查询,只需开启一个开关。回放相关实现见 packages/template/src/lib/hexclave-app/apps/implementations/session-replay.ts 与 event-tracker.ts,事件采集底层使用 rrweb(见 packages/template/package.json 依赖)。
Webhooks:签名防篡改的实时事件推送
React to every user event in real time with signed, tamper-proof webhooks. Retries and backoff are handled for you; verify in five lines and manage endpoints from the dashboard.
Webhooks 对每个用户事件实时推送签名、防篡改的事件,重试与退避由平台负责,五行业务代码即可完成校验,端点从 dashboard 管理。协议细节与校验示例见 docs-mintlify/guides/apps/webhooks/webhooks.mdx,webhook 在 openapi 中的请求/响应规范见 docs-mintlify/openapi/webhooks.json。
Data Vault:用你的密钥锁住用户机密
A safe for the secrets your users hand you, locked with your secret so we never see the plaintext. Store and retrieve tokens in two lines each, server-only by design.
数据保险库用于安全托管用户交给你的第三方 token(如 OAuth access token),加密密钥由你掌握、平台侧不见明文,服务端专属设计。存储与读取各两行代码,API 见 packages/template/src/lib/hexclave-app/data-vault。
Launch Checklist:上线前的必做清单
Run through the must-do checks before flipping to production: domain setup, callbacks locked, secrets rotated. The progress tracker keeps your team aligned so nothing critical slips through on launch day.
上线清单覆盖域名配置、回调地址锁定、密钥轮换等生产前必做检查,并提供进度跟踪,帮助团队在发布日不漏项。使用说明见 docs-mintlify/guides/apps/launch-checklist。
hexclave.config.ts:配置即代码
README 强调"auth methods toggle from the dashboard with no code changes needed",其底层机制正是配置以代码形式存在于项目仓库。demo 项目给出了一个真实、完整的配置示例(examples/demo/hexclave.config.ts):
import { defineHexclaveConfig } from "@hexclave/next";
export const config = defineHexclaveConfig({
emails: {
selectedThemeId: "a0172b5d-cff0-463b-83bb-85124697373a",
},
auth: {
password: {
allowSignIn: true,
},
otp: {
allowSignIn: true,
},
oauth: {
providers: {
google: {
type: "google",
allowSignIn: true,
allowConnectedAccounts: true,
},
github: {
type: "github",
allowSignIn: true,
allowConnectedAccounts: true,
},
},
},
},
apps: {
installed: {
authentication: { enabled: true },
payments: { enabled: true },
emails: { enabled: true },
analytics: { enabled: true },
},
},
});
这个示例可以让你直观看到三层结构:
auth段:每个认证方式(password、otp、oauth 提供商)都有独立的allowSignIn/allowConnectedAccounts开关,对应 README 中"从 dashboard 切换认证方式"的配置来源;apps.installed段:每个应用有enabled开关,印证了"catalog of apps you switch on"的按需点亮模型;- 顶层:还可以配置邮件主题等全局偏好。
defineHexclaveConfig 的实现位于 packages/shared/src/config-authoring.ts,它并非简单的类型标注:内部通过 StrictConfigShape 对配置对象做逐字段严格校验(config-authoring.ts),任何不属于 schema 的多余键或类型错误的键都会在编译期报错,保证"配置即代码"不产生脏数据。demo 配置的注释还说明:该文件是 RBAC 权限/角色、认证方式、OAuth 提供商、注册规则、API Key 与支付方案的单一事实来源,Hexclave CLI(hexclave dev)会打包并执行此文件,将项目按配置实际落地。
旧项目如需兼容,可继续从 <pkg>/config 入口导入(见 packages/template/src/config.ts),但源码注释明确标注该入口已不推荐,新配置应从包根导入 defineHexclaveConfig 与类型。
一个模板,多平台产物:SDK 的构建机制
"你选择前端"这句话的工程实现,体现在 @hexclave/template 的模板化构建机制上。packages/template/package-template.json 用 IF_PLATFORM next / ELSE_IF_PLATFORM js / END_PLATFORM 等标记注释声明条件块,同一份源码据此编译出不同框架包:@hexclave/template(模板本体,私有)、@hexclave/js、@hexclave/next、@hexclave/react、@hexclave/tanstack-start。
各平台的差异被收敛到 peerDependencies 上(package-template.json):
- React 生态统一要求
react >= 18.0.0与react-dom >= 18.0.0; - Next.js 包要求
next >= 14.1 || >=15.0.0-canary.0 || >=15.0.0-rc.0; - TanStack Start 包要求
@tanstack/react-router >= 1.100.0与@tanstack/react-start >= 1.100.0。
包根导出(packages/template/src/index.ts)为所有平台提供一致的面:
HexclaveProvider(providers/hexclave-provider.tsx)、HexclaveHandler(components-page/hexclave-handler.tsx)、useHexclaveApp / useUser(lib/hooks.tsx),以及 SignIn、SignUp、AccountSettings、UserButton、TeamSwitcher 等一套 UI 组件。
值得一提的是 HexclaveHandler 的兼容处理:hexclave-handler.tsx 专门保留了对旧版 <StackHandler app={...} routeProps={props} /> 调用方式的兼容——旧的 app、routeProps、params、searchParams 参数全部标记 @deprecated 并被忽略,组件内部直接渲染 HexclaveHandlerClient,避免不可序列化对象在 Server/Client 组件间传参时报错。源码注释中还保留了旧品牌名 StackHandler 的迁移说明(新名 HexclaveHandler,同一符号、新品牌名)。
对于 Convex 用户,包内还提供了官方集成:getConvexProvidersConfig(packages/template/src/integrations/convex.ts)生成基于 customJwt 的 Convex 认证提供方配置,其中 JWKS 端点指向 Hexclave 项目服务(含匿名用户变体),配合包导出 ./convex.config 与 ./convex-auth.config 使用。
部署形态与自托管
README 徽章标明"Cloud or self-hosted"两种部署方式。SDK 侧为部署声明了完整的作者面类型(packages/shared/src/config-authoring.ts 起的 deployments 段):HexclaveDeploymentConfig、HexclaveDeploymentContext、HexclaveEnvVarValue(字面量、null 省略、或来自 secret() / service(...).<output> / hexclave.<output> 的不透明引用)、HexclavePersistentVolume、HexclaveServerService / HexclaveServerlessService 等,供部署文件的 deploy 导出使用——编辑器内获得类型补全,CLI 在运行时仍会再次校验,因为部署文件是任意用户 TypeScript。自托管的具体操作步骤以 docs-mintlify/other/self-host.mdx 与 docs-mintlify/going-further/hosted-vs-handler.mdx 为准。
开源、许可与贡献
README 末尾声明 Hexclave 为开源项目并欢迎贡献:
- 许可徽章标明 MIT / AGPLv3 双许可(仓库根目录有 LICENSE);
- 贡献指南见仓库根 CONTRIBUTING.md;
- 贡献者在认领较大的改动前,可先加入官方 Discord 沟通;
- 发现安全问题请邮件联系
security@hexclave.com(README 原文说明)。
小结
从 packages/template/README.md 出发可以提炼出 Hexclave 的三层设计:表面是"一行提示词接入"的极简体验与十个按需点亮的应用;中层是配置即代码(defineHexclaveConfig)驱动的、dashboard 与代码库共享的单一事实来源;底层则是一个统一用户模型 + 多平台 SDK 模板(Next.js / React / JS / TanStack Start / Convex)。如果你想进一步深入,推荐按以下路径阅读源码:从 packages/template/src/index.ts 看导出全貌,从 examples/demo/hexclave.config.ts 看真实配置,再从 packages/shared/src/config-authoring.ts 理解类型级校验的实现细节。