Corpus Pipeline | WorkBuddy MCP 批量处理工作流

Quick Start

快速开始 — 工作空间里放 PDF，然后输入"开始"

远端 MCP 不能主动读取成员电脑硬盘；WorkBuddy 根据 Skill 在本机 workspace 根目录读取 PDF，自动上传到受控 staging，再调用远端 MCP 批处理，最后把导出包解压回本机 outputs/。

1

配置一次

安装 WorkBuddy Skill，添加 Streamable HTTP MCP：https://corpus.phuyu.cloud/mcp，并配置团队上传口令。

2

打开文件夹

把待加工 PDF 全部放在一个本机文件夹根目录，用 WorkBuddy 把这个文件夹作为 workspace 打开。

3

输入开始

WorkBuddy 扫描根目录 PDF，自动上传，调用 process_incoming_batch，无需成员手动操作 MCP。

4

查看 outputs

处理完成后，本机出现 outputs/markdown、outputs/review、outputs/metadata、outputs/qc。

开始

Fallback Intake

备用：网页手动上传到受控 staging

默认应让 WorkBuddy 自动完成上传。只有当前客户端不能读取 workspace 或不能自动发 HTTP 请求时，才使用这个网页表单作为备用入口。

1

接 MCP

在 WorkBuddy 里添加远端 Streamable HTTP MCP：https://corpus.phuyu.cloud/mcp。

2

加载 Skill

安装团队 Skill，让 WorkBuddy 知道"开始"代表上传、处理、导出和下载，不需要成员记工具名。

3

放 PDF

PDF 放在 workspace 根目录；WorkBuddy 只读取这一层，不递归、不扫桌面或下载目录。

4

拿结果

远端导出的 ZIP 会被 WorkBuddy 下载并解压到本机 outputs/。

Setup

接入指南 — 从 Agent 怎么接 MCP 开始

Step 0 · 确认连接

线上服务器已部署在 https://corpus.phuyu.cloud/mcp（健康检查 /health）。支持远程 MCP 的客户端选择 Streamable HTTP；只支持本地 stdio 的客户端请下载本地服务器包。

WorkBuddy

图形界面：连接器 → 管理连接器 → 自定义连接器 → 配置 MCP，粘贴如下 JSON。保存后配置团队上传口令为 secret，新开 Agent 会话并调用 batch_status 验证。

{
  "mcpServers": {
    "corpus-pipeline": {
      "type": "streamable-http",
      "url": "https://corpus.phuyu.cloud/mcp"
    }
  }
}

如果 WorkBuddy 使用文件配置，放入配置包里的 workbuddy.mcp.json，再按客户端要求重启。

Codex（桌面版 / CLI）

Codex 版本差异较大。优先在设置里添加远程 MCP；如果使用 TOML 配置，可参考配置包中的模板：

[mcp_servers.corpus-pipeline]
transport = "streamable-http"
url = "https://corpus.phuyu.cloud/mcp"
enabled = true

如果当前 Codex 只支持本地 stdio MCP，下载本地服务器包后用 python -m mcp_server.server 作为本地命令。

连接成功的判断标准不是"配置文件存在"，而是 Agent 能实际调用 batch_status，并返回文档数量、状态分布、next_actions。

工作流指令 — 让 Agent 按团队流程做事

MCP 提供远端处理工具，Skill 负责让 WorkBuddy 理解"开始"的完整含义：只读当前 workspace 根目录 PDF、自动上传、调用批处理、下载 export ZIP 并解压到本机 outputs。

通用 Markdown 指令

下载 Agent 工作流指令
作为 Skill、项目指令或系统提示词加载

WorkBuddy 目录包

下载 WorkBuddy Skill 包。如果客户端支持导入 zip，直接导入；否则把其中的 SKILL.md 放入对应 Skill 目录。

MCP 配置包

下载 客户端配置包
选择与你的 Agent 匹配的 JSON / TOML 片段
保存配置后调用 batch_status 验证

配置包是模板，不会自动修改本机配置；先读 README，再按客户端版本合并。

本地 stdio 服务器

对 Agent 说：

请先阅读 corpus-pipeline Agent 工作流指令，
然后通过 corpus-pipeline MCP 调用 batch_status 验证连接。

如果客户端不能连接远程 HTTP MCP，下载 本地服务器包 后运行 stdio 模式。

How It Works

工作流原理 — WorkBuddy 无感调用远端 MCP

成员只输入"开始"；WorkBuddy 在背后用受控 HTTP 上传本机 PDF，再用远端 MCP 按状态机逐个推进。了解原理有助于排错和复核。

