Sign inSign up

sumengnan/ai-learning-helper

By sumengnan

•Updated 7 days ago

面向学习场景的 AI 助手：AI 聊天、知识库、题库/错题集、学习概览一体

Image
0

5.7K

sumengnan/ai-learning-helper repository overview

⁠AI 学习助手 · AI Learning Helper

面向学习场景的 AI 助手：以自研的最小 Agent 运行时内核（harness）为后端，配合 React 前端，一站式提供 AI 聊天、知识库、题库、错题集、学习概览。支持联网检索、代码沙箱执行、无头浏览器抓取与 MCP 工具接入。

前后端打包进同一个镜像，容器内 FastAPI 同源托管前端静态产物，开箱即用，只暴露一个端口。

⁠✨ 功能特性

  • AI 聊天 — 多轮对话、断点续传（刷新/重连接回在途生成）、附件上传、耗时/tokens 统计、回复标注参考来源、生成文件聊天内内联预览与下载。
  • 知识库 — 文档入库、语义检索（sqlite-vec 向量）、片段抽屉预览；AI 回答基于知识库做 grounding；聊天中可直接把资料存入知识库。
  • 题库 / 错题集 — 基于知识库出题、作答判分、错题归集回顾。
  • 首页概览 — 学习主场 + 系统监控双视角，时间范围筛选、图表、记忆查看、产物预览、模型分层计费与成本估算。
  • 工具能力 — 联网 http_request（被防抓时自动改用浏览器抓取）、代码沙箱（按语言起一次性子沙箱执行）、无头浏览器抓取、MCP 客户端（stdio + streamable-http）。
  • 回答校验门（可选）— 交付前对格式 / 知识库 grounding / 代码可运行 / LLM 自评打分做校验，不过则带反馈自动重答。

⁠🚀 快速开始

⁠方式一：docker run（最小可用）
docker run -d --name ai-learning-helper \
  -p 8000:8000 \
  -v "$PWD/data:/app/data" \
  -e HARNESS_API_KEY=sk-your-key \
  -e HARNESS_BASE_URL=https://api.openai.com/v1 \
  -e HARNESS_MODEL=gpt-4o-mini \
  -e AUTH_SECRET=$(openssl rand -hex 32) \
  sumengnan/ai-learning-helper:latest

打开 http://localhost:8000⁠，注册/登录后即可使用。

⁠方式二：docker compose（推荐，数据持久化）

.env：

HARNESS_API_KEY=sk-your-key
HARNESS_BASE_URL=https://api.openai.com/v1
HARNESS_MODEL=gpt-4o-mini
AUTH_SECRET=change-me-to-a-long-random-secret
HARNESS_REQUIRE_CAPTCHA=true

docker-compose.yml：

services:
  app:
    image: sumengnan/ai-learning-helper:latest
    container_name: ai-learning-helper
    restart: unless-stopped
    env_file: [.env]
    environment:
      HARNESS_APP_HOST: "0.0.0.0"
      HARNESS_APP_PORT: "8000"
      # 全部持久化数据落到挂载卷 /app/data，重建容器不丢
      HARNESS_APP_DB_PATH: /app/data/app.db
      HARNESS_PERSISTENCE_DB_PATH: /app/data/harness.db
      HARNESS_MEMORY_DB_PATH: /app/data/memory.db
      HARNESS_DOWNLOADS_DIR: /app/data/downloads
      HARNESS_ATTACHMENTS_DIR: /app/data/attachments
    ports:
      - "8000:8000"          # 需要 80 端口改成 "80:8000"
    volumes:
      - ./data:/app/data

docker compose up -d

⁠⚙️ 环境变量

⁠必填
变量说明
HARNESS_API_KEY大模型 API Key
HARNESS_BASE_URLOpenAI 兼容的 API Base URL
HARNESS_MODEL模型名，如 gpt-4o-mini
AUTH_SECRET登录签名密钥，生产必须设为随机长字符串（勿用默认值）
⁠常用可选
变量默认说明
HARNESS_APP_PORT8000容器内监听端口
HARNESS_MAX_STEPS10单轮 Agent 最大步数
HARNESS_TEMPERATURE0.7采样温度
HARNESS_REQUIRE_CAPTCHA—登录/注册是否强制图形验证码（生产建议 true）
HARNESS_APP_DB_PATH / HARNESS_PERSISTENCE_DB_PATH / HARNESS_MEMORY_DB_PATH—三个 SQLite 库路径，建议都指向挂载卷 /app/data
HARNESS_DOWNLOADS_DIR / HARNESS_ATTACHMENTS_DIR—下载/附件产物目录，同样建议放 /app/data

进阶能力（代码沙箱 HARNESS_ENABLE_SANDBOX、无头浏览器 HARNESS_ENABLE_BROWSER、MCP HARNESS_ENABLE_MCP、回答校验门 HARNESS_ENABLE_ANSWER_GATE）默认关闭。完整清单见源码仓库的 .env.example⁠。

⁠💾 数据与端口

  • 端口：容器暴露 8000（前后端同源）。
  • 数据卷：挂载 /app/data 持久化全部 SQLite 库与下载/附件产物，重建容器不丢数据。
⁠启用代码沙箱 / 无头浏览器（可选）

应用会调用宿主 Docker 起一次性子沙箱来执行代码或抓网页。启用时需额外挂载 Docker socket，并打开对应开关：

    environment:
      HARNESS_ENABLE_SANDBOX: "true"
      HARNESS_ENABLE_BROWSER: "true"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock

⚠️ 挂载 docker.sock 等同于把宿主 Docker 控制权交给容器，请仅在受信任环境启用。

⁠🏷️ 镜像标签

  • latest — 最新构建。
  • X.Y.Z — 语义版本号：X.Y 由仓库 VERSION 文件声明，Z（patch）由 CI 在每次 main 推送时自增。

镜像由 GitHub Actions 自动构建并推送（多阶段构建：Node 20 编译前端 → Python 3.12-slim 运行时）。

⁠🔗 相关链接

Tag summary

Content type

Image

Digest

sha256:99c0fddec…

Size

115.1 MB

Last updated

7 days ago

docker pull sumengnan/ai-learning-helper