# Essence

**Repository Path**: dirtywave/essence

## Basic Information

- **Project Name**: Essence
- **Description**: AI 知识工作台：以文档为核心的 RAG 问答、引用溯源、多模型配置，以及飞书机器人对话式控制。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Essence（撷英）

AI 知识工作台：以文档为核心的 RAG 问答、引用溯源、多模型配置，以及飞书机器人对话式控制。

| 属性 | 值 |
|------|-----|
| 英文名 | Essence |
| 中文名 | 撷英 |
| 许可证 | [Apache-2.0](./LICENSE) |
| 桌面端 | Next.js (`apps/web`) |
| 移动端 | uni-app x (`apps/mobile`) |
| 后端 | FastAPI (`services/api`) |

## 核心能力

- **资料工作台**：上传 PDF / Word / 图片，解析、分块、向量检索 + 全文混合搜索
- **RAG 对话**：流式问答、引用溯源、多轮上下文
- **成果生成**：摘要、学习指南、闪卡、能力图谱、PPT、Word 教案、微课视频、音频播客
- **飞书集成**：WebSocket 长连接（个人/本地免公网）、OAuth 绑定、自然语言提问与口语化触发生成
- **系统配置**：Web 端 `/settings/env` 可视化编辑 `.env`（密钥、飞书、CORS 等）

## 文档

| 文档 | 说明 |
|------|------|
| [Docker 部署（推荐下载用户）](./docs/DOCKER.md) | 一键容器启动、镜像导出 |
| [安装与启动指南](./docs/INSTALL.md) | Docker 与源码两种方式详解 |
| [飞书集成](./docs/FEISHU_INTEGRATION.md) | 机器人、OAuth、长连接配置 |
| [Ubuntu 生产部署](./docs/UBUNTU_DEPLOYMENT.md) | 服务器、Nginx、HTTPS |
| [完整开发方案](./docs/DEVELOPMENT_GUIDE.md) | 架构与模块说明 |
| [第三方许可说明](./NOTICE) | 依赖与 AGPL 提示 |

## 免责声明

- **独立项目**：Essence（撷英）是独立开源项目，与 Google NotebookLM、ChatPDF 等商业产品**无隶属、无授权、无官方合作关系**。功能上的相似属于同类产品范畴，不代表品牌或产品关联。
- **按现状提供**：本软件按「原样」（AS IS）提供，不提供任何明示或默示担保。使用本软件所产生的数据丢失、服务中断、模型输出错误或合规风险，由部署方与用户自行承担。
- **第三方服务**：大语言模型 API（OpenAI、DeepSeek、通义、Ollama 等）、CosyVoice TTS、Pollinations 配图、飞书开放平台、云存储与向量数据库等均由部署方自行配置，须遵守各服务商的使用条款、计费与数据政策。
- **用户内容与合规**：上传的文档、生成的教案/PPT/音频/视频等内容，其版权与合规责任由上传者与使用方负责。面向教育或企业场景时，请自行完成隐私、未成年人保护与数据出境等合规评估。
- **PyMuPDF（AGPL）**：后端使用 PyMuPDF 解析 PDF。若你将本软件作为网络服务或二进制形式分发，可能需要遵守 AGPL-3.0 相关义务，详见 [NOTICE](./NOTICE)。

## 仓库结构

```
essence/
├── apps/web/              # Next.js 桌面 Web
├── apps/mobile/           # uni-app x 移动一体化
├── services/api/          # FastAPI 后端
├── packages/              # OpenAPI、Design Tokens
├── deploy/                # Docker Compose（dev / all / prod）
├── scripts/               # dev-start、docker-up 等脚本
└── docs/
```

## 快速开始

> 完整说明见 **[Docker 部署](./docs/DOCKER.md)** 与 **[安装指南](./docs/INSTALL.md)**。

### 方式 A：Docker 全栈（推荐下载用户）

无需安装 Python / Node，容器内已包含 API、Web 及运行依赖（含 fastembed、ffmpeg、飞书 SDK）。

```bash
git clone https://gitee.com/dirtywave/essence.git
cd essence
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY   # 若有失效代理

cp .env.docker.example .env
make docker-up          # 首次自动构建镜像并启动
```

| 服务 | 地址 |
|------|------|
| Web | http://localhost:3000 |
| API | http://localhost:8000/health |

首次打开 Web → **注册** → 创建笔记本 → 上传资料 → 在「体悟」中对话或生成。

**离线镜像包**：维护者执行 `make docker-export` 生成 `dist/essence-docker-latest.tar.gz`；使用者 `docker load` 后按 [DOCKER.md](./docs/DOCKER.md) 启动。

### 方式 B：源码安装（推荐开发）

Docker 仅跑基础设施，API / Web 在本机运行，支持热更新与飞书长连接调试。

```bash
cp .env.example .env
make dev-start          # 基础设施 + 迁移 + API :8000 + Web :3000
```

Conda 环境名默认 `essence`，详见 [INSTALL.md](./docs/INSTALL.md)。

### 飞书机器人（可选）

1. Web → **设置 → 飞书集成** → 授权绑定
2. 飞书开放平台配置长连接事件 `im.message.receive_v1`
3. 私聊机器人：直接提问，或说「帮我做一份 PPT」

详见 [飞书集成文档](./docs/FEISHU_INTEGRATION.md)。

### CosyVoice TTS（可选）

音频播客、微课配音需在宿主机或独立容器运行 CosyVoice：

```bash
make tts-setup && make tts-start
curl http://localhost:8000/api/v1/tts/status
```

## 当前进度

- [x] Monorepo + Docker Compose + 数据库迁移
- [x] 认证 JWT、笔记本 CRUD、笔记
- [x] 文档上传 / 解析 / 分块 / Embedding / Qdrant
- [x] RAG 对话 SSE 流式 + 引用
- [x] 模型 Provider 配置（通义 / DeepSeek / OpenAI / Ollama）
- [x] 生成：摘要、指南、闪卡、图谱、PPT、教案、微课、播客
- [x] Web 三栏工作台、WebSocket 事件推送
- [x] **飞书集成**：OAuth、WebSocket、文件上传、自然语言对话与生成
- [x] **Web 系统配置** `/settings/env`
- [x] **Docker 全栈镜像** `make docker-up` / `make docker-export`
- [ ] 笔记本分享链接（后续）

## 常用命令

```bash
# Docker 全栈
make docker-up          # 构建并启动
make docker-down        # 停止
make docker-export      # 导出镜像 tar.gz

# 源码开发
make dev-start          # 一键启动
make dev-stop
make migrate            # 数据库迁移
make test               # 后端测试

# TTS（可选）
make tts-start
```

## 远程仓库

https://gitee.com/dirtywave/essence

## 许可证

Copyright 2024-2026 Essence Contributors

Licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).