CyberStrikeAI/docs/workflow-graph.md

CyberStrikeAI 图编排使用说明

English

本文档说明 图编排（Graph Orchestration） 的完整使用方式：如何在画布上搭建流程、配置各类型节点、在节点之间传递数据，以及如何将流程绑定到角色并自动运行。

---

一、在哪里使用图编排

1. 登录 CyberStrikeAI Web 端
2. 左侧导航进入 图编排
3. 在左侧列表选择已有流程，或新建流程
4. 在中央画布拖拽、连线、配置节点
5. 填写流程 ID、名称、描述 后点击 保存

保存后的流程可在 角色管理 中绑定到某个角色。绑定后，用户与该角色对话时会按流程图自动执行（workflow_policy: auto）。

---

二、画布基本操作

操作	说明
添加节点	点击画布上方节点类型按钮（开始、工具、Agent、条件、审批、输出、结束）
连线	点击 连线，依次点击源节点和目标节点；再次点击 连线 退出连线模式
选中元素	单击节点或连线，右侧显示 节点属性
删除选中	点击 删除选中 删除当前节点或连线
自动布局	点击 自动布局 整理节点位置
删除流程	点击 删除 删除整个流程定义

建议： 每个流程至少包含 1 个开始节点 和 1 个输出节点；开始节点不应有入边，输出节点不应有出边。

---

三、执行模型（先理解再配置）

图编排按 有向图 执行，引擎从 开始 节点出发，沿连线依次运行下游节点。

每次运行会维护一份内部状态，模板变量 {{...}} 从这里取值：

内部状态	模板前缀	含义
inputs	{{inputs.xxx}}	流程启动时的输入（用户消息、会话 ID 等）
lastOutput	{{previous.xxx}}	上一个刚执行完 的节点的输出
outputs	{{outputs.xxx}}	全局 命名变量池（由节点的「输出变量名」写入）
nodeOutputs	{{节点ID.xxx}}	指定节点 ID 的完整输出对象

3.1 previous 是什么？

{{previous.output}} 表示 紧邻的上一个执行节点 的 output 字段。

• 每执行完一个节点，引擎都会更新 lastOutput
• 不是「画布上画线的上游」，而是 实际执行顺序上的上一步

示例：

开始 → Agent A → Agent B

Agent B 的 {{previous.output}} = Agent A 的输出。

但若中间有条件节点：

开始 → Agent A → 条件 → Agent B

Agent B 的 {{previous.output}} = 条件节点 的输出（true / false），不是 Agent A 的结果。

3.2 outputs 是什么？

outputs 是引擎在运行过程中维护的 命名变量注册表。

当 Agent、工具、输出 等节点配置了 输出变量名（字段 output_key）后，节点执行成功会把结果写入：

outputs["你填的变量名"] = 节点输出内容

之后 任意下游节点 都可以通过 {{outputs.变量名}} 引用，不要求两个节点直接相连。

示例：

• Agent A 的 输出变量名 填 agent_result1
• Agent B 的 输入来源 填 {{outputs.agent_result1}}

即使 A 和 B 之间隔着条件节点，B 仍能拿到 A 的输出。

3.3 什么时候用 previous，什么时候用 outputs？

场景	推荐写法
两个节点 直连，只取上一步结果	{{previous.output}}
中间有其他节点（条件、工具、审批等）	{{outputs.变量名}}
需要引用 更早 的某个节点结果	{{outputs.变量名}} 或 {{节点ID.output}}
条件判断要基于某 Agent 的输出	{{outputs.变量名}} != ""
读取用户最初输入	{{inputs.message}}

记忆口诀：

• previous = 上一步（链式、紧邻）
• outputs = 按名字取（跨节点、可回溯）

---

四、模板语法

4.1 基本格式

{{变量路径}}

支持字母、数字、下划线、点、连字符，例如：

{{previous.output}}
{{outputs.agent_result1}}
{{inputs.message}}
{{inputs.conversationId}}
{{previous.matched}}
{{node-abc123.output}}

4.2 可用路径一览

