openJiuwen DeepSearch 报告样式化:report_style_css 提示词模板与 LLM 驱动 CSS 生成管线深度解析
openJiuwen DeepSearch 报告样式化:report_style_css 提示词模板与 LLM 驱动 CSS 生成管线深度解析
导读
openJiuwen DeepSearch 在报告导出环节内置了一套「LLM 生成报告 CSS」的样式化能力:系统将报告标题、标题树、摘要与内容统计作为结构化上下文喂给模型,由模型为固定 1280px 桌面画布设计一套完整的视觉系统。本文以 report_style_css 用户侧提示词模板 为核心骨架,结合同目录下的 系统侧设计约束 与 report_style 模块 源码,完整拆解提示词变量含义、上下文构建、CSS 规整注入、封面可读性保护、语义 DOM 装饰与失败回退机制。读完本文,你将掌握这套提示词模板的每个占位变量如何被填充、模型输出如何被安全地写入报告 HTML,以及如何复用同一套模板体系扩展新的报告样式化场景。
一、模板定位:报告导出链路中的样式化阶段
在 DeepSearch 的 HTML 报告导出流程中,样式化是一个可选的增强步骤,统一由 导出编排入口 export_report 调度。其核心调用链如下:
build_report_bundle将工作流最终结果(Markdown 原文与图表资源)打包为临时目录 bundle;convert_md_to_html先将 Markdown 转为带基础样式与语义结构的 HTML(HTML 导出实现);- 当
enable_html_styling=True时调用_apply_html_style:先通过build_style_context提炼样式上下文,再用build_prompt_messages("report_style_css", ...)渲染提示词消息,随后调用 LLM 生成 CSS; - 生成的 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 会按以下分支处理:
- 解析封面背景:从模型 CSS 中提取
.report-cover的background/background-color声明,支持纯色与含十六进制色标的linear-gradient,并解析var(--xxx)变量引用; - 背景可解析且标题色对比度达 4.5:1 → 原样返回,不覆盖模型设计(测试
test_append_cover_title_contrast_safeguard_keeps_readable_cover_title); - 背景可解析但对比度不足 → 在 CSS 末尾追加
.report-cover > h1 { color: #ffffff !important; }或深色候选色(黑白二选一,取与所有背景色最小对比度更大的那个),即title_color_override模式; - 背景声明存在但无法解析(如
url(cover.svg))→ 追加标题底板兜底:白色文字 +#0f172a深色不透明底板 +padding+box-decoration-break: clone,即title_backdrop模式; - 未修改封面背景 → 保持模型原有标题设计。
其中对比度计算完整实现了 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 保留原资源。
八、实战要点小结
- 模板变量是唯一的信息通道:修改
report_style_css/user.md即可控制模型可感知的报告维度;要新增维度(如章节数、引用来源域名),需同步扩展 StyleContext 的提取逻辑与to_prompt_dict。 - system.md 是机器可校验的契约:封面标题 4.5:1 对比度、
.report-shell1280px 唯一宽度、表头颜色设在th本身、禁止外部资源等条款,都有对应的服务端保护或基线样式兜底。 - 模型输出按「原样注入 + 定点兜底」处理:规整阶段不筛选声明(保持模型自由度),只由对比度保护对封面标题这一个点做强制修正。
- 回退永远是安全的:样式化是导出链路的增强层,任何失败都不影响报告 bundle 的完整性与可用性。
若需在生产环境启用该能力,只需在调用 export_report 时传入 enable_html_styling=True 并提供已初始化的 LLM 运行时对象(HTML styling requires an initialized LLM 为缺失时的显式校验提示);而 stylize_report 作为保留的兼容入口,内部同样委托给统一的 export_report 完成导出,集成方无需关心实现迁移。
参考与延伸阅读
- 提示词模板本体:user.md 与 system.md
- 上下文构建:context.py
- CSS 处理:css.py
- 语义 DOM 装饰:structure.py
- 导出编排:service.py 与 html_export.py
- 提示词渲染设施:message_builder.py
- 运行时配置:report_style_runtime.py
- 测试佐证:test_css.py、test_style_context.py、test_structure.py、test_service.py、test_report_style_runtime.py