openJiuwen DeepSearch 报告样式化:report_style_css 提示词模板与 LLM 驱动 CSS 生成管线深度解析

原创2026-10-12 13:05:101,630 阅读
文章标签:人工智能大模型AI Agent深度研究RAG代码智能体搜索引擎Agent 工作流

openJiuwen DeepSearch 报告样式化:report_style_css 提示词模板与 LLM 驱动 CSS 生成管线深度解析

导读

openJiuwen DeepSearch 在报告导出环节内置了一套「LLM 生成报告 CSS」的样式化能力:系统将报告标题、标题树、摘要与内容统计作为结构化上下文喂给模型,由模型为固定 1280px 桌面画布设计一套完整的视觉系统。本文以 report_style_css 用户侧提示词模板 为核心骨架,结合同目录下的 系统侧设计约束 与 report_style 模块 源码,完整拆解提示词变量含义、上下文构建、CSS 规整注入、封面可读性保护、语义 DOM 装饰与失败回退机制。读完本文,你将掌握这套提示词模板的每个占位变量如何被填充、模型输出如何被安全地写入报告 HTML,以及如何复用同一套模板体系扩展新的报告样式化场景。

一、模板定位:报告导出链路中的样式化阶段

在 DeepSearch 的 HTML 报告导出流程中,样式化是一个可选的增强步骤,统一由 导出编排入口 export_report 调度。其核心调用链如下:

  1. build_report_bundle 将工作流最终结果(Markdown 原文与图表资源)打包为临时目录 bundle;
  2. convert_md_to_html 先将 Markdown 转为带基础样式与语义结构的 HTML(HTML 导出实现);
  3. 当 enable_html_styling=True 时调用 _apply_html_style:先通过 build_style_context 提炼样式上下文,再用 build_prompt_messages("report_style_css", ...) 渲染提示词消息,随后调用 LLM 生成 CSS;
  4. 生成的 CSS 依次经过规整(normalize_css_output)、封面标题对比度保护(append_cover_title_contrast_safeguard)与注入(inject_css),最终写入 HTML。

其中第 3 步使用的正是 report_style_css 提示词目录:system.md 提供角色设定与设计约束,user.md 提供本次报告的结构化信息。二者合起来构成一次完整的 LLM 样式化请求。

二、用户侧模板解剖:六个占位变量逐一说明

user.md 全文即一个 Jinja2 模板,定义了模型在生成 CSS 前可以读取的全部报告信息:

Report title: {{ report_title }}

Heading tree:
{{ headings }}

Abstract:
{{ abstract }}

Content statistics: {{ table_count }} table rows, {{ image_count }} images, and {{ citation_count }} citations.

模板中每个变量都由 StyleContext 在运行时填充,to_prompt_dict() 方法将它们转换为模板渲染所需的字典。各变量含义与来源如下:

