docparse：实践指南

在项目中评估docparse，可以先看清用途边界：自适应文档解析工具：通过初步诊断，为每一层选择最优的解析器组合，并与Primary+Patch进行融合，自适应文档解析。从文档与演示交付的使用方式看，内容结构和版式在转换后容易走样是采用前必须回答的问题。先拿一份结构复杂的真实文档完成转换更稳妥；过程中要观察标题层级、表格图片、字体版式和可编辑性，失败也应能解释原因。我会把它列入经常交付正式文档或演示稿的团队的候选清单，而不是仅凭项目介绍直接纳入生产。

名称：docparse 描述：> 自适应文档解析工作流程。提前诊断文档以选择最佳的解析器组合， 与 Primary+Patch 方法有效融合，生成最高质量的单个降价。 触发条件： (1) 当您想要以最高质量解析文档时 (2) 当使用 /docparse 命令时 (3) 当尝试组合/融合多个解析器结果时 (4) 在 PDF、image、HWP、DOCX 等文档中。 提取文本时 元数据： 版本：“1.6.0”

docparse v3：自适应解析+Primary+Patch融合

提前诊断文档 → 选择最佳解析器组合 → 使用 Primary+Patch Fusion 生成高效、高质量的 Markdown。 LlamaParse v2（代理层）是中型~超大主级。

사용법

/docparse                       # 현재 디렉토리에서 파일 자동 탐색
/docparse input.pdf             # 파일 지정
/docparse input.pdf --lang en   # 비한국어 문서

参数解析：分隔空格→提取--lang <값>作为语言代码（默认ko）→剩余第一个token作为文件路径→如果没有路径，则自动在当前目录（Glob）中搜索支持的扩展。

패키지 구조

~/.claude/skills/docparse 符号链接指向的一个文件夹就是整个技能。运行时，该路径名为<스킬루트>。文件夹外的准备工作（pip包、Java、poppler以及转换HWP的hwpx-automation技巧）由README安装部分指导，每个解析器的准备状态由scripts/check_env.py检查。

파서 ( parsers/ )

스크립트 ( scripts/ )

评估工具由parser-eval技能管辖：对解析器进行比较和评分，并将判断留在账本中，score_transcription.py（CER/WER与原始相比的定量评分）和diff_fidelity.py（LLM ↔ OCR发散标记→视觉阅读目标）就在该技能中。 ⚠ parser-eval 是作者的本地技能，因此它不随 docparse 一起分发，并且并不存在于所有机器上 — 如果不存在，则使用 tier-rules 中指定的替代路径完成编写两个脚本的步骤。原来的解析方法和提示是docparse。

참조 ( references/ )

파서별 특성 한눈 비교

실행 워크플로우

步骤0：环境检查（首次运行或怀疑密钥/依赖项时）

python "<스킬루트>/scripts/check_env.py"

每个解析器的依赖包·API 一次性打印密钥准备状态和密钥发行 URL（只读，不安装任何东西）。如果这是第一个克隆环境或特定解析器由于缺少密钥或软件包而失败，请首先运行它以检查要安装和配置的内容。免费的本地解析器（hwpx_local·pdfplumber·xlsx_local·docx_local·opendataloader）无需密钥即可直接使用。并非每个任务都需要此过程，因此环境准备好后可以跳过此过程。

步骤0.5：浏览编辑源代码（必须在解析PDF之前完成）

如果您收到要打印或分发的 PDF，首先在下一个文件夹、共享驱动器或订购地点中查找同一文档 (HWP·HWPX·DOCX·XLSX) 的原始编辑。 如果是这样，请将文件发送到确定性层(hwpx·docx·xlsx)并将PDF发送到页面。仅用于编号和比较目的。在编辑后的原稿中，合并单元格、表格边框、格式（删除线、字体颜色）和标题级别均在 XML 中指定，因此从结构上消除了 LLM 解析器的三大错误（合并单元格制造、列拥挤和页面边框截断）。询问您是否有原件的成本就是一次答复。

第一步：预诊断

python "<스킬루트>/scripts/assess_document.py" "<파일경로>"

