companion-assistant/docs/ARCHITECTURE.md

架构设计

总体架构

┌─────────────────────────────┐
│  客户端 (任意组合)            │
│  ├─ 安卓 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_/	代码生成 + 命令执行
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