zfl-batch-pipeline —— 通用批量处理管线模板
用途
把"我有 N 个文件要做 X 处理"这类需求，组织成一条带独立质检门禁、可追溯、能自测的管线。
不让 LLM 子智能体去干机械/像素活——那违反编排能力匹配原则，又慢又不可靠。
何时使用
触发信号（出现即调用）：
- "批量处理 N 张图片/PDF/文档""给这批文件加水印/重命名/裁剪/转格式"
- "把这批素材整理成报告""批量生成缩略图/封面图"
- 用户希望批处理任务有质量门禁 + 处理报告，而非一次性脚本糊完就跑。
本技能产出的管线骨架天然适配：图片批量处理、PDF 批量加水印/旋转、DOCX 批量重排、
CSV/Excel 清洗、任意"对每个输入产出确定产物"的批处理。
约束与错误处理
process_one()必须幂等：重复运行同一 task 不重复注入产物、不破坏已有输出。- 单文件失败不影响整批：Processor 捕获异常，把 task 置
Failed并记 reason，继续下一张；禁止因为一张坏图中断整条管线。 - 真实输入缺失时不得臆造业务内容；只允许用
make_samples.py的固定种子合成样例做端到端验证。 - QC 与 Processor 解耦：QC 永远从
plan重新推导期望（尺寸/水印包围盒/格式），不读 Processor 内部返回的"成功"标记。 - 路径约定：脚手架产物一律落在目标工作区
input/ output/ report/，不写绝对机器路径（防跨机坏）。 - 并行边界：
ThreadPoolExecutorworkers 上限默认 4，IO 密集可调高；CPU 密集（如重编码）勿盲目拉满。
工作流（WorkBuddy 执行步骤）
1. 脚手架生成
运行 assets/scaffold.py 在目标工作区生成管线项目：
python 技能目录/assets/scaffold.py 目标目录
生成结构：
目标目录/
├── pipeline.py # 4-Agent 编排骨架（已含 Orchestrator/状态机/报告）
├── plan.py # ★ 用户填充：处理方案（规则/命名/QC 阈值）
├── processor.py # ★ 用户填充：process_one(task) 单文件处理
├── qc.py # ★ 用户填充：qc_one(task) 单文件质检
├── make_samples.py # 无真实输入时生成可复现样例（可选）
├── report_template.html # Summarizer 用的自包含报告模板
└── input/ # 放置待处理文件
2. 填充三个钩子
仅需改三个文件，其余骨架不动：
| 文件 | 函数 | 职责 | 返回 |
|---|---|---|---|
plan.py |
plan() |
定义裁剪/水印/格式/命名/QC 阈值 | dict |
processor.py |
process_one(task, plan) |
对单文件执行确定动作，写产物 | 更新 task["artifacts"]/task["meta"] |
qc.py |
qc_one(task, plan) |
独立校验，从 plan 推导期望 | {"passed":bool,"checks":{},"reasons":[]} |
> 关键纪律：QC 必须依据 plan 推导校验点，不信任 Processor 内部状态。
> 这与用户既有五源一致性 / PDCA / skill-up 离线回归同属"独立验证"哲学。
3. 跑通 + 自测
cd 目标目录
python make_samples.py 20 # 无真实输入时生成样例
python pipeline.py --run # 跑完整 4-Agent 管线 + 产出 HTML 报告
make_samples.py 用固定随机种子，保证管线可复现地端到端跑通——证明"真 work"，
而非"看起来能跑"。换真实文件只需把文件丢进 input/ 再 --run。
输出格式（交付物）
管道产出三类确定交付物，结构固定：
output/full/— 每张输入的处理后成品（按 plan 的命名规范）。output/thumbs/— 缩略图（如有该阶段）。report/batch_report.html— 自包含 HTML 报告（图片 base64 内嵌，可离线打开），含：
- 顶部统计卡（总数 / 通过 / 失败 / 体积压缩率等）
- 工作流图（4 Agent 角色与数据流）
- 逐文件前后对比（处理前 / 成品 / 缩略图内嵌）+ 状态徽章 + 失败原因列
- 指标对比条形图
报告无外部依赖、无未替换占位符（__XXX__）；任一处 __XXX__ 残留即视为生成失败。
不适用场景（边界）
- 需要判断力/语义理解的任务不适用：如"挑出最好看的 5 张""按文案风格重写"——这些是 LLM 决策，本模板只承接确定动作。
- 实时流/超大体量（十万级+）单进程：默认单进程线程池，海量需改分布式/分批，本骨架不替你做。
- 非"每输入→确定产物"的映射：如聚合统计、跨文件关联分析，不在本模板职责内。
- 发布/对外动作：本技能只在内网工作区脚手架与处理，绝不包含发邮件/发推等对外动作。
自检与完成标准
生成报告后，执行以下输出前自检清单（CREATE-T，控幻觉最便宜一招）：
- [ ] 报告 HTML 打开无崩溃、统计卡数字与
tasks.json一致 - [ ] 抽查 3 张图：前后对比图确为同一源、缩略图尺寸正确
- [ ] 全量
grep '__[A-Z_]*__'报告 → 无残留占位符 - [ ]
output/full/文件数 == 输入数；失败项在报告中有 reason
完成标志（做到什么算好）：管线跑完且 qc_report.json 里 passed == True 的数量 == 输入总数（或失败项均有明确 reason 且用户已知晓），报告 HTML 无占位符残留，方可宣称"完成"。
编排原则（写进 SKILL 的硬规则）
- 机械/像素活 → 确定性代码 Agent。 不派 LLM 子智能体。
- Orchestrator 统管状态机。
Inbox→Assigned→InProgress→Review→Done/Failed，
状态流转写在tasks.json，由编排器而非各 Agent 自报。 - QC 独立。 从 spec(plan) 重新推导校验点验收，绝不信上游自报完成。
- 轻量优先。 同一进程内的 stage 流水线优于开多 LLM team——先问"这步需要判断力吗？"
不需要就用代码 stage，别为编排而编排。 - 后端分层。 每个任务挑最轻够用的执行后端（isolate/managed/container），不无脑起重环境；
CONTAINER 不可用时优雅降级到 managed/isolate 并记 degradation（见下节）。
三层执行后端（Backend Tiering）
借鉴 Cloudflare computer 的三套执行后端，本管线对每个任务自动选最轻但够用的执行环境：
| 后端 | 对应 computer | zfl 环境含义 | 典型任务 |
|---|---|---|---|
isolate |
Isolate Shell / JS | 纯标准库/直接文件操作，当前进程内，零启动开销 | 重命名、复制、std 库文本/JSON/CSV 改写、元数据戳 |
managed |
受管运行时（venv） | 隔离 venv 跑带第三方依赖脚本（PIL/openpyxl/docx/...） | 图片裁剪/水印、Excel 清洗、PDF 提取 |
container |
完整 Linux 容器 | Docker 跑装包/编译/系统工具（libreoffice/ffmpeg/tesseract）/不可信代码 | 音视频转码、Office 批量转 PDF、跑外部工具 |
选择逻辑（backends.py 的 BackendRouter.select）：
plan["backend"]["force"]强制指定 > 2.by_ext按扩展名映射 > 3. 扩展名启发式（图片/xlsx/docx/pdf→managed，csv/txt/json→isolate，mp4→container）> 4.default（默认 managed）。- 能力探测 + 优雅降级（借鉴 zfl-skill-governance「探测先于调用」）：
-container但本机无docker→ 降级managed（受管 venv 就绪）或isolate，记degradation；
-managed声明依赖（如PIL）缺失 → 记degradation，保留 managed 以便报出明确失败原因。 - 选中后端写入
task["meta"]["backend"]（逐任务遥测），并打印Backend 分布与Backend 降级汇总，供编排健康看板聚合。
在 processor.process_one 里可读取 task["_backend"]（BackendTier）做重活分支；真实跨进程/跨容器隔离执行见 backends.BackendRouter.dispatch 的契约注释。
> SSOT 声明：三层执行后端的设计规范与代码源头在 zfl-common（references/exec_backend_tier.md + scripts/exec_backend_tier.py，--selftest 实跑通过）。本技能的 backends.py 是脚手架模板自带副本——生成的 pipeline.py 须在用户项目内独立运行（不依赖 zfl-common 安装），故必须自带；以 zfl-common 规范为准，副本仅在 batch-pipeline 升版时手工同步。
> 编辑纪律：同时改动 SKILL.md 与 assets/（如 backends.py / scaffold_src）等多文件时，遵循坑点库 PF-024——同文件多 Edit 逐次发送（串行/重 Read 取最新快照）、old_string 用长且上下文唯一锚点避开 2 matches found、遇 EBUSY 瞬时锁先重试；完整三步见 zfl-skill-factory references/implementation-details.md「编辑操作铁律」。
看板可观测性（FrontierAgent 启发）
FrontierAgent 的核心增量之一，是把"子任务 pending/active/卡住"做成一眼可见的看板，
直接削掉"绝不信 agent 自报完成→必须独立重跑核实"的隐性信任成本。
本管线的 tasks.json 状态机（Orchestrator 统管、不依赖各 Agent 自报）已是看板的数据源；
本技能补一层消费侧可观测性：
- 跑
python scripts/kanban_summary.py --tasks <项目>/tasks.json即可把状态聚合成看板
（按 Inbox/Assigned/InProgress/Review/Done/Failed 分组 + 失败项带 reason），并写report/kanban.json。 - 看板只读 tasks.json、不改原文件；它是观测工具，不是新门禁——QC 门禁仍由
qc_one独立验证把守。 - 用途：批量大时，一眼定位"卡在 Review 的几张"或"Failed 且 reason 不明的项"，
把"全量重跑核实"降级为"只对看板标红项核实"。
> 与评估体系关联：看板可观测性降低信任成本，而真正的回归判定仍走
> zfl-contrastive-regression 的 eval-pack（断言集 + 双判分）——两者正交，可叠加。
参考
详细架构、钩子签名、QC 推导示例见 references/architecture.md。
电商图批处理的完整可用实例见 assets/quickstart_example/（图片裁剪+水印+缩略图+WebP）。
