feat(定时任务): 模板数据转换器对话页加「页面模板+渲染预览」调试入口

- 后端 POST /api/scheduled-tasks/template-fill/render：不调模型，抽取回复里的 JSON
  → 校验 → 填充，返回完整 HTML + 校验错误/缺失字段（非法也照样填充便于看效果），
  只展示模板原样返回
- 前端仅 template-json-builder 智能体的 AgentChatPage：顶部加页面模板下拉 +「渲染预览」
  按钮，取最近一条 AI 回复填进所选模板，弹窗用 sandbox=allow-scripts iframe 预览 +
  校验状态；严格按 agent id 门控，不影响其他智能体对话页
- 文档同步

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -79,7 +79,7 @@ The frontend (`frontend-web/`) is a React 19 + Vite SPA:
 
 - **Routing**: React Router v7; top-level routes in `src/pages/PageRoutes.tsx`, workspace sub-routes in `src/pages/WorkspaceRoutes.tsx`
 - **Pages**: `ChatPage` (thread chat), `AgentChatPage` (custom agent chat), `AgentsPage`/`NewAgentPage` (agent management), `ScheduledTasksPage`/`ScheduledTaskRunDetailPage` (scheduled tasks), `LightAppManagementPage`/`LightAppListPage`/`LightAppIframeView` (轻应用中心 — register/list/embed mini-apps)
