feat(定时任务): 内置「模板数据转换器」按 HTML 模板填充 JSON 生成大屏

- 模板填充引擎 template_fill.py:模板注册表 + schema 骨架 + 结构校验 + 行级安全填充;
  模板自带 DATA 即 schema 来源。no.1 可转换填充(含 MANIFEST 更新时间刷新),
  no.2 暂为「只展示」(convertible=False) 原样输出已有数据
- 内置 agent template-json-builder(seed + SOUL),随 lifespan 注入,自动出现在
  定时任务「执行智能体」下拉
- 调度器新增模板填充执行分支 _run_template_fill_attempt:源 JSON→大模型转换→
  结构校验→失败回喂重试;空源/只展示模板直接用模板默认数据,绝不失败
- API:GET /api/scheduled-tasks/html-templates
- 前端:选中该 agent 后条件渲染「HTML模板」下拉 + .json 上传,只展示型模板隐藏 JSON 输入
- 文档同步(前后端 CLAUDE.md)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
董宏凯andClaude Opus 4.8 committed 2026-06-23 18:00:00 +08:00
1 parent 1a2ef0a537
commit cd33aaeded
17 files changed
+1511 -57

No files matched your search

@@ -960,6 +960,20 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
"AI-writing functional agent seeding failed at startup (non-fatal)"
)
# 内置「模板数据转换器」agent(JSON → HTML 模板填充)。同样必须在
# _sync_legacy_agents **之前**补建目录,后者把它 upsert 进 agents 表,
# 第一次启动 /api/agents 与定时任务下拉框里就有它。
try:
from app.gateway.routers._template_builder_seed import (
ensure_template_builder_agent,
)
ensure_template_builder_agent()
except Exception:
logger.exception(
"Template-builder agent seeding failed at startup (non-fatal)"
)
# ?????????????????3Q/6BF/7BF/8BF??agent/chain ?????
try:
business_mapping_store = getattr(app.state, "business_mapping_store", None)
@@ -0,0 +1,63 @@
"""内置「模板数据转换器」agent 的「缺失自动补建」工具。
``template-json-builder`` 是定时任务「JSON → HTML 模板填充」功能的执行大脑:当用户在
定时任务表单里选中它、再选一个 HTML 模板时,到点执行会用它的 ``SOUL.md`` 把源 JSON
智能映射成模板需要的 ``DATA`` 结构(详见
:mod:`deerflow.runtime.scheduler.template_fill` 与调度器 ``service.py``)。
与 ``_ai_writing_seed.py`` / ``_roundtable_seed.py`` 完全同构:验证版 ``SOUL.md`` +
``config.yaml`` 随 git 发布于 ``_template_builder_seed_assets/<id>/``,seeder 只在
``.deer-flow/agents/<id>/`` 目录**缺失**时字节级复制(绝不覆盖线上手改)。lifespan 在
``_sync_legacy_agents`` 之前调用本 seeder,后者扫描 agents 目录把它 upsert 进 agents 表
(``user_id IS NULL`` 内置、``published=True``),于是 ``/api/agents`` 列表、进而定时任务
「执行智能体」下拉框里第一次启动就有它,admin 也能在智能体管理页编辑 SOUL/模型。
"""
from __future__ import annotations
import logging
from pathlib import Path
from deerflow.config.paths import get_paths
logger = logging.getLogger(__name__)
TEMPLATE_BUILDER_AGENT_ID = "template-json-builder"
# 验证版 SOUL.md + config.yaml 的源码资源目录(随 git 发布)。子目录名即 agent id。
_ASSETS_DIR = Path(__file__).parent / "_template_builder_seed_assets"
# seeder 复制的文件(存在即复制,缺失则跳过)。
_SEED_FILES: tuple[str, ...] = ("config.yaml", "SOUL.md")
def ensure_template_builder_agent() -> bool:
"""若 ``.deer-flow/agents/template-json-builder/`` 缺失,从资源补建。
返回 True 表示本次刚创建;目录已存在(尊重本地手改)或资源缺失则返回 False。
错误只记日志、绝不抛出——seeding 失败不能拖垮启动。
"""
try:
agent_dir = get_paths().agent_dir(TEMPLATE_BUILDER_AGENT_ID)
if agent_dir.exists():
return False
src_dir = _ASSETS_DIR / TEMPLATE_BUILDER_AGENT_ID
if not src_dir.is_dir():
logger.error(
"Missing seed assets for agent '%s' (expected at %s)",
TEMPLATE_BUILDER_AGENT_ID,
src_dir,
)
return False
agent_dir.mkdir(parents=True, exist_ok=True)
for fname in _SEED_FILES:
src = src_dir / fname
if src.exists():
(agent_dir / fname).write_bytes(src.read_bytes())
logger.info("Seeded built-in agent '%s'", TEMPLATE_BUILDER_AGENT_ID)
return True
except Exception:
logger.exception("Failed to seed built-in agent '%s'", TEMPLATE_BUILDER_AGENT_ID)
return False
@@ -0,0 +1,30 @@
# 模板数据转换器
你是一名严谨的「JSON 结构转换专家」。你的唯一职责是:把用户传入的**源 JSON**,
精确映射成给定**目标结构**所要求的 JSON,供后续填充进 HTML 模板渲染成数据大屏。
## 你会收到
1. **目标结构骨架**:一份 JSON,展示了目标格式的**完整字段与类型**(每个数组只给 1 个
样例元素,但该元素已列出全部字段)。这是你必须严格对齐的契约。
2. **源 JSON**:用户提供的原始数据,结构任意、字段名可能与目标不同、可能有多有少。
3. (重试时) **上一轮的校验错误 / 缺失字段清单**:你必须据此修正后重新输出。
## 转换规则
- **顶层键必须齐全且类型一致**:目标结构里的每一个顶层键(及其数组/对象类型)都必须
出现在你的输出里,一个都不能少。
- **逐字段映射,尽力填满**:把源数据里语义对应的内容填进目标字段;字段名不同就按含义
对应(如源 `name`→目标 `名称`)。目标数组的每个元素都要尽量带齐目标样例里出现的全部字段。
- **缺数据时给出合理空值**:源里确实没有的字段,按其类型填空字符串 `""`、空数组 `[]`、
`null` 或合理占位,**绝不删除该字段**,也不要伪造与源无关的事实性内容。
- **保持数据真实**:只搬运/重组源数据,不臆造统计数字与结论。`overview` 里的计数类字段
应与各列表的实际条数自洽。
- **不要输出模板骨架本身**:目标结构骨架只是格式范例,不要把它的样例值原样抄回。
## 输出要求(必须严格遵守)
- **只输出一个 ` ```json ` 代码块**,块内是填充好的完整目标 JSON,**不要任何解释性文字、
前后缀、注释**。
- 输出必须是**合法 JSON**(双引号、无尾逗号、无注释),可被 `json.loads` 直接解析。
- 不要使用工具,不要分多步,直接给出最终 JSON。
@@ -0,0 +1,4 @@
id: template-json-builder
name: 模板数据转换器
description: 把用户传入的任意 JSON 智能映射成所选 HTML 模板需要的数据结构,校验后填充进模板生成可预览的页面(定时任务中选择 HTML 模板后生效)
skills: []
@@ -209,6 +209,18 @@ async def get_scheduler_thread(request: Request) -> dict:
return await service.ensure_scheduler_thread(user_id)
@router.get("/html-templates")
async def list_html_templates() -> dict:
"""可选的 HTML 模板清单(供「模板数据转换器」内置 agent 填充用)。
返回 ``{"templates": [{id, name, description}]}``,前端定时任务表单在选中
「模板数据转换器」后据此渲染「HTML 模板」下拉。开放给任意登录用户。
"""
from deerflow.runtime.scheduler import template_fill
return {"templates": template_fill.list_templates()}
@router.get("")
async def list_scheduled_tasks(
request: Request,