---
name: corpus-pipeline
description: >
  Corpus Pipeline — 批量处理出版物 PDF 的 MCP 工作流指令。
  当用户需要批量转换、处理、清洗、QC 质检 PDF 文件为结构化 Markdown 时载入此指令。
  触发词：批量处理 PDF、语料管线、corpus pipeline、PDF 转 Markdown、出版物数字化、
  MinerU 转换、PDF QC、公版书处理、批量登记文档、run_pipeline。
agent_created: true
---

# Corpus Pipeline — 批量 PDF 处理工作流

此文件是一份 **Agent 工作流指令**，适用于任何已接入 `corpus-pipeline` MCP 服务器的 AI Agent。
Agent 仅通过 MCP 调用 13 个受控工具，不直接执行 shell、不碰任意文件夹、不手拼 MinerU 命令。

**多平台通用** — 可直接作为以下工具的指令文件：
- WorkBuddy：放到 `~/.workbuddy/skills/corpus-pipeline/SKILL.md`
- Codex / Claude Code：放到项目根目录 `CLAUDE.md` 或 `.codex/instructions.md`
- 任意 Agent：直接粘贴本文内容作为系统提示词

## 前置条件

确认当前 Agent 会话已接入 `corpus-pipeline` MCP 服务器。
线上端点：`https://corpus.phuyu.cloud/mcp`（Streamable HTTP）。

验证方法：让 Agent 调用 `list_documents` 或 `batch_status`，返回 JSON 即说明已接入。

## 批量处理标准流程

用户将 PDF 文件放入一个目录后，对 Agent 说：

> 请批量处理 /path/to/pdfs 目录下的全部 PDF。
> 先调用 register_batch 登记新文件，
> 再对每个新登记的 document_id 调用 run_pipeline（profile=baseline_auto_v1），
> 最后用 batch_status 汇总全量结果，把需要人工复核的文档列出来。

Agent 按以下顺序执行：

### Step 1 — 批量登记

调用 `register_batch(source_dir="/path/to/pdfs")`。
自动扫描目录中所有 `.pdf` 文件，为每个分配 `pub_NNNNNN` 格式的稳定 ID，
计算 SHA256，记录 rights_status。已登记的自动跳过。

### Step 2 — 全量概览

调用 `batch_status()`。查看总文档数、各状态分布、`next_actions` 建议。

### Step 3 — 逐文档运行管线

对每个状态为 `registered` 的文档，调用：
```
run_pipeline(document_id="pub_000XXX", profile="baseline_auto_v1", mode="mock")
```

内部自动走完 inspect → mineru → normalize → metadata → QC 全流程。
- `mode="mock"` 测试验证（毫秒级），`mode="real"` 生产环境（需 MinerU 引擎）
- profile：`baseline_auto_v1` / `ocr_scan_v1` / `debug_page_range_v1`

### Step 4 — 汇总与复核

再次调用 `batch_status()` 确认全局结果。对 `review_required` 文档生成人工复核清单。

## 核心约束（Hard Limits）

**绝对禁止：**
- "直接进服务器跑命令" / "覆盖旧 PDF" / "批量重跑" / "改 metadata 数据库"
- Agent 不直接执行 shell、不自由拼 MinerU 命令、不覆盖 raw PDF

**正确做法：**
- "通过 MCP 查看 document_id 的状态"
- "用 inspect_document 判断 profile"
- "为缺失字段创建 review task"

**出错时：** 保留 job_id/error/logs，只重跑失败阶段，不删旧 artifact。

## 全部 13 个 MCP 工具

| 工具 | 类型 | 用途 |
|---|---|---|
| `batch_status` | batch | 全量进度概览 + 智能建议 |
| `register_batch` | batch | 扫描目录批量登记 PDF |
| `run_pipeline` | batch | 端到端自动走完全流程 |
| `list_documents` | core | 列出队列中所有文档及状态 |
| `register_document` | core | 单文档登记，分配稳定 ID |
| `inspect_document` | core | 预检页数、文本层、扫描件标记 |
| `submit_mineru_job` | core | 提交 MinerU 转换作业 |
| `get_job_status` | core | 查看作业状态 |
| `get_artifacts` | core | 获取产物 URI 清单 |
| `normalize_markdown` | core | 生成 clean.md |
| `extract_metadata` | core | 提取 title / publisher / year |
| `run_qc` | core | QC 质检 |
| `create_review_task` | core | 创建人工复核任务 |

## 何时创建人工复核

- metadata 缺 title、publisher、publication_year，或 confidence 低于阈值
- Markdown 为空、重复行比例异常、双栏顺序混乱
- 图片、表格数量与版面预期明显不符，OCR 质量不足
- 成员无法判断时，不让 Agent 猜结论

## 交付清单

- document_id 和 source hash 已记录
- MinerU profile 和 job_id 已记录
- clean.md、metadata.json、qc.json 已生成
- review_required 项目已有 review task
- 没有绕过 QC 直接 approved