【Dify自动化实战】规划Dify资料报告工作流目标-平芜编程栈

云博士带小白：自然语言AI编程做A股选股产品

AI神经网络全谱系架构全景精讲

哈佛博后带你玩转深度学习实战

规划 Dify 资料报告工作流目标

课程归属：Dify 自动化实战｜第 1 节：规划 Dify 资料报告工作流目标

当资料需要被反复阅读、提炼要点并整理成统一报告时，单纯把文件交给大模型提问，往往会遇到输入不统一、重要信息遗漏、结论找不到依据、输出格式不稳定等问题。本节先不急着拖拽节点，而是为贯穿课程的“资料报告助手”定义可实现、可验证的目标：明确谁提交什么资料、系统要完成哪些处理、结果长什么样，以及如何判断一次运行真正成功。后续的 Dify 节点设计都以这份目标契约为依据。

一、先定义要解决的具体问题

本课程的项目名称统一为“资料报告助手”。它面向需要阅读多份资料并产出主题报告的场景，例如项目调研、产品资料整理、课程资料汇总或内部文档初审。使用者上传一个或多个文件，再填写本次报告的主题；工作流解析资料、提取摘要和关键点、在适用时检索已整理的知识、保留来源片段，最后生成结构一致的 Markdown 报告。

这里要区分“自动生成一段文字”和“交付一份可检查的报告”。前者只关心模型有没有回答；后者还要关心输入是否完整、事实是否能回到来源、失败时有没有说明，以及下游能否稳定读取字段。因此，本项目把报告正文、结构化结果、来源证据和警告分开定义，而不是让所有信息混在一个长字符串中。

1.1 本节要交付的结果

本节的交付物不是已搭好的工作流，而是可以直接用于后续搭建与验收的目标说明，包含：

工作流类型与运行入口的选择；
输入变量及其业务含义；
结构化输出字段和字段类型；
主处理链路与异常分支；
正常用例、边界用例和通过标准。

Dify 官方将 Workflow 定位为适合单次任务的应用，并支持通过用户输入或触发器启动。资料报告通常由人提交资料、指定主题后按需运行，因此本课程选择Workflow + User Input 入口；定时触发和外部 API 定时归档留到后续章节处理。Dify Key Concepts

1.2 本节暂时不做什么

暂不纳入本节	原因	后续处理方向
安装或升级 Dify	环境部署是下一节的主要目标	第 2 节验证基础服务
配置模型供应商和密钥	需要先有可运行的 Dify 实例	第 3 节配置模型接口
OCR 扫描件识别	普通文档提取不能保证识别图片中的文字	第 11 节接入 OCR 服务
知识库和 Embedding	需要先明确资料结构和检索目标	第 12—16 节逐步实现
生成可下载 Word 文件	需要文件生成工具或外部服务，不是纯文本输出的天然能力	第 24 节补齐交付工具
定时执行与 API 归档	涉及发布后的调用和外部脚本	第 29—30 节处理

把边界写清楚，可以避免第一版工作流同时承担部署、OCR、知识检索、文件转换和自动发布等多个独立问题。先验收最核心的“资料进来，得到有依据的报告”，后续再增加能力。

二、用一张图确定工作流边界

图 1：资料报告助手的目标级流程

图 1 是目标流程，不是声称当前已经在 Dify 中配置完成的画布。它把节点开发前需要决定的事情先排清楚：先验证输入，再处理文件；来源证据与摘要一起保留；报告生成后还要检查，而不是看到 LLM 有输出就直接判成功。无法解析的资料不能默默当作“没有相关信息”，必须形成警告或失败结果。

三、确定输入契约：工作流需要用户提供什么

课程统一采用两个主输入：files和report_topic。files是 Dify 用户输入中的多文件类型，代表本次运行实际上传的文件；它不是本地路径字符串数组，也不是把dify_lab/data/input/目录名传给模型。report_topic是描述本次报告要回答什么问题的字符串。

表 1：输入字段设计

字段名	类型	必填	含义与校验目标
`files`	多文件输入	是	一份或多份本次上传的资料；至少包含一个有效文件
`report_topic`	String	是	报告主题或核心问题；去除首尾空白后不能是空字符串

Dify 官方文档说明，用户输入节点中的每个输入字段都会成为后续节点可引用的变量；变量在一次工作流运行开始时设定，后续节点通过变量选择器读取。Dify Quick Start 在配置界面中，文件字段的具体显示名称可能随版本或语言不同而变化，应选择语义上支持多文件上传的字段，并将变量名保持为files。

3.1 为什么不把文件路径当成输入

