coding-agent/s03_permission/代码讲解.md

S03 Permission 代码讲解

这一节只讲相对 S02 新增的内容：

工具真正执行前，要先经过权限系统。

---

1. 本节新增内容

• DENY_LIST：绝对禁止的危险命令。
• PERMISSION_RULES：需要用户确认的风险操作规则。
• check_deny_list()：硬性拦截。
• check_rules()：匹配需要审批的规则。
• ask_user()：暂停并询问用户。
• check_permission()：统一权限入口。

---

2. 为什么需要 Permission

模型可能会生成危险操作，比如：

rm -rf /
sudo ...
shutdown

即使模型不是故意的，也可能因为上下文误解而做错事。

所以 Agent 不能直接执行工具调用，而应该是：

tool_use -> 权限检查 -> 允许才执行 -> tool_result

---

3. DENY_LIST

DENY_LIST 是字符串列表：

DENY_LIST: list[str] = [
    "rm -rf /",
    "sudo",
    "shutdown",
]

只要命令里包含这些片段，就直接拒绝。

这是第一道关卡：绝对禁止。

---

4. PERMISSION_RULES

PERMISSION_RULES 是一组规则：

PERMISSION_RULES: list[dict]

每条规则大概长这样：

{
    "tool": "bash",
    "pattern": "rm ",
    "reason": "可能删除文件"
}

它不是直接拒绝，而是告诉程序：

这个操作有风险，需要问用户

---

5. check_permission(block)

block 是模型返回的 tool_use 对象。

典型结构：

{
    "type": "tool_use",
    "name": "bash",
    "input": {
        "command": "rm test.txt"
    }
}

check_permission() 做三件事：

1. 如果是 deny list，直接拒绝。
2. 如果命中风险规则，询问用户。
3. 如果都没命中，允许执行。

---

6. Agent Loop 中的变化

S02 中拿到 tool_use 后直接执行。

S03 中多了一步：

if not check_permission(block):
    continue

这就是工具执行前的安全闸门。

---

7. 本节课堂重点

Permission 不是让模型自己判断安不安全。

真正的安全边界应该在程序里：

模型只能提出请求
程序决定是否执行
用户可以参与审批