Tutor-GPT

Tutor-GPT 是由 Plastic Labs 开发的基于大语言模型的学习伙伴。它能够动态地分析你的学习需求，并自动更新自身的提示词，以更好地满足你的学习需求。

我们借鉴了“心理理论”相关的实验成果，因此 Tutor-GPT 不再仅仅是一个阅读辅导工具，而是一个功能全面的学习伙伴。关于其工作原理的详细说明，请参阅 这里。

Tutor-GPT 由 Honcho 提供支持，用于构建强大的用户画像并为每位用户提供个性化的体验。

tutor-gpt 的托管版本名为 Bloom，以此向本杰明·布鲁姆提出的“二西格玛问题”致敬。

此外，你也可以按照以下说明运行属于自己的 Bot 实例。

项目结构

Tutor-GPT 项目是一个使用 App Router 的 Next.js 应用程序。

• app/ — 页面、布局和 API 路由
• hooks/ — 前端自定义 Hook
• util/ — 各种实用函数及与外部服务的集成
• components/ — 包含 Tutor-GPT 的全栈 Next.js 版本
• supabase/ — 包含设置本地 Supabase 所需的 SQL 脚本
• scripts/ — 用于项目初始化和同步的生命周期脚本

我们使用 pnpm 进行依赖管理。

该项目还集成了多个第三方服务：

• Honcho 用于身份建模和个性化
• Supabase 用于用户认证和数据库管理
• Openrouter 用于大语言模型集成
• PostHog 用于数据分析
• Stripe 用于支付处理

安装

克隆仓库并安装所需的 Node.js 依赖项：

git clone https://github.com/plastic-labs/tutor-gpt.git && cd tutor-gpt
pnpm install

在 .env.local 文件中配置你的 环境变量，然后启动开发服务器：

pnpm run dev

使用浏览器打开 http://localhost:3000，即可查看效果。

环境变量

本节介绍运行 Tutor-GPT Web UI 所需的各种环境变量。我们提供了一个 .env.template 文件，方便你快速上手。

核心

• NEXT_PUBLIC_SITE_URL — Next.js 应用程序将运行的 URL。本地开发时，默认值为 http://localhost:3000。

LLM

• AI_API_KEY — 推理服务提供商的 API 密钥
• AI_PROVIDER — LLM 推理服务提供商的名称
• AI_BASE_URL — 兼容 OpenAI 的 LLM 推理 API 端点
• MODEL — 用于生成响应的 LLM 模型。

Mistral

• MISTRAL_API_KEY — Mistral OCR 的 API 密钥

Honcho

• HONCHO_URL — 需要使用的 Honcho 实例的 URL
• HONCHO_APP_NAME — 在 Honcho 中使用的应用名称

Supabase

• NEXT_PUBLIC_SUPABASE_URL — 你的 Supabase 项目的 URL。
• NEXT_PUBLIC_SUPABASE_ANON_KEY — 你的 Supabase 项目的公共 API 密钥。
• SUPABASE_SERVICE_ROLE_KEY — Supabase 项目的服务密钥。
• JWT_SECRET — 用于签名 JWT 令牌的密钥。

Stripe

• NEXT_PUBLIC_STRIPE_ENABLED — 用于启用或禁用 Stripe 的功能标志。默认值为 false。
• STRIPE_SECRET_KEY — Stripe 的私有密钥
• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — Stripe 的公钥
• STRIPE_WEBHOOK_SECRET — Stripe 的 Webhook 密钥

以下是几个可选的环境变量，用于启用错误监控和数据分析。

Sentry

• NEXT_PUBLIC_SENTRY_DSN — Sentry 的 DSN
• SENTRY_ENVIRONMENT — Sentry 的环境
• SENTRY_RELEASE — Sentry 的发布版本

PostHog

• NEXT_PUBLIC_POSTHOG_KEY — PostHog 项目的密钥
• NEXT_PUBLIC_POSTHOG_HOST — PostHog 的主机地址

Supabase

设置

本项目使用 Supabase 来管理用户认证以及跟踪 Stripe 订阅信息。我们建议在测试和本地开发时使用本地 Supabase 实例。使用 supabase-cli 是最佳方式。

请参考 Supabase 文档 获取更多信息。项目中包含一个 supabase/ 文件夹，内含设置必要表结构所需的 SQL 迁移脚本。安装好 supabase-cli 后，只需在 tutor-gpt 目录下运行以下命令，即可启动本地 Supabase 实例。

注意：本地 Supabase 依赖 Docker，请确保 Docker 已启动后再执行此命令。

supabase start

另外，在本地使用 Supabase 进行测试时的一个便利之处是，创建账户无需验证，因此你可以在 Web UI 上直接创建新账户并立即登录。

身份验证

此应用程序使用新的 Supabase SSR 功能和 PKCE 身份验证流程。因此，在应用能够与 Supabase 配合使用之前，需要进行一些设置步骤。

主要的更改在于，身份验证的电子邮件模板需要修改，以执行令牌交换。

为了在本地 Supabase 实例中使用，相应的电子邮件模板已在 ./supabase/templates 中设置好。

确认注册

<h2>请确认您的注册</h2>

<p>请点击以下链接以确认您的用户：</p>
<p>
  <a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email"
    >确认您的邮箱</a
  >
</p>

邀请用户

<h2>您已被邀请</h2>

<p>
  您已被邀请在 {{ .SiteURL }} 上创建一个用户。请点击以下链接以接受邀请：
</p>
<p>
  <a
    href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=invite&next=/path-to-your-update-password-page"
    >接受邀请</a
  >
