1. 背景与目标

• 背景
  需求文档是软件开发的核心输入，但人工评估需求质量存在效率低、标准不一致等问题。
  飞书云文档作为团队协作工具，可结合自动化工具实现质量评估。
  Dify 作为低代码/自动化平台，需与飞书云文档集成，提升需求管理效率。
• 目标
  实现 Dify 读取本地需求文档内容。
  通过预定义规则，使用 AI 模型对需求文档进行质量评分（如完整性、清晰度、可测试性等）。
  将评估结果生成结构化报告反馈至飞书文档。

2. 系统架构与流程

2.1 整体架构图

+-------------------+       +----------------+       +---------------+
|    本地文档        |       | Dify 平台       |       | 评估结果输出    |
| - 需求文档存储      |<----->| - 数据接入模块   |<----->| - 可视化报告    |
|                   |       | - 质量评估引擎   |       |               |
+-------------------+       +----------------+       +---------------+

2.2 核心流程

• 文档读取：用户上传需求文档至Dify。
• 预处理：清洗文档格式（如 Markdown/富文本转换）、提取关键字段（需求描述、验收标准等）。
• 质量评估：
  • 规则引擎：基于预设规则。
  • AI 模型：使用 LLM 模型分析需求描述的清晰度、歧义性。
• 结果反馈：将评估结果回写至飞书文档或推送至指定群组。

2.3 dify工作流概览

3. 实现细节

3.1 文档提取

创建一个空白应用，添加开始节点，在开始节点中定义一个变量来存放上传的需求文档

使用文档提取器读取该需求文档内容，输出为text。

3.2 需求评估

添加LLM节点，编辑系统提示词和用户提示词，制定需求质量评估规则进行需求评估，输出为text。
这里需注意，system级别的提示词和user级别的提示词的区别。在上个节点中的输出只能在user级别的提示词中被处理，如果没有user提示词，而选择用system级别的提示词处理该变量，会产生报错。

此节点作为该应用的核心部分，承担了需求质量评估的作用，我们在这个节点定义需求质量评估规则。提示词工程的精细度决定了需求评估的准确性。

3.3 参数提取

后面的飞书云文档插件，要求输入变量作为文档标题和文档内容。而在需求评估节点，并没有这些参数内容输出，因此我们要从需求评估LLM节点的输出text中，提取出这两个参数。
添加参数提取节点，用于从需求评估节点的结果中提取关键参数作为文档标题和文档内容。

3.4 创建飞书云文档

创建飞书云文档，将结构化输出写入。此处需要设置文档标题为参数提取节点中的文档标题参数，文档内容设置为参数提取节点中的文档内容参数。另外还需要填写文档所在文件夹的Token。

4. 难点总结

4.1 提示词编写

下面提供system和user两块提示词的内容，存在优化空间。

system提示词，定义角色和能力，以及目标

# 专家角色设定：QA需求质量评估专家## 身份定义：
你是一名资深软件需求质量评估专家，精通IEEE 830、ISO/IEC 25030等标准，擅长从技术可行性、业务价值、风险管理多角度评估需求质量，并给出评分依据和改进建议。## 核心技能：
-需求分析方法（用例分析、用户故事拆分）
-非功能需求（性能、安全、可维护性）识别
-矛盾点与模糊术语检测
-风险评估与优先级划分（MoSCoW法）
-需求可测试性（定义验收标准）# 需求质量评估维度
请按以下维度分析需求文档，针对每个问题提供改进建议：
评估维度权重评分标准（1-5分）得分
-评估维度：命名规范性
权重：10%
评估标准：
1分：含技术术语（如"开发/接口"）
3分：描述功能但无价值
5分："动词+业务价值"（如"提升XX转化率"）
附加项：需求名称是否从开发者角度来描述，是则在此维度得分基础上减0.5分
-评估维度：用户价值明确
权重：25%
1分：无用户故事
3分：有用户但无痛点
5分：清晰用户故事+数据支撑（如"减少30%客诉"）
-评估维度：验收标准量化
权重：20%
1分：仅描述"功能可用"
3分：部分量化指标
5分：明确成功指标（如"响应时间≤2s/错误率＜0.1%"）
-评估维度：场景覆盖度
权重：15%
1分：仅主流程
3分：主流程+部分异常
5分：覆盖网络/并发/兼容性等全场景
附加项：
是否存在歧义词（例如‘支持多种格式’未明确具体格式）？是则在此维度得分基础上减0.2分
高层需求是否已逐级拆解到子功能？否则在此维度得分基础上减0.2分
是否存在未定义的业务场景或用户角色？是则在此维度得分基础上减0.1分
是否遗漏系统边界外的依赖项（如第三方接口）？是则在此维度得分基础上减0.1分
-评估维度：技术合理性
权重：10%
1分：捆绑具体技术方案（如"必须用Redis"）
3分：有技术风险未评估
5分：方案中立+风险评估完备
附加项：
是否符合GDPR/CCPA等数据法规？否则在此维度得分基础上减0.2分
是否包含无障碍访问设计（WCAG标准）？否则在此维度得分基础上减0.2分
-评估维度：优先级合理
权重：10%
1分：与OKR无关
3分：关联次要目标
5分：直接支撑KR且ROI清晰
-评估维度：可测试性
权重：10%
1分：无测试方案
3分：需自研工具
5分：现有工具全覆盖+数据可获取# 权重计算
总得分 = Σ(各维度得分 × 权重)
优秀：≥4.5分（总分）
合格：3.0-4.4分
需重构：<3.0分# 生成结构化报告
创建飞书文档并根据以下模版生成报告
# 需求质量评估报告_需求ID
需求名称：
## 1. 质量评估
以表格形式展现，展示评估维度、权重、分数、评分依据四列，最后一行展示总质量分。
## 2. 关键问题  
- [优先级:高] 问题描述 + 违反的质量属性  
- [优先级:中] ...  
## 3. 改进建议  
- 对模糊需求"XXX"的澄清方案：建议增加边界条件定义（示例：用户并发数≥1000时...）  
## 4. 风险评估  
- 技术风险：需引入未经验证的AI框架，建议增加POC阶段 

