flowlink-examples

FlowLink Examples

这个模块只放业务侧接入示例，不属于框架核心运行时。

推荐阅读顺序

• realworker/：普通业务服务的推荐形态。服务启动期读取 flowlink 配置并调用 plan.LoadConfig，可选安装 Switch 开关解析器，再调用 plan.ConfigureFromConfig。 单服务单链路请求只创建 core.FlowContext、写入 Params，然后调用 plan.Execute(fc)。它也演示把 plan.NewDebugHandler 挂到业务服务自己的 POST /worker/v1/workflow-debug 和 GET /worker/v1/node-manifest，供控制台调试 当前 workflow 定义并读取实际注册的节点清单。
• simpleworker/：不接 flowlink-admin 的纯代码形态。适合测试、内嵌 workflow 或本地验证。
• publishedworker/：低阶 adapter-message worker helper 形态。它会直接展示 flowlink-engine/adapter 和 flowlink-ext 的用法，因此依赖面比普通业务 接入更宽。新业务服务通常优先看 realworker/。

模块依赖说明

flowlink-examples 为了把不同接入层级放在一个示例模块中，会同时依赖 flowlink-plan、flowlink-core、flowlink-engine 和 flowlink-ext。 这不是普通业务服务的最小依赖面。

普通单链路业务服务通常只需要：

• flowlink-plan
• flowlink-core

如果业务要安装默认扩展节点，再显式引入 flowlink-ext。

如果 workflow 的 tracing.switchBinding 绑定到了 Switch 开关名，业务服务可以按 Switch demo 启动 SDK，然后把 flowlink-plan/switchsdk.NewResolver() 放到 plan.RuntimeOptions.SwitchResolver 或 plan.Config.SwitchResolver。示例不默认启动 Switch SDK，避免没有本地 Switch 服务时影响最小接入示例运行。 固定模式只配置 tracing.enabled；Switch 模式只配置 tracing.switchBinding.switchName， 不存在兜底值。使用 Switch 模式却未启动 SDK、未同步到对应规则或解析失败时，本次 workflow 会在进入 engine 前返回错误。

realworker/ 已经演示这条链路：默认不开启 Switch；设置 FLOWLINK_SWITCH_ENABLED=true 后，会使用 FLOWLINK_SWITCH_DOMAIN、 FLOWLINK_SWITCH_NAMESPACE、FLOWLINK_SWITCH_ENV、FLOWLINK_SWITCH_SERVICE、 FLOWLINK_SWITCH_VERSION 启动 Switch SDK，并把 resolver 交给 flowlink-plan。

业务侧 debug 入口

admin 控制面不执行业务节点调试。控制台调试当前编辑内容或已保存版本时，需要把请求发到业务服务， 因为只有业务进程注册了真实业务 node、业务依赖和外部 client。业务服务应挂载：

handler := plan.NewDebugHandler(plan.DebugHandlerOptions{
	Token:          os.Getenv("FLOWLINK_DEBUG_TOKEN"),
	AllowedOrigins: []string{"http://localhost:8000"},
})
mux.Handle("/worker/v1/workflow-debug", handler)
mux.Handle("/worker/v1/node-manifest", handler)

realworker/ 默认只监听 127.0.0.1:19080；可通过 FLOWLINK_DEBUG_ADDR 覆盖。 本地默认 token 是 flowlink-local-debug-token，默认只允许 http://localhost:8000 和 http://127.0.0.1:8000。可分别通过 FLOWLINK_DEBUG_TOKEN 和逗号分隔的 FLOWLINK_DEBUG_ALLOWED_ORIGINS 覆盖。 debug 与 node-manifest 都要求 token；不要把 allowed origins 配成 *。 如果只想启动 debug HTTP 服务而不执行示例请求，设置：

cd flowlink-examples
FLOWLINK_DEBUG_SERVER_ONLY=true go run ./realworker

前端控制台在 flowlink-frontend/config/env.ts 配置业务服务地址：

WORKFLOW_DEBUG_BASE_URL: 'http://127.0.0.1:19080',
WORKFLOW_DEBUG_TOKEN: 'flowlink-local-debug-token',

调试请求会访问 ${WORKFLOW_DEBUG_BASE_URL}/worker/v1/workflow-debug，节点库会访问 ${WORKFLOW_DEBUG_BASE_URL}/worker/v1/node-manifest。业务侧的 FLOWLINK_DEBUG_TOKEN 与前端 WORKFLOW_DEBUG_TOKEN 必须完全相同。

admin 保存的节点密码使用 AES-GCM secretRef。realworker 拉取或调试这些 workflow 时， 必须与 admin 使用同一个 FLOWLINK_WORKFLOW_SECRET_KEY，否则引用无法解密且执行会失败。 dev 下两者都有相同的本地默认值；共享环境必须显式注入至少 32 字节的稳定 key：

export FLOWLINK_WORKFLOW_SECRET_KEY='replace-with-the-same-stable-key-used-by-admin'
export FLOWLINK_DEBUG_TOKEN='replace-with-a-debug-only-token'
export FLOWLINK_DEBUG_ALLOWED_ORIGINS='https://flowlink-console.example.com'

workflow.returning 和 workflow.tracing 仍按 workflow 定义生效；调试弹窗里的 trace 开关只是本次请求的临时覆盖，便于临时打开事件、日志或 stats，不会修改已保存或 已发布版本。