DEMO-AGENT/docs/详细设计/skill/目录汇总Skill.md

目录汇总Skill 设计

1. Skill 定位

目录汇总Skill 负责把一个资料包批次中的文档主数据聚合为目录汇总报告。它是第一步“资料包导入与目录汇总”的最终输出 Skill。

本 Skill 不重新扫描文件，不重新统计页数，只消费已经落库或已处理的文档事实。

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

2. 输入

@dataclass
class DirectorySummaryInput:
    batch_id: int
    include_unsupported: bool = true
    include_warnings: bool = true

3. 输出

@dataclass
class RegistrationOverviewReport:
    batch_id: int
    batch_no: str
    workflow_type: str
    source_role: str
    file_count: int
    supported_file_count: int
    unsupported_file_count: int
    failed_file_count: int
    manual_review_count: int
    total_page_count: int
    page_count_status: str
    chapter_summary: list[dict]
    documents: list[dict]
    warnings: list[dict]

4. 核心方法

4.1 run(input) -> RegistrationOverviewReport

主入口方法。

执行顺序：

1. 读取批次信息。
2. 读取该批次所有文档记录。
3. 计算总文件数。
4. 计算支持文件、不支持文件、失败文件和待复核文件数量。
5. 汇总页数。
6. 按章节点聚合。
7. 生成文档明细。
8. 生成导入警告。
9. 返回结构化报告。

4.2 summarize_counts(documents) -> dict

计算：

1. file_count
2. supported_file_count
3. unsupported_file_count
4. failed_file_count
5. manual_review_count

4.3 summarize_pages(documents) -> dict

计算：

1. total_page_count
2. exact_page_count
3. manual_review_page_count
4. page_count_status

page_count_status 规则：

1. 全部精确：exact
2. 部分待复核：partial_review_required
3. 全部无法统计：manual_review_required

4.4 summarize_chapters(documents) -> list[dict]

按 chapter_code 聚合：

1. 文件数。
2. 页数。
3. 待复核数。
4. 主要资料角色。

无章节点的文件归入 unclassified。

4.5 build_document_rows(documents) -> list[dict]

生成页面明细。

字段：

1. document_id
2. relative_path
3. original_filename
4. file_type
5. page_count
6. page_count_confidence
7. chapter_code
8. chapter_name
9. document_role
10. processing_status
11. needs_manual_review

4.6 build_warnings(documents) -> list[dict]

生成业务化提示。

提示类型：

1. unsupported_file
2. page_count_review_required
3. chapter_unclassified
4. file_type_mismatch
5. duplicate_file
6. archive_extract_warning

5. 技术实现

使用技术：

1. Django ORM 聚合查询
2. Python dataclass 或 Pydantic
3. JSONField 存储报告快照

建议注册名：

tool_registry.register(
    name="build_directory_summary",
    handler=DirectorySummarySkill().run,
)

6. 报告存储

建议将目录汇总报告快照写入批次模型或独立模型：

class SubmissionBatchSummary(models.Model):
    batch = models.OneToOneField(SubmissionBatch, on_delete=models.CASCADE)
    report_type = models.CharField(max_length=64, default="registration_overview_report")
    report_json = models.JSONField(default=dict)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

7. 与页面接口

Documents 页面直接消费 RegistrationOverviewReport：

1. 顶部显示统计卡片。
2. 中部显示按章节点聚合表。
3. 底部显示文件明细。
4. 侧边显示待人工复核提示。

8. 与后续 Agent Core 接口

法规完整性核查从本报告读取：

1. batch_id
2. documents
3. chapter_summary
4. manual_review_count
5. warnings

如果 manual_review_count > 0，后续完整性核查仍可执行，但最终报告应标记“存在资料处理不确定性”。

9. 测试要点

1. 空批次返回合理空报告。
2. 多章节点文件能正确聚合。
3. 页数合计只统计有明确页数的文档。
4. 待复核文件数量正确。
5. 不支持文件可选展示。
6. 输出 schema 字段稳定。