路径	说明
{{inputs.message}}	用户消息（开始节点输入）
{{inputs.conversationId}}	会话 ID
{{inputs.projectId}}	项目 ID
{{previous.output}}	上一节点主输出
{{previous.matched}}	上一条件节点的匹配结果（true / false）
{{outputs.变量名}}	某节点注册过的命名输出
{{节点ID.output}}	指定节点 ID 的 output 字段

4.3 条件表达式

条件节点和连线条件支持简单比较：

{{outputs.agent_result1}} != ""
{{previous.output}} == "ok"
{{outputs.count}} == "100"

规则：

• 使用 == 或 != 做字符串比较（两侧会自动去掉首尾空格和引号）
• 无比较符时，非空且不为 false / 0 / null 视为真

---

五、节点类型与配置

5.1 开始（start）

流程入口，将用户输入注入 inputs。

字段	说明	默认值
输入变量	逗号分隔的输入键名	message, conversationId, projectId

开始节点输出包含：output、message、conversationId、projectId。

5.2 Agent（agent）

调用大模型 Agent 处理任务，支持多种运行模式。

字段	说明	默认值
Agent 模式	eino_single / deep / plan_execute / supervisor	eino_single
输入来源	上游数据的模板表达式	{{previous.output}}
节点指令	本节点要完成的任务描述	空
输出变量名	写入 outputs 的键名	agent_result

消息拼装规则：

• 仅填 节点指令：直接把指令发给 Agent
• 仅填 输入来源：生成「请基于上游节点输出继续处理：…」
• 两者都填：合并为「上游输入 + 节点指令」

Agent 节点执行后：

• previous.output 更新为本节点响应文本
• 若配置了 输出变量名，同时写入 outputs[输出变量名]

5.3 工具（tool）

调用已启用的 MCP 工具。

字段	说明	默认值
MCP 工具	工具名称（必填）	—
参数模板	JSON，支持 {{...}} 模板	{}
超时秒数	可选	空

示例参数模板：

{"target": "{{inputs.message}}", "port": "443"}

若配置了 输出变量名，工具返回结果会写入 outputs。

5.4 条件（condition）

根据表达式计算分支，输出 matched（true / false）。

字段	说明	默认值
条件表达式	支持 {{...}} 与 == / !=	{{previous.output}} != ""

分支规则：

• 从条件节点连出的 第一条线 默认为 「是」 分支（matched == true）
• 第二条线 默认为 「否」 分支（matched == false）
• 连线标签可写 是 / 否（或 yes / no、true / false）辅助识别
• 第三条及以后的出边需在 连线条件 中自定义表达式

连线条件示例（选中连线后在右侧配置）：

{{previous.matched}} == "true"
{{previous.matched}} == "false"

5.5 审批（hitl）

人工确认检查点（当前为记录模式，自动标记 approved: true 并继续）。

字段	说明	默认值
审批提示	支持模板	请审批该步骤是否继续执行
审批方	human / audit_agent	human

5.6 输出（output）

将流程最终结果写入 outputs，供结束摘要和对话展示使用。

字段	说明	默认值
输出变量名	必填，最终结果的键名	result
变量来源	模板表达式，决定写入的值	{{previous.output}}

注意： 输出节点是流程的「出口」，不应再有出边。

5.7 结束（end）

可选节点，用于生成结束摘要模板（角色绑定流程中较少单独使用）。

字段	说明	默认值
结束摘要模板	支持 {{outputs.xxx}}	{{outputs.result}}

---

六、连线配置

选中 连线 后，右侧可配置 连线条件。

场景	示例
普通节点后的过滤	{{previous.output}} == "ok"
条件节点「是」分支	{{previous.matched}} == "true"
条件节点「否」分支	{{previous.matched}} == "false"

若不填连线条件：

• 非条件节点：连线始终放行
• 条件节点：按出边顺序自动分配是/否分支

---

七、完整示例：跨条件节点传递 Agent 输出

7.1 流程结构

