---
name: corpus-pipeline
description: >
  Corpus Pipeline — WorkBuddy 使用远端 MCP 批量处理出版物 PDF 的工作流指令。
  成员把 PDF 放入本机工作空间根目录后，只需输入“开始”，Agent 应自动上传、
  调用远端 MCP、运行 MinerU 管线、下载结果到本机 outputs/。
  触发词：开始、批量处理 PDF、语料管线、corpus pipeline、PDF 转 Markdown、
  MinerU、QC、metadata、review task、process_incoming_batch。
agent_created: true
---

# Corpus Pipeline WorkBuddy 工作流

目标体验：

```text
成员配置好 WorkBuddy MCP + Skill
  -> 打开一个装满 PDF 的本机文件夹作为 workspace
  -> 输入“开始”
  -> WorkBuddy 自动上传 PDF、调用远端 MCP、下载结果
  -> 本机 workspace/outputs/ 出现 Markdown、metadata、QC、review 档案
```

线上 MCP 端点：`https://corpus.phuyu.cloud/mcp`

受控上传端点：`https://corpus.phuyu.cloud/upload/pdf`

团队上传口令应配置为 WorkBuddy secret、连接器变量或本地安全配置。不要把口令写进 repo，也不要要求成员每次粘贴。

## 核心原则

远端 MCP 服务器不能直接读取成员电脑硬盘。WorkBuddy 必须在本机工作空间中完成“文件桥接”：

1. 只扫描当前 workspace 根目录的一层 PDF。
2. 将这些 PDF 通过受控上传端点送入远端 `corpus/incoming`。
3. 调用远端 MCP 的 `process_incoming_batch(mode="real")`。
4. 用返回的 export download URL 下载 ZIP。
5. 解压到当前 workspace 的 `outputs/`。
6. 向成员汇报摘要、失败项、人工复核项和本机输出路径。

对成员来说，MCP 是无感的；对 Agent 来说，MCP 是唯一允许推进服务端管线的接口。

## 连接验证

首次配置后，成员可以输入：

```text
检查连接
```

Agent 应调用 `batch_status()`，只返回：

```text
MCP 连接正常/异常
当前 total:
状态分布:
下一步:
```

不要在连接验证时处理 PDF。

## “开始”指令的标准行为

当成员在 WorkBuddy 输入：

```text
开始
```

Agent 必须执行以下流程。

### Step 1. 确认 workspace

确认当前 WorkBuddy workspace 是成员打开的 PDF 文件夹。

规则：
- 只读取 workspace 根目录下的 `*.pdf` / `*.PDF`。
- 不递归子目录。
- 不扫描桌面、下载目录、全盘或任意外部路径。
- 忽略隐藏文件和非 PDF。
- 如果根目录没有 PDF，提示成员把 PDF 放到当前 workspace 根目录后再输入“开始”。

### Step 2. 自动上传本机 PDF

对每个根目录 PDF：

```http
POST https://corpus.phuyu.cloud/upload/pdf?filename=<原文件名>
X-Corpus-Upload-Token: <团队口令>
Content-Type: application/pdf
```

上传成功后记录每个文件的：
- `status`
- `filename`
- `sha256`
- `staged_path`

同 hash 重复上传返回 `duplicate_already_staged` 时不算失败。

### Step 3. 调用远端 MCP 批处理

上传完成后调用：

```text
process_incoming_batch(mode="real", retry_failed=false, created_by="workbuddy")
```

这个工具会在远端完成：

```text
register_batch
  -> inspect_document
  -> 自动选择 MinerU profile
  -> MinerU conversion
  -> normalize_markdown
  -> extract_metadata
  -> run_qc
  -> create_review_task if needed
  -> export_batch
```

不要让成员手动调用这些子步骤；Agent 可以在内部调用和观察，但最终只给成员结果。

### Step 4. 下载结果回本机

从 `process_incoming_batch` 返回值中读取：

```text
export.download_url
export.filename
```

用团队口令下载：

```http
GET <export.download_url>
X-Corpus-Upload-Token: <团队口令>
```

将 ZIP 解压到当前 workspace：

```text
outputs/
  markdown/
  metadata/
  qc/
  review/
  MANIFEST.json
  README.md
```

如果本机已有 `outputs/`，可以覆盖同名导出文件，但不得删除成员自行放入的其他文件。

### Step 5. 汇报给成员

标准汇报格式：

```text
已完成

本机输出:
- Markdown: outputs/markdown/
- 复核档案: outputs/review/
- Metadata: outputs/metadata/
- QC: outputs/qc/

本批次摘要:
- uploaded:
- registered:
- processed:
- approved:
- review_required:
- failed:

需要人工复核:
- document_id:
- source_filename:
- review file:
- reason:

失败项:
- document_id:
- source_filename:
- error:
```

不要把整本 Markdown 原文贴到聊天中。

## 备用模式

如果 WorkBuddy 当前版本无法自动读取 workspace 文件或无法下载 ZIP：

1. 明确说明限制。
2. 使用网页上传入口作为备用：`https://corpus.phuyu.cloud/`。
3. 上传后仍调用 `process_incoming_batch(mode="real")`。
4. 如果不能自动下载，返回 export download URL 和说明。

备用模式是降级方案，不是默认成员流程。

## 允许的 MCP 工具

| 工具 | 用途 |
|---|---|
| `batch_status` | 验证连接、查看全量状态 |
| `process_incoming_batch` | WorkBuddy “开始”后的首选批处理工具 |
| `export_batch` | 只导出当前成果，不重跑转换 |
| `register_batch` | 扫描远端 `corpus/incoming` 并登记 |
| `run_pipeline` | 单文档端到端处理 |
| `list_documents` | 列出文档与状态 |
| `register_document` | 单文档登记 |
| `inspect_document` | 预检 PDF、判断 profile |
| `submit_mineru_job` | 提交 MinerU job |
| `get_job_status` | 查询 job 状态 |
| `get_artifacts` | 返回 artifact URI |
| `normalize_markdown` | 生成 clean.md |
| `extract_metadata` | 生成 metadata.json |
| `run_qc` | 生成 qc.json |
| `create_review_task` | 生成 review.json |

## 禁止事项

Agent 不得：
- 要求成员 SSH/scp 到服务器。
- 要求成员手动把 PDF 放到服务器目录。
- 扫描 workspace 根目录以外的本机路径。
- 递归扫描子目录，除非成员明确要求且项目负责人同意。
- 直接执行任意 shell 处理 PDF。
- 自由拼 MinerU 命令。
- 覆盖或删除 raw PDF。
- 无审计地批量重跑所有文档。
- 绕过 QC 直接 approved。
- 直接修改 metadata 或 DB。
- 把整本 Markdown 粘贴到聊天里代替本机输出文件。

## 人工复核触发条件

必须进入 review：
- metadata 缺 title、publisher、publication_year。
- metadata confidence 低于团队阈值。
- Markdown 为空、重复行异常、章节顺序明显错乱。
- 图片或表格数量与版面预期明显不符。
- OCR 质量不足。
- 成员或 Agent 无法判断。

不确定时，保留证据并创建 review task，不让 Agent 猜。