Dify 1.17 实操：工作区 Skill 管理、循环内人工介入与 LLM 变量复用

# 查看当前版本（页面右上角「关于」或 API 均可）
curl -s http://localhost/console/api/version

# 自托管：升级前备份数据库与数据卷
docker exec -t docker-db-1 pg_dump -U postgres -d dify > dify_backup_$(date +%Y%m%d).sql
docker run --rm -v docker_volumes:/data -v $(pwd):/backup alpine \
  tar czf /backup/dify_volumes_$(date +%Y%m%d).tgz /data

1.17.0 之前，Agent 的 shell 与代码执行跑在本地沙箱里；现在可以选择 E2B 云沙箱作为后端。自托管环境这样切换：

# .env 中指定执行后端（默认本地，改为 E2B）
DIFY_AGENT_RUNTIME_BACKEND=e2b
E2B_API_KEY=你的-E2B-API-KEY

# 官方随版本附带 E2B 栈的 compose 文件
docker compose -f docker-compose.e2b.yaml up -d

三条配套机制值得知道：E2B 流量带鉴权，不是裸连；E2B 模板随 Dify 发版自动同步，不用自己维护镜像；本地沙箱仍是默认值，你不改环境变量就一切照旧。

过去有个经典别扭：你在调试时装好的 Python 依赖、上传的参考文件、跑出来的中间状态，发布成应用之后不一定还在，换个会话就得重来。Home Snapshot 的逻辑是：当 Agent 构建被应用（发布）时，把沙箱 home 目录——已安装的包、准备好的文件、工作状态——整体拍成快照；此后每次运行这个已发布应用，都从快照还原文件系统。

构建（Build） → 拍快照：/home 下的包、文件、状态全部固化
发布（Publish）→ 快照与应用版本绑定
运行（Run）   → 从快照还原 home，再开始干活

Skill 是 1.17.0 里概念上最重要的新增：把「一段代码 + 一组工具定义」打包成可复用、可版本化的能力单元，放在工作区级统一管理，任何 Agent 都可以发现并调用它。入口在工作区设置里的 Skills 管理器，带列表页、构建面板与文件编辑器。

一个 Skill 的生命周期：
draft（草稿）  → 在构建面板写代码、挂工具定义
publish（发布）→ 版本号 +1，进入工作区可用列表
version（版本）→ 改动出新版本，旧版本仍可回溯

一个 Skill 的组成：
- 代码：能力逻辑（如「按模板生成周报」）
- 工具定义：声明它能调用哪些工具、入参出参是什么

实操建议：挑一个你已经在多个应用里复制粘贴过的能力（比如「把上传表格清洗成标准格式」），把它抽成你的工作区内 Skill。发布后到任意 Agent 的能力列表里确认它能被发现、被调用、给出正确版本号。

1.17.0 把人工介入表单（human-in-the-loop form）带进了 Loop 和 Iteration 节点内部：循环跑到某一步暂停，弹出表单等人确认或修改，确认后从断点续跑。官方说明它对 debug 与已安装应用都生效，且跨页面刷新保持暂停状态。

典型用法（批量线索清洗）：
Iteration 开始
  ├─ LLM 节点：判断线索质量，打分
  ├─ 条件分支：低分线索 → 人工介入表单
  │     表单字段：[丢弃 / 修正后继续] + 修改意见
  │     人选「修正」→ 分支回流，用修正值继续跑
  └─ 高分线索 → 直接入库
Iteration 结束

过去工作流里十几个 LLM 节点各自选模型、调参数，想统一把摘要模型换掉，得逐个节点点开改，漏一个就出现「口径漂移」。1.17.0 允许定义可复用的 LLM 环境变量——把供应商、模型、模式、参数打包成一个命名配置（比如 for_summarize、for_research），任何 LLM 节点直接引用。

# 概念示意（在工作区的 LLM 环境变量面板中定义）
for_summarize : 供应商=DeepSeek, 模型=deepseek-chat, 温度=0.3
for_research  : 供应商=Anthropic, 模型=claude-sonnet, 温度=0.7

# LLM 节点里不再逐项配置，引用变量名即可
摘要节点   → 使用 for_summarize
调研节点   → 使用 for_research

# .env 打开统一追踪（默认关闭，向后兼容）
OPS_TRACE_UNIFIED_ENABLED=true

# 适配器按你用的平台配置（首发支持 Phoenix 与 LangSmith）
# 具体变量名以所用版本的 .env.example 为准

打开后，工作流、聊天流、消息、节点、循环、迭代、嵌套工作流的父子 span 树会在核心层拼好一次，适配器只负责传输。GenAI 规范的 span 还会带出 LLM 首 token 延迟（TTFT）、Agent 的 ReAct 步骤、工具调用与失败的 LLM 节点——排查「哪一步慢、哪一步错」终于不用翻日志拼时间线了。