llm-in-text/README.md

# LLM in Text - 智能写作助手

基于 Vue3 和 FastAPI 的智能 Markdown 编辑器，集成大语言模型（LLM）实时补全建议功能。

## 功能特性

### Markdown 编辑器
- 基于 Milkdown Crepe 的所见即所得编辑体验
- 支持 Markdown 语法和 LaTeX 公式
- 支持 Mermaid 图表渲染
- 导入/导出 Markdown 文件
- 导出 DOCX 和 PDF 格式

### AI 智能补全
- 实时生成文本补全建议（灰色显示）
- 流式响应，低延迟体验
- 多种交互方式：Tab接受、Esc拒绝、点击接受

### 功能块系统

编辑器提供三种**功能块**，统一为顶层原子节点（`atom: true, isolating: true`），通过 ProseMirror schema 强制禁止互相嵌套，无数量限制。导入 Markdown 后自动解析还原为交互卡片，导出后可完整复原：

| 功能块 | Markdown 语法 | 作用 |
|--------|---------------|------|
| **文档块** (`doc_block`) | \`\`\`llm-file fenced code / `<doc_type=...>` legacy HTML tag | 上传的 PDF/DOCX/PPTX/TXT 等文件以可折叠卡片嵌入编辑器，支持内联编辑和 AI 补全 |
| **PRO 块** (`pro_block`) | `[PRO]` / `[PRO]{指令}` | 基于全文上下文进行深度 AI 思考并流式生成 Markdown，`Ctrl+Shift+P` 快速插入 |
| **上传块** (`upload_block`) | `{{{}}}` / `{{{upload file type:pdf,docx}}}` | 文件上传占位符，支持按类型过滤（PDF/DOCX/PPTX/TXT/JSON/YAML/图片等） |

### 文档处理（历史名称，已整合入功能块系统）
- OCR 图片识别：上传图片自动识别文字（OCR 结果注入 AI 补全和 PRO 块上下文）
- 智能大小限制：32KB自动禁用AI

### 设置面板
- 外观主题：亮色/暗色/跟随系统
- 背景模式：默认/暖色/阅读灯/自定义图片
- 模型智能：低/中/高思考级别
- 隐私控制：隐私模式防止发送IP
- 多语言界面：中英日韩德法

### 语音功能
- TTS文字转语音（macOS优化，支持Apple Silicon M1/M2/M3）
- STT语音转文字（支持多种模型大小和量化）
- 自动设备检测（MPS/CUDA/CPU智能切换）
- 离线模式支持（模型缓存检查）

## 技术架构

前端: Vue3 + Vite + Milkdown/Crepe + ProseMirror
后端: FastAPI + Python（OpenAI 兼容端点）

### 功能块架构
三种功能块统一为顶层原子节点（`atom: true, isolating: true`），通过 ProseMirror schema 强制禁止嵌套：
- **文档块** (`doc_block`) — `src/plugins/docBlockPlugin.ts`，Markdown 语法：\`\`\`llm-file fenced code block
- **PRO 块** (`pro_block`) — `src/plugins/proBlockPlugin.ts`，Markdown 语法：`[PRO]` / `[PRO]{指令}`
- **上传块** (`upload_block`) — `src/plugins/uploadBlockPlugin.ts`，Markdown 语法：`{{{}}}` / `{{{upload file type:...}}}`

每个功能块配备独立的 Remark 解析器和序列化器，确保 Markdown 导入导出时自动识别和还原。

## 快速开始

环境: Node.js 18+、Python 3.8+

安装:
- 前端: npm install
- 后端: pip install -r backend/requirements.txt

启动:
- 后端: python backend/main.py (端口8001)
- 前端: npm run dev (端口5173)

## API接口

- POST /v1/completions 流式补全建议
- POST /v1/ocr 图片文字识别
- POST /v1/convert 文档转换
- POST /v1/completions/cancel 取消请求
- GET /v1/tts-asr/status TTS/ASR模型状态
- GET /v1/tts-asr/config TTS/ASR配置信息
- POST /v1/tts-asr/warmup 模型预热
- POST /v1/tts-asr/tts 文字转语音
- POST /v1/tts-asr/asr 语音转文字

## TTS/ASR环境变量配置

支持以下环境变量来配置TTS/ASR模块：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `TTS_ASR_DEVICE` | 设备选择 (auto/mps/cuda/cpu) | auto |
| `TTS_ASR_MODEL_SIZE` | ASR模型大小 (tiny/base/small/medium/large/turbo) | auto |
| `TTS_ASR_QUANTIZE` | 是否使用INT8量化 (true/false) | false |
| `TTS_ASR_OFFLINE_MODE` | 离线模式，仅使用缓存模型 (true/false) | false |
| `TTS_ASR_WARMUP` | 启动时预热模型 (true/false) | true |
| `TTS_ASR_WARMUP_TIMEOUT` | 预热超时时间(秒) | 120 |
| `TTS_ASR_IDLE_TIMEOUT` | 空闲卸载时间(秒，0=不卸载) | 0 |
| `TTS_ASR_MPS_MEMORY_LIMIT_MB` | MPS内存限制(MB) | 8192 |

**Apple Silicon优化建议**:
- 系统自动检测Apple Silicon并推荐使用`small`模型
- MPS内存限制默认为系统内存的60%
- 建议使用`small`或`medium`模型以获得更好的性能
- 可通过`TTS_ASR_MODEL_SIZE=medium`手动指定模型大小

## 核心实现

### 后端
- main.py: FastAPI服务器、SSE流式响应
- llm.py: 异步LLM调用（OpenAI兼容）、超时控制
- prompt.py: 7条Prompt规则
- tts_asr.py: macOS/Apple Silicon优化的TTS/ASR处理
  - 自动检测Apple Silicon (M1/M2/M3)
  - MPS/CUDA/CPU智能降级
  - 支持多种Whisper模型大小
  - INT8量化支持
  - 离线模式支持
  - 健壮的音频重采样

### 前端
- copilotPlugin.ts: ProseMirror Mark系统
- 关键函数: scheduleFetch、insertGhostText
- Pinia Store状态管理

## 设计亮点

1. 前后端分离
2. 低延迟优化：防抖+SSE+AbortController
3. ProseMirror Mark系统
4. 多种交互方式
5. 智能大小限制
6. 隐私保护
7. 多语言支持
8. 主题定制
9. 文档处理
10. 语音功能

## 开发指南

代码风格: Python(4空格,snake_case) JS/TS(2空格,camelCase)
测试: pytest
构建: npm run build

### 运行测试

项目提供完整的测试套件，包括单元测试、集成测试和macOS环境模拟测试：

```bash
# 快速运行单元测试
python backend/tests/run_tests.py unit

# 运行集成测试（需要启动后端服务）
python backend/tests/run_tests.py integration

# 运行macOS环境模拟测试（在非Mac环境测试）
python backend/tests/run_tests.py simulate

# 运行所有测试
python backend/tests/run_tests.py all
```

详细测试说明请参考: [测试指南](backend/tests/TESTING_GUIDE.md)

## 许可证

MIT License