Pi Command Guardian

Pi Command Guardian 是一个最小 Pi Extension，用于阻止模型 Bash 中常见的显式删库、系统删除和磁盘破坏操作，同时允许清理项目构建产物和系统临时文件。

保护范围

Extension 只处理模型发起的 bash tool_call：

• 自动允许工作区和系统临时目录严格子项的文件删除。
• sudo、env 和执行模式的 command 包装后继续判断实际删除命令。
• 阻止工作区根和工作区外目标的删除，并要求人工审阅。
• 变量、命令替换、未引用的波浪号或花括号展开等无法静态确定的目标，要求简化为语法完整、直接包含静态目标的 Bash 删除命令。
• 阻止显式 DROP DATABASE、DROP TABLE 和 TRUNCATE。
• 永久阻止文件系统根、用户目录根、系统关键目录、数据库数据目录和磁盘设备破坏。

明确外部目标等普通阻止发生后，应先审阅被阻止的操作和目标，再自行决定是否手动删除。无法静态确定目标或 Shell 嵌套超过八层时，应先确定所有实际删除目标，再将命令简化为语法完整、直接包含静态目标的 Bash 删除命令后重新提交。Extension 不推荐绕过保护的具体执行方式。永久阻止只限制模型工具调用，同样不会接管用户 Bash。

允许示例

rm -rf build
rm -rf ./dist/*
find ./coverage -type f -delete
rm -f /tmp/pi-output.log

所有删除目标均位于工作区或系统临时目录内部，因此保持自动执行。

阻止示例

rm -rf .
rm -rf ../other-project
rm -rf "$TARGET"
rm -rf ~/
rm -rf {build,../shared}
sudo rm -rf /
psql -c 'DROP DATABASE production'

外部目标和工作区根会被阻止并要求人工审阅。动态内容、xargs 输入、空缺目标、无法可靠解析或 Shell 嵌套超过八层等不确定删除会被阻止，并要求先确定所有实际删除目标，再简化为语法完整、直接包含静态目标的 Bash 删除命令。显式删库使用人工审阅提示，Git 命令保持 Pi 原有行为。

永久阻止示例

rm -rf /
rm -rf "$HOME"
rm -rf /var/lib/postgresql
mkfs.ext4 /dev/sda1
dd if=/dev/zero of=/dev/sda
parted /dev/sda mklabel gpt

明确限制

以下间接副作用不做分析：

python cleanup.py
npm run migrate
./deploy.sh

Extension 也不处理 read、write、edit、自定义工具、!command 或 !!command。备份、数据库最小权限、磁盘快照和容器隔离仍由运行环境负责。

实现结构

src/
├── index.ts             # Pi tool_call 接入
├── command-parser.ts    # Tree-sitter Bash 解析
└── deletion-guard.ts    # 显式破坏操作判断

运行时没有模型请求、配置文件、会话授权状态或审查记录。生产依赖只有 @vscode/tree-sitter-wasm。

环境要求

• Node.js >=22.19.0
• Pi 0.81.1 或兼容版本

安装

仓库安装：

npm install
pi install .

临时加载：

pi -e .

npm 发布后安装：

pi install npm:[email protected]

验证

npm test
npm run typecheck
npm run spec:check
npm run pack:check

卸载

pi remove npm:pi-command-guardian

旧版本创建的配置和审查记录不会自动删除。

许可证

本 package 以 MIT 许可证发布，详见 LICENSE。