模板变量 说明 填充来源
report_title 报告一级标题;Markdown 无标题时回退为默认名 Report 首个 # 标题文本
headings 按出现顺序排列的完整标题树,每一行以 - 前缀开头,并保留 # 层级符号(如 - # 总览、- ## 市场规模) 正则 ^(#{1,6})[ \t]+(.+?)[ \t]*$ 全量提取
abstract 完整摘要段落;无摘要时回退为首个正文块的前 4000 字符 对「摘要」/「abstract」标题区间的内容提取
table_count Markdown 表格行数(以行首 ` ` 计数),用于判断数据密度
image_count Markdown 图片数量 正则 !\[[^\]]*]\([^)]+\)
citation_count 外链引用数量(形如 [[数字]](http(s)://...)) 正则 \[\[\d+]]\(https?://[^)]+\)

2.1 标题树为何保留 # 层级

从 context.py 实现 的注释可以确认:保留 # 层级,是为了让模型能从扁平文本中恢复章节父子关系。测试 test_style_context.py 验证了 build_style_context 会保留 ("# 总览", "## 市场规模", "### 区域分布") 并转换为 - # 总览 形式的渲染结果。这意味着模型在配色、字号层级设计时,能准确判断 h1/h2/h3/h4 的归属,从而遵守 system.md 中「一级章节用 .report-section > h1,二级至四级子节保持 h2/h3/h4」的结构契约。

2.2 摘要提取的两种策略

摘要提取逻辑(_extract_abstract)是模板上下文中最重要的「语义浓缩」环节:

  • 存在摘要标题时:找到文本为「摘要」或「abstract」(不区分大小写)的标题,取其到下一个同级或更高级标题之间的完整内容,中间可跨多个段落;
  • 不存在摘要标题时:剔除所有标题后取首个按空行分隔的正文块,并硬性截断到 4000 字符,避免超长报告撑爆提示词。

测试 test_build_style_context_uses_complete_abstract_and_heading_tree 验证了「完整摘要两段都被提取」,而 test_build_style_context_falls_back_to_first_body_block_at_4000_chars 验证了无摘要时的 4000 字符回退上限。这种设计使模板始终只向 LLM 暴露「有界语义上下文」,而非整篇长报告。

三、系统侧约束:system.md 定义的视觉系统契约

与 user.md 配对的是 system.md。它将模型角色设定为「专业研究报告视觉设计师」,并给出四组可机器校验的硬约束:

3.1 设计对象清单

模型需要为一套固定的桌面画布设计完整视觉系统,覆盖以下 DOM 区域:

  • .report-cover:报告封面,需体现主题、标题层级与视觉焦点;
  • .report-abstract:摘要卡片,相对正文有清晰的层级关系;
  • .report-section 及其 h1/h2/h3/h4:章节组织、阅读节奏与关键信息;
  • .report-table、table、th、td:数据表格的表头、分隔与可读性;
  • .report-figure、.mermaid-wrap、.figure-caption、img:图表、图注与正文的协调;
  • .citation 与链接:来源可辨识且不打断阅读。

3.2 封面可读性的强制要求

system.md 对封面标题(.report-cover > h1)有非常明确的硬性规定:

  • 必须直接在 .report-cover > h1 上设置 color,不能只依赖从 .report-cover 继承;
  • 标题色必须是不透明十六进制色(#RRGGBB),且与封面所有不透明背景色/渐变停止色的对比度 ≥ 4.5:1(WCAG AA 级别);
  • 禁止用 background-image、透明封面背景或装饰覆盖层作为标题可读性的唯一手段。

这条约束直接对应服务端的「对比度保护」实现,见下文第五节。

3.3 严格输出约束

  • 只输出 CSS 文本,不输出 Markdown 围栏、HTML、JavaScript 或解释说明;
  • 仅面向固定桌面画布,禁止输出 @media 媒体查询;
  • 禁止 @import、@font-face、url()、外部字体与外部资源;
  • 不得修改、伪造、添加、隐藏或重排报告文本、链接、SVG 内容与资源路径;不得使用「加载、替换、覆盖或隐藏报告内容」的 CSS;
  • 页面画布宽度只由 .report-shell 上的 1280px 基线样式控制,不得设置或覆盖页面宽度与视口尺寸;
  • 优先使用系统字体,并重点关注中文研究报告的封面、摘要、章节、表格、图表、图注与引用可读性。

这些约束的存在保证了模型 CSS 即使「天马行空」,也永远不会破坏报告内容本身——这正是样式化阶段可以安全回退的前提(见第七节)。

四、上下文构建:StyleContext 数据流

模板填充的完整数据流可以总结为:

Markdown 报告
   │  build_style_context(markdown)
   ▼
StyleContext(title, headings, abstract, table_count, image_count, citation_count)
   │  to_prompt_dict()
   ▼
{report_title, headings, abstract, table_count, image_count, citation_count}
   │  build_prompt_messages("report_style_css", context)
   ▼
[{"role": "system", "content": system.md 渲染结果},
 {"role": "user",   "content": user.md 渲染结果}]
   │  ainvoke_llm_with_stats(llm, messages, llm_type="basic")
   ▼
模型返回 CSS 文本(可能带 ```css 围栏)

从 message_builder.py 的实现可以看到,提示词消息构建是一套通用的模板渲染设施:system.md 会被静态校验(不得含运行时变量与动态 include),user.md 通过 meta.find_undeclared_variables 收集变量并渲染。因此 report_style_css 只是这套体系下的一个模板实例,其 system.md 被 _assert_static_template_tree 断言为完全静态,保证设计约束永不因上下文注入而走样。

五、模型输出处理:从原始文本到安全 CSS

LLM 返回的原始文本不能直接写入 HTML,必须经过 css.py 中三个阶段的处理。

5.1 normalize_css_output:规整与校验

normalize_css_output 只做两件事:类型校验(非字符串直接抛 ValueError: CSS must be a string)与围栏剥离(_strip_css_fence)。围栏剥离有两个细节:

  • 完整匹配 ```css ... ``` 时移除整段围栏;
  • 模型在 token 截断时可能漏掉结尾的 ```,此时只移除开头的 CSS 围栏,避免把正文中的 Markdown 围栏误认作样式内容。

测试 test_css.py 用参数化用例验证了一个关键设计:任意非空 CSS 都会被原样保留(verbatim)——包括 @media、.report-cover { display: none; }、.report-shell { width: 960px } 等「违规」样式。也就是说,模块并不在规整阶段过滤声明,而是把校验责任前移到 system.md 约束与后置的兜底保护上;同时模型回答为空字符串或空围栏时则拒绝注入。

5.2 append_cover_title_contrast_safeguard:封面标题对比度保护

这是整套样式化管线中最精巧的源码级保障。append_cover_title_contrast_safeguard 会按以下分支处理:

  1. 解析封面背景:从模型 CSS 中提取 .report-cover 的 background / background-color 声明,支持纯色与含十六进制色标的 linear-gradient,并解析 var(--xxx) 变量引用;
  2. 背景可解析且标题色对比度达 4.5:1 → 原样返回,不覆盖模型设计(测试 test_append_cover_title_contrast_safeguard_keeps_readable_cover_title);
  3. 背景可解析但对比度不足 → 在 CSS 末尾追加 .report-cover > h1 { color: #ffffff !important; } 或深色候选色(黑白二选一,取与所有背景色最小对比度更大的那个),即 title_color_override 模式;
  4. 背景声明存在但无法解析(如 url(cover.svg))→ 追加标题底板兜底:白色文字 + #0f172a 深色不透明底板 + padding + box-decoration-break: clone,即 title_backdrop 模式;
  5. 未修改封面背景 → 保持模型原有标题设计。

其中对比度计算完整实现了 WCAG 规范:_relative_luminance 按 sRGB 线性化((c/255 + 0.055)/1.055)^2.4)加权 0.2126/0.7152/0.0722,_contrast_ratio 计算 (L1+0.05)/(L2+0.05)。服务端只追加 .report-cover > h1 规则,不会改变模型为其余报告区域生成的样式(见 service.py 中 _apply_html_style 的注释)。

5.3 inject_css:注入基础样式之后

inject_css 将规整后的 CSS 以 <style id="report-style-generated"> 标签形式插入到 </head> 之前——即紧跟基础样式表之后。测试 test_inject_css_appends_generated_style_after_baseline_style 验证了模型样式一定排在基础样式之后,从而能按 CSS 层叠规则覆盖基线;HTML 缺少 </head> 时抛出 ValueError: HTML document has no head closing tag。

六、语义 DOM 装饰:模型样式的作用对象

模型设计的 .report-cover、.report-section、.report-table 等选择器并非凭空存在,而是由 structure.py 的 decorate_report_html 在 HTML 导出阶段预先构建的稳定语义结构。其核心逻辑:

  • body 打上 .report-page,内层创建 main.report-shell(1280px 画布)与 div.report-content;
  • 第一个标题(任意层级,包括「摘要」/「Abstract」)成为 header.report-cover 封面;没有标题时,首个非空白内容块成为封面;
  • 封面之后同级的「摘要」/「Abstract」标题形成 section.report-abstract 摘要区;
  • 与封面同级的后续标题各自开启 section.report-section 章节;低于封面层级的标题留在章节内部形成 h2/h3/h4 层级;
  • _mark_data_blocks 为 figure、.mermaid-wrap、含图片的段落追加 report-figure,为表格或其 .table-wrap 父容器追加 report-table;
  • SVG 标记在装饰期间用占位符保护,序列化后原样恢复,确保图表渲染内容不被 BeautifulSoup 改写。

测试 test_structure.py 覆盖了多种边界:h2 封面 + h3 子节、目录先于摘要、无标题文档、仅有标题的文档、SVG 占位符注释的幂等性等。这份「结构契约」与 system.md 中的 HTML 结构契约一一对应,是模型 CSS 能够精准命中封面上级容器的前提。

值得注意的还有 HTML_TEMPLATE 中内嵌的 STYLED_CSS_OVERLAY 基线:它在 page_variant="styled" 时启用,将 body 外边距清零、.report-shell 固定为 width: 1280px; margin: 48px auto,并为 .report-section > h1 和 .report-table th 提供默认高对比度配色。system.md 中「表格表头背景必须设在 th 本身而非 thead」的要求,正对应这段基线中 .report-table th 的 background-color 与 color 直接声明。

七、运行时与回退机制

7.1 样式化 LLM 运行时

样式化调用使用通用模型而非专门的写作模型。 report_style_llm_context 会从配置中选择 general 类别(或直接传入的 model_name 配置),创建 LLM 实例后通过 ContextVar token 压入会话上下文,结束时精确恢复调用方的上下文。测试 test_report_style_runtime.py 验证了「使用 general 模型并恢复外层上下文」,以及缺失可用配置时抛出 llm_config 校验错误。

7.2 五阶段回退与状态码

_apply_html_style 将整个样式化过程划分为 build_style_context → apply_prompt → invoke_llm → extract_css_response → normalize_css_output → append_cover_title_contrast_safeguard → inject_css 多个阶段,任何异常(模型不可用、超时、空 CSS、非字符串 CSS、注入失败)都会触发回退到基础 HTML,且只记录阶段名、异常类型与 CSS 长度,绝不把模型 CSS 内容写入日志(测试 test_stylize_report_logs_css_lengths_without_css_content 与 test_stylize_report_logs_compact_fallback_diagnostics 均有断言)。

最终通过 ReportExportResult 的 style_status 向调用方暴露样式状态,取值有四档:

style_status 含义 触发条件
applied 模型 CSS 成功注入 全流程无异常
fallback 回退到基础 HTML 样式化任一阶段失败
not_requested 未启用样式化 enable_html_styling=False
not_supported 格式不支持样式化 export_format="docx"

核心设计原则是「样式生成不能影响已经成功构建的研究报告」——即使样式阶段完全失败,用户拿到的仍是一份完整、可读的基础 HTML 报告。端到端测试 test_service.py 通过 mock LLM 验证了完整闭环:bundle 中 report.md 原文不变、report.html 包含 report-style-generated 样式块、VLM 生成的 PNG 以 base64 内嵌且 bundle 保留原资源。

八、实战要点小结

  1. 模板变量是唯一的信息通道:修改 report_style_css/user.md 即可控制模型可感知的报告维度;要新增维度(如章节数、引用来源域名),需同步扩展 StyleContext 的提取逻辑与 to_prompt_dict。
  2. system.md 是机器可校验的契约:封面标题 4.5:1 对比度、.report-shell 1280px 唯一宽度、表头颜色设在 th 本身、禁止外部资源等条款,都有对应的服务端保护或基线样式兜底。
  3. 模型输出按「原样注入 + 定点兜底」处理:规整阶段不筛选声明(保持模型自由度),只由对比度保护对封面标题这一个点做强制修正。
  4. 回退永远是安全的:样式化是导出链路的增强层,任何失败都不影响报告 bundle 的完整性与可用性。

若需在生产环境启用该能力,只需在调用 export_report 时传入 enable_html_styling=True 并提供已初始化的 LLM 运行时对象(HTML styling requires an initialized LLM 为缺失时的显式校验提示);而 stylize_report 作为保留的兼容入口,内部同样委托给统一的 export_report 完成导出,集成方无需关心实现迁移。

参考与延伸阅读

登录后查看全文
deepsearch