DEMO-AGENT/docs/详细设计/skill/资料包扫描Skill.md

资料包扫描Skill 设计

1. Skill 定位

资料包扫描Skill 负责扫描资料包根目录，生成后续文档登记、页数统计和章节点识别所需的文件清单。

它处理的是文件系统事实，不读取文档正文，不做页数统计。

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

2. 输入

@dataclass
class PackageFileScanInput:
    root_dir: Path
    batch_id: int
    source_role: str = "submission"
    allowed_extensions: set[str] = field(default_factory=set)

3. 输出

@dataclass
class PackageFileScanOutput:
    scanned_files: list[ScannedFile]
    unsupported_files: list[ScannedFile]
    skipped_files: list[SkippedFile]
    warnings: list[dict]

ScannedFile 字段：

1. absolute_path
2. relative_path
3. original_filename
4. extension
5. file_size
6. file_hash
7. source_role

4. 核心方法

4.1 run(input) -> PackageFileScanOutput

主入口方法。

执行顺序：

1. 遍历根目录。
2. 过滤目录和临时文件。
3. 识别文件类型。
4. 生成文件大小和哈希。
5. 区分支持文件、不支持文件和跳过文件。
6. 返回扫描结果。

4.2 iter_files(root_dir) -> Iterator[Path]

使用 pathlib.Path.rglob("*") 遍历文件。

4.3 should_skip(path) -> bool

跳过规则：

1. .DS_Store
2. Thumbs.db
3. __MACOSX
4. Office 临时文件 ~$*.docx
5. 空文件

4.4 is_supported_document(path) -> bool

支持类型：

1. pdf
2. docx
3. doc
4. txt
5. md

压缩包在本 Skill 中不再进入支持文档列表，应由导入入口先交给 压缩包解包Skill。

4.5 build_relative_path(root_dir, path) -> str

生成统一的相对路径，使用 / 作为内部存储分隔符。

4.6 build_file_hash(path) -> str

使用 sha256。

5. 技术实现

使用技术：

1. pathlib
2. hashlib
3. mimetypes
4. 可选 python-magic

6. 输出用途

扫描结果用于：

1. 创建 RegistrationDocument。
2. 保留资料包原始目录结构。
3. 识别重复文件。
4. 后续章节点识别。
5. 页面展示不支持文件提示。

7. 异常处理

异常	处理
根目录不存在	返回失败
文件读取失败	加入 skipped_files
文件为空	加入 skipped_files
类型不支持	加入 unsupported_files
哈希计算失败	保留文件记录，标记警告

8. 测试要点

1. 多层目录扫描后相对路径正确。
2. Office 临时文件被跳过。
3. 不支持文件进入 unsupported_files。
4. 支持文件进入 scanned_files。
5. 哈希对同一文件稳定。