MarkItDown
用 MarkItDown 构建可解释的文档导入实验室
设计保存原文、选项、预期事实和复核结论的小项目，明确区分现有转换能力与建议扩展。
你将学会
- 先让遗漏可见，再扩展导入规模。
- 预期事实必须独立于生成结果。
- 路由和复核界面在实现前都属于建议扩展。
开始前需要
- 具备基础 Python 与命令行知识
- 准备一份内容可核验且不含敏感信息的文档
使用本章清单解释并验证文档导入流程中的对应环节。
先看结论
- 先让遗漏可见，再扩展导入规模。
- 预期事实必须独立于生成结果。
- 路由和复核界面在实现前都属于建议扩展。
先做小型实验室，再扩展导入服务
一个实用练习是建立包含原文件、Markdown 和验收清单三个视图的转换实验室。先支持一种格式和少量自己编写的样本。目标是在自动处理大规模文档之前，能够解释每一次转换，包括其中的遗漏。
MarkItDown 负责转换步骤；本文的清单、对照界面和质量检查属于建议实现的应用组件。明确这一边界，可以避免读者到上游仓库寻找文章设计出来、实际上并不存在的看板或校验功能。
让每个结果都能追溯输入
每次运行保存源文件校验值、环境标识、转换选项、输出校验值和复核结论。预期事实应与生成的 Markdown 分开，不能让转换结果通过重复自身来给自己评分。若使用模型描述图像，应标注该产物属于生成性解释。
第一版可视化只需用 SVG 连接源文件、所选转换器和输出。只有在帮助复核者定位丢失表格或阅读顺序变化时，再加入交互对照。这个关系不需要三维场景，额外的 3D 效果反而可能妨碍阅读。
从观察逐步走向受控发布
先记录输出与失败，不阻断任何流程；下一步标记已知事实消失的样本；等检查确实有效后，再将其加入工作进程发布门槛。这样每条强制规则都对应明确的理由和可复现的回归样本。
另一位开发者能够新增样本、复现输出、解释拒绝原因并对照两个环境时，实验室才算完成。扫描页分流和复核批注可以作为后续能力分别评估。只有证据仍然可理解，更多自动化才真正有价值。
实施步骤
- 1
为一种格式建立带事实标签的小样本集。
- 2
记录源文件、输出校验值和环境设置。
- 3
并排展示原文、Markdown 与验收事实。
- 4
检查捕获真实回归后，再把它设为发布门槛。
可复制示例
import hashlib
from pathlib import Path
def digest(path):
return hashlib.sha256(Path(path).read_bytes()).hexdigest()
manifest = {
"source_sha256": digest("example.docx"),
"output_sha256": digest("example.md"),
"review": "pending",
}
print(manifest)常见问题
复核看板是 MarkItDown 自带的吗？
不是。本章围绕转换 API 设计应用，额外组件都明确标为练习项目。
什么时候交互图有帮助？
当复核者需要在原文段落、转换结果和失败检查之间定位时，小型对照界面就足够。