企业官网建设流程全解析

如何在 PenguinHarness 中用好工具审批：4 种审批模式保障 Agent 安全执行

【免费下载链接】penguin-harness🐧 Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness

PenguinHarness 是一个面向自改进 Agent（RSI）的统一开发平台，它的工具审批机制让每一次 Agent 调用工具前都经过一道安全关卡。无论你在聊天界面、命令行还是嵌入自己的程序，都可以用 4 种审批模式——全部放行、全部拒绝、放行只读、总是询问——精确控制 Agent 能做什么、何时需要你点头。本文面向新手，带你快速掌握这套 Agent 安全执行保障机制。

为什么 Agent 需要工具审批 🔒

Agent 的核心能力来自工具：执行 shell 命令、读写文件、启动子 Agent……一旦放任不管，一个判断失误的模型就可能改坏你的项目。

PenguinHarness 的设计原则是：每个完整的工具调用（tool_call）恰好触发一次审批决策。这个决策会被记录为一条approval_decision事件，写入 Trace 审计日志——事后你可以完整回溯「谁批准了什么、谁拒绝了什么」。审批回调的接口定义在 ApproveFn，服务器端的具体实现见 approvals.ts。

对新手来说，你只需要记住一句话：模式决定「问不问你」，你的决定决定「做不做」。

4 种审批模式速览：一张表看懂区别

几个关键细节：

• 每次决策都会重新读取当前模式，所以 Session 进行中随时切换审批模式，立即生效，不用重开对话；
• 命令行里y或回车即批准，n即拒绝；
• 子 Agent 会继承父会话的审批模式，你只管一个开关，全链路都受控。

怎么选：按场景匹配你的审批模式 🧭

• 首次使用、建立信任：选always-ask（总是询问）。每一次rm、每一次写文件都由你亲自把关，是学习 Agent 行为方式最快的途径。
• 日常开发、追求省心：选read-only（放行只读）。读代码、查日志自动通过，只有真正会改动内容的操作（执行命令、编辑文件、启动子 Agent）才弹确认——效率与安全兼得。
• 无人值守跑任务：选allow-all（全部放行）。配合后台任务，Agent 可以整夜无人值守地工作；建议同时配置下文提到的命令策略作为兜底护栏。
• 出事了先止血：切到deny-all（全部拒绝），Agent 立即「只说不做」。

在哪里设置审批模式？

Web App（最常用）：新建对话时，输入框上方就有审批模式选择器，四种模式任选。工具调用需要审批时，对话里会直接出现允许和拒绝按钮；子 Agent 有等待审批的调用时，对应行会亮起琥珀色圆点提醒。详见 Web App 对话文档。

CLI：用--approve <mode>指定，例如--approve read-only；不指定时默认为allow-all。在 Agent 内部创建的会话还会自动继承调用方会话的模式。详见 CLI 文档的审批模式一节。

SDK 嵌入：每次session.run时传入approve回调；若不提供，引擎默认拒绝一切调用——这是一个保守而安全的设计，无人值守时不会有任何操作被误批准。

被拒绝之后会发生什么？

被拒绝的调用不会让 Agent「卡死」，它会收到一条合成的aborted输出，并根据拒绝方不同看到不同文案，从而知道该换条路还是就此打住：

也就是说，「策略禁止」和「人为取消」在 Agent 眼中是两回事，它能据此做出正确反应，而不是把你的策略否决误解成一次普通取消。

审计留痕：Trace 里能看到每一次审批 ✅

每一次审批决策都会以approval_decision事件写入 Trace，与工具调用一一对应：策略否决会明确记为forbidden。这意味着 Trace 天然就是一份完整的安全审计记录——出了问题，你可以逐条查看：哪次调用被谁拒绝、为什么。审批相关的完整文档见 工具与审批。

再加一道防线：命令策略与 pre-tool-use 钩子

审批模式之上，PenguinHarness 还有两层更硬的护栏：

1. 命令策略：Project 级的一组正则拒绝规则（如禁止rm -rf、禁止--force推送），先于审批模式生效——即使是allow-all模式，命中规则也会直接拒绝。它存放在 Project 配置中，Agent 自己改不了。详见 配置参考。
2. pre-tool-use 钩子：在审批回调之前运行，可以直接allow或deny某次调用；但命令策略的否决优先级最高，钩子放行也挡不住策略拦截。

快速上手：3 步开始使用工具审批

1. 获取项目并启动 PenguinHarness（需要克隆仓库时使用git clone https://gitcode.com/gh_mirrors/pe/penguin-harness）；
2. 打开 Web App，新建对话，在输入框上方选择审批模式——新手推荐放行只读；
3. 发送消息，观察工具卡片上的允许/拒绝按钮；任务跑偏时随时切换模式，立刻生效。

常见问题 FAQ

Q：切换审批模式需要重开对话吗？不需要。模式在每次决策时从数据库重读，改动即刻生效。

Q：为什么我设了allow-all还有调用被拒绝？多半是命中了 Project 的命令策略（forbidden优先级最高），或某个 pre-tool-use 钩子返回了deny。看 Trace 里的approval_decision事件即可确认是谁拒绝的。

Q：子 Agent 的审批怎么管？子会话继承父会话的审批模式，待审批请求会直接呈现给你；父任务结束时也不会自动拒绝子 Agent 的待审批调用，卡片会一直保留到你作出决定。

总结：PenguinHarness 的 4 种审批模式 + 命令策略 + 钩子 + Trace 审计，构成了一套层层递进的 Agent 安全执行体系。新手从「总是询问」起步，熟悉后切到「放行只读」，高风险场景再叠加命令策略——安全与效率，你可以按自己的节奏来拿捏。

【免费下载链接】penguin-harness🐧 Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness