goalflow

goalflow — 图编排 Agent 循环

goalflow 提供两种基于 LangGraph 构建大模型应用的方式，并允许你将它们组合使用：可视化优先（在 Dify 中设计，再将导出的 DSL 转译为你拥有的 LangGraph Python 文件）和代码优先（通过随附的 agent_kit 构建 ReAct/Deep Agent 循环）。graph 节点可以承载 agent 循环，而 Agent 可以将子工作流作为工具调用。

有两点几乎影响着关于本项目的所有回答：

1. 它是从内部生产系统中提取出来的。可泛化的核心是真实可用的；默认配置则带有倾向性（Qwen/DashScope、Alibaba OSS）。
2. 项目自身文档开篇就有一条CAUTION：有效凭据仍留在 git 历史中。这是任何公开推送前必须解决的阻碍，不是脚注。

何时使用此技能

• 将 Dify 流程转换为受版本控制的 LangGraph 代码，而不再依赖 Dify 运行时
• 选择或编写工作流节点、边、分支路由或迭代／循环子图
• 使用 agent_kit 构建 Agent 循环——图构建器、中间件链、执行框架／模型路由器、可执行技能
• 配置服务层：数据适配器、SSE 流式传输、HITL 中断、Redis/MySQL 和工作流注册
• 编写可由大模型匹配并注入提示词的 SKILL.md 能力
• 在发布或实际部署之前审计代码仓库

何时不使用此技能

• 一般的 LangGraph 图／状态／检查点 API 问题 → langgraph-fundamentals、langgraph-persistence
• 通用 LangChain 链、检索器或 RAG 设计 → langchain-fundamentals、 langchain-rag
• 与此引擎无关的通用 HITL 模式 → langgraph-human-in-the-loop
• 在 agent_kit 封装之外直接使用 deepagents → deep-agents-core
• 为此代码仓库的 Agent 目录而非 goalflow 运行时编写技能 → skill-standardization、write-a-skill
• 大模型追踪／评估平台选型 → langsmith、opik

说明

第 1 步：收集需求信息

以下四项决定使用模式：

1. 起始材料——Dify DSL 导出文件、空代码仓库、现有的 BaseWorkflow 子类，或正在运行的部署
2. 目标形态——工作流图、Agent 循环，或承载循环的图节点
3. 客户端协议——Dify 原生协议（默认）、兼容 OpenAI 的协议，或自定义协议
4. 环境实际情况——Redis 和 MySQL 是否确实可用？MySQL 为检查点提供支持，而检查点是实现停止／恢复和 HITL 的必要条件

第 2 步：只选择一种模式

模式	适用场景	产出
orient	不确定 goalflow 是否合适	适配性判断，或坦诚建议改用原生 LangGraph
transpile	已有 Dify DSL 导出文件	生成的 BaseWorkflow 子类，已注册且可运行
build	编写或修复图本身	节点选择、边／分支路由、错误处理策略
agent	任务需要开放式的工具使用循环	带有构建器、中间件和执行框架的 Agent/AgentBaseNode
serve	为客户端配置运行时	适配器、端点、流式传输、HITL、存储、注册
harden	发布或部署之前	发布前检查关卡列出的阻碍项

无论用户要求哪种模式，在向公共或共享远程仓库推送之前都要运行 harden。

第 3 步：以只读方式检查环境

bash .agent-skills/goalflow/scripts/goalflow.sh doctor
bash .agent-skills/goalflow/scripts/goalflow.sh doctor /path/to/goal-flow

doctor 会报告 Python 版本、核心软件包（langgraph、fastapi、 redis、pymysql、sqlalchemy、langchain-openai）、goalflow 和 agent_kit 是否可导入，以及哪些 .env 键已设置——仅报告键名，绝不报告键值。它不会安装任何内容，也不会启动服务。

第 4 步：在手写图之前先进行转换

转换器采用两阶段流水线：先将 DSL 解析为内部图模型，再通过双分派访问器生成 Python。

python -m goalflow.tool.dify_transformer.wf_transformer_tool \
  --dsl path/to/my_flow.yml \
  --out my_flow_workflow.py \
  --class MyFlowWorkflow

以下两点可以避免常见错误：

