Gumloop 功能规格 - Human-in-the-Loop

初始上下文

1. 概览

背景

v10.0.0 之前，Gumloop 已经建好了 Agent 的所有核心能力——工具调用（MCP 生态 60+ 集成）、子代理编排（Subagents）、知识系统（Skills）、自我进化（Reflections）、对外分发（Hosted Pages、Email Inboxes）。但缺少一个关键的控制层：企业凭什么信任 Agent 自主执行？

这个缺失不是理论问题。生产环境中 Agent 的实际风险场景：

场景	风险	后果
Agent 发邮件给客户	内容不当或收件人错误	客户关系受损、合规问题
Agent 删除数据库记录	删错表或条件过宽	数据丢失、业务中断
Agent 创建 GitHub PR	代码质量不达标	CI 污染、安全漏洞
Agent 遇到歧义时猜测	假设错误导致后续全错	结果不可靠、需人工返工

HITL 通过三层递进控制回答信任问题。核心设计哲学：「读操作自由，写操作审批，高风险操作条件审批」。

Gumloop 由此形成完整的 Agent 控制矩阵：

┌──────────────────────────────────────────────────────────────────────┐
│                    Gumloop Agent 控制矩阵                              │
├──────────────────┬───────────────────┬───────────────────────────────┤
│  事前约束层        │  事中审批层 (HITL)  │  事后审计层                  │
│  (pre-execution)  │  (mid-execution)   │  (post-execution)            │
├──────────────────┼───────────────────┼───────────────────────────────┤
│  App Policies     │  Approval Settings │  Audit Logs                  │
│  Tool Restrictions│  Per-Tool Control  │  Activity History            │
│  Rate Limits      │  App Rules (CEL)   │  Evaluations                 │
│                   │  Ask Human         │  Reflections 分析            │
│  "规定能做什么"     │  "审批该不该做"     │  "检查做了什么"              │
└──────────────────┴───────────────────┴───────────────────────────────┘

目标

1. 建立生产级信任：让企业可以在关键操作上要求人工审批，Agent 无法绕过
2. 渐进式控制粒度：从简单的「全部审批」到参数条件级的「仅当 X 条件时审批」——按风险偏好选择
3. 审批体验无摩擦：多渠道 + 键盘快捷键 + 结构化选项——审批不应成为瓶颈
4. Agent 主动求助：不仅在「该不该做」时暂停，也能在「不知道该怎么做」时提问

2. 核心机制 [文档已验证]

三层控制体系

┌─────────────────────────────────────────────────────────────────────┐
│                  HITL 三层递进控制架构                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Layer 1 — App 级审批模式                                           │
│   ┌───────────────────────────────────────────────────────────────┐ │
│   │  Always allow  │  Ask each time  │  Ask for writes/deletes  │ │
│   │  (默认全部放行)  │  (每次都要审批)    │  (读自由/写审批) ⭐推荐    │ │
│   │                │                  │                          │ │
│   │   Custom ──────────────────────────────────────────▶ L2      │ │
│   └───────────────────────────────────────────────────────────────┘ │
│                              │                                       │
│                              ▼                                       │
│   Layer 2 — Per-Tool 独立控制（Custom 模式）                          │
│   ┌───────────────────────────────────────────────────────────────┐ │
│   │  工具按风险分组：                                                │ │
│   │  Read-only Tools           Write/Delete Tools                 │ │
│   │  ✓ Always allow            ✋ Ask each time                   │ │
│   │  ✋ Ask each time           🚫 Never allow                    │ │
│   │  🚫 Never allow            ✓ Always allow                    │ │
│   └───────────────────────────────────────────────────────────────┘ │
│                              │                                       │
│                              ▼                                       │
│   Layer 3 — App Rules 参数条件审批（CEL 表达式）                       │
│   ┌───────────────────────────────────────────────────────────────┐ │
│   │  "收件人 ∉ 公司域 → 审批"                                       │ │
│   │  → CEL: recipient.email_domain != "mycompany.com"              │ │
│   │  "删除 >100 条 → 审批"                                         │ │
│   │  → CEL: operation == "delete" && affected_rows > 100           │ │
│   └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

