联枢:接口与工具

事件、轮询与定时

由入站事件启动工作流,用轮询代替推送,延时启动下一段,按间隔运行定时任务。

入站事件与事件触发

原系统(HR、OA、ERP 等)把状态变化推送给 Nexus,联枢收到后,让正在等待这个事件的工作流继续,也可以让事件直接启动一个工作流。

登记事件来源

在「接入中心 › 入站事件」里登记来源,接收模块选联枢。主要设置如下:

字段说明
来源编码、接收模块、认证方式来源编码如 hr,推送地址是 /v1/events/<来源编码>。三项创建后都不能修改
认证方式共享密钥(HMAC 签名)、钉钉事件订阅、飞书事件订阅。其余认证方式是给研枢的研发系统 Webhook 用的
允许的事件类型每种类型填「关联键位置」(事件内容里的 JSON Pointer,如 /application_id)和可选的内容 Schema。工作流的等待步骤按「事件类型加关联键」等待
每分钟上限默认 600,超过后返回 429

共享密钥点「生成密钥」,只显示一次,更换后旧密钥立即失效。原系统或转发脚本这样推送:

POST /v1/events/<来源编码>
Content-Type: application/json
X-Nexus-Timestamp: <Unix 秒>
X-Nexus-Nonce: <随机数>
X-Nexus-Signature: v2=<十六进制签名>

{ "event_id": "hr-0001", "type": "hr.approval.finished", "data": { "application_id": "A-1001", "result": "approved" } }
  • 签名是对 <时间戳>.<随机数>.<请求体原文> 计算 HMAC-SHA256,密钥是共享密钥。时间戳与核心时间相差超过 5 分钟即拒收,同一随机数在 5 分钟内只接受一次。
  • 请求体最大 64KB,只含 event_id、type、data 和可选的 occurred_at。data 必须在关联键位置上有一个字符串或数字。
  • 返回 202 表示已写入收件表。同一个 event_id 重复推送会识别为重复,不再处理。401 表示来源不存在、已停用或签名不对,422 表示事件类型不被允许、内容不符合 Schema 或缺少关联键,429 表示超过每分钟上限。

联枢按「来源加 event_id」去重,只匹配已经在等待的运行:事件先到、运行后到时不会匹配上。最近 7 天的事件(最多 1000 条)保留在联枢里供诊断。每收到一条非重复事件,「操作审计」里写一条「接收入站事件」;核心拒收或忽略的事件只在控制台的「审计日志」里。钉钉和飞书的事件订阅按平台公开文档实现,用按文档格式构造的请求测试过,没有在真实的钉钉或飞书租户上验证。

事件触发

打开「接口与工具(联枢) › 编排与触发 › 事件触发」,点「新增触发规则」,配置「某来源的某类事件启动某工作流」:

字段说明
事件来源编码、事件类型来源是「入站事件」里登记的,类型如 hr.employee.hired。
启动的工作流只能选已启用的工作流。
服务 Agent 编号以哪个单位服务 Agent 的身份运行,不能是个人 Agent。它须持有工作流的运行授权和各步工具的调用授权,并有有效的 Key。
输入映射「来源:事件内容位置」到「目标:工作流输入字段」,两边都是 JSON Pointer,来源留空为整个事件内容。
启用勾选后收到匹配的事件即启动工作流。

保存时和每次触发时,联枢都会向核心核对服务 Agent 的授权。保存即确认规则针对工作流的当前版本,工作流修改后,要重新保存规则,否则不再触发。触发规则不批准任何东西:含「需要他人审批」工具的计划,以服务 Agent 为发起者申请审批,在审批页批准后自动运行。含「需要本人确认」工具的工作流不能保存为触发规则,因为单位服务 Agent 没有本人。要全自动执行,就把相关工具设为「授权后直接调用」。触发的运行会记下来源编码和事件 ID。没能启动时,审计里会有一条「事件未能触发工作流」记录(只含规则编号)。

联枢事件触发页面
「接口与工具(联枢) › 编排与触发 › 事件触发」页面。截图来自测试环境,数据为示例。

轮询与延时启动

轮询代替推送

原系统改不动、只能查询时,用「接口与工具(联枢) › 编排与触发 › 轮询代替推送」。联枢定时调用它的只读查询工具,把条目状态的变化转换为同样的事件,事件触发和「等待事件」照常生效。点「新增轮询」填写:

字段说明
查询工具、查询参数只能选只读且授权后直接调用的工具,参数是完整的 JSON 对象,须符合工具契约。
服务 Agent 编号须持有查询工具的调用授权,每次运行前向核心核验。不在职、没授权或核心不可达时,本次不运行。
间隔(分钟)1 到 1440。
列表位置、关联键、状态JSON Pointer:结果里的列表位置(留空表示整个结果)、条目里的关联键、条目里的状态(留空表示整个条目)。
事件来源编码、默认事件类型、按状态指定类型可以把某个状态映射成特定事件类型,指定后只有这些状态发事件。
首次运行只建立基线默认开启:第一次只记录现有条目,不发事件。

轮询每次最多读取 500 条、发出 100 个事件,不翻页,只适合「最近变化」或「待处理」这类有界列表。失败时下次运行的等待时间按「间隔乘以 2 的 N 次方」递增(N 为连续失败次数),最长 6 小时(间隔本身更长时取间隔),成功后清零,不会自动停用。两次轮询之间的中间状态会丢失,事件时间是轮询时间。脱敏后的值不宜作为关联键或状态。每个联枢最多 50 条轮询。许可证未生效时,轮询不运行。

延时启动下一段

原系统推送不了衔接事件、流程以月计时,可以在本段末尾加一步「延时启动下一段」,设置「下一段工作流」和「启动时间」(「本步之后过一段时间」,延时 1 到 365 天;或「到某个时间」,最晚 1 年内)。这一步的参数绑定生成下一段的输入。

  • 本次运行不等待,执行到这一步就登记一次启动并继续,登记保存在联枢里,重启后仍在。各段不能首尾相接成环,保存时会拒绝并写出整条循环。
  • 到时,联枢以本次运行的 Agent 身份,按核心当时的授权和当时的配置重新生成计划。全部步骤都是「授权后直接调用」的,直接运行;含需要本人确认或他人审批工具的,进入待审批,有效期 1 天,批准后自动运行。授权不足、工作流已停用或输入不合契约时不启动,原因显示在「延时启动」记录里,审计里有一条「下一段未能启动」。
  • 在「接口与工具(联枢) › 编排与触发 › 延时启动」可以查看已登记的启动、取消尚未启动的。最多 1000 个待启动,已结束的保留 30 天。

这是给存量系统的后期适配办法。能由原系统推送事件时,请改用事件触发。含这一步和其他等待步骤的工作流,都不能设为定时任务。

定时任务

打开「接口与工具(联枢) › 编排与触发 › 定时任务」,点「新增定时任务」,按间隔运行一个只读的调用模板或只读的工作流。许可证未生效时,定时任务不运行。

联枢定时任务页面
「接口与工具(联枢) › 编排与触发 › 定时任务」页面。截图来自测试环境,数据为示例。
字段说明
名称、运行对象运行对象选「调用模板」或「工作流」。
工作流输入(JSON 对象)运行工作流时填写,须符合工作流的输入 Schema。模板运行它预置的参数,所以预置参数必须是完整的。
运行间隔(分钟)5 到 10080(7 天)。
启用勾选后开始按间隔运行。
  • 只运行只读内容:模板的工具、工作流的每一步工具都必须是读操作且为「授权后直接调用」,保存时和每次运行前都检查,写操作一律拒绝。含等待步骤的工作流不能设为定时任务。
  • 以谁的身份执行:以最后保存(或恢复)它的管理员身份。每次运行前,联枢向核心确认这个人仍是活跃的人员,否则这次不执行,记为「未执行」。联枢没有接入核心时,定时任务从不执行。运行走与 Agent 调用相同的执行链,限额按这位管理员计,结果脱敏,也写调用日志。
  • 失败与恢复:连续 3 次未成功(失败、限额拒绝或身份无法核验)自动暂停。点「恢复」清零计数,恢复的人成为新的运行身份。「立即运行」以当前控制台会话的管理员执行,不影响计时和失败计数。
  • 运行记录可在页面查看,输出已脱敏,最多保留 4000 个字符。

进一步交流

带一件正在做的事来聊

告诉我们你想让智能体接哪一类系统。我们在演示环境里把这件事走一遍,再一起判断合不合适。