开始 → Agent（生成初始值）→ 条件 → Agent（加工）→ 输出
                              ↘ 否 → 输出

7.2 节点配置

Agent 1（第一个 Agent）

字段	值
节点指令	只输出 123333333
输出变量名	agent_result1

条件

字段	值
条件表达式	{{outputs.agent_result1}} != ""

Agent 2（第二个 Agent）

字段	值
输入来源	{{outputs.agent_result1}}
节点指令	在输入基础上加 100，然后输出
输出变量名	agent_result

输出

字段	值
输出变量名	result
变量来源	{{outputs.agent_result}}

7.3 常见错误

错误配置	原因
Agent 2 输入来源写 {{previous.output}}	previous 指向条件节点，得到的是 true/false，不是 Agent 1 的文本
未给 Agent 1 填输出变量名	outputs.agent_result1 不存在，下游取到空值
条件表达式写 {{previous.output}}	判断的是开始节点或上一节点的输出，而非 Agent 1 的命名变量

---

八、绑定角色并运行

8.1 在角色管理中绑定

1. 进入 角色管理，编辑或新建角色
2. 选择 工作流 / 图编排 绑定的流程 ID
3. 策略设为 auto（默认：有 workflow_id 时自动执行）
4. 保存角色

也可在角色 YAML 中直接配置：

name: 工作流测试
workflow_id: "1233"
workflow_version: latest
workflow_policy: auto

8.2 运行效果

用户选择该角色并发送消息后：

1. 引擎加载对应 graph_json 并按图执行
2. 对话页可看到 workflow_start、workflow_node_start、Agent 推理等进度事件
3. 流程结束后返回摘要，列出 outputs 中所有命名输出

若未配置输出节点或条件未命中，outputs 可能为空，摘要会提示检查输出节点与分支。

---

九、保存前校验规则

保存时系统会自动检查：

规则	说明
必须有开始节点	至少 1 个 start
必须有输出节点	至少 1 个 output，且填写输出变量名
连线合法	源/目标节点存在，不能自环
开始节点无入边	开始节点不能被指向
输出节点无出边	输出节点后不应再连线
工具节点	必须选择 MCP 工具
条件节点	必须填写表达式；建议 1～2 条出边（是/否）

---

十、排错指南

现象	可能原因	处理建议
下游拿到空值	上游未配置输出变量名	给上游 Agent/工具填 输出变量名，下游用 {{outputs.xxx}}
下游拿到 true/false	误用 {{previous.output}}，上一步是条件节点	改用 {{outputs.xxx}}
条件总走「否」	表达式与真实输出格式不一致	检查 Agent 输出是否带引号、换行；用 != "" 先验证
流程无最终输出	未命中输出节点所在分支	检查条件分支连线；确保至少一条路径到达 输出 节点
角色对话未跑流程	角色未绑定或未启用	确认 workflow_id、workflow_policy: auto、流程 enabled: true
工具节点失败	参数 JSON 不合法或工具未启用	检查参数模板；在 MCP 中启用对应工具

---

十一、最佳实践

1. 命名规范：为每个需要被引用的节点设置有意义的输出变量名，如 scan_result、parsed_targets，避免都叫 agent_result。
2. 跨节点传参优先用 outputs：只要中间可能插入条件、工具、审批节点，就应用命名变量。
3. previous 仅用于直连：A → B 且无中间节点时，{{previous.output}} 最简洁。
4. 条件判断引用源数据：判断 Agent 输出时用 {{outputs.xxx}}，不要用 {{previous.output}}（除非条件紧跟在目标 Agent 之后）。
5. 每条路径都要有出口：确保「是」「否」分支最终都能到达 输出 节点（或你期望的终点）。
6. 保存前跑一遍：用简单指令（如固定字符串输出）验证数据传递，再替换为真实业务逻辑。

---

十二、相关代码位置（开发者参考）

模块	路径
执行引擎	internal/workflow/runner.go
画布前端	web/static/js/workflows.js
流程 API	internal/handler/workflow.go
角色绑定	internal/config/config.go（workflow_id 字段）