user提示词，用户需要做的应用做的事情

# 阅读以下需求文档内容{{#1743404017066.text#}}# 进行需求质量评估# 输出结果

4.2 关联飞书云文档

在创建飞书云文档节点中，我们需要调用飞书云文档插件下的工具。
这一步的前提条件是dify需要在插件市场安装飞书云文档插件。

4.2.1 安装飞书云文档插件并关联到飞书自建应用

标签下拉选择社交类型，搜索feishu，安装飞书云文档插件。

安装完成之后，需要对飞书云文档进行授权，输入app ID和app Secret。这两项值应该从飞书开发者后台获取。
进入飞书开放平台的开发者后台（可以切换成飞书个人用户账号登录），创建企业自建应用。

进入凭证与基础信息页面，复制app ID和app Secret，输入到dify的飞书云文档插件中去进行授权，授权成功，dify通过飞书云文档插件能关联到该飞书自建应用。

4.2.2 飞书自建应用关联到飞书云文档

我们通过为飞书自建应用创建机器人能力，再操作该机器人加入群组，给目标飞书云文档文件夹添加该群组操作权限来使飞书自建应用能操作飞书云文档下的文件夹（因为我们目标是要在该文件夹下创建编辑云文档）。
下面是具体实施步骤。
进入应用详情页面，添加应用能力为机器人。

进入权限管理，添加云文档的应用身份权限的所有权限，使该应用具备操作云文档的权限。

进入版本管理与发布，创建版本并发布。

飞书创建群组，并在群组设置中添加该应用机器人。

添加完成之后，进入云盘的目标文件夹，为该文件夹添加协作者为该群组，并且给可管理权限即可。

4.2.3 在dify的飞书云文档节点输入文件夹token

通过以上操作，我们已经让dify的飞书云文档节点具备了操作飞书云文档文件夹的能力，但我们还需要告诉该节点，我需要将文件创建到哪个飞书云文档文件夹下。
配置完成后，需要回到dify的飞书云文档节点输入文件夹token。如何获取文件夹token？最简单的方法，可以在网页端打开该飞书文件夹，通过url链接获取到文件夹token，将该token输入到节点中。

其他获取方式请见飞书开发者手册。
将以上token输入到dify的飞书云文档节点即可。

5. 改进方案

5.1 工作流优化

经测试，上文工作流为串行运行，存在耗时长的弊端。经测试，分析1个需求文档的各节点耗时如下：

5.1.1 优化前后对比

因此优化工作流节点，将参数提取器与需求评估LLM节点并行运行。经测试，分析1个需求文档的各节点耗时如下：

5.1.2 优化细节

• 参数提取器获取飞书云文档的内容，从中提取需求ID，作为文档标题的重要元素。
• 需求评估获取飞书云文档的内容，输出text(String)作为文档内容。
  

5.2 配置环境

在创建和读取飞书云文档时，需要输入token，此内容可以保存在环境变量中。

5.3 读取飞书云文档需求

将本地文件上传和提取文档内容节点更换为获取飞书云文档节点，输入为文档的url，文档返回格式为text。
文档的url为开始节点的变量传入。该变量需定义为文本类型。