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:
@@ -1,65 +1,90 @@
|
||||
# rules.md
|
||||
# LLM in Text 项目知识库
|
||||
|
||||
在构建这个LLM应用网页时，你需要基于VUE3开发。我需要前端只运行渲染和数据回传，后端负责llm api调用，类似copilet的auto inline suggustions实现和数据解析。
|
||||
**生成时间:** 2025-04-10
|
||||
**Commit:** 2fdc996
|
||||
**Branch:** main
|
||||
|
||||
# **重要** : 在回复用户消息时，一定要使用中文
|
||||
## 概述
|
||||
|
||||
## 指导原则
|
||||
智能 Markdown 编辑器，集成 LLM 实时补全建议。前端 Vue3 + Vite + Milkdown，后端 FastAPI + Python + Ollama。核心功能：AI 补全、OCR 图片识别、文档转换、TTS/ASR 语音功能。
|
||||
|
||||
- 不要擅自用npm或者yarn运行网页，你既看不到网页的内容，也无法阻止命令暂停。但是，你可以用npm run build检查代码。
|
||||
- 应该保证代码效率，不多定义变量，不写冗余注释，把降低延迟放在第一位。
|
||||
- 每次完成任务前都要反复阅读检查代码，确保代码准确无误。
|
||||
- 尽量不要搜索关键字，而是了解代码结构后查询整个问题代码明确问题所在。
|
||||
- @/milkdown-docs/ 代表milkdown的最新官方文档，不要修改，涉及到前端编辑器的指令时要核对官方文档。
|
||||
## 结构
|
||||
|
||||
|
||||
# 仓库指南
|
||||
|
||||
## 语言约定
|
||||
项目文档、日志、错误提示以及对外返回的文字信息统一使用 **中文**。前端 UI 默认展示中文，若需多语言支持请在相应模块实现。
|
||||
|
||||
## 项目结构 \& 模块组织
|
||||
```
|
||||
backend/ # FastAPI 后端（Python）
|
||||
├─ main.py # API 入口
|
||||
├─ llm.py # LLM 包装工具
|
||||
├─ prompt.py # Prompt 构建辅助
|
||||
└─ tests/ # pytest 测试套件
|
||||
public/ # 前端静态资源
|
||||
src/ # 前端源码（Vite + React）
|
||||
dist/ # 构建产出（生成文件）
|
||||
llm-in-text/
|
||||
├── backend/ # FastAPI 后端 (Python)
|
||||
│ ├── main.py # API 入口，路由定义
|
||||
│ ├── llm.py # Ollama 调用封装
|
||||
│ ├── prompt.py # Prompt 构建逻辑
|
||||
│ ├── prompts/ # JSON 格式的提示模板
|
||||
│ └── tests/ # pytest 测试套件
|
||||
├── src/ # 前端源码 (Vue3 + Vite)
|
||||
│ ├── main.js # Vue 入口
|
||||
│ ├── App.vue # 根组件
|
||||
│ ├── components/ # Vue 组件
|
||||
│ ├── plugins/ # Milkdown/Copilot 插件
|
||||
│ ├── stores/ # Pinia 状态管理
|
||||
│ ├── views/ # 页面视图
|
||||
│ └── utils/ # 工具函数
|
||||
├── public/ # 静态资源
|
||||
├── milkdown-docs/ # Milkdown 官方文档（只读）
|
||||
└── index.html # HTML 入口
|
||||
```
|
||||
生产代码主要位于 `backend/`（Python）和 `src/`（JS/TS）。测试文件与被测模块并置。
|
||||
|
||||
## 构建、测试、开发命令
|
||||
| 命令 | 说明 |
|
||||
|----------------------------------------------|--------------------------------------------------|
|
||||
| `npm install` | 安装前端依赖 |
|
||||
| `npm run dev` | 启动 Vite 开发服务器 |
|
||||
| `uvicorn backend.main:app --reload` | 本地运行 FastAPI 服务 |
|
||||
| `pytest` | 运行 Python 测试套件 |
|
||||
| `npm run build` | 生成生产环境构建产物至 `dist/` |
|
||||
## 查找指南
|
||||
|
||||
## 编码风格 \& 命名约定
|
||||
- **Python**：使用 4 空格缩进，`snake_case` 命名函数/变量，`PascalCase` 命名类。提交前请使用 `ruff`/`black` 格式化。
|
||||
- **JavaScript/TypeScript**：使用 2 空格缩进，`camelCase` 命名变量/函数，`PascalCase` 命名 React 组件。使用 `eslint` 与 `prettier` 检查。
|
||||
- 文件名采用全小写加短横线，例如 `my-module.py`、`my-component.tsx`。
|
||||
| 任务 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| 后端 API 入口 | `backend/main.py` | FastAPI 路由、CORS、启动逻辑 |
|
||||
| LLM 调用 | `backend/llm.py` | Ollama 异步调用、超时控制 |
|
||||
| Prompt 构建 | `backend/prompt.py` | 系统提示、上下文准备 |
|
||||
| AI 补全核心 | `src/plugins/copilotPlugin.ts` | ProseMirror Mark、ghost text |
|
||||
| 编辑器组件 | `src/components/MilkdownEditor.vue` | Milkdown 编辑器封装 |
|
||||
| 状态管理 | `src/stores/settings.js` | 用户设置、主题、偏好 |
|
||||
| API 调用 | `src/utils/api.js` | fetchSuggestion、TTS 接口 |
|
||||
| 测试运行 | `pytest.ini` + `backend/tests/` | 测试配置与用例 |
|
||||
|
||||
## 测试指南
|
||||
- 后端使用 **pytest**，测试文件放在对应模块目录下，命名为 `test_<module>.py`。
|
||||
- 目标覆盖率 ≥ 80%（`pytest --cov=backend`）。
|
||||
- 在虚拟环境中运行：`pip install -r backend/requirements.txt && pytest`。
|
||||
## 约定（项目特定）
|
||||
|
||||
## 提交 \& Pull Request 规范
|
||||
- 提交信息遵循 **Conventional Commits**：`feat:` 新功能、`fix:` 修复、`docs:` 文档、`refactor:` 重构等。
|
||||
- PR 必须包含：
|
||||
- 与提交信息匹配的标题。
|
||||
- 关联的 Issue（如 `Fixes #123`）。
|
||||
- UI 变更或 API 示例的截图/示例。
|
||||
- 所有 CI 检查（代码检查、测试、类型检查）均通过。
|
||||
- **前端入口**：`src/main.js`（非 TypeScript），使用 Vue3 + Pinia + Vue Router
|
||||
- **后端入口**：`backend/main.py`，端口 8001，uvicorn 启动
|
||||
- **代理配置**：开发时 `/v1` 代理到远程 API，生产需调整
|
||||
- **文件命名**：全小写+短横线（`my-module.py`、`my-component.vue`）
|
||||
- **语言**：UI 默认中文，响应必须使用中文
|
||||
|
||||
## 安全 \& 配置建议
|
||||
- 敏感信息请放入 `.env` 并确保已在 `.gitignore` 中。
|
||||
- 按照 `backend/main.py` 中的实现，对上传文件的大小和类型进行校验，防止滥用。
|
||||
- 定期审计依赖安全（`npm audit`、`pip-audit`）。
|
||||
## 反模式（本项目禁止）
|
||||
|
||||
- ❌ 硬编码 API_KEY（必须从环境变量读取）
|
||||
- ❌ 在前端暴露密钥（应通过后端代理）
|
||||
- ❌ `npm run dev` 运行网页（无法看到内容）
|
||||
- ❌ 修改 `milkdown-docs/` 目录
|
||||
- ❌ 类型错误使用 `as any` / `@ts-ignore`
|
||||
- ❌ 空的 catch 块
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 前端开发
|
||||
npm install
|
||||
npm run dev # 端口 5173
|
||||
npm run build # 构建到 dist/
|
||||
|
||||
# 后端运行
|
||||
pip install -r backend/requirements.txt
|
||||
python backend/main.py # 端口 8001
|
||||
# 或
|
||||
uvicorn backend.main:app --reload --port 8001
|
||||
|
||||
# 测试
|
||||
pytest # 运行所有测试，覆盖率要求 90%
|
||||
python backend/tests/run_tests.py unit # 单元测试
|
||||
python backend/tests/run_tests.py integration # 集成测试
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **架构分离**：前端仅渲染和数据回传，后端负责 LLM API 调用和数据解析
|
||||
- **延迟优先**：代码效率优先，降低延迟放在第一位
|
||||
- **大小限制**：文档超过 32KB 自动禁用 AI 补全
|
||||
- **milkdown-docs/**：官方文档参考，不可修改，编辑器相关问题需核对此目录
|
||||
|
||||
|
||||
Reference in New Issue
Block a user