"""HTML 模板「JSON 填充」纯引擎 + 模板注册表。 定时任务的「模板数据转换器」内置 agent 把用户传入的任意 JSON 智能映射成某个 HTML 模板需要的 ``DATA`` 结构后,本模块负责把数据**填充**进模板并产出一份完整、 可预览的 HTML 文档。 设计要点 -------- * **模板自身即 schema 来源**:每个模板的 HTML 里都内嵌一行 ``const DATA={...};`` (台湾滨海防卫展示系统 no.1 还内嵌 ``const MANIFEST={...};``)。我们直接解析这行 拿到「参考数据」,既当**目标格式的范例**(喂给大模型),又当**结构校验**的基准 (顶层键 + 类型)。注册表因此不需要手写一份庞大的 schema 字面量,改模板即改契约。 * **行级安全替换**:模板把每个常量压在**单独一行**(``const DATA=...;`` 以分号结尾、 行内无换行),所以用 ``^const VAR=.*;$`` (MULTILINE) 精确命中该行整体替换,绝不 误伤模板里别处出现的同名子串。替换值用函数回调写入,避开 ``re.sub`` 把 JSON 里的 反斜杠当反向引用的坑。 * **结构化模板(kind="structured")**: no.1 起引入 page-generator 范式——目录含 ``template.html``(骨架,带 :data:`STRUCTURED_MARKERS` 注入标记)/``runtime.js`` (渲染逻辑 + 页面内 JSON 编辑器)/``data.json``(默认数据,兼作转换契约)/可选 ``manifest.json``。填充走 :func:`compose_structured` 标记组合,产物仍是自包含 单文件 HTML;``reference_data`` 读 ``data.json``,与单文件模板的契约/校验/合并 语义完全一致。 * **harness 层、零 app.* 依赖**:可被调度器(harness)与 Gateway 路由(app)共同 import。 公开入口:``list_templates`` / ``get_template`` / ``reference_data`` / ``schema_skeleton_json`` / ``validate_data`` / ``field_coverage_gaps`` / ``shape_mismatches`` / ``fill_template`` / ``invalidate_cache``。 模板来源(读取顺序):运行时存储 :mod:`.template_store` (``{base_dir}/html-templates//``,模板管理页可上传/编辑/新增,内置模板由 :func:`template_store.ensure_seeded` 启动 seed,缺失才复制、绝不覆盖修改)→ 随包 注册表 :data:`TEMPLATES`(下方静态清单)兜底。写操作经 ``template_store`` 完成, 写入后调 :func:`invalidate_cache` 清掉本模块的 lru_cache。 """ from __future__ import annotations import json import re from dataclasses import dataclass from datetime import date from functools import lru_cache from pathlib import Path from typing import Any _FENCE_RE = re.compile(r"```(?:json)?\s*(.*?)```", re.DOTALL | re.IGNORECASE) def _scan_balanced(text: str, open_ch: str, close_ch: str) -> Any | None: """从 text 里扫第一个**平衡**的 ``open_ch…close_ch`` 块并 ``json.loads``。 字符串感知(跳过引号内的括号/转义),失败返回 None。供从「含 JSON 的文本」里 把 JSON 段抠出来用。 """ start = text.find(open_ch) if start == -1: return None depth = 0 in_string = False escape = False for i in range(start, len(text)): ch = text[i] if in_string: if escape: escape = False elif ch == "\\": escape = True elif ch == '"': in_string = False continue if ch == '"': in_string = True elif ch == open_ch: depth += 1 elif ch == close_ch: depth -= 1 if depth == 0: blob = text[start : i + 1] try: return json.loads(blob) except (ValueError, TypeError): return None return None def extract_embedded_json(text: str | None) -> Any | None: """尽力从一段文本里抽出内嵌的 JSON(对象或数组)。 覆盖三种用户输入:纯 JSON(直接解析)、含 JSON 的文本(抠出第一个平衡的 ``{…}`` 或 ``[…]``)、纯文本(返回 ``None``)。也识别 ```json fence。 """ if not text or not isinstance(text, str): return None s = text.strip() fence = _FENCE_RE.search(s) if fence: inner = fence.group(1).strip() try: return json.loads(inner) except (ValueError, TypeError): s = inner # fence 内不是完整 JSON,继续往下扫 try: return json.loads(s) except (ValueError, TypeError): pass # 取最靠前出现的那种括号块(对象优先于数组,谁先出现谁优先)。 brace = _scan_balanced(s, "{", "}") bracket = _scan_balanced(s, "[", "]") if brace is not None and bracket is not None: return brace if s.find("{") <= s.find("[") else bracket return brace if brace is not None else bracket # 模板资源根目录(随 git 发布,与本模块同级 ``templates/`` 子目录)。 _TEMPLATES_ROOT = Path(__file__).parent / "templates" # 结构化模板骨架里的三个注入标记(compose_structured 逐个替换)。 DATA_MARKER = "__PAGE_DATA__" MANIFEST_MARKER = "__PAGE_MANIFEST__" RUNTIME_MARKER = "__PAGE_RUNTIME__" STRUCTURED_MARKERS: tuple[str, ...] = (DATA_MARKER, MANIFEST_MARKER, RUNTIME_MARKER) _MARKER_RE = re.compile(r"__PAGE_[A-Z0-9_]+__") # 结构化模板目录里的必备件。 STRUCTURED_PARTS: tuple[str, ...] = ("template.html", "runtime.js", "data.json") # 可选件:seed/reset 按存在复制;骨架里可写 __PAGE___ 扩展标记引用同名件 # (NAME 小写、下划线转连字符,如 KNOWLEDGE→knowledge.json、SOURCE_LOCAL→source-local.json)。 STRUCTURED_OPTIONAL_PARTS: tuple[str, ...] = ( "manifest.json", "fields.json", "knowledge.json", "source-local.json", ) def _marker_part_name(marker: str) -> str: """扩展标记 → 可选件文件名(``__PAGE_SOURCE_LOCAL__`` → ``source-local.json``)。""" inner = marker[len("__PAGE_") : -len("__")] return inner.lower().replace("_", "-") + ".json" @dataclass(frozen=True) class TemplateSpec: """一个 HTML 模板的注册信息。 ``file`` 相对 :data:`_TEMPLATES_ROOT`;``data_var``/``manifest_var`` 是模板里 待替换的 JS 常量名(``manifest_var`` 为空表示该模板没有 MANIFEST 行)。 ``kind`` 有两种: * ``"single"``(默认): 单文件模板,数据以 ``const DATA={…};`` 单行内嵌,填充 = 行级替换; * ``"structured"``: 结构化模板(page-generator 范式),目录含 ``template.html``(骨架,带 :data:`STRUCTURED_MARKERS` 三个注入标记)/ ``runtime.js``(渲染 + 页面内 JSON 编辑器)/``data.json``(默认数据,即转换 契约)/可选 ``manifest.json``,填充 = 标记组合,产物仍是自包含单文件 HTML。 ``legacy_file`` 指向单文件时代的随包正文,供 template_store 自动升级时做 「未被手改」的字节级比对。 ``convertible=False`` 表示该模板暂只「直接展示已有数据」——执行时原样输出模板 HTML,不做 JSON 转换/校验/填充(无 ``const DATA=`` 注入行的模板用它,后续接入 转换后再改回 True)。 """ id: str name: str description: str file: str data_var: str = "DATA" manifest_var: str = "" convertible: bool = True kind: str = "single" legacy_file: str = "" @property def structured(self) -> bool: return self.kind == "structured" # 已注册模板(随包 seed 源 + 存储缺失时的兜底注册表)。新增模板时在此追加一条 # 即可——前端下拉、调度器填充全自动生效;运行时增删改走 template_store。 TEMPLATES: tuple[TemplateSpec, ...] = ( TemplateSpec( id="no1", name="no.1", description="", file="no1/template.html", data_var="DATA", manifest_var="MANIFEST", # 结构化模板(page-generator 范式):骨架 + runtime + 默认数据 + MANIFEST, # 填充走 compose_structured 标记组合;legacy_file 是单文件时代的随包正文, # 供 template_store 把「未被手改」的旧存储副本自动升级到结构化版。 kind="structured", legacy_file="no1/taiwan_littoral_ui_redwhite_v2.html", ), TemplateSpec( id="no2", name="no.2", description="", file="no2/template.html", # 结构化模板:骨架+runtime+data/knowledge/source-local/manifest/fields, # KNOWLEDGE/SOURCE_LOCAL 经 __PAGE_KNOWLEDGE__/__PAGE_SOURCE_LOCAL__ 扩展标记注入。 kind="structured", legacy_file="no2/taiwan_air_force_v3_2.html", ), TemplateSpec( id="no3", name="no.3", description="", file="no3/template.html", # 结构化模板:骨架+runtime+data/manifest/fields,页面隐藏/字段管理/写回全量能力。 kind="structured", legacy_file="no3/no3.html", ), TemplateSpec( id="no4", name="no.4", description="", file="no4/template.html", # 结构化模板:骨架+runtime+data(8 顶层键,40 数据集)/manifest(6 页面)/fields # (267 字段),页面隐藏/字段值级隐藏/写回全量能力。 kind="structured", legacy_file="no4/no4.html", ), TemplateSpec( id="no5", name="no.5", description="", file="no5/template.html", # 结构化模板:骨架+runtime+data(8 顶层键,含 navigation.tabs/ui.field_labels) # /manifest(5 页面)/fields(68 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no5/no5.html", ), TemplateSpec( id="no6", name="no.6", description="", file="no6/template.html", # 结构化模板:骨架+runtime+data(14 顶层分支,11 页面)/manifest/fields # (108 中文字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no6/no6.html", ), TemplateSpec( id="no7", name="no.7", description="", file="no7/template.html", # 结构化模板:骨架+runtime+data(9 顶层键,6 页面)/manifest/fields # (149 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no7/no7.html", ), TemplateSpec( # 显示 no.8;id 用 no8b(no8 已被显示名 no.12 的模板占用)。 id="no8b", name="no.8", description="", # 结构化模板:骨架 + runtime + 数据 + 页面/字段配置。保留旧单文件, # 以便运行时存储只在用户未修改旧稿时自动升级。 file="no8b/template.html", kind="structured", legacy_file="no8b/no8b.html", ), TemplateSpec( # 显示 no.9;id 用 no9b(no9 已被显示名 no.13 的模板占用)。 id="no9b", name="no.9", description="", # 结构化模板:骨架 + runtime + 数据 + 页面/字段配置。保留旧单文件, # 以便运行时存储只在用户未修改旧稿时自动升级。 file="no9b/template.html", kind="structured", legacy_file="no9b/no9b.html", ), TemplateSpec( id="no10", name="no.10", description="", file="no10/template.html", # 结构化模板:骨架+runtime+data(6 顶层键,10 分类页面)/manifest/fields # (110 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no10/no10.html", ), TemplateSpec( id="no11", name="no.11", description="", file="no11/template.html", # 结构化模板:骨架+runtime+data(15 顶层键,10 分类页面)/manifest/fields # (71 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no11/no11.html", ), TemplateSpec( id="no8", name="no.12", description="", file="no8/template.html", # 结构化模板:骨架+runtime+data(11 顶层键,8 分类 tab)/manifest/fields # (73 中文字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no8/no8.html", ), TemplateSpec( id="no9", name="no.13", description="", file="no9/template.html", # 结构化模板:骨架+runtime+data(18 顶层键,12 页面)/manifest/fields # (110 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no9/no9.html", ), TemplateSpec( id="no14", name="no.14", description="", file="no14/template.html", # 结构化模板:骨架+runtime+data(10 顶层键,11 静态 panel 页面)/manifest/fields # (53 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no14/no14.html", ), TemplateSpec( id="no15", name="no.15", description="", file="no15/template.html", # 结构化模板:骨架+runtime+data(9 顶层键,12 动态 tab 页面)/manifest/fields # (130 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no15/no15.html", ), TemplateSpec( id="no16", name="no.16", description="", file="no16/template.html", # 结构化模板:骨架+runtime+data(16 顶层键,11 动态 tab 页面)/manifest/fields # (123 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no16/no16.html", ), TemplateSpec( id="no17", name="no.17", description="", # 结构化模板:保留原始数据集和全部页签交互,支持页面/字段配置与旧稿升级。 file="no17/template.html", kind="structured", legacy_file="no17/no17.html", ), TemplateSpec( id="no18", name="no.18", description="", # 原始静态页面模块被保存为结构化 pages 数据,保留旧单文件用于自动升级。 file="no18/template.html", kind="structured", legacy_file="no18/no18.html", ), TemplateSpec( id="no19", name="no.19", description="", file="no19/template.html", # 结构化模板:骨架+runtime+data(6 个数据集,10 个静态分页)/manifest/fields # (29 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no19/no.19.html", ), TemplateSpec( id="no20", name="no.20", description="", file="no20/template.html", # 结构化模板:骨架+runtime+data(12 顶层键,11 个动态 tab)/manifest/fields # (65 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no20/no.20.html", ), TemplateSpec( id="no21", name="no.21", description="", file="no21/template.html", # 结构化模板:骨架+runtime+data(4 顶层键,12 个动态 tab)/manifest/fields # (108 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no21/no.21.html", ), TemplateSpec( id="no22", name="no.22", description="", file="no22/template.html", # 结构化模板:骨架+runtime+data(19 顶层键,10 个动态 tab)/manifest/fields # (76 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no22/no.22.html", ), TemplateSpec( id="no23", name="no.23", description="", file="no23/template.html", # 结构化模板:骨架+runtime+data(13 顶层键,10 个分页)/manifest/fields # (39 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no23/no.23.html", ), TemplateSpec( id="no24", name="no.24", description="", file="no24/template.html", # 结构化模板:骨架+runtime+data(7 顶层键,12 个动态 tab)/manifest/fields # (29 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no24/no.24.html", ), TemplateSpec( id="no25", name="no.25", description="", # 结构化模板:保留原始动态数据模型、搜索/筛选/详情交互和旧稿升级能力。 file="no25/template.html", kind="structured", legacy_file="no25/no.25.html", ), TemplateSpec( id="no26", name="no.26", description="", file="no26/template.html", # 结构化模板:骨架+runtime+data(2 顶层键,11 个分页)/manifest/fields # (3 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no26/no.26.html", ), TemplateSpec( id="no27", name="no.27", description="", file="no27/template.html", # 结构化模板:骨架+runtime+data(2 顶层键,11 个分页)/manifest/fields # (8 字段),页面隐藏/值级字段管理/写回全量能力。 kind="structured", legacy_file="no27/no.27.html", ), ) _TEMPLATES_BY_ID: dict[str, TemplateSpec] = {t.id: t for t in TEMPLATES} class TemplateError(Exception): """模板缺失 / 解析失败 / 填充失败。""" def list_templates() -> list[dict[str, Any]]: """前端下拉用的轻量清单(只含 id/name/description/convertible,不含庞大数据)。 优先读运行时存储(template_store,含管理页上传/自建的模板);存储整体不可用时 回退随包静态注册表,保证「还没 seed / 存储目录损坏」时功能仍可用。 """ from deerflow.runtime.scheduler import template_store try: entries = template_store.list_templates() except Exception: entries = [] if entries: return [ { "id": e["id"], "name": e["name"], "description": e.get("description") or "", "convertible": bool(e.get("convertible")), } for e in entries ] return [ {"id": t.id, "name": t.name, "description": t.description, "convertible": t.convertible} for t in TEMPLATES ] def _store_template_file(template_id: str) -> Path | None: """存储里该模板的正文路径;不存在(未 seed/自建被删)返回 None。""" from deerflow.runtime.scheduler import template_store path = template_store.store_template_file(template_id) return path if path.is_file() else None def get_template(template_id: str) -> TemplateSpec | None: """模板注册信息:存储 meta 优先(动态,含管理页修改),随包注册表兜底。""" from deerflow.runtime.scheduler import template_store try: meta = template_store.get_template_meta(template_id) except Exception: meta = None if meta is not None: return TemplateSpec( id=str(meta["id"]), name=str(meta.get("name") or meta["id"]), description=str(meta.get("description") or ""), # 存储模板的正文路径由 _template_path 按 id 解析,这里的 file 仅占位。 file=f"{meta['id']}/template.html", data_var="DATA", manifest_var=str(meta.get("manifest_var") or ""), convertible=bool(meta.get("convertible")), kind=str(meta.get("kind") or "single"), ) return _TEMPLATES_BY_ID.get(template_id) def invalidate_cache() -> None: """清掉 reference_data / schema_skeleton_json 的 lru_cache。 template_store 的写操作(创建/编辑/上传覆盖/重置/删除)后必须调用,否则引擎 仍按改前的旧 DATA 做校验与骨架注入。 """ reference_data.cache_clear() schema_skeleton_json.cache_clear() def is_convertible(template_id: str) -> bool: spec = get_template(template_id) return bool(spec and spec.convertible) def _require(template_id: str) -> TemplateSpec: spec = get_template(template_id) if spec is None: raise TemplateError(f"未知模板 id:{template_id!r}") return spec def _template_path(spec: TemplateSpec) -> Path: # 存储副本优先(管理页编辑/上传的新版);没有才读随包静态文件。 store_file = _store_template_file(spec.id) if store_file is not None: return store_file return _TEMPLATES_ROOT / spec.file # ── 结构化模板(骨架 + runtime + 数据分文件,组合成单文件产物) ──────────────── def _structured_part(template_id: str, name: str) -> Path | None: """结构化模板某个组成文件的路径:存储副本优先,随包文件兜底;都没有返回 None。 ``manifest.json`` 可选;其余文件缺失属打包损坏,由 :func:`_structured_text` 报错。 """ from deerflow.runtime.scheduler import template_store store_file = template_store.store_root() / template_id / name if store_file.is_file(): return store_file fallback = _TEMPLATES_ROOT / template_id / name return fallback if fallback.is_file() else None def _structured_text(template_id: str, name: str) -> str: path = _structured_part(template_id, name) if path is None: raise TemplateError(f"结构化模板文件缺失:{template_id}/{name}") return path.read_text(encoding="utf-8") def _read_default_manifest(template_id: str) -> dict[str, Any]: """结构化模板的默认 MANIFEST;没有 manifest.json 时返回空对象。""" path = _structured_part(template_id, "manifest.json") if path is None: return {} try: obj = json.loads(path.read_text(encoding="utf-8")) except (OSError, ValueError) as exc: raise TemplateError(f"解析 {template_id}/manifest.json 失败:{exc}") from exc return obj if isinstance(obj, dict) else {} def structured_module_labels(template_id: str) -> list[dict[str, str]]: """结构化模板各数据模块(DATA 顶层键)的中文显示名,管理页「编辑数据」用。 标签来源按优先级:MANIFEST.页面 的「编号」精确命中 → 「数据源/架构数据」去掉 ``data/`` 前缀和 ``.json`` 后缀后命中(如 organization_charts) → 编号按 ``_`` 拆分后命中任一段(如 events/projects 命中 events_projects)。都没有则回退键名。 """ ref = reference_data(template_id) manifest = _read_default_manifest(template_id) labels: dict[str, str] = {} page_seg: dict[str, str] = {} pages = manifest.get("页面") if isinstance(pages, list): for page in pages: if not isinstance(page, dict): continue name = str(page.get("名称") or "").strip() if not name: continue candidates: list[str] = [] for field in ("编号", "数据源", "架构数据"): raw = str(page.get(field) or "").strip() if not raw: continue key = raw.removeprefix("data/").removesuffix(".json") if key: candidates.append(key) for key in candidates: labels[key] = name page_seg[key] = name for part in key.split("_"): if part: page_seg.setdefault(part, name) out: list[dict[str, str]] = [] for key in ref: label = labels.get(key) if not label: # 双向段匹配:分支键与页面候选键互为子段(如 capability_pressure_matrix # ↔ 页面编号 matrix)时按页面名显示。 for part in key.split("_"): if part and part in page_seg: label = page_seg[part] break out.append({"key": key, "label": label or key}) return out def compose_structured( *, skeleton: str, runtime: str, data: Any, manifest: dict[str, Any] | None = None, extra_parts: dict[str, str] | None = None, ) -> str: """把数据/运行时按标记组合进骨架,产出自包含单文件 HTML。 与 page-generator 技能的 render 脚本同一套安全转义:数据 JSON 里的 `` dict[str, str]: """解析骨架里的扩展标记,从模板目录读对应可选数据件并序列化。 标准 DATA/MANIFEST 标记不走这里(它们由 compose 参数注入)。文件缺失的扩展 标记跳过——组合后的残留断言会兜底报错。 """ parts: dict[str, str] = {} for marker in set(_MARKER_RE.findall(skeleton)): if marker in STRUCTURED_MARKERS: continue path = _structured_part(template_id, _marker_part_name(marker)) if path is not None: parts[marker] = json.dumps( json.loads(path.read_text(encoding="utf-8")), ensure_ascii=False ) return parts def read_template_text(template_id: str) -> str: spec = _require(template_id) if spec.structured: # 结构化模板对外始终呈现「组合后的完整文档」(预览/只展示/参考展示共用); # 骨架原文(编辑用)由 template_store.read_template_html 直接读文件。 tpl_skeleton = _structured_text(template_id, "template.html") return compose_structured( skeleton=tpl_skeleton, runtime=_structured_text(template_id, "runtime.js"), data=reference_data(template_id), manifest=_read_default_manifest(template_id), extra_parts=structured_extra_parts(template_id, tpl_skeleton), ) path = _template_path(spec) if not path.is_file(): raise TemplateError(f"模板文件缺失:{path}") return path.read_text(encoding="utf-8") def _const_line_re(var: str) -> re.Pattern[str]: # 单行 ``const VAR={...};`` —— 默认点号不跨行,故 ``.*`` 恰好吃到该物理行的结尾分号。 return re.compile(r"^const " + re.escape(var) + r"=.*;[ \t]*$", re.MULTILINE) def _extract_const_object(text: str, var: str) -> Any: """解析模板里 ``const VAR={...};`` 那一行的 JSON 值。""" match = _const_line_re(var).search(text) if match is None: raise TemplateError(f"模板中未找到 const {var}=… 行") line = match.group(0).strip() body = line[len("const ") + len(var) + 1 :] # 去掉 ``const VAR=`` body = body.rstrip().rstrip(";").rstrip() try: return json.loads(body) except json.JSONDecodeError as exc: # pragma: no cover - 模板损坏才会触发 raise TemplateError(f"解析 const {var} 失败:{exc}") from exc @lru_cache(maxsize=16) def reference_data(template_id: str) -> dict[str, Any]: """模板内嵌的参考 ``DATA`` 对象(目标格式范例 + 校验基准),按模板缓存。 单文件模板解析 ``const DATA=`` 行;结构化模板直接读 ``data.json``(两者语义一致: 顶层键即子页面,validate_data/merge_with_reference/骨架 prompt 全部通用)。 """ spec = _require(template_id) if spec.structured: try: obj = json.loads(_structured_text(template_id, "data.json")) except OSError as exc: raise TemplateError(f"读取 {template_id}/data.json 失败:{exc}") from exc except ValueError as exc: raise TemplateError(f"解析 {template_id}/data.json 失败:{exc}") from exc if not isinstance(obj, dict): raise TemplateError(f"模板 {template_id} 的 data.json 不是对象") return obj text = read_template_text(template_id) obj = _extract_const_object(text, spec.data_var) if not isinstance(obj, dict): raise TemplateError(f"模板 {template_id} 的 {spec.data_var} 不是对象") return obj def _skeleton(value: Any, *, list_sample: int = 1, depth: int = 0, max_depth: int = 6) -> Any: """把一份具体数据压成「空占位骨架」:保留全部字段名与类型,值一律抹空。 模板只是样式外壳,**示例值(模板自带的模拟内容)绝不能进入转换 prompt**—— 否则大模型会照抄示例内容、或被其领域(如台海防卫)限制住,不肯把用户主题的 内容映射进来。叶子按类型给空占位:字符串→\"\"、数字→0、布尔→false、 其它→null;数组元素同构,留 1 个抹空样例即可暴露该元素的完整字段集。 """ if depth >= max_depth: return None if isinstance(value, dict): return {k: _skeleton(v, list_sample=list_sample, depth=depth + 1, max_depth=max_depth) for k, v in value.items()} if isinstance(value, list): if not value: return [] return [_skeleton(v, list_sample=list_sample, depth=depth + 1, max_depth=max_depth) for v in value[:list_sample]] if isinstance(value, bool): return False if isinstance(value, (int, float)): return 0 if isinstance(value, str): return "" return None @lru_cache(maxsize=16) def schema_skeleton_json(template_id: str) -> str: """目标格式的空占位骨架(JSON 字符串),注入到大模型的转换 prompt 里。""" skeleton = _skeleton(reference_data(template_id)) return json.dumps(skeleton, ensure_ascii=False, indent=1) def top_level_keys(template_id: str) -> list[str]: return list(reference_data(template_id).keys()) def validate_data(template_id: str, obj: Any) -> list[str]: """硬校验:转换结果必须是对象,且顶层键齐全、容器类型与模板一致。 返回错误列表(空 = 通过)。只校验顶层结构——字段级缺失通过 :func:`field_coverage_gaps` 作为软反馈回喂大模型,而不在这里硬卡死。 """ errors: list[str] = [] if not isinstance(obj, dict): return ["转换结果不是 JSON 对象(应为 {…})"] ref = reference_data(template_id) for key, ref_val in ref.items(): if key not in obj: errors.append(f"缺少顶层字段「{key}」") continue got = obj[key] if isinstance(ref_val, list) and not isinstance(got, list): errors.append(f"字段「{key}」应为数组") elif isinstance(ref_val, dict) and not isinstance(got, dict): errors.append(f"字段「{key}」应为对象") return errors def _element_fields(value: Any) -> set[str]: """取一个数组里所有 dict 元素字段名的并集。""" fields: set[str] = set() if isinstance(value, list): for item in value: if isinstance(item, dict): fields.update(item.keys()) return fields def field_coverage_gaps(template_id: str, obj: Any, *, max_items: int = 40) -> list[str]: """软反馈:对照参考数据,列出转换结果里缺失的字段(数组元素字段 / 对象子键)。 用于把「字段没填全」回喂大模型让它补齐,不作为硬性失败。 """ gaps: list[str] = [] if not isinstance(obj, dict): return gaps ref = reference_data(template_id) for key, ref_val in ref.items(): if key not in obj: continue got = obj[key] if isinstance(ref_val, dict) and isinstance(got, dict): for sub in ref_val: if sub not in got: gaps.append(f"{key}.{sub} 缺失") elif isinstance(ref_val, list) and isinstance(got, list): want = _element_fields(ref_val) have = _element_fields(got) for f in sorted(want - have): gaps.append(f"{key}[].{f} 缺失") if len(gaps) >= max_items: return gaps[:max_items] + ["…(更多字段省略)"] return gaps def _has_content(value: Any) -> bool: """该值是否含「有效内容」(用于判断子页面 / 字段是否抽到东西)。 空 / None / 空串 / 全空的列表或字典 视为无内容;数字(含 0)、布尔、非空字符串 视为有内容。 """ if value is None: return False if isinstance(value, str): return bool(value.strip()) if isinstance(value, (list, tuple)): return any(_has_content(v) for v in value) if isinstance(value, dict): return any(_has_content(v) for v in value.values()) return True # 数字 / 布尔 / 其它标量 # 元素字段中至少要有这个比例能在模板参考数据的元素字段里找到,否则视为「自造字段」。 _LIST_FIELD_OVERLAP_MIN = 0.5 # 元素字段至少要覆盖模板参考元素字段的这个比例:低于它意味着大部分展示字段缺失 # (卡片大面积空白/undefined),不如整支回退模板原数据。 _LIST_FIELD_RECALL_MIN = 0.4 def _list_misaligned(got: Any, ref_val: Any) -> bool: """非空列表与模板参考列表是否「无法有效渲染」。 顶层校验挡不住这种情况:转换结果键齐全、类型也对,但列表元素的**字段**不对, 填进模板后 JS 读不到字段,页面满屏 ``undefined``。判定(满足其一即错位): * 模板元素是对象而转换给了非对象(字符串/数字读不出属性); * 元素字段里能对上模板的比例过低(:data:`_LIST_FIELD_OVERLAP_MIN`, 自造字段名占主导); * 元素字段对模板参考字段的**覆盖率**过低(:data:`_LIST_FIELD_RECALL_MIN`, 只填了零星几个字段,展示字段大面积缺失)。 空列表不算错位(交由「无内容回退」处理)。 """ if not isinstance(got, list) or not got: return False ref_fields = _element_fields(ref_val) if not ref_fields: return False # 模板元素本身没有对象字段,无从比对 ref_dicts = [item for item in ref_val if isinstance(item, dict)] got_dicts = [item for item in got if isinstance(item, dict)] if ref_dicts and not got_dicts: return True # 模板元素是对象,转换给了字符串/数字 → 必然读不到字段 if not got_dicts: return False got_fields: set[str] = set() for item in got_dicts: got_fields.update(item.keys()) if not got_fields: return False overlap = got_fields & ref_fields if len(overlap) / len(got_fields) < _LIST_FIELD_OVERLAP_MIN: return True # 自造字段名占主导 return len(overlap) / len(ref_fields) < _LIST_FIELD_RECALL_MIN # 覆盖率过低 def _mismatch_reason(got: Any, ref_val: Any) -> str: """错位原因的人话描述(回喂重试用),与 :func:`_list_misaligned` 同判定。""" ref_fields = _element_fields(ref_val) got_fields: set[str] = set() for item in got or []: if isinstance(item, dict): got_fields.update(item.keys()) overlap = got_fields & ref_fields if got_fields and len(overlap) / len(got_fields) < _LIST_FIELD_OVERLAP_MIN: return "的元素字段名与模板不一致(疑似自造字段名,必须原样沿用目标结构的字段名)" return "的元素字段覆盖过低(样例元素的字段大部分缺失;缺数据的字段按类型留空补齐,不要省略字段)" def shape_mismatches(template_id: str, obj: Any, *, max_items: int = 20) -> list[str]: """硬反馈:列出非空列表分支里「无法有效渲染」的项(供回喂重试)。 与 :func:`field_coverage_gaps`(软反馈,字段没填全)不同,本函数抓的是 **填了也渲染不出来**的情况:列表有内容但元素字段自造(对不上模板)或覆盖 过低(展示字段大面积缺失) → 渲染必然大面积 undefined,必须回喂重试。 """ out: list[str] = [] if not isinstance(obj, dict): return out ref = reference_data(template_id) for key, ref_val in ref.items(): got = obj.get(key) if isinstance(ref_val, list) and _list_misaligned(got, ref_val): out.append(f"「{key}」{_mismatch_reason(got, ref_val)}") if len(out) >= max_items: break return out def _ref_element_types(ref_val: list) -> dict[str, Any]: """参考列表各字段的类型样本(取第一个携带该字段的元素)。""" types: dict[str, Any] = {} for item in ref_val: if isinstance(item, dict): for key, value in item.items(): types.setdefault(key, value) return types def _blank_like(sample: Any) -> Any: """按参考类型给出「空值」:字符串→空串、列表→空数组、对象→空对象、其它→null。""" if isinstance(sample, str): return "" if isinstance(sample, list): return [] if isinstance(sample, dict): return {} return None def _fill_missing_fields(got: list, ref_val: list) -> list: """给保留的转换列表逐元素补齐模板元素字段(缺失的按参考类型给空值)。 模板 JS 常裸读 ``${item.字段}``(不经过空值兜底函数),字段缺失会直接把 ``undefined`` 打到页面上;补齐成空值后渲染为空白,不再出现字面 undefined。 只补缺、不改已有值,多出来的自造键原样保留(JS 不读,无害)。 """ types = _ref_element_types(ref_val) if not types: return got out: list[Any] = [] for item in got: if isinstance(item, dict): filled = dict(item) for key, sample in types.items(): if key not in filled: filled[key] = _blank_like(sample) out.append(filled) else: out.append(item) return out def _merge_fill(got: Any, ref: Any) -> Any: """用 ``got`` 覆盖,但 ``got`` 里「没有有效内容」的部分回退 ``ref``。 字典逐键递归(空分支回退);列表有内容就整体保留 ``got``(不逐元素合并,避免与 原模板元素错配)——**例外**:列表元素无法有效渲染(:func:`_list_misaligned`, 自造字段名占主导/覆盖率过低/元素类型不符)时整支回退 ``ref``,否则填进模板 JS 读不到字段,页面满屏 undefined。保留的列表会逐元素补齐缺失字段的空值 (:func:`_fill_missing_fields`),防止局部缺字段裸读出 undefined。 """ if not _has_content(got): return ref if isinstance(ref, dict) and isinstance(got, dict): out = dict(got) # 保留 got 里 ref 没有的额外键 for key, ref_val in ref.items(): out[key] = _merge_fill(got.get(key), ref_val) return out if isinstance(ref, list) and isinstance(got, list): if _list_misaligned(got, ref): return ref return _fill_missing_fields(got, ref) return got def merge_with_reference(template_id: str, data: Any) -> dict[str, Any]: """用转换结果覆盖,但「没抽到有效内容」的子页面 / 字段回退模板原有数据。 顶层键即子页面:某子页面(及其内部空字段)无有效内容时,用模板自带的原始数据补上, 保证页面与子页面不空白。整体为空时等价于返回模板默认数据。 """ ref = reference_data(template_id) merged = _merge_fill(data, ref) return merged if isinstance(merged, dict) else dict(ref) def _dump_const(var: str, obj: Any) -> str: body = json.dumps(obj, ensure_ascii=False) return f"const {var}={body};" def _escape_html(text: str) -> str: return ( text.replace("&", "&") .replace("<", "<") .replace(">", ">") .replace('"', """) ) # 转换结果里约定的两个额外顶层键:页面大标题/副标题(填充时替换页头,不进 DATA)。 PAGE_TITLE_KEY = "页面标题" PAGE_SUBTITLE_KEY = "页面副标题" def pop_page_titles(obj: dict[str, Any]) -> tuple[str | None, str | None]: """取出并移除转换结果里的「页面标题/页面副标题」额外键。 模型按转换 prompt 的约定额外输出这两个顶层字符串键;它们不是模板 DATA 的 字段(校验本就忽略额外键),填充前摘出来用于替换页头,避免漏进 ``const DATA``。 """ def _clean(value: Any) -> str | None: if isinstance(value, str) and value.strip(): return value.strip() return None title = _clean(obj.pop(PAGE_TITLE_KEY, None)) subtitle = _clean(obj.pop(PAGE_SUBTITLE_KEY, None)) return title, subtitle def _apply_page_titles( text: str, title: str | None, subtitle: str | None, manifest_overrides: dict[str, Any] | None, ) -> tuple[str, dict[str, Any] | None]: """替换页头静态标题/副标题;给出 title 时同步返回含 ``系统.名称`` 的 overrides。 模板页头(````、第一个 ``<h1>``、其后紧跟的副标题 ``<p>``)是写死的静态 HTML,不随 DATA 变化——给出新标题时替换这两处,并把 MANIFEST 的 系统.名称 一并 同步;不给则保持模板原文。单文件/结构化两条填充路径共用。 """ if title: overrides = dict(manifest_overrides or {}) system = overrides.get("系统") system = dict(system) if isinstance(system, dict) else {} system["名称"] = title overrides["系统"] = system manifest_overrides = overrides escaped = _escape_html(title) text = re.sub(r"<title>.*?", lambda _m: f"{escaped}", text, count=1, flags=re.DOTALL) text = re.sub(r"

