refactor: improve codebase structure and Univer integration

- Add AGENTS.md knowledge base with project documentation
- Move UserPreferences model to separate models.py file
- Extract API_KEY to environment variable for security
- Enhance Univer Editor with PPTX support and improved UI
- Improve file system handling with binary file detection
- Add HF_ENDPOINT mirror for better China connectivity
- Clean up unused imports and code structure
This commit is contained in:
2026-04-11 09:24:14 +08:00
parent 2fdc996af9
commit d8b7832b14
18 changed files with 901 additions and 544 deletions
+40
View File
@@ -0,0 +1,40 @@
# Backend 模块指南
## OVERVIEW
FastAPI 后端,处理 AI 补全、OCR、文档转换、TTS/ASR。
## STRUCTURE
- main.py - API 入口、路由、CORS、启动逻辑
- llm.py - Ollama 异步调用、超时控制、日志
- prompt.py - Prompt 构建、上下文准备、语言处理
- geoip.py - IP 地理位置查询
- tts_asr.py - TTS/ASR 处理、Apple Silicon 优化
- prompts/ - JSON 格式提示模板(PromptManager 单例)
- tests/ - pytest 测试套件(见子目录 AGENTS.md)
## WHERE TO LOOK
| 任务 | 文件 | 说明 |
|------|------|------|
| API 路由定义 | main.py | /v1/completions、/v1/ocr、/v1/convert 等 |
| LLM 调用封装 | llm.py | call_ollama、call_vlm_ocr、超时控制 |
| Prompt 构建 | prompt.py | build_completion_prompts、语言处理 |
| 提示模板 | prompts/__init__.py | PromptManager、JSON 模板加载 |
| TTS/ASR | tts_asr.py | 模型预热、设备检测、音频处理 |
| 测试 | tests/ | pytest 测试套件 |
## CONVENTIONS
- Python 4 空格缩进
- 函数/变量:snake_case
- 类:PascalCase
- 文件名:全小写+短横线
## ANTI-PATTERNS
- 硬编码 API_KEY(必须从环境变量读取)
- 空 catch 块
- 类型错误使用 as any / @ts-ignore
## 注意事项
- 端口:8001
- 启动:`python backend/main.py``uvicorn backend.main:app --reload`
- 依赖:`pip install -r backend/requirements.txt`