检查 JSON 中的 tier、pages、has_text_layer、table_hint、format → 确定每层的解析器策略。 table_hint: true 表示已检测到矢量规则网格，如果存在文本层，则 pdfplumber 出现在 recommended_parsers 的开头（步骤 2 第 0 层）。 没有文本层（扫描副本），tier 比页数层高一级（12 页扫描副本 → 中）。 recommended_parsers 是步骤 2 基本层表加上三处更正：扫描副本排除 ODL 并添加 Upstage·Mistral（诊断层大或更高 = 16 页或更多）；如果 --lang 不是 ko，则添加 Mistral； docx·xlsx 在本地解析器之后添加了一个升级候选者（upstage·llamaparse）。由于hwp、pptx、images为表外格式，建议使用Upstage系列（HWP转换为references/hwpx.md后输入）。如果表格或更正发生变化，脚本也会发生变化。

signals 仅包含可确定性测量的内容：text_pages（示例页面中包含文本的页数。示例是前 3 页 + 分布在整个文档中的最多 12 页）、pua_per_10k（文本层每 10,000 个字符的 PUA 代码点。如果 ≥100，则公式试纸规则），latin_ratio（字符之间的拉丁比例。Mistral 主要考虑条件如果≥0.5）。 rule_hints 是 tier-rules 子句的名称（或子句要点的一行），仅由诊断确定。为空并不意味着“不适用”，而是意味着“尚有条款无法诊断确定”。手写、组合抄写、合并单元格、人口统计交叉表等由座席直接从第2步修正规则列表中判断。

第 2 步：选择自适应解析器

기본 티어 표

页数从小到大是根据文本层所在的PDF计算的。扫描遵循步骤 1 中的较高层和层规则的“无文本层”部分。

第 0 层（决定论优先级门）：table_hint: true（矢量规则网格）+ has_text_layer: true，并且如果目标输出是表格数据而不是散文（管理文档，例如时间表、公告牌、统计表和每周学习指南），则页数层优先。尝试 pdfplumber_parse.py（本地、免费、非 LLM）。这是因为当来源明确时（绘制的网格+嵌入的字母），LLM 的推论是纯粹的下行风险。 Grid↔坐标自验证和PyMuPDF独立双引擎交叉投票机器比较单元位置。

• PASS：按原样采用 (_fused_v3_pdfplumber.md) 并省略步骤 5 和 6（完整性门/交叉验证）。步骤7 进行最终检查。
• 警告（单元格不匹配、未分配的单词、合并可疑单元格、跨引擎不匹配、未检测到表）：解析器不会创建输出文件，因此将其提升为基本层表。
• 您可以通过选择加入--strategy text来尝试无规则排序表，PASS的含义最多为“单词保存+2引擎结构收敛”。
• 验证原理和应用边界见references/tier-rules.md的“格线格式表PDF”部分。

HWPX·HWP：如果format是hwpx·hwp，则读取references/hwpx.md（hwpx_local优先级基础，确定性强化，草案HWP +打印PDF 混合、后级交叉条件、发动机故障处理、HWP 转换）。

Office 本地层 (XLSX·DOCX)：XLSX·DOCX 是一种在文件 XML 中指定单元格值、合并范围和标题样式的格式，因此按原样应用第 0 层哲学（如果来源明确，LLM 推理存在下行风险）。先写xlsx_local_parse.py（openpyxl +原始XML值多重集交叉验证）和docx_local_parse.py（python-docx + document.xml全回忆比较），如果PASS就照原样（_fused_v3_xlsxlocal.md/_fused_v3_docxlocal.md，步骤5和6省略，步骤7进行最终检查）。如果被拒绝（验证不匹配、文本框、脚注、嵌套表），则升级为 Upstage·LlamaParse。基础和边界在层级规则「XLSX·DOCX」部分。

ODT：没有本地解析器，只有一个已确认接受的云端解析器，OpenAI，因此不存在交叉验证伙伴。而是将原始content.xml的非空终端text:p段落进行空间归一化，并与输出完全进行比较（段落内容、表格单元格对应、阅读顺序，甚至重复），如果PASS，则采用为_fused_v3_openai.md。此排序规则取代了步骤 5 和 6，并且步骤 9a 中的“第三类型解析器”请求不适用（如果需要视觉阅读，请将 PDF 转换为 LibreOffice，然后阅读）。将 dc:title 通知合并到第一行、用 - 填充空单元格以及支付表的重新排列不会通过排序规则捕获，因此请参阅步骤 7。基础和边界是分层规则“非 PDF 文档格式的解析器选择”行 ODT。