在本地项目中，dify_lab/data/input/是课程资料的归档目录，方便管理演示文件；但 Dify 运行时的文件输入是平台识别的上传对象。路径文本如data/input/a.pdf并不等于文件已经上传，也不保证工作流服务能读取到用户电脑上的路径。将“文件对象”与“文件路径”混为一谈，后续会出现模型拿到路径却拿不到正文的问题。

3.2 输入检查要早于模型调用

至少定义以下检查：

files不能为空，且每个文件都确实由本次运行上传。
文件类型应处于当前处理能力范围内；暂不支持的类型需要提示，而不是强行解析。
report_topic去除首尾空白后必须有内容。
多文件输入要记录每份文件的名称，后续摘要和来源不能把不同文件混成一份。
如果文件上传成功但解析结果为空，应区分“空文件、扫描件、格式不支持、解析失败”等可能原因；没有证据时不要猜测具体原因。

图 2：输入校验决策

图 2 的重点是把可在运行前判断的错误拦在最前面。缺文件或缺主题不需要调用模型；越早拦截，越容易给出清楚的错误信息，也能避免无效的后续处理。

四、定义输出契约：结果要能被人和程序同时使用

报告正文是给人阅读的，结构化字段则便于后续节点、API 调用方或归档脚本处理。课程将沿用以下固定字段名；本节先定义含义，不要求现在把所有字段都配置到画布中。

表 2：标准输出字段

字段名	类型	内容要求
`source_name`	String	当前结果主要对应的来源名称；多文件综合结果可使用明确的汇总标识，并在引用数组中逐项记录来源
`summary`	String	对材料核心内容的简洁概括，不添加材料未支持的事实
`key_points`	字符串数组	可独立理解的关键点，每条只表达一个主要信息
`source_refs`	对象数组	每项必须包含`source_name`、`locator`、`excerpt`三个字符串
`warnings`	字符串数组	记录读取失败、来源不足、内容冲突、部分资料未处理等情况；没有警告时为空数组
`report_markdown`	String	按报告结构组织的完整 Markdown 正文
`download_url`	String	本课程后续接入文件生成能力后填写下载地址；未生成文件时必须是空字符串

source_refs是可靠性设计的关键。source_name说明引用来自哪份资料；locator给出能够定位的页码、章节、段落或其他可用位置；excerpt保存支持该结论的短原文片段。具体定位能力取决于解析器是否能提供页码或段落信息，不能保证时就如实标记，而不是伪造精确页码。

例如，结构化输出的形状可以先按下列教学样例约定。它是字段契约示例，不是本节实际执行生成的结果：

{"source_name":"资料汇总","summary":"材料介绍了项目目标、主要方案与待验证事项。","key_points":["项目目标是整理多份资料并形成主题报告。","需对无法读取或缺少依据的信息给出提示。"],"source_refs":[{"source_name":"项目说明.pdf","locator":"第 2 页，项目目标段","excerpt":"形成统一的项目资料报告。"}],"warnings":[],"report_markdown":"# 资料报告\n\n## 摘要\n...","download_url":""}

需要注意：上述内容是示例值，不能作为模型已经正确提取出真实 PDF 内容的证据。download_url为空是有意的，因为当前目标阶段尚未接入 Word 文件生成服务。

五、报告应该长什么样

报告版式先固定下来，再在后续章节决定由哪些节点生成各部分。这样模型更容易遵循统一结构，测试时也有可比较的检查点。

表 3：报告正文模板契约

报告部分	目标	验收关注点
报告标题与主题	对齐`report_topic`	主题不能被改成无关内容
摘要	说明资料主要讲什么	不添加材料没有的结论
关键要点	按条列出核心信息	每条能回到资料依据
详细分析	根据主题组织相关内容	区分原文事实、归纳与待验证项
来源与引用	对主要结论给出处	引用字段齐全，不捏造位置或原文
警告与限制	显示未处理资料或证据不足	不把缺失信息包装成确定结论

这里的“统一”不代表所有报告都要有一样长的正文。不同主题可以改变详细分析部分，但摘要、要点、出处和警告这几个关键区域应保持可预期。对于材料没有提到的问题，应写明“资料未提供足够信息”，而不是让模型补齐看似合理的答案。

图 3：从上传文件到可追溯报告的数据关系

图 3 强调报告不是单靠主题提示词生成的。正文应同时受解析内容、结构化要点、来源片段和异常警告约束；这样即使某份文件没有被成功读取，系统也有地方说明这一限制。

六、把“完成”定义成验收条件

工作流最容易出现的误判，是模型返回了一段文字，运行看起来没有报错，于是就被认为成功。对资料报告助手来说，只有输出满足预先定义的条件，才算通过验收。

表 4：最小验收测试集

