SuperAPI AI 工具集

velt-approval-engine-best-practices

通用与其它

查看项目

更新于 10-16 08:38

技能介绍

本技能是 Velt Approval Engine 的实现指南。该引擎是用于多步骤智能体加人工审批流程的声明式工作流运行时。

用途:在编写审批工作流定义、派发执行、记录决策、构建 Webhook 接收端、配置仲裁组与 SLA、执行管理级操作或排查 INVALID_ARGUMENT 校验错误时参考。仅覆盖 Approval Engine 领域,通用 Velt REST API 模式见 velt-rest-apis-best-practices。

主要能力与内容: 一、概念(高优先级):工作流定义由节点、边、组与循环构成;节点分为 agent 与 human;reviewerEmails 支持 0–50 个并显示在步骤输出中;commentBody 存于输出,引擎不会自动创建标注;onReject 有 routeToNodeId 与 loopBack 两种形式;严格模式下每个 human 节点需有 onReject 或属于循环;顶层 loops[] 含 loopId、entryNodeId、bodyNodeIds(1–50)、maxIterations(1–20)与 previousAttempts;默认循环判定 decision == 'reject' && rejectorMandatory == true 在使用 /steps/resolve 的 reject 动作时不会触发,应改用 recordReviewerDecision;边支持 when 表达式;组支持 waitAll、cancelOnQuorum、joinOnQuorum 仲裁策略。 二、REST 端点(高优先级):基础包括鉴权头、请求/响应封装与规范错误码(含 DEADLINE_EXCEEDED);定义类 5 个端点(create/update/get/list/delete,update 带 ifVersion 乐观锁),含 25 条 linter 规则、按级别必填字段(organization 作用域需 organizationId,document 作用域需两者)、服务端命名空间 ID 注意事项与 triggers 元数据说明;执行类 5 个端点(dispatch 需 idempotencyKey 与 webhook 配置、get、list、cancel、getEvents 支持 sinceSeq 恢复),v1 列表不支持按 organizationId/documentId 过滤;步骤类 4 个端点:recordReviewerDecision(未知审阅人会被静默接受为未知响应者)、recordAgentResolution、cancel 与 resolve(均要求 actorId,1–256 字符;resolve 支持强制通过与审阅人动作,reject 动作不填充 rejectorMandatory);对象视图给出 ExecutionView、StepView 等 TypeScript 形状。 三、Webhook(高优先级):基于原始字节的 HMAC-SHA256 签名验证、投递头、重试计划、事件类型目录(含 loop.iteration-started 与 loop.exhausted)、至少一次投递的幂等性;入站处理端点为外部系统直接 POST 原始 JSON(无 data 封装),使用 bearer token、签名回调令牌、按来源限流、请求体大小限制与 SSRF 防护。

使用方式:先读 AGENTS.md 压缩索引,再按需查阅 rules/shared 下各规则文件(concepts-workflow-model、rest-foundations、rest-definitions、rest-executions、rest-steps、rest-object-views、webhooks-delivery、webhooks-inbound-handler),每个文件含原因说明、请求/响应示例、常见陷阱与验证清单。派发时始终携带 idempotencyKey,webhookUrl 与 webhookSecret 需成对配置。

限制与适用场景:以上为资料明确内容,具体价格、平台支持与部署方式暂未提供。