.*?

", lambda _m: f"

{escaped}

", text, count=1, flags=re.DOTALL) if subtitle: escaped_sub = _escape_html(subtitle) text = re.sub( r"(

.*?

\s*

).*?(

)", lambda m: f"{m.group(1)}{escaped_sub}{m.group(2)}", text, count=1, flags=re.DOTALL, ) return text, manifest_overrides def _fill_structured( template_id: str, data_obj: Any, *, manifest_overrides: dict[str, Any] | None, update_date: date | None, title: str | None, subtitle: str | None, ) -> str: """结构化模板填充:标记组合出完整单文件 HTML(数据内嵌 JSON 元素 + runtime 内联)。""" skeleton, manifest_overrides = _apply_page_titles( _structured_text(template_id, "template.html"), title, subtitle, manifest_overrides ) manifest = _read_default_manifest(template_id) if update_date is not None: system = manifest.get("系统") if isinstance(system, dict): system["更新时间"] = update_date.isoformat() if manifest_overrides: _deep_merge(manifest, manifest_overrides) return compose_structured( skeleton=skeleton, runtime=_structured_text(template_id, "runtime.js"), data=data_obj, manifest=manifest, extra_parts=structured_extra_parts(template_id, skeleton), ) def fill_template( template_id: str, data_obj: Any, *, manifest_overrides: dict[str, Any] | None = None, update_date: date | None = None, title: str | None = None, subtitle: str | None = None, ) -> str: """把 ``data_obj`` 填进模板,产出完整 HTML 文档。 单文件模板:行级替换 ``const DATA=…``;结构化模板::func:`_fill_structured` 标记组合。可选地更新 MANIFEST 的「系统.更新时间」(``update_date``,默认不动) 以及任意 ``manifest_overrides``(深合并到解析后的 MANIFEST,如改系统名称)。 ``title``/``subtitle`` 来自转换结果里的「页面标题/页面副标题」:模板页头 (、第一个 <h1>、其后紧跟的副标题 <p>)是写死的静态 HTML,不随 DATA 变化——给出新标题时替换这三处,并把 MANIFEST 的 系统.名称 一并同步; 不给则保持模板原文。 """ spec = _require(template_id) if spec.structured: return _fill_structured( template_id, data_obj, manifest_overrides=manifest_overrides, update_date=update_date, title=title, subtitle=subtitle, ) text = read_template_text(template_id) text, manifest_overrides = _apply_page_titles(text, title, subtitle, manifest_overrides) data_re = _const_line_re(spec.data_var) if data_re.search(text) is None: raise TemplateError(f"模板 {template_id} 中未找到 const {spec.data_var}= 行") new_data_line = _dump_const(spec.data_var, data_obj) text = data_re.sub(lambda _m: new_data_line, text, count=1) if spec.manifest_var and (manifest_overrides or update_date is not None): manifest_re = _const_line_re(spec.manifest_var) match = manifest_re.search(text) if match is not None: try: manifest = _extract_const_object(text, spec.manifest_var) except TemplateError: manifest = None if isinstance(manifest, dict): if update_date is not None: system = manifest.get("系统") if isinstance(system, dict): system["更新时间"] = update_date.isoformat() if manifest_overrides: _deep_merge(manifest, manifest_overrides) new_manifest_line = _dump_const(spec.manifest_var, manifest) text = manifest_re.sub(lambda _m: new_manifest_line, text, count=1) return text def _deep_merge(base: dict[str, Any], overrides: dict[str, Any]) -> None: for k, v in overrides.items(): if isinstance(v, dict) and isinstance(base.get(k), dict): _deep_merge(base[k], v) else: base[k] = v # ── require_html 模式选「内置模板」作参考 ───────────────────────────────────────── # 「参考收藏页面」下拉里模板选项的值存成 ``tpl:<id>``,与用户收藏(普通 id)区分。 # 选了模板 → 调度器用**真实模板**出页(保留全部子页面),不抽风格摘要(那会丢子页面)。 REFERENCE_PREFIX = "tpl:" def reference_template_id(reference: str | None) -> str | None: """``tpl:no1`` → ``no1``;非模板参考(普通收藏 id / 空)返回 None。""" if isinstance(reference, str) and reference.startswith(REFERENCE_PREFIX): return reference[len(REFERENCE_PREFIX) :] or None return None