• 解析是只读的。为了适配主机，对内存中的副本进行重写；导出文件永远不会被修改。
• 替换表是 DifyDslParser.DEFAULT_HOST_SUBSTITUTIONS。它编码了原作者的内部主机名。传入自己的 host_substitutions=，或传入 {} 来禁用它——不要沿用他们的设置。

生成代码只是工作的一半。生成的类必须先注册才会生效（第 6 步）。详情请参阅 references/dify-transpile.md。

第 5 步：根据真实的 BaseNode 契约编写节点

你只需实现一个方法 call(self, state)，其返回类型同时决定状态更新和路由方式：

返回值	含义
dict	合并到状态中，并继续前往 next_node_ids
Command(update=, goto=)	更新状态并跳转
List[str]	分支路由——选择传出的句柄
Sequence[Send]	扇出，每个 Send 对应一个并行分支
None	不更新

__call__ 包装器会免费为你提供计时、日志记录和汇合屏障：具有多个 pre_node_ids 的节点会重新入队，直到到达其拓扑深度，因此它会在所有上游分支到达后运行一次。不要自己手动实现。

节点目录、错误策略以及迭代/循环上限，请参阅 references/nodes-and-graph.md。

第 6 步：注册工作流，并说明注册的真实含义

# src/goalflow/api/auth_validator.py
apikey_workflow_def_map = {
    "2999a65aa67e37253623075d60796f9a": MyWorkflow,  # md5(api_key)
}

这是一个按 API 密钥的 MD5 值作为键的静态代码内映射表。上游文档将其描述为当前设计，也是实际部署时首先需要替换的部分。MD5 不适合用于对密钥进行哈希。用户询问如何注册工作流时，既要回答问题，也要指出这一点——不要把它说成生产环境的身份验证方案。

第 7 步：Agent 工作优先使用 AgentBaseNode

AgentBaseNode 多重继承工作流的 BaseNode 和 agent_kit 的 Agent。继承它并实现 output_schema、build_prompt 和 build_command。它取代了 DeepAgentBaseNode、CreateAgentBaseNode 和 StateGraphBaseNode，也是比旧版手动 AgentNode ReAct 循环更推荐的方式。

构建器会自动选择：存在 subagents 时使用 DeepGraphBuilder，否则使用 ReactGraphBuilder。中间件按列表顺序运行。

references/agent-kit.md介绍了钩子、中间件目录以及执行框架/模型路由器契约。

第 8 步：将协议变更限制在适配器层

引擎会发出与协议无关的语义事件；DataAdapter 是负责序列化这些事件的最后一环。要添加协议，只需实现 generate()（流式）和 execute()（阻塞式）——无需改动引擎、节点或图。

DifyDataAdapter 会直接透传，因为内部格式本身就是 Dify 协议。OpenAIDataAdapter 为 /v1/chat/completions 提供支持。

流式处理会感知分支：来自未选中的 if-else 或分类器分支的令牌会在抵达客户端之前被过滤掉。详情请参阅 references/serving-and-protocols.md。

步骤 9：推送前运行预发布检查

python3 .agent-skills/goalflow/scripts/preflight_audit.py /path/to/goal-flow

