feat: update AGENTS.md with new components and API details; enhance FileContent.vue with Plyr video support; add VideoPlayer.vue for video playback; improve MilkdownEditor.vue for video file handling; refine TTSPlayer.vue volume controls; optimize settings store for localStorage; implement video upload support in uploadBlock.js; create utility functions for Plyr player management.
This commit is contained in:
“ydy0615”
@@ -1,4 +1,4 @@
|
||||
# LLM in Text 仓库指引
|
||||
# LLM in Text 仓库指引 (v0.2.0)
|
||||
|
||||
本文件适用于整个仓库。进入更深层目录后，子目录中的 AGENTS.md 优先于本文件。
|
||||
|
||||
@@ -6,7 +6,8 @@
|
||||
|
||||
- 这是一个智能 Markdown 编辑器，前端负责编辑器 UI、上传导出、补全交互和设置状态，后端负责 LLM、OCR、文件转换和 TTS 接口。
|
||||
- 前端技术栈：Vue 3 + Vite + Milkdown/Crepe + Pinia + Vue Router。
|
||||
- 后端技术栈：FastAPI + Python + OpenAI-compatible LLM endpoint。
|
||||
- 后端技术栈：FastAPI + Python + Ollama-compatible LLM endpoint + Redis Streams。
|
||||
- 项目版本：v0.2.0（自 b82c6d3 之后的全栈架构升级版本）。
|
||||
|
||||
## 功能块系统（核心概念）
|
||||
|
||||
@@ -32,25 +33,49 @@
|
||||
- 前端入口：src/main.js
|
||||
- 路由：src/router/index.js
|
||||
- 编辑器主组件：src/components/MilkdownEditor.vue
|
||||
- AI 补全核心：src/plugins/copilotPlugin.ts
|
||||
- 前端请求层：src/utils/api.js
|
||||
- AI 补全核心：src/plugins/copilotPlugin.ts、src/plugins/copilotTypes.ts（类型定义）
|
||||
- 前端请求层：src/utils/api.js、src/utils/fetch.js（安全 fetch wrapper）
|
||||
- 前端配置：src/utils/config.js
|
||||
- 设置状态：src/stores/settings.js
|
||||
- 后端入口和主路由：backend/main.py
|
||||
- LLM 和 OCR 调用：backend/llm.py
|
||||
- Prompt 组装：backend/prompt.py
|
||||
- Prompt 组装：backend/prompt.py（含 PRO 模式模板）
|
||||
- TTS 路由：backend/tts_asr.py
|
||||
- 测试配置和入口：pytest.ini、backend/tests/run_tests.py
|
||||
- **任务队列系统**：backend/job_system.py（Redis Streams 异步任务管理）
|
||||
- **Worker 进程入口**：backend/worker.py（消费 Redis Streams 的独立 worker）
|
||||
- **任务处理器注册表**：backend/job_handlers.py（completion/PRO/web_search/compress/OCR/convert/TTS/ASR 处理器）
|
||||
- **会话管理**：backend/session_store.py（内存 + PostgreSQL 双后端）
|
||||
- **API/LLM 审计日志**：backend/audit_store.py（PostgreSQL 持久化）
|
||||
- **风控配置**：backend/risk_config.py（环境变量驱动的配置数据类）
|
||||
- **风控引擎**：backend/risk_control.py（速率限制、并发控制、熔断器、预算追踪）
|
||||
- **验证码路由**：backend/captcha_api.py（FastAPI router）
|
||||
- **文档存储**：backend/docs_store.py（MIME 类型检测、文本/二进制分类）
|
||||
- **LLM 策略解析**：backend/llm_policy.py（按 job_type 解析模型配置）
|
||||
- **网页搜索块组件**：src/components/WebSearchBlockCrepe.vue（可折叠/压缩/删除的搜索结果卡片）
|
||||
- **网页搜索块插件**：src/plugins/webSearchBlockPlugin.ts（```llm-websearch fenced code 语法）
|
||||
- **OCR 图片包装器**：src/components/OCRImageWrapper.vue（加载/成功/失败状态覆盖层）
|
||||
- **验证码组件**：src/components/CaptchaComponent.vue（vue3-captcha 封装）
|
||||
- **SSE 流式解析**：src/utils/sse.ts（Server-Sent Events 事件解析）
|
||||
- **文档管理 API**：src/utils/docsApi.js（上传/预览/删除接口客户端）
|
||||
- **PRO 功能接受追踪**：src/utils/proAccept.js（使用分析和统计）
|
||||
- **Cookie 策略管理**：src/utils/cookie_policy.js（SameSite/Secure 标志处理）
|
||||
- **字符串工具**：src/utils/string.ts（长度计算、编码检测）
|
||||
- **网页搜索上下文提取**：src/utils/webSearch.js（搜索结果 Markdown 构建与解析）
|
||||
- **测试配置和入口**：pytest.ini、backend/tests/run_tests.py
|
||||
|
||||
## 稳定事实
|
||||
|
||||
- **功能块禁止嵌套**：`doc_block`、`pro_block`、`upload_block` 的 schema 均设 `atom: true, isolating: true`，ProseMirror 层面强制禁止互相嵌套。DocBlockCrepe.vue 的嵌套 Crepe 编辑器仅注册 copilotPlugin + hiddenText*，不注册任何功能块插件。修改时不得移除 atom/isolating 属性或在嵌套编辑器中引入功能块插件。
|
||||
- **功能块导入解析**：各功能块的 Remark 插件（`docBlockRemark`, `proBlockRemark`, `uploadBlockRemark`）负责从 Markdown AST 识别对应语法并转换为节点。doc_block Remark 同时支持 fenced code (`llm-file`) 和 legacy HTML tag (`<doc_type=...>`)。解析链路必须保持完整，否则导入后无法自动复原。
|
||||
- **功能块导出序列化**：doc_block 的 `toMarkdown` runner 输出 legacy HTML tag，但 `getExportMarkdown()` 中通过 `transformLegacyDocBlocksForExport()` 转换为 fenced code block。pro_block/upload_block 的 toMarkdown/leafText 直接输出标准语法。修改时需验证导出后再次导入能完整复原。
|
||||
- **Web Search 块语法**：web_search_block 使用 fenced code ```llm-websearch date=... 语法，与 doc_block(llm-file)、pro_block([PRO])、upload_block({{{}}}) 并列。触发语法为 [WEBSEARCH]（不区分大小写），由 `webSearchBlockPlugin.ts` 处理。
|
||||
- **Store 同步格式**：`scheduleMarkdownSync()` emit markdown 不做转换（doc_block 为 legacy HTML tag），store 中始终是 legacy format。`syncInitialMarkdown()` / `getExportMarkdown()` 负责格式转换。
|
||||
- **上传块生命周期**：upload_block 是临时占位符，文件上传后被替换为 image node（图片）或 doc_block（文档），不会与 pro_block 共存。
|
||||
- **PRO block escape/unescape**：`escapeProBlockContent()` / `unescapeProBlockSyntax()` 处理 `\`, `]`, `}`, newline，确保指令 round-trip 正确。
|
||||
- **补全接口当前不是 SSE**；前端用普通 POST 请求拿 JSON 响应。
|
||||
- **任务队列架构（v0.2.0 新增）**：后端从同步端点转向 Redis Streams 异步队列。`job_system.py` 定义 JOB_TYPES（completion/pro_completion/web_search/compress/ocr/convert/tts/asr），`worker.py` 消费队列，`job_handlers.py` 注册各类型处理器。所有任务支持并发控制、速率限制和熔断器模式。
|
||||
- **会话追踪**：`session_store.py` 提供 InMemorySessionStore（开发）和 PostgresSessionStore（生产），通过 session_hash + ip_hash 追踪请求身份。
|
||||
- **风控系统**：`risk_config.py` + `risk_control.py` 实现速率限制（滑动窗口）、并发控制、熔断器模式和预算追踪，所有阈值通过环境变量配置。
|
||||
- 前端会生成 X-Request-Id，并在请求被中止时额外调用 /v1/completions/cancel。
|
||||
- 文档超过 32 KB 时，AI 补全会在前端和插件层被禁用。
|
||||
- OCR 文本和文档块内容会被注入补全上下文，但这些内容属于隐藏上下文，不应被直接当作用户可见文本重复输出。
|
||||
@@ -78,6 +103,7 @@
|
||||
- 本机部署目录固定在 `/Users/allenyuan/lit/` 下，不在仓库外再散落数据库或 Docker 持久化目录。
|
||||
- 当前推荐的部署工作目录是 `/Users/allenyuan/lit/llm-in-text/`；把仓库同步到该目录后，从该目录执行 `docker compose up -d --build`。
|
||||
- 不再使用 `/Volumes/New Volume/lit/` 部署本项目；迁移时可放弃旧 PostgreSQL 数据，从新部署目录初始化空数据库。
|
||||
- **docker-compose.yml 定义的服务**：api（FastAPI）、worker（任务消费者）、frontend（Nginx）、postgres（审计+会话存储）、redis（任务队列）、searxng（网页搜索后端）、firecrawl（网页内容抓取）。每次 `docker compose up --build` 后，必须验证所有目标服务（api/worker/frontend/postgres/redis）是否处于 Up 状态。
|
||||
- **前端网络硬约定**：前端 API 必须调用 `https://api.imageteach.tech:8002/` 反向代理，不要让前端调用 Docker 内 `api` 服务、本机 `localhost:8001`、`localhost:8081` 或同源 `/v1` 代理。网络和反向代理由外部配置处理，除非用户明确要求，不要新增或恢复前端到 Docker 后端的代理。
|
||||
- 每次修改会影响 Docker 运行效果的代码后，不能只停留在本地测试；必须同步更新当前 Docker 环境中的代码，并验证容器内代码已经变化。
|
||||
- 首选更新方式：
|
||||
@@ -94,6 +120,8 @@
|
||||
- Docker 持久化数据统一落在部署目录内的 `docker-data/`，包括 PostgreSQL、Redis 和任务共享临时目录。
|
||||
- 容器内访问宿主机模型服务时，不要继续使用 `localhost`；应改成 `host.docker.internal` 之类的容器可达地址。
|
||||
- 当前 Docker 部署默认使用轻量后端依赖集（`backend/requirements.docker.txt`），覆盖补全、OCR、转换、文档空间和队列，不默认包含本地 `torch` / TTS / ASR 模型栈。
|
||||
- **Worker 容器**：worker.py 作为独立服务运行，通过 Redis Streams 消费任务队列。修改 job_handlers.py 或 worker.py 后需要验证 worker 容器内的代码已更新，可通过 `docker compose exec -T worker sh -lc "python -c 'from backend.job_handlers import get_handler; print(get_handler(\"completion\").__name__)'"` 验证。
|
||||
- **Redis Streams 架构**：任务队列使用 Redis Streams，支持并发控制、速率限制和熔断器。job_system.py 定义 JOB_TYPES 和队列配置，worker.py 注册处理器并运行事件循环。
|
||||
- 修改 Docker 相关文件时，除了代码本身，还要同步检查：
|
||||
- `docker-compose.yml`
|
||||
- `backend/Dockerfile`
|
||||
|
||||
Reference in New Issue
Block a user