Skip to content

第 7 章 别让它乱删东西 ​

本章代码 code/ch07/main.py、code/ch07/probe_modes.py · 读完约 18 分钟

7.0 上一章留下的问题 ​

第 5 章给工具划了个工作区,Bash 从 ./sandbox 起步。但 5.3 说得很清楚,那个 LocalWorkspace 只给起点,既不校验路径也不隔离进程,Read 里填个工作区外的绝对路径照样能打开。它不是墙。

第 6 章我们学会了自己写工具,check_permissions 是这么填的:

python
return PermissionDecision(
    behavior=PermissionBehavior.ALLOW,
    message="build_report 是只读工具,自动放行。",
)

只读工具这么写没问题。问题是 5.5 为了让命令行脚本跑通,还留了这么一行。

python
agent.state.permission_context.mode = PermissionMode.BYPASS

两处叠起来,整条链路上没有一个地方真的问过用户。相当于门卫上班第一天就把闸机抬起来焊死了。

如果你经常用 workbuddy,会发现它老在弹窗要你授权,一开始还挺烦。现在把 BYPASS 撤掉,那个弹窗就该回来了。它要建文件、改文件、跑命令,rm -rf ./src 路径在工作区内,命令也合规,结果可能是灾难性的。工作区管不住这件事,工具自己也不管。

有读者会想,把会删文件的工具在 check_permissions 里返回 DENY 不就完了。

这话对一半。Bash 收的是一整条命令,ls 和 rm -rf 走同一个工具,工具在拿到参数之前不知道这次要干什么。工作区内的写入该不该问,还得看现在有没有人能点「允许」,凌晨三点的定时任务和坐在终端前的你,答案不该一样。真拦下来之后对话怎么接着跑,工具更答不了。

所以判定得放在工具之外,还得有个能停下来等人的地方。

这一章回答三个问题:

  1. 框架给操作分了几个危险等级,谁说了算?
  2. 一次调用的判定按什么顺序走,哪一步的结果不许被覆盖?
  3. 需要人类点头的时候,一轮对话怎么暂停、怎么继续?

准备好了吗,我们把焊死的闸机拆下来~~

7.1 先跑三件事,再谈"危险" ​

先把 5.5 那行 BYPASS 撤掉,回到 DEFAULT,规则一条不加,工具也不改,就问它三个动作。

code/ch07/probe_modes.py 不需要模型,也不需要 API key,直接跑。

bash
python code/ch07/probe_modes.py

第一段输出是这样(Windows,agentscope 2.0.8 实测)。

text
--- 1. 同一套默认设置,三件事三个答案
  读一下 readme.md -> allow  immune=False
  改一下 notes.md -> ask  immune=False
  往 ~/.bashrc 追加一行 -> ask  immune=True
  补一条 Bash 全放行规则,再问第三件
  往 ~/.bashrc 追加一行 -> ask  immune=True   规则没盖住

第一件只是看一眼,放行。第二件动了文件,哪怕 notes.md 就在工作区里,也要先问。第三件动的是工作区外的系统配置,问得最坚决,脚本后面补了一条 Bash 全放行的 allow 规则再问一遍,还是 ask。

同一台机器,同一个 Agent,同样的设置,三件事三个答案。要是权限只是一个开关,这里只能填一个值,怎么都不够。

差别在哪儿?把三件事摆在一起,其实是在问三个不同的问题。

每次判定都要问上面三件事的差别前面在哪儿见过
这个动作改不改东西读不改,写会改第 3.4 节工具表最后一列「只读」
改的是哪一个notes.md 在工作区内,~/.bashrc 在外面第 5 章划的工作目录
现在有没有人能点「允许」你坐在终端前,还是凌晨三点没人看着的定时任务第 5 章命令行脚本没人点确认,只好临时设成 BYPASS

这三个问题互相不搭界,答了一个不等于答了另两个。前两个每次调用都会变,跟着工具名和参数走。第三个往往一整轮对话都不换。

所以框架没把它们压成一个布尔值,而是分两处放。

  • 模式(mode)是大前提,一次设好,整轮生效,一共只有五个取值。它主要管"现在有没有人盯着,整体该多严"。
  • 规则(rule)是具体的例外,一条盯住一类动作,想加几条加几条。"以后凡是 npm install 都别问我了"就是一条规则。

