# 工作流编辑后台（GSWF Admin）

> **入口地址**：编辑服务地址 + `/workflow-admin`（图形界面为 `/workflow-admin/ui`）
>
> **可用条件**：部署的是工作流编辑服务角色，且部署环境已设置工作流密码
>
> **更新日期**：2026 年 10 月 31 日
>
> 相关文档：[AuditSense 智能审核](/sense/README.md)、[AI 集成](/AI%E9%9B%86%E6%88%90.md)

## 这是什么

GSWF Admin 是**工作流的制作与发布后台**。AuditSense 等工作台负责"运行"工作流；工作流本身长什么样、有哪些节点、用哪些工具、发到哪个环境，都在这里编辑。

打开地址后先输入部署环境中设置的工作流密码，进入图形编辑界面。页面顶部有这些入口：

- **工作流库**：浏览全部工作流
- **新建工作流**：从空白骨架开始
- **设置**：含 Gate 部署、资源空间等后台设置
- **OpenViking**：查看资源
- **退出登录**：结束当前后台会话

> 看不到这个后台，通常说明当前部署的不是编辑服务角色，或没有设置工作流密码。编辑的是发布源文件本身，保存后运行时按最新源文件重新加载，**不需要重启服务**。

## 工作流库与生命周期

工作流库以表格列出每个工作流的**名称、目录、Workflow ID、节点数、Tools 数与共享技能数**，顶部搜索框支持按名称、目录名、Workflow ID 或摘要检索。每行操作列可进入**打开画布、资源、发布、重命名、归档**。

- **新建**：只需填写名称与业务描述，目录名、Workflow ID 和空白骨架会自动生成。
- **重命名**：只修改显示名称，目录名与 Workflow ID 保持不变，不影响已有引用。
- **归档**：归档后不再出现在工作流库；在归档页可以恢复、导出备份、导入归档文件，或彻底删除。

「发布目标」页签汇总各目标当前已发布的工作流，可在此单条移除。

## 流程图编辑器

打开工作流后，主画布上方有一排页签：**流程图 / 检查清单 / 主提示词 / 资源 / 工具 / 文件**，以及「发布」「关闭标签」。

流程图页签里还有三个视图可切换：**原生执行图**（默认，由已保存的 LangGraph 编译产物生成）、**LangGraph 源码**、**完整工作流**（只读 JSON，用于核对最终文档）。未保存的源码不会显示旧图；源码与编译包不一致时会拒绝加载。

节点库提供 **7 类节点**，点击或拖入即可创建：

| 节点 | 界面标题 | 用途 |
| --- | --- | --- |
| **Guard** | 输入校验 | 校验人工输入、前置条件或分支守卫 |
| **Agent** | 智能节点 | 执行主提示词、调用共享技能并产出推理结果 |
| **Judge** | 判断节点 | 根据结构化问题判定材料，输出结论与待复核标记 |
| **Tool** | 工具节点 | 调用外部工具或文件处理步骤，沉淀中间产物 |
| **Foreach** | 循环清单 | 绑定任务清单；原生流程在 LangGraph 代码中定义调度 |
| **HITL** | 人工介入 | 在关键节点请求人工确认、补充或复核 |
| **Finalize** | 结束输出 | 汇总上下文并生成最终结构化输出 |

主要交互：

- **连线**：从节点锚点拖出连线；拖动边的两端小圆点可以重新连接；点击边上的条件标签可修改条件或删除该连接。
- **节点检查器**：提供「可视化 / 文本」两个视图，文本视图可直接编辑 `config`、`bindings` JSON。
- **设为入口**：指定流程从哪里开始执行；当前入口节点会在画布上有标记。
- 各类节点有专属配置，例如 Guard 的人工输入定义与校验范围、Foreach 绑定的任务清单与顺序/并行及失败策略（终止 / 跳过 / 重试 / 询问人类）、Agent 的提示词变量与共享技能、工具绑定、Tool 节点的脚本选择。
- **输入参数映射 / 聚合方式 / 输出项**：在检查器中配置节点之间如何取数与透传。

## 检查清单页签：执行前看范围

「检查清单」页签无需执行即可预览这次会检查什么，它直接读取**已保存**的工作流设计：

- 顶部两个数字：**已列明的固定检查项**、**按输入资料展开的检查组**；
- 逐项表格：检查项目、负责节点、检查范围，范围列标注「已列明 / 执行时展开 / 待完善」；
- 底部说明：Agent 主动扩展的检查执行前不预列，另有若干取数、分类或汇总节点**不计为业务检查项目**。

若出现「N 项仍按节点整体描述、尚未拆分细项」的提示，说明这些检查项还挂在节点整体描述上，建议拆成独立细项——否则执行时无法逐项登记结论。

这一页只有**计划**——通过、问题等结论要等运行结束后在审核表里查看。

## 自动排版与草稿保存

画布上方提供三个样式选项：

- **连线**：曲线 / 直角折线——**切换立即生效，不移动节点**
- **方向**：从左到右 / 从上到下
- **间距**：紧凑 / 宽松

