没有 HITL 人工审批的 Agent，rm -rf 他都敢干。

我们现在的 Agent 是完全信任 AI 的，这等于说把一些危险的动作也交给了 AI。

比如说删除一个文件夹。

但真正的 Agent 显然不应该具备这种无限制的权限，在遇到一些危险的操作时候，应该把控制权交给我们人。

于是 HITL，Human-in-the-Loop，人工审批介入出现了。

危险操作执行前，先问一声。

这篇文章会手把手带大家实现完整的 HITL 系统，包括危险策略识别、审批请求格式化、用户交互收集、以及最核心的拦截层设计。

01、为什么 Agent 需要人工审批

先说清楚背景。

PaiCLI 已经有了 ReAct、Plan-and-Execute、Memory、RAG、Multi-Agent，功能挺全的。

但越能干，风险越高。

一个 Agent 在执行任务的时候，可能会：

用 write_file 覆写一个你不想动的文件，用 execute_command 跑一条不符合预期的命令，用 create_project 在磁盘上创建出一堆你不知道的文件夹。

Agent 本身是没有恶意的，但模型有时候会“理解偏差”，把你的意图曲解成另一件事。

特别是在 Plan-and-Execute 和 Multi-Agent 模式下，任务执行的周期一旦很长，执行者就有可能犯下大错。

HITL 的出发点很简单：在执行之前，让人眼瞅一眼，确认没问题再继续。

这不是什么新鲜概念。

Claude Code 里有个 --dangerously-skip-permissions 参数，参数名里的 dangerously 就说明了一切——默认状态下，执行危险操作前它会停下来等你确认。

Codex 里有个 Approval Mode，也是同样的道理。

工具的设计者意识到，一个有写磁盘和执行命令能力的 Agent，不加任何约束直接跑，风险是很大的。

大模型的幻觉虽然在下降，但永远不会到零。

用户的意图经过提示词翻译成行动，本身就有信息损耗。损耗叠加幻觉，执行就可能跑偏。HITL 不是说 Agent 不可信，而是在模型还没有足够可靠之前，人始终要把控最后一道关。

02、危险操作怎么判断

这里有个很关键的设计决策：危险操作的判断，用静态规则还是动态 LLM 判断？

我选的是静态规则，理由很简单。

动态判断意味着每次调用工具之前，都要问一次 LLM：“这个操作危险吗？”这不仅慢，而且不可靠——今天问出来是危险的，明天可能问出来是安全的。

模型本身有随机性，用它来判断“是否要人工干预”，我们暂时先不考虑。

直接用静态规则写死一个名单。

public class ApprovalPolicy {

    // 需要人工确认的工具集合
    private static final Set DANGEROUS_TOOLS = Set.of(
            "write_file",
            "execute_command",
            "create_project"
    );

    public static boolean requiresApproval(String toolName) {
        return DANGEROUS_TOOLS.contains(toolName);
    }

    public static String getDangerLevel(String toolName) {
        return switch (toolName) {
            case "execute_command" -> "🔴 高危";
            case "write_file"      -> "🟡 中危";
            case "create_project"  -> "🟡 中危";
            default                -> "🟢 安全";
        };
    }

    public static String getRiskDescription(String toolName) {
        return switch (toolName) {
            case "execute_command" -> "将在系统上执行 Shell 命令，可能修改文件、安装软件或影响系统状态";
            case "write_file"      -> "将写入或覆盖文件内容，原有内容将丢失";
            case "create_project"  -> "将在磁盘上创建新目录和文件";
            default                -> "安全的只读操作";
        };
    }
}

read_file、list_dir、search_code 这三个工具是只读操作，不会改变任何东西，不需要审批。

write_file、execute_command、create_project 会写磁盘或跑命令，需要人工确认。

逻辑简单、结果可预期，这才是做 Agent 该有的样子。

execute_command 是高危（会跑 shell 命令），write_file 和 create_project 是中危（会写磁盘）。

这个等级信息后面会展示在审批框里，让用户一眼看出当前操作的危险指数。

03、审批请求怎么设计

审批请求是 HITL 系统里用户感知最强的一环——它决定了用户看到什么，进而决定用户能不能做出合理的判断。

ApprovalRequest 的定义如下：

public record ApprovalRequest(
        String toolName,
        String arguments,
        String dangerLevel,
        String riskDescription,
        String suggestion,
        String callerContext
) {
    public static ApprovalRequest of(String toolName, String arguments, String suggestion) {
        return new ApprovalRequest(
                toolName,
                arguments,
                ApprovalPolicy.getDangerLevel(toolName),
                ApprovalPolicy.getRiskDescription(toolName),
                suggestion,
                null
        );
    }
}

Record 在这里特别合适，因为审批请求是个纯数据载体，不可变，不需要方法逻辑。构建一次就是最终状态。

但光有数据还不够，还需要一个 toDisplayText() 方法，把这些字段格式化成好看的终端输出：

┌──────────────────────────────────────────────────────────┐
│  ⚠️  需要审批                                             │
├──────────────────────────────────────────────────────────┤
│  工具: write_file                                         │
│  等级: 🟡 中危                                            │
│  风险: 将写入或覆盖文件内容，原有内容将丢失                │
├──────────────────────────────────────────────────────────┤
│  参数:                                                    │
│    path: "/Users/itwanger/project/config.json"            │
│    content: "{"version": "2.0", ...}" (1240 字符)         │
└──────────────────────────────────────────────────────────┘

这个 toDisplayText() 方法里有个细节值得讲，就是显示宽度算法。

终端输出中，中文字符和 emoji 占两列，英文字符占一列。

如果不做处理，直接用字符串长度做 padding，中文和 emoji 就会把右边框挤歪掉，整个审批框看起来就歪歪扭扭的。

所以 ApprovalRequest 里实现了一个 displayWidth() 方法，专门计算字符串的终端显示列宽：

static int displayWidth(String s) {
    int w = 0;
    int i = 0;
    while (i < s.length()) {
        int cp = s.codePointAt(i);
        i += Character.charCount(cp);
        if (isWideCodePoint(cp)) {
            w += 2;   ...