openJiuwen DeepSearch 报告摘要生成提示词模板深度解析:从 Jinja 模板到流水线落地

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

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)
)

值得注意的两点:

  1. 优先使用紧凑上下文:若 _build_reporter_compact_context("abstract") 能构建出结构化的章节摘要(详见 1.3),则传入该紧凑上下文;否则回退到"完整拼接正文"(sub_reports_content)。测试用例 test_general_report.py 专门验证了"紧凑上下文为空时回退完整正文"这一分支。
  2. 并发执行:摘要与结论通过 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 Summary and Key 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}}**

三个关键设计点:

  1. audience_role 与 tone 为可选变量:只有二者至少提供一个时,才渲染 Report Detail Constraints 小节。audience_role 要求"以该受众决策所需结论开头,避免教科书式背景铺陈";tone 要求按英文枚举(如 objective、formal、analytical)理解为写作立场,且必须与子报告保持风格一致、不得中途换风格。
  2. main_content 为必填主体变量:承载紧凑章节上下文或完整拼接正文(由 1.2 节的编排逻辑决定)。
  3. 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 清洗:

  1. 空内容兜底:content is None or content == "" 时返回 ArticlePart.get_not_found_prompt("abstract", language)(如中文"未能从生成内容中提取到摘要");
  2. 清理引用标记:sanitize_citation_markers 剥除不适用于摘要/结论等非正文部位的引用标注(见 report_utils.py 的注释"Use at citation-stripping points (abstract, conclusion, chart labels)");
  3. 修正加粗公式:_convert_bold_formula_to_inline_math 把误用 **..** 包裹的公式转为行内 $..$;
  4. 剥除语言前缀:中文输出若以"摘要"开头(长度 ≥ 2)则剥掉前缀与后续的冒号/破折号/空格;英文输出若以小写 abstract 开头(长度 ≥ 8)同样剥除,避免"摘要摘要"式重复标题;
  5. 补齐语言标题:最终确保内容以 # 摘要 或 # 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)复用同一条流水线提供现成范式。

登录后查看全文
deepsearch