初级选择原则：选择缺陷少且无法自动化纠正的解析器作为初级。 LlamaParse v2 最适合中型到大型（目录组织良好、表格列准确、0 噪音、LaTeX 0）。当信用不足时，回退到 ODL 主要 + 后台交叉验证（当有文本层时。扫描副本具有分层规则“无文本层”）。 Mistral ocr-4 生成标题结构，是 textPDF 后备的主要候选者，但噪声和 OCR 字符漂移的后处理是前提（层规则“Mistral ocr-4 标题生成”）。

Small Tier Gemini Note（最初的 Gemini 规则。其他文档中的 Gemini 描述遵循本节）：gemini-flash-latest 是指向思维模型（由 check-stack-updates 监控的生成）的服务器别名。当思维开启时，长文本（≳20p）进入摘要而不是转录，悄悄地丢弃正文并将其伪装成完整的文档（基于gotchas.md）。为了防止这种情况，gemini_parse.py被忠实地转录为默认thinking_budget=0 + max_output_tokens=65536。 请勿将 Gemini 用作长主（仅限小 ≤15p）。但如果关闭思考，手写复选框的读取就会变弱，所以对于复选框、韩文名字等需要精确读取的辅助补丁，将其打开，并用gemini_parse.py <파일> --thinking单独调用。

보정 규칙 (티어 결정 후 적용)

这就是references/tier-rules.md的整个判断部分。 一个文档同时卡在多个子句中是正常的，冲突可以通过层级规则开头的“规则优先级”解决（格式门 > 禁止 > 添加必填 > 推荐）。从上到下浏览下面的列表 为每个条款勾选“适用/不适用”，并仅写出第 8 步摘要中适用的条款（未列出的条款必须已被判断为不适用，而不是不被判断）。 assess_document.py的rule_hints自动捕获的子句用◇标记。

• ◇ 格线格式表 PDF + 目标输出为表数据（第 0 层：pdfplumber 确定性优先）
• XLSX·DOCX（Office 本地确定性解析器）- 默认层表中的对应行
• ◇ 无文本层（扫描/图像PDF：诊断向上移动一页层）。 ◇ 可疑部分扫描（仅部分样本为文字）
• ◇ 英文比例≥50%/标准化表格（Mistral Primary考虑条件）+Mistral ocr-4标题生成（fallback Primary）
• Mistral附加条件（主要↔次要不匹配/非韩文/扫描16页以上）+ ◇非韩文文件条件的细化（--lang≠ko）
• 信用不足时的回退（ODL Primary + Upstage）
• ◇ 采用ODL Primary之前验证车身编号（即使有文字层）
• 可打印小册子 PDF 中跨多个页面的表格/合并单元格
• 学术/研究报告（v2 标题层次结构不稳定）
• 扫描文件+表格中的数字数据（申请表、表格、统计表）
• 扫描件+打印表格（病历检查结果等）
• 打印多人口统计交叉表（仅图像：首选 Google Vision）
• 同一表格多份的合并副本 PDF
• 专注于手写的扫描文档（忠实转录至关重要：4 级管道、Vision → Claude 级联、身份字段、学生答题纸组合）
• 试卷/试卷/评价试卷（可选文字重点）+ ◇ 含公式试卷（PUA 密度≥100：LlamaParse v2 仅初级）
• has_text_layer：true，但只有pdftotext不能选择韩文（禁止扫描误判）
• ◇ ≤20p小尺寸PDF（读取视觉渲染=groundtruth）
• 非PDF格式（PPTX·图像·兼容性矩阵。HWP·HWPX程序为references/hwpx.md）
• 医疗记录、法律文件、合同（准确性关键、页面层无关、三向交叉：“无文本层”部分末尾。如果采用格式门 PASS，则不适用：“规则优先级”）

第 3 步：运行解析器

