llm-in-text/README.md

# 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