审批模式详解

Always allow — 默认。Agent 可使用该 App 的所有工具，无需审批。适合内部低风险工具

Ask each time — 每个工具调用都需要人工批准。最安全但审批成本最高

Ask for writes/deletes ⭐ 推荐默认 — 只读操作自动通过，写入/删除操作需要审批。平衡自主性和安全性——读不需要审批（低风险），写需要审批（有后果）。适合 90% 的生产场景

Custom — 进入 Layer 2，对每个工具独立设置

Per-Tool 控制

状态	图标	含义
Always allow	✓	无需审批，自动执行
Ask each time	✋	每次调用都需要审批
Never allow	🚫	完全禁止使用该工具

工具自动按风险分组：Read-only Tools / Write-Delete Tools。每组可统一设置也可单独调整。

App Rules（参数条件审批） [关键差异化]

将审批从「工具级别」细化到「参数条件级别」。Rule = CEL 表达式 + 审批要求。

实例：recipient.email_domain != "mycompany.com"（收件人不在公司域需要审批）、action == "refund" && amount > 10000（>$10K 退款需要审批）

创建方式：手动编写 CEL 表达式，或 Agent 通过 NL→CEL 翻译辅助创建。

Ask Human — Agent 主动提问

与工具审批不同，Ask Human 解决「Agent 不知道该怎么做」的问题。Agent 暂停并展示结构化问题（含预设选项），用户选择后从暂停处继续。

审批通知渠道

渠道	体验	适用场景
In-App 通知卡片	应用内弹窗，展示完整上下文	正在使用 Gumloop
Slack DM	消息直接送达，可在 Slack 中 Approve/Reject	异步场景、移动端
聊天线程内	审批提示出现在对话中	实时对话

拒绝后行为 [关键设计]

Agent 被拒后不重试同一操作，而是：(1) 确认拒绝 (2) 寻找替代路径 (3) 无法继续时向用户说明。这防止了 Agent 死循环。

3. 功能需求

模块 A — App 级审批配置

ID	触发场景	系统行为	优先级
A1	管理员为 App 选择审批模式	提供四种模式。切换即时生效	P0
A2	选择 Ask for writes/deletes	系统识别 Read/Write-Delete 分组，读自动放行、写进入审批	P0
A3	选择 Custom 模式	展开 Per-Tool 控制面板	P0

模块 B — Per-Tool 独立控制

ID	触发场景	系统行为	优先级
B1	管理员查看工具列表	按风险分组展示，每个工具显示当前审批状态图标	P0
B2	管理员切换工具状态	即时切换 ✓/✋/🚫	P0
B3	批量设置整组工具	一键将某风险组全部工具设为同一状态	P1

模块 C — App Rules

ID	触发场景	系统行为	优先级
C1	管理员手动创建 CEL 规则	提供 CEL 编辑器和参数预览，保存后立即生效	P1
C2	Agent 通过对话创建规则	NL→CEL 翻译，生成的规则进入待审核状态	P2
C3	工具调用触发 CEL 条件	评估表达式，匹配则暂停并发送审批请求	P0

模块 D — 审批请求与响应

ID	触发场景	系统行为	优先级
D1	Agent 调用需审批的工具	暂停执行，生成审批卡片（工具名+意图+参数），推送至所有已配置渠道	P0
D2	用户点击 Approve	Agent 从暂停处继续。⌘+Enter 快速批准	P0
D3	用户点击 Reject	Agent 确认拒绝，调整方法。不重试同一操作	P0
D4	审批请求超时	保持在暂停状态直到响应，不自动超时通过	P1

模块 E — Ask Human

ID	触发场景	系统行为	优先级
E1	Agent 遇到歧义	暂停并生成结构化问题卡片（问题+预设选项+自定义输入）	P0
E2	用户选择/输入	Agent 接收值，从暂停处继续	P0

