安全 Agent 设计

一个能操作本地文件和 shell 的 Agent，最低限度要守住这些边界：

1. 工具调用必须结构化。
2. 工具执行前必须校验参数。
3. 写操作必须经过权限网关。
4. 工具失败必须显式返回错误结果。
5. 权限决策必须可记录。

读写分离

Claude Code 通过 isReadOnly()、isConcurrencySafe() 和权限规则区分读操作和写操作。

自研 Agent 也应该先区分：

Read tools:
  - read_file
  - list_files
  - grep

Write tools:
  - edit_file
  - write_file
  - bash

读工具可以默认允许，写工具默认询问。

Bash 是高风险工具

Bash 工具的问题是：一个字符串可以包含很多真实动作。

例如：

cat package.json && rm -rf dist

如果只检查命令开头，就可能误判。

简化版 Bash 权限至少要做：

• 命令摘要展示给用户。
• 默认 ask。
• 支持 allowlist，例如 git status、ls、pwd。
• 禁止明显危险命令，例如 rm -rf /。
• 无法解析时保守处理。

文件路径权限

文件工具至少要处理：

• 相对路径转绝对路径。
• 禁止越权访问工作区外路径。
• symlink。
• 读写权限区分。
• 文件被外部修改后的冲突。

Claude Code 的 FileEdit 会检查文件在上次读取后是否变化，这是一个值得学习的设计。

小结

安全设计不要等到功能完成后再补。Agent 的每个外部动作都应该天然经过 PermissionGate，这是从 toy agent 走向真实产品的分界线。