xionghao/FunMD_Convert
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v1.0.0
FunMD_Convert/修改总结.md

460 lines
14 KiB
Markdown
Raw Permalink Normal View History

Import project files
2026-01-07 17:18:26 +08:00
toolName: search_codebase
status: success
query: Locate existing Python code for docling and word2markdown converters, FastAPI app, and any existing front-end reference at docling/app/static/index.html. Identify project structure and existing functions for converting docx/pdf to markdown and custom conversions.
toolName: view_folder
status: success
/Users/fanyang/Desktop/FunMD_Convert
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/services/docling_adapter.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/services/docling_adapter.py
toolName: search_by_regex
status: success
query: def .*\(
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/word2markdown/convert_to_md.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/word2markdown/convert_to_md.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/static/index.html
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/static/index.html
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/static/index.html
toolName: search_by_regex
status: success
query: convert-folder
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
toolName: search_by_regex
status: success
query: Dockerfile
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/tests/test_md_to_docx.py
toolName: view_folder
status: success
/Users/fanyang/Desktop/FunMD_Convert/word2markdown
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/word2markdown/app.py
toolName: todo_write
status: success
Todos updated: 5 items
toolName: ApplyPatch
status: running
toolName: write_to_file
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/services/unified_converter.py
content: undefined
toolName: ApplyPatch
status: running
toolName: edit_file_update
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
changes:
toolName: ApplyPatch
status: running
toolName: edit_file_update
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
changes:
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
toolName: ApplyPatch
status: running
toolName: edit_file_update
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/server.py
changes:
toolName: ApplyPatch
status: running
toolName: write_to_file
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/tests/test_api_convert.py
content: undefined
toolName: run_command
status: success
command: python -m pytest -q undefined
toolName: ApplyPatch
status: running
toolName: edit_file_update
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/tests/test_api_convert.py
changes:
toolName: run_command
status: success
command: python -m unittest -q undefined
toolName: run_command
status: success
command: python -m unittest discover -s tests -p "test_*.py" -v undefined
toolName: todo_write
status: success
Todos updated: 5 items
toolName: view_files
status: success
filePath: /Users/fanyang/Desktop/FunMD_Convert/docling/app/services/unified_converter.py
**重构概要**
- 统一了两套转换能力（Docling 通用转换 + Word2Markdown 定制转换），新增统一入口类并在后端暴露标准化接口。
- 按文档规范统一了接口输出结构（POST、JSON、包含 code/msg/data），并为错误处理加上 try/except 包装。
- 增强 Markdown/HTML 的后处理：将 `:::` 提示块转换为 `!!!`，HTML 表格标签强制小写，去除标签后无意义换行。
- 扩展批量上传：支持 ZIP/TAR 压缩包上传，自动解压、资源上传至 MinIO、Markdown 资产重写并回传可用 URL。
- 预置了单元测试样例，覆盖统一转换和接口返回结构，后续安装依赖后可运行。
**核心改动**
- 统一转换类
- 新增 `FormatConverter`，可一键选择使用 Docling 或 Word2Markdown 引擎，统一返回目标格式。
- 文件位置：`docling/app/services/unified_converter.py:57`，核心方法 `convert` 在 `docling/app/services/unified_converter.py:61`。
- 行为要点：
- 引擎选择：传 `engine=word2markdown|pandoc|custom` 时走 `word2markdown.convert_any`；默认走 `Docling.DocumentConverter`。
- Markdown后处理：将 `:::` 提示块转换为 `!!!`（`docling/app/services/unified_converter.py:33`）；HTML表格标签小写化（`docling/app/services/unified_converter.py:22`）。
- 标准化接口
- 新增统一转换接口 `POST /api/convert`，提供 file 或 source_url 二选一；可选 `export=markdown|html|json|doctags` 和 `engine`；支持 `save=true` 上传到 MinIO。
- 位置：`docling/app/server.py:1413`，统一返回结构在 `docling/app/server.py:1380` 和 `docling/app/server.py:1396`。
- 返回字段：
- 不保存：`data = {encoding, content, name, media_type}`
- 保存到 MinIO：`data = {encoding, name, media_type, minio_url, minio_presigned_url}`
- 所有响应遵循 `{"code": 0|500, "msg": "...", "data": ...}`，实现于 `docling/app/server.py:1363` 和 `docling/app/server.py:1368`。
- 压缩包上传
- 新增 `POST /api/upload-archive`：上传 ZIP/TAR 包，后端解压→批量上传资源至 MinIO→重写 `*.md` 内部相对资源链接为 MinIO URL→返回列表。
- 位置：`docling/app/server.py:1413`（函数起始见 `docling/app/server.py:1414`）。
- 返回数据：`data={count, files:[{source, minio_url, minio_presigned_url, mappings}]}`。
- 用到了现有资产上传与链接重写能力：`_bulk_upload_assets` 在 `docling/app/server.py:1079`，`_rewrite_md_assets_to_minio` 在 `docling/app/server.py:885`。
- MinIO 配置与管理
- 运行时配置体 `RUNTIME_CONFIG` 保持不变，动态载入/保存配置、桶管理接口均已可用。相关路径：
- 载入/保存配置：`docling/app/server.py:349`、`docling/app/server.py:369`、`docling/app/server.py:386`
- 桶列表/创建：`docling/app/server.py:287`、`docling/app/server.py:304`
- Markdown → DOCX/PDF
- 保留原有 `POST /md/convert` 接口能力（页眉页脚、logo、封面、CSS 模板、目录 TOC、MinIO 存储等），详见 `docling/app/server.py:473`。
- 实际转换使用 `md_to_docx_bytes` 与 `md_to_pdf_bytes_with_renderer`（`docling/app/services/docling_adapter.py:105`、`docling/app/services/docling_adapter.py:676`），并已支持页眉页脚与封面元信息渲染（`normalize_html` 流水线在 `docling/app/services/docling_adapter.py:433` 到 `docling/app/services/docling_adapter.py:662`）。
**满足 PRD 的关键点**
- 统一 POST + JSON + code/msg/data：新增 `api_convert` 与 `api_upload-archive`，所有返回体包含 `code/msg/data`（`docling/app/server.py:1363`、`docling/app/server.py:1368`、`docling/app/server.py:1413`）。
- 异常捕获：统一接口有 `try...except...` 并转换为标准结构（`docling/app/server.py:1408`、`docling/app/server.py:1476`），全局异常中间件已存在（`docling/app/server.py:1231`、`docling/app/server.py:1245`、`docling/app/server.py:1255`）。
- 转换特性：
- 非 UTF-8 文档编码识别与归一化由 `word2markdown.convert_to_md` 内置实现（例如 `word2markdown/convert_to_md.py:309`、`word2markdown/convert_to_md.py:326`）。
- DOC/DOCX 单行单列表格识别为代码块由 `word2markdown/convert_to_md.py:196`、`word2markdown/convert_to_md.py:200` 完成。
- HTML `<table>` 标签统一小写由统一转换类的 HTML 后处理完成（`docling/app/services/unified_converter.py:22`）。
- 删除 HTML 标签后多余换行由小写化时一并规整（`docling/app/services/unified_converter.py:29`）。
- Markdown 中 `:::` 提示块 → `!!!` 由统一转换类完成（`docling/app/services/unified_converter.py:33` 到 `docling/app/services/unified_converter.py:55`）。
- 图片/静态资源入库 MinIO 与 URL 重写：单文件在 `md_convert` 内部，批量在 `md_convert_folder` 与 `md_upload_folder`（`docling/app/server.py:1099`、`docling/app/server.py:1151`），新 `api_upload-archive` 同样实现（`docling/app/server.py:1413`）。
- 文件上传场景：
- 单文件上传：`POST /api/convert` 提供 `file`（`docling/app/server.py:1369`）。
- URL 上传：`POST /api/convert` 提供 `source_url`（`docling/app/server.py:1369`）。
- 压缩包：`POST /api/upload-archive`（`docling/app/server.py:1413`）。
- 前端页面
- 现有测试页仍可用（`docling/app/static/index.html`）。Vue3 重构计划后续推进。
- 部署
- 现有 FastAPI 服务与静态页集成，后续可将 `docling/app` 打包为镜像；MinIO 配置已支持运行时动态调整。
**接口用法示例**
- 单文件转 Markdown（不保存）
- `curl -s -X POST http://localhost:8000/api/convert -F file=@/path/sample.docx -F export=markdown -F save=false`
- URL 转换为 Markdown（保存到 MinIO）
- `curl -s -X POST http://localhost:8000/api/convert -F source_url="https://example.com/sample.pdf" -F export=markdown -F save=true`
- 压缩包批量上传并重写链接
- `curl -s -X POST http://localhost:8000/api/upload-archive -F file=@/path/docs.zip -F prefix=assets`
**教育性说明**
- 引擎路由与契约统一
- 统一转换类屏蔽底层差异，默认走 Docling，遇到需要 Pandoc/定制规则时切 Word2Markdown，实现“契约优先”的稳定输出。
- Markdown/HTML 后处理
- 将 `:::` → `!!!` 保证提示块在统一渲染器（包括 PDF/DOCX 流程）下保持一致；HTML 表格小写化避免某些渲染器的大小写敏感差异。
- 资产重写与 MinIO
- 多层回退：先批量上传图片资源，再按路径和搜索根解析相对链接；任何失败的映射保留在 `mappings` 中，便于后续修复。
- 防御式异常处理
- 接口返回始终有 `code/msg/data`，即使遇到异常也不会破坏前端调用流程；需要详细排错时可开启 `debug` 查询参数或请求头（`docling/app/server.py:1216`）。
**已添加的测试**
- 位置：`docling/app/tests/test_api_convert.py:1`
- 用例：上传一个包含 `:::` 的 Markdown 文件，验证返回 `code=0`、`data.content` 存在并包含 `!!! note`。
- 运行方法（需要安装依赖）：
- `python -m unittest discover -s tests -p "test_*.py" -v`
**后续建议**
- 前端 Vue3 重构：将 `docling/app/static/index.html` 的交互改造为 Vue3，抽象配置表单与批量任务的状态管理。
- 镜像化与部署：整理 `requirements`，增加 Dockerfile 与构建脚本，结合 Ingress 暴露。
- 配置管理：完成配置文件的多环境切换与权限控制，支持 Profile 导入导出（已有后端支持，`docling/app/server.py:349`、`docling/app/server.py:369`、`docling/app/server.py:386`）。
- 测试矩阵：在 `tests` 中补充更多文件类型与异常场景（损坏 DOCX、RTF、伪 DOCX、MDX 复杂 JSX 等），并加上 MinIO 交互的集成测试。
如果你现在就要联调，可以直接用上述 curl 命令触发新接口；如需我继续把前端测试页改造以调用新接口或推进 Vue3 页面，我可以立刻开始。
Reference in New Issue Copy Permalink