xionghao/FunMD_Convert
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v1.0.0
FunMD_Convert/修改总结.md
seekee 0b07e63b76 Import project files
2026-01-07 17:18:26 +08:00

14 KiB
Raw Permalink Blame History

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 页面，我可以立刻开始。