Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

docs: migrate project instructions to AGENTS.md

myhloli7f90f0b5a035
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 120000
index 681311eb..00000000
--- a/AGENTS.md
+++ /dev/null
@@ -1 +0,0 @@
-CLAUDE.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..0ab5c5bd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,199 @@
+# MinerU 项目编码规范
+
+## 开发环境
+
+使用 **uv** 管理 Python 虚拟环境和依赖。
+
+```bash
+# 在项目根目录中创建虚拟环境
+uv venv .venv
+
+# 激活虚拟环境
+source .venv/bin/activate
+
+# 安装依赖
+uv pip install -e ".[dev,test]"
+```
+
+运行 Python 代码须在项目根目录 `MinerU` 中执行:
+
+```bash
+.venv/bin/python -m mineru.path.to.submodule
+```
+
+## GitHub Issue / PR 处理规范
+
+处理 GitHub issue 时,commit message 和 PR body 中不要使用会导致 issue 在 merge 后自动关闭的关键词。
+
+禁止使用:
+- `fixes #123` / `fix #123`
+- `closes #123` / `close #123`
+- `resolves #123` / `resolve #123`
+
+需要关联 issue 时,使用不会自动关闭 issue 的表述:
+- `Refs #123`
+- `Related to #123`
+- `Issue: #123`
+
+## Import 规范
+
+mineru 模块内部子模块之间的引用统一使用 **relative import**,不使用 `import mineru.xxx` 形式的绝对导入。
+
+```python
+# 正确 — relative import
+from .base import DocumentParser
+from ..render import RenderMode
+
+# 错误 — 项目内不允许 absolute import 引用自身模块
+from mineru.api.base import DocumentParser
+from mineru.render import RenderMode
+```
+
+只引用外部第三方库时使用 absolute import(如 `from loguru import logger`)。
+
+## 格式化
+
+- 格式化工具:**ruff**
+- 保存时自动格式化:开启
+- 保存时自动 organize imports:开启
+- 行宽:**128**
+
+## Lint 规则
+
+启用的规则集:
+- **C** — 复杂度/编码规范 (mccabe, pycodestyle 约定等)
+- **E** — pycodestyle 错误
+- **F** — pyflakes 检查
+- **W** — pycodestyle 警告
+- **ANN** — flake8-annotations(类型注解)
+
+忽略的规则:
+- **C901** — 函数过复杂(允许必要的复杂函数)
+- **ANN204** — 特殊方法(如 `__init__`)不需要返回类型注解
+- **ANN401** — 允许使用 `Any` 类型标注
+
+## 编程原则
+
+### 确定性优先
+
+agent 通过静态分析理解代码。避免运行时注册、猴子补丁、`globals()` 等动态模式,使用显式映射。
+
+```python
+# 差 — agent 无法静态追踪
+registry.register(MyParser)
+
+# 好 — 显式映射
+TIER_TO_EFFORT: dict[Tier, Effort] = {
+ "flash": "flash",
+ "basic": "medium",
+ "standard": "high",
+ "advanced": "xhigh",
+}
+```
+
+### 入口一致性
+
+每个模块的 `__init__.py` 必须明确导出 `__all__`,让 agent 能快速获取模块边界。
+
+```python
+# mineru/parser/__init__.py
+from .base import DocumentParser, ParseResult
+
+__all__ = ["DocumentParser", "ParseResult", "parse", "parse_async"]
+```
+
+### 类型优先
+
+公开函数必须有完整类型注解。避免 `**kwargs: Any` 透传内部配置。
+
+```python
+# 差 — agent 不知道合法参数
+def parse(path, **kwargs): ...
+
+# 好
+def parse(
+ path: str | Path,
+ *,
+ tier: Tier = "standard",
+ ocr_mode: Literal["auto", "txt", "ocr"] = "auto",
+ image_analysis: bool = True,
+ page_range: str = "",
+) -> ParseResult: ...
+```
+
+### 副作用隔离
+
+模块级别不得有隐式副作用(读取环境变量、创建目录、注册 handler 等)。`import` 只应定义符号。
+
+```python
+# 差 — import 时执行
+os.makedirs(DEFAULT_OUTPUT_DIR, exist_ok=True)
+
+# 好 — 使用时执行
+def parse(...):
+ Path(output_dir).mkdir(parents=True, exist_ok=True)
+```
+
+### 惰性加载
+
+对外 API 层的 `import` 不得触发重依赖(torch、transformers 等)。重依赖应在函数体内按需导入。
+
+```python
+# 对外 API 层不触发重依赖;轻依赖(如 doc_analyze 所在的 backend.analyze)
+# 可模块顶层导入,重依赖(torch、transformers 等)在函数体内按需导入。
+class MinerUParser(DocumentParser):
+ def parse(self, path: str | Path, *, page_range: str = "") -> ParseResult:
+ from ..model.flash.pdf.document import PDFDocument # 重依赖惰性加载
+
+ ...
+```
+
+## DocVortex 与 MinerU 的文档架构
+
+### 1. 唯一实现归属
+
+`docvortex` 独立拥有原生文档解析、PDF 基础访问与分类、公共文档类型、确定性后处理、素材、七种通用渲染格式和导出实现,不得反向依赖 MinerU。
+
+MinerU 保留 OCR/VLM/Hybrid 推理、模型生命周期、LLM 增强、tier 策略、CLI/API/Gradio/Doclib。通过 DocVortex 公开接口复用能力,不导入其私有实现。
+
+### 2. 路由
+
+`backend/analyze.py:doc_analyze()` 仍是 MinerU 的统一分析门面。只有 `parse_mode="auto"` 调用共享 `PDFDocument.classify()`。
+
+- Flash + txt:使用 DocVortex 的原生 PDF 模型。
+- Flash + auto:txt 分类走 DocVortex;ocr 分类走 MinerU 现有 Flash OCR。
+- Flash + ocr:直接走现有 Flash OCR。
+- 其他 tier:保持已有推理流程,共享 DocVortex 的基础 PDF、类型、后处理和渲染能力。
+
+原生解析不自行追加分类或 OCR 回退。非 PDF 原生格式仍只支持整本解析,PDF 页范围继续采用 `1-5`、`r1`、`all`。
+
+### 3. 协议与类型
+
+`mineru.types` 重新导出 `docvortex.schema` 的文档类型,并保留 MinerU 产品档位类型。
+
+共享文档协议是带 `schema` 身份的版本 2.0(Python 属性名为 `schema_id`,JSON 序列化键为 `schema`)。MinerU 直接消费共享类型:`ParseResult` 持有 `MiddleJson` 读写,不维护独立的协议封装层。MinerU 通过 `extensions["mineru"]` 记录实际执行的 `tier` 与 `parse_mode`,由 `mineru.integrations.docvortex.MinerUMetadata` 严格校验(`extra="forbid"`,不接受其他字段,没有 `effort`、`mineru_version` 字段);生产者版本位于 `metadata.producer.version`。
+
+历史协议兼容限定在 Doclib 持久化缓存的读取边界(`mineru.doclib.core.middle_json.read_cached_middle_json`),不扩展为通用 SDK/API 的兼容承诺;3.4.5 旧页面转换由 `mineru.backend.postprocess.legacy_schema_adapter` 在该边界内维护。协议细节以 `docs/next/middle-json/` 为唯一参考,兼容行为对应测试为 `tests/unittest/test_doclib_legacy_schema_adapter.py`。产品字段校验和旧结果兼容均归 MinerU,DocVortex 不提供兼容模块或旧路径别名。不要为旧底层构造参数增加动态兼容别名。
+
+ModelJson 仍保存 raw pages 与 page_index_map;MiddleJson 仍保存有序 PageInfo 数组。PageInfo 只有 page_idx 与 blocks。Block/InlineSpan 的现有语义、几何和父子约束保持不变;自然语言 InlineSpan 不携带字体或几何信息。
+
+### 4. 后处理与渲染
+
+DocVortex 的确定性后处理独立构造有效 MiddleJson。`mineru.backend.postprocess.document` 在其后显式执行 MinerU 的可选 LLM 增强。
+
+`mineru.render` 保留九种输出:Content List V1/V2 实现及专用选项归属 MinerU,其余七种 renderer 和通用选项来自 DocVortex。两边各自定义 RenderFormat,RenderMode 与共享文档类型仍复用。Content List 通过 `docvortex.render.fragments` 调用共享片段能力,不导入私有实现。公式定界符等宿主配置显式传入,不让 DocVortex 读取 MinerU 配置。
+
+九种输出为 Markdown、HTML、LaTeX、DOCX、EPUB、PDF、Structured Content、Content List V1/V2。LaTeX/EPUB/PDF/Content List 的低层能力不自动扩展所有产品入口。PDF 输出布局由 `PdfLayout` 控制:`AUTO`(默认,有几何信息时保留原始布局,缺失时回退语义重排)、`ORIGINAL`(仅原始布局)、`REFLOW`(仅语义重排)。
+
+文件写出属于 `docvortex.export`;语义类型不再提供文件导出方法。结果包保存中间协议和物化素材,渲染不依赖已关闭的 PDFium 对象或源文件,也不修改原始语义树。
+
+### 5. PDF 与依赖方向
+
+PDF 字符、片段、行和矩形类型由 DocVortex 维护;项目不再依赖 pdftext,也没有其 0.6/0.7 运行时分支。pypdfium2 最低版本为 5.10.1,DocVortex 约束为 `<6`,MinerU 安装时共同遵守该范围。
+
+访问同一 PDFium 运行时必须使用 DocVortex 的共享锁及资源管理。跨进程传递字节和物化数据,不传递裸句柄。
+
+- DocVortex:schema/foundation → document/content → analyzers/postprocess/render/export → api/result。
+- MinerU:共享 DocVortex 能力 → model/backend → parser/kit/doclib/cli。
+- `model/runtime` 继续负责 MinerU 设备、显存、ONNX 与本地模型生命周期;`model/registry.py`、`model/download.py` 保持产品模型管理职责。
+- 已迁移的 Flash、通用后处理、renderer 私有目录及共享 leaf utilities 不在 MinerU 中保留第二份实现。
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 0ab5c5bd..00000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,199 +0,0 @@
-# MinerU 项目编码规范
-
-## 开发环境
-
-使用 **uv** 管理 Python 虚拟环境和依赖。
-
-```bash
-# 在项目根目录中创建虚拟环境
-uv venv .venv
-
-# 激活虚拟环境
-source .venv/bin/activate
-
-# 安装依赖
-uv pip install -e ".[dev,test]"
-```
-
-运行 Python 代码须在项目根目录 `MinerU` 中执行:
-
-```bash
-.venv/bin/python -m mineru.path.to.submodule
-```
-
-## GitHub Issue / PR 处理规范
-
-处理 GitHub issue 时,commit message 和 PR body 中不要使用会导致 issue 在 merge 后自动关闭的关键词。
-
-禁止使用:
-- `fixes #123` / `fix #123`
-- `closes #123` / `close #123`
-- `resolves #123` / `resolve #123`
-
-需要关联 issue 时,使用不会自动关闭 issue 的表述:
-- `Refs #123`
-- `Related to #123`
-- `Issue: #123`
-
-## Import 规范
-
-mineru 模块内部子模块之间的引用统一使用 **relative import**,不使用 `import mineru.xxx` 形式的绝对导入。
-
-```python
-# 正确 — relative import
-from .base import DocumentParser
-from ..render import RenderMode
-
-# 错误 — 项目内不允许 absolute import 引用自身模块
-from mineru.api.base import DocumentParser
-from mineru.render import RenderMode
-```
-
-只引用外部第三方库时使用 absolute import(如 `from loguru import logger`)。
-
-## 格式化
-
-- 格式化工具:**ruff**
-- 保存时自动格式化:开启
-- 保存时自动 organize imports:开启
-- 行宽:**128**
-
-## Lint 规则
-
-启用的规则集:
-- **C** — 复杂度/编码规范 (mccabe, pycodestyle 约定等)
-- **E** — pycodestyle 错误
-- **F** — pyflakes 检查
-- **W** — pycodestyle 警告
-- **ANN** — flake8-annotations(类型注解)
-
-忽略的规则:
-- **C901** — 函数过复杂(允许必要的复杂函数)
-- **ANN204** — 特殊方法(如 `__init__`)不需要返回类型注解
-- **ANN401** — 允许使用 `Any` 类型标注
-
-## 编程原则
-
-### 确定性优先
-
-agent 通过静态分析理解代码。避免运行时注册、猴子补丁、`globals()` 等动态模式,使用显式映射。
-
-```python
-# 差 — agent 无法静态追踪
-registry.register(MyParser)
-
-# 好 — 显式映射
-TIER_TO_EFFORT: dict[Tier, Effort] = {
- "flash": "flash",
- "basic": "medium",
- "standard": "high",
- "advanced": "xhigh",
-}
-```
-
-### 入口一致性
-
-每个模块的 `__init__.py` 必须明确导出 `__all__`,让 agent 能快速获取模块边界。
-
-```python
-# mineru/parser/__init__.py
-from .base import DocumentParser, ParseResult
-
-__all__ = ["DocumentParser", "ParseResult", "parse", "parse_async"]
-```
-
-### 类型优先
-
-公开函数必须有完整类型注解。避免 `**kwargs: Any` 透传内部配置。
-
-```python
-# 差 — agent 不知道合法参数
-def parse(path, **kwargs): ...
-
-# 好
-def parse(
- path: str | Path,
- *,
- tier: Tier = "standard",
- ocr_mode: Literal["auto", "txt", "ocr"] = "auto",
- image_analysis: bool = True,
- page_range: str = "",
-) -> ParseResult: ...
-```
-
-### 副作用隔离
-
-模块级别不得有隐式副作用(读取环境变量、创建目录、注册 handler 等)。`import` 只应定义符号。
-
-```python
-# 差 — import 时执行
-os.makedirs(DEFAULT_OUTPUT_DIR, exist_ok=True)
-
-# 好 — 使用时执行
-def parse(...):
- Path(output_dir).mkdir(parents=True, exist_ok=True)
-```
-
-### 惰性加载
-
-对外 API 层的 `import` 不得触发重依赖(torch、transformers 等)。重依赖应在函数体内按需导入。
-
-```python
-# 对外 API 层不触发重依赖;轻依赖(如 doc_analyze 所在的 backend.analyze)
-# 可模块顶层导入,重依赖(torch、transformers 等)在函数体内按需导入。
-class MinerUParser(DocumentParser):
- def parse(self, path: str | Path, *, page_range: str = "") -> ParseResult:
- from ..model.flash.pdf.document import PDFDocument # 重依赖惰性加载
-
- ...
-```
-
-## DocVortex 与 MinerU 的文档架构
-
-### 1. 唯一实现归属
-
-`docvortex` 独立拥有原生文档解析、PDF 基础访问与分类、公共文档类型、确定性后处理、素材、七种通用渲染格式和导出实现,不得反向依赖 MinerU。
-
-MinerU 保留 OCR/VLM/Hybrid 推理、模型生命周期、LLM 增强、tier 策略、CLI/API/Gradio/Doclib。通过 DocVortex 公开接口复用能力,不导入其私有实现。
-
-### 2. 路由
-
-`backend/analyze.py:doc_analyze()` 仍是 MinerU 的统一分析门面。只有 `parse_mode="auto"` 调用共享 `PDFDocument.classify()`。
-
-- Flash + txt:使用 DocVortex 的原生 PDF 模型。
-- Flash + auto:txt 分类走 DocVortex;ocr 分类走 MinerU 现有 Flash OCR。
-- Flash + ocr:直接走现有 Flash OCR。
-- 其他 tier:保持已有推理流程,共享 DocVortex 的基础 PDF、类型、后处理和渲染能力。
-
-原生解析不自行追加分类或 OCR 回退。非 PDF 原生格式仍只支持整本解析,PDF 页范围继续采用 `1-5`、`r1`、`all`。
-
-### 3. 协议与类型
-
-`mineru.types` 重新导出 `docvortex.schema` 的文档类型,并保留 MinerU 产品档位类型。
-
-共享文档协议是带 `schema` 身份的版本 2.0(Python 属性名为 `schema_id`,JSON 序列化键为 `schema`)。MinerU 直接消费共享类型:`ParseResult` 持有 `MiddleJson` 读写,不维护独立的协议封装层。MinerU 通过 `extensions["mineru"]` 记录实际执行的 `tier` 与 `parse_mode`,由 `mineru.integrations.docvortex.MinerUMetadata` 严格校验(`extra="forbid"`,不接受其他字段,没有 `effort`、`mineru_version` 字段);生产者版本位于 `metadata.producer.version`。
-
-历史协议兼容限定在 Doclib 持久化缓存的读取边界(`mineru.doclib.core.middle_json.read_cached_middle_json`),不扩展为通用 SDK/API 的兼容承诺;3.4.5 旧页面转换由 `mineru.backend.postprocess.legacy_schema_adapter` 在该边界内维护。协议细节以 `docs/next/middle-json/` 为唯一参考,兼容行为对应测试为 `tests/unittest/test_doclib_legacy_schema_adapter.py`。产品字段校验和旧结果兼容均归 MinerU,DocVortex 不提供兼容模块或旧路径别名。不要为旧底层构造参数增加动态兼容别名。
-
-ModelJson 仍保存 raw pages 与 page_index_map;MiddleJson 仍保存有序 PageInfo 数组。PageInfo 只有 page_idx 与 blocks。Block/InlineSpan 的现有语义、几何和父子约束保持不变;自然语言 InlineSpan 不携带字体或几何信息。
-
-### 4. 后处理与渲染
-
-DocVortex 的确定性后处理独立构造有效 MiddleJson。`mineru.backend.postprocess.document` 在其后显式执行 MinerU 的可选 LLM 增强。
-
-`mineru.render` 保留九种输出:Content List V1/V2 实现及专用选项归属 MinerU,其余七种 renderer 和通用选项来自 DocVortex。两边各自定义 RenderFormat,RenderMode 与共享文档类型仍复用。Content List 通过 `docvortex.render.fragments` 调用共享片段能力,不导入私有实现。公式定界符等宿主配置显式传入,不让 DocVortex 读取 MinerU 配置。
-
-九种输出为 Markdown、HTML、LaTeX、DOCX、EPUB、PDF、Structured Content、Content List V1/V2。LaTeX/EPUB/PDF/Content List 的低层能力不自动扩展所有产品入口。PDF 输出布局由 `PdfLayout` 控制:`AUTO`(默认,有几何信息时保留原始布局,缺失时回退语义重排)、`ORIGINAL`(仅原始布局)、`REFLOW`(仅语义重排)。
-
-文件写出属于 `docvortex.export`;语义类型不再提供文件导出方法。结果包保存中间协议和物化素材,渲染不依赖已关闭的 PDFium 对象或源文件,也不修改原始语义树。
-
-### 5. PDF 与依赖方向
-
-PDF 字符、片段、行和矩形类型由 DocVortex 维护;项目不再依赖 pdftext,也没有其 0.6/0.7 运行时分支。pypdfium2 最低版本为 5.10.1,DocVortex 约束为 `<6`,MinerU 安装时共同遵守该范围。
-
-访问同一 PDFium 运行时必须使用 DocVortex 的共享锁及资源管理。跨进程传递字节和物化数据,不传递裸句柄。
-
-- DocVortex:schema/foundation → document/content → analyzers/postprocess/render/export → api/result。
-- MinerU:共享 DocVortex 能力 → model/backend → parser/kit/doclib/cli。
-- `model/runtime` 继续负责 MinerU 设备、显存、ONNX 与本地模型生命周期;`model/registry.py`、`model/download.py` 保持产品模型管理职责。
-- 已迁移的 Flash、通用后处理、renderer 私有目录及共享 leaf utilities 不在 MinerU 中保留第二份实现。