DeerFlow保姆级教学：DeerFlow中自定义报告Markdown模板语法详解

DeerFlow保姆级教学：DeerFlow中自定义报告Markdown模板语法详解

1. DeerFlow是什么？先搞清楚它能为你做什么

DeerFlow不是另一个需要你反复调参、写配置文件的AI工具。它更像一位随时待命的研究搭档——当你想搞懂某个技术趋势、分析一个新兴市场，或者快速梳理某项医疗AI的最新进展时，它能立刻行动起来：自动搜索权威资料、运行代码验证数据、整理逻辑脉络，最后交给你一份结构清晰、内容扎实的报告，甚至还能把这份报告变成一段自然流畅的播客音频。

它不卖概念，只解决实际问题。比如你想知道“2024年开源大模型推理框架的演进路径”，DeerFlow会自己去查Hugging Face更新日志、GitHub star增长曲线、主流论文实验对比，再把关键结论组织成带图表说明的文字；如果你输入“用Python分析过去30天比特币价格与Reddit情绪的相关性”，它会直接调用API拉取数据、执行统计分析、生成可视化图，并把过程和结果一并写进报告里。整个过程你只需要提出问题，剩下的交给它。

这背后不是黑箱魔法，而是一套可观察、可干预、可定制的工作流。其中最关键的一环，就是报告生成阶段——它最终交到你手里的那份Markdown文档，其格式、结构、重点呈现方式，完全由你定义。而掌握这套自定义模板的语法，就是真正把DeerFlow从“好用”变成“专属”的第一步。

2. 为什么非得学这个模板语法？因为默认报告只是起点

很多人第一次用DeerFlow，看到生成的报告就以为“已经完成了”。但其实，那份默认报告只是系统根据通用逻辑拼出来的初稿。它可能把所有搜索到的信息平铺直叙地堆在一起，关键结论被埋在段落中间；可能图表编号混乱，导致你在引用时反复翻页；也可能缺少你团队内部约定的章节结构，比如必须包含“风险提示”或“落地建议”模块。

而DeerFlow的报告模板系统，正是为了解决这些问题而设计的。它不是让你写HTML或LaTeX那种复杂标记，而是基于你 already 熟悉的Markdown语法，叠加了一套轻量、直观的变量与控制逻辑。你可以：

• 把每次生成的报告自动加上公司Logo和保密等级水印
• 让“核心发现”部分永远以加粗+高亮块形式突出显示
• 控制图表按“图1-1、图1-2…”统一编号，并自动生成图注
• 在“数据来源”章节自动列出本次调用的所有搜索引擎和API端点
• 甚至让报告末尾根据分析主题，智能插入一句定制化总结（比如分析技术趋势时写“建议重点关注模型量化方向”，分析市场数据时写“短期波动受流动性影响显著”）

这些能力，全靠一套简洁的模板语法驱动。它不增加学习负担，反而把你从重复排版中彻底解放出来——你专注思考“要表达什么”，它负责精准呈现“怎么表达”。

3. 模板基础：从零开始写第一个自定义报告

DeerFlow的报告模板本质就是一个.md文件，放在项目指定目录下（通常是/root/workspace/templates/report/）。你不需要改任何后端代码，只需编辑这个文本文件，保存后下次生成报告就会自动生效。

3.1 模板文件位置与启用方式

首先确认你的DeerFlow服务已正常运行（可通过cat /root/workspace/bootstrap.log检查日志末尾是否有Report template loaded successfully字样）。然后进入模板目录：

cd /root/workspace/templates/report/ ls -la

你会看到类似default.md的文件。这就是当前生效的模板。要创建自己的模板，只需复制一份并重命名，例如：

cp default.md my_research_template.md

接着，在DeerFlow Web UI的设置页面（通常在右上角齿轮图标 → “Report Settings”）中，将模板名称改为my_research_template.md，点击保存。下次生成报告时，系统就会加载你修改后的版本。

3.2 最小可用模板长什么样？

打开my_research_template.md，删掉所有内容，填入以下三行：

# {{ title }} > **研究主题**：{{ query }} {{ content }}

这就是一个合法的DeerFlow模板。其中：

• {{ title }}是系统自动生成的报告标题，比如“2024年RAG技术演进深度分析”
• {{ query }}是你输入的原始问题，原样保留
• {{ content }}是整个报告的主体内容，包含所有章节、图表、代码块等

保存后，随便提一个问题（比如“LangChain和LlamaIndex的核心区别”），生成报告。你会发现标题变成了你问题的精炼版，引言区块准确显示了你的原始提问，正文则完整保留了所有分析内容——但此时它还是默认样式。接下来，我们让它真正“长”出你的风格。

4. 核心语法详解：变量、条件与循环，三招搞定定制化

DeerFlow模板语法只有三类基本元素：变量（{{ }}）、条件判断（{% if %}）、循环（{% for %}）。没有函数、没有嵌套复杂逻辑，全部围绕“如何把已有信息组织得更好”展开。

4.1 变量：提取关键信息，让报告自带上下文

除了前面提到的title和query，DeerFlow预置了十余个常用变量，它们都来自真实运行时的数据流：

