wjjjjjjjjjjj MarkItDown 文件转换
把用户给出的源文件转换成适合检索、分析、知识库归档和大模型处理的 Markdown。MarkItDown 的目标是保留标题、段落、列表、表格和链接等语义结构，不追求复刻源文件的视觉版式。
已在 Windows PowerShell 5.1+ 与 MarkItDown 0.1.6 上验证。每次运行仍须探测命令版本及目标格式所需的可选依赖，不能把当前环境状态当作永久前提。
工作流程
确定输入。
- 优先使用用户明确给出的文件或目录。
- 用户说“这些文件”但未给出路径时，先查看当前会话附件或当前工作区中最可能的文件；仍无法唯一确定时，只问一个关键确认问题。
- 不要在未经用户同意的情况下扫描与任务无关的大目录。
确定输出位置。
- 用户指定位置时，遵从用户要求。
- 单个文件且未指定位置时，默认在源文件同目录生成同名
.md。 - 目录批量转换且未指定位置时，默认写入源目录下的
markdown_output/，递归转换时保留相对目录结构。 - 不覆盖已有文件；脚本会自动生成
-converted或数字后缀。只有用户明确要求覆盖时才传入-Force。
执行转换。
powershell -NoProfile -ExecutionPolicy Bypass -File "<skill目录>\scripts\convert.ps1" -InputPath "<输入文件或目录>"常见参数：
# 指定输出目录 -OutputDirectory "<输出目录>" # 递归转换目录 -Recurse # 用户明确要求时覆盖已有输出 -Force # 用户明确需要第三方 MarkItDown 插件时启用 -UsePlugins # 用户明确要求保留 data URI 时启用 -KeepDataUris校验结果。
- 读取脚本返回的 JSON 汇总。
- 成功必须同时满足：命令退出正常、目标
.md存在、文件大小大于 0。 - 对 Word、PPT、PDF、Excel 等结构化文档，抽查 Markdown 的标题或关键文本，避免只生成空壳文件。
- 批量转换时报告成功、失败、跳过数量，并列出失败文件及原因。
回报用户。
- 给出生成文件的可点击绝对路径。
- 简要说明转换数量与失败项。
- 如源文件主要由扫描图片构成，说明普通本地转换可能只得到有限文本；需要 OCR/视觉模型时再建议增强方案，不要把低质量结果说成完整提取。
安全与边界
- 保留源文件，不删除、不移动、不改写。
- 包装脚本只处理本地文件。URL 应先通过安全的网页获取流程下载到受控工作目录，完成来源与访问边界检查后，再把本地副本交给本 Skill；不要把 URL 直接传给脚本。
- 对不可信 ZIP 或 HTML，先确认输入来源；MarkItDown 会以当前进程权限读取它可访问的资源。
- 如果
markitdown命令或目标格式依赖不可用，脚本必须返回结构化失败 JSON 和非零退出码。不要静默换用另一套转换器；需要重装时向用户说明。 - 所有转换先写入目标同目录的唯一临时文件，校验成功后再原子替换目标。失败时删除临时文件并保留旧 Markdown；不得把半成品留作成功结果。
- MarkItDown 适合内容提取和语义结构保留。用户要求“版式一模一样”“可编辑排版复刻”时，应改用对应的 PDF、Word、PPT 或表格工具。
支持范围
脚本批量扫描以下常见扩展名：
.pdf、.docx、.pptx、.xlsx、.xls、.html、.htm、.csv、.json、.xml、.txt、.zip、.epub、.msg、.eml、.wav、.mp3、.jpg、.jpeg、.png、.gif、.tif、.tiff、.bmp
若 MarkItDown 新版本增加格式，可对单个文件直接尝试转换；目录批量扫描前再把新扩展名补入脚本白名单。