判定时先看规则,规则里没写,才轮到模式兜底。规则管例外,模式管兜底,这句话可以记一下。还是那个门卫,模式是他今天的值班守则,规则是你贴在墙上的几张纸条,纸条写了的按纸条办。

顺带说一句,上面这几行输出一个 token 都没花。权限判定是纯本地计算,不碰模型。这本书里凡是能不花 token 验的事,都建议先跑一遍再看结论。

7.2 五种模式 ​

PermissionMode 只有五个取值,枚举名与字符串值如下。

python
PermissionMode.DEFAULT       # "default"
PermissionMode.ACCEPT_EDITS  # "accept_edits"
PermissionMode.EXPLORE       # "explore"
PermissionMode.BYPASS        # "bypass"
PermissionMode.DONT_ASK      # "dont_ask"

光看名字猜不出边界。刚才那次运行还打了第二段,把三条命令在五种模式下各问一遍。

python
COMMANDS = [
    "ls -la",
    "rm -rf /",
    "echo hi >> ~/.bashrc",
]

async def show_mode_table() -> None:
    tool = Bash()

    print("--- 2. 五种模式 × 三类命令")
    header = f"{'mode':<14}{'command':<24}{'decision':<10}{'immune':<9}reason"
    print(header)
    print("-" * 100)

    for mode in PermissionMode:
        engine = PermissionEngine(PermissionContext(mode=mode))
        for command in COMMANDS:
            decision = await engine.check_permission(tool, {"command": command})
            print(
                f"{mode.value:<14}{command:<24}"
                f"{decision.behavior.value:<10}"
                f"{str(decision.bypass_immune):<9}"
                f"{decision.message[:36]}",
            )
        print()

真实输出(reason 那一列是脚本里截断过的,完整内容在 decision.message 里)。

