feat: enhance Milkdown editor and file system functionality
- Normalize line endings in Markdown export for DOCX files. - Improve selection serialization to Markdown with better handling of empty documents. - Add a new `updateFile` function to the file system for updating file properties. - Introduce video transcoding capabilities using FFmpeg, supporting various video formats. - Update AGENTS.md for clearer plugin structure and responsibilities. - Add scoped styles for TreeNodeItem component to improve UI consistency. - Implement cross-origin isolation headers in Vite configuration for enhanced security. - Remove obsolete test_cross.py file.
This commit is contained in:
@@ -1,90 +1,101 @@
|
||||
# LLM in Text 项目知识库
|
||||
# LLM in Text 仓库指引
|
||||
|
||||
**生成时间:** 2025-04-10
|
||||
**Commit:** 2fdc996
|
||||
**Branch:** main
|
||||
本文件适用于整个仓库。进入更深层目录后，子目录中的 AGENTS.md 优先于本文件。
|
||||
|
||||
## 概述
|
||||
## 项目定位
|
||||
|
||||
智能 Markdown 编辑器，集成 LLM 实时补全建议。前端 Vue3 + Vite + Milkdown，后端 FastAPI + Python + Ollama。核心功能：AI 补全、OCR 图片识别、文档转换、TTS/ASR 语音功能。
|
||||
- 这是一个智能 Markdown 编辑器，前端负责编辑器 UI、上传导出、补全交互和设置状态，后端负责 LLM、OCR、文件转换和 TTS 接口。
|
||||
- 前端技术栈：Vue 3 + Vite + Milkdown/Crepe + Pinia + Vue Router。
|
||||
- 后端技术栈：FastAPI + Python + Ollama。
|
||||
- 当前代码中可以确认的主功能是：AI 补全、OCR、文档转 Markdown、TTS、Markdown/DOCX/PDF 导入导出。
|
||||
- 历史文档中有一部分 TTS/ASR、Apple Silicon、Whisper、离线模式说明已经落后于当前代码；出现冲突时以实际代码和测试为准。
|
||||
|
||||
## 结构
|
||||
## 先看哪里
|
||||
|
||||
```
|
||||
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 入口
|
||||
```
|
||||
- 项目概览和运行说明：README.md
|
||||
- 前端入口：src/main.js
|
||||
- 路由：src/router/index.js
|
||||
- 编辑器主组件：src/components/MilkdownEditor.vue
|
||||
- AI 补全核心：src/plugins/copilotPlugin.ts
|
||||
- 前端请求层：src/utils/api.js
|
||||
- 前端配置：src/utils/config.js
|
||||
- 设置状态：src/stores/settings.js
|
||||
- 后端入口和主路由：backend/main.py
|
||||
- LLM 和 OCR 调用：backend/llm.py
|
||||
- Prompt 组装：backend/prompt.py
|
||||
- TTS 路由：backend/tts_asr.py
|
||||
- 测试配置和入口：pytest.ini、backend/tests/run_tests.py
|
||||
|
||||
## 查找指南
|
||||
## 稳定事实
|
||||
|
||||
| 任务 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| 后端 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/` | 测试配置与用例 |
|
||||
- 补全接口当前不是 SSE；前端用普通 POST 请求拿 JSON 响应。
|
||||
- 前端会生成 X-Request-Id，并在请求被中止时额外调用 /v1/completions/cancel。
|
||||
- 文档超过 32 KB 时，AI 补全会在前端和插件层被禁用。
|
||||
- OCR 文本和文档块内容会被注入补全上下文，但这些内容属于隐藏上下文，不应被直接当作用户可见文本重复输出。
|
||||
- /v1/convert 当前支持 txt、docx、pptx、pdf，非 txt 文件通过 MarkItDown 转成 Markdown，之后会清理图片标记。
|
||||
- 前端存在 /v1/export/pdf 调用点，但当前后端主路由中看不到同名端点；排查 PDF 导出问题前先确认服务端是否真正提供该接口。
|
||||
- 当前 tts_asr.py 主要提供 TTS 相关能力。不要直接沿用 README 或历史修复文档里关于 ASR、Whisper、MPS/offline 的描述。
|
||||
|
||||
## 约定（项目特定）
|
||||
## 常用命令
|
||||
|
||||
- **前端入口**：`src/main.js`（非 TypeScript），使用 Vue3 + Pinia + Vue Router
|
||||
- **后端入口**：`backend/main.py`，端口 8001，uvicorn 启动
|
||||
- **代理配置**：开发时 `/v1` 代理到远程 API，生产需调整
|
||||
- **文件命名**：全小写+短横线（`my-module.py`、`my-component.vue`）
|
||||
- **语言**：UI 默认中文，响应必须使用中文
|
||||
- 前端安装：npm install
|
||||
- 前端开发：npm run dev
|
||||
- 前端构建：npm run build
|
||||
- 后端安装：pip install -r backend/requirements.txt
|
||||
- 后端启动：python backend/main.py
|
||||
- 可选启动方式：uvicorn backend.main:app --reload --port 8001
|
||||
- 全量测试：pytest
|
||||
- 常用窄测试：
|
||||
- pytest backend/tests/test_main_endpoints.py -v
|
||||
- pytest backend/tests/test_main_cancel.py -v
|
||||
- pytest backend/tests/test_prompt.py -v
|
||||
- pytest backend/tests/test_llm.py -v
|
||||
|
||||
## 反模式（本项目禁止）
|
||||
## 代码约定
|
||||
|
||||
- ❌ 硬编码 API_KEY（必须从环境变量读取）
|
||||
- ❌ 在前端暴露密钥（应通过后端代理）
|
||||
- ❌ `npm run dev` 运行网页（无法看到内容）
|
||||
- ❌ 修改 `milkdown-docs/` 目录
|
||||
- ❌ 类型错误使用 `as any` / `@ts-ignore`
|
||||
- ❌ 空的 catch 块
|
||||
- 不要把整个仓库当成“全小写+短横线命名”项目。当前实际情况是：
|
||||
- Vue 组件和视图多为 PascalCase
|
||||
- 前端工具模块多为小写 .js
|
||||
- 插件层使用 TypeScript
|
||||
- Python 使用 snake_case
|
||||
- 以就地风格为准，不要顺手做全仓格式统一。
|
||||
- UI 文案和代理回复默认使用中文。
|
||||
- 不要修改 milkdown-docs/，它是只读参考资料。
|
||||
- 不要新增硬编码密钥、空 catch/except、as any、@ts-ignore 之类的扩散式技术债。
|
||||
- 代理在这个仓库里应优先做局部、可验证的修改，不要做无关重构。
|
||||
|
||||
## 命令
|
||||
## 调试路径
|
||||
|
||||
```bash
|
||||
# 前端开发
|
||||
npm install
|
||||
npm run dev # 端口 5173
|
||||
npm run build # 构建到 dist/
|
||||
- 补全问题：
|
||||
src/components/MilkdownEditor.vue
|
||||
-> src/plugins/copilotPlugin.ts
|
||||
-> src/utils/api.js
|
||||
-> backend/main.py
|
||||
-> backend/prompt.py / backend/llm.py
|
||||
|
||||
# 后端运行
|
||||
pip install -r backend/requirements.txt
|
||||
python backend/main.py # 端口 8001
|
||||
# 或
|
||||
uvicorn backend.main:app --reload --port 8001
|
||||
- OCR 问题：
|
||||
src/components/MilkdownEditor.vue
|
||||
-> backend/main.py
|
||||
-> backend/llm.py
|
||||
|
||||
# 测试
|
||||
pytest # 运行所有测试，覆盖率要求 90%
|
||||
python backend/tests/run_tests.py unit # 单元测试
|
||||
python backend/tests/run_tests.py integration # 集成测试
|
||||
```
|
||||
- 文档转换问题：
|
||||
src/utils/convert.js
|
||||
-> backend/main.py
|
||||
|
||||
## 注意事项
|
||||
- TTS 问题：
|
||||
src/components/TTSMenu.vue / src/components/TTSPlayer.vue / src/components/MilkdownEditor.vue
|
||||
-> src/utils/api.js
|
||||
-> backend/tts_asr.py
|
||||
|
||||
- **架构分离**：前端仅渲染和数据回传，后端负责 LLM API 调用和数据解析
|
||||
- **延迟优先**：代码效率优先，降低延迟放在第一位
|
||||
- **大小限制**：文档超过 32KB 自动禁用 AI 补全
|
||||
- **milkdown-docs/**：官方文档参考，不可修改，编辑器相关问题需核对此目录
|
||||
## 测试和产物
|
||||
|
||||
- pytest.ini 对 backend.main、backend.llm、backend.prompt、backend.geoip、backend.prompts、backend.tts_asr 设了覆盖率门槛，低于 90% 会失败。
|
||||
- 默认测试目录是 backend/tests。
|
||||
- 常见生成产物包括 dist、htmlcov、.pytest_cache、api_performance_report.md；它们不是源代码。
|
||||
|
||||
## 文档注意事项
|
||||
|
||||
- README.md 对产品功能有参考价值，但其中补全、TTS/ASR 和部分接口说明已经比代码旧。
|
||||
- backend/TTS_ASR_MACOS_FIX.md 和 backend/tests/TESTING_GUIDE.md 更适合作为历史背景，不应在与代码冲突时被当成事实来源。
|
||||
- 修改行为时，优先参考实现代码和对应测试，再决定是否同步普通文档。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user