Well English

一个用于英语学习的 AI 项目仓库，采用 monorepo 结构，包含 Web 端、浏览器扩展和 Go 后端。

当前仓库的核心能力已经围绕「生词采集 + 页面分析 + 词汇复习」搭起来：

• apps/web 提供登录、注册、Dashboard、词库、单词详情和复习页面
• apps/Extension 提供浏览器扩展，可以抓取页面内容、分析英文页面、添加选中单词
• backend 提供认证、词汇、学习分析、扩展接口等 API
• packages/* 提供共享 UI 和工程配置

技术栈

• Monorepo: Turborepo
• Frontend: Next.js 16, React 19, TypeScript
• Extension: Plasmo, React 18
• Backend: Go, Gin, PostgreSQL, Redis
• Package manager: Bun

仓库结构

.
├── apps/
│   ├── web/          # 主 Web 应用
│   ├── docs/         # 文档/演示站，当前仍是模板页
│   └── Extension/    # 浏览器扩展
├── backend/          # Go 后端服务
├── packages/
│   ├── ui/           # 共享 UI 组件
│   ├── eslint-config/
│   └── typescript-config/
├── docker-compose.yml
└── turbo.json

架构图

flowchart LR
    User[User]
    Web[apps/web<br/>Next.js Web App]
    Ext[apps/Extension<br/>Plasmo Browser Extension]
    API[backend<br/>Go + Gin API]
    PG[(PostgreSQL)]
    Redis[(Redis)]
    AI[AI Provider<br/>OpenAI / DeepSeek / Gemini / Ollama]
    Docs[apps/docs<br/>Docs Site]
    UI[packages/ui<br/>Shared UI]

    User --> Web
    User --> Ext
    User --> Docs

    Web --> API
    Ext --> API
    Ext -. custom provider fallback .-> AI
    API --> PG
    API --> Redis
    API --> AI

    Web --> UI
    Docs --> UI

Loading

这个项目目前的运行形态是：

• apps/web 和 apps/Extension 都是业务入口
• backend 是统一 API 层，负责认证、词汇、学习分析和扩展接口
• PostgreSQL 存业务数据，Redis 做缓存
• AI 能力默认由后端调用，也支持扩展直接走自定义 AI provider

核心流程

1. 页面分析与生词提取

sequenceDiagram
    participant U as User
    participant E as Extension
    participant B as Backend API
    participant A as AI Provider
    participant D as PostgreSQL/Redis

    U->>E: 在网页中点击分析
    E->>E: 提取页面标题与正文
    E->>B: POST /api/extension/analyze_page
    B->>A: 请求总结、难度、新词
    A-->>B: 返回分析结果
    B-->>E: 返回 summary / difficulty / new_words
    E-->>U: 展示双语分析结果

    U->>E: 选中单词并加入词库
    E->>B: POST /api/extension/add_word
    B->>A: 补全释义/音标/例句
    B->>D: 保存词汇与学习记录
    B-->>E: 返回添加结果

Loading

2. Web 学习闭环

sequenceDiagram
    participant U as User
    participant W as Web App
    participant B as Backend API
    participant D as PostgreSQL/Redis

    U->>W: 登录 / 注册
    W->>B: /api/login 或 /api/register
    B-->>W: JWT token

    U->>W: 打开 Dashboard
    W->>B: GET /api/dashboard
    B->>D: 查询学习数据
    B-->>W: 总词数、复习数、进度数据

    U->>W: 打开词库 / 复习页
    W->>B: GET /api/vocabulary/list / review
    B->>D: 查询词汇与复习计划
    B-->>W: 返回单词列表或复习卡片

Loading

当前功能

Web

apps/web 已接入后端 API，包含这些页面：

• /login 登录
• /register 注册
• /dashboard 学习概览
• /vocabulary 词库列表和手动加词
• /vocabulary/[id] 单词详情
• /vocabulary/review 复习卡片

Web 端默认请求 http://localhost:8080/api。

Extension

apps/Extension 是基于 Plasmo 的浏览器扩展，当前能力包括：

• 登录 / 注册
• 右键选中文本加入词库
• 提取当前网页正文并做英文内容分析
• 优先调用后端分析接口，失败时可回退到自定义 AI 提供方
• 支持自定义 AI endpoint / model / apiKey

默认后端地址同样是 http://localhost:8080/api，也可以在扩展设置中覆盖。

Backend

backend 已实现的主要接口分组：

• 认证：/api/login, /api/register, /api/user/profile
• 词汇：/api/vocabulary/add, /api/vocabulary/list, /api/vocabulary/:id, /api/vocabulary/review
• 学习：/api/page/analyze, /api/dashboard
• 扩展：/api/extension/analyze_page, /api/extension/add_word, /api/extension/chat

后端依赖：

• PostgreSQL 16
• Redis 7
• AI provider 配置

快速启动

1. 安装前端依赖

在仓库根目录执行：

bun install

2. 启动数据库和 Redis

docker compose up -d

这会启动：

• PostgreSQL: localhost:5432
• Redis: localhost:6379

3. 初始化后端数据库

先安装迁移工具：

go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

然后执行迁移：

cd backend
migrate -path ./migrations -database "postgres://postgres:password@localhost:5432/well_english?sslmode=disable" up

4. 启动后端

cd backend
go run ./cmd/server

默认监听：

http://localhost:8080

5. 启动 Web

cd apps/web
bun run dev

打开：

http://localhost:3000

6. 启动扩展开发

cd apps/Extension
bun run dev

然后把生成的开发构建加载到浏览器中。

常用命令

根目录：

bun run build
bun run dev
bun run lint
bun run check-types

更推荐按模块单独启动，尤其是开发阶段，因为根目录 bun run dev 会通过 Turbo 同时拉起所有 workspace。

配置说明

后端默认配置文件在 backend/configs/config.yaml。

关键默认值：

• 服务端口：:8080
• PostgreSQL DSN：postgres://postgres:password@localhost:5432/well_english?sslmode=disable
• Redis：localhost:6379
• AI endpoint：https://api.openai.com/v1
• AI model：gpt-4

生产环境至少需要修改：

• jwt.secret
• database.dsn
• ai.api_key

开发状态

这个仓库目前不是纯模板，但也还没完全收口，现状大致如下：

• apps/web 已经是业务页面，不再是默认 Next.js 首页
• apps/Extension 已经接入真实业务逻辑
• backend 已有完整的基础分层和 API
• apps/docs 仍然基本是 Turborepo/Next 模板页
• packages/ui 仍比较轻，只包含少量共享组件

建议的开发顺序

如果你要继续推进这个项目，比较合理的顺序是：

1. 先保证 backend + web 本地联调稳定
2. 再验证 Extension 的登录、加词、页面分析链路
3. 最后补 docs、部署配置、环境变量和测试