Knowledge Batch Task Lifecycle

Module Structure

批量任务生命周期域管理ComfyUI批量处理任务的完整生命周期。它是一个ComfyUI自定义节点扩展，封装ComfyUI的prompt执行系统以支持参数化批量执行：用户配置参数组合，系统计算笛卡尔积生成多个prompt变体，提交到ComfyUI队列，通过猴子补丁钩子追踪执行，跨子任务聚合状态，处理取消和清理。

Directory Layout

• lumi_batcher_service/handler/batch_tools.py — 核心API处理器（BatchToolsHandler单例），包含所有HTTP端点、参数叉乘引擎、prompt队列提交
• lumi_batcher_service/hooks/ — 通过猴子补丁进行生命周期事件拦截
  • task_start.py — 拦截执行开始事件
  • task_done.py — 拦截执行完成、聚合状态、触发打包
  • patch_wrpper.py — 通用猴子补丁装饰器工具
• lumi_batcher_service/controller/task/ — 任务操作控制器
  • update_prompt.py — 参数注入ComfyUI prompt图
  • update_workflow.py — 参数注入workflow UI表示
  • cancel_queue.py — 队列取消与中断逻辑
• lumi_batcher_service/common/ — 共享工具
  • validate_prompt.py — Prompt校验兼容包装
  • delete_file.py — 异步并发文件删除
  • file_path.py — 路径安全白名单校验（被handler引用）
• lumi_batcher_service/dao/ — SQLite数据访问层
  • batch_task.py — 批量任务CRUD与重启恢复
  • batch_sub_task.py — 子任务CRUD（含重试逻辑）
• lumi_batcher_service/constant/task.py — 状态枚举与数据类
• lumi_batcher_service/thread/ — 后台线程
  • task_scheduler_manager.py — 线程执行工具
  • check_status.py — 后备状态轮询线程
• __init__.py（项目根目录）— 扩展入口点：实例化handler、注册钩子

Key Entry Points

• BatchToolsHandler.__init__() 在 lumi_batcher_service/handler/batch_tools.py — 服务初始化、DB设置、路由注册、重启恢复
• createBatchTask POST /api/comfyui-lumi-batcher/batch-task/create — 任务创建API
• cancelTask POST /api/comfyui-lumi-batcher/batch-task/cancel — 任务取消API
• deleteTask POST /api/comfyui-lumi-batcher/batch-task/delete — 任务删除API
• 模块加载时注册钩子：__init__.py中的batch_tools_task_start_hook()、batch_tools_task_done_hook()

Gotchas

• BatchToolsHandler通过__init__中设置的instance = None类变量使用单例模式，但没有强制保护——如果意外实例化两次，路由会被注册两次，钩子重复补丁自身，导致状态更新双重执行（lumi_batcher_service/handler/batch_tools.py）
• 服务重启恢复在__init__中路由注册之前运行，根据已记录的计数将所有未完成任务标记为SUCCESS/PARTIAL_SUCCESS/FAILED——但重启时已排队但从未开始的子任务（PENDING）不会从子任务表中清理，遗留孤儿记录（lumi_batcher_service/handler/batch_tools.py, lumi_batcher_service/dao/batch_task.py）
• 猴子补丁在模块导入时应用（ComfyUI加载自定义节点时），这意味着它们在整个ComfyUI进程生命周期中持续存在——不重启ComfyUI重新加载扩展会导致已补丁方法被再次包装，形成嵌套包装器链，造成原始逻辑被多次调用（__init__.py, lumi_batcher_service/hooks/patch_wrpper.py）
• 任务创建中的number参数控制队列优先级：-1插入队首，数值设置优先级，但post_prompt仅在未提供显式number时才递增server.PromptServer.instance.number——如果批量中所有任务都使用显式number，服务端计数器不会前进，可能导致number冲突（lumi_batcher_service/handler/batch_tools.py）
• 批量任务状态聚合是事件驱动的（task_done钩子）而非轮询，如果钩子遗漏事件（例如异常或任务在钩子注册前完成），批量任务可能永久卡在RUNNING或WAITING状态；check_status线程作为后备存在，但从不同模块路径（lib.comfy_patch.batch_tools_patch）导入，表明存在遗留/双代码路径（lumi_batcher_service/thread/check_status.py）