文档 / 快速开始
快速开始
三种用法，同一套转换逻辑：终端里敲命令、图形界面拖文件、起一个常驻服务盯住文件夹。 加上给 Agent 用的 MCP，一共四个入口。
第一次转换#
把文件放进 raw/，然后不带参数直接跑——它会列出目录里的文件让你按编号挑：
$ morsel # 也可以直接给路径，或者从访达把文件/文件夹拖进终端 $ morsel 报告.pdf $ morsel ~/Documents/合同/
产物默认进 output/<文件名>/，一个文件一个子目录，同名文件不会互相覆盖，
提取出来的图片也有地方归拢。默认输出 Markdown 和 JSON 两种格式。
输入与输出#
| 输入 | 页的含义 | 说明 |
|---|---|---|
| 物理页 | 主路径，版面分析最完整：标题层级、表格、坐标、字号 | |
| .docx | 全文算第 1 页 | 标题层级、列表、表格都保留 |
| .xlsx | 每个工作表一页 | 读公式的缓存值 |
| .pptx | 每张幻灯片一页 | 含演讲者备注 |
| .html / .htm | 全文算第 1 页 | 标准库解析，零额外依赖；脚本与样式丢弃 |
| 图片 | 每帧一页 | png jpg tiff bmp webp gif；需 OCR 才能出文字 |
输出有五种：markdown、json、html、text，
以及 pdf——最后这个是标注版 PDF，把识别出的每个区块用彩色框标回原文，
用来检查版面识别准不准。
$ morsel 报告.pdf -f markdown,json,text $ morsel 报告.pdf --pages 1,3,5-7 # 只转指定页 $ morsel 加密的.pdf -p 密码
常用选项#
- --better-tables
- 增强表格识别。默认靠边框找表格，无边框表格需要开这个
- --images
off/embedded/external（默认）。external 能稳定导出图片文件- --page-markers
- 在 Markdown / 文本里插入分页标记，方便引用溯源
- --sanitize
- 把邮箱、电话、身份证、信用卡、IP 换成占位符
- --header-footer
- 保留页眉页脚（默认丢弃）
- --keep-all-content
- 关闭内容过滤。怀疑有内容缺失时用它把页外和极小的文字也找回来
常用组合可以写进项目根目录的 config.toml 当默认值。
规则很简单：配置只改默认值，命令行显式传的参数永远优先。
写错的键会给出提示并忽略，不会中断运行。
批量与长跑#
$ morsel ~/合同/ --jobs 4 # 四个进程并发 $ morsel ~/合同/ --force # 不跳过，全部重转 $ morsel --watch ~/Dropbox/收件 # 常驻监听，新文件自动转
- 断点续传默认开着。成功记录写进输出目录的清单文件，记的是源文件的修改时间、 大小和这次用的选项签名。源文件改了、或者换了输出格式和参数，都会自动重转。 每成功一个就落盘，中途断电不丢进度。
- 失败的文件不记入清单，下次自然重试。
- 每批生成一份
report.csv：状态、页数、产物数、耗时、是否走了 OCR、 失败原因。用 utf-8-sig 编码，Excel 打开中文不乱码。 - 监听模式会等文件稳定：连续两轮大小和修改时间都没变才转， 避免转到还在拷贝中的半截文件——对网盘同步目录尤其重要。
面向 AI 的加工#
$ morsel 年报.pdf --rag-chunks --chunk-size 400 $ morsel 年报.pdf --export-tables $ morsel ~/资料/ --merge $ morsel 年报.pdf --qa
- RAG 分块
- 按标题层级 + token 预算切块，输出一行一块的
.chunks.jsonl，每块带页码范围和标题路径。标题处开新块，太小的小节自动与后文合并，正文超预算按行、按句逐级切开 - 表格导出
- 每个表格单独一个 CSV，文件名带页码；跨行跨列的单元格填在左上角锚点
- 多文档合并
- 本批的 Markdown 合成一份带可点目录的
merged.md，每份文档占一个一级标题 - 质量自检
- 生成标注版 PDF（标题蓝、正文绿）加一份逐页统计 CSV，标出空白页、疑似扫描页和低密度页，并在日志里报「N/M 页疑似需复核」
分块和表格导出都基于 JSON 结构树。没选 json 输出时会自动补转一份。
扫描件与 OCR#
OCR 默认是 auto：每个文件先探测文字密度，只有疑似扫描件才走 OCR——
OCR 比普通转换慢不少，auto 让你只在必要时付这个代价。
也可以 --ocr off 完全关掉，或 --ocr force 全部强制。
OCR 服务没启动时不会报一堆连接错误，而是明确告诉你怎么启动，并把文件降级成普通模式转换。 安装方式见下载页。
图形界面与 Web 服务#
- 图形界面：拖文件进去、勾选项、点转换。转换跑在后台线程，界面不卡， 进度实时；单个文件失败不中断整批。
- Web 常驻服务：把「监听文件夹」和一个本机网页界面合在一起，适合挂在后台长期跑。 浏览器里上传、看日志、下载产物。默认只绑本机，且没有访问控制—— 别暴露到不可信网络。