4Ever 是一个 Python/FastAPI + React 构建的个人 AI 工作空间。它从一个 AI 工作台出发，逐步扩展成集聊天、模型配置、Agent 工作流、长期记忆、Token 用量统计和个人内容管理于一体的系统。
| 模块 | 能力 |
|---|---|
| 交耳 Chat | 多供应商 AI 聊天，支持 Persona、记忆、流式事件、附件、引用和 MCP 工具事件。 |
| 中枢 Provider Hub | 管理模型 profile、base URL、API key、fallback model 和图片理解能力。 |
| 秩序 Workflow | 面向 Agent / MCP 的工作流界面，由 Python 后端运行时承载。 |
| Token 统计 | 本地 CLI 采集、仪表盘、热力图、排行榜和设备 / Key 管理。 |
| 虚实 / 笔记 / 地图纪念 / 灵感 | 围绕创作、记录、记忆和灵感整理的个人工作面。 |
| 管理员端 | 用户、模块、MCP 策略、readiness 检查和审计记录。 |
当前后端已经切到 Python/FastAPI，并保持前端 API 合同稳定。默认使用 SQLite，因此本地运行不需要额外数据库服务。
- FastAPI 后端：覆盖认证、聊天、模型供应商、图像生成、Token 统计、管理员端和 Agent 工作流。
- React + Vite 前端：模块化工作台，包含 Chat、Provider Hub、Workflow、Token Usage、Notes、Memory Map、Inspiration 和 Admin。
- 流式聊天事件协议：支持文本 chunk、错误、工具调用、Token 用量、引用校验和运行事件回放。
- 后端托管模型配置：支持用户隔离、模型 profile 和加密保存模型 API key。
- Persona 与记忆：让 AI 联系人更稳定，并支持轻量长期记忆召回。
- 私有附件存储：owner-scoped 下载、签名临时 URL、文档 chunk 检索和引用详情。
- MCP-ready 运行时：支持 BigModel MCP planned/live 模式和管理员 allowlist。
- Docker Compose 部署：包含 Caddy 前端 / 反代容器和持久化 Docker volume。
- Token CLI：把本机 AI 编程工具的 Token 用量同步到 4Ever 仪表盘。
4Ever 不是单一聊天页，而是一个模块化工作空间：
交耳 | 中枢 | 秩序 | Token统计 | 笔记 | 地图纪念 | 灵感 | 管理员端
后续如果要补产品截图，可以放到 docs/images/ 后在这里引用。
cd python_backend
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
uvicorn app.main:app --host 127.0.0.1 --port 7778cd frontend
npm install
npm run dev打开：
http://127.0.0.1:7777
Vite 开发服务器会把 /api 和 /health 代理到 http://127.0.0.1:7778。
如果你希望用容器方式在本地运行，而不是分别启动前后端开发服务器，可以使用 Docker Compose。
cd deploy
cp .env.example .env把 deploy/.env 改成本地 HTTP 配置：
SITE_ADDRESS=:80
HTTP_PORT=7777
HTTPS_PORT=7443
VITE_API_BASE_URL=
CORS_ORIGINS=http://localhost:7777,http://127.0.0.1:7777
ALLOW_LEGACY_GLOBAL_MODEL_PROFILES=0
MODEL_PROFILE_ENCRYPTION_KEY=local-dev-stable-key
CHAT_ATTACHMENT_URL_SECRET=local-dev-attachment-secret构建并启动：
docker compose build
docker compose up -d打开：
http://127.0.0.1:7777
健康检查：
curl http://127.0.0.1:7777/health
curl http://127.0.0.1:7777/api/database/health停止容器但保留数据：
cd deploy
docker compose down删除容器和本地 Docker volume 数据：
cd deploy
docker compose down -vdeploy/.env 已被 Git 忽略。若你希望已保存的模型 API key 在重启后仍可解密，请保持 MODEL_PROFILE_ENCRYPTION_KEY 稳定不变。
安装 CLI：
npm install -g @anglyaoy/token-usage绑定线上 4Ever 并立即同步一次：
forever-token init本地开发服务：
forever-token init local设置自动同步：
forever-token service setup后端配置可以放在项目根目录 .env 或 python_backend/.env，参考 python_backend/.env.example。
DATABASE_URL=sqlite:///./4ever.db
BIGMODEL_API_KEY=
BIGMODEL_MCP_LIVE=0
AGENT_SYNTHESIS_LIVE=0
AGENT_GRAPH_RUNTIME=langgraph前端配置可以放在 frontend/.env，参考 frontend/.env.example。
.
├── python_backend/ # Python FastAPI 后端
│ ├── app/ # API routes、配置和 Agent runtime
│ ├── tests/ # 后端合同测试
│ ├── .env.example # 后端环境变量示例
│ └── pyproject.toml # Python 依赖和 pytest 配置
├── frontend/ # React + Vite 前端
│ ├── src/ # Panels、services、types 和应用壳
│ ├── .env.example # 前端环境变量示例
│ ├── package.json # 前端脚本和依赖
│ └── vite.config.ts # Vite 开发服务器和代理配置
├── deploy/ # Docker Compose、Caddy 和部署环境变量示例
├── token-usage-cli/ # forever-token CLI 包
├── docs/ # 调研和实现文档
├── deploy.sh # 维护者服务器部署辅助脚本
├── README.md # 中文 README
└── README_EN.md # English README
前端：
cd frontend
npm run build后端：
cd python_backend
python3.11 -m pytest健康检查：
curl http://127.0.0.1:7778/health
curl http://127.0.0.1:7778/api/database/health- 本地数据库、
.env、node_modules/、Vitedist/和生成媒体文件都应保持在 Git 外。 - 不要把密钥提交到仓库。
- Agent、LangGraph 和 BigModel MCP 工作流细节见 docs/agent-mcp-workflow.md。