127 lines
3.2 KiB
Markdown
127 lines
3.2 KiB
Markdown
# 文档页数统计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. 损坏文件返回失败状态。
|