MarkItDown
MarkItDown 安全与运维：约束文件访问、获取和转换
结合项目说明的 I/O 边界，使用窄接口、隔离工作进程以及明确的插件和云服务配置处理文档导入。
你将学会
- 窄转换接口不等于操作系统沙箱。
- 插件与外部服务需要分别配置和授权。
- 转换后的文档指令仍是不可信内容。
开始前需要
- 具备基础 Python 与命令行知识
- 准备一份内容可核验且不含敏感信息的文档
使用本章清单解释并验证文档导入流程中的对应环节。
先看结论
- 窄转换接口不等于操作系统沙箱。
- 插件与外部服务需要分别配置和授权。
- 转换后的文档指令仍是不可信内容。
选择符合应用需求的入口
README 提醒，转换会以当前进程权限执行 I/O。通用 convert 接受多种输入；如果应用只处理本地文件，应先确认路径在允许范围内，再调用 convert_local。如果字节由应用控制，则向 convert_stream 传入二进制流。
更窄的接口明确了应用打算使用哪种输入获取方式，但它不是操作系统沙箱。高权限进程仍然拥有对应账户的访问能力。应限制挂载目录与账户权限，并在调用任何本地转换接口前验证用户提供的路径。
明确授权可选行为
第三方插件默认关闭。启用后，插件代码可以注册转换器并在进程中执行，应审查插件并在部署记录里保留其版本。安装一个可选格式依赖，与授权任意插件执行，是两项不同的决定。
云转换和模型辅助描述可能向外部服务发送文档内容。本地处理产品应在配置中明确并执行这一选择。如果流程允许远程输入，则应在获取层实施 URL、跳转和网络访问策略，不能假设转换器自动提供这些边界。
给不可信文件设置资源边界
文档解析可能消耗大量 CPU 和内存，压缩包还可能包含许多嵌套条目。应在库之外限制任务资源，并在日志中保留原始失败类别。默认记录任务标识、版本和错误摘要，而不是把整份敏感文档写入日志。
生成的 Markdown 是派生数据，不是下游智能体的可信指令。应保留来源身份，将内容放在文档上下文中。文档即使要求助手泄露秘密或执行命令，也不会因为经过转换器就获得更高权限。
实施步骤
- 1
定义允许的输入获取方式并选用对应 API。
- 2
限制账户权限、挂载目录和资源预算。
- 3
记录插件与外部服务设置。
- 4
保留来源身份，并在日志中屏蔽敏感内容。
可复制示例
from pathlib import Path
from markitdown import MarkItDown
root = Path("/input").resolve()
candidate = (root / "example.docx").resolve()
if not candidate.is_relative_to(root):
raise ValueError("Input must stay inside the assigned directory")
# 使用不可变输入挂载，避免检查后路径发生变化。
result = MarkItDown(enable_plugins=False).convert_local(candidate)常见问题
convert_stream 能让所有解析变安全吗？
不能。它让调用方控制输入字节，但解析器、插件、资源使用和进程权限仍需要边界。
Markdown 会包含提示注入吗？
会。应把内容当作来源文档，而不是模型或工具的高权限指令。