仅使用标准库。该脚本以确定性方式运行上游检查清单：检查已跟踪的 .env*/密钥/日志文件、在 git 历史中仍可访问的 .env* 对象、 硬编码的内部 IP 和端点、.gitignore 覆盖范围、LICENSE 是否存在、开放 CORS 与凭据同时启用的情况、MD5 认证映射，以及 CodeNode 的 exec 路径。它会输出一个 ```review 围栏 JSON 代码块， 并在发现阻断项时以 1 退出。

其中编码了不可妥协的规则：取消跟踪 .env 并不会将其从历史记录中移除。 轮换所有凭据，并且使用 git filter-repo 清理历史记录，然后推送到一个全新远程服务，绝不要推送到 已经保存这些密钥的远程服务。

已发布的 wanmol/goal-flow 历史记录已经清理过（只保留了 .env.example）， 因此通常能通过这项检查。它对内部 Fork、镜像，以及清理前创建的克隆 尤为重要，因为原始凭据仍保存在这些位置。

完整检查清单见 references/security-gate.md。

步骤 10：编写运行时技能时考虑注入成本

goalflow 有两套技能系统。主项目引擎 （src/goalflow/skill/）使用 大模型 将 SKILL.md 与查询匹配（而非 关键词；默认值为 qwen-turbo、阈值为 0.3、top_k 为 1），并将 Markdown 正文原样注入系统提示词。agent_kit 的引擎还支持可执行 技能（将 module:func 作为 LangChain 工具）和混合模式。

python3 .agent-skills/goalflow/scripts/check_goalflow_skill.py skills/weather_query

由于正文会原样注入，每次匹配到该技能时，正文长度都会产生提示词成本。检查器会对正文过长和 description 过于含糊、无法让匹配器据此进行判断的情况发出警告。

references/skills-engine.md 介绍了 frontmatter、 匹配机制，以及如何在两种引擎之间选择。

最佳实践

1. 先转译，再自行维护代码。 目的是摆脱 Dify 的运行时；不要继续将 DSL 作为事实来源来回转换。
2. 替换主机替换表。 继承上游作者的内部主机名会悄无声息地改写你的 URL。
3. 绝不要把 MD5 API 密钥映射说成生产级认证。 回答注册相关问题后，再指出这一点。
4. 仅将 CodeNode 输入视为可信内容。 它会对 DSL/模型提供的 Python 执行 exec，而 AST safe_check() 防护在上游已禁用。不要接受不可信的 DSL，除非重新启用并加强沙箱。
5. 没有 MySQL 时，不要承诺支持 HITL 或暂停/恢复。 检查点保存器是两者的 基础；没有检查点保存器，就无法实现持久化暂停。
6. 优先使用 AgentBaseNode，而不是 AgentNode，也不要使用那三个已弃用的 基类。
7. 将协议工作放在适配器中，绝不要放进引擎。 如果支持某个客户端需要改动节点， 就说明设计已经偏离方向。
8. 说明某个默认值何时带有阿里巴巴风格。 Qwen/DashScope、OSS 和 Hologres 的默认值源于项目的起源，而非推荐方案。
9. 推送到共享远程服务前运行 preflight_audit.py，并将历史记录中残留的密钥视为已泄露，而不只是取消跟踪。

示例

示例 1：“我在 Dify 中设计了一个工作流，接下来该做什么？”

使用 transpile 模式：运行转换器，覆盖 host_substitutions，将生成的类注册到 API 密钥映射中，并指出该映射只是演示机制。

示例 2：“我分支中的令牌泄露给客户端了”

不应该发生这种情况——分块处理器会剪除未选中的 if-else/分类器分支。请检查该节点是否能够根据已选择的分支确定地到达 answer/end 节点，而不是去修补适配器。

示例 3：“不使用 MySQL 可以运行吗？”

可以部分运行，但必须说明哪部分会出问题：MySQL 为 LangGraph 检查点保存器提供支持，因此暂停/恢复和 HITL 将不再持久化。

示例 4：“我们准备开源自己的分叉版本”

先使用 harden 模式。针对你自己的检出副本运行 preflight_audit.py——干净的 git status 并不能说明克隆后还能恢复什么，而在上游清理之前创建的分叉版本仍带有原始凭据。

示例 5：“我该用 goalflow，还是直接用 LangGraph？”

使用 orient 模式。如果没有要转译的 Dify 设计、不需要可切换的线协议，也不需要由图来托管循环，那么直接使用 LangGraph 更轻量——应当引导用户改用它，并说明原因。

参考资料

• references/dify-transpile.md — 两阶段流水线、CLI 标志、宿主替换、生成内容的结构
• references/nodes-and-graph.md — BaseNode 契约、NodeOutput 联合类型、扇入、错误策略、完整节点目录
• references/agent-kit.md — Agent 钩子、图构建器、中间件目录、运行框架/模型路由器、可执行技能
• references/skills-engine.md — SKILL.md 前置元数据、LLM 匹配、提示词注入、主引擎与 agent_kit 引擎
• references/serving-and-protocols.md — 端点、数据适配器、三层流式传输、人在回路（HITL）、存储和配置
• references/security-gate.md — 发布前检查清单，以及每项发现实际造成的代价
• scripts/goalflow.sh — 只读的 doctor，以及 audit 和 check-skill 透传
• scripts/preflight_audit.py — 仅使用标准库的发布前安全检查
• scripts/check_goalflow_skill.py — 仅使用标准库的运行时 SKILL.md 前置元数据和注入成本检查
• goalflow GitHub Repository
• 项目标准：.agent-skills/skill-standardization/SKILL.md