---
name: literature-processing-workflow
description: Manage a traceable workflow for modern-periodical, letter, and historical-source scans from PDF through PaddleOCR, template-backed Word proofreading, and optional research-layer outputs.
---

# 近代期刊文献处理工作流

面向近代期刊、书信与史料扫描件的 AI Skill 案例：将 PaddleOCR、模板化 Word、人工校对和古籍整理串成可追溯流程。此技能负责建档、交接、验证和停止条件；不取代各技能本身。

工作根目录：`<工作根目录>/任务/`。

## 固定目录与状态

每个任务均有以下目录，原 PDF 只复制到 `00_原始` 并设为只读：

```text
<任务>/
├── 00_原始/
├── 01_OCR/
├── 02_人工校对/
├── 03_研究成果/
├── 处理记录.md
└── 任务元数据.json
```

只使用下列状态：`待OCR`、`待确认文章清单`、`待人工校对`、`待古籍整理`、`研究完成`、`失败`。不得跳过人工校对而进入古籍整理。

运行本地辅助工具时使用：

```text
python3 scripts/workflow.py <命令>
```

## 入口一：处理新文献

当用户说“处理新文献：<PDF 路径>”时：

1. 运行 `new-single <PDF 路径>`；回报生成的任务目录。
2. 任务状态应为 `待OCR`。使用 PaddleOCR Dispatcher 的 `submit_paddleocr_job`，输入为 `00_原始` 中的 PDF；不得把令牌写入提示、文件或命令。
3. 记录返回的 job ID 至 `任务元数据.json` 与 `处理记录.md`。只在用户要求等待时调用等待工具；失败时改为 `失败`，不自动重投。
4. job 完成后，调用 PaddleOCR Dispatcher 的下载工具，目标目录必须是 `01_OCR`；确认 Markdown 已下载后运行 `record-ocr <任务目录> <job ID> <Markdown 路径>`，状态才会变为 `待人工校对`。
5. 将 OCR Markdown 转为 `02_人工校对/待校对.docx`：

```text
markdown-to-word <01_OCR 中的 Markdown> <任务>/02_人工校对/待校对.docx
verify-word <Markdown> <待校对.docx> <任务>/02_人工校对/Word校验.json
```

6. 用文档渲染器把待校对 Word 渲染成页面图片，逐页检查断页、表格、图片和页码。当前本机的无界面渲染器缺少 CJK 字体，因此它不能作为中文字符显示的验收依据；交付前仍须在本机 Word 中打开，人工确认中文字体与字形。若渲染或结构校验失败，停止并记录，不交给用户作为已通过的 Word。
7. 告知用户在 `02_人工校对` 中将人工修订后的文件保存为 **`校对定稿.docx`**。不自动运行断句、翻译或解读。

## 入口二：处理合集

当用户说“处理合集：<PDF 路径>”时，运行 `new-collection <PDF 路径>`。它只建立 `待确认_文章清单.md`，不提交 OCR。

待用户填写标题、起始页和终止页并明确确认后，运行 `split-collection <合集任务目录>`。该命令检查页码范围、重叠和总页数，为每篇建立只读的独立 PDF 与 `待OCR` 子任务。随后逐篇执行“处理新文献”的 OCR 与人工校对阶段；不得从 OCR 内容猜测文章边界。

## 入口三：提交校对定稿

当用户说“提交校对定稿：<任务目录>”时：

1. 运行 `extract-reviewed <任务目录>`，仅接受 `02_人工校对/校对定稿.docx`。
2. 生成 `校对定稿.md` 后状态为 `待古籍整理`。
3. 若文献不是古籍、文言或历史材料，只报告已完成 OCR 与人工校对，不自动进入古籍整理。

## 入口四：生成古籍整理稿

当用户明确说“生成古籍整理稿：<任务目录>”且状态为 `待古籍整理` 时：

1. 读取 `校对定稿.md`，调用 `guji-punctuate-translate-explain`，将完整结果保存为 `03_研究成果/古籍整理总稿.md`。
2. 先运行：

```text
validate-guji <古籍整理总稿.md> <任务>/03_研究成果/古籍整理校验.json
split-guji <古籍整理总稿.md> <任务>/03_研究成果
```

3. 分别把 `原文断句.md`、`全文翻译.md`、`简要解读.md`、`内容概括.md` 转为同名 `.docx`；每份都运行 `verify-word` 和逐页渲染检查。
4. 仅在四份 Word 全部通过后，运行 `finish-research <任务目录>` 将状态改为 `研究完成`。繁体断句仅添加标点与分段；简体中的校改必须加粗并写入校注。

## 失败与交接规则

- OCR API 未配置、提交失败、下载结果不存在、DOCX 结构失败或页面渲染异常：停止在当前步骤，记录具体原因，保留现有文件。无界面渲染中的中文方块属于当前环境字体限制，必须标记为“待 Word 人工字形确认”，不能误报为内容错误。
- Markdown 与 Word 文本签名不一致时，不能宣称文本完整；检查表格、图片与 Markdown 语法后再决定是否继续。
- 不覆盖原 PDF、OCR Markdown、待校对 Word 或校对定稿。生成新版本时使用新文件名并记录。
- OCR 转 Word 网页如由用户提供 URL 并验证可用，可以替换本技能的 `markdown-to-word` 命令；在验证输入、下载位置和版面结果前，不假定该网页可用。