128 lines
2.7 KiB
Markdown
128 lines
2.7 KiB
Markdown
# 资料包扫描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. 哈希对同一文件稳定。
|