ydy0615/llm-in-text
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2283020e51fe251aea88c01e1dc1dea3e03c2794
llm-in-text/README.md
T
“ydy0615” 5a26dfde2a refactor: 全栈架构升级 - 风险控制、会话管理、审计日志和验证码功能 
后端变更:
- 新增 risk_config.py: 风险配置数据类，支持环境变量驱动
- 新增 risk_control.py: 风险控制控制器，管理并发和预算
- 新增 session_store.py: 匿名会话存储，基于 cookie 的 session ID
- 新增 audit_store.py: API 审计日志存储，记录请求和 LLM 调用
- 新增 captcha_api.py: 验证码 API，用于验证用户操作真实性
- 新增 llm_policy.py: LLM 策略配置，管理 completion/pro/vision 模型
- main.py: 集成 middleware、risk/audit/session 模块 (+467/-7)
- job_handlers.py: LLM 执行流程重构，新增 risk/audit 集成 (+207/-4)
- llm.py: 异步客户端封装，新增 max_output_tokens 参数 (+78/-1)
- job_system.py: stream_events 逻辑优化，支持心跳检测 (+12/-4)
- pro_completions.py: SSE heartbeat 机制，防止连接超时 (+14/-4)
- prompt.py: _normalize_preferences 支持 Mapping 类型 (+13/-0)
- tts_asr.py: asyncio loop 初始化，router export (+10/-0)

前端变更:
- src/components/CaptchaComponent.vue: 新增验证码组件 (NEW)
- src/utils/cookie_policy.js: Cookie 策略工具 (NEW)
- SettingsPanel.vue: 集成验证码组件，新增安全设置部分 (+59/-0)
- MilkdownEditor.vue: 移除硬编码 API_KEY，新增 credentials (+32/-10)
- ProBlockCrepe.vue: 样式简化，移除渐变动画 (+18/-4)
- proBlockPlugin.ts: 重构 schema/serializer 引用方式，通过 Ctx 管理 (+40/-10)
- api.js: 新增 credentials，重构 headers 条件逻辑 (+50/-14)
- config.js: API 基址改为 https://api.imageteach.tech:8002 (+8/-4)
- convert.js, docsApi.js, i18n.js: 新增 credentials 和验证码 i18n (+54/-12)
- proAccept.js: 重构正则和转义处理，修复捕获组索引 (+14/-4)

配置和基础设施:
- docker-compose.yml: 新增端口映射 8001:8001 (+2/-0)
- docker/nginx.conf: 改为 307 redirect，优化代理配置 (+8/-6)
- vite.config.js: 移除 proxy 配置，直接调用远程 API (+8/-4)
- .env.example: 新增 VITE_API_BASE_URL, VITE_API_KEY (+3/-1)
- backend/.env.example: 大量 RISK_*, SESSION_*, CORS_* 配置 (+54/-0)
- pytest.ini: 扩展 coverage 范围到整个 backend，移除 fail_under (+3/-2)
- .coveragerc: 移除 fail_under = 90 (+0/-1)
- .gitignore: 新增 docker-data/ (+3/-0)
- package.json: 新增 vue3-captcha 依赖 (+3/-1)
- AGENTS.md, README.md: 更新 Docker 部署和前端网络约定 (+20/-5)
- public/sw.js: Service Worker cache 版本从 v1 升级到 v2 (+0/-1)

测试变更:
- test_main_endpoints.py: 新增 session/risk/audit reset，新增测试用例 (+63/-4)
- test_main_cancel.py: 新增 reset 调用 (+6/-0)
- test_pro_completions.py: 新增 preferences 序列化和测试 (+23/-0)

总计: 45 个文件变更，+1009/-280 行
2026-06-08 11:51:39 +08:00

197 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
## Docker 部署
将整个项目目录放进本机 `~/lit/llm-in-text` 后，在项目根目录执行：
```bash
cp backend/.env.example backend/.env
docker compose up -d --build
```
默认对外端口：
- 前端: `http://localhost:8080`
- 后端: `http://localhost:8001`
持久化目录全部位于当前项目下的 `docker-data/`：
- PostgreSQL: `docker-data/postgres`
- Redis: `docker-data/redis`
- 任务共享临时目录: `docker-data/jobs`
部署前至少需要修改这些环境变量：
- `backend/.env` 中的 `LLM_BASE_URL`
- `backend/.env` 中的 `LLM_API_KEY`
- `backend/.env` 或 shell 环境中的 `DATABASE_URL`
- `backend/.env` 中的 `API_KEY`
## API接口
- POST /v1/completions 流式补全建议
- POST /v1/ocr 图片文字识别
- POST /v1/convert 文档转换
- POST /v1/completions/cancel 取消请求
- GET /v1/docs/nodes 文档空间节点列表
- POST /v1/docs/folders 创建文件夹
- POST /v1/docs/files/text 创建文本文件
- POST /v1/docs/files/upload 上传文件到文档空间
- PATCH /v1/docs/nodes/{id} 更新节点
- PUT /v1/docs/files/{id}/blob 替换文件二进制内容
- DELETE /v1/docs/nodes/{id} 删除节点
- GET /v1/docs/files/{id}/blob 下载或预览原文件
- 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
Reference in New Issue View Git Blame Copy Permalink