方向与间距选择后会显示「待应用」，需要再点一次**自动排版**才重新排列节点。排版使用 ELK Layered 算法，同一张图重复排版结果一致。

手工拖动节点、增删节点或连线后，原有的直角折线路由会失效并回退为跟随新锚点的简易折线；再次点击「自动排版」即可恢复完整路由。空图、只读预览、保存中或排版进行中时，排版按钮不可用。

编辑器默认**每 5 秒批量保存草稿**，也可以点「立即保存」。**草稿不等于发布**——草稿只是保存编辑内容，发布是单独的动作。

## 自动排版与草稿保存

画布上方提供三个样式选项：

- **连线**：曲线 / 直角折线——**切换立即生效，不移动节点**
- **方向**：从左到右 / 从上到下
- **间距**：紧凑 / 宽松

方向与间距选择后会显示「待应用」，需要再点一次**自动排版**才重新排列节点。排版使用 ELK Layered 算法，同一张图重复排版结果一致。

手工拖动节点、增删节点或连线后，原有的直角折线路由会失效并回退为跟随新锚点的简易折线；再次点击「自动排版」即可恢复完整路由。空图、只读预览、保存中或排版进行中时，排版按钮不可用。

编辑器默认**每 5 秒批量保存草稿**，也可以点「立即保存」。**草稿不等于发布**——草稿只是保存编辑内容，发布是单独的动作。

## 发布到 Gate / Workers

发布以**单个工作流**为粒度，一次可以勾选一个或多个发布目标，分别写入对应资源空间的发布包。

点「发布」会**先校验再发布**：校验发现错误时会暂停发布，并逐条列出出错节点与原因；警告不会阻断发布。

发布后 Gate / Workers 按各自的同步机制生效。要确认线上到底跑的是哪一版，可参考下方「怎么确认正在跑的是哪一版」。

## Gate 部署登记与自动接入

「设置」里的 Gate 部署页用于登记机构 Gate：机构 ID、Sense 列表、部署名与端口。一个机构默认一个 Gate，可供多个 Sense 使用。

- 点「生成接入资料」得到一次性接入 Token，把它填进 Gate 的 `WORKS_GATE_ENROLLMENT_TOKEN` 后启动，Gate 会自动绑定槽位。
- 面板上通过**配置同步 / 期望发布 / 实际发布**三项状态判断线上是否已生效。
- 可执行撤销接入 Token、停用实例、解绑或更换机器，以及生成、轮换各 Sense 的凭据。
- 「运行库 Workflow」用于核对某个目标**真实已部署**了哪些工作流。

## 资源：共享技能与任务清单

- **共享技能**以 store-hub 为唯一来源，按文件夹整包上传。
- Agent 节点勾选共享技能后，以 `shared/<id>@<version>` 形式写入绑定；发布时会自动快照进发布包，因此运行时不受后续改动影响。
- **原子任务清单**：一个任务项对应一个 Markdown 文件，Foreach 节点按清单顺序加载并执行。清单与任务项可新增、删除、上移下移，保存后随工作流一起发布。
- **主提示词**页签单独维护工作流的 `prompt.md`，含输入参数说明与整体执行要求。

## 工具与运行能力

工具面板分为三个分区：

- **脚本工具（Python / TS）**：必须按 `tools/<tool-id>/tool.yaml` 的结构放置，脚本文件直接落在 `tools` 根目录会被标为「不合格」。文件树里可区分清单文件与只读预览。
- **MCP HTTP**：填写 ID、名称、描述、HTTP URL、Tools 与 Metadata。当前**只支持 streamable HTTP MCP 服务**，不会再拉起本地 command/stdio 进程。
- **运行能力**：基础工具 baseline，以及是否允许执行脚本、Python 工具与 MCP 等能力开关，决定该工作流在宿主上可用的执行范围。

## 文件页签

「文件」页签是工作流目录的文件树，可直接查看与编辑随工作流发布的文本文件（如规则脚本、说明文档）。它不替代「资源」页签里的任务清单与共享技能管理。

## 怎么确认正在跑的是哪一版

工作流发布时会为**这一个工作流**生成内容版本：把规范化后的 manifest（含提示词、图与配置、工具 schema 与脚本、共享技能正文）做 SHA256。因此：

- 卡片徽章显示 `sha256:<前 12 位>`，悬浮信息里有完整的工作流 SHA256、资源包 SHA256 与资源包发布时间；
- 旧资源没有记录单工作流版本时显示「单工作流版本未记录」，**不会**拿资源包版本冒充工作流版本；
- 同一个资源包重建不会改变工作流版本；只更新 A 工作流也不会改动未选中的 B 工作流。

徽章来自**发布包**，不是编辑器里的草稿状态。重新发布或回滚后刷新页面即可看到徽章变化。需要严格对账时请以完整的 SHA256 为准，短徽章仅用于展示。

## 说明

后台编辑能力会随工作流使用情况持续完善。若入口地址、名称或部署方式调整，请同步更新本页内容。
