@dsh-gis/dsh-video-studio-skill 0.6.0 → 0.8.1

package/skills/video-studio/scripts/gates.py

@@ -54,13 +54,41 @@ def _sha1_file(path):
         return "missing"
 
 
-def content_hash(script=None, scenes_path="", script_path="", engine="pil"):
-    """本次渲染的"内容身份"：剧本 + 场景代码 + 引擎。
+WEB_ASSET_EXT = (".js", ".mjs", ".html")
+# web 引擎的画面逻辑在页面脚本里，不在 scenes.py 里。这几个后缀按文件名排序后逐个取
+# sha1，再合并成一个指纹；不含 .css（样式改动不影响"画面语义"，也确实常见于调色试错）。
+
+
+def web_asset_fingerprint(entry):
+    """入口页面同目录下 .js/.mjs/.html 的内容指纹（按文件名排序后拼接）。
+
+    返回 (combined, files)：combined 是 16 位 hex（目录读不了返回 "missing"）；
+    files 是参与计算的 [文件名]，只用于报告/排错，不进指纹（避免绝对路径进 hash）。
+    """
+    if not entry:
+        return "missing", []
+    d = os.path.dirname(os.path.abspath(str(entry)))
+    try:
+        names = sorted(n for n in os.listdir(d) if n.lower().endswith(WEB_ASSET_EXT))
+    except OSError:
+        return "missing", []
+    if not names:
+        return "missing", []
+    rows = []
+    for n in names:
+        rows.append("%s:%s" % (n, _sha1_file(os.path.join(d, n))))
+    return _sha1_text("\n".join(rows)), names
+
+
+def content_hash(script=None, scenes_path="", script_path="", engine="pil", web_entry=""):
+    """本次渲染的"内容身份"：剧本 + 场景代码 + 引擎（web 时再加页面脚本）。
 
     只取与"这一版画面/声音"相关的量：
       * 剧本：去掉渲染期注入的 _path/_dir/_style 等私有键后规范化 json；
       * scenes.py：文件内容（画面逻辑变了，旧签核就得失效）；
