Whirl

一款注重细节的 AI 聊天应用。所有顶级模型、真实记忆、
活文档与你的自有工具，汇集在一个快速而友好的地方。

Whirl 是一个基于 Next.js 和 Convex 构建的全栈 AI 聊天应用。它是 whirl.chat 背后的代码，以 MIT 许可证完整发布。你可以阅读它、运行自己的实例，或帮助它变得更好。

功能特性

一个对话中使用所有顶级模型，通过 OpenRouter 路由，并可调节思考等级。
活文档（Living artifacts）：文档、图表和完整的交互式页面，可在侧边栏中持续编辑，并可通过链接分享。
集成你自己的工具，基于 MCP（含 OAuth），还可安装技能（skills）教会 Whirl 新本领。
长期记忆，在对话之间延续你的偏好和项目。
实时联网搜索与网页阅读，让回答立足于今天的网络。
锁定聊天：在你的设备上以密码加密（服务器永远看不到密码），仅由零保留（zero-retention）模型响应。
隐身模式、消息排队、语音输入、图像生成、文件附件、文件夹、分享，以及对动效和细节打磨的大量用心。
浅色与深色模式、主题色，以及可安装的移动端 Web 应用。

技术栈

层级	所用技术
Web 应用	Next.js 16、React 19、Tailwind CSS v4、Motion
后端	Convex：数据库、函数、流式处理、定时任务
认证	Clerk
模型	通过 AI SDK 使用 OpenRouter
工具链	Bun workspaces、TypeScript

除 Convex、Clerk 和 OpenRouter 之外的一切都是可选的，配置各自的密钥即可启用：计费（Autumn）、网络搜索（Exa）、记忆（Supermemory）、分析（PostHog、Axiom）、追踪（Braintrust）、邮件（Resend）以及客服代理（Median）。不配置它们，Whirl 会自动隐藏相应功能。详见 docs/configuration.md。

快速开始

你需要 Bun、一个免费的 Convex 账户、一个 Clerk 应用，以及一个 OpenRouter API 密钥。

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

# 1. 创建 Convex 开发部署并推送后端。
cd packages/backend
bunx convex dev            # 首次运行会引导你创建项目

# 2. 在另一个终端中，为后端配置密钥。
bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

# 3. 将 Web 应用指向 Convex 和 Clerk。
cd ../../apps/v2
cp .env.example .env.local  # 然后填入四个必填值

# 4. 在仓库根目录运行一切。
cd ../..
bun run dev

打开 localhost:3000 打个招呼吧。自托管指南详细介绍了每一步，包括 Convex 所需的 Clerk JWT 模板以及如何部署到生产环境。

仓库结构

apps/
  v2/         Web 应用（Next.js）。这是生产环境使用的版本。
  console/    管理模型、集成与技能的管理控制台（Vite）
  mobile/     原生应用（Expo）
  waitlist/   独立的候补名单页面
  remotion/   宣传视频合成
  legacy/     上一代 Web 应用，仅供参考。不再维护。
packages/
  backend/    Convex 后端：schema、函数与 AI 流水线
docs/         自托管、配置与架构指南
brand/        Logo、配色、横幅与应用图标

文档

自托管：在本地和生产环境运行 Whirl
配置：每个环境变量及其启用的功能
架构：一条消息如何从输入框到模型再返回
贡献指南：规范、检查与 pull request

参与贡献

欢迎提交 bug 报告、想法和 pull request。请先阅读 CONTRIBUTING.md，并遵守行为准则。发现安全问题？请参阅 SECURITY.md。