feat(backend): 新增页面报告设计器 Seed 与模板工具

功能说明:\n- 新增页面报告设计器的路由级 seed 接口与初始化模板资源加载能力\n- 新增内置页面报告模板工具,实现报告生成流程中的模板路径与参数接入\n- 补充页面报告模板与相关资产目录,供运行时/离线环境直接读取\n- 将页面报告配置与工具链纳入后端启动路径,支持离线部署下可复用的默认模板
This commit is contained in:
董宏凯 committed 2026-09-02 12:52:40 +08:00
1 parent 6d326a21cd
commit 1c891df8fb
14 files changed
+9256

No files matched your search

@@ -0,0 +1,322 @@
"""Thread-safe page-report template preparation and static quality checks."""
from __future__ import annotations
import json
import re
from collections.abc import Iterable
from pathlib import Path
from langchain.tools import ToolRuntime, tool
from langgraph.typing import ContextT
from deerflow.agents.thread_state import ThreadState
from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
from deerflow.page_reports.templates import (
choose_template,
get_template_profile,
list_template_profiles,
resolve_template_file,
)
from deerflow.runtime.thread_paths import resolve_path_user_id
_MAX_HTML_BYTES = 4 * 1024 * 1024
# Allow human-readable Chinese filenames while still rejecting path separators,
# Windows-reserved filename characters, and control characters.
_SAFE_OUTPUT_NAME = re.compile(r'^[^<>:"/\\|?*\x00-\x1f]+\.html$', re.IGNORECASE)
_FONT_SIZE_RE = re.compile(r"font-size\s*:\s*([0-9]+(?:\.[0-9]+)?)px", re.IGNORECASE)
_MIN_TEXT_FONT_SIZE = 16.0
def _thread_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str:
context = runtime.context or {}
thread_id = context.get("thread_id")
if not thread_id:
thread_id = (getattr(runtime, "config", {}) or {}).get("configurable", {}).get("thread_id")
if not thread_id:
raise ValueError("当前会话缺少 thread_id,无法准备页面模板。")
return str(thread_id)
def _virtual_path(path: Path, *, thread_id: str, user_id: str | None) -> str:
root = get_paths().sandbox_user_data_dir(thread_id, user_id=user_id).resolve()
relative = path.resolve().relative_to(root)
return f"{VIRTUAL_PATH_PREFIX}/{relative.as_posix()}"
def _thread_directories(runtime: ToolRuntime[ContextT, ThreadState]) -> tuple[str, str | None, Path, Path]:
thread_id = _thread_id(runtime)
user_id = resolve_path_user_id(thread_id)
paths = get_paths()
workspace = paths.sandbox_work_dir(thread_id, user_id=user_id)
outputs = paths.sandbox_outputs_dir(thread_id, user_id=user_id)
workspace.mkdir(parents=True, exist_ok=True)
outputs.mkdir(parents=True, exist_ok=True)
return thread_id, user_id, workspace, outputs
def _safe_output_filename(output_name: str) -> str:
raw = (output_name or "report-page.html").strip()
if not raw.lower().endswith(".html"):
raw += ".html"
if Path(raw).name != raw or not _SAFE_OUTPUT_NAME.fullmatch(raw):
raise ValueError("output_name 必须是单个安全的 .html 文件名,不能包含路径或 Windows 非法字符。")
return raw
def _apply_minimum_font_size(html: str) -> str:
"""Normalize editable template copies to the report designer's font floor.
The library includes some legacy dashboard skeletons with compact labels.
They are useful layout starting points, but the designer contract requires
that visible text is at least 16px. Normalize the *per-thread copy* here
so a weaker model does not have to remember a large CSS-only cleanup before
it can work on the actual report content. The immutable source template is
never changed, and ``validate`` remains the final guard if later edits add
a smaller declaration.
"""
def replace(match: re.Match[str]) -> str:
size = float(match.group(1))
if size >= _MIN_TEXT_FONT_SIZE:
return match.group(0)
return f"font-size: {_MIN_TEXT_FONT_SIZE:g}px"
return _FONT_SIZE_RE.sub(replace, html)
def _edit_contract(template_id: str) -> dict[str, object]:
profile = get_template_profile(template_id)
chart_driven = "reportData" in profile.data_entry
return {
"data_entry": profile.data_entry,
"edit_order": [
"先把用户材料整理为文字摘要、指标、表格行、图表数据和待办事项。",
"只编辑工作区的副本;禁止改动模板源文件。",
"若存在 reportData,先改该对象中的图表数组,再替换标题、段落、卡片和表格文案。",
"根据材料删掉无数据的卡片或整页;不要为了凑页数保留空白面板。",
"将最终 HTML 写入 outputs 后调用 validate;通过后用 present_files 交付。",
],
"must_keep": (
["reportData 的字段名和图表渲染函数", "页面切换及 prefers-reduced-motion 逻辑"]
if chart_driven
else ["已有布局类名", "移动端 / reduced-motion 样式"]
),
"illustrative_data_rule": "没有可核验数值但用户明确要求图表时,可画示意图;页面必须在图例或数据口径处标注“示意数据 / 待补充数据”,不得伪装为事实。",
}
def _prepare(
runtime: ToolRuntime[ContextT, ThreadState],
*,
theme: str,
content_density: str,
required_features: list[str],
preferred_page_count: int | None,
selection_key: str,
exclude_template_ids: list[str],
template_id: str | None,
output_name: str,
page_brief: str,
) -> str:
profile = (
get_template_profile(template_id)
if (template_id or "").strip()
else choose_template(
theme=theme,
content_density=content_density,
required_features=required_features,
preferred_page_count=preferred_page_count,
selection_key=selection_key,
exclude_template_ids=exclude_template_ids,
)
)
source = resolve_template_file(profile.id)
thread_id, user_id, workspace, outputs = _thread_directories(runtime)
filename = _safe_output_filename(output_name)
working_copy = workspace / f"{Path(filename).stem}--{profile.id}.html"
brief_path = workspace / f"{Path(filename).stem}--page-brief.json"
# Copy first, then normalize only the editable thread-local copy. This
# preserves the bundled assets exactly as supplied while giving every run a
# usable 16px-or-larger starting point.
working_copy.write_text(_apply_minimum_font_size(source.read_text(encoding="utf-8")), encoding="utf-8")
brief = {
"template": profile.to_dict(),
"requested_theme": theme or "auto",
"requested_content_density": content_density or "balanced",
"required_features": required_features,
"recommended_final_output": _virtual_path(outputs / filename, thread_id=thread_id, user_id=user_id),
"working_copy": _virtual_path(working_copy, thread_id=thread_id, user_id=user_id),
"user_material_brief": (page_brief or "").strip(),
"edit_contract": _edit_contract(profile.id),
"font_rule": "所有可见文字最小字号为 16px;生成后必须通过 validate 校验。",
}
brief_path.write_text(json.dumps(brief, ensure_ascii=False, indent=2), encoding="utf-8")
return json.dumps(
{
"ok": True,
"template": profile.to_dict(),
"working_copy": _virtual_path(working_copy, thread_id=thread_id, user_id=user_id),
"brief_path": _virtual_path(brief_path, thread_id=thread_id, user_id=user_id),
"final_output": brief["recommended_final_output"],
"next_step": "读取 brief_path 和 working_copy,改完后写入 final_output,再调用 action=validate。",
},
ensure_ascii=False,
)
def _resolve_current_thread_file(
runtime: ToolRuntime[ContextT, ThreadState],
virtual_path: str,
) -> tuple[Path, str, str | None]:
thread_id, user_id, workspace, outputs = _thread_directories(runtime)
normalized = (virtual_path or "").strip()
if not normalized.startswith(f"{VIRTUAL_PATH_PREFIX}/"):
raise ValueError(f"file_path 必须位于 {VIRTUAL_PATH_PREFIX}/workspace 或 {VIRTUAL_PATH_PREFIX}/outputs。")
actual = get_paths().resolve_virtual_path(thread_id, normalized, user_id=user_id)
permitted_roots: Iterable[Path] = (workspace.resolve(), outputs.resolve())
if not any(actual.is_relative_to(root) for root in permitted_roots):
raise ValueError("file_path 只能指向当前会话的 workspace 或 outputs 目录。")
if not actual.is_file():
raise ValueError(f"待校验 HTML 不存在:{virtual_path}")
return actual, thread_id, user_id
def _count_textual_content(html: str) -> int:
plain = re.sub(r"<script[\s\S]*?</script>|<style[\s\S]*?</style>|<[^>]+>", " ", html, flags=re.IGNORECASE)
return len(re.sub(r"\s+", "", plain))
def _quality_report(html: str, *, data_mode: str, expected_features: set[str]) -> dict[str, object]:
lowered = html.lower()
errors: list[str] = []
warnings: list[str] = []
if "<!doctype html" not in lowered or "</html>" not in lowered:
errors.append("HTML 不完整:需要 <!doctype html> 和 </html>。")
if "<body" not in lowered or "</body>" not in lowered:
errors.append("HTML 缺少完整 body 结构。")
if "<title" not in lowered:
errors.append("页面缺少 title。")
if _count_textual_content(html) < 500:
warnings.append("有效文字内容偏少;本类页面应以结论、要点、说明和行动项为主体。")
chart_markers = {"line": "svg", "bar": "bar", "pie": "pie", "radar": "radar", "scatter": "scatter", "gantt": "gantt"}
for feature in expected_features:
marker = chart_markers.get(feature)
if marker and marker not in lowered:
warnings.append(f"未检测到请求的 {feature} 图表结构,请确认是否应删去该要求或补充图表。")
font_sizes = [float(value) for value in _FONT_SIZE_RE.findall(html)]
too_small = sorted({value for value in font_sizes if value < 16})
if too_small:
errors.append("发现小于 16px 的字号:" + "、".join(f"{value:g}px" for value in too_small[:8]) + "。")
if (data_mode or "provided").strip().lower() in {"illustrative", "mixed"} and not any(
mark in html for mark in ("示意数据", "待补充数据", "模拟数据")
):
errors.append("示意图表没有标注“示意数据 / 待补充数据”,可能被误认为事实。")
if "reportdata" in lowered and "const reportdata" not in lowered:
warnings.append("检测到 reportData 引用但未检测到 const reportData 定义,请检查图表脚本。")
return {
"ok": not errors,
"errors": errors,
"warnings": warnings,
"metrics": {
"bytes": len(html.encode("utf-8")),
"text_characters": _count_textual_content(html),
"page_sections": len(re.findall(r"class=[\"'][^\"']*(?:report-page|page)[^\"']*[\"']", html, flags=re.IGNORECASE)),
"has_script": "<script" in lowered,
},
}
def _validate(
runtime: ToolRuntime[ContextT, ThreadState],
*,
file_path: str,
data_mode: str,
expected_features: list[str],
) -> str:
actual, thread_id, user_id = _resolve_current_thread_file(runtime, file_path)
if actual.stat().st_size > _MAX_HTML_BYTES:
raise ValueError(f"HTML 超过 {_MAX_HTML_BYTES // 1024 // 1024}MB,拒绝读取。")
html = actual.read_text(encoding="utf-8")
report = _quality_report(
html,
data_mode=data_mode,
expected_features={item.strip().lower() for item in expected_features if item.strip()},
)
report_path = actual.with_name(f"{actual.stem}.quality.json")
report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
report["quality_report"] = _virtual_path(report_path, thread_id=thread_id, user_id=user_id)
report["file_path"] = _virtual_path(actual, thread_id=thread_id, user_id=user_id)
return json.dumps(report, ensure_ascii=False)
@tool("page_report_template", parse_docstring=True)
def page_report_template_tool(
runtime: ToolRuntime[ContextT, ThreadState],
action: str,
theme: str = "auto",
content_density: str = "balanced",
required_features: list[str] | None = None,
preferred_page_count: int | None = None,
selection_key: str = "",
exclude_template_ids: list[str] | None = None,
template_id: str | None = None,
output_name: str = "report-page.html",
page_brief: str = "",
file_path: str = "",
data_mode: str = "provided",
) -> str:
"""Select, copy, and quality-check reusable HTML report-page templates.
Use this tool instead of editing a source template in place.
Args:
action: One of ``catalog``, ``prepare``, or ``validate``. ``catalog`` lists
profiles; ``prepare`` selects/copies a source into this thread's
workspace and writes an editing brief; ``validate`` checks an edited
HTML file and writes a JSON quality report next to it.
theme: ``dark`` or ``light``. Use the UI-provided presentation theme when
available; ``auto`` lets the selector use all profiles.
content_density: ``text-heavy``, ``balanced``, or ``data-heavy``.
required_features: Needed components such as ``line``, ``pie``,
``radar``, ``scatter``, ``gantt``, ``table``, ``text-panels``.
preferred_page_count: Preferred number of report pages. The agent may
remove unused skeleton pages after preparation.
selection_key: Stable request/thread-derived text used to vary equally
good template choices.
exclude_template_ids: Recently-used template ids to avoid where possible.
template_id: Optional explicit catalog id. Omit to select automatically.
output_name: Final safe HTML filename, e.g. ``经营月报.html``.
page_brief: Concise summary of supplied materials and desired output.
file_path: For ``validate`` only: current-thread HTML under workspace or
outputs.
data_mode: ``provided`` for factual data, ``illustrative`` when charts
are intentionally demonstrative, or ``mixed``.
"""
normalized_action = (action or "").strip().lower()
if normalized_action == "catalog":
return json.dumps({"templates": [profile.to_dict() for profile in list_template_profiles()]}, ensure_ascii=False)
if normalized_action == "prepare":
return _prepare(
runtime,
theme=theme,
content_density=content_density,
required_features=required_features or [],
preferred_page_count=preferred_page_count,
selection_key=selection_key,
exclude_template_ids=exclude_template_ids or [],
template_id=template_id,
output_name=output_name,
page_brief=page_brief,
)
if normalized_action == "validate":
return _validate(
runtime,
file_path=file_path,
data_mode=data_mode,
expected_features=required_features or [],
)
raise ValueError("action 仅支持 catalog、prepare、validate。")
__all__ = ["page_report_template_tool"]