collate AGENTS.md

AGENTS.md

面向任何运行此 pipeline 的 agent 运行时（Claude Code / Codex CLI / Cursor / Gemini CLI / Hermes agents）。描述完整的自动化工作流、每个 skill 的调用契约、agent 自主决策点、失败处理。人类只负责提供 PDF、接收最终产物与审计报告。

范围说明：本文档覆盖 8 步 pipeline 层。仓库还包含 7 个阅读层 skill（xray-paper / paper-summary / chunqiu / kaozheng / prometheus / real-thesis / constellatio），它们独立于 pipeline，使用各自 skills/<name>/SKILL.md 作为调用契约，本文档不重复展开。

---

总原则

1. 端到端自主：从 PDF 到 .docx + .mp.html 由 agent 独立完成。不要把中间步骤暴露给人类确认，除非失败降级到人类决策（见「失败处理」）。
2. 保留可追溯性：每一步的中间产物全部落盘，不清理。diff-review 的审计报告是交付的一部分，不是调试工具。
3. 按 checklist 执行 proofread：结果是机器可读的结构化清单（A/B/C 分级），由 agent 消化后修改 raw.md → final.md。不做超出清单的结构性改写。
4. 不替换学术判断：C 类（存疑待考）条目不要替人做决定；在 final.md 里保留原文 + 脚注标注，由读者判断。
5. 失败要显性：引擎调用失败、依赖缺失、输入不合规 → 立即终止并回传结构化错误，不要静默兜底。

---

Pipeline 全景

Human ──► PDF
           │
           ▼
  ┌──────────────────────────────────────────────────┐
  │ 1. prep-scan       产 <ws>.ocr/prep/cleaned.pdf   │
  │ 2. visual-preview  产 previews/visual-prep.html   │
  │ 3. ocr-run         产 raw.md + meta.json + assets │
  │ 4. proofread       产 review/raw.review.md        │
  │ 5. (agent 按 checklist 写 final.md)              │
  │ 6. diff-review     产 previews/diff-review.html   │
  │ 7. to-docx         产 output/<title>_…_final.docx │
  │ 8. mp-format       产 output/<title>_…_wechat.*   │
  └──────────────────────────────────────────────────┘
           │
           ▼
Human ◄── <ws>.ocr/README.md  （指向 output/ 与 previews/）

整个 .ocr/ 工作区自描述：根目录 README.md 由 scripts/workspace_readme.py 在每个 skill 结束时刷新，给人类一个清晰的入口。

一条命令模式：

• shell / CI / 本地编排：python3 scripts/run_full_pipeline.py --pdf <input.pdf>
• agent runtime：以 agents/ocr-pipeline-operator.md 作为单一入口；它负责调用上面的总编排脚本、在 raw.md 就位后起 historical-proofreader subagent、再重入总编排脚本完成 final.md / diff-review / docx / wechat。

每一步的详细契约见下。

---

1. setup（首次/环境校验）

何时调用：新环境、依赖缺失、OCR 凭证未配置或怀疑失效。稳定环境下不重复调用。

做什么：按 skills/setup/SKILL.md 检查 Python 依赖、poppler、mineru CLI 可用性；探活 OCR_ENGINE 指向的引擎（本地 mineru 跑一个 --help、云 API 或百度跑一次空探测）。