-      * engine：pil 与 web 是两条渲染路径，产物不可互换。
+      * engine：pil 与 web 是两条渲染路径，产物不可互换；
+      * web_entry：engine=web 时，入口页同目录的 .js/.mjs/.html 一起算。
+        **pil 路线不参与**——否则老 PIL 项目每次升级都会被判"内容已变"，签核无故失效。
     """
     body = {}
     if isinstance(script, dict):
@@ -68,27 +96,40 @@ def content_hash(script=None, scenes_path="", script_path="", engine="pil"):
             if str(k).startswith("_"):
                 continue
             body[k] = v
+    eng = str(engine or "pil")
     payload = {
         "script": _sha1_text(json.dumps(body, sort_keys=True, ensure_ascii=False, default=str)),
         "script_file": _sha1_file(script_path) if script_path else "",
         "scenes": _sha1_file(scenes_path) if scenes_path else "",
-        "engine": str(engine or "pil"),
+        "engine": eng,
     }
+    if eng == "web":
+        assets, _names = web_asset_fingerprint(web_entry)
+        payload["web_assets"] = assets
     return _sha1_text(json.dumps(payload, sort_keys=True))
 
 
 class GateLedger:
     """一次运行内的门禁账本（多 stage 共用；--stage all 时是同一个对象）。"""
 
-    def __init__(self, work, script=None, scenes_path="", script_path="", engine="pil"):
+    def __init__(self, work, script=None, scenes_path="", script_path="", engine="pil",
+                 web_entry="", run_id=""):
         self.work = str(work or "work")
         self.items = []
         self.t0 = time.time()
+        # v0.8：run_id 是"这一版"的标签（--run-id）。没给就按时间戳生成，
+        # 保证每次运行在 work/runs/<runId>/ 下都有独立记录，而不是互相覆盖。
+        self.run_id = str(run_id or "").strip() or time.strftime("r%Y%m%d-%H%M%S")
         self.script = script or {}
         self.scenes_path = str(scenes_path or "")
         self.script_path = str(script_path or "")
         self.engine = str(engine or "pil")
-        self.content_hash = content_hash(script, self.scenes_path, self.script_path, self.engine)
+        self.web_entry = str(web_entry or "")
+        self.web_assets = []
+        self.content_hash = content_hash(script, self.scenes_path, self.script_path,
+                                         self.engine, web_entry=self.web_entry)
+        if self.engine == "web":
+            _fp, self.web_assets = web_asset_fingerprint(self.web_entry)
         self.bypassed = []          # --no-gate 绕过的记录（必须留痕）
 
     # ---- 记账 ----
@@ -142,9 +183,30 @@ class GateLedger:
 
     # ---- 落盘 ----
     def to_dict(self):
-        return dict(schema=SCHEMA, at=self.t0, contentHash=self.content_hash,
-                    engine=self.engine, counts=self.counts(),
-                    items=list(self.items), bypassed=list(self.bypassed))
+        d = dict(schema=SCHEMA, at=self.t0, contentHash=self.content_hash,
+                 runId=self.run_id,
+                 engine=self.engine, counts=self.counts(),
+                 items=list(self.items), bypassed=list(self.bypassed),
+                 inputs=self.input_fingerprints())
+        if self.engine == "web":
+            # 审计用：让用户/CI 能看出这个指纹到底盖了哪些页面脚本（不进 hash，绝对路径不外泄）
+            d["webAssets"] = list(self.web_assets)
+        return d
+
+    def input_fingerprints(self):
+        """输入指纹快照（v0.8）：剧本 / scenes / 词级 / 本脚本。
+
+        为什么要单独记：contentHash 是"一个 16 位 hex"，能判"变了没"，但**说不出
+        变了哪个**。批量出片时最常见的问题是"这条用的还是上一版的词级时间戳"，
+        有个逐项指纹才能在事后对账（也让 QT 报告能标出"本次跑的是哪一版输入"）。
+        """
+        return {
+            "script": _sha1_file(self.script_path) if self.script_path else "missing",
+            "scenes": _sha1_file(self.scenes_path) if self.scenes_path else "missing",
+            "words": _sha1_file(os.path.join(self.work, "words.json")),
+            "gates_py": _sha1_file(os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                                "filmkit.py")),
+        }
 
     def write_json(self):
         """work/gates.json —— 给程序读（QC-REPORT.md 只是它的渲染层）。"""
@@ -156,6 +218,37 @@ class GateLedger:
         return p
 
 
+def archive_run(work, ledger, artifacts=None, report_path=None):
+    """把"这一版"的账本快照归档到 work/runs/<runId>/（v0.8）。
+
+    只归档**小文件**（gates.json / QC-REPORT.md / run.json）。视频/音频/分块体积大，
+    就地保留即可——这里要解决的是"跑了几版之后，谁都说不清上一版的门禁结论是什么"，
+    不是备份媒体。返回 run 目录。
+    """
+    d = os.path.join(str(work), "runs", str(ledger.run_id))
+    try:
+        os.makedirs(d, exist_ok=True)
+    except OSError as e:                                    # noqa: BLE001
+        return "", "建目录失败：%s" % e
+    info = dict(runId=ledger.run_id, at=ledger.t0,
+                atText=time.strftime("%Y-%m-%d %H:%M:%S"),
+                contentHash=ledger.content_hash, counts=ledger.counts(),
+                inputs=ledger.input_fingerprints(),
+                artifacts=[str(x) for x in (artifacts or [])])
+    _atomic_json(os.path.join(d, "run.json"), info)
+    for src, name in ((os.path.join(str(work), "gates.json"), "gates.json"),
+                      (str(report_path or ""), "QC-REPORT.md")):
+        try:
+            if src and os.path.exists(src):
+                with open(src, "rb") as fh:
+                    data = fh.read()
+                with open(os.path.join(d, name), "wb") as fh:
+                    fh.write(data)
+        except OSError:
+            pass
+    return d, ""
+
+
 # ---------------------------------------------------------------- 签核账本
 def signoff_path(work):
     return os.path.join(str(work), "signoff.json")
@@ -288,9 +381,22 @@ def render_report(work, out=None):
     ch = str(g.get("contentHash") or "")
     items = list(g.get("items") or [])
     counts = {OK: 0, FAIL: 0, SKIP: 0}
+    # 坏条目必须先归到"不通过"里，不能让它从三种计数里漏出去：
+    # 以前 st 不是 pass/fail/skipped 时 counts 只加了个 count[x]，而结论分支只看
+    # counts[FAIL] / counts[SKIP] —— 于是 "status": "warn"（或大小写写错、null）
+    # 的条目在矩阵里照样列出来，结论却写"所有门禁本次都执行且通过"。
+    # 这正是本模块开头要防的"看起来干净、其实没在查"，所以未知状态一律按 fail 计。
+    bad_items = 0
     for x in items:
-        st = x.get("status", SKIP)
-        counts[st] = counts.get(st, 0) + 1
+        if not isinstance(x, dict):
+            bad_items += 1
+            continue
+        st = x.get("status")
+        if st not in (OK, FAIL, SKIP):
+            bad_items += 1
+            counts[FAIL] += 1
+            continue
+        counts[st] += 1
     state, stale = signoff_state(work, ch)
     signed_n = sum(1 for v in state.values() if v["status"] == OK)
 
@@ -304,11 +410,20 @@ def render_report(work, out=None):
     L.append("| 项 | 值 |")
     L.append("|---|---|")
     L.append("| 内容指纹 | `%s` |" % (ch or "未生成"))
+    L.append("| 运行编号 | `%s` |" % (g.get("runId") or "-"))
     L.append("| 引擎 | `%s` |" % (g.get("engine") or "-"))
+    _inp = g.get("inputs") or {}
+    if _inp:
+        L.append("| 输入指纹 | script `%s` · scenes `%s` · words `%s` |"
+                 % (_inp.get("script", "-"), _inp.get("scenes", "-"),
+                    _inp.get("words", "-")))
     L.append("| 生成时间 | %s |"
              % time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(g.get("at") or time.time())))
     L.append("| 门禁合计 | pass %d · fail %d · skipped %d |"
              % (counts.get(OK, 0), counts.get(FAIL, 0), counts.get(SKIP, 0)))
+    if bad_items:
+        L.append("| 账本损坏条目 | %d 条（status 不是 pass/fail/skipped）——按 fail 计 |"
+                 % bad_items)
     L.append("| 人工签核 | %d/%d 有效 |" % (signed_n, len(GATE_ORDER)))
     L.append("")
     L.append("## 一、门禁矩阵")
@@ -317,6 +432,12 @@ def render_report(work, out=None):
         L.append("| 门禁 | 判据 | 结果 | 实测 / 说明 |")
         L.append("|---|---|---|---|")
         for x in items:
+            if not isinstance(x, dict):
+                # 坏条目不能让整份报告炸掉（.get 会 AttributeError，_finish_gates 只
+                # 打一行 WARN，交付目录里就没有 QC-REPORT.md 了）：照实列成一行。
+                L.append("| `?` | （账本条目损坏） | **fail** | %r |"
+                         % (str(x)[:60].replace("|", "\\|"),))
+                continue
             L.append("| `%s` | %s | **%s** | %s |"
                      % (x.get("id", "?"), x.get("title", ""), x.get("status", "?"),
                         (x.get("detail") or "-").replace("|", "\\|")))
@@ -334,7 +455,8 @@ def render_report(work, out=None):
                     (v.get("detail") or "-").replace("|", "\\|")))
     if stale:
         L.append("")
-        L.append("> 内容已变的签核：%s（改了剧本 / scenes.py / 引擎，旧签核自动失效，需重新签）"
+        L.append("> 内容已变的签核：%s（改了剧本 / scenes.py / 引擎 / web 页面脚本，"
+                 "旧签核自动失效，需重新签）"
                  % "、".join("`%s`" % x for x in stale))
     L.append("")
     L.append("## 三、耗时台账（`work/cost.jsonl` 实测，非估算）")
@@ -366,8 +488,23 @@ def render_report(work, out=None):
         nxt = "四"
     L.append("## %s、结论（照抄，别自己发挥）" % nxt)
     L.append("")
-    if counts.get(FAIL):
+    if not items:
+        # 没有门禁记录 ≠ 全部通过。以前这里落到 else 分支打印"**通过**"，
+        # 于是 gates.json 被删 / 写坏 / 根本没跑 qa 时，QC-REPORT.md 会是一份
+        # 宣称通过的交付凭据——正是本模块开头要防的"看起来干净、其实没在查"。
+        if not os.path.exists(gj):
+            why = "没有 %s（本次没有跑过任何 stage，或 work/ 目录已丢）" % gj
+        else:
+            why = "%s 读不出来 / 里面 0 条门禁（JSON 损坏或并发写坏）" % gj
+        L.append("- **未判定**：%s。**这不等于通过**——先跑 --stage qa（或 --stage all）"
+                 "产出真实门禁再交付。" % why)
+    elif counts.get(FAIL):
         L.append("- **未通过**：fail %d 项，按上表逐条修，别宣称完成。" % counts.get(FAIL))
+    elif bad_items:
+        # 条目损坏 / 状态值不认识：既不能算"通过"，也不该说成"查了没过"。
+        L.append("- **未判定**：账本里有 %d 条损坏的记录（不是合法 dict 或 status 不是 "
+                 "pass/fail/skipped），无法判断这些门禁到底查没查、过没过。"
+                 "**这不等于通过**——重跑 --stage qa 重新产出账本。" % bad_items)
     elif counts.get(SKIP):
         L.append("- **有条件通过**：skipped %d 项（明确没执行），交付时必须逐项说明原因。"
                  % counts.get(SKIP))
@@ -439,7 +576,17 @@ if __name__ == "__main__":
         p = write_report(a.work, a.out or None)
         print("[QC 报告]", p)
         if a.json:
-            print(json.dumps(GateLedger(a.work).to_dict(), ensure_ascii=False, indent=1))
+            # 读磁盘上的账本，别现场 new 一个空的：GateLedger(work) 不传剧本时
+            # contentHash 是按空剧本算的，打出来的 JSON 跟 work/gates.json 对不上、
+            # items 永远是 [] —— 机读输出等于撒谎。
+            gp = os.path.join(str(a.work), "gates.json")
+            try:
+                with open(gp, encoding="utf-8") as fh:
+                    print(json.dumps(json.load(fh), ensure_ascii=False, indent=1))
+            except (OSError, json.JSONDecodeError) as err:
+                print(json.dumps(dict(ok=False, work=str(a.work),
+                                      error="没有可读的 %s：%s" % (gp, err)),
+                                 ensure_ascii=False, indent=1))
         sys.exit(0)
     except (ValueError, OSError) as e:
         print("[ERROR] %s" % e, file=sys.stderr)