模块 F — 通知渠道与审计

ID	触发场景	系统行为	优先级
F1	用户连接 Slack	审批请求自动同时发送至 Slack DM	P0
F2	所有审批事件	记录到 Audit Logs：谁、什么时间、哪个工具、什么参数、结果	P1
F3	权限校验	仅 Owner/Editor 可配置 HITL 设置	P0

4. 用户场景

5. 竞争分析

竞品	功能/行为	优势	劣势
Temporal HITL	工作流级信号审批	持久化引擎，适合长流程	信号粒度——审批整个信号而非具体工具。无 Agent 主动提问
Cursor Approve	IDE 内文件修改 Accept/Reject	Diff 视图直接审批	仅限文件修改——不是通用工具审批框架。无 Slack 渠道
OpenAI Codex CLI Approvals	CLI 命令执行前 y/n prompt	极简	无层级、无条件规则、无多渠道。不支持异步审批
Claude Code Permissions	工具调用权限（allow/deny/ask）	细粒度，可针对每个工具路径	限于 CLI/IDE。无 Slack。无条件规则
Zapier Approvals	Workflow 中拖拽审批节点	简单易用	审批硬编码在流程中。Agent 不能主动请求审批

关键洞察

1. 「Ask for writes/deletes」是战略性默认：让 HITL 从「全部审批」（太烦）和「全部自动」（太危险）的二元对立中找到第三条路。这是 Gumloop 的产品哲学声明——Agent 应该自由地「看」但谨慎地「动」
2. Slack 异步审批覆盖移动场景：绝大多数 HITL 方案只能在操作发生的同一界面内审批。Slack DM 让用户在手机上处理审批——对长时间运行的 Agent 任务至关重要
3. Ask Human 解决不同问题：工具审批是「把关」，Ask Human 是「求助」。两者覆盖 Agent 执行中两类完全不同的人类介入需求
4. HITL + App Policies 构成双层安全模型：Policies 设硬护栏（Agent 无法绕过），HITL 设软检查点（Agent 可以执行但需批准）——互补不替代

6. 遥测

漏斗阶段	事件名称	触发条件	指标/KPI	优先级
采用	hitl_app_mode_set	为 App 设置审批模式	各模式分布占比	P0
采用	hitl_app_rule_created	创建 CEL 规则	规则数/App	P1
使用	hitl_approval_requested	发送审批请求	请求数/日	P0
使用	hitl_approval_approved	批准请求	通过率	P0
使用	hitl_approval_rejected	拒绝请求	拒绝率	P0
使用	hitl_ask_human_triggered	Agent 调用 Ask Human	触发次数/日	P1
质量	hitl_rejection_adapt_success	被拒后成功找到替代方案	调整成功率	P0
质量	hitl_approval_response_time	审批请求到响应的时间	P50/P95 延迟	P1
留存	hitl_slack_connected	连接 Slack 渠道	Slack 连接率	P1

7. 未来演进方向

阶段	时间线	里程碑	状态
Phase 1 — 核心 HITL	v10.0.0	三层控制 + Per-Tool + App Rules + Ask Human + 多渠道	已发布
Phase 2 — 智能审批	v10.x	审批风险评分、批量审批、基于历史模式的审批建议	规划中
Phase 3 — 组织级审批	v11.x	团队审批策略模板、审批委托/升级、审批 SLA	探索中
Phase 4 — 预测式干预	远期	规划阶段预测高风险操作并预审批、自适应审批关闭	探索中

关键演进判断

1. CEL 的用户门槛：CEL 对工程师友好但对非技术管理员太高。NL→CEL 翻译如果准确则解决此问题；不准确则信任崩塌——该审批的没审批
2. 智能审批可能适得其反：「你通常批准此类操作」会导致不假思索点 Approve——需要比常规产品更谨慎地设计
3. 审批委托是自然延伸：当前 HITL 是单人的。团队中审批人可能在开会/休假，委托是「单人审批→团队审批能力」的升级