ydy0615
2abf276d10
This commit refactors the LLM integration to use Ollama's native Python client instead of OpenAI-compatible API, while fixing critical template syntax errors and improving project structure. Key changes: - Replace openai package with ollama package in backend requirements - Rewrite llm.py to use ollama.AsyncClient for direct Ollama API calls - Update main.py to use non-streaming Ollama responses with thinking extraction - Fix template syntax error in MilkdownEditor.vue (GhostTextOverlay component tags) - Fix string截取错误 by using slice() instead of substring() - Add src/utils/api.js and src/utils/config.js for shared configuration - Add CORS middleware to FastAPI backend - Update prompt.py with clearer instructions for continuation generation - Add comprehensive README.md documentation BREAKING CHANGE: Environment variables OLLAMA_BASE_URL changed to OLLAMA_HOST (remove /v1/ suffix)
211 lines
5.5 KiB
Markdown
211 lines
5.5 KiB
Markdown
# LLM in Text - 智能写作助手
|
||
|
||
基于 Vue3 和 FastAPI 的智能写作助手，实现类似 GitHub Copilot 的 inline suggestions（行内建议）功能。
|
||
|
||
## 项目概述
|
||
|
||
本项目是一个全屏 Markdown 编辑器，集成了大语言模型（LLM）的智能补全功能。当用户输入时，系统会根据上下文实时提供文本补全建议，用户可以通过 Tab 键接受建议或点击建议文本直接插入。
|
||
|
||
## 技术栈
|
||
|
||
### 前端
|
||
- **Vue 3** - 渐进式 JavaScript 框架
|
||
- **Vite** - 下一代前端构建工具
|
||
- **Milkdown** - 基于 ProseMirror 的 WYSIWYG Markdown 编辑器
|
||
- **Pinia** - Vue 状态管理
|
||
- **Axios** - HTTP 客户端
|
||
|
||
### 后端
|
||
- **FastAPI** - 现代化的 Python Web 框架
|
||
- **OpenAI API** - 大语言模型接口
|
||
- **Ollama** - 本地 LLM 服务支持
|
||
|
||
## 核心功能
|
||
|
||
### 1. 全屏 Markdown 编辑器
|
||
- 基于 Milkdown Crepe 的所见即所得编辑体验
|
||
- 支持完整的 Markdown 语法
|
||
- 代码块高亮、图片粘贴等功能
|
||
- 导出 Markdown 文件
|
||
|
||
### 2. 智能行内建议
|
||
- 实时监听用户输入
|
||
- 基于上下文（光标前后文本）生成补全建议
|
||
- 流式响应，实时显示建议内容
|
||
- 支持多种交互方式：
|
||
- **Tab 键**：接受建议
|
||
- **Esc 键**：取消建议
|
||
- **点击建议**：直接插入
|
||
|
||
### 3. 性能优化
|
||
- 150ms 防抖机制，避免频繁请求
|
||
- 流式传输（SSE），降低延迟
|
||
- 上下文智能截取（光标前30行 + 后5行）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
llm-in-text/
|
||
├── src/
|
||
│ ├── components/
|
||
│ │ ├── MilkdownEditor.vue # 主编辑器组件
|
||
│ │ ├── GhostTextOverlay.vue # 建议文本显示组件
|
||
│ │ └── MarkdownEditor.vue # 备用编辑器
|
||
│ ├── plugins/
|
||
│ │ ├── inlineSuggestionPlugin.ts # 行内建议插件
|
||
│ │ └── types.ts # 类型定义
|
||
│ ├── router/
|
||
│ │ └── index.js # 路由配置
|
||
│ ├── store/
|
||
│ │ └── index.js # 状态管理
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.js # 入口文件
|
||
├── backend/
|
||
│ ├── main.py # FastAPI 服务器
|
||
│ ├── llm.py # LLM API 调用
|
||
│ ├── prompt.py # Prompt 构建
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ └── .env # 环境变量配置
|
||
├── plans/
|
||
│ ├── milkdown-editor-plan.md # 编辑器实施计划
|
||
│ └── inline-suggestions-plan.md # 建议功能实施计划
|
||
├── index.html
|
||
├── package.json
|
||
├── vite.config.js
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
- Node.js 18+
|
||
- Python 3.8+
|
||
- OpenAI API Key 或 Ollama 服务
|
||
|
||
### 安装依赖
|
||
|
||
**前端：**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
**后端：**
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 配置环境变量
|
||
|
||
在 `backend/.env` 文件中配置：
|
||
|
||
```env
|
||
OPENAI_API_KEY=your_api_key_here
|
||
OLLAMA_BASE_URL=http://localhost:11434/v1/
|
||
OLLAMA_MODEL=gpt-4
|
||
```
|
||
|
||
### 启动服务
|
||
|
||
**启动后端：**
|
||
```bash
|
||
cd backend
|
||
python main.py
|
||
```
|
||
|
||
**启动前端：**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
访问 `http://localhost:5173` 开始使用。
|
||
|
||
## API 接口
|
||
|
||
### POST /v1/completions
|
||
|
||
获取文本补全建议（流式响应）
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"prefix": "# Hello\n\nThis is ",
|
||
"suffix": "",
|
||
"languageId": "markdown"
|
||
}
|
||
```
|
||
|
||
**响应（SSE 流）：**
|
||
```
|
||
data: {"content": "a "}
|
||
|
||
data: {"content": "a te"}
|
||
|
||
data: {"content": "a test"}
|
||
|
||
data: {"done": true}
|
||
```
|
||
|
||
## 已知问题
|
||
|
||
### 🔴 严重问题（P0）
|
||
|
||
1. **模板语法错误** - [`MilkdownEditor.vue:7-13`](src/components/MilkdownEditor.vue:7-13)
|
||
- GhostTextOverlay 组件标签缺少尖括号
|
||
- 导致建议功能完全失效
|
||
|
||
2. **字符串截取错误** - [`MilkdownEditor.vue:155`](src/components/MilkdownEditor.vue:155)
|
||
- `prefix.substring(-50)` 应该改为 `prefix.slice(-50)`
|
||
|
||
3. **错误处理违反原则** - [`MilkdownEditor.vue:92-94`](src/components/MilkdownEditor.vue:92-94)
|
||
- 请求失败时返回空字符串而不是抛出错误
|
||
- 违反了"获取失败直接报错"的原则
|
||
|
||
### 🟡 中等问题（P1）
|
||
|
||
4. **内存泄漏风险** - 组件卸载时未清理 debounceTimer
|
||
5. **不可靠的事件绑定** - 使用硬编码的 500ms 延迟
|
||
6. **代码重复** - fetchSuggestion 逻辑在两个文件中重复
|
||
7. **全局状态污染** - 插件使用模块级全局变量
|
||
|
||
### 🟢 轻微问题（P2）
|
||
|
||
8. 大量调试日志影响性能
|
||
9. 缺少完整的类型定义
|
||
10. 没有加载状态指示器
|
||
11. 建议文本无长度限制
|
||
12. API URL 硬编码在前端
|
||
13. 后端缺少 CORS 配置
|
||
|
||
## 开发指南
|
||
|
||
### 代码规范
|
||
|
||
- **前端**：遵循 Vue 3 Composition API 最佳实践
|
||
- **后端**：遵循 FastAPI 异步编程模式
|
||
- **错误处理**：获取失败直接报错，不返回默认值
|
||
- **性能优化**：优先考虑降低延迟，避免冗余代码
|
||
|
||
### 调试
|
||
|
||
前端使用浏览器开发者工具，后端查看控制台输出。所有关键操作都有日志记录。
|
||
|
||
## 贡献指南
|
||
|
||
欢迎提交 Issue 和 Pull Request。在提交代码前，请确保：
|
||
|
||
1. 代码通过 ESLint 检查
|
||
2. 所有测试通过
|
||
3. 添加必要的注释和文档
|
||
4. 遵循项目的代码规范
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 致谢
|
||
|
||
- [Milkdown](https://milkdown.dev/) - 优秀的 Markdown 编辑器框架
|
||
- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的 Python Web 框架
|
||
- [OpenAI](https://openai.com/) - 大语言模型 API
|