-- **定时任务「JSON → HTML 模板填充」(模板数据转换器)**: a third scheduled-task execution mode. In the create/edit dialog (`ScheduledTasksPage.tsx`), selecting the built-in agent **「模板数据转换器」** (`execution_agent_name === "template-json-builder"`, `TEMPLATE_BUILDER_AGENT_ID`) reveals a 「HTML模板」 select (`useHtmlTemplates` → `GET /api/scheduled-tasks/html-templates`) + a **.json 上传** button (reads the file's text into the prompt box) and **hides** the 必须生成 HTML/Markdown switches (this mode always outputs HTML). The chosen template persists as `execution_context.template_config.template_id` (`TemplateFillConfig` in `core/scheduled-tasks/types.ts`). At run time the backend converts the source JSON (the task prompt) into that template's `DATA` structure, validates (retry-on-fail), fills the template, and stores an HTML page previewable via the existing run-detail HTML preview. The source can be **pure JSON, plain text, or text-with-embedded-JSON** — the backend pre-extracts any embedded JSON and the agent's `SOUL.md` maps it (or the plain text's semantics) to the template's schema skeleton. See the backend CLAUDE.md「Template-fill mode」for the engine (`deerflow/runtime/scheduler/template_fill.py`), agent seed, and dispatch.
+- **定时任务「JSON → HTML 模板填充」(模板数据转换器)**: a third scheduled-task execution mode. In the create/edit dialog (`ScheduledTasksPage.tsx`), selecting the built-in agent **「模板数据转换器」** (`execution_agent_name === "template-json-builder"`, `TEMPLATE_BUILDER_AGENT_ID`) reveals a 「HTML模板」 select (`useHtmlTemplates` → `GET /api/scheduled-tasks/html-templates`) + a **.json 上传** button (reads the file's text into the prompt box) and **hides** the 必须生成 HTML/Markdown switches (this mode always outputs HTML). The chosen template persists as `execution_context.template_config.template_id` (`TemplateFillConfig` in `core/scheduled-tasks/types.ts`). At run time the backend converts the source JSON (the task prompt) into that template's `DATA` structure, validates (retry-on-fail), fills the template, and stores an HTML page previewable via the existing run-detail HTML preview. The source can be **pure JSON, plain text, or text-with-embedded-JSON** — the backend pre-extracts any embedded JSON and the agent's `SOUL.md` maps it (or the plain text's semantics) to the template's schema skeleton. **Chat-page debug entry (only this agent's `AgentChatPage`)**: when `agent_id === "template-json-builder"`, the chat header shows a 「页面模板」 select + a 「渲染预览」 button — after a normal Q&A run, the button takes the **latest AI reply**, POSTs it to `POST /api/scheduled-tasks/template-fill/render` (`renderTemplateFill`), and pops a dialog rendering the filled HTML in a `sandbox="allow-scripts"` iframe plus the structure-validation status/errors/gaps — for debugging the agent's conversion effect without creating a scheduled task. Gated strictly on the agent id, so other agents' chat pages are untouched. See the backend CLAUDE.md「Template-fill mode」for the engine (`deerflow/runtime/scheduler/template_fill.py`), agent seed, dispatch, and the render API.
 - **轻应用中心 (Light App Center)**: a sibling of 任务管理 in the sidebar with two pages — 应用管理 (admin registers `window_open` or `iframe` mini-apps with a route-param builder: login params resolved from `localStorage.userInfo`, theme params literal) and 应用列表 (card grid of `window_open` apps, `window.open` launch). `iframe` apps are mounted under a chosen parent menu (XK/PG/TY/综合管理) and **dynamically injected into the sidebar** by `core/page-layout/use-sidebar-menu.ts` (`useSidebarMenuItems`), opening in the `LightAppIframeView` host. Client + React Query hooks in `strategy-components/api/light-apps.ts`; URL builder/constants in `strategy-components/lib/light-app.ts`. Backend: `/api/light-apps` (global/shared, admin-gated writes).
 - **菜单管理 (Menu Management, admin-only)**: an **overlay** over the static sidebar menu — `MenuManagementPage` (`pages/MenuManagementPage.tsx`, route `/page/strategy/admin/menu-management`, opened from the admin-only 「菜单管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`). Admins rename / 停用·启用 / reorder (↑↓ or @dnd-kit drag) / re-parent (horizontal drag **or** the edit dialog's 「移动到」parent selector) any node across 一级/二级/三级, **including injected iframe light-app nodes** (`light-app-<appId>`). The static tree (`core/page-layout/sidebar-menu.ts`) stays the source of icons/routes; only per-node deltas (`label`/`disabled`/`parentId`/`sortOrder`) persist to the backend. Merge logic in `core/page-layout/menu-overrides.ts` (`applyMenuOverrides`, applied in `use-sidebar-menu.ts` after light-app injection, before role filter; disabling a node hides its whole subtree) — strict **3-level cap** (`wouldExceedDepth`). Client `strategy-components/api/menu-overrides.ts`. Backend: `/api/menu-overrides` (global/shared; open read, admin atomic replace-all).
 - **敏感词管理 (Sensitive Word Management)**: configures the **展示层脱敏映射** (原始词 → 替换词). **Gated on the username `lqq`** (not the admin role) — `getAccountDisplayName().toLowerCase() === "lqq"` (username = email `@` prefix, else `user_id`, same as the profile page); the dropdown entry, the route guard, and the page-level guard all use this check. `src/lib/desensitize.ts` ships a frozen seed map `SEED_DESENSITIZE_MAP` (the deployment seed) plus a live mutable `DESENSITIZE_MAP` (initialized from the seed so `desensitize()` works before any fetch). `DesensitizeWordsLoader` (mounted in `App.tsx` `AppProviders`) fetches `/api/sensitive-words` on startup and, if non-empty, calls `replaceDesensitizeMap(...)` to make the backend config the source of truth (empty/failed → keep seed). Page `SensitiveWordsPage.tsx` (route `/page/strategy/admin/sensitive-words`, opened from the 「敏感词管理」 item in the **bottom-left settings dropdown** of `components/page-sidebar.tsx`, present in **both** full + collapsed sidebar modes) lists/adds/edits/启停/deletes words and saves the **whole set atomically** (replace-all); a 「导入种子词」 button merges any missing `SEED_DESENSITIZE_MAP` entries into the editor. Client + hooks in `strategy-components/api/sensitive-words.ts` (`wordsToMap` folds enabled rows into the runtime map). Backend: `/api/sensitive-words` (global/shared; open read, write allowed for admin **or** the `lqq` account), mirroring 菜单管理's store shape. **侧边栏 + 导航栏 menu labels are desensitized** at the data source: `useSidebarMenuItems`/`useActiveThirdLevel` (`core/page-layout/use-sidebar-menu.ts`) map every node's `label` through a desensitizer built **directly from the `/api/sensitive-words` query** (`makeDesensitizer(wordsToMap(words))`, falling back to the global seed `desensitize` while empty) — this sidesteps the `replaceDesensitizeMap` effect-timing race. Only `label` is rewritten; `path`/`id`/`icon` are untouched so routing/highlight are unaffected. All nav surfaces (`page-sidebar.tsx`, `page-sidebar-dark.tsx`, `page-sidebar-v1.tsx`, `strategy-components/Header.tsx`, `PageRoutes.tsx`) consume this hook and are covered; `MenuManagementPage` uses the raw tree so admins still edit real labels.

frontend-web/src/core/scheduled-tasks/api.ts

@@ -42,6 +42,26 @@ export async function listHtmlTemplates() {
   return data.templates ?? [];
 }
 
+/** 「模板数据转换器」对话页「渲染预览」结果。 */
+export type TemplateRenderResult = {
+  ok: boolean;
+  display_only?: boolean;
+  errors: string[];
+  gaps: string[];
+  html: string | null;
+};
+
+/** 调试用:把一段(智能体回复的)文本里的 JSON 填进所选 HTML 模板,返回完整 HTML 与校验信息。 */
+export async function renderTemplateFill(templateId: string, text: string) {
+  return parseResponse<TemplateRenderResult>(
+    await apiFetch(`${baseUrl()}/template-fill/render`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ template_id: templateId, text }),
+    }),
+  );
+}
+
 export interface ListScheduledTasksParams {
   search?: string;
   tagIds?: string[];

frontend-web/src/pages/AgentChatPage.tsx

@@ -31,11 +31,32 @@ import { saveLastAgentId, useThreadSettings } from "@/core/settings";
 import { stopThreadRun, useThreadStream } from "@/core/threads/hooks";
 import { textOfMessage } from "@/core/threads/utils";
 import { OptType, writeYLog } from "@/core/log/y-log";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  renderTemplateFill,
+  useHtmlTemplates,
+  type TemplateRenderResult,
+} from "@/core/scheduled-tasks";
 import { env } from "@/env";
 import { readTaskContext, taskThreadMetadata } from "@/core/auth/task-purpose";
 import { TaskPurposePanel } from "@/strategy-components/components/task-components/TaskPurposePanel";
 import { desensitize } from "@/lib/desensitize";
 
+/** 内置「模板数据转换器」agent 的稳定 id。仅此 agent 的对话页显示「页面模板 + 渲染预览」调试入口。 */
+const TEMPLATE_BUILDER_AGENT_ID = "template-json-builder";
+
 export default function AgentChatPage({
   embeddedAgentId,
   chatBasePath,
@@ -190,6 +211,41 @@ export default function AgentChatPage({
     },
   });
 
+  // ── 「模板数据转换器」对话页专属调试入口（仅此 agent）──────────────────────────
+  // 选一个页面模板，问答跑完后点「渲染预览」：取最近一条 AI 回复里的 JSON 填进模板，
+  // 弹出 HTML 预览 + 结构校验信息，用于调试该智能体的转换效果。
+  const isTemplateBuilder = agent_id === TEMPLATE_BUILDER_AGENT_ID;
+  const { data: debugTemplates = [] } = useHtmlTemplates(isTemplateBuilder);
+  const [debugTemplateId, setDebugTemplateId] = useState("");
+  const [debugPreviewOpen, setDebugPreviewOpen] = useState(false);
+  const [debugBusy, setDebugBusy] = useState(false);
+  const [debugPreview, setDebugPreview] = useState<TemplateRenderResult | null>(
+    null,
+  );
+  const runDebugPreview = useCallback(async () => {
+    if (!debugTemplateId) return;
+    const lastAi = [...thread.messages]
+      .reverse()
+      .find((m) => (m as { type?: string }).type === "ai");
+    const text = (lastAi ? textOfMessage(lastAi) : "") ?? "";
+    setDebugBusy(true);
+    setDebugPreview(null);
+    setDebugPreviewOpen(true);
+    try {
+      const result = await renderTemplateFill(debugTemplateId, text);
+      setDebugPreview(result);
+    } catch (error) {
+      setDebugPreview({
+        ok: false,
+        errors: [error instanceof Error ? error.message : "渲染失败"],
+        gaps: [],
+        html: null,
+      });
+    } finally {
+      setDebugBusy(false);
+    }
+  }, [debugTemplateId, thread.messages]);
+
   const handleSubmit = useCallback(
     (message: PromptInputMessage) => {
       setHasStartedConversation(true);
@@ -327,6 +383,36 @@ export default function AgentChatPage({
                 </div>
 
                 <div className="flex items-center">
+                  {/* 「模板数据转换器」专属：选页面模板 + 渲染预览（调试该智能体效果）。 */}
+                  {isTemplateBuilder && (
+                    <div className="mr-2 flex items-center gap-1.5">
+                      <Select
+                        value={debugTemplateId || undefined}
+                        onValueChange={setDebugTemplateId}
+                      >
+                        <SelectTrigger className="h-8 w-[150px] text-xs">
+                          <SelectValue placeholder="选择页面模板" />
+                        </SelectTrigger>
+                        <SelectContent position="popper">
+                          {debugTemplates.map((tpl) => (
+                            <SelectItem key={tpl.id} value={tpl.id}>
+                              {tpl.name}
+                            </SelectItem>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                      <Tooltip content="用最近一条回复里的 JSON 填进所选模板并预览">
+                        <Button
+                          size="sm"
+                          variant="secondary"
+                          disabled={!debugTemplateId || debugBusy}
+                          onClick={runDebugPreview}
+                        >
+                          {debugBusy ? "渲染中…" : "渲染预览"}
+                        </Button>
+                      </Tooltip>
+                    </div>
+                  )}
                   {/* 3qfx/xdfx 任务深链：用户主动「新建对话」进问答页后，点此发出任务开场信息开始问答。
                       首次进入且无历史（taskAutoStart）会自动发，不显示此按钮。 */}
                   {taskStartText && isLandingState && !taskAutoStart && (
@@ -489,6 +575,70 @@ export default function AgentChatPage({
           showRecentChats={!taskCtxOn}
         />
       </div>
+
+      {/* 「模板数据转换器」调试预览弹窗（仅此 agent）。 */}
+      {isTemplateBuilder && (
+        <Dialog open={debugPreviewOpen} onOpenChange={setDebugPreviewOpen}>
+          <DialogContent className="flex h-[88vh] w-[92vw] max-w-[92vw] flex-col gap-0 p-0">
+            <DialogHeader className="border-b px-4 py-2">
+              <DialogTitle className="text-sm">
+                模板填充预览 · 渲染结果
+              </DialogTitle>
+            </DialogHeader>
+            <div className="max-h-28 overflow-y-auto border-b px-4 py-2 text-xs">
+              {debugBusy && (
+                <span className="text-muted-foreground">正在渲染…</span>
+              )}
+              {!debugBusy && debugPreview && (
+                <div className="flex flex-col gap-1">
+                  <span
+                    className={
+                      debugPreview.html
+                        ? debugPreview.ok
+                          ? "text-emerald-600"
+                          : "text-amber-600"
+                        : "text-destructive"
+                    }
+                  >
+                    {debugPreview.display_only
+                      ? "该模板为「只展示」，已原样输出现有数据"
+                      : debugPreview.html
+                        ? debugPreview.ok
+                          ? "✓ 结构校验通过"
+                          : "⚠ 结构校验有问题（已照常填充，可对照下方修正后再让智能体重答）"
+                        : "✗ 渲染失败"}
+                  </span>
+                  {debugPreview.errors.length > 0 && (
+                    <span className="text-destructive">
+                      错误：{debugPreview.errors.join("；")}
+                    </span>
+                  )}
+                  {debugPreview.gaps.length > 0 && (
+                    <span className="text-muted-foreground">
+                      缺失字段：{debugPreview.gaps.slice(0, 20).join("、")}
+                      {debugPreview.gaps.length > 20 ? " …" : ""}
+                    </span>
+                  )}
+                </div>
+              )}
+            </div>
+            <div className="min-h-0 flex-1 bg-white">
+              {debugPreview?.html ? (
+                <iframe
+                  title="模板填充预览"
+                  srcDoc={debugPreview.html}
+                  sandbox="allow-scripts"
+                  className="size-full border-0"
+                />
+              ) : (
+                <div className="text-muted-foreground flex size-full items-center justify-center text-sm">
+                  {debugBusy ? "正在渲染…" : "无可预览内容"}
+                </div>
+              )}
+            </div>
+          </DialogContent>
+        </Dialog>
+      )}
     </ThreadContext.Provider>
   );
 }

offline-backend-20260512/backend/CLAUDE.md

@@ -300,7 +300,7 @@ Two on-demand/automatic refresh paths layer on top:
 
 **Unified output switches (`require_html` + `require_markdown`).** The task form no longer splits "???? / HTML ??" into separate kinds. `execution_context` now carries two **independent** booleans that may both be on: `require_html` (???? HTML) and `require_markdown` (???? Markdown). `_task_requires_html()` returns true for `require_html` **or** legacy `task_kind == "html_page"` (so old tasks need no data migration), and `_run_task_attempt()` dispatches to `_run_html_page_attempt` when it is true, else the regular agent attempt. When **both** switches are on, `_gather_html_data()` returns `(text, files)` ? the gather agent run is additionally told to save a `.md` file ? and `_run_html_page_attempt` validates it (`MarkdownRequirementError` on failure) and surfaces it alongside the generated page, so the run delivers both artifacts. The single main `prompt` doubles as the HTML page requirement (`html_config.page_prompt`); there is no separate page-prompt field. Tests: `tests/test_scheduled_task_require_html.py` + the markdown-coexistence cases in `tests/test_html_page_tasks.py`.
 
-**Template-fill mode (JSON → 固定 HTML 模板填充).** A third execution mode, distinct from the free-form `require_html` render pipeline: convert a user-supplied JSON into a **fixed** HTML template's data structure and fill it. Triggered when `execution_context.template_config.template_id` is set (chosen in the task form after selecting the built-in **「模板数据转换器」** agent `template-json-builder`). `_task_template_id()` reads it and `_run_task_attempt()` dispatches to `_run_template_fill_attempt` **before** the `require_html` check. Pipeline: take the source (the task `prompt`, pasted or uploaded .json) — which may be **pure JSON, plain text, or text-with-embedded-JSON** (`template_fill.extract_embedded_json` pre-extracts any embedded `{…}`/`[…]` with a string-aware balanced scan and surfaces it as a labeled block while keeping the full original text; plain text → no block, the model reads it semantically) → load the selected agent's `SOUL.md`+model and run a **direct** `_invoke_conversion_model` call (system=SOUL, human=conversion prompt carrying the template's compact **schema skeleton** + the recognized-JSON block + source) → `extract_json_object` → `template_fill.validate_data` (top-level keys + container types) → **on failure feed the structure errors + `field_coverage_gaps` back and retry up to `_MAX_TEMPLATE_FILL_RETRIES`=2** → `template_fill.fill_template` replaces the template's `const DATA={…}` line (and refreshes `MANIFEST.系统.更新时间`) → archive `index.html` + persist a `scheduled_html_pages` row → return `format:"html"` (reusing the existing HTML preview at `/runs/{id}/html`). Any terminal failure raises `TemplateFillError` → run marked failed (no retry, message shown). **Pure engine** `deerflow/runtime/scheduler/template_fill.py` (harness, no `app.*`): the template registry (`TEMPLATES`: id=`no1` name=`no.1` 台湾滨海防卫大屏, and id=`no2` name=`no.2` 台湾飞行部队平台 with **`convertible=False`** — a 「只展示」 template that renders its existing HTML **as-is**, no model/validation/fill, until conversion is wired in later; `_run_template_fill_attempt` short-circuits to `read_template_text` for it, and `list_templates`/`is_convertible` expose the flag so the form hides the JSON input), `list_templates`/`reference_data`/`schema_skeleton_json`/`validate_data`/`field_coverage_gaps`/`fill_template` — **the template's own embedded `DATA` is the schema source of truth** (parsed at load, 1-sample-per-array skeleton fed to the LLM, top-level structure as the validation basis); template HTML files live under `runtime/scheduler/templates/<id>/`, add a `TemplateSpec` to register a no.2. The agent is seeded like the AI-writing ones: `app/gateway/routers/_template_builder_seed.py` + `_template_builder_seed_assets/template-json-builder/{config.yaml,SOUL.md}`, called from the lifespan before `_sync_legacy_agents` (which upserts it into the `agents` table as built-in/published so it shows in `/api/agents` → the task form's 执行智能体 dropdown). Template list API: `GET /api/scheduled-tasks/html-templates` → `{templates:[{id,name,description}]}` (open). Frontend: when the agent dropdown = `template-json-builder` the form hides the HTML/Markdown switches and shows a 「HTML模板」 select (`useHtmlTemplates`) + a .json upload (reads file text into the prompt box). Tests: `tests/test_template_fill.py`, `tests/test_template_fill_attempt.py`, `tests/test_template_builder_seed.py`.
+**Template-fill mode (JSON → 固定 HTML 模板填充).** A third execution mode, distinct from the free-form `require_html` render pipeline: convert a user-supplied JSON into a **fixed** HTML template's data structure and fill it. Triggered when `execution_context.template_config.template_id` is set (chosen in the task form after selecting the built-in **「模板数据转换器」** agent `template-json-builder`). `_task_template_id()` reads it and `_run_task_attempt()` dispatches to `_run_template_fill_attempt` **before** the `require_html` check. Pipeline: take the source (the task `prompt`, pasted or uploaded .json) — which may be **pure JSON, plain text, or text-with-embedded-JSON** (`template_fill.extract_embedded_json` pre-extracts any embedded `{…}`/`[…]` with a string-aware balanced scan and surfaces it as a labeled block while keeping the full original text; plain text → no block, the model reads it semantically) → load the selected agent's `SOUL.md`+model and run a **direct** `_invoke_conversion_model` call (system=SOUL, human=conversion prompt carrying the template's compact **schema skeleton** + the recognized-JSON block + source) → `extract_json_object` → `template_fill.validate_data` (top-level keys + container types) → **on failure feed the structure errors + `field_coverage_gaps` back and retry up to `_MAX_TEMPLATE_FILL_RETRIES`=2** → `template_fill.fill_template` replaces the template's `const DATA={…}` line (and refreshes `MANIFEST.系统.更新时间`) → archive `index.html` + persist a `scheduled_html_pages` row → return `format:"html"` (reusing the existing HTML preview at `/runs/{id}/html`). Any terminal failure raises `TemplateFillError` → run marked failed (no retry, message shown). **Pure engine** `deerflow/runtime/scheduler/template_fill.py` (harness, no `app.*`): the template registry (`TEMPLATES`: id=`no1` name=`no.1` 台湾滨海防卫大屏, and id=`no2` name=`no.2` 台湾飞行部队平台 with **`convertible=False`** — a 「只展示」 template that renders its existing HTML **as-is**, no model/validation/fill, until conversion is wired in later; `_run_template_fill_attempt` short-circuits to `read_template_text` for it, and `list_templates`/`is_convertible` expose the flag so the form hides the JSON input), `list_templates`/`reference_data`/`schema_skeleton_json`/`validate_data`/`field_coverage_gaps`/`fill_template` — **the template's own embedded `DATA` is the schema source of truth** (parsed at load, 1-sample-per-array skeleton fed to the LLM, top-level structure as the validation basis); template HTML files live under `runtime/scheduler/templates/<id>/`, add a `TemplateSpec` to register a no.2. The agent is seeded like the AI-writing ones: `app/gateway/routers/_template_builder_seed.py` + `_template_builder_seed_assets/template-json-builder/{config.yaml,SOUL.md}`, called from the lifespan before `_sync_legacy_agents` (which upserts it into the `agents` table as built-in/published so it shows in `/api/agents` → the task form's 执行智能体 dropdown). Template list API: `GET /api/scheduled-tasks/html-templates` → `{templates:[{id,name,description,convertible}]}` (open). **Debug-render API** `POST /api/scheduled-tasks/template-fill/render` `{template_id, text?|data?}` → `{ok, display_only?, errors, gaps, html}` (open): no model call — `extract_embedded_json(text)` (or `data`) → `validate_data` → `fill_template`, returning the filled HTML **plus** the validation errors/field-gaps (fills even when invalid so you can see the effect). Powers the chat-page debug button below; non-convertible templates return their raw HTML. Frontend: when the agent dropdown = `template-json-builder` the form hides the HTML/Markdown switches and shows a 「HTML模板」 select (`useHtmlTemplates`) + a .json upload (reads file text into the prompt box). Tests: `tests/test_template_fill.py`, `tests/test_template_fill_attempt.py`, `tests/test_template_builder_seed.py`.
 
 ### Per-user Prompts & UI Preferences
 

offline-backend-20260512/backend/app/gateway/routers/scheduled_tasks.py

@@ -221,6 +221,50 @@ async def list_html_templates() -> dict:
     return {"templates": template_fill.list_templates()}
 
 
+class TemplateRenderRequest(BaseModel):
+    """「模板数据转换器」对话页的调试渲染入参。"""
+
+    template_id: str
+    # 智能体回复原文(含转换后的 JSON);后端用 extract_embedded_json 抽取后填充。
+    text: str | None = None
+    # 或直接给已解析好的对象(优先于 text)。
+    data: Any | None = None
+
+
+@router.post("/template-fill/render")
+async def render_template_fill(body: TemplateRenderRequest) -> dict:
+    """调试用:把一段(智能体回复的)内容里的 JSON 填进所选 HTML 模板并返回完整 HTML。
+
+    供「模板数据转换器」对话页的「渲染预览」按钮调试智能体效果——不调模型,只做
+    抽取 → 校验 → 填充,把校验错误/缺失字段一并返回方便定位。「只展示」模板原样返回。
+    开放给任意登录用户。
+    """
+    from deerflow.runtime.scheduler import template_fill
+
+    spec = template_fill.get_template(body.template_id)
+    if spec is None:
+        raise HTTPException(status_code=404, detail=f"未知模板：{body.template_id}")
+
+    # 「只展示」模板(no.2 等):原样返回模板 HTML。
+    if not spec.convertible:
+        html = template_fill.read_template_text(body.template_id)
+        return {"ok": True, "display_only": True, "errors": [], "gaps": [], "html": html}
+
+    obj = body.data
+    if obj is None and body.text:
+        obj = template_fill.extract_embedded_json(body.text)
+    if obj is None:
+        return {"ok": False, "errors": ["未从内容中识别到可用的 JSON"], "gaps": [], "html": None}
+
+    errors = template_fill.validate_data(body.template_id, obj)
+    gaps = template_fill.field_coverage_gaps(body.template_id, obj)
+    try:
+        html = template_fill.fill_template(body.template_id, obj)
+    except template_fill.TemplateError as exc:
+        return {"ok": False, "errors": [str(exc)], "gaps": gaps, "html": None}
+    return {"ok": not errors, "errors": errors, "gaps": gaps, "html": html}
+
+
 @router.get("")
 async def list_scheduled_tasks(
     request: Request,