openJiuwen DeepSearch 报告摘要生成提示词模板深度解析:从 Jinja 模板到流水线落地
openJiuwen DeepSearch 报告摘要生成提示词模板深度解析:从 Jinja 模板到流水线落地
openJiuwen DeepSearch 在生成研究报告时,会在所有子报告(sub-reports)完成后,由 Reporter 编排器并发调用 LLM 生成一篇凝练、单段落的报告摘要(Abstract)。本文以 report_abstract_markdown/user.md 与同目录 system.md 为切入点,完整解析这对提示词模板的变量契约、格式约束与数学公式规范,并结合 report_parts.py、report.py、message_builder.py 等源码与测试用例,讲清"模板如何被渲染、摘要如何被生成、后处理如何兜底"的完整链路,为二次开发、Prompt 调优与问题排查提供可直接参考的实现细节。
一、摘要生成在报告流水线中的位置
1.1 摘要属于报告"部件"而非正文
在 openJiuwen DeepSearch 中,报告正文由各章节子报告拼接而成,而摘要、结论、参考资料属于报告级"部件"(parts)。源码 report_utils.py 中的 ArticlePart 类把报告划分为 abstract、conclusion、reference 三类部件,并为中英文分别定义了标题、占位提示与缺失时的兜底文案:
- 中文:
# 摘要/# 结论/# 参考文章 - 英文:
# Abstract/# Conclusion/# Reference Articles - 生成失败时的兜底文案(
not_found_prompts),例如中文摘要为空时输出# 摘要\n\n[未能从生成内容中提取到摘要]
摘要生成完成后,generate_report 会按照"报告标题 → 一级目录 → 摘要 → 正文章节 → 结论 → 参考文章"的顺序拼接最终 Markdown 报告,可见摘要处于目录之后、正文之前的黄金位置,承担着"让读者/决策者在读完一段话后即把握全文核心结论"的任务。
1.2 摘要与结论的并发编排
报告编排入口 generate_report 在子报告全部生成完毕后,先构建"紧凑章节上下文",再并发发起摘要与结论两路生成任务:
abstract_context = self._build_reporter_compact_context("abstract")
conclusion_context = self._build_reporter_compact_context("conclusion")
sub_reports_content = sub_report_res.get("sub_reports_content")
abstract_task = asyncio.create_task(
self.generate_abstract(abstract_context or sub_reports_content)
)
conclusion_task = asyncio.create_task(
self.generate_conclusion(conclusion_context or sub_reports_content)
)
值得注意的两点:
- 优先使用紧凑上下文:若
_build_reporter_compact_context("abstract")能构建出结构化的章节摘要(详见 1.3),则传入该紧凑上下文;否则回退到"完整拼接正文"(sub_reports_content)。测试用例 test_general_report.py 专门验证了"紧凑上下文为空时回退完整正文"这一分支。 - 并发执行:摘要与结论通过
asyncio.create_task并发运行,任一路失败(RetryError或未知异常)都会导致整篇报告生成失败并返回格式化错误,而不是产出残缺报告。
1.3 摘要的输入:紧凑章节上下文
_build_reporter_compact_context(report_parts.py)负责把各子报告的 sidecar 元数据压缩为摘要/结论的 Prompt 输入,其核心逻辑:
- 优先使用
ChapterSidecar.chapter_summary(结构化摘要),缺失时回退到sub_report_content_summary(全文兜底摘要),并在文本中显式标注Summary/Summary (fallback); - 逐章输出
Chapter {section_id} {section_task}标题行; - 针对
target == "abstract",只取key_findings前 3 条(findings[:3]);而结论阶段取全部 findings 并额外携带risk_points(风险点)。这正是摘要与结论信息量差异的设计体现:摘要讲"核心发现",结论讲"综合判断与风险"。
测试用例 test_build_reporter_compact_context_selects_fields_by_target 精确断言了这一差异:摘要上下文中包含"发现1""发现3"但不包含"发现4"与"风险1",而结论上下文中两者皆在。
二、提示词模板结构逐段解析
report_abstract_markdown 目录下是一对 Jinja2 模板:system.md(系统提示,静态无变量)与 user.md(用户消息,含变量渲染)。
2.1 system.md:摘要写作指南
system.md 定义了"专业 Deep Researcher 写作者"的角色约束,全文可分四层:
(1)接地边界(Grounding Boundary)
The provided input may be compact chapter context containing
SummaryandKey findings. Treat it as the complete grounding boundary: use only information explicitly present in the input, and do not add facts, numbers, entities, examples, or judgments from outside the input.
这是整个摘要提示的"事实红线":输入即证据边界,LLM 不得引入输入之外的任何事实、数字、实体、示例或判断。这保证了摘要的可溯源性与防幻觉,与 openJiuwen DeepSearch 的片段级引用溯源能力一脉相承。
(2)摘要格式约束(Abstract)
- 必须输出恰好一个文本块:无项目符号、无标题、无换行、无段落分隔;
- 只总结源自子报告的事实与关键信息,避免模糊、泛化或推测性表述;
- 关键数字与术语用加粗(如
**18%**、**关键信息**); - 公式一律使用行内数学
$...$,绝不用**...**包裹公式; - 不得包含任何章节标题(如"摘要")、元数据或解释性注释,直接以摘要内容开头。
(3)数学公式语法(Mathematical Formula Syntax)
- 摘要为单段落,只允许行内数学
$...$(单个美元符),禁止块级数学$$...$$; - 使用标准 LaTeX:
\ln、e^{rT}、\frac、\sqrt{}、\sigma、\mu、\Pi; - 禁止用加粗包裹公式(加粗仅用于数字与关键术语);
- 每个分隔符对必须闭合:每个
\left需配对\right,每个{需配对}; - 每个公式必须自包含:格式错误的公式会破坏 HTML 与 DOCX 渲染。
这条公式规范并非空话——由于早期提示词只要求"关键信息加粗"而缺少公式格式指导,LLM 常把公式误用 **..** 包裹,为此源码专门实现了后处理兜底函数(见 4.3 节)。
(4)Critical Requirements
模板末尾以 # Critical Requirements 收尾,提示后续还有不可省略的硬性要求(模板文件本身到此处结束,未展示的强约束由 system.md 其余行承载,读者可直接打开文件查阅完整内容)。
2.2 user.md:用户消息模板(变量契约核心)
user.md 全文即本文关联文档,是一个典型的"条件块 + 主体内容"结构:
{% if audience_role or tone %}
## Report Detail Constraints
{% if audience_role %}
- **Target Audience**: {{ audience_role }}. Lead with conclusions this audience needs for decisions; avoid textbook-style background.
{% endif %}
{% if tone %}
- **Tone Intent**: {{ tone }}. Interpret as writing stance (English enum, e.g. objective, formal, analytical). Stay consistent with sub-reports; do not shift style.
{% endif %}
{% endif %}
Main Content: {{main_content}}
- The language of generated content is specified by language = **{{language}}**
三个关键设计点:
audience_role与tone为可选变量:只有二者至少提供一个时,才渲染Report Detail Constraints小节。audience_role要求"以该受众决策所需结论开头,避免教科书式背景铺陈";tone要求按英文枚举(如objective、formal、analytical)理解为写作立场,且必须与子报告保持风格一致、不得中途换风格。main_content为必填主体变量:承载紧凑章节上下文或完整拼接正文(由 1.2 节的编排逻辑决定)。language控制输出语言:明确告知 LLM 生成内容语言由language指定,对应枚举值见 config.py 的ReportLang:zh-CN与en-US。
三、模板变量契约与自动化校验
3.1 契约声明:哪些变量必填、哪些可选
仓库用一套集中式契约表(test_deepresearch_prompt_contracts.py)声明每个 Prompt 模板暴露的变量。对 report_abstract_markdown:
- 必填变量:
main_content、language - 可选变量:
audience_role、tone(由_OPTIONAL_VARIABLES中"report_abstract_markdown": {"audience_role", "tone"}声明,见 第135行)
这与 user.md 的 {% if %} 条件渲染一一对应:可选变量在调用方上下文缺失时被安全省略,模板渲染不会报错。
3.2 契约测试如何守护模板稳定性
test_prompt_contract 测试(第244-260行)用 Jinja2 的 meta.find_undeclared_variables 解析模板变量集合,并断言:
- system 模板不得包含任何运行时变量(
system_vars == set()); - user 模板变量集合必须精确等于
required_vars | optional_vars(不多不少)。
这意味着:任何人修改 user.md 增加或删除一个变量名,而不同步更新契约表,测试就会失败。这是一道防止"模板与调用方脱钩"的自动化防线。此外,测试还通过 test_current_date_is_limited_to_design_whitelist_and_systems_are_time_free 断言 system 模板中不允许出现 CURRENT_TIME,且只有白名单内的 Prompt 才能声明 current_date——摘要模板不在 DATE_PROMPTS 白名单中,因此摘要生成不依赖当前日期。
3.3 渲染器的变量注入逻辑
模板由 message_builder.py 的 build_prompt_messages 统一渲染:
render_context = dict(context or {})
_validate_name_and_context(prompt_name, render_context)
environment = _create_environment()
system_text = environment.get_template(system_name).render() # system 模板无变量
# ...
user_variables = _template_variables(environment, user_name, recursive=True)
if "current_date" in user_variables and "current_date" not in render_context:
render_context["current_date"] = datetime.now(timezone.utc).date().isoformat()
user_text = environment.get_template(user_name).render(**render_context)
渲染器同时做了两类安全校验:提示名必须匹配 ^[A-Za-z0-9_-]+$;上下文不得占用 messages、history、prior_messages、images 等预留键。system 模板还会被递归断言为静态(不含动态 include 与变量),确保系统提示永远稳定、不被调用方污染。
四、摘要生成的底层调用链与后处理
4.1 从 generate_abstract 到 LLM 调用
摘要生成的入口是 ReportPartsMixin.generate_abstract:
async def generate_abstract(self, sub_reports_content: str) -> str:
logger.info(f"Start to generate abstract with llm...")
report_format = ReportFormat.MARKDOWN
prompt = f"report_abstract_{report_format.get_name()}"
abstract = await self._generate_with_llm("abstract", prompt, sub_reports_content)
logger.info(f"Generating report abstract Done.")
return abstract
注意 prompt = "report_abstract_markdown" 的拼装方式:模板目录按 report_abstract_{format} 命名,目前固定为 Markdown 格式,为未来按 Word/PPT 等格式扩展预留了命名空间。
_generate_with_llm(第67-97行)完成消息构建与带重试的调用:
- 通过
build_prompt_messages(prompt, {**self.gen_report_context, "main_content": content})渲染 system + user 消息;gen_report_context中天然携带language、audience_role、tone等字段; - 任务类型映射到专属 Agent 名:
"abstract" → REPORTER_ABSTRACT(常量值reporter_abstract,定义于 node_constants.py),与结论的reporter_conclusion、过渡句的reporter_transaction区分,便于按 Agent 维度做统计与限流; - 使用 tenacity
AsyncRetrying按Config().service_config.report_max_generate_retry_num重试,仅在捕获到异常时重试,失败后统一抛出。
测试用例 test_general_report.py 验证了 generate_abstract("test content") 会以 ("abstract", "report_abstract_markdown", "test content") 调用 _generate_with_llm;而 test_abstract_network_retry_reuses_request_snapshot 则验证了网络错误重试时复用同一份请求消息快照(first is second),确保重试不会因上下文变化而产生不一致。
4.2 摘要后处理 _post_process_abstract
LLM 原始输出不能直接入文,需经 _post_process_abstract 清洗:
- 空内容兜底:
content is None or content == ""时返回ArticlePart.get_not_found_prompt("abstract", language)(如中文"未能从生成内容中提取到摘要"); - 清理引用标记:
sanitize_citation_markers剥除不适用于摘要/结论等非正文部位的引用标注(见 report_utils.py 的注释"Use at citation-stripping points (abstract, conclusion, chart labels)"); - 修正加粗公式:
_convert_bold_formula_to_inline_math把误用**..**包裹的公式转为行内$..$; - 剥除语言前缀:中文输出若以"摘要"开头(长度 ≥ 2)则剥掉前缀与后续的冒号/破折号/空格;英文输出若以小写
abstract开头(长度 ≥ 8)同样剥除,避免"摘要摘要"式重复标题; - 补齐语言标题:最终确保内容以
# 摘要或# Abstract标题开头(若 LLM 未输出则补上)。
4.3 加粗公式兜底转换的实现细节
markdown_utils.py 中的 _convert_bold_formula_to_inline_math 是"提示词规范 + 代码兜底"双保险的典型样本。它只对高置信度公式特征做转换,避免误伤普通加粗文本(百分比、关键词、数据对比):
- 含
=的文本需同时含数学符号(_ ^ \ · × √、希腊字母 α-ω/Α-Ω,或ln|log|sqrt|sin|cos|tan|exp)才判定为公式; - 含
^即判定为公式; - 匹配
\frac|\sum|\int|\sqrt等 LaTeX 命令、数学函数调用、√加字母数字等特征。
该函数的存在印证了 system.md 中"禁止用加粗包裹公式"规则的现实必要性:提示词约束无法 100% 保证模型行为,运行时后处理是不可或缺的兜底层。
五、测试与验证全景
与摘要 Prompt 相关的验证分布在三个层面,可分别作为回归测试的切入点:
| 验证目标 | 测试文件 | 关键断言 |
|---|---|---|
| 模板变量契约 | test_deepresearch_prompt_contracts.py | user 模板变量 == 契约声明的 required ∪ optional;system 模板零变量 |
| 摘要生成调用链 | test_general_report.py | generate_abstract 以 report_abstract_markdown 调用;重试复用消息快照;紧凑上下文字段按 target 裁剪;空上下文回退完整正文 |
| 报告工具集成 | test_tools_in_report.py | 报告生成工具注册表包含 report_abstract_markdown 条目(第 52、79 行) |
此外,test_professional_isolation.py 与 test_research_intent_contract.py 也引用了该 Prompt 名,说明摘要模板与"专业版报告 / Brief 隔离""研究意图契约"等模块存在交叉约束,修改模板时需关注这些关联测试。
六、二次开发与调优指南
6.1 如何调整摘要模板
模板文件位置:deepsearch/openjiuwen_deepsearch/algorithm/prompts/report_abstract_markdown/。修改要点:
- 改 system.md:需保证不含任何 Jinja 变量(含 include 递归检查),否则
test_prompt_contract与渲染器的_assert_static_template_tree都会拒绝; - 改 user.md:增删变量名必须同步更新 test_deepresearch_prompt_contracts.py 的
_PROMPT_VARIABLES与_OPTIONAL_VARIABLES,否则契约测试失败; - 新增可选约束(如新的受众维度)应沿用
{% if %}条件渲染模式,保证老调用方不传该字段时渲染结果向后兼容。
6.2 如何排查摘要问题
- 摘要为空:检查
_post_process_abstract兜底文案是否被触发,以及generate_abstract传入的上下文是否为空(_build_reporter_compact_context在没有任何Chapter前缀段落时返回""); - 公式渲染错乱:检查 LLM 输出是否违反 system.md 的公式规范(块级
$$、未闭合分隔符、加粗公式),_convert_bold_formula_to_inline_math仅兜底高置信度场景,规范遵守仍需提示词约束; - 风格漂移:user.md 的
tone块明确要求与子报告保持风格一致,若出现风格不一致,检查调用方是否传入tone且与子报告阶段的取值相同; - 引入外部事实:检查是否遵守接地边界(只使用输入中的 Summary / Key findings),这是防幻觉的第一道闸门。
6.3 运行相关测试
推荐命令(在仓库根目录执行):
uv run pytest tests/algorithm/prompts/test_deepresearch_prompt_contracts.py -k "report_abstract_markdown"
uv run pytest tests/report/test_general_report.py
uv run pytest tests/report/test_tools_in_report.py
更完整的报告模块回归可参考 report-generation.md 中的说明(如 uv run pytest tests/report)。
七、小结
report_abstract_markdown 这对提示词模板虽短,却浓缩了 openJiuwen DeepSearch 报告生成的关键设计:接地边界防幻觉、单段落强格式约束、可选受众/语气注入、行内数学公式规范;而在模板之外,report.py 的并发编排、report_parts.py 的紧凑上下文构建与重试机制、markdown_utils.py 的公式兜底转换,共同构成了"提示词规范 + 代码兜底"的工程化闭环。理解这一闭环,既能为摘要质量调优提供方向,也能为新增报告部件(如 executive summary、key takeaways)复用同一条流水线提供现成范式。