01
WorkBuddy 本机桥接
只读取 workspace 根目录 PDF，通过受控上传端点送入远端 corpus/incoming。
02
process_incoming_batch
登记 staging、逐文档预检、自动选 profile、跑 MinerU、清洗、metadata、QC、review。
03
register_batch
只扫描 corpus/incoming，分配 pub_000001 稳定 ID，按 source hash 幂等跳过重复文件。
04
inspect_document
读页数、文本层密度、hash、疑似扫描件。born-digital 用 baseline，扫描件用 OCR。
05
submit_mineru_job
只传 profile：baseline_auto_v1 / ocr_scan_v1 / debug_page_range_v1。Agent 不暴露命令行。
06
normalize / metadata / QC
生成 clean.md、metadata.json、qc.json。无法确认的字段标 review_required，不让 Agent 猜。
07
export_batch
打包 Markdown、metadata、QC、review 和 MANIFEST，返回受控下载 URL。
08
下载回本机
WorkBuddy 下载 export ZIP，解压到 workspace 的 outputs/，成员直接查看本机产物。

全部 15 个 MCP 工具

工具类型一句话

batch_statusbatch全量进度概览 + 建议

process_incoming_batchbatchWorkBuddy "开始"后的服务端批处理

export_batchbatch打包当前产物并返回下载 URL

register_batchbatch扫描目录批量登记 PDF

run_pipelinebatch端到端自动走完全流程

list_documentscore列出队列中所有文档及状态

register_documentcore单文档登记，分配稳定 ID

inspect_documentcore预检页数、文本层、扫描件标记

submit_mineru_jobcore提交 MinerU 转换作业

get_job_statuscore查看作业状态

get_artifactscore获取产物 URI 清单

normalize_markdowncore生成 clean.md

extract_metadatacore提取 title / publisher / year

run_qccoreQC 质检

create_review_taskcore创建人工复核任务

禁区 — 这些话不要对 Agent 说

高风险指令

"直接进服务器跑一下命令"
"把这个目录全扫一遍"
"覆盖掉旧 PDF"
"所有文件批量重跑"
"你自己改 metadata 数据库"

正确说法

"通过 MCP 查看这个 document_id 的状态"
"用 inspect_document 判断 profile"
"提交 baseline_auto_v1 的 MinerU job"
"返回 artifact URI 和 QC 摘要"
"为缺失字段创建 review task"

出错时

保留 job_id、error、logs
只重跑明确失败阶段
不要删除旧 artifact
把不确定项写入 review.json

Delivery & Review

交付与复核

批量流水线跑完后，Agent 会给出汇总。以下清单帮你确认交付质量。

Review Queue

什么时候必须人工复核

metadata 缺 title、publisher、publication_year，或 confidence 低于团队阈值。

Markdown 为空、重复行比例异常、双栏顺序混乱、页码或章节明显错位。

图片、表格数量与版面预期明显不符，或 OCR 质量不足以直接入库。

成员无法判断时，不让 Agent 猜结论；保留证据并创建 review task。

交付前确认

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

document_id: pub_000001
current_status: qc_done | review_required | approved
agent_entry: corpus-pipeline MCP
mineru_profile: baseline_auto_v1
job_id: job_000001
artifacts:
  clean_markdown: corpus/cleaned/pub_000001.clean.md
  metadata: corpus/metadata/pub_000001.metadata.json
  qc: corpus/qc/pub_000001.qc.json
review:
  required: true
  reason: Missing publication_year
next_action: human reviewer checks title page

Downloads

下载 — 按用途选择正确文件

不要把"工作流指令""MCP 客户端配置""本地服务器代码"混在一起安装。每个包都带 README，先读再合并到你的客户端。

Guide

Agent 工作流指令

单个 Markdown 文件。说明 WorkBuddy 如何把"开始"解释为本机上传、远端 MCP 批处理、下载 outputs。

MD

Skill

WorkBuddy Skill 目录包

主推荐包。ZIP 内含 corpus-pipeline/SKILL.md、MCP JSON 模板和 README，让成员只需输入"开始"。

ZIP

Config

MCP 客户端配置模板

ZIP 内含 WorkBuddy JSON、Codex TOML 示例、通用 Streamable HTTP 配置和本地 stdio 模板。

ZIP

Upload

本地 PDF 上传脚本

备用脚本。WorkBuddy 不能自动上传时使用；正常流程由 Skill 在 workspace 中自动完成。

PY

Server

本地 MCP 服务器包

ZIP 只有一个根目录，含 README.md、mcp_server/、pipeline/、docs 和 requirements。

ZIP

备用：本地 stdio 服务器或手动上传

# 1. 下载并解压
unzip corpus-pipeline-mcp-server.zip -d corpus-pipeline

# 2. 安装依赖（需要 Python ≥ 3.11）
cd corpus-pipeline/corpus-pipeline-mcp-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 3. 启动 MCP 服务器（stdio 模式，供本地 Agent 调用）
.venv/bin/python -m mcp_server.server

# 4. 或启动为线上服务器
.venv/bin/python -m mcp_server.server --transport streamable-http --port 8000

# 备用：本机批量上传到线上 staging
CORPUS_UPLOAD_TOKEN=团队口令 python3 corpus-pipeline-upload-pdfs.py ./pdfs

配置 WorkBuddy 后，输入开始交付 PDF 语料