第 7 章 别让它乱删东西
本章代码
code/ch07/main.py、code/ch07/probe_modes.py· 读完约 18 分钟
7.0 上一章留下的问题
第 5 章给工具划了个工作区,Bash 从 ./sandbox 起步。但 5.3 说得很清楚,那个 LocalWorkspace 只给起点,既不校验路径也不隔离进程,Read 里填个工作区外的绝对路径照样能打开。它不是墙。
第 6 章我们学会了自己写工具,check_permissions 是这么填的:
return PermissionDecision(
behavior=PermissionBehavior.ALLOW,
message="build_report 是只读工具,自动放行。",
)只读工具这么写没问题。问题是 5.5 为了让命令行脚本跑通,还留了这么一行。
agent.state.permission_context.mode = PermissionMode.BYPASS两处叠起来,整条链路上没有一个地方真的问过用户。相当于门卫上班第一天就把闸机抬起来焊死了。
如果你经常用 workbuddy,会发现它老在弹窗要你授权,一开始还挺烦。现在把 BYPASS 撤掉,那个弹窗就该回来了。它要建文件、改文件、跑命令,rm -rf ./src 路径在工作区内,命令也合规,结果可能是灾难性的。工作区管不住这件事,工具自己也不管。
有读者会想,把会删文件的工具在
check_permissions里返回DENY不就完了。
这话对一半。Bash 收的是一整条命令,ls 和 rm -rf 走同一个工具,工具在拿到参数之前不知道这次要干什么。工作区内的写入该不该问,还得看现在有没有人能点「允许」,凌晨三点的定时任务和坐在终端前的你,答案不该一样。真拦下来之后对话怎么接着跑,工具更答不了。
所以判定得放在工具之外,还得有个能停下来等人的地方。
这一章回答三个问题:
- 框架给操作分了几个危险等级,谁说了算?
- 一次调用的判定按什么顺序走,哪一步的结果不许被覆盖?
- 需要人类点头的时候,一轮对话怎么暂停、怎么继续?
准备好了吗,我们把焊死的闸机拆下来~~
7.1 先跑三件事,再谈"危险"
先把 5.5 那行 BYPASS 撤掉,回到 DEFAULT,规则一条不加,工具也不改,就问它三个动作。
code/ch07/probe_modes.py 不需要模型,也不需要 API key,直接跑。
python code/ch07/probe_modes.py第一段输出是这样(Windows,agentscope 2.0.8 实测)。
--- 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 只有五个取值,枚举名与字符串值如下。
PermissionMode.DEFAULT # "default"
PermissionMode.ACCEPT_EDITS # "accept_edits"
PermissionMode.EXPLORE # "explore"
PermissionMode.BYPASS # "bypass"
PermissionMode.DONT_ASK # "dont_ask"光看名字猜不出边界。刚才那次运行还打了第二段,把三条命令在五种模式下各问一遍。
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 里)。
--- 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 为例,六个步骤,任何一步给出结论就立即返回。
- deny 规则命中,拒绝
- ask 规则命中,询问
check_read_only()为真,放行,也就是只读快通道- 工具自己的
check_permissions()- 返回放行或拒绝,直接采纳
- 返回安全询问(
bypass_immune=True),直接采纳,allow 规则无法覆盖 - 返回普通询问或
PASSTHROUGH,继续往下
- allow 规则命中,放行
- 模式默认值,
DEFAULT下为询问
第 4 步里那个 bypass_immune 是整章最值得记住的字段。它的含义是"这条判定不接受豁免"。翻 Bash.check_permissions 的源码注释,会看到五种打上这个标记的情况。命令含 $(...) 这类动态展开、命中危险命令模式、sed 就地修改敏感文件、目标路径落在敏感配置文件或目录、rm 指向系统关键目录。
所以你大概会想写这么一条规则,给 rm -rf 发张通行证。
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 规则怎么写
一条规则是四个字段。
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 上,而这个结构的三个规则容器都是按工具名分组的字典。
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(),它负责分组。
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。
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,
)四个对象的职责要分清,写错了会直接抛校验错误。
| 对象 | 字段 | 谁产生 |
|---|---|---|
RequireUserConfirmEvent | reply_id、tool_calls | 框架 |
ConfirmResult | confirmed、tool_call、rules | 你 |
UserConfirmResultEvent | reply_id、confirm_results | 你 |
PermissionRule | tool_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 在两种模式下各问一次。
输出是这样。
--- 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四条结论,每一条都值得停一下。
- 写了 allow 规则,
rm -rf /依然询问。这是bypass_immune在起作用。 rm -rf ./build也依然询问。危险模式的判定按命令形态走,不区分目标目录。ls -la被判成拒绝,因为后加的 deny 规则排在第 1 位,压过了第 3 位的只读快通道。- 同一个
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 当成普通容器
context.allow_rules.append(rule) # AttributeError: 'dict' object has no attribute 'append'三个规则容器都是"工具名 → 规则列表"的字典。用 PermissionEngine(context).add_rule(rule),别自己往里塞。
错误 2:续跑时忘了带 reply_id
inputs = UserConfirmResultEvent(confirm_results=results) # 缺 reply_id这个字段的作用是把续跑接回原处。缺了它,框架找不到对应的回复上下文,表现为状态混乱或直接报错。正确写法永远是 reply_id=pending.reply_id,从那个让你 break 的事件里取。
错误 3:在 while 里重新构造 UserMsg
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,怎么在有限窗口里活下去?
