infra-dify-ops

infra-dify-ops

配套 CLI difyctl（difyresctl 旧包与 shim 已下线）。

用途

用于在 组织内部集群 场景中做 Dify 平台的使用层资源运维与 workflow DSL 创作，而不是处理部署层。它作为 AI 平台基础设施治理的一部分纳入 infra-*，但不接管 Dify Compose、数据库或容器生命周期。

这个 Skill 主要覆盖：

• Dify app / workflow / chatflow / agent 等资源的本地归档
• DSL 创作：从业务需求生成 import-ready DSL（workflow-create + spec v2）、本地校验（dsl validate）
• 双轨 DSL 导入：优先 Console API（dsl import --via auto），5xx/网络错误自动降级 Playwright；不再默认依赖 RPA
• DSL 导出：经 Console API 拉取现网 app 的 DSL（dsl export）
• 导出的 DSL 文件校验、摘要、快照与 current 版本维护
• 基于 app API key 的使用层检查
• 模型 provider 配置（openai_api_compatible 加模型，联动 newapictl 消费）
• Dify 1.13.x workflow DSL / graph 兼容性排障与生产验收
• Studio 导入后 graph 损坏、未发布 app、输出结构漂移等使用层救援
• 资源清单 resources.yml 的登记与批量筛选计划
• 把后续新 workflow 及时沉淀到统一资源目录

DSL 创作与导入（0.2.0 新增）

三步创作流程

1. difyctl workflow-create intake ... --spec-out ./specs/x.yml：从业务需求生成结构化 spec（默认 v2）
2. difyctl workflow-create scaffold --spec ./specs/x.yml --output ./drafts/x.dify.yml：产出 import-ready DSL（含 app/kind: app/version: "0.6.0"/workflow.features/完整 graph node wrapper + position + edges）
3. difyctl dsl validate ./drafts/x.dify.yml：本地校验（version/mode、图端点可达性、环检测、edge 引用、LLM 必填字段、变量引用语法、if-else handle）

双轨导入决策

• difyctl dsl import --dsl ./drafts/x.dify.yml --via auto（推荐）：
  • Console API 成功 → 返回 app_id + app_url
  • Console API 返回 5xx 或网络错误 → 自动降级 Playwright 浏览器导入
  • Console API 返回 4xx（配置/鉴权错误）→ 直接报错，不降级
• --via api：只走 Console API，失败即报错（CI / 无 GUI 环境）
• --via browser：只走 Playwright（现网 API 不可用时的兜底）

导入前默认自动跑一次 dsl validate；用 --skip-validate 跳过。

详细 DSL 结构、节点 schema、布局与踩坑见：

• references/REFERENCE-DSL-AUTHORING.md
• references/REFERENCE-DSL-GOTCHAS.md

输入

• 当前资源目标，例如 app、workflow、chatflow
• 本地 DSL 导出文件路径
• Dify app base URL 与 app API key（如需远端检查）
• 资源 ID、标题、标签、app_id、app_name
• 当前项目的资源工作区目录

输出

• 规范化的资源目录
• resource.json 元数据
• dsl/current.* 与 dsl/snapshots/* 快照
• 远端 app 信息或参数检查结果
• 对后续沉淀方式的明确建议

工作流

1. 先判断这是“远端 app 检查”还是“本地资源沉淀”。
2. 若需要远端检查：
   • 优先使用 difyctl app info
   • 必要时再用 difyctl app parameters
   • 如需补充环境描述，可再用 difyctl app meta
   • 若任务涉及命名、描述、发布对象或 Studio 卡片展示，先确认 live app 事实，再讨论本地 DSL 或 registry
3. 若需要沉淀资源：
   • 先用 difyctl resource init <resource_id> --mode ...
   • 再把导出的 DSL 用 difyctl resource capture ... 归档
   • 默认维护 dsl/current.* 与时间戳快照
4. 若要维护项目级资源清单：
   • 先用 difyctl registry init
   • 再用 difyctl registry upsert ...
   • 批量筛选时用 difyctl batch plan ...
5. 若需要从零生成一个业务需求对应的 workflow：
   • 先用 difyctl workflow-create intake ... 或 draft --from-demand ...
   • 再用 difyctl workflow-create validate-spec ...
   • 然后用 difyctl workflow-create scaffold ... 产出 DSL 草稿
6. 若需要把本地资源同步回 Dify Studio：
   • 先用 difyctl studio create-plan ...
   • 或对已有资源用 difyctl studio export-plan ...
   • 或用 difyctl studio duplicate-plan ...
7. 若准备切到真实浏览器自动化执行：
   • 先用 difyctl studio browser-doctor
   • 再用 difyctl studio import-dsl-run --dsl ...
   • 当前阶段要预期登录页和按钮选择器仍需现场微调
8. 若只想快速理解一个 DSL：
   • 先用 difyctl dsl summarize <path>
9. 每次新增或明显改造 workflow 后，都要判断是否应该：
   • 继续补当前资源目录
   • 新增一个独立资源目录
   • 回填到项目级知识卡片或 SOP
10. 若导入后的 workflow 在 Dify 1.13.x 中无法运行或 Studio 无法正常打开：

• 先把问题分层为 graph schema、publish state、runtime invoke 三类
• 优先用黑盒 app API 调用和只读数据库检查定位，不要一上来就改库
• 确认是旧 DSL 兼容性问题后，再决定是“最小字段补丁”还是“整图原生重建”

1. 若需要做生产救援：

• 先确认 draft graph、published workflow、apps.workflow_id、api_tokens 四个对象是否齐全
• 再确认 start、llm、end 三类节点是否符合当前 Dify 原生 schema
• 最后用真实样例做健康路径与异常路径双验证，结果通过后再宣布可用

1. 若任务同时涉及 Git 台账、本地 DSL、Studio 页面和 live app：

• 先把四层对象分开看，不要假设它们天然一致
• 优先核对 live app，再核对 resources.yml / resource.json / dsl/current.*
• 若只是 Studio 资产漂移，先修正 Studio，再把本地台账回写到一致状态

1. 若需要查询/新增 Dify 模型提供商下的模型（模型台账）：

• 先 difyctl provider login --username-env ... --password-env ... --headed 取 Console 会话，用返回的 full_cookie_header（含 csrf_token，纯 session_cookie 会 401）作为 --console-key
• 用 difyctl provider models --provider <full-path> 查某提供商已配置模型（台账视图），随时看清现状
• 用 difyctl provider add-model --provider <full-path> --model <name> --endpoint-url <base>/v1 --api-key <key> 给 openai_api_compatible 类可自定义模型的提供商加单个模型；先 --dry-run 预览 payload（无需 Console 会话）
• newapi 消费 key 无法经 Admin API 读取（服务端全程脱敏、忽略客户端传入 key），必须从 newapi Web UI 复制或由用户提供；获取后 newapi/v1/chat/completions 冒烟测试确认模型可用再注册

1. 若需要改某 workflow 的 LLM 节点模型：

• GET /console/api/apps 定位 app_id → GET .../workflows/draft 取 graph
• 改 data.type=="llm" 节点的 model.provider 与 model.name → POST .../workflows/draft 保存 → POST .../workflows/publish 发布
• 用 POST .../workflows/draft/run（SSE 流）跑一次，确认 node_finished/workflow_finished 均 status=succeeded 且 error=None