text
--- 2. 五种模式 × 三类命令
mode          command                 decision  immune   reason
----------------------------------------------------------------------------------------------------
default       ls -la                  allow     False    Permission granted for Bash (read-on
default       rm -rf /                ask       True     Permission required: Command contain
default       echo hi >> ~/.bashrc    ask       True     Permission required: Bash command op

accept_edits  ls -la                  allow     False    Permission granted for Bash (read-on
accept_edits  rm -rf /                ask       True     Permission required: Command contain
accept_edits  echo hi >> ~/.bashrc    ask       True     Permission required: Bash command op

explore       ls -la                  allow     False    Permission granted for Bash (read-on
explore       rm -rf /                deny      False    Permission denied for Bash (explore 
explore       echo hi >> ~/.bashrc    deny      False    Permission denied for Bash (explore 

bypass        ls -la                  allow     False    Permission granted for Bash (bypass 
bypass        rm -rf /                allow     False    Permission granted for Bash (bypass 
bypass        echo hi >> ~/.bashrc    allow     False    Permission granted for Bash (bypass 

dont_ask      ls -la                  allow     False    Permission granted for Bash (read-on
dont_ask      rm -rf /                deny      False    Permission denied for Bash (dont_ask
dont_ask      echo hi >> ~/.bashrc    deny      False    Permission denied for Bash (dont_ask

把这十五行收成一张表,就是行为规范。

表 7-1 五种权限模式

模式只读操作工作区内写入工作区外写入高危命令(rm -rf /)适用场景
DEFAULT放行询问询问询问,且不可被规则覆盖日常交互
ACCEPT_EDITS放行放行询问询问,且不可被规则覆盖你正在盯着改代码
EXPLORE放行拒绝拒绝拒绝只想让它读、不想让它写
BYPASS放行放行放行放行(跳过安全询问)一次性容器 / 沙箱
DONT_ASK放行放行拒绝拒绝(询问转拒绝)定时任务、后台跑

四条容易看错的地方:

第一,DEFAULT 下写工作区内也要问。 很多人以为"在工作区里就安全",框架不这么认为。工作区的边界本来就不是墙,5.3 已经说过。这一条不用信我,7.6 的第三段会把它跑出来。

第二,EXPLORE 不查 allow 规则。 源码注释写得很直接,只读保证不能被你配置的规则让渡出去。哪怕你写了 allow: Bash *,在 EXPLORE 下照样拒绝。

第三,DONT_ASK 永远不会返回"询问"。 它的不变量是,任何本该弹出询问的路径一律转换为拒绝。这是为无人值守准备的,没有人能回答,那就当作不允许。

第四,ls 在 EXPLORE 和 DONT_ASK 下还是放行。 上面输出里那两行 ls -la -> allow 不是表格写错。Bash.check_permissions 的源码注释里单列了一条只读命令检查,ls、pwd、git status、cat 这些已知安全的命令在任何模式下都直接放行,它排在模式默认值之前。

这里有个挺贵的坑。想让程序后台跑,顺手把模式设成 BYPASS,看着省事,实际把 rm -rf / 和写 ~/.bashrc 的询问一起关掉了。无人值守要的是 DONT_ASK。对照上面那段输出,bypass 三行全是 allow,dont_ask 后两行是 deny,差的就是"没人点头时该拒还是该放"。

至于 BYPASS,源码里专门写了一句提醒,它会把所有工具发出的安全询问跳过,包括 rm -rf /、写 ~/.bashrc、命令注入这些。仅用于容器或你完全信任行为的场合。5.5 那行注释说「第 7 章会把这件事重新管起来」,说的就是把它换回 DEFAULT。

7.3 判定的真实顺序 ​

新手最容易误解的一点是,以为先看模式,模式说问就弹窗。实际顺序正好相反,模式排在最后一位。

权限判定的六级过滤

图 7-1 权限判定的六级过滤,顺序本身即安全设计

以 DEFAULT 为例,六个步骤,任何一步给出结论就立即返回。

  1. deny 规则命中,拒绝
  2. ask 规则命中,询问
  3. check_read_only() 为真,放行,也就是只读快通道
  4. 工具自己的 check_permissions()
    • 返回放行或拒绝,直接采纳
    • 返回安全询问(bypass_immune=True),直接采纳,allow 规则无法覆盖
    • 返回普通询问或 PASSTHROUGH,继续往下
  5. allow 规则命中,放行
  6. 模式默认值,DEFAULT 下为询问

第 4 步里那个 bypass_immune 是整章最值得记住的字段。它的含义是"这条判定不接受豁免"。翻 Bash.check_permissions 的源码注释,会看到五种打上这个标记的情况。命令含 $(...) 这类动态展开、命中危险命令模式、sed 就地修改敏感文件、目标路径落在敏感配置文件或目录、rm 指向系统关键目录。

所以你大概会想写这么一条规则,给 rm -rf 发张通行证。

python
engine.add_rule(
    PermissionRule(
        tool_name="Bash",
        rule_content="rm -rf",
        behavior=PermissionBehavior.ALLOW,
        source="user",
    ),
)

看起来能放行,实际上第 4 步就把它拦下了,7.1 第三条那个 immune=True 也是它。这不是 bug,是设计。能让你一键放行一切的安全机制,等于没有安全机制。

顺序本身就是安全设计。deny 排第一,allow 排第五,中间夹着工具自检,谁也别想靠一条写在后面的规则把前面的判定翻掉。

顺带说一个平台差异。上面这套静态分析在 Bash 工具里,第二段输出也是拿 Bash 跑的。Windows 上工作区给的是 PowerShell 工具,它的自检弱得多,多数命令直接交给引擎兜底,只读命令未必还能走那条快通道。别把两处的输出对混了。这不是配置错误,是平台实现差异,真要做细粒度放行,用规则把它压下去。

7.4 规则怎么写 ​

一条规则是四个字段。

python
from agentscope.permission import (
    PermissionBehavior,
    PermissionContext,
    PermissionEngine,
    PermissionRule,
)

rule = PermissionRule(
    tool_name="Write",          # 工具名,规则按它分组存放
    rule_content="src/**",      # 匹配内容,语义随工具而变
    behavior=PermissionBehavior.ALLOW,
    source="user",              # 来源标记,便于审计
)

rule_content 的语义不是统一的,得按工具分别记。

工具rule_content 的含义示例
Bash / PowerShell命令字符串的子串匹配"npm install" 命中 npm install express
Read / Write / Edit文件路径的 glob"src/**" 命中 src/main.py
其他工具工具自定义的过滤串由工具自己解释
留空 ""匹配一切等价于"这个工具全放行"

注意最后一行。rule_content="" 是一把万能钥匙,7.5 节的"始终允许"就是靠它实现的,用户按下 a 之后,我们给他写的就是一条空内容的 allow 规则。7.1 那条 Bash 全放行规则也是它,结果照样没盖住 immune=True。万能钥匙能开普通的门,开不了安全门。

规则挂在 PermissionContext 上,而这个结构的三个规则容器都是按工具名分组的字典。

python
PermissionContext(
    mode=PermissionMode.DEFAULT,
    working_directories={},   # dict
    allow_rules={},           # dict[str, list[PermissionRule]]
    deny_rules={},
    ask_rules={},
)

第 6 章留下的那两个参数,到这里能对上了。check_permissions(tool_input, context) 的第二个参数就是这个 PermissionContext,引擎把自己持有的那一份原样传进去,工具自检读到的 context.mode 和规则跟引擎用的是同一份。第一个参数 tool_input 是本次调用的参数字典,内容就是模型这次填的那几个字段,Bash 判断命令里有没有 $(...),读的就是 tool_input.get("command", "")。工具自检因此能赶在真正执行之前看清这次要干什么,只读快通道之后还要留这一步,原因就在这里。

所以不要写 context.allow_rules.append(rule),那会报 AttributeError: 'dict' object has no attribute 'append'。正确做法是用引擎的 add_rule(),它负责分组。

python
engine = PermissionEngine(agent.state.permission_context)
engine.add_rule(rule)

PermissionEngine 是无状态的薄壳,打印它的 __dict__ 只有一个键 context。也就是说,通过引擎加的规则直接写进了 Agent 的状态,下一次判定立刻生效。

有一种需求别用规则解决。业务上确实要频繁删临时目录,别急着给 rm 写 allow 规则,7.6 会看到那条路根本走不通。写一个 clean_temp_dir 工具,让它只接受白名单里的子目录名。用工具收窄能力,别用规则放宽权限。

7.5 人在回路:暂停与续跑 ​

判定结果是"询问"之后,框架不会自己弹窗。它往事件流里抛一个 RequireUserConfirmEvent,然后停下来。

这个"停下来"很关键。不是这一轮回复结束了,是异步生成器停在了中间,模型的上下文、已经产生的工具调用、reply_id,全都还活着。

人在回路的暂停与续跑

图 7-2 人在回路的暂停与续跑,两次调用同一个 reply_id

代码上就是一个 break 加一个 while True。下面这份省掉了打印和渲染,完整文件在 code/ch07/main.py。

python
async def run_with_confirmation(agent: Agent, question: str) -> None:
    inputs = UserMsg(name="user", content=question)

    while True:
        pending = None

        async for event in agent.reply_stream(inputs):
            if event.type == EventType.REQUIRE_USER_CONFIRM:
                pending = event
                break                    # 事件流在这里断掉
            render(event)

        if pending is None:              # 没有待确认项,这一轮真的结束了
            return

        results = []
        for tool_call in pending.tool_calls:
            answer = input("允许执行?[y] 允许 / [n] 拒绝 / [a] 始终允许 > ")
            answer = answer.strip().lower()

            rules = []
            if answer == "a":
                rule = PermissionRule(
                    tool_name=tool_call.name,
                    rule_content="",
                    behavior=PermissionBehavior.ALLOW,
                    source="user",
                )
                PermissionEngine(agent.state.permission_context).add_rule(rule)
                rules.append(rule)

            results.append(
                ConfirmResult(
                    confirmed=answer in ("y", "a"),
                    tool_call=tool_call,
                    rules=rules,
                ),
            )

        inputs = UserConfirmResultEvent(
            reply_id=pending.reply_id,   # 靠它把续跑接回原处
            confirm_results=results,
        )

四个对象的职责要分清,写错了会直接抛校验错误。

对象字段谁产生
RequireUserConfirmEventreply_id、tool_calls框架
ConfirmResultconfirmed、tool_call、rules你
UserConfirmResultEventreply_id、confirm_results你
PermissionRuletool_name、rule_content、behavior、source你(可选)

ConfirmResult.tool_call 是必填的,不接受 None。因为它是一个 ToolCallBlock,里面带着 id,框架要靠这个 id 把"批准"对应到具体哪一次调用。一次询问可能同时包含多个工具调用,模型并行发起的,所以 confirm_results 是列表,逐条对应。

rules 字段的用途是"这次批准要记住"。框架会把它合并进上下文,效果和你手动调 add_rule() 一样。两者都写也不会重复,但没必要,选一个即可。

这里最容易写错的不是异步语法,是把续跑当成重新提问。发出去的必须是 UserConfirmResultEvent,不是又发一遍原始问题。7.7 会把这个错的后果摆出来。

7.6 规则能压到哪儿,压不到哪儿 ​

同一次运行的第三段专门验这件事。它把 7.3 那条 rm -rf 的 allow 规则真写进去,再补一条 ls 的 deny 规则,最后拿同一个 Write 在两种模式下各问一次。

输出是这样。

text
--- 3. 规则能不能盖住安全拦截
已写入 allow 规则:Bash / rm -rf
  rm -rf /           -> ask   immune=True Permission required: Command contains da
  rm -rf ./build     -> ask   immune=True Permission required: Command contains da
  ls -la             -> deny  (deny 规则压过只读快通道)
  Write default       -> ask   Permission required for Write
  Write accept_edits  -> allow Permission granted for writing C:\Users\xion

四条结论,每一条都值得停一下。

  1. 写了 allow 规则,rm -rf / 依然询问。这是 bypass_immune 在起作用。
  2. rm -rf ./build 也依然询问。危险模式的判定按命令形态走,不区分目标目录。
  3. ls -la 被判成拒绝,因为后加的 deny 规则排在第 1 位,压过了第 3 位的只读快通道。
  4. 同一个 Write,工作区内的路径在 default 下询问、在 accept_edits 下放行,和表 7-1 对得上。

回头看第二段输出的 immune 那一列。只有 default 和 accept_edits 下的高危命令是 True。到了 explore 和 dont_ask,判定在更前面就变成了拒绝,bypass_immune 也就无从谈起了。

第 2 条带来一个实际结论,不要指望用 allow 规则给 rm 开后门。如果你的业务确实需要频繁删除临时目录,正确的做法是写一个专用的 clean_temp_dir 工具,让它只接受白名单内的子目录名。用工具收窄能力,不用规则放宽权限。第 6 章讲"一个工具只做一件事",在这儿又兑现了一次。

整段实验不调模型,也不要 key。上面贴的两段输出,你都能在自己机器上原样跑出来。

7.7 三个常见错误 ​

错误 1:把 PermissionContext 当成普通容器

python
context.allow_rules.append(rule)      # AttributeError: 'dict' object has no attribute 'append'

三个规则容器都是"工具名 → 规则列表"的字典。用 PermissionEngine(context).add_rule(rule),别自己往里塞。

错误 2:续跑时忘了带 reply_id

python
inputs = UserConfirmResultEvent(confirm_results=results)   # 缺 reply_id

这个字段的作用是把续跑接回原处。缺了它,框架找不到对应的回复上下文,表现为状态混乱或直接报错。正确写法永远是 reply_id=pending.reply_id,从那个让你 break 的事件里取。

错误 3:在 while 里重新构造 UserMsg

python
while True:
    async for event in agent.reply_stream(UserMsg(...)):   # 每一轮都是新问题

续跑的输入必须是 UserConfirmResultEvent,不是又发一遍原始问题。发原始问题会让模型以为用户在重复提问,然后重新规划一遍,可能又发起同一个工具调用,形成死循环。

7.8 小结 ​

  • 模式是粗粒度默认策略,规则是细粒度例外,规则先于模式
  • 判定有六个步骤,deny 规则排第一,模式排最后
  • check_read_only() 是快通道,但 deny / ask 规则能压过它
  • bypass_immune=True 的安全询问不接受 allow 规则豁免,这是防护的底线
  • EXPLORE 不查 allow 规则,DONT_ASK 永不返回询问,BYPASS 跳过全部安全询问
  • 询问用 break 暂停生成器,用 reply_id 续跑,不是重新发起对话
  • 规则容器是按工具名分组的字典,用 add_rule() 写入
  • 权限判定不碰模型,五种模式的行为可以用离线脚本亲手验一遍

到这里,Buddy 会干活、会守边界,也知道什么时候该问人。但它这一轮的记忆只活在进程内存里。任务一长,几十步调用堆进上下文,最早那句要求就被埋住了。关掉终端更干脆,一切归零。

下一章要解决的问题:一轮对话跑了几十步、上下文涨到几万 token,怎么在有限窗口里活下去?

教程正文采用 CC BY-NC-SA 4.0 许可,code/ 下示例代码可自由使用