feat(backend): 新增页面报告设计器 Seed 与模板工具
功能说明:\n- 新增页面报告设计器的路由级 seed 接口与初始化模板资源加载能力\n- 新增内置页面报告模板工具,实现报告生成流程中的模板路径与参数接入\n- 补充页面报告模板与相关资产目录,供运行时/离线环境直接读取\n- 将页面报告配置与工具链纳入后端启动路径,支持离线部署下可复用的默认模板
This commit is contained in:
1 parent
6d326a21cd
commit
1c891df8fb
14 files changed
+9256
No files matched your search
+322
@@ -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"]
|
||||
Reference in new issue
Block a user