# eai-data

**Repository Path**: eai-code/eai-data

## Basic Information

- **Project Name**: eai-data
- **Description**: 文档→Markdown 转换组件，把 PDF/HTML 等手册文档转成结构化 Markdown，给 AI（RAG）消费
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# doc2md

> **文档 → Markdown 转换组件** — 把各类手册文档（PDF/HTML）转成结构化 Markdown，给 AI（RAG/LLM）消费。

## 简介

eai-code 生态的数据源工具层组件。核心能力：

- **多引擎转换**：mineru.net 在线 vlm（高质量，表格/公式/图片）/ pymupdf（轻量快速）
- **多格式支持**：PDF / HTML（架构预留 Word/Excel 扩展）
- **自动绕反爬**：playwright 自动突破 LCSC WAF，零干预下载
- **角色差异化**：嵌入式软件工程师 vs 硬件工程师（受众筛选）
- **开箱即用**：`doc2md config set-token` 配置一次，之后一行调用

```bash
pip install git+https://gitee.com/eai-code/eai-data.git
doc2md config set-token sk-xxxxx
doc2md datasheet --yml hw.yml
```

## 定位

把各类手册文档转成 Markdown，给 AI 消费。

- **表层**：文档转换工具（v0.1 优先 PDF）
- **深层**：可持续适应变化的转换组件

## 架构理念（[详见 docs/architecture.md](docs/architecture.md)）

**调度链接器 + 多层分类解调器**：

```
ai/人 → CLI/SDK → Linker（持配方+链路知识，不亲自做事）
                     ↓ 调度
                 原子解调器（每个是一等公民）
```

- **一等公民**：每个解调器独立可用，有清晰 `(Input) → Output` 类型签名
- **工具画像**（4 维工程标签）：资源占用 / 资源竞争 / 失败模式 / 缓存依赖
  → 让调度器自动做缓存/重试/并行/错误隔离（不用人管）
- **高集成度 → CLI**（如 `doc2md pdf2md`）；**��集成度 → manifest 告知 AI**
- **角色差异化**：不同群体关心不同数据子集（软件 vs 硬件工程师），通过 `interest_filter` 管理

## 文档导航

| 文档 | 内容 | 适合谁 |
|------|------|-------|
| [快速开始](docs/quickstart.md) | 5 分钟安装 / 配 Token / 跑第一条命令 / SDK | **第一次用先看这个** |
| [架构说明](docs/architecture.md) | 调度链接器 + 解调器哲学、四部分、依赖方向 | 想理解设计的 |
| [解调器详解](docs/adapters.md) | 16 个一等公民的签名 / 画像 / 用途（input/filter/fetch/convert/output） | 要深度定制的 |
| [配方说明](docs/recipes.md) | 4 条配方 + convert 引擎选型决策树 + 各 backend 对比 | 要选 backend 的 |
| [扩展指南](docs/extend.md) | 加新 convert 引擎 / 新 input 格式 / 新受众角色（完整示例） | 二次开发的 |
| [故障排查](docs/troubleshooting.md) | LCSC WAF / mineru Token / playwright / Windows 编码 / pymupdf vs vlm | 出问题的 |
| [minerU 集成](docs/mineru-setup.md) | minerU 安装 / 模型加速 / backend 选型 / 版本要求 | 启用本地高质量引擎的 |

## 安装

```bash
pip install -e .

# 可选：minerU 真实集成（需要 Python 3.10-3.12，3.13+ 因 ray 依赖不支持）
pip install -e ".[mineru]"
```

> 全新用户推荐先看 **[快速开始](docs/quickstart.md)**（gitee 远程安装 + Token 配置 + 5 分钟跑通）。
> minerU 详细安装见 [docs/mineru-setup.md](docs/mineru-setup.md)。

## 快速使用

### datasheet — 从硬件 yml 产出关键芯片 datasheet Markdown（核心场景）

```bash
# 嵌入式软件工程师视角（默认：sensor + communication + 主MCU，排除被动元件）
doc2md datasheet --yml hw.yml --output ./doc

# 嵌入式硬件工程师视角（含电源芯片选型规格）
doc2md datasheet --yml hw.yml --output ./doc --audience hw-engineer

# 自定义受众（见 config/audiences.yml）
doc2md datasheet --yml hw.yml --audience ai-rag
```

### pdf2md — 单个 PDF 转 Markdown（高集成度独立工具）

```bash
doc2md pdf2md --pdf datasheet.pdf --output ./md --backend local
# backend: local（本地 minerU）/ http（在线服务）/ stub（开发兜底）/ auto
```

### 通用命令

```bash
doc2md run --recipe <name> --input <file> [--set key=val]   # 按配方执行
doc2md tools                                                 # 列出所有工具 + 画像
doc2md manifest [--format yaml|markdown|json]                # 能力清单（给 AI 读）
doc2md recipes                                               # 可用配方
```

## 一等公民解调器（16 个）

每个解调器都是独立可用的原子单元。按调用层级分层（签名 / 画像 / 用途详解见 [docs/adapters.md](docs/adapters.md)）：

