pi-safety-guards

Pi 的 Bash 安全规则插件：规则直接写在配置文件里，支持逐条设置动作、说明和扩展匹配器。

English

安装

pi install npm:pi-safety-guards

安装或修改配置后执行 /reload。

默认规则

第一次运行时，如果配置文件还不存在，插件会把下面 4 条规则写进 <pi-agent-dir>/extensions/pi-safety-guards/config.json，之后只读这个文件。没有藏在代码里的内置规则，改文件就是改行为。

规则 ID	匹配范围	动作
filesystem.delete	实际执行的 rm/rmdir	confirm
filesystem.format	实际执行的 mkfs/mkfs.*	confirm
filesystem.ownership	实际执行的 chown	confirm
shell.fork-bomb	支持的冒号函数 fork bomb 形式	confirm

这 4 条就是原来的 destructive-operations 预设，原文见 config.example.json，可以整段复制。原来的 workspace-boundary 预设（目录越界即阻断）现在这样写：

{ "id": "paths.workspace", "action": "block", "match": { "outsideRoots": ["."] } }

匹配基于解析后的命令，覆盖支持的 wrapper、字面量嵌套 shell、命令替换和重定向。echo 'rm file' 和 git rm 不视为实际执行 rm；commandPattern 是例外，它看原始命令文本。

配置

文件：<pi-agent-dir>/extensions/pi-safety-guards/config.json，agent 目录遵守 PI_CODING_AGENT_DIR。顶层只接受 rules。

{
  "rules": [
    { "id": "filesystem.delete", "action": "confirm", "match": { "commands": ["rm", "rmdir"] } },
    {
      "id": "project.build",
      "action": "block",
      "match": { "commands": ["mvn"] },
      "message": { "zh-CN": "禁止直接运行 Maven。", "en-US": "Direct Maven execution is blocked." }
    },
    { "id": "paths.workspace", "enabled": false, "action": "block", "match": { "outsideRoots": ["."] } }
  ]
}

另见 config.example.json 和 custom-rules.json。

• rules：规则数组，可以为空；为空表示没有任何保护，启动时会明确提示。
• 每条规则必须写 id、action、match；只写 id 不再有意义（预设已删除）。
• enabled：可选的布尔值；false 表示暂时停用这条规则但保留内容。停用的规则同样要写全 id、action、match。
• 列表内 ID 不能重复，字段名写错会直接报错，不会静默忽略。
• message：可选的非空文本，或包含 zh-CN、en-US 的对象。不填写时反馈规则 ID 和动作。

/config:safety-guards（等价于 /config:safety-guards show）只打印配置文件路径和当前生效规则，不打开菜单、也不改文件：

配置文件：<pi-agent-dir>/extensions/pi-safety-guards/config.json
  filesystem.delete → confirm · commands: rm, rmdir
  project.build → block · commands: mvn
  paths.workspace → 已停用

停用的规则显示“已停用”。改完配置后执行 /reload。

动作

动作	行为
warn	放行，将提醒附加到对应工具结果，无 UI 模式也可见。
confirm	合并命中的规则后询问一次；无法交互或用户未确认时阻断。
block	不询问，直接拒绝。

多条规则命中时，优先级为 block > confirm > warn，反馈包含所有命中的规则 ID。

匹配器

每条规则选择一种匹配方式：

match	含义
{ "commands": ["example-command"] }	实际执行程序的 basename 精确匹配
{ "commandPrefixes": ["mkfs"] }	实际执行程序的 basename 以某个前缀开头
{ "commandPattern": ":\\(\\)\\s*\\{" }	对原始命令文本做正则匹配；不带 flags，引号内文本也算
{ "outsideRoots": [".", "../shared"] }	显式路径超出配置的允许根
{ "module": "./rules/deploy.mjs" }	可信的本地匹配器模块

commandPattern 是命令语法无法用命令名表达时的退路。它看的是原始命令文本，所以 echo ':(){ :|:& };:' 也会命中；需要精确到“命令加参数”的判断时用 module。

旧的 detector 匹配器已删除，因为它的逻辑藏在代码里而不在配置里。迁移对照：

已删除	替代写法
{ "detector": "disk-format" }	{ "commandPrefixes": ["mkfs"] }
{ "detector": "fork-bomb" }	{ "commandPattern": ":\\(\\)\\s*\\{" }
{ "detector": "in-place-edit" }	用 module 匹配器自己判断命令和参数
{ "detector": "home-root" }	用 module 匹配器自己判断命令和参数
{ "detector": "root-search" }	用 module 匹配器自己判断命令和参数

目录规则

相对根路径以 Pi 当前工作目录为基准，也支持绝对路径和 ~/。只有列出的根才被允许，["."] 表示工作目录。安装 pi-add-dir 时会同时尊重其当前会话目录授权；session_squash 后会从被压缩的源分支恢复这份授权。需要时添加额外目录或 /dev/null 等设备路径。

自定义匹配器可使用导出的 findOutOfScopeBashPaths(command, cwd, roots)，提供自行计算的目录列表。

文件系统无法表示的名字（含 NUL，或单个分量超过 255 字节）不算路径引用，所以 python3 -c '...' 这类解释器程序正文不会让规则失败；整条路径长到无法表示的候选也只按普通路径判定范围，不会以异常阻断。

自定义模块

模块路径以配置文件所在目录为基准。JavaScript ES 模块必须默认导出匹配函数：

export default ({ commands }) => commands.some(
  ({ name, args }) => name === "example-deploy" && args.includes("--production"),
);

函数接收冻结的 { command, cwd, commands: [{ name, args }] } 摘要，返回布尔值或 Promise<boolean>。包内导出了 RuleContext 和 RuleMatcher 类型。

只加载启用的模块。加载失败、匹配异常、非布尔返回或异步工作超过 5 秒，均会阻断操作。修改模块后执行 /reload。

模块拥有进程权限，超时无法中断同步死循环或撤销副作用，因此只能加载可信代码。

限制与错误

本包检查 Pi 的 bash 工具，不覆盖用户直接执行的 shell、其他工具或程序内部操作。不保证检测所有危险命令，不模拟所有工作目录变化，也不解析任意变量计算的路径。目录检查处理可静态识别的引用和符号链接，不是操作系统访问控制。

配置文件不存在时按没有规则处理；配置损坏、Bash 解析失败或启用规则异常时阻断 Bash，修复相应错误后恢复；修改配置需要 /reload。

运行时文案支持中英文。

开发

npm run check