用例	输入	预期行为	通过判据
正常用例	1 份可读取的文本型 PDF + 非空主题	输出摘要、关键点、出处与 Markdown 报告	必需字段存在；主要结论有来源；无虚构页码
多文件用例	2 份主题相关资料 + 同一主题	合并归纳，同时保留每份资料的出处	不把来源混成一个文件；引用可区分来源
缺文件	`files`为空，主题有值	在解析或 LLM 处理前提示补交文件	有明确错误/提示，不生成伪报告
缺主题	有文件，`report_topic`为空白	提示填写主题	不进入报告生成主流程
解析异常	上传支持范围内但无法提取正文的文件	返回失败说明或警告	不静默忽略文件，警告描述可理解
证据不足	材料没有回答主题中的某个问题	明确说明材料未提供依据	不凭空补事实，`warnings`或正文体现限制

本节建议先准备一份可复制的教学资料和一份故意设置的边界输入。教学资料应当短小、内容明确，并且只包含用于演示的虚构项目说明，不放客户资料、真实合同或隐私信息。正常用例用于核对输出契约；缺文件或空主题用例用于核对校验设计。当前尚未部署和运行 Dify，因此以上是计划中的验收用例与预期判据，不是已实测通过的结果。

七、工作流怎样才算“可交付”

除了内容正确，目标还要考虑如何定位一次运行和如何向后续课程交接。Dify 的 Workflow 运行会提供运行标识与节点执行信息，可用来查看运行历史和排查节点问题；官方关键概念文档也说明了sys.workflow_run_id等系统变量的用途。Dify Key Concepts 因此，后续构建时应记录运行标识、检查失败节点，并在发布后对线上版本做一次端到端验证；不能仅根据编辑器中的草稿状态就认为已对外可用。

表 5：目标完成检查表

检查项	合格标准	不合格示例
输入定义	变量名、类型、必填条件已固定	用`file_path`字符串冒充上传文件
输出定义	字段名、类型与含义一致	有时把`key_points`输出成字符串，有时输出数组
可追溯性	重要结论能映射到来源片段	只给结论，没有来源信息
异常处理	缺资料、空主题和解析失败有反馈	失败时只返回一份空白报告
报告完整性	正文结构完整，警告与来源保留	只输出一段没有标题的文本
文件交付	只有生成服务实际返回地址后才填`download_url`	没生成文件却编造下载链接
发布验收	测试版通过后再发布，并复测线上版本	修改草稿后假定已自动更新线上应用

八、交付前的工作流草图与决策顺序

确定目标后，建议按以下顺序推进，而不是一开始就把所有节点堆到画布上：

这张图给出的是本课程的实施顺序。先冻结接口，可以减少后续重命名变量、改变数据类型或补写异常分支的返工；测试集也不必等流程做完才准备，因为边界条件会反过来影响输入校验和输出设计。

九、先约定项目资料如何摆放

本节还不需要编写外部脚本，但应先统一目录职责，避免后续把平台上传文件、本地测试资料和最终报告混在一起。建议课程项目按下表组织；这些目录是项目管理约定，不代表 Dify 会自动读取本地目录。

表 6：资料报告助手的目录约定

路径	用途	本节是否必须创建
`dify_lab/data/input/`	保存可重复使用的教学输入文件	建议创建
`dify_lab/scripts/`	后续放置调用 Dify API、定时归档等脚本	暂不需要
`dify_lab/services/`	后续放置 OCR 或文件生成等外部辅助服务代码	暂不需要
`dify_lab/output/`	归档后续运行生成的报告和结果	可先创建空目录
`.env.example`	记录所需环境变量的名称和说明，不放真实密钥	后续接 API 时补全

这样安排的价值是把“工作流定义”和“工作流周边的工程能力”分开。Dify 画布负责编排节点；本地脚本负责后续的 API 调用或定时任务；外部服务负责 OCR、Word 文件生成等需要独立能力的步骤。对于本节的目标规划，先明确边界即可。

十、本节最终确定的项目约定

在开始下一节之前，至少把以下约定记录到项目说明中：

应用类型：Dify Workflow，首期由 User Input 按需启动；定时触发属于后续扩展。
项目名：资料报告助手。
主输入：files（多文件上传类型）、report_topic（String）。
核心结果：source_name、summary、key_points、source_refs、warnings、report_markdown、download_url；字段含义按本文表 2 固定。
结果原则：不伪造来源；材料不足时明确报告限制；未生成文件时download_url为空字符串。
验收方式：至少执行正常用例、缺文件用例、缺主题用例和解析异常用例，并按表 4 记录结果。
安全边界：首轮只使用教学资料；上传前确认资料适合交由已配置的模型与服务处理，不把 API 密钥写进提示词或文档正文。