# @aliou/pi-guardrails 中文文档 规范地址：https://npmcn.com/package/%40aliou/pi-guardrails/ 版本：0\.22\.0 npm 元数据更新时间：2026-11-03T18:07:52.541Z 中文译文更新时间：2026-11-06T03:33:15.708Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40aliou/pi-guardrails 原文对照：https://npmcn.com/package/%40aliou/pi-guardrails/?lang=original 项目主页：https://github.com/aliou/pi-guardrails#readme 源码仓库：https://github.com/aliou/pi-guardrails ## 关键信息（来自 npm 元数据） - 包体积（解压后）：320 kB，69 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：2 个 - peer 依赖：@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \>=1\.5\.0 - 首次发布：2026-01-25T22:07:40.083Z - 最新版本发布：2026-11-03T18:07:52.179Z - 近 30 天下载量：5520（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：53（近 12 个月 53 个） ## 中文简介 ![banner](https://assets.aliou.me/github/aliou/pi-guardrails/banner.png) ## 安装 ```sh npm install @aliou/pi-guardrails ``` 也可以使用：`pnpm add @aliou/pi-guardrails`、`yarn add @aliou/pi-guardrails`、`bun add @aliou/pi-guardrails` ## README ![banner](https://assets.aliou.me/github/aliou/pi-guardrails/banner.png) # 护栏 > \[尖叫声\] 我对特工造成的任何问题、损坏或数据损失不负责任,即使使用护卫系统也是如此。 护栏不是沙盒 也不保证安全 您负责添加并维护在您环境中防止危险操作的规则; 不只依赖默认规则 . 护卫机为Pi增加了安全检查,因此特工们不太可能读取秘密,写出受保护的文件,进入工作空间外的路径,或者偶然运行危险的外壳命令. 软件包安装了四个 Pi 扩展: - **护栏** ——文件保护政策,设置,入职,并举出例子. - **路径访问** ——控制当前工作空间外的访问. - **权限门** ——确认或屏蔽有风险的外壳命令. - **医生** 向Herdr报告护卫队的批准情况. ## 安装 ```bash pi install npm:@aliou/pi-guardrails ``` ## 首发 安装后, 运行登入命令以选择起始设置 : `/guardrails:onboarding`。您以后可以改变一切 `/guardrails:settings`。 。 。 . [![Guardrails onboarding walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/onboarding.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/onboarding.mp4) ## 包含扩展 ### 护栏 保护文件如 `.env`,私有密钥,本地证书,数据库堆放,或任何您不希望 Pi 在没有明确意图的情况下读取或修改的特定项目路径. 规则默认尊重当前工作目录,并在设置 UI 中可配置. [![Guardrails policies and settings walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/policies.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/policies.mp4) 使用 `/guardrails:examples` 以添加共同的策略和命令预设,而不替换您现有的配置. [![Guardrails examples command walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/examples.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/examples.mp4) ### 路径访问 检查工具调用当前工作目录以外的目标路径 。 它可以在 Pi 访问您机器其它文件之前允许, 封锁, 或询问文件; 在询问模式中, 您可以允许文件或目录一次, 用于会话, 或总是这样 。 默认情况下,检查既适用于工作空间外的读取和写作,而且“总是”赠款被保存到项目配置上——两者都可以通过 `/guardrails:settings`。 。 。 . [![Guardrails path access prompt walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/path-access.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/path-access.mp4) ### 权限门 运行前检测到危险的shash命令——递归删除,特权命令,磁盘格式化,宽权限更改,以及您配置的任何自定义模式. 您可以允许一次, 允许会话, 拒绝, 或下降和停止, 这也会中止当前转弯 。 可设置自动密度模式 `terminate: true` 以在屏蔽后结束代理的回合,所以它不会重试被屏蔽的命令. 命令、政策和路径检查也查看了命令内部和处理替代,所以一个风险电话被包裹 `$(...)` 还被抓到了. [![Guardrails permission gate walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/permission-gate.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.22.0/permission-gate.mp4) ### 医生 包括Herdr适配器报告 积极的Guardrails批准 通过Herdr's `herdr:blocked` 因此,赫德可以显示 Pi 面板被屏蔽,同时提示等待决定。 除非赫德的Pi集成活动,否则没有配置和效果. 核准提示也报告 `blocked` 程序状态( OSC 7501) `blocked` 选项 `ctx.ui.custom()`,所以Rex等终端显示Pi在快速等待时被屏蔽;对此不再需要扩展了. ## 延长活动 Guardrails在 Pi 共享事件总线上发布对等事件: `guardrails:prompt:opened` 当交互式提示开始等待输入时 `guardrails:prompt:closed` 当它停止。 都一样 `prompt.id` 关系. ## 配置 大多数配置都通过交互设置 UI 实现(`/guardrails:settings`) (中文(简体) ). 高级用户可以直接编辑设置文件 : - 全球: `~/.pi/agent/extensions/guardrails.json` - 项目: `.pi/extensions/guardrails.json` 工程设置仅在 Pi 信任文件夹后才适用( P)`/trust`,然后重新启动 Pi 。 在此之前,未信任的项目文件被忽略并保持不变,而全局设置和内置保护仍然适用. 设定 `pathAccess.alwaysScope` 改为 `"global"` 在不信任项目的情况下保存“永远”路径赠款. 保存的文件包括 a `$schema` 字段,用于编辑器自动完成和校验 [`schema.json`](https://npmcn.com/package/%40aliou/pi-guardrails/schema.json)。 。 。 . ## 类似但不同 Pi的设计是为了让剂安全可以扩展. 护卫系统侧重于确定性、可配置文件政策、路径访问控制和危险指令提示。 见 [pi. dev/包装](https://pi.dev/packages) 整个登记册. 最接近的选项 : - [@ gotgenes/ pi-permission- system](https://pi.dev/packages/%40gotgenes/pi-permission-system): Pi工具调用的广泛许可执行. - [@vtstech/ pi- security (帮助)](https://pi.dev/packages/%40vtstech/pi-security):命令,路径,网络,模式,以及审计控制. - [@casualjim/pi-heimdall (英语)](https://pi.dev/packages/%40casualjim/pi-heimdall): 秘密暴露警卫、指挥政策、受保护 `.env` 还有一个沙盒警卫. - [纸箱](https://pi.dev/packages/pi-sandbox):OS级的沙箱来进行击打,允许/拒绝检查,并提示文件工具. - [皮-集装箱-沙盒](https://pi.dev/packages/pi-container-sandbox):在容器会话内运行读取、写取、编辑、拍取和用户拍取操作. 也可以自制:从 [Pi 权限门实例](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/permission-gate.ts) 并且请 Pi 为您的工作流程定制 . ## 发展 ```bash pnpm test # Run tests pnpm test:watch # Run tests in watch mode pnpm typecheck # Type check pnpm lint # Lint pnpm format # Format pnpm gen:schema # Regenerate schema.json pnpm check:schema # Verify schema.json is current ``` ## 常见问题 ### 如何安装 @aliou/pi-guardrails？ 在项目目录运行 npm install @aliou/pi-guardrails，或使用 pnpm add / yarn add / bun add。 ### @aliou/pi-guardrails 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aliou\_\_pi-guardrails 是否存在。 ### @aliou/pi-guardrails 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @aliou/pi-guardrails 可以商用吗？ @aliou/pi-guardrails 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @aliou/pi-guardrails 的下载量有多少？ 根据 npm 官方下载统计，@aliou/pi-guardrails 在 2026/10/06 – 2026/11/04 这 30 天内被下载 5,520 次，日均约 184 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @aliou/pi-guardrails 还在维护吗？ 最新版本 0\.22\.0 发布于 2026/11/04（2 天前）；至今共发布 53 个版本，其中过去 12 个月发布了 53 个；首次发布于 2026/01/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。