# Batch File Pipeline

> 批量文件管道（Batch File Pipeline）：对一批文件执行可复用的处理管道——方向检查与校正（OCR检测旋转）、按命名规范统一重命名、格式转换、去重、校验。泛化于一切"一批文件要统一处理整理"的任务：扫描证书、照片、下载的媒体（音频/视频）、PDF文档、字幕、图片。防丢失是硬约束：先验证新文件再动旧文件。 Triggers when: 需要批量旋转/校正一批图片或扫描件、按统一命名规范批量重命名文件、批量转换格式（PDF↔图片、docx↔md、媒体压缩）、去重、检查一批文件是否规范、为一批文件生成清单。 Commands: - /批量文件 <目录> rotate - 批量检测并校正图片旋转方向（OCR盒坐标判断90°/180°） - /批量文件 <目录> rename <规范> - 按命名规范批量重命名（支持模板/正则/顺序号） - /批量文件 <目录> convert <目标格式> - 批量转换格式 - /批量文件 <目录> dedupe - 按内容哈希去重 - /批量文件 <目录> verify <规范> - 校验文件完整性与命名 - /batchfiles <dir> <action> - English alias Capabilities: OCR盒坐标旋转检测（竖排文字比例判断90°旋转+CW/CCW判定）、PIL旋转校正（quality=95）、按模板批量重命名、格式转换管道、SHA-256内容去重、先验证后删旧的防丢失协议、批量清单生成、命名规范正则校验

- Skill: `cycleuser/batch-file-pipeline` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add cycleuser/batch-file-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cycleuser/batch-file-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: cycleuser (https://skillmd.com/u/cycleuser)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/cycleuser/batch-file-pipeline

---


## Safety Rules

参见 [_shared/core/safety-rules.md](../_shared/core/safety-rules.md)

关键补充：**先验证后删旧**。任何覆盖/删除旧文件的步骤，必须等新文件通过可打开性+内容校验后再执行；`rm` 只针对本批次确认无误的旧文件，且用变量守卫。

# 批量文件管道 (Batch File Pipeline)

处理"一批文件"的统一方法论：检查 → 规范化 → 命名 → 转换 → 去重 → 校验。可以只执行其中一步，也可以串成管道。泛化于扫描证书、媒体收藏、文档库、照片等一切批量整理。

## 管道步骤

```
Step 1 盘点
   列出目录内文件（类型、数量、大小、EXIF方向）。确认要处理哪些、跳过哪些。

Step 2 检查与方向校正（图片/扫描件）
   用 OCR 文字框坐标判断方向：
   - 竖排文字比例 >60% → 图片旋转了90°（文字被转成了竖排）。
   - 判定 CW/CCW：取同一串竖排文字的首尾字符 Y 坐标——
     顺时针旋转后首字符在左、文字左→右读；否则逆时针。
   - 180° 颠倒：OCR 完全读不出时尝试 180° 后重试。
   校正用 PIL `rotate(angle, expand=True)`，保存 quality=95。

Step 3 按命名规范重命名
   命名规范通常形如：`<年度>-<赛事>-<学生，顿号分隔>-<指导教师>-<奖项>-获奖证书.ext`
   或 `<来源>-<序号>-<名称>.<ext>`。重命名前先列出映射表，用户确认后再执行。

Step 4 格式转换
   PDF↔图片（pymupdf）、docx↔md（pandoc/python-docx）、媒体压缩（x264 CRF 23 等）。
   转换后逐文件校验可打开。

Step 5 去重
   按内容 SHA-256 哈希去重；保留首个，其余移入"疑似重复"清单，人工确认后删除。

Step 6 校验
   用 verify-deliver 的脚本：每个新文件可打开、命名符合正则、无文件丢失、
   原文件有备份（若覆盖过）。
```

## 防丢失协议（硬约束）

1. 重命名/覆盖前，先生成"旧→新"映射清单。
2. 新文件全部生成并通过校验后，才删除旧文件。
3. `rm` 命令必须用变量守卫，逐项删除，不用 `rm -rf`。
4. 大改动前先在批次目录外留一个 tar 备份或 rename 到 `.bak` 后缀。
5. 任何一步失败：停下，报告，不继续。

## 旋转检测算法（关键技巧）

```
for each 图片:
    OCR → 取前若干文字框的 (x1,y1,x2,y2)
    vertical = 计数(h > 1.5*w) / 总数
    if vertical > 0.6:  需要旋转90°
        用同一串文字的首尾 y：首y < 尾y（在竖列中文字从上到下）
        rotate CW（PIL rotate(-90)）→ 该竖列变为横排且左→右读
    else: 方向正常
    若 OCR 完全无文字 → 尝试 180° 后重试
```

## Anti-Patterns

| 违规 | 严重度 | 后果 |
|------|--------|------|
| 未验证新文件就删旧 | 高 | 数据丢失 |
| 旋转方向判断错（CW/CCW搞反） | 中 | 文字成镜像/倒读 |
| 重命名无映射表直接改 | 高 | 无法回退 |
| `rm -rf` 无守卫 | 高 | 误删整目录 |
| 转换后不校验可打开性 | 中 | 交付损坏文件 |

## 依赖

- Python：`PIL`、`rapidocr-onnxruntime`、`pymupdf`、`python-docx`
- 脚本：`scripts/batch_pipeline.py`（方向检测/旋转/重命名/哈希去重/校验）

## 文件结构

```
skills/batch-file-pipeline/
├── README.md
├── SKILL.md
├── rules/
│   ├── orientation.md   # OCR 旋转检测与校正
│   ├── naming.md        # 命名规范与重命名安全
│   └── safety.md        # 防丢失协议
└── scripts/
    └── batch_pipeline.py
```

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-09-01 | 初始版本：从证书批量旋转重命名、媒体批量命名、PDF批量转换等多次批处理任务提炼 |