llm-in-text/AGENTS.md

LLM in Text 仓库指引

本文件适用于整个仓库。进入更深层目录后，子目录中的 AGENTS.md 优先于本文件。

项目定位

• 这是一个智能 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、离线模式说明已经落后于当前代码；出现冲突时以实际代码和测试为准。

先看哪里

• 项目概览和运行说明：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

稳定事实

• 补全接口当前不是 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 的描述。

常用命令

• 前端安装：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

代码约定

• 不要把整个仓库当成“全小写+短横线命名”项目。当前实际情况是：
  • Vue 组件和视图多为 PascalCase
  • 前端工具模块多为小写 .js
  • 插件层使用 TypeScript
  • Python 使用 snake_case
• 以就地风格为准，不要顺手做全仓格式统一。
• UI 文案和代理回复默认使用中文。
• 不要修改 milkdown-docs/，它是只读参考资料。
• 不要新增硬编码密钥、空 catch/except、as any、@ts-ignore 之类的扩散式技术债。
• 代理在这个仓库里应优先做局部、可验证的修改，不要做无关重构。

调试路径

• 补全问题： src/components/MilkdownEditor.vue -> src/plugins/copilotPlugin.ts -> src/utils/api.js -> backend/main.py -> backend/prompt.py / backend/llm.py

• OCR 问题： src/components/MilkdownEditor.vue -> backend/main.py -> backend/llm.py

• 文档转换问题： 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

测试和产物

• 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 更适合作为历史背景，不应在与代码冲突时被当成事实来源。
• 修改行为时，优先参考实现代码和对应测试，再决定是否同步普通文档。