企业官网建设流程全解析

HumanLayer 高价值函数调用的人类监督机制：从 Function Stakes 到 Autonomous Agents 的确定性兜底

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer

导读

本文以仓库根目录的 humanlayer.md 为主线，系统讲解 HumanLayer 的核心设计思想：为什么高价值（high-stakes）的 LLM 函数调用必须有人类监督，以及如何通过"确定性（deterministic）"机制把人类审批内建到工具本身，从而为 Gen 3 自主 Agent（Autonomous Agents）的 "Outer Loop" 提供安全底座。文中所有概念均结合当前仓库中 hld（HumanLayer Daemon）的审批管理器、JSON-RPC 协议、事件总线以及 claudecode-go 的 MCP 集成等源码进行印证，读完后你将理解 HumanLayer 的函数风险分级框架、审批生命周期设计，以及下一代自主 Agent 对"人类在环"基础设施的硬性需求。

说明：仓库根目录 README.md 与 humanlayer.md 均明确提示，早期的 HumanLayer SDK 已在 #646 中被移除，当前仓库中代码已大幅转向以 hld 守护进程 + CodeLayer 桌面端为代表的重构形态。本文聚焦的仍是该文档确立的、并被当前实现继承的核心概念体系。

为什么需要 HumanLayer：LLM 值得信任，但不能在无人监督下操作高风险函数

函数与工具（function calling / tool calling）是 Agentic Workflow 的关键一环，它让 LLM 能够与外部世界产生有意义的交互，并自动化大范围的高价值工作。准确、正确的函数调用，是 AI Agent 完成预约、与客户互动、管理账单信息、编写并执行代码等真实任务的前提。

然而，人类能想象到的"最有用"的函数，往往也是最危险的。例如，一个 AI 数据库管理员若能持续调优和重构 SQL 数据库会带来巨大价值，但绝大多数团队绝不会让 LLM 对生产数据库执行任意 SQL——连人类通常都没有这个权限。HumanLayer 文档对这一点给出了一个核心论断：

即使拥有最先进的 Agentic 推理和 prompt 路由，LLM 在可靠性上仍不足以在无人监督的情况下被授予高价值函数的使用权。

高价值函数恰恰是自动化人类工作流中价值最高、影响最大的部分，但也是"90% 的准确率不可接受"的部分。当前 LLM 的幻觉倾向、以及生成明显带有"AI 味"的低质量文本，都会进一步削弱可靠性。团队越早能让 Agent 以高质量输入可靠、安全地调用这些工具，就能越早收获巨大的自动化收益。

HumanLayer 的答案是：提供一组工具，确定性地保证高价值函数调用的人类监督。即使 LLM 出错或产生幻觉，HumanLayer 也已经"烘焙"进工具/函数本身，从而保证始终有人类在环（human in the loop）——监督不是概率性的、不是"建议性的"，而是机制上强制的。

函数风险分级：界定什么是 "High Stakes"

为了更好地定义"高价值（high stakes）"的含义，HumanLayer 文档给出了一个从低到高的函数风险分级框架：

• 低风险（Low Stakes）：对公共数据的只读访问（如搜索 Wikipedia、访问公共 API 与数据集）
• 低风险（Low Stakes）：与 Agent 作者沟通（如工程师授权 Agent 通过 Slack 私信汇报进度）
• 中风险（Medium Stakes）：对私有数据的只读访问（如读取邮件、访问日历、查询 CRM）
• 中风险（Medium Stakes）：在严格规则下沟通（如按一串硬编码的邮件模板依次发送）
• 高风险（High Stakes）：以我或公司名义对外沟通（如发送邮件、发布 Slack 消息、发布社交/博客内容）
• 高风险（High Stakes）：对私有数据的写访问（如更新 CRM 记录、修改功能开关、更新账单信息）

风险分级的直觉很简单：权限越大、越不可逆、越代表"身份"的操作，越需要人类把关。以"发送邮件"为例，从"按模板发送"到"以公司名义对外发布"，看似只是同一个动作，风险却从"中"跃升到"高"——前者可以被规则约束，后者则直接与公司声誉和法律责任挂钩。

当前仓库的 hld 实现把这个分级思想落到了具体工程上：审批（Approval）成为会话生命周期中的一等公民，任何被标记为需要审批的工具调用都会进入pending状态，等待人工approve或deny后再继续执行。

确定性人类监督：从 require_approval / human_as_tool 到审批基础设施

