docparser-core 0.1.0

# docparser-core


独立文档解析的**核心层**：统一 IR、统一错误码、能力抽象、注册表、格式嗅探、策略与引擎编排。
零 native 依赖（仅 `serde`），不含任何具体格式实现——格式后端在 `docparser-pdf` / `docparser-office` 等 crate 中。

## 安装


```bash
cargo add docparser-core                                        # 内核 + 文本族（md/csv/html）
cargo add docparser-core --no-default-features                  # 只要内核：IR + 引擎 + txt
cargo add docparser-core --no-default-features --features md    # 只加 markdown
```

### 特性


| feature | 默认 | 作用 |
| --- | --- | --- |
| `md` | ✅ | Markdown 块级解析插件（标题/列表/引用/代码/表格） |
| `csv` | ✅ | CSV（RFC4180）→ `TableData` |
| `html` | ✅ | HTML 标签级块解析（`docparser-epub` 依赖它，不能裁） |

`txt` 是底座（字节流读取 + 空行分段 + IR 组装），始终编译。
关掉某个 feature 后该格式不注册，`engine` 遇到对应扩展名返回 `unsupported`（不 panic）。
依赖树只有 `serde`，与开关无关；省下的是**编译进来的代码量**（实测 `rlib` 1.03 MB → 1.18 MB）。

需要开箱即用（含 PDF / Office 后端）时用门面 crate：

```bash
cargo add docparser-sdk
```

## 组成


| 模块 | 作用 |
| --- | --- |
| `model` | IR：`Document` / `Page` / `Block` / `Image` / `TableData` / `Rect` / `DocMeta`（serde 双向）；`DocMeta.extra` 承载插件级元数据（EPUB 书名/作者/封面）与处理链告警 |
| `error` | `ErrorCode{encrypted,corrupt,unsupported,timeout,native_crash,unknown}` + `DocError` |
| `plugin` | `ParseCapability` / `ProcessCapability` / `FormatPlugin` / `RawDoc` |
| `registry` | 后端注册、按策略解析链、复合后端委托环检测 |
| `router` | magic + 扩展名嗅探（识别伪装件与加密 OOXML） |
| `policy` | `BackendPolicy`：后端链、偏好、回退、超时、OCR/版面开关 |
| `engine` | `DocumentEngine`：嗅探 → 解析链 → 处理链 → assemble |
| `emit` | `to_text` / `to_markdown` |
| `plugins` | 内置文本族：`txt`（空行分段）/ `md`（标题/列表/引用/代码/表格）/ `csv`（RFC4180）/ `html`（标签级块） |

## 用法


```rust
use docparser_core::{DocumentEngine, Registry};

let mut reg = Registry::new();
docparser_core::plugins::text::register_defaults(&mut reg); // txt/md/csv/html
let engine = DocumentEngine::new(reg);

let doc = engine.parse("note.md")?;
println!("{} pages, {} blocks", doc.pages.len(), doc.pages[0].blocks.len());
```

接入 PDF/Office 只需注册对应后端：

```rust
docparser_pdf::register_defaults(&mut reg);
docparser_office::register_defaults(&mut reg);
```

## 错误语义


解析失败返回 `DocError`，`code` 是跨后端稳定的结论：

- `encrypted` / `unsupported` 是**终止码**，不会回退到兜底后端（避免真结论被兜底掩盖）；
- `corrupt` 表示后端链耗尽；
- 处理链（OCR / layout）失败不致命，写入 `meta["warnings"]`。

## 许可


MIT OR Apache-2.0