| 类别 | 解调器 | 输入 → 输出 | 集成度 |
|------|------|------|------|
| **input** | `yml_parser` | `YmlPath → HardwareSchema` | low |
| | `pdf_input` | `Path → PdfFile` | low |
| | `dir_input` | `DirInput → list[PdfFile]` | low |
| **filter** | `device_filter` | `HardwareSchema → list[SelectedDevice]`（低级原语） | low |
| | **`interest_filter`** | `HardwareSchema + audience → list[SelectedDevice]`（角色管理） | low |
| **fetch** | `lcsc_fetch` | `SelectedDevice → PdfFile`（LCSC 黑盒） | low |
| | `http_fetch` | `URL → PdfFile` | low |
| **convert** | `mineru_pipeline` | `PdfFile → Markdown`（CPU，subprocess） | **high** |
| | `mineru_vlm` | `PdfFile → Markdown`（GPU，VLM 模型） | **high** |
| | `mineru_hybrid` | `PdfFile → Markdown`（CPU+GPU） | **high** |
| | `mineru_http` | `PdfFile → Markdown`（在线服务） | **high** |
| | `pymupdf` | `PdfFile → Markdown`（轻量纯文本提取） | **high** |
| | `html_to_md` | `HtmlContent → Markdown`（HTML 格式直转） | **high** |
| | `stub` | `PdfFile → Markdown`（开发兜底） | low |
| **output** | `file_writer` | `Markdown → WrittenFile` | low |
| | `stdout_writer` | `Markdown → str` | low |

**多引擎选型**（调度器按画像+环境自动决策）：
- 有 GPU + minerU → `mineru_hybrid`（速度精度平衡）
- 有 minerU 无 GPU → `mineru_pipeline`（CPU 兼容）
- 无 minerU → `pymupdf`（轻量备选，不挑 Python 版本）
- 显式强制 → `--backend pipeline/vlm/hybrid/pymupdf/http/stub`

完整契约（输入/输出类型 + 画像 + 描述）见 [manifest.yml](manifest.yml) 或跑 `doc2md manifest`。

## 其他工具如何使用本组件

### ① 读能力清单（自描述）

本组件通过 `manifest.yml` 对外自描述。其他工具/AI 读这个文件即可知道：
- 组件提供哪些工具
- 每个工具的输入/输出类型
- 资源占用 / 失败模式 / 是否可缓存重试
- 哪些有独立 CLI 可直接调

```bash
# 生成最新 manifest
doc2md manifest --format yaml > manifest.yml
```

或直接读仓库的 [manifest.yml](manifest.yml)（自动生成，已提交）。

### ② Python SDK 调度

```python
from pathlib import Path
from doc2md.cli.main import build_default_linker
from doc2md.core.types import YmlPath

linker = build_default_linker()
result = linker.run("datasheet", YmlPath(path=Path("hw.yml")))
print(result.succeeded, result.failed, result.cached)
```

### ③ 直接调单个解调器（不走调度器）

```python
from doc2md.adapters.convert.mineru_local import pdf_to_md_mineru_local
from doc2md.core.types import PdfFile

md = pdf_to_md_mineru_local(PdfFile(path=Path("x.pdf")))
print(md.text)
```

### ④ 加新解调器（扩展，零改内核）

```python
# 1. 实现函数（adapters/ 下对应子目录）
from doc2md.core.profile import profile

@profile(resources=["cpu_heavy"], retryable=False, integration="high")
def pdf_to_md_pandoc(input: PdfFile) -> Markdown:
    """用 pandoc 把 PDF 转 Markdown。"""
    ...
```

```python
# 2. 在 adapters/registry.py 注册
"convert.pandoc": pdf_to_md_pandoc,
```

完成。内核 / 其他解调器 / CLI 零改动。更多完整示例（新 convert 引擎 / 新 input 格式 / 新受众 / 新配方）见 [docs/extend.md](docs/extend.md)。

## 受众角色管理（可迭代维护）

规则在 [config/audiences.yml](config/audiences.yml)，数据驱动：

| 受众 | 关心的器件 | 场景 |
|------|------|------|
| `sw-engineer` | sensor + communication + 主MCU | 嵌入式软件（寄存器/协议文档） |
| `hw-engineer` | 上述 + power | 嵌入式硬件（选型规格） |
| `ai-rag` | sensor + communication + 主MCU | AI RAG 索引（减少噪音） |

加新角色（如 `test-engineer`）只改 yml，零改代码（完整示例见 [docs/extend.md](docs/extend.md#场景-3加新受众角色)）。

## 默认配方

共 4 条（`datasheet` / `device-to-md` / `pdf-direct` / `pdf-to-md`）。完整拓扑 + convert 引擎选型决策树见 [docs/recipes.md](docs/recipes.md)。速查：

| 配方 | 步骤 | 用途 |
|------|------|------|
| `datasheet` | parse→filter→select→fetch→convert→write | yml → 关键芯片 MD（v0.1 单器件） |
| `device-to-md` | fetch→convert→write | 单器件子链路（datasheet 多器件循环的子配方） |
| `pdf-direct` | input→convert→write | PDF → MD 直转（落盘） |
| `pdf-to-md` | input→convert | PDF → MD（API `convert_pdf` 用，不落盘） |

## 项目结构

```
src/doc2md/
├── core/          # 内核（零外部依赖）：types/profile/protocol/recipe/knowledge/linker
├── adapters/      # 解调器（一等公民）：input/filter/fetch/convert/output + registry
├── manifest/      # 能力清单：generator/reviewer/to_format
└── cli/           # 开放层：main/pdf2md/defaults
config/audiences.yml   # 受众规则（可迭代维护）
docs/                  # 文档：quickstart / architecture / adapters / recipes / extend / troubleshooting / mineru-setup
tests/                 # 测试 + fixtures/
```

## 技术栈

Python 3.10+ / pydantic v2 / typer / pyyaml / requests / beautifulsoup4 / mineru（可选）

## 生态

Part of eai-code ecosystem: https://gitee.com/eai-code

## License

MIT