honeydo 0.1.0

package/packages/lmedia/python/edit.py

@@ -0,0 +1,107 @@
+"""edit.py - 参考图编辑驱动（QwenImageEditPlusPipeline，1+ 张参考图）。
+ * 直跑：argv[1] = JSON {prompt, out, snapshotEdit, refs: [path...], width, height, steps, trueCfg, neg, seed,
+ *                        loras?: [{path, scale}], lightningSched?: bool, teaCache?: {thresh}|true}
+ * serve.py 复用：load_pipe / run（daemon 常驻热路径）
+ *   trueCfg: true CFG 强度（官方 Edit-2511 配方 4.0；<=1 无引导——旧版行为/蒸馏 LoRA 路径）
+ *   neg: 负向提示词（官方编辑配方默认 " "，trueCfg>1 时才下发）
+ *   loras: LoRA 叠加（如 lightningedit2511 蒸馏加速，scale 固定 1.0）
+ *   lightningSched: Lightning 蒸馏专用调度器（base_shift=max_shift=ln3、shift_terminal=None；
+ *                   蒸馏分布外 shift 区间 0.5-0.9 会掉质——官方 generate_with_diffusers.py 同款配置）
+ *   teaCache: TeaCache 步缓存（teacache.py；质量近似无损加速， thresh 缺省 0.2）
+ * 出参：stdout 最后一行 JSON {out, seconds, teaCache?}
+ * 历史坑：guidance_scale 被 diffusers 静默忽略，真实旋钮 true_cfg_scale+negative_prompt——2026-08 修复。
+"""
+import json
+import math
+import os
+import sys
+import time
+
+import torch
+from diffusers import FlowMatchEulerDiscreteScheduler, QwenImageEditPlusPipeline
+from PIL import Image
+
+# Lightning 蒸馏 LoRA 调度器（与 gen.py 同名定义逐字段一致；改参数两处需同步——serve.py 用 gen 的）
+LIGHTNING_SCHEDULER_CONFIG = {
+    "base_image_seq_len": 256,
+    "base_shift": math.log(3),
+    "invert_sigmas": False,
+    "max_image_seq_len": 8192,
+    "max_shift": math.log(3),
+    "num_train_timesteps": 1000,
+    "shift": 1.0,
+    "shift_terminal": None,
+    "stochastic_sampling": False,
+    "time_shift_type": "exponential",
+    "use_beta_sigmas": False,
+    "use_dynamic_shifting": True,
+    "use_exponential_sigmas": False,
+    "use_karras_sigmas": False,
+}
+
+
+def load_pipe(
+    snapshot_edit: str, loras: list | None = None, lightning_sched: bool = False
+) -> QwenImageEditPlusPipeline:
+    """from_pretrained(bf16) → LoRA（CPU 上，须在 to("mps") 前）→ 可选蒸馏调度器 → to("mps")。"""
+    pipe = QwenImageEditPlusPipeline.from_pretrained(snapshot_edit, torch_dtype=torch.bfloat16)
+    if loras:
+        names = []
+        for i, l in enumerate(loras):
+            name = f"l{i}"
+            pipe.load_lora_weights(l["path"], adapter_name=name)
+            names.append(name)
+        pipe.set_adapters(names, adapter_weights=[l.get("scale", 1.0) for l in loras])
+    if lightning_sched:
+        pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(LIGHTNING_SCHEDULER_CONFIG)
+    return pipe.to("mps")
+
+
+def run(pipe: QwenImageEditPlusPipeline, cfg: dict) -> dict:
+    """一次编辑并落盘，返回结果 dict（不 print）。
+    refVaeSize: 实验开关——monkeypatch 管线 VAE_IMAGE_SIZE（官方 1024² 面积），
+    参考图 token 占序列 ~64%（4ref@2048），降面积是出版档候选加速；任务后恢复原值（daemon 安全）。"""
+    from teacache import apply_teacache
+
+    tc = apply_teacache(pipe, cfg)
+    t0 = time.time()
+    true_cfg = float(cfg.get("trueCfg", 1.0))
+    neg = cfg.get("neg") if true_cfg > 1.0 else None
+    refs = [Image.open(p).convert("RGB") for p in cfg["refs"]]
+
+    import diffusers.pipelines.qwenimage.pipeline_qwenimage_edit_plus as plus_mod
+
+    old_vae_size = plus_mod.VAE_IMAGE_SIZE
+    if cfg.get("refVaeSize"):
+        plus_mod.VAE_IMAGE_SIZE = int(cfg["refVaeSize"])
+    try:
+        img = pipe(
+            image=refs,
+            prompt=cfg["prompt"],
+            negative_prompt=neg,
+            true_cfg_scale=true_cfg,
+            width=cfg.get("width", 1664),
+            height=cfg.get("height", 928),
+            num_inference_steps=cfg.get("steps", 20),
+            generator=torch.Generator(device="mps").manual_seed(cfg.get("seed", 42)),
+        ).images[0]
+    finally:
+        plus_mod.VAE_IMAGE_SIZE = old_vae_size
+    img.save(cfg["out"])
+    result = {"out": cfg["out"], "seconds": round(time.time() - t0, 1)}
+    if tc is not None:
+        result["teaCache"] = tc.stats()
+    if cfg.get("refVaeSize"):
+        result["refVaeSize"] = int(cfg["refVaeSize"])
+    return result
+
+
+def main() -> None:
+    cfg = json.loads(sys.argv[1])
+    os.environ.setdefault("HF_HUB_OFFLINE", "1")
+    pipe = load_pipe(cfg["snapshotEdit"], cfg.get("loras"), bool(cfg.get("lightningSched")))
+    print(json.dumps(run(pipe, cfg), ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/packages/lmedia/python/esrgan_path.py

@@ -0,0 +1,16 @@
+"""Real-ESRGAN 权重路径解析：env LMEDIA_REALESRGAN_PATH > ~/.cache/lmedia/ > 历史 /tmp 位"""
+import os
+
+CACHE_PATH = os.path.expanduser("~/.cache/lmedia/RealESRGAN_x2.pth")
+LEGACY_TMP_PATH = "/tmp/RealESRGAN_x2.pth"
+
+
+def resolve_esrgan_path() -> str:
+    env = os.environ.get("LMEDIA_REALESRGAN_PATH")
+    if env and os.path.exists(env):
+        return env
+    if os.path.exists(CACHE_PATH):
+        return CACHE_PATH
+    if os.path.exists(LEGACY_TMP_PATH):
+        return LEGACY_TMP_PATH
+    return env or CACHE_PATH

package/packages/lmedia/python/gen.py

@@ -0,0 +1,131 @@
+"""gen.py - 文生图驱动（diffusers bf16 + LoRA 叠加 + 可选超分）。
+ * 直跑：argv[1] = JSON {prompt, out, snapshot, width, height, steps, trueCfg, neg, num, seed,
+ *                        loras: [{path, scale}], lightningSched?: bool, teaCache?: {thresh}|true,
+ *                        upscaleTo?: [w,h], esrganModel?}
+ * serve.py 复用：load_pipe / load_esrgan / run（daemon 常驻热路径，免每次 ~2min 冷加载）
+ *   trueCfg: true CFG 强度（官方推荐 4.0；<=1 无引导——旧版行为；蒸馏 LoRA 路径用 1.0）
+ *   neg: 负向提示词（trueCfg>1 时才下发；官方 2512 中文负向模板由 CLI 层注入）
+ *   num: 一次生成张数（1-4），输出 out-1.png..out-N.png
+ *   lightningSched: Lightning 蒸馏专用调度器（base_shift=max_shift=ln3、shift_terminal=None；
+ *                   用默认调度器跑蒸馏 LoRA 是分布外，会掉质——2026-08-29 修复 --fast 遗漏）
+ *   teaCache: TeaCache 步缓存（teacache.py；质量近似无损加速，thresh 缺省 0.2）
+ * 出参：stdout 最后一行 JSON {out, seconds, upscaled?, outs?, teaCache?}（num=1 形状与旧版一致）
+ * 历史坑：guidance_scale 参数被 diffusers 静默忽略（仅 guidance-distilled 模型生效），
+ *         真实旋钮是 true_cfg_scale，且必须传 negative_prompt 才启用——2026-08 修复。
+ """
+import json
+from esrgan_path import resolve_esrgan_path
+import math
+import os
+import sys
+import time
+
+import torch
+from diffusers import FlowMatchEulerDiscreteScheduler, QwenImagePipeline
+from PIL import Image
+
+# Lightning 蒸馏 LoRA 调度器（shift=3 蒸馏分布；官方 generate_with_diffusers.py 同款）
+LIGHTNING_SCHEDULER_CONFIG = {
+    "base_image_seq_len": 256,
+    "base_shift": math.log(3),
+    "invert_sigmas": False,
+    "max_image_seq_len": 8192,
+    "max_shift": math.log(3),
+    "num_train_timesteps": 1000,
+    "shift": 1.0,
+    "shift_terminal": None,
+    "stochastic_sampling": False,
+    "time_shift_type": "exponential",
+    "use_beta_sigmas": False,
+    "use_dynamic_shifting": True,
+    "use_exponential_sigmas": False,
+    "use_karras_sigmas": False,
+}
+
+
+def load_pipe(snapshot: str, loras: list | None = None, lightning_sched: bool = False) -> QwenImagePipeline:
+    """from_pretrained(bf16) → LoRA（CPU 上加载，须在 to("mps") 前）→ 可选蒸馏调度器 → to("mps")。"""
+    pipe = QwenImagePipeline.from_pretrained(snapshot, torch_dtype=torch.bfloat16)
+    if loras:
+        names = []
+        for i, l in enumerate(loras):
+            name = f"l{i}"
+            pipe.load_lora_weights(l["path"], adapter_name=name)
+            names.append(name)
+        pipe.set_adapters(names, adapter_weights=[l.get("scale", 1.0) for l in loras])
+    if lightning_sched:
+        pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(LIGHTNING_SCHEDULER_CONFIG)
+    return pipe.to("mps")
+
+
+def load_esrgan(path: str | None = None):
+    """Real-ESRGAN x2（spandrel，MPS）——懒加载，权重缺文件时抛错（doctor 有检查项）。"""
+    from spandrel import ModelLoader
+
+    return ModelLoader().load_from_file(path or resolve_esrgan_path()).to("mps").eval()
+
+
+def run(pipe: QwenImagePipeline, cfg: dict, sr=None) -> dict:
+    """一次生成并落盘，返回结果 dict（不 print——print 由调用方/直跑 main 做）。
+    sr: 预载 ESRGAN 模型（daemon 复用）；upscaleTo 存在且 sr=None 时现场加载。"""
+    from teacache import apply_teacache
+
+    tc = apply_teacache(pipe, cfg)
+    t0 = time.time()
+    true_cfg = float(cfg.get("trueCfg", 1.0))
+    neg = cfg.get("neg") if true_cfg > 1.0 else None  # 无引导路径不传负向，避免 diffusers 警告
+    num = int(cfg.get("num", 1))
+    images = pipe(
+        prompt=cfg["prompt"],
+        negative_prompt=neg,
+        true_cfg_scale=true_cfg,
+        width=cfg.get("width", 1664),
+        height=cfg.get("height", 928),
+        num_inference_steps=cfg.get("steps", 20),
+        num_images_per_prompt=num,
+        generator=torch.Generator(device="mps").manual_seed(cfg.get("seed", 42)),
+    ).images
+
+    up = cfg.get("upscaleTo")
+    if up and sr is None:
+        sr = load_esrgan(cfg.get("esrganModel"))
+    if up:
+        import numpy as np
+
+    outs = []
+    for i, im in enumerate(images, start=1):
+        if up:
+            arr = np.array(im.convert("RGB")).astype(np.float32) / 255.0
+            t = torch.from_numpy(arr).permute(2, 0, 1).unsqueeze(0).to("mps")
+            with torch.no_grad():
+                out_t = sr(t)
+            im = Image.fromarray(
+                (out_t.squeeze(0).permute(1, 2, 0).clamp(0, 1).cpu().numpy() * 255).astype("uint8")
+            ).resize((up[0], up[1]), Image.LANCZOS)
+        if num == 1:
+            p = cfg["out"]
+        else:
+            root, ext = os.path.splitext(cfg["out"])
+            p = f"{root}-{i}{ext or '.png'}"
+        im.save(p)
+        outs.append(p)
+
+    result = {"out": outs[0], "seconds": round(time.time() - t0, 1)}
+    if num > 1:
+        result["outs"] = outs
+    if up:
+        result["upscaled"] = up
+    if tc is not None:
+        result["teaCache"] = tc.stats()
+    return result
+
+
+def main() -> None:
+    cfg = json.loads(sys.argv[1])
+    os.environ.setdefault("HF_HUB_OFFLINE", "1")
+    pipe = load_pipe(cfg["snapshot"], cfg.get("loras"), bool(cfg.get("lightningSched")))
+    print(json.dumps(run(pipe, cfg), ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/packages/lmedia/python/serve.py

@@ -0,0 +1,352 @@
+"""serve.py — 常驻推理 daemon（stdlib-only unix socket，NDJSON 帧）。
+ * 由 TS 侧 `lmedia image serve start` 或 gen/edit 自动拉起；路径全部由 argv 传入。
+ * 顺序关键：bind+listen **先于** import torch/加载模型——加载期（~2min）客户端连接进
+ * backlog 排队，首任务等加载完执行，不回退冷路径。
+ * 线程模型：dispatcher（主线程 accept + 每连接轻线程读请求/排队/ping）
+ *          + worker（唯一碰 torch 的线程，串行消费任务队列 ← GPU 串行铁律的代码化）
+ *          + watchdog（空闲自退）
+ * 协议：请求一行 JSON {"kind": "gen|edit|upscale|ping", ...}；
+ *       响应 0..n 个 {"t":"queued"|"log"} 帧 + 恰好 1 个 {"t":"done", ok, result|error} 帧后 close。
+ * 退出：TERM/idle 统一 unlink socket+status → os._exit(0)（绕过 MPS 退出清理挂死——2026-08 实录坑）。
+ * 依赖 gen.py/edit.py/upscale.py 的 load_pipe/run 函数（同目录 import，脚本目录自动在 sys.path）。
+"""
+import argparse
+import contextlib
+import gc
+import json
+from esrgan_path import resolve_esrgan_path
+import os
+import queue
+import re
+import signal
+import socket
+import sys
+import threading
+import time
+import traceback
+
+REQUEST_LIMIT = 8 << 20  # 单行请求上限 8MB（正常 payload 10KB 级）
+MAX_ADAPTERS = 4         # LoRA adapter 缓存上限（单个几百 MB，防无限累积）
+
+STATE = {
+    "pid": os.getpid(), "mode": None, "state": "boot",  # boot|loading|ready|busy
+    "busy": False, "queue": 0, "jobs": 0,
+    "lastJobAt": None, "startedAt": None, "snapshot": None,
+}
+JOBS: "queue.Queue[tuple]" = queue.Queue()
+EXITING = threading.Event()
+SRV: socket.socket | None = None
+LOG = None            # logfile 句柄（daemon 自身输出）
+SOCK_PATH = STATUS_PATH = None
+
+# —— worker 线程内初始化（延迟 import torch 后才存在）——
+PIPE = None           # QwenImagePipeline | QwenImageEditPlusPipeline
+SR = None             # (path, spandrel model) upscale 懒加载缓存
+GEN_SR = None         # gen 内联超分（upscaleTo）懒加载
+LOADED: dict[str, str] = {}   # adapter_name -> abspath
+_ADAPTER_SEQ = 0
+CUR_LIGHTNING = False
+SCHED_DEFAULT_CONFIG = None   # load 后的默认调度器 config（任务间恢复用）
+
+
+def log(msg: str) -> None:
+    if LOG:
+        LOG.write(f"[{time.strftime('%H:%M:%S')}] {msg}\n")
+
+
+def write_status() -> None:
+    tmp = STATUS_PATH + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(STATE, f, ensure_ascii=False)
+    os.replace(tmp, STATUS_PATH)
+
+
+def send(conn, frame: dict) -> None:
+    """发一帧；对端已死（EPIPE）吞掉——任务照常算完，结果丢弃。"""
+    try:
+        conn.sendall((json.dumps(frame, ensure_ascii=False) + "\n").encode())
+    except OSError:
+        pass
+
+
+class ClientWriter:
+    """redirect_stdout/stderr 用：任务输出按 \\n 与 \\r 切帧转发客户端 + 落日志（tqdm 进度条走 \\r）。"""
+
+    def __init__(self, conn):
+        self.conn = conn
+        self.tail = ""
+
+    def write(self, s: str) -> int:
+        self.tail += s
+        parts = re.split(r"[\r\n]+", self.tail)
+        self.tail = parts.pop()
+        for p in parts:
+            if p.strip():
+                send(self.conn, {"t": "log", "line": p})
+                log(f"  | {p}")
+        return len(s)
+
+    def flush(self) -> None:
+        pass
+
+
+def readline(conn, limit: int = REQUEST_LIMIT) -> bytes | None:
+    buf = b""
+    while b"\n" not in buf:
+        if len(buf) > limit:
+            return None
+        try:
+            chunk = conn.recv(65536)
+        except OSError:
+            return None
+        if not chunk:
+            return None
+        buf += chunk
+    return buf.split(b"\n", 1)[0]
+
+
+def status_snapshot() -> dict:
+    return {**STATE, "queue": JOBS.qsize(), "kind": "ping"}
+
+
+def handle_conn(conn) -> None:
+    """dispatcher 派生的轻线程：读请求/排队/ping，不碰 torch。"""
+    try:
+        line = readline(conn)
+        if line is None:
+            conn.close()
+            return
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            send(conn, {"t": "done", "ok": False, "error": "请求不是合法 JSON"})
+            conn.close()
+            return
+        kind = req.get("kind")
+        if kind == "ping":
+            send(conn, {"t": "done", "ok": True, "result": status_snapshot()})
+            conn.close()
+            return
+        if kind not in ("gen", "edit", "upscale"):
+            send(conn, {"t": "done", "ok": False, "error": f"未知 kind: {kind}"})
+            conn.close()
+            return
+        send(conn, {"t": "queued", "position": JOBS.qsize() + 1})
+        JOBS.put((conn, req))
+    except Exception:
+        traceback.print_exc(file=LOG)
+        try:
+            conn.close()
+        except OSError:
+            pass
+
+
+def apply_loras(pipe, loras: list | None) -> None:
+    """LoRA 热切换（gen/edit 通用）。peft 后端下 adapter 是旁路模块、base 权重不被改写，
+    set_adapters 只切激活集与 scale（毫秒级）；未加载过的文件在常驻 pipe 上直接 load。"""
+    global _ADAPTER_SEQ
+    import torch
+
+    req = [(os.path.abspath(l["path"]), float(l.get("scale", 1.0))) for l in (loras or [])]
+    if not req:
+        if LOADED:
+            pipe.disable_lora()  # 不用 set_adapters([])：空列表语义跨版本不稳
+        return
+    by_path = {p: n for n, p in LOADED.items()}
+    missing = [p for p, _ in req if p not in by_path]
+    if missing and len(LOADED) + len(missing) > MAX_ADAPTERS:
+        pipe.unload_lora_weights()
+        LOADED.clear()
+        gc.collect()
+        torch.mps.empty_cache()
+        by_path = {}
+        missing = [p for p, _ in req]
+    for p in missing:
+        _ADAPTER_SEQ += 1
+        name = f"a{_ADAPTER_SEQ}"
+        pipe.load_lora_weights(p, adapter_name=name)
+        LOADED[name] = p
+        by_path[p] = name
+        log(f"lora loaded: {name} <- {p}")
+    pipe.enable_lora()
+    pipe.set_adapters([by_path[p] for p, _ in req], [s for _, s in req])
+
+
+def apply_scheduler(pipe, lightning: bool) -> None:
+    """Lightning 蒸馏调度器 per-job 切换/恢复（配置常量 import 自 gen.py——与 edit.py 内
+    同名定义逐字段一致，改调度参数时两处需同步）。"""
+    global CUR_LIGHTNING
+    if lightning == CUR_LIGHTNING:
+        return
+    from diffusers import FlowMatchEulerDiscreteScheduler
+    import gen as G
+
+    pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(
+        G.LIGHTNING_SCHEDULER_CONFIG if lightning else SCHED_DEFAULT_CONFIG
+    )
+    CUR_LIGHTNING = lightning
+
+
+def run_job(req: dict) -> dict:
+    kind = req["kind"]
+    if kind == "gen":
+        import gen as G
+        global GEN_SR
+        apply_loras(PIPE, req.get("loras"))
+        apply_scheduler(PIPE, bool(req.get("lightningSched")))
+        if req.get("upscaleTo") and GEN_SR is None:
+            GEN_SR = G.load_esrgan(req.get("esrganModel"))
+        return G.run(PIPE, req, sr=GEN_SR)
+    if kind == "edit":
+        import edit as E
+        apply_loras(PIPE, req.get("loras"))
+        apply_scheduler(PIPE, bool(req.get("lightningSched")))
+        return E.run(PIPE, req)
+    if kind == "upscale":
+        import upscale as U
+        global SR
+        path = req.get("model") or resolve_esrgan_path()
+        if SR is None or SR[0] != path:
+            SR = (path, U.load_model(path))
+        return U.run(SR[1], req)
+    raise ValueError(f"未知 kind: {kind}")
+
+
+def worker(mode: str, snapshot: str) -> None:
+    """唯一碰 torch 的线程：加载模型 → 串行消费任务队列。"""
+    global PIPE, SCHED_DEFAULT_CONFIG, STATE
+    import torch  # —— 重 import 从这里才开始（bind 已完成，客户端在 backlog 排队）——
+
+    STATE["state"] = "loading"
+    write_status()
+    log(f"loading pipeline mode={mode} snapshot={snapshot}")
+    t0 = time.time()
+    if mode == "gen":
+        import gen as G
+        PIPE = G.load_pipe(snapshot)
+    else:
+        import edit as E
+        PIPE = E.load_pipe(snapshot)
+    SCHED_DEFAULT_CONFIG = dict(PIPE.scheduler.config)
+    STATE.update(state="ready", startedAt=time.time(), lastJobAt=time.time())
+    write_status()
+    log(f"ready（加载 {time.time() - t0:.1f}s）")
+
+    while True:
+        conn, req = JOBS.get()
+        STATE.update(busy=True, state="busy", queue=JOBS.qsize())
+        write_status()
+        log(f"job #{STATE['jobs'] + 1} kind={req['kind']} out={req.get('out') or req.get('in')}")
+        t0 = time.time()
+        try:
+            with contextlib.redirect_stdout(ClientWriter(conn)), contextlib.redirect_stderr(
+                ClientWriter(conn)
+            ):
+                result = run_job(req)
+            send(conn, {"t": "done", "ok": True, "result": result})
+            log(f"job done in {time.time() - t0:.1f}s")
+        except Exception as e:
+            tb = traceback.format_exc()[-2000:]
+            log(f"job FAILED in {time.time() - t0:.1f}s: {e}\n{tb}")
+            send(conn, {"t": "done", "ok": False, "error": str(e), "tb": tb})
+        finally:
+            try:
+                conn.close()
+            except OSError:
+                pass
+            STATE.update(busy=False, state="ready", jobs=STATE["jobs"] + 1, lastJobAt=time.time())
+            write_status()
+            gc.collect()
+            torch.mps.empty_cache()  # 保权重，释放激活/allocator 缓存块
+
+
+def shutdown_and_exit() -> None:
+    """统一退出路径。unlink 先行——dispatcher 主线程在 EXITING.set() 后即退出 main 并冻结
+    本 daemon 线程，清理动作若排在 sleep 后会被竞态跳过（2026-08-30 实录：idle 自退残留 socket）。
+    unlink 后新 connect 得 ENOENT → 客户端冷路径，行为等价于关 listen。"""
+    EXITING.set()
+    for p in (SOCK_PATH, STATUS_PATH):
+        try:
+            os.unlink(p)
+        except OSError:
+            pass
+    if SRV:
+        try:
+            SRV.close()
+        except OSError:
+            pass
+    time.sleep(0.3)  # 让 in-flight 客户端收到断连（而非挂到进程树消亡）
+    log("exit")
+    os._exit(0)
+
+
+def watchdog(idle_timeout: float) -> None:
+    """空闲自退（默认 30min）：ready 且队列空且距上一任务超时。"""
+    while not EXITING.wait(15):
+        if STATE["busy"] or not JOBS.empty() or STATE["lastJobAt"] is None:
+            continue
+        idle = time.time() - STATE["lastJobAt"]
+        if idle > idle_timeout:
+            log(f"idle {idle:.0f}s > {idle_timeout:.0f}s，自退")
+            shutdown_and_exit()
+
+
+def on_term(signum, frame) -> None:
+    log(f"signal {signum}")
+    shutdown_and_exit()
+
+
+def bind_with_stale_probe(path: str) -> socket.socket:
+    """socket 文件已存在：probe connect 通=已有活实例（exit 3）；拒=陈旧残留（-9 遗物）清掉重绑。"""
+    if os.path.exists(path):
+        probe = socket.socket(socket.AF_UNIX)
+        try:
+            probe.connect(path)
+            probe.close()
+            print(f"已有一个 {path} 的活实例在运行", file=sys.stderr)
+            sys.exit(3)
+        except OSError:
+            os.unlink(path)
+    s = socket.socket(socket.AF_UNIX)
+    s.bind(path)
+    return s
+
+
+def main() -> None:
+    global LOG, SRV, SOCK_PATH, STATUS_PATH, STATE
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mode", choices=["gen", "edit"], required=True)
+    ap.add_argument("--socket", required=True)
+    ap.add_argument("--status", required=True)
+    ap.add_argument("--log", required=True)
+    ap.add_argument("--snapshot", required=True)
+    ap.add_argument("--idle-timeout", type=float, default=1800)
+    a = ap.parse_args()
+
+    os.makedirs(os.path.dirname(a.socket), exist_ok=True)
+    LOG = open(a.log, "a", buffering=1)
+    sys.stdout = sys.stderr = LOG  # daemon 自身输出全落日志（任务输出由 ClientWriter 定向）
+    SOCK_PATH, STATUS_PATH = a.socket, a.status
+    STATE.update(mode=a.mode, startedAt=time.time(), snapshot=a.snapshot)
+    write_status()
+    log(f"boot pid={os.getpid()} mode={a.mode} idle_timeout={a.idle_timeout}s")
+
+    srv = bind_with_stale_probe(a.socket)
+    srv.listen(128)
+    SRV = srv
+    signal.signal(signal.SIGTERM, on_term)
+    signal.signal(signal.SIGINT, on_term)
+
+    threading.Thread(target=worker, args=(a.mode, a.snapshot), daemon=True).start()
+    threading.Thread(target=watchdog, args=(a.idle_timeout,), daemon=True).start()
+
+    while not EXITING.is_set():  # 主线程 = dispatcher
+        try:
+            conn, _ = srv.accept()
+        except OSError:
+            break
+        threading.Thread(target=handle_conn, args=(conn,), daemon=True).start()
+
+
+if __name__ == "__main__":
+    main()