| name | dify-workflow-variable-check |
| description | Thoroughly checks and fixes variable reference issues in Dify workflow YAML files. Ensures every {{#conversation.XXX#}} used in prompts is declared in workflow.conversation_variables. Use when auditing Dify YAML, fixing "invalid variable" or "未设置键值" errors, or when the user asks to check variable problems, 检查变量问题, 会话变量, 无效变量, or Dify 变量. |
Dify 工作流变量检查与修复
对 Dify 导出的 workflow YAML 做彻底变量检查，找出未声明的会话变量并按规定格式补全，避免编排里出现「无效变量」/ 红叹号。
何时执行本 Skill
- 用户说：检查变量问题、彻底检查变量、Dify 变量、无效变量、未设置键值、会话变量
- 导入/编辑 Dify YAML 后出现「invalid variable」或红叹号
- 需要批量审计多个 workflow 的变量引用是否合规
一、彻底检查变量（检查清单）
按下面顺序执行，不跳过。
1. 提取「已声明的会话变量名」
在目标 YAML 中，workflow.conversation_variables 下列出的 name 即为已声明变量。
- 方式 A（推荐）：用 grep 搜
conversation_variables 所在块，逐条看 name: 的值。
- 方式 B：运行本 Skill 自带的检查脚本（若存在）：
python .cursor/skills/dify-workflow-variable-check/scripts/check_variables.py <path-to-workflow.yml>
得到集合 Declared = { x, suketextbookcontents, keycompetencies, textbookcontents, content, hexinsuyang, TextBook_Data, round_text, ... }（以实际为准）。
2. 提取「被引用的 conversation 变量」
在整个 YAML 中搜索所有对会话变量的引用：
- 模式：
{{#conversation.<变量名>#}}
- 注意：变量名大小写敏感（如
TextBook_Data 与 textbook_data 不同）。
命令示例（在项目根下）：
rg -o "\{\{#conversation\.([^#]+)#\}\}" -- "path/to/workflow.yml"
或直接搜索字符串：
#conversation.
从匹配结果中收集所有出现的 变量名，得到集合 Referenced。
3. 对比结果
- 未声明却被引用：
Referenced - Declared → 这些会在 Dify 里显示为无效变量，必须修复。
- 已声明但未引用：
Declared - Referenced → 可选清理，不影响「无效变量」报错。
4. 其他引用（无需在 conversation_variables 声明）
以下不要加入 conversation_variables：
{{#sys.query#}}、{{#sys.*#}}：系统变量，由 Dify 提供。{{#<nodeId>.<output_key>#}}：节点输出引用（如 {{#1747860591336.file#}}），由图上节点提供。
检查时只关注 conversation. 的引用是否都在 Declared 中。
5. 赋值节点（assigner）写入的变量
若某变量是由 变量赋值 / assigner 节点「写入」到会话的（如 variable_selector: [conversation, TextBook_Data]），则：
- 该变量也必须出现在
conversation_variables 中；
- 否则在 LLM 等节点的提示词里引用
{{#conversation.TextBook_Data#}} 仍会报无效。
因此：凡在提示词或赋值目标里出现的 conversation.XXX，都必须在 conversation_variables 中有同名声明。
二、修复：补全缺失的 conversation_variables
对「未声明却被引用」的每个变量名，在 workflow.conversation_variables 中追加一条。插入位置：最后一个已有变量条目的 value_type: string（或 value_type: integer 等）之后、environment_variables: 之前。
单条模板（字符串）
- description: '简短说明该变量用途（由哪类节点写入、供谁使用）'
id: <UUID>
name: <变量名>
selector:
- conversation
- <变量名>
value: ''
value_type: string
- name 与 selector 第二项 必须与引用处完全一致（含大小写）。
- id：可用新 UUID（如
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 格式），或从现有条目复制格式。
- 若为数字型（如轮次 x），则
value_type: integer，value: 0。
示例：补 TextBook_Data 与 round_text
- description: '由变量赋值节点写入的课时内容（Excel 查询结果），供教学设计修改时参考'
id: a1b2c3d4-5e6f-4a5b-8c9d-0e1f2a3b4c5d
name: TextBook_Data
selector:
- conversation
- TextBook_Data
value: ''
value_type: string
- description: '由变量赋值节点写入的上一轮完整教案文本，供多轮修改时作为基础'
id: b2c3d4e5-6f7a-5b6c-9d0e-1f2a3b4c5d6e
name: round_text
selector:
- conversation
- round_text
value: ''
value_type: string
插入后保存 YAML，重新导入 Dify 或刷新编排，无效变量应消失。
三、输出报告格式（可选）
检查完成后，可用如下格式汇总给用户：
## Dify 变量检查结果
- **已声明会话变量**：x, suketextbookcontents, keycompetencies, ...
- **引用到的 conversation 变量**：keycompetencies, textbookcontents, content, TextBook_Data, round_text, ...
- **未声明却被引用（需修复）**：TextBook_Data, round_text
- **已修复**：已在 conversation_variables 中补充上述项。
四、为何之前会漏掉
- 只看了节点连线/命名，没有系统对比「所有 conversation 引用」与「conversation_variables 声明」。
- 引用写在长段 prompt 的
text: 里，不专门搜 #conversation. 容易漏。
- Dify 仅对「已声明」的会话变量在 UI 上标为有效；赋值节点可写任意 key，但未声明的 key 在提示词里引用仍会报无效。
按本 Skill 的清单逐项做即可彻底检查并修复此类变量问题。
