企业官网建设流程全解析

Executor 人机协作实战：审批流、执行暂停与Resume机制完整指南

【免费下载链接】executorThe missing integration layer for AI agents. Let them call any OpenAPI / MCP / GraphQL / custom js functions in secure environment.项目地址: https://gitcode.com/gh_mirrors/executor14/executor

Executor 是 AI Agent 的"缺失集成层"——让 AI 代理在安全环境中调用任意 OpenAPI、MCP、GraphQL 或自定义 JS 函数。本文带你吃透它的三大安全机制：审批流（Approval Flow）、执行暂停（Pause）与 Resume 恢复机制，掌握"让 AI 干活、人来把关"的人机协作完整姿势 🎯

为什么 AI Agent 需要"刹车系统"？

AI Agent 很能干，但它可能会：

• ❌ 误删一条生产数据
• ❌ 用错账号发起一笔支付
• ❌ 在未经确认时发送一封对外消息

Executor 的答案不是"限制 AI 的能力"，而是给每个工具调用加一道人工确认关卡：

策略（Policy）决定哪些调用必须等人点头；需要点头的调用会暂停执行；人的决定再通过 Resume 机制送回，执行要么继续、要么终止。

这套机制对新手最友好的地方在于：你不需要写任何安全代码，只需配置策略，审批流自动生效。

核心概念一：Policy 审批策略的三级开关

在 Executor 中，每个工具调用都受策略控制，只有三种状态，简单直接：

策略有合理默认值：例如 OpenAPI 规范中的只读GET操作默认放行，写操作可设为"需审批"，且可以随时对任意工具微调。策略的完整说明见 apps/docs/concepts/policies.mdx。

核心概念二：执行暂停（Pause）是如何发生的

当 Agent 调用了一个"需审批"的工具，Executor 的执行引擎不会继续跑下去，而是把这次执行冻结成一个暂停记录（PausedExecution），并把控制权交还给人类。

引擎在 packages/core/execution/src/engine.ts 中实现了这套暂停/恢复语义，对外暴露的关键能力包括：

• executeWithPause：执行代码，遇到审批关卡时返回暂停状态；
• getPausedExecution：查询某个暂停中执行的详情；
• pausedExecutionCount：统计当前挂起的执行数量；
• resume：用人类的决定恢复或终止执行。

暂停时，Executor 会给 Agent 返回一份"人话说明书"，包含：

• 📋待审批消息（message）：说明这次调用是什么；
• 🔗交互信息：是打开某个 URL 完成浏览器流程，还是填写表单，或仅做模型侧确认；
• ⏰截止时间（resumeDeadline）：审批窗口还有多久关闭；
• 🔑executionId：恢复执行时的唯一凭据。

这样 Agent（或前端界面）就清楚知道"该让谁、在哪里、做什么"。

核心概念三：Resume 机制——人类的三种决定

审批结束后，Executor 通过 Resume 响应恢复执行，ResumeResponse只有三种动作（定义见 packages/core/execution/src/engine.ts）：

accept → 批准，执行继续，工具真正被调用 decline → 拒绝，执行终止 cancel → 取消，执行终止

三个关键安全细节值得新手了解：

1. 审批窗口有时效：待审批记录默认15 分钟有效（见 packages/core/sdk/src/pending-approval.ts）。人看参数预览、做决定需要的是分钟级时间，超过窗口后记录视为失效，用户重新触发即可——因为此时什么都没执行，所以失败也安全。
2. 一次批准只授权一次调用：审批记录是"单次消耗"的，恢复时被读取并删除。同一次批准无法被重放执行第二次。
3. 批准的是"服务器生成的调用"：恢复时执行的代码是服务端构建的最终版本，而非任何前端发来的字符串，暂停期间没有人能偷偷扩大授权范围。

三种审批模式：browser / model / native

Executor 支持三种 elicitation 模式（读取逻辑见 packages/hosts/mcp/src/browser-approval.ts），决定"人类在哪里做决定"：

🌐 browser 模式（浏览器审批）

适合连接了图形界面的场景。被门禁的工具调用暂停后，Executor 返回一个approvalUrl，指向控制台的/resume/<executionId>审批页。你在浏览器里点"批准"或"拒绝"，决定被记录下来，Agent 的 resume 调用随即消费该结果并返回执行产出。

🤖 model 模式（模型侧确认，默认）

没有浏览器界面时的默认方式：Agent 自己转述审批请求给你（"我准备调用 X 工具，参数是 Y，是否批准？"），你口头同意后，Agent 直接调用 resume 工具，action传accept、decline或cancel。

📱 native 模式（客户端原生弹窗）

由支持 MCP 原生 elicitation 协议的客户端（如桌面端）直接弹出确认框，体验最流畅。

一个完整审批流的六步走

把前面的概念串起来，一次审批协作是这样发生的：

1. 配置策略：把敏感工具设为"需审批"（默认策略通常已帮你做好）；
2. Agent 发起调用：execute工具运行沙箱代码，命中审批关卡；
3. 执行暂停：引擎挂起执行，返回executionId、审批消息与截止时间；
4. 人类做决定：在浏览器审批页、聊天界面或原生弹窗中选择 accept / decline / cancel；
5. Resume 恢复：决定被送回引擎——批准则工具真正执行，拒绝则执行干净终止；
6. 结果返回 Agent：执行产出交还给 AI，任务继续推进 ✅

这套流程在本地、桌面、自托管与云环境通用：同一实例内的暂停/恢复直接走引擎内存中的挂起纤维；在按请求创建新执行器的宿主上，则通过持久化待审批存储（PendingApprovalStore）记录"待执行的最终调用"，审批到达后等价地重放，保证任何部署形态下审批都能正确送达。

快速上手：三步体验审批流

🚀 想亲手试试？步骤非常轻：

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/executor14/executor；
2. 启动本地服务：按仓库内 apps/docs/local/cli.mdx 的说明用 CLI 启动本地 Executor，它自带 Web 控制台；
3. 观察暂停与恢复：连接一个需要审批的工具（或直接用控制台里的 Run 面板，它自带 autoApprove 一键批准选项），在控制台观察waiting_for_interaction状态，再到/resume/<executionId>页面完成审批。

相关的端到端测试（本地浏览器审批、暂停后恢复、审批超时）可以直接阅读验证机制：

• 本地浏览器审批全流程：apps/local/src/mcp-browser-resume.test.ts
• 暂停与审批存储：packages/core/sdk/src/pending-approval.ts
• 策略概念文档：apps/docs/concepts/policies.mdx

小结：安全与效率兼得

对新手而言，Executor 的审批流最大的价值是零代码接入：配置好策略，暂停、审批、恢复全部自动发生。AI 负责跑得快，你负责踩得稳——这就是人机协作的正确打开方式。

【免费下载链接】executorThe missing integration layer for AI agents. Let them call any OpenAPI / MCP / GraphQL / custom js functions in secure environment.项目地址: https://gitcode.com/gh_mirrors/executor14/executor