仅并行执行选定的解析器。 xlarge 的时间限制为 600 秒，其他为 300 秒。使用 < /dev/null 阻止交互式提示。如果--lang不是ko，它也被传递到llamaparse_parse.py(--lang <코드>)·gvision_parse.py(--lang <코드>,ko逗号列表)。

执行契约：仅当创建输出文件时，所有解析器退出代码0。错误/空结果/验证失败/部分结果（Gemini 令牌截断、Upstage 放置缺失、Mistral 页数不匹配、Vision 页面调用失败/上一页结果为空）以 1 结尾且没有输出，并且在执行开始时，首先删除以前的同名输出。因此，在继续步骤 4 之前，检查退出代码和输出文件是否存在。如果退出代码非零并且文件存在，则该文件不属于本次运行。

下面的示例基于 bash (Git Bash·Linux)。

• macOS：没有 timeout 命令，因此如果按原样键入它，将导致退出 127，并且解析器甚至不会运行。如果coreutils中有gtimeout，则将其替换为timeout。如果没有，则不运行timeout N，然后手动关闭超过时间限制的解析器。
• PowerShell：$null，因为没有 暂停·< /dev/null·&·等待 | python ...关闭标准输入 Start-Job/Start-Process -Wait 或者用顺序执行代替。

# medium 티어 예
timeout 300 python <스킬루트>/parsers/llamaparse_parse.py "<파일경로>" < /dev/null &
timeout 300 python <스킬루트>/parsers/upstage_parse.py "<파일경로>" < /dev/null &
wait

# xlarge 티어 예
timeout 600 python <스킬루트>/parsers/llamaparse_parse.py "<파일경로>" < /dev/null &
timeout 300 python <스킬루트>/parsers/opendataloader_parse.py "<파일경로>" < /dev/null &
wait

# t0 티어 예 (괘선 표 PDF, 로컬·무료·1초 내외. PASS/경고를 표준 출력으로 보고)
timeout 300 python <스킬루트>/parsers/pdfplumber_parse.py "<파일경로>" < /dev/null
# 괘선 없는 정렬 표(opt-in): text 전략 + 2엔진 교차 투표
timeout 300 python <스킬루트>/parsers/pdfplumber_parse.py "<파일경로>" --strategy text < /dev/null

# xlsx·docx 티어 예 (로컬·무료. PASS/거부를 표준 출력으로 보고)
timeout 300 python <스킬루트>/parsers/xlsx_local_parse.py "<파일.xlsx>" < /dev/null
timeout 300 python <스킬루트>/parsers/docx_local_parse.py "<파일.docx>" < /dev/null

# hwpx 티어 예 (로컬·무료 우선; 긴 지문이 셀 안에 있으면 --cell-br)
timeout 300 python <스킬루트>/parsers/hwpx_local_parse.py "<파일.hwpx>" < /dev/null
# 이미지 경고·recall 경고가 뜨거나 레이아웃이 중요하면 Upstage로 교차검증
timeout 300 python <스킬루트>/parsers/upstage_parse.py "<파일.hwpx>" < /dev/null

辅助功能优先解析（残疾人和视障用户文档的信息材料）添加了 --instructions <스킬루트>/references/custom-prompts/accessible.txt 并注入 v2 agentic_options.custom_prompt。 只有一个选项名称，--instructions。对于其他名称（--custom-prompt-file、--prompt 等），参数解析器将该值识别为第二个输入文件，并将accessible.txt 单独发送到LlamaParse，因此实际上并未应用custom_prompt。

第 4 步：创建主要基地

最终输出文件名规则（文件名揭示了哪个解析器被集成到 fused 中）：

• 最终融合的文件为<파일명>_fused_v3_<파서조합>.md。
• <파서조합> 只列出其内容实际上反映在该结果中的解析器，从 Primary 开始，并以 + 继续。不包括仅执行简单比较且不合并文本的解析器（因为文件名是“合并内容”的记录）。
• 解析器标记相当于各个输出后缀： llamaparse·upstage·gemini·mistral·opendataloader·hwpxlocal·pdfplumber·xlsxlocal·docxlocal·corepin·gvision·cohere·openai.
• 示例：LlamaParse 如果Upstage标题·元数据修补到Primary，则为_fused_v3_llamaparse+upstage.md，如果仅采用Mistral，则为_fused_v3_mistral.md，如果仅采用hwpx_local，则为_fused_v3_hwpxlocal.md。
• 创建主库时，仅添加主解析器名称，并在每次实际反映步骤 6 中辅助解析器的内容时，通过在文件名中添加 +<파서> 来重命名它。