</p>

魔法链接

<h2>魔法链接</h2>

<p>请点击以下链接以登录：</p>
<p>
  <a
    href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=magiclink"
    >登录</a
  >
</p>

更改电子邮件地址

<h2>确认更改电子邮件</h2>

<p>
  请点击以下链接以确认将您的电子邮件从 {{ .Email }} 更改为 {{ .NewEmail }}：
</p>
<p>
  <a
    href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email_change"
  >
    更改电子邮件
  </a>
</p>

重置密码

<h2>重置密码</h2>

<p>请点击以下链接以重置您的用户密码：</p>
<p>
  <a
    href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=recovery&next=/auth/reset"
    >重置密码</a
  >
</p>

Docker

为了方便自托管和本地开发，项目中包含了一个 Dockerfile。要构建并运行镜像，请执行以下命令：

cd tutor-gpt
docker build -t tutor-gpt .
docker run --env-file .env.local -p 3000:3000 tutor-gpt

参与贡献

本项目完全开源，欢迎任何形式的开源贡献。参与贡献的工作流程是先对仓库进行 fork。您可以在 Issues 标签页中认领一个问题，或者开启一个新的讨论主题，说明您正在处理的功能或 bug 修复。

完成贡献后，请向 staging 分支提交 PR，它将由项目经理进行评审。欢迎您加入我们的 Discord 社区，讨论您的更改或寻求帮助。

一旦您的更改被接受并合并到 staging 分支，它们将进入一段线上测试期，随后才会被合并到上游的 main 分支。

许可证

Tutor-GPT 采用 GPL-3.0 许可证授权。更多信息请参阅 许可证文件。

Tutor-GPT 快速上手指南

Tutor-GPT 是一个由 Plastic Labs 开发的基于大语言模型（LLM）的学习伴侣。它具备“心智理论”能力，能动态推理用户的学习需求并自动更新提示词，提供个性化的学习体验。本项目基于 Next.js 构建，依赖 Honcho（用户画像）、Supabase（认证与数据库）和 OpenRouter（LLM 接入）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Node.js: 建议安装最新 LTS 版本
• 包管理器: pnpm (项目指定使用 pnpm)
  • 安装命令：npm install -g pnpm
• Docker: 用于运行本地 Supabase 实例（必须开启 Docker 守护进程）
• Supabase CLI: 用于管理本地数据库
  • 安装命令：npm install -g supabase
• 账号与服务:
  • LLM 提供商: 如 OpenRouter, Mistral 等，需获取 API Key。
  • Honcho: 用于身份建模（需注册获取 URL 和应用名称）。
  • Stripe (可选): 如需测试支付功能。

国内开发者提示：如果 npm 或 pnpm 安装依赖缓慢，可配置国内镜像源（如腾讯云或阿里云镜像）。

安装步骤

1. 克隆项目与安装依赖

git clone https://github.com/plastic-labs/tutor-gpt.git && cd tutor-gpt
pnpm install

2. 配置环境变量

复制模板文件并编辑 .env.local，填入您的密钥和服务地址：

cp .env.template .env.local

核心配置项说明（请根据实际服务商填写）：

• 基础设置:
  • NEXT_PUBLIC_SITE_URL: 本地开发设为 http://localhost:3000
• LLM 设置:
  • AI_API_KEY: 您的推理提供商 API Key
  • AI_PROVIDER: 提供商名称 (例如 openrouter)
  • AI_BASE_URL: 兼容 OpenAI 的 API 端点
  • MODEL: 使用的模型名称 (例如 mistralai/mistral-large)
• Honcho 设置:
  • HONCHO_URL: Honcho 实例地址
  • HONCHO_APP_NAME: 应用名称
• Supabase 设置 (本地开发通常保持默认，启动后会自动注入部分变量):
  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY
  • JWT_SECRET

3. 启动本地 Supabase

项目依赖 Supabase 进行用户认证和数据存储。本地开发推荐使用 Docker 运行 Supabase 实例。

确保 Docker 正在运行，然后在项目根目录执行：

supabase start

注意: 首次运行会下载相关 Docker 镜像。启动成功后，终端会输出本地的 Supabase URL 和 Keys，请将这些值更新到 .env.local 中对应的变量里。

配置邮件模板（重要）： 本地 Supabase 需要特定的邮件模板以支持 PKCE 认证流。项目已在 ./supabase/templates 目录下提供了预配置好的模板（包含 Confirm Signup, Magic Link 等），supabase start 时通常会自动加载。如需手动确认，请确保模板中的链接格式包含 {{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}...。

4. 启动开发服务器

完成上述配置后，运行以下命令启动应用：

pnpm run dev

基本使用

1. 访问应用: 打开浏览器访问 http://localhost:3000。

2. 注册/登录:

   • 在本地环境中，创建新账户后通常无需验证邮箱即可直接登录（取决于 Supabase 本地配置）。
   • 输入邮箱和密码进行注册，然后使用该凭证登录。

3. 开始对话:

   • 登录后，您将进入对话界面。
   • 输入您的学习目标或具体问题（例如：“我想学习量子力学的基础概念”）。
   • Tutor-GPT 将根据您的输入动态调整策略，提供个性化的辅导内容。

4. Docker 部署 (可选): 如果您希望以容器化方式运行整个应用（而非仅 Supabase），可以使用以下命令构建并运行：

   docker build -t tutor-gpt .
   docker run --env-file .env.local -p 3000:3000 tutor-gpt
   

现在您已经成功运行了 Tutor-GPT，可以开始探索其自适应学习能力了。