v0.1.0 随身助手初版：FastAPI后端(认证/对话/智能体/项目/文件/视频分析) + Vue3 Vant PWA前端(流式对话/智能体市场/项目任务/视频分析)

2026-08-14 18:11:16 +08:00
commit ee9f5ffe13
57 changed files with 10658 additions and 0 deletions
@@ -0,0 +1,80 @@
+# 架构设计
+
+## 总体架构
+
+```
+┌─────────────────────────────┐
+│  客户端 (任意组合)            │
+│  ├─ 安卓 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`