LlamaParse v2 主要

cp "<파일명>_llamaparse.md" "<파일명>_fused_v3_llamaparse.md"

通过简单地组织图像占位符，可以立即将基于文本的文档（法律、论文、报告）进行融合。 可打印的小册子、图表丰富的文档（信息图表、章节封面、标题内嵌图标等）应用 references/postprocess.md v2 的 7 种后处理模式。

⚠ 不要简单地去掉图片占位符：即使在学术报告中，也混杂着1-2个文本信息图。首先用generate_alt_text.py创建一个富含韩语的alt，然后去掉封面、标志和设计标签，以(이미지: )的形式保持文本信息图内嵌。

python <스킬루트>/scripts/generate_alt_text.py \
    --pdf "<파일>.pdf" --markdown "<파일>_llamaparse.md" \
    --output "<파일>_with_alt.md" --map "_work-docparse/<파일>_alt_map.json"

检查创建的 alt 并仅将正文图内嵌插入 fused 中。标志和徽标被删除。

ODL 主要（后备）

python <스킬루트>/scripts/normalize_odl.py "" "<파일명>_fused_v3_opendataloader.md"

自动处理项详情请参见references/postprocess.md。由于图像占位符不会被删除，而是保留为 (이미지: alt)/(이미지) 标记，因此在步骤 7 中使用与上面的 LlamaParse 项目相同的标准对其进行组织（保留人体图并删除装饰）。

⚠ ODL 采用前需要进行主要正文编号验证（即使是文本层）：当出版物嵌入字体的字形映射被破坏并且 ODL 省略所有正文编号/特殊字符时，就会存在这种情况。立即将正文第一段中的 1-2 个数字与 v2/Upstage 进行比较。如果丢失，则丢弃 ODL Primary。详细信息：references/tier-rules.md。

第 5 步：数据完整性门

必须在选择Primary之后、LLM交叉验证之前立即执行。 在表格中有数字数据的文档中不能省略。 但是，在按原样采用局部确定性解析器（Tier 0·XLSX·DOCX·HWPX）的PASS并且ODT的content.xml完全比较PASS的情况下，不适用，因为验证替换了该门。

1. 算术验证：验证所有表中数字行的总和（개별항목 합 == 소계等）。成本0。
2. 当发现不匹配时：辅助解析器提取相应的表号并执行逐个单元格的匹配。即使格式混乱，也可以提取数值本身（“格式质量≠数据准确性”）。
3. 单元格位置比较（最重要，不能省略）：始终执行，无论算术验证如何。即使总数是正确的，类别也可能会颠倒。如果2个解析器同意，则采用；如果存在分歧，则第三个解析器是多数票。 对于扫描手写格式的表号，Gemini·LlamaParse v2 不参与投票，仅使用Upstage·Mistral（列移动记录，层级规则“扫描文档+表中的数字数据”）。如果将两者分开，第三个表就是对应方的时间读数。
4. 如果无法解决差异：运行额外的解析器进行 3 路交叉验证（Mistral。视觉阅读，如果已投票）。

⚠ 仅通过算术验证无法检测到热运动。 步骤 5.3 单元位置比较是唯一的防线。

第6步：LLM交叉验证和修补

6a。标题间隙补丁

python <스킬루트>/scripts/compare_outputs.py "" ""

仅从 Upstage 读取有间隙的标题部分并将其插入到编辑中。

6b.文本/数字交叉验证

