DEMO-AGENT/docs/详细设计/skill/文档页数统计Skill.md

文档页数统计Skill 设计

1. Skill 定位

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

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

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

2. 输入

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

3. 输出

@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. 损坏文件返回失败状态。