用法很简单：在任意位置插入{{ 变量名 }}，它就会被替换成对应值。比如在报告末尾加一段说明：

--- **报告生成于** {{ date }}，全程耗时 {{ duration }} 秒，共参考 {{ sources_count }} 个权威来源，使用 {{ search_engines | join: ", " }} 进行信息检索。

注意这里用了| join: ", "这个过滤器——它能把列表["Tavily", "Brave Search"]转成字符串"Tavily, Brave Search"。DeerFlow内置了join、upper、truncate:50（截取前50字符）等实用过滤器，无需额外学习，看名字就能懂。

4.2 条件判断：让报告“懂分寸”，该显则显，该隐则隐

不是所有内容都适合出现在每份报告里。比如，当你的问题不涉及数据计算时，就不该出现“代码执行”章节；当搜索结果非常丰富时，才值得单独列出“关键信息源”清单。

用{% if %}就能实现这种智能控制：

{% if code_executions > 0 %} ## 数据分析过程 以下为本次研究中执行的关键代码及输出结果： {% for code_block in code_blocks %} ### 代码片段 {{ forloop.index }} ```python {{ code_block.code }}

执行结果：

{{ code_block.output }}

{% endfor %} {% endif %}

这段模板的意思是：“只有当`code_executions`大于0时，才渲染‘数据分析过程’这一整节；并且对每个代码块，按顺序编号并展示代码与输出”。`forloop.index`是循环内置变量，表示当前是第几个元素（从1开始计数），比手动写1、2、3更可靠。 再举个实用例子：给不同敏感度的问题自动添加声明： ```markdown {% if "医疗" in query or "药物" in query %} > **免责声明**：本报告内容基于公开信息整理，不构成任何医疗建议。具体诊疗请务必咨询专业医师。 {% endif %}

只要你的提问里包含“医疗”或“药物”，这段声明就会自动出现。逻辑清晰，维护简单。

4.3 循环：批量处理图表、引用、步骤，告别重复劳动

DeerFlow在生成报告时，会把所有图表、引用条目、研究步骤都组织成列表。通过{% for %}循环，你可以一次性处理全部，而不是为每张图单独写一段。

比如，自动为所有图表生成带编号的图注：

{% for figure in figures %} ### 图 {{ forloop.index }}：{{ figure.caption }} ![{{ figure.caption }}]({{ figure.url }}) *来源：{{ figure.source }} | 生成时间：{{ figure.generated_at }}* {% endfor %}

figures是一个预置列表，每个元素包含caption（图注文字）、url（图片地址）、source（来源）、generated_at（生成时间）等字段。循环会遍历所有图表，按顺序渲染——你完全不用关心这次生成了几张图，模板自动适配。

同理，引用文献也可以这样处理：

## 参考文献 {% for source in sources %} - [{{ source.title }}]({{ source.url }}) — {{ source.site_name }}（{{ source.published_date | default: "未知日期" }}） {% endfor %}

| default: "未知日期"是另一个实用过滤器：当published_date为空时，显示“未知日期”而不是一片空白。这种细节，让报告看起来更专业、更可靠。

5. 实战案例：打造一份“技术决策支持报告”模板

现在，我们把前面学的语法组合起来，做一个真正能用在工作中的模板。假设你是技术团队负责人，需要定期评估新技术是否值得引入。你希望每份报告都包含：明确的采纳建议、关键指标对比、风险提示、以及可执行的下一步。

5.1 模板结构设计

我们按逻辑顺序组织章节：

1. 执行摘要（强制显示，含明确建议）
2. 核心指标对比（仅当有对比数据时显示）
3. 优势分析（用图标+短句罗列）
4. 风险与限制（带分级标识）
5. 下一步行动项（带复选框，方便后续跟踪）

5.2 完整模板代码

将以下内容保存为tech_decision_template.md：

# {{ title }} > **执行摘要** > {% if decision_recommendation == "adopt" %} > **建议采纳**：综合评估，该技术成熟度高、生态完善，推荐在Q3试点落地。 > {% elif decision_recommendation == "caution" %} > **谨慎观察**：存在明显兼容性风险，建议先进行小范围PoC验证。 > {% else %} > **暂不推荐**：当前版本稳定性不足，等待v2.0发布后再评估。 > {% endif %} --- ## 核心指标对比 {% if comparison_table %} | 维度 | {{ title }} | 行业基准 | 差距 | |------|-------------|----------|------| {% for row in comparison_table %} | {{ row.dimension }} | {{ row.deerflow_value }} | {{ row.benchmark }} | {{ row.gap }} | {% endfor %} {% endif %} ## 优势分析 {% for strength in strengths %} - {{ strength.icon }} **{{ strength.title }}**：{{ strength.description }} {% endfor %} ## 风险与限制 {% for risk in risks %} - {% if risk.severity == "high" %}🔴{% elif risk.severity == "medium" %}🟠{% else %}🟢{% endif %} **{{ risk.title }}**：{{ risk.description }} *应对建议*：{{ risk.mitigation }} {% endfor %} ## ▶ 下一步行动项 {% for action in actions %} - [ ] {{ action.description }}（负责人：{{ action.owner }}，截止：{{ action.due_date }}） {% endfor %}

5.3 如何让模板“活”起来？

这个模板依赖几个自定义变量：decision_recommendation、comparison_table、strengths、risks、actions。它们不是DeerFlow默认提供的，而是由你通过DeerFlow的“研究规划器”（Planner）模块注入的。

具体操作：在Web UI提问后，进入“高级设置” → “自定义报告参数”，填入JSON格式的参数：

{ "decision_recommendation": "caution", "comparison_table": [ {"dimension": "社区活跃度", "deerflow_value": "GitHub Star 12.4k", "benchmark": "同类平均 8.1k", "gap": "+53%"}, {"dimension": "文档完整性", "deerflow_value": "覆盖92% API", "benchmark": "行业标准 85%", "gap": "+7%"} ], "strengths": [ {"icon": "⚡", "title": "启动速度极快", "description": "冷启动<200ms，远超竞品平均500ms"}, {"icon": "🔌", "title": "插件生态丰富", "description": "官方认证插件超200个，覆盖主流云平台"} ], "risks": [ {"severity": "high", "title": "企业级权限管理缺失", "description": "当前仅支持RBAC基础模型，不支持细粒度策略", "mitigation": "计划Q4通过MCP集成火山引擎IAM"}, {"severity": "medium", "title": "中文文档覆盖率不足", "description": "API文档仅65%完成中文翻译", "mitigation": "已提交PR，预计2周内合并"} ], "actions": [ {"description": "安排与架构组同步技术方案", "owner": "张工", "due_date": "2025-03-25"}, {"description": "申请测试环境资源配额", "owner": "运维组", "due_date": "2025-03-28"} ] }

保存后生成报告，你会得到一份结构严谨、重点突出、可直接用于技术评审会议的决策支持材料。所有内容都源于你的真实判断，DeerFlow只是把它优雅地呈现出来。

6. 常见问题与避坑指南：少走弯路，一次配对

即使语法简单，新手在实操中也常遇到几个典型问题。以下是高频场景的解决方案：

6.1 模板修改后不生效？检查这三个地方

1. 文件路径是否正确：确保模板放在/root/workspace/templates/report/下，且文件名与UI设置中填写的完全一致（包括大小写和扩展名）
2. 服务是否重启：修改模板后，DeerFlow不会自动热重载。执行pkill -f "deeflow-server"杀掉进程，再运行deeflow-server重新启动
3. 日志是否有报错：重启后检查/root/workspace/bootstrap.log，搜索template关键字。如果看到Jinja2 TemplateSyntaxError，说明语法有误（比如{% if %}没闭合）

6.2 变量显示为空？可能是数据未生成或名称错误

DeerFlow的变量分两类：

• 系统变量（如title,date）：始终存在，名称固定
• 流程变量（如code_blocks,figures）：仅当对应环节被执行时才生成

如果你在模板中写了{{ code_blocks }}但报告里显示空，大概率是因为本次研究没触发代码执行。此时应改用条件判断包裹：{% if code_blocks %}...{% endif %}。另外，变量名区分大小写，sources和Sources是两个不同变量。

6.3 中文乱码或特殊符号显示异常？

DeerFlow模板文件必须保存为UTF-8无BOM格式。用VS Code打开模板文件，右下角查看编码，如果不是UTF-8，点击切换并选择“Save with Encoding” → “UTF-8”。Linux下也可用命令批量转换：

iconv -f GBK -t UTF-8 my_template.md -o my_template_utf8.md

6.4 想加CSS样式或JavaScript？不建议，但有替代方案

DeerFlow的Markdown渲染器不支持内联HTML或JS，强行添加会被过滤。但你可以通过以下方式达到类似效果：

• 用Emoji代替图标：、、 等Unicode符号天然支持，且语义清晰
• 用引用块模拟高亮：> **关键结论**：xxx比<div class="highlight">更简洁可靠
• 用表格控制布局：复杂排版尽量用Markdown表格实现，而非CSS

记住原则：模板的目标是内容组织，不是视觉设计。最终报告导出为PDF或HTML时，样式由统一的主题CSS控制，你只需专注信息结构。

7. 总结：从模板使用者，变成报告架构师

学到这里，你已经掌握了DeerFlow报告模板的核心能力：用最熟悉的Markdown语法，驱动一个智能、灵活、可复用的内容生成系统。你不再被动接受系统给的“标准答案”，而是能主动定义：

• 信息优先级：哪些内容必须前置，哪些可以折叠
• 表达颗粒度：是展示原始代码，还是只呈现结论摘要
• 协作友好性：自动添加负责人、截止时间、状态标记，让报告成为项目推进的载体

更重要的是，这套能力是可迁移的。今天你为技术评估定制模板，明天就能为市场分析、竞品调研、学术综述快速复用——只需调整变量和逻辑分支，无需重学一套新语言。

真正的AI生产力，不在于它能多快生成内容，而在于它能否理解你的工作流，并成为你思维的延伸。DeerFlow的模板系统，正是这条延伸线上的关键一环。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。