将当前融合文件 (_fused_v3_<파서조합>.md) 的 3 到 5 个代表性部分（开始、中间、表密集部分和结束）与辅助解析器输出进行比较。如果辅助解析器更准确，则替换它，如果两者不同且无法确定，则添加 Mistral（如果您已经听过，请目视阅读）。 LlamaParse v2 元数据遗漏倾向（打印机、电子签名者、原始验证完成等管理元数据）在Upstage中补充。 如果辅助解析器的文本实际上已被反映（替换/修补），则通过将解析器添加为 +<파서> 来重命名文件名 <파서조합>（步骤 4 命名约定）。

6c。表数据一致性

对于表格中包含数字数据的文档来说是必需的。如果步骤 5 中的一种情况存在差异，则通过额外执行 Mistral 来进行 3 路交叉（如果您已经听过，请目视阅读）。

第 7 步：最终噪声清除

最终融合文件的最终检查 (_fused_v3_<파서조합>.md)。 不要随意更正原文中的错别字：LLM解析器悄悄更正的符号（「垃圾→垃圾桶」「构造→构造」）通过三字比对返回原文，如果需要更正，则通过apply_corrections.py的更正列表CSV。 OCR 伪影（一、□）、页面边框孤立线、重复标题、幻觉文本、图像占位符残留、后台 OCR 字段、HTML 复选框伪影、重复页脚等。有关详细清单，请参阅 references/postprocess.md 步骤 7 部分。

第 8 步：打印并整理

原理：最终结果（_fused_v3_<파서조합>.md）保留在工作文件夹中，而到目前为止的副产品（单独的解析器输出）则隔离在 _work-docparse/ 子文件夹中。文件夹名称揭示出处（docparse）+性质（工作=中间工作），后缀规则与hwpx-automation技能的_work-hwpx-automation/统一。

1. 将其保存到工作文件夹中，名称为 [파일명]_fused_v3_<파서조합>.md（有关解析器组合命名约定，请参阅步骤 4）。 在保存之前，检查文件名中的解析器列表是否与实际反映内容的解析器匹配（我只使用了 Primary 并反映了 secondary 解析器，以免省略重命名）。
2. 对话框中的摘要输出：页数·层·使用的解析器·解析器失败/超时（退出代码）·应用的校正规则子句名称（基于步骤2列表）·融合方法·自动校正项目数·LLM交叉验证结果·最终行数·表数+步骤9的两个结果（执行附加交叉验证/不必要和理由，规则文件中的反映历史）。
3. 将单个解析器输出移至 _work-docparse/ 子文件夹：

mkdir -p "<파일 디렉토리>/_work-docparse"
mv "<파일명>_llamaparse.md" "<파일명>_upstage.md" "<파일 디렉토리>/_work-docparse/"
# 如果使用，_gemini.md、_mistral.md、_opendataloader.md、_hwpxlocal.md、_pdfplumber.md、
# 同时移动 _xlsxlocal.md、_docxlocal.md、_gvision.md、_corepin.md、_cohere.md、_openai.md、_with_alt.md
# (로컬 티어 단독 채택이면 그 출력을 _fused_v3_<토큰>.md로 채택)

步骤9：后期处理：额外的交叉验证回顾+学习反思（不可省略）

工作并没有随着融合输出而结束。在每次解析操作结束时，都会执行以下两个过程，并将结果逐行包含在步骤 8 的摘要输出中。

9a。审查是否需要额外的解析器进行交叉验证。 如果出现以下任一情况，则执行额外的解析器（主要是 Mistral，视情况而定，ODL·Gemini），并由三方投票得出结论。如果不适用，请在摘要中注明“额外的交叉验证：不需要”并说明理由。

9b.反思学习。 如果通过验证发现新的可重用模式，则立即反映在相应的规则文档中，防止下一个任务重复相同的试错：

1. 发现更改层选择/解析器策略 → references/tier-rules.md 更新 + 反映了 SKILL.md 解析器比较表。
2. 后处理/噪声清除模式 → references/postprocess.md。
3. 陷阱/错误处理 → references/gotchas.md。

根据发现的规模，向现有规则或案例添加新规则或案例。影响用户的更改在 CHANGELOG.md 中记录为日期条目，并在 SKILL.md metadata.version 中引发（操作更改次要，表达式补丁）。

환경 변수

变量列表的原始版本是.env.example，就绪检查是scripts/check_env.py（步骤0）。

변경 이력

CHANGELOG.md（存储库根）