# 资料包扫描Skill 设计

## 1. Skill 定位

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

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

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

## 2. 输入

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

## 3. 输出

```python
@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. 哈希对同一文件稳定。