HumanLayer 文档点名的两大核心工具原语是require_approval（要求审批）与human_as_tool（把人类当作工具），前者用于"把审批装饰器包在高风险函数上"，后者用于"让 Agent 在需要时主动向人类发起双向沟通"。下图展示了require_approval装饰器包裹"以我名义对外沟通"类函数的效果：

HumanLayer 提供一组工具，确定性地保证高价值函数调用的人类监督。

虽然上述两个 Python 装饰器原语随 SDK 一并移除，但其背后的审批生命周期在当前仓库中被完整地继承并工程化，体现在三个层面：

1. 审批管理器（hld/approval）：审批状态的确定性与自动放行策略

hld/approval/manager.go 中的CreateApproval是审批的核心入口：当一次工具调用需要审批时，它会以run_id反查会话、创建一条pending状态的审批记录（ID 形如local-<uuid>），并通过事件总线广播。这里有两个值得注意的"确定性"设计：

• 自动放行是显式策略，而非默认行为：只有会话开启了DangerouslySkipPermissions（含过期时间校验）或针对编辑类工具的AutoAcceptEdits时，审批才会被自动标记为approved，且会写入Auto-accepted (dangerous skip permissions enabled)之类的说明注释。这印证了"默认必须人工审批"的保守原则；
• 审批与工具调用关联是尽力而为但被显式处理：correlateApproval会把审批关联到最近一次未关联的工具调用，失败时只记 warning 而不阻断主流程（见 hld/approval/manager.go 中的日志与注释），保证监督机制本身不会成为系统脆弱点。

审批管理器的接口定义在 hld/approval/types.go：CreateApproval、GetPendingApprovals、ApproveToolCall、DenyToolCall等构成了完整的"创建 → 查询 → 决策"闭环。

2. 审批的 API 面：deny 必须给出理由

在 hld/api/handlers/approvals.go 的DecideApproval中，可以看到决策规则的强约束：

• approve：批准工具调用；
• deny：拒绝时必须附带 comment，否则返回HLD-3001 "comment is required when denying"（400 错误）；
• 对已决策的审批再次决策会返回HLD-3002（ErrAlreadyDecided），审批不存在返回HLD-1002。

这种"拒绝必须留痕"的设计，正是为了让人类监督不仅是门禁，还能为 Agent 提供可追溯的反馈信号——拒绝理由会随事件流回到会话中，成为后续行为的上下文。底层数据层对应的状态枚举（NULL/pending/approved/denied/resolved）与错误定义可参考 hld/PROTOCOL.md 与 hld/store。

3. 事件总线：审批结果的实时分发

hld/bus/events.go 实现的内存事件总线（每个订阅者默认缓冲 100 条事件，慢订阅者的事件会被丢弃并告警）负责把new_approval、approval_resolved、session_status_changed等事件实时推送给订阅方。结合 hld/PROTOCOL.md 中定义的基于 Unix domain socket 的 JSON-RPC 2.0 协议（默认~/.humanlayer/daemon.sock，权限 0600，行分隔 JSON），外部客户端可以订阅审批事件、查询会话状态并下发决策，形成完整的"Agent 调用工具 → 人类审批 → 决策回流"链路。会话状态机（starting/running/completed/failed/waiting_input）中专门有waiting_input状态——当出现 pending 审批时，会话会切换到等待人工输入的状态，这正是"Agent 被确定性暂停等待人类"的直接体现。

下一代范式：自主 Agent 与 "Outer Loop"

Gen 1 → Gen 2 → Gen 3 的演进

HumanLayer 文档用三代演进概括了 LLM 应用的历史脉络，以明确"下一代 Agent"的定位：

• Gen 1：聊天（Chat）——人类发起的问答式界面；
• Gen 2：Agentic 助手（Agentic Assistants）——由框架驱动 prompt 路由、工具调用、思维链与上下文窗口管理，以获得更高的可靠性与功能性。绝大多数工作流由人类以单次"这里有个任务，去完成它"或滚动聊天界面的方式发起；
• Gen 3：自主 Agent（Autonomous Agents）——不再由人类发起，Agent 将活在 "Outer Loop"（外循环）中，使用各种工具和函数持续驱动自己朝目标前进。人类与 Agent 之间的通信由Agent 主动发起，而非人类发起。

Gen 3 自主 Agent 需要在各种任务上征询人类意见，要真正产出有效工作，敏感操作就必须有人类监督。它们需要能够跨多种渠道（chat、email、sms 等）联系一个或多个人类。文档还前瞻性地描述了这类 Agent 对基础设施的硬性要求：

