@xicode/pi-permission-system

面向 Pi coding agent 的权限控制扩展，由 @xicode 维护和发布。

该包基于 @gotgenes/pi-permission-system，为工具调用、Bash 命令、MCP、Skill、 文件路径和工作目录外访问提供统一的 allow、ask、deny 策略。

主要能力

• 在 Agent 启动前隐藏不允许使用的工具。
• 在工具调用时执行确定性的允许、确认或拒绝策略。
• 按命令模式控制 Bash，并对无法可靠解析的命令采用 fail-closed 行为。
• 对 Pi 工具、Bash、MCP 和扩展工具执行统一的路径保护。
• 识别工作目录外访问，并支持按目录配置例外规则。
• 提供会话级授权、交互式确认和子 Agent 权限转发。
• 暴露跨扩展权限服务，供其他扩展注册访问提取器或授权器。

安装

pi install npm:@xicode/pi-permission-system

基本配置

全局配置文件：

~/.pi/agent/extensions/pi-permission-system/config.json

项目配置文件：

<project>/.pi/extensions/pi-permission-system/config.json

示例：

{
  "permission": {
    "*": "allow",
    "path": {
      "*": "allow",
      "*.env": "deny",
      "~/.ssh/*": "deny"
    },
    "bash": {
      "*": "ask",
      "git status": "allow",
      "rm -rf *": "deny"
    },
    "external_directory": "ask"
  }
}

项目配置覆盖全局配置。规则的完整语义、优先级和迁移说明随包发布：

• docs/configuration.md
• docs/session-approvals.md
• docs/cross-extension-api.md
• docs/subagent-integration.md
• docs/troubleshooting.md

跨扩展接入

其他扩展通过包根导出查询权限策略。接入时使用的包名以本节为准。

try {
  const { getPermissionsService } = await import("@xicode/pi-permission-system");
  const permissions = getPermissionsService();
  if (permissions) {
    const result = permissions.checkPermission("bash", "git push");
    console.log(result.state); // "allow" | "deny" | "ask"
  }
} catch {
  // 未安装本扩展，优雅降级
}

类型从同一入口导入：

import type {
  PermissionCheckResult,
  PermissionDecisionEvent,
  PermissionUiPromptEvent,
  PermissionsService,
} from "@xicode/pi-permission-system";

需要扩展工厂本身（而不是跨扩展服务）时，使用 ./extension 子路径导出：

import piPermissionSystemExtension from "@xicode/pi-permission-system/extension";

随包发布的 docs/cross-extension-api.md 由上游 @gotgenes/pi-permission-system 原样同步，文中的 await import("@gotgenes/pi-permission-system") 指的是上游包名；在本发行版中请一律替换为 @xicode/pi-permission-system，否则会得到 ERR_MODULE_NOT_FOUND。

例外：文档中的运行时符号 Symbol.for("@gotgenes/pi-permission-system:service")、事件通道名 （permissions:ready 等）以及 @gotgenes/pi-subagents 的事件契约保持上游命名不变——它们是与上游包 互通的契约，只有 import specifier 需要改写。

发行说明

• Pi 扩展入口为 dist/extension.js，同时通过 ./extension 子路径导出。
• 公共服务入口通过包根导出（main、types、exports["."] 一致指向 dist/service.*）。
• Bash 解析器使用随包发布的 Tree-sitter WASM。
• 发布包不包含安装期生命周期脚本。
• 配置 Schema、示例、面向使用者的文档和上游许可证随 npm 包发布（上游内部的 docs/plans、docs/retro、docs/architecture、docs/decisions 与上游一致不发布）。
• 内联和随包分发的第三方组件署名见 THIRD_PARTY_LICENSES.md。

上游版本、源码位置和本地适配见 UPSTREAM.md。