Companion Bot Widget

多人格 AI 陪伴聊天机器人 SaaS，支持多租户、记忆系统、RAG 知识库、流式对话。

---

目录结构

widget/
├── backend/          # FastAPI + LangGraph 后端 (端口 9876)
├── frontend/         # React + Redux + TypeScript 前端 (端口 9527)
└── docs/             # 架构文档、数据字典、接口文档

---

依赖服务

启动前确保以下外部服务已运行：

服务	地址	说明
PostgreSQL	localhost:5432	主数据库，database=demo，schema=bot
记忆系统	localhost:8000	无鉴权，存储对话记忆
RAG 系统	localhost:8001	Bearer Token 鉴权，知识库检索

---

后端启动

cd backend

# 首次：创建虚拟环境并安装依赖
uv venv .venv --python 3.13
source .venv/bin/activate
uv sync

# 配置环境变量（.env 已包含默认值，修改 OPENAI_API_KEY）
cp .env .env.local   # 可选：本地覆盖

# 数据库迁移（首次或 schema 变更后）
uv run alembic upgrade head

# 启动开发服务器
uv run uvicorn app.main:app --reload --port 9876

服务就绪后访问：

• API 文档：http://localhost:9876/docs
• 健康检查：http://localhost:9876/health

环境变量 (.env)

变量	默认值	说明
DB_HOST	localhost	PostgreSQL 主机
DB_PORT	5432	PostgreSQL 端口
DB_DATABASE	demo	数据库名
DB_USER	fengy	数据库用户
DB_PASSWORD	123456	数据库密码
DB_SCHEMA	bot	Schema 名称
SECRET_KEY	(随机)	JWT 签名密钥，生产环境必须替换
OPENAI_API_KEY	(必填)	OpenAI API Key
RAG_API_BASE	http://localhost:8001	RAG 服务地址
MEMORY_API_BASE	http://localhost:8000	记忆服务地址

---

前端启动

cd frontend

# 首次：安装依赖
npm install

# 开发模式（含热重载，自动代理 /api → localhost:9876）
npm run dev

# 生产构建
npm run build

访问：http://localhost:9527

---

运行测试

cd backend
source .venv/bin/activate

# 运行全部测试（需要 PostgreSQL 已启动）
uv run pytest

# 只运行单元测试
uv run pytest tests/unit/

# 只运行集成测试
uv run pytest tests/integration/

# 带覆盖率
uv run pytest --cov=app --cov-report=term-missing

集成测试使用真实 PostgreSQL，每次测试前自动清空 bot schema 数据。

---

数据库迁移

cd backend

# 生成新迁移（修改 models 后）
uv run alembic revision --autogenerate -m "describe_change"

# 升级到最新
uv run alembic upgrade head

# 回滚一步
uv run alembic downgrade -1

# 查看当前版本
uv run alembic current

---

机器人人格类型

类型	名称	适用场景
youth	青春伙伴	年轻人日常陪伴
worker	职场搭档	职场压力疏导
tech	技术极客	技术讨论
mentor	人生导师	人生指导建议
caregiver	暖心关怀	情感支持陪伴
coach	健康教练	健身健康指导
custom	自定义	自由定制人格

---

快速体验

1. 注册账号：POST /api/v1/auth/register
2. 创建机器人：POST /api/v1/robots（系统自动在 RAG 中创建知识库）
3. 开始聊天：POST /api/v1/chat/stream（SSE 流式响应）

详细接口说明见 docs/api.md。