#MoonBitMark

• 统一 engine / converter registry
• 共享 normalize passes
• semantic section tree / role / provenance 派生
• PDF 页级 OCR fallback 恢复链路
• 面向 MCP 与 eval 的结构化 diagnostics / explanations
• MCP normalizer 决策轨迹与 baseline compare debug 解释

#支持的输入

• TXT
• CSV
• JSON
• PDF
• 图片：png、jpg、jpeg、bmp、gif、tif、tiff、webp
• HTML / XHTML
• URL：http://...、https://...
• DOCX
• PPTX
• XLSX
• EPUB
• DOC（Word 97-2003 二进制）
• WPS（WPS Writer 二进制）

#快速开始

moon check
moon test

scripts\build.bat

moon build --target native --release

_build/native/release/build/cmd/main/main.exe <input> [output]

_build\native\release\build\cmd\main\main.exe tests\conversion_eval\fixtures\inputs\html\simple_table.html
_build\native\release\build\cmd\main\main.exe --diag-json tests\conversion_eval\fixtures\inputs\pdf\multi_page.pdf
_build\native\release\build\cmd\main\main.exe --dump-ast tests\conversion_eval\fixtures\inputs\html\simple_table.html

#安装为 moonbitmark 命令（Windows）

powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -OutDir D:\docs\markdown

• 构建（或复用）release 二进制，复制为 %LOCALAPPDATA%\MoonBitMark\bin\moonbitmark.exe
• 复制 scripts\ocr、scripts\pdf bridge 脚本到安装目录
• 把 bin 目录加入用户 PATH（新开终端后生效）
• 设置 MOONBITMARK_OCR_BRIDGE / MOONBITMARK_PDF_BRIDGE 用户环境变量
• -OutDir 给定时写入 %USERPROFILE%\.moonbitmark\config.json 的 out_dir 字段

powershell -ExecutionPolicy Bypass -File scripts\uninstall.ps1   # -RemoveConfig 同时删除配置

#默认输出目录

1. MOONBITMARK_OUT_DIR 环境变量（空值跳过该层）
2. <home>/.moonbitmark/config.json 的 out_dir 字段（JSON，如 {"out_dir": "D:/docs/md"}；缺失或空则禁用）

# 配置了默认输出目录后：
moonbitmark report.docx            # -> <out_dir>/report.md
moonbitmark notes.html             # -> <out_dir>/notes.md
moonbitmark report.docx out\x.md   # 显式输出，忽略默认目录

#作为依赖使用（mooncakes）

import {
  "hnlyxiaobing/moonbitmark@0.4.6",
}

import {
  "hnlyxiaobing/moonbitmark/src/engine",
  "moonbitlang/async",
}

supported_targets = "native"

///|
async fn main raise {
  let engine = @engine.MarkItDown::new()
  let result = engine.convert("input.docx")
  println(result.markdown)
}

• 版本要求 >= 0.4.4：0.3.0–0.4.3 的 PDF 支持依赖 registry 版 bobzhang/mbtpdf@0.1.2，该版本使用了当前工具链已移除的 @strconv API， 消费者侧 moon check 会直接失败（实测 7 个错误）。详见 docs/KNOWN_ISSUES.md。
• 使用 async fn main 时必须直接声明 moonbitlang/async 依赖：模块间的传递 依赖不能被本包直接导入（否则报 "its containing module is not imported by ..."）。
• src/engine 等包为 native-only，消费者侧需以 --target native 构建。

#CLI 选项

• --frontmatter
• --plain-text
• --no-metadata
• --asset-dir <dir>
• --ocr <off|auto|force>
• --ocr-lang <lang>
• --ocr-images
• --ocr-backend <auto|mock|tesseract>
• --ocr-timeout <ms>
• --diag-json
• --detect-only
• --dump-ast
• --dump-raw-ast
• --dump-normalized-ast
• --dump-semantic
• --debug
• --help

• --diag-json 输出结构化 diagnostics、stats 和 metadata。
• --dump-ast 输出统一 AST 的 strict JSON。
• --dump-raw-ast 输出 normalize 之前的原始 AST。
• --dump-normalized-ast 输出共享 normalize passes 之后的 AST。
• --dump-semantic 输出派生得到的 semantic section tree / role / provenance。
• MCP response_mode=json 会进一步暴露 explanations，其中包括 heading / table / OCR / uncertainty，以及 normalizer 决策轨迹与 baseline compare debug。
• --detect-only 只做检测，不执行转换。

#项目结构

src/
├── ast/              统一 AST 与 Markdown 渲染
├── capabilities/     横切能力层，目前包含 OCR
├── core/             结果类型、diagnostics、共享 helper
├── engine/           检测与统一调度
├── formats/          各格式转换器
├── libzip/           纯 MoonBit ZIP / Deflate
├── mcp/              MCP 协议、handler 与传输
├── normalize/        共享结构归一化 passes
├── ole2/             纯 MoonBit OLE2/CFB 复合文件读取
├── python/           Python 解释器解析与 bridge 脚本定位
├── semantic/         Section tree / role / provenance 派生层
└── xml/              纯 MoonBit XML parser

cmd/
├── main/             CLI 入口
├── demo/             最小示例
├── mcp-server/       MCP STDIO 入口
└── mcp-http-server/  MCP HTTP 入口

#开发与验证

moon check
moon test
moon test --enable-coverage
moon coverage analyze
moon info
moon fmt

python tests/conversion_eval/scripts/run_eval.py run

pwsh -File scripts/benchmark.ps1 -InputPath <input-file> -Iterations 10

powershell -ExecutionPolicy Bypass -File scripts/run_ocr_mcp_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/integration/mcp_stdio_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/integration/mcp_resources_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/integration/mcp_prompts_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/integration/mcp_security_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/integration/mcp_http_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/integration/mcp_http_security_smoke.ps1

powershell -ExecutionPolicy Bypass -File tests/ocr/ocr_force_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/ocr/ocr_backend_missing.ps1
powershell -ExecutionPolicy Bypass -File tests/ocr/ocr_timeout_smoke.ps1
powershell -ExecutionPolicy Bypass -File tests/ocr/pdf_ocr_force_smoke.ps1

#运行边界

• CLI 是当前主公共入口。
• DOCX、PPTX、XLSX、EPUB 的容器解析依赖仓库内的 libzip + xml。
• OCR 是可选能力，依赖 scripts/ocr/bridge.py 和可用 backend；Python 解释器经 src/python/ 的 resolver 显式解析（可用 MOONBITMARK_PYTHON 覆盖）。
• PDF 主路径使用 registry 依赖 bobzhang/mbtpdf@0.2.0（词距感知抽取在本仓库实现），必要时可按页触发 OCR fallback，并把恢复页信息写回 metadata / diagnostics / eval；当前已补到页级恢复、linewise normalization 和一类常见 OCR 空格分列表格重建。
• MCP 仍是实验性接口，默认以本地 STDIO 或 loopback HTTP 使用为前提。
• Windows native release 构建依赖 MSVC；scripts/build.bat 自动探测 vcvars64（可用 MOONBITMARK_VCVARS64 覆盖）。

#文档

• docs/architecture.md：当前架构、模块职责和外部依赖边界。
• docs/codex_development_guide.md：面向 Codex 的自主开发指引和优先级路线图。
• docs/mcp.md：MCP 入口、工具面和运行时限制。
• docs/KNOWN_ISSUES.md：当前仍有效的已知问题。

#许可证