81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 架构设计
|
||
|
||
## 总体架构
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 客户端 (任意组合) │
|
||
│ ├─ 安卓 App (Capacitor) │
|
||
│ ├─ 苹果 App (Capacitor) │
|
||
│ ├─ 手机浏览器 (PWA) │
|
||
│ └─ 桌面浏览器 │
|
||
└─────────────┬───────────────┘
|
||
│ HTTPS / REST + WebSocket
|
||
┌─────────────▼───────────────┐
|
||
│ 后端 FastAPI (Python) │
|
||
│ ├─ /api/auth 认证 JWT │
|
||
│ ├─ /api/chat 对话 │
|
||
│ ├─ /api/agents 智能体 │
|
||
│ ├─ /api/projects 项目 │
|
||
│ ├─ /api/files 文件 │
|
||
│ ├─ /api/tasks 后台任务 │
|
||
│ └─ /api/chat/ws 流式对话 │
|
||
└─────────────┬───────────────┘
|
||
│
|
||
┌─────────────▼───────────────┐
|
||
│ LLM 适配层 (OpenAI 兼容) │
|
||
│ 火山方舟 / DeepSeek / Qwen │
|
||
│ / AutoDL / 本地 vLLM │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
## 分层设计（解耦原则）
|
||
|
||
1. **路由层 (api/)**：只做参数校验、鉴权、HTTP/WS 协议转换，不写业务逻辑
|
||
2. **服务层 (services/)**：业务逻辑（对话编排、agent 调度、项目执行），不感知 HTTP
|
||
3. **模型层 (models/)**：SQLAlchemy ORM，纯数据
|
||
4. **核心层 (core/)**：配置、安全工具、LLM 客户端适配器（provider 可插拔）
|
||
|
||
依赖方向：路由 → 服务 → 模型/核心。禁止反向依赖。
|
||
|
||
## 关键技术决策
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| API 风格 | REST + WebSocket | 流式对话用 WS，普通操作 REST，前端可缓存 |
|
||
| 认证 | JWT Bearer (30天有效期) | 移动端免频繁登录 |
|
||
| 数据库 | SQLite → PostgreSQL | 单机起步零运维，环境变量切换 |
|
||
| 前端 | Vue3 + Vant + PWA | 移动优先、浏览器直达、可安装 |
|
||
| App 化 | Capacitor | 一套 Web 代码打包安卓/iOS，成本最低 |
|
||
| LLM | OpenAI 兼容适配器 | 多 provider 可配，按模型名路由 |
|
||
| 后台任务 | asyncio 任务表 | 视频分析等耗时操作异步化，状态可查 |
|
||
|
||
## 数据模型
|
||
|
||
```
|
||
users ─┬─ chat_sessions ── chat_messages
|
||
├─ agents (内置/自定义, is_builtin)
|
||
├─ projects ── project_tasks
|
||
├─ file_entries (可选关联 project)
|
||
└─ tasks (后台任务)
|
||
```
|
||
|
||
## 项目类型（Project.type）
|
||
|
||
| type | 用途 | 工作目录 | 执行方式 |
|
||
|------|------|----------|----------|
|
||
| programming | 编程开发 | data/workspace/project_<id>/ | 代码生成 + 命令执行 |
|
||
| research | 研究 | 同上 | 检索 + 报告生成 |
|
||
| office | 办公 | 同上 | 文档/表格/PPT 生成 |
|
||
| writing | 小说/短剧 | 同上 | 分章节/分集生成 |
|
||
| video | 视频分析 | 同上 | ffmpeg 抽帧 + 视觉模型 |
|
||
|
||
## API 规范
|
||
|
||
- 前缀：`/api`
|
||
- 响应格式：`{"code": 0, "data": ..., "message": "ok"}`（code=0 成功）
|
||
- 错误：HTTP 状态码 + `{"code": <业务码>, "message": "..."}`
|
||
- 分页：`?page=1&page_size=20` → `{"total": n, "items": [...]}`
|
||
- 鉴权：`Authorization: Bearer <token>`
|
||
- 流式：WebSocket `/api/chat/ws`，消息类型 `chat/delta/done/error`
|