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為開始節點的變量傳入。該變量需定義為文本類型。