# 文档页数统计Skill 设计

## 1. Skill 定位

`文档页数统计Skill` 负责为注册申报资料文件生成页数统计结果。页数是题面明确要求的关键指标，因此本 Skill 必须把页数、统计方法和可信度分开记录。

本 Skill 不负责文档正文抽取，不负责 OCR，不负责合规判断。

英文实现标识建议使用 `DocumentPageCountSkill`，用于 Python 类名和 Tool Registry 注册处理器。

## 2. 输入

```python
@dataclass
class DocumentPageCountInput:
    document_id: int
    file_path: Path
    file_type: str
    options: dict = field(default_factory=dict)
```

## 3. 输出

```python
@dataclass
class PageCountResult:
    document_id: int
    page_count: int | None
    method: str
    confidence: str
    status: str
    message: str = ""
```

## 4. 页数统计策略

| 文件类型 | 策略 | 可信度 |
|---|---|---|
| `pdf` | 使用 `pypdf` 或 `PyMuPDF` 读取页数 | `exact` |
| `docx` | 优先读取 Word 统计信息，必要时转换 PDF 后统计 | `exact` |
| `doc` | 尝试转换后统计，失败则待复核 | `manual_review_required` |
| `txt` | 页数不适用 | `not_applicable` |
| `md` | 页数不适用 | `not_applicable` |

DOCX 是 V1 验收重点，不能用字数、段落数或估算分页代替精确页数。

## 5. 核心方法

### 5.1 `run(input) -> PageCountResult`

根据文件类型路由到具体统计方法。

### 5.2 `count_pdf_pages(path) -> PageCountResult`

推荐使用 `pypdf` 或 `PyMuPDF`。

失败处理：

1. 文件损坏：`failed`
2. 加密 PDF：`manual_review_required`
3. 无法读取：`failed`

### 5.3 `count_docx_pages(path) -> PageCountResult`

DOCX 精确页数建议采用两级策略：

1. 读取文档内部统计属性中的页数。
2. 若统计属性不可用，使用 LibreOffice headless 转 PDF，再统计 PDF 页数。

如果两级策略均失败，输出 `manual_review_required`，并在页面突出显示。

### 5.4 `count_doc_pages(path) -> PageCountResult`

DOC 文件首版策略：

1. 尝试用兼容转换工具转 PDF。
2. 转换成功后统计 PDF 页数。
3. 转换失败则标记待人工复核。

### 5.5 `count_text_pages(path) -> PageCountResult`

TXT/MD 首版不做页数强制验收。

返回：

1. `page_count = None`
2. `method = "not_applicable"`
3. `confidence = "not_applicable"`

## 6. 技术实现

建议依赖：

1. `pypdf`
2. `PyMuPDF`
3. `python-docx`
4. LibreOffice headless，可作为增强能力

如果 V1 Docker 环境暂不内置 LibreOffice，应在配置中显式标注 `DOCX_PAGE_COUNT_STRATEGY`，并保证演示样本能通过已实现策略得到精确页数。

## 7. 状态设计

| 状态 | 含义 |
|---|---|
| `success` | 页数统计成功 |
| `not_applicable` | 文本类文件不适用 |
| `manual_review_required` | 需要人工复核 |
| `failed` | 统计失败 |

## 8. 落库字段

建议写入 `RegistrationDocument`：

1. `page_count`
2. `page_count_method`
3. `page_count_confidence`
4. `page_count_status`
5. `processing_message`

## 9. 测试要点

1. PDF 返回精确页数。
2. DOCX 返回精确页数。
3. DOC 无法统计时标记待人工复核。
4. TXT/MD 返回不适用。
5. 损坏文件返回失败状态。