• 即便早期版本的自主 Agent 在技术上仍可能"由人类发起"（例如通过 cron 定时启动），但最优秀的版本将自行管理调度与成本，需要成本检查工具包与类似sleep_until的能力；
• 它们需要运行在能够持久化序列化并在跨数小时甚至数天的工具调用之间恢复Agent 工作流的编排框架中；
• 这些框架需要支持由 "manager LLM" 进行上下文窗口管理，并允许 Agent fork 出子链来处理专业化任务与角色。

HumanLayer 文档曾以 LinkedIn 收件箱助手、客户引导助手等 LangChain 示例作为这类 Outer Loop Agent 的用例（这些./examples/langchain/示例文件已随 SDK 移除）。在当前的 hld 中，这一愿景的落地形态是会话级监督：hld/PROTOCOL.md 中的launchSession/continueSession/getSessionState/Subscribe等方法，以及 hld/session 下的会话管理器（含waiting_input状态、成本/Token 统计字段cost_usd、total_tokens），共同构成了让 Agent 在长时间运行中"可暂停、可恢复、可监督、可计量"的外循环基础设施。

MCP 集成：审批作为 Agent 的工具面

在 claudecode-go/README.md（仓库中的实验性 Go SDK）中可以看到审批与 Agent 工作流集成的具体姿势：通过 MCP 配置注入approvals服务器，并设置PermissionPromptTool: "mcp__approvals__request_permission"，即可让 Claude Code 的权限请求走 HumanLayer 审批通道：

mcpConfig := &claudecode.MCPConfig{ MCPServers: map[string]claudecode.MCPServer{ "approvals": { Command: "npx", Args: []string{"humanlayer", "mcp", "claude_approvals"}, }, }, } session, err := client.Launch(claudecode.SessionConfig{ Query: "Deploy to production", MCPConfig: mcpConfig, PermissionPromptTool: "mcp__approvals__request_permission", AllowedTools: []string{"mcp__approvals__*"}, })

这段代码是"把人类监督内建到工具本身"的直观体现：对 Agent 而言，请求审批只是一个普通的 MCP 工具调用；对人类而言，所有高风险动作都会先经过审批服务器。配合 docs/introduction.mdx 中描述的 CodeLayer 桌面端（当前仓库中对应 humanlayer-wui 前端与 hld 守护进程），审批可以在图形界面中完成，并通过 SSE 事件实时看到 Agent 的执行流。

项目开发规范：TODO 注释体系

仓库遵循一套基于优先级的 TODO 注释标注系统（humanlayer.md 中定义），便于在代码中快速识别问题严重程度：

• TODO(0)：严重（Critical）——绝不合并
• TODO(1)：高（High）——架构缺陷、重大 bug
• TODO(2)：中（Medium）——小 bug、缺失功能
• TODO(3)：低（Low）——打磨、测试、文档
• TODO(4)：需要调查/求证的问题
• PERF：性能优化机会

这套约定可以让你在阅读 hld、humanlayer-wui、packages 等源码时快速定位优先级最高的遗留问题，也方便贡献者按优先级认领工作。

贡献与许可

HumanLayer SDK 与文档是开源的，欢迎以 issue、文档、Pull Request 等形式贡献，详见 CONTRIBUTING.md。仓库中的 HumanLayer SDK 与 CodeLayer 源码基于 Apache 2 License 授权（见 LICENSE）。注意仓库当前处于重构过渡期，README.md 与 humanlayer.md 均提示早期 SDK 代码已大量弃用，新一代体验以 CodeLayer 桌面端（见 docs/introduction.mdx 与 humanlayer-wui/README.md）及 hld 守护进程为主，参与贡献前建议先阅读 CLAUDE.md 与 CONTRIBUTING.md 了解现状。

小结：从概念到工程的确定性监督

HumanLayer 文档的核心主张可以浓缩为一句话：LLM 的高价值函数调用必须被确定性的人类监督所约束，而监督机制应内建在函数/工具本身，而不是依赖 Agent 的"自觉"。在当前仓库中，这一主张落地为完整的工程链路：风险分级指导哪些调用需要审批 → 审批管理器以pending/approved/denied状态机确定性拦截工具调用（hld/approval/manager.go）→ 拒绝必须附带理由以形成可追溯反馈（hld/api/handlers/approvals.go）→ 事件总线与 JSON-RPC 协议把审批状态实时同步给前端与外部订阅者（hld/bus/events.go、hld/PROTOCOL.md）→ 会话进入waiting_input状态等待人工决策，从而支撑 Gen 3 自主 Agent 在 Outer Loop 中长期、安全地运行。

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer