goalflow — Graph-Orchestrated Agent Loop
goalflow — Graph-Orchestrated Agent Loop
一句话结论
wanmol/goal-flow 是一个把 可视化 workflow graph 和 代码型 agent loop 合并到同一运行时里的 LangGraph 应用框架：前者通过 Dify DSL → LangGraph Python 转译获得可视化设计与版本化代码，后者通过 vendored agent_kit 提供 ReAct/Deep/custom agent loop、中间件、模型路由、skills、observability 和 streaming/HITL。它对 Loop-Engineering 与 Harness-Engineering 的价值在于：不是再发明一个聊天 UI，而是把“图式确定控制流”和“开放式 agent 循环”放在同一个可部署、可替换协议、可路由 skill 的工程面上。
为什么对用户重要
用户的 Hermes / llm-wiki 工作流已经具备最小 loop：cron 触发、wiki orient、来源发现、deep ingest、index/log/vector 维护和最终报告。但现在这些 loop 主要靠 prompt + markdown discipline 连接；一旦流程变复杂，例如“先可视化设计 ingest/review/publish 流程，再让 agent 在某些节点开放探索”，就需要更明确的 graph/loop 分层。goalflow 提供了一个值得观察的形态：确定性 workflow 负责边界、分支、协议、状态；agent loop 只在需要开放式推理/工具调用的节点内运行。
这也直接关联 External-Agent-Skills-Design-Patterns：goalflow 的 SKILL.md 技能不是全局常驻 prompt，而是按查询匹配、按需注入；agent_kit 侧还支持 executable skills。对 llm-wiki 来说，这强化了“技能/知识包应渐进披露，而不是把所有长期知识都塞进上下文”的方向。
机制 / 一阶原理
1. Graph 与 Loop 的职责分离
goalflow 的核心机制是：Dify DSL 先解析成内部 graph model，再生成 BaseWorkflow 子类形式的 LangGraph Python 文件。这样 workflow graph 可以由 Dify 这类视觉编辑器设计，但最终产物是用户可拥有、可 diff、可版本管理、可扩展的代码。它避免了“可视化工具锁在平台 runtime 里”的常见问题。
在 graph 内部，agent 不必接管所有控制流；一个 graph node 可以承载 agent loop，而 agent 也可以把子 workflow 当作工具调用。这是一种比“纯 ReAct 一路跑到底”更可治理的结构：确定分支、协议适配、SSE streaming、HITL interrupt、存储和知识检索由 workflow 层承载；开放式探索、工具选择和多步推理由 agent loop 承载。
2. 协议适配与运行时边界
goalflow 把 engine 产生的 semantic events 与 wire protocol 分开：DataAdapter 把内部 stream/blocking response 转成 Dify 或 OpenAI-compatible 输出。这对 Harness-Engineering 很关键，因为 agent runtime 一旦产品化，就不能把“模型流”“业务事件”“客户端协议”混在一起；否则很难做 replay、debug、policy gate 或跨宿主迁移。
3. Skills 的渐进披露
主项目 skill engine 会扫描 skills/<skill_id>/SKILL.md，用 frontmatter 的 description/triggers/tags 做匹配，只在 query 触发时加载正文并注入 prompt。这个模式和 Hermes skill 的原则一致：skill 是 routing/workflow contract，长资料和脚本应放到 references/scripts，而不是常驻上下文。agent_kit 侧 executable skills 则进一步把 skill 从“说明文档”推进到可执行能力，但也带来权限、供应链和验证门禁问题。
与已有 wiki 概念的关系
- 对 Loop-Engineering：goalflow 是“graph-owned loop”的样本。Loop 不只是 while 调用模型，而是由 workflow graph、agent node、状态存储、streaming、HITL 和 verifier/observability 共同组成。
- 对 Harness-Engineering：它把 harness 的一部分落到工程接口上：DSL parser、workflow generator、DataAdapter、agent harness、middleware、model router、skills 和 observability 都是可替换组件。
- 对 Context-Engineering：Dify DSL、
SKILL.md、knowledge retrieval、conversation state 和 protocol events 都是不同层次的 context；框架价值来自把它们分层，而不是全部压成一段 prompt。 - 对 External-Agent-Skills-Design-Patterns：goalflow 再次验证 skill 需要 metadata、触发、渐进披露和执行边界；executable skills 必须配套安全/验证策略。
对 Hermes / llm-wiki 的可执行启发
- 把复杂无人任务拆成 graph + agent node：例如未来 wiki radar 可以显式建模为 Discover → Score → Fetch → Raw Archive → Promote/Reject → Update Concepts → Verify → Report；只有 Discover/Score/Promote 这类开放判断节点交给 agent，文件写入和验证节点尽量机械化。
- 为 cron 报告定义协议适配层：同一轮 radar 的内部事件（候选、失败、写入、reindex）可以先形成结构化 event，再适配成中文日报、log.md 条目或 Obsidian 页面，减少“报告里说了但文件没写”的漂移。
- skill 候选新增 execution-risk 字段：看到 executable skills / plugin runtimes 时，不只看 README 价值，还要记录它是否执行脚本、是否有权限边界、是否有示例任务与验证输出。
- 谨慎看待 README 性能声明：goalflow 声称低资源并发表现和生产级能力，但本次 cron 未安装/压测；这些只能作为 medium-confidence 观察，不应作为本地选型结论。
失败模式 / 边界条件
- Git history secrets 风险：goalflow 文档明确提醒真实凭证曾存在于 git history，公开前需要 history scrub 和 credential rotation。这使它不适合在无人 cron 中自动 clone/install/run；当前只应作为方法论和架构样本观察。
- 平台复杂度风险：graph + agent + skills + retrieval + protocol adapter + storage 会带来较大集成面。对个人 llm-wiki，不应因为看到完整框架就引入重平台；应先迁移低成本结构原则。
- visual builder lock-in 的反向风险：Dify DSL 转译降低 runtime lock-in，但 DSL schema、node 语义和 parser 仍可能漂移；需要对生成代码做 diff/test，而不是盲目信任转译。
- executable skill 供应链风险：一旦 skill 可执行脚本或外部工具，skill catalog 就从“文档索引”变成“软件供应链”。必须配套来源、版本、权限、checksum、sandbox 和验收任务。
深度判断
本次将 goalflow 晋升为正式 source page，而不是只留 raw，原因是它满足三项价值触发：第一，它提供可复用的 graph/loop 分层方法论；第二，它能改进 Hermes / llm-wiki 对复杂 cron workflow 的结构化建模；第三，它澄清了 workflow graph、agent loop、skill、protocol adapter 和 retrieval 在 LLM system 中的边界。未将其作为工具推荐，是因为存在 git history secrets 风险、未本机运行验证、且 README 性能声明未复现。
写入记录
- 2026-08-18 09:00 CST：新增 goalflow 来源页，沉淀 graph-orchestrated agent loop、Dify DSL 转译、DataAdapter、skill 渐进披露以及对 Hermes/llm-wiki cron workflow 结构化的启发。