# @amaster\.ai/pi-security 中文文档

规范地址：https://npmcn.com/package/%40amaster.ai/pi-security/

版本：0\.1\.37
npm 元数据更新时间：2026-11-09T02:51:16.022Z
中文译文更新时间：2026-11-09T07:48:20.741Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/pi-security
原文对照：https://npmcn.com/package/%40amaster.ai/pi-security/?lang=original
项目主页：https://github.com/TGYD-helige/pi#readme
源码仓库：https://github.com/TGYD-helige/pi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.8 MB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@earendil-works/pi-coding-agent \>=0\.79\.1
- 首次发布：2026-05-18T11:36:04.360Z
- 最新版本发布：2026-11-09T02:51:15.797Z
- 近 30 天下载量：3821（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

资源意识安全政策引擎和工具授权的扩展

## 安装

```sh
npm install @amaster.ai/pi-security
```

也可以使用：`pnpm add @amaster.ai/pi-security`、`yarn add @amaster.ai/pi-security`、`bun add @amaster.ai/pi-security`

## README

# 皮卫兵

![pi-security preview](https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-security/preview.png)

`@amaster.ai/pi-security` 提供沙盒感知安全政策引擎和Pi扩展切入点.

核心引擎将工具调用分类为资源(文件, shell 命令,网络访问),评估风险,并应用配置规则来决定调用是被允许的,被拒绝的,还是需要人类批准. 剖面图由两个正交轴来构建—— **沙盒** (哪些工具被曝光)和 **核准** (何时去问用户)——受"法典"启发.

## Pi 扩展

安装扩展入口 `@amaster.ai/pi-security/extension` 并装入 `pi-security` 通过 Pi 设置密钥 `SettingsManager`数字 :

```json
{
  "pi-security": {
    "enabled": true,
    "profile": "default",
    "approvals": {
      "allowSessionGrants": true
    }
  }
}
```

扩展收听 Pi `tool_call` 财务报告和审定财务报表 `user_bash` 事件。 它没有注册一个可以绕过策略的LLM可调用工具. 人类通过Pi UI原始程序在获得UI时请求批准;非交互上下文在某项规则需要批准时关闭.

## 内置配置文件

简介来自a `sandbox` × `approval` 矩阵。 选择一个作为起点, 并覆盖您自身配置中的任意一轴 .

| 简介 | 沙盒 | 核准 | 使用大小写 |
| --- | --- | --- | --- |
| `read-only` | `read-only` | `never` | 只读检查,无修改 |
| `default` | `workspace-write` | `on-request` | 允许写作的工作空间编辑( 建议) |
| `auto` | `workspace-write` | `on-failure` | 自动编辑, 仅在风险高时才询问 |
| `full-access` | `full-access` | `never` | 受信任的自动化,不玩游戏(小心使用) |

### 沙盒模式

| 模式 | 允许的工具 | 被拒绝的工具 |
| --- | --- | --- |
| `read-only` | `read`, (中文(简体) ), `ls`, (中文(简体) ), `find`, (中文(简体) ), `grep` | `write`, (中文(简体) ), `edit`, (中文(简体) ), `bash` |
| `workspace-write` | `read`, (中文(简体) ), `ls`, (中文(简体) ), `find`, (中文(简体) ), `grep`, (中文(简体) ), `write`, (中文(简体) ), `edit`, (中文(简体) ), `bash` | —— 说 |
| `full-access` | `*` (所有工具) | —— 说 |

工具名称与 pi-coding- agent 内置工具一致 : `bash`, (中文(简体) ), `read`, (中文(简体) ), `write`, (中文(简体) ), `edit`, (中文(简体) ), `ls`, (中文(简体) ), `find`, (中文(简体) ), `grep`。 。 。 .

### 核准模式

| 模式 | 行为 |
| --- | --- |
| `never` | 没有批准提示(对秘密等仍然适用否定规则). |
| `on-failure` | 只询问高/关键风险操作. |
| `on-request` | 询问工作空间写作/删除(除了高风险操作). |
| `untrusted` | 关于工作空间的询问会加上高风险操作; 默认决定也会被询问 . |

基线秘密保护(拒绝) `.ssh/`, (中文(简体) ), `.env`, (中文(简体) ), `*.pem`, (中文(简体) ), `*.key`)总是启用的,而不论配置.

## 自定义配置

剖面可以分为三地来定义. 高优先源覆盖同名低优先源 :

1.  **受托项目**数字 : `<cwd>/.pi/policy/<name>.json` (接受项目信托时的最高优先级)
2.  **探员**数字 : `<agentDir>/policy/<name>.json`
3.  **用户**数字 : `~/.pi/agent/policy/<name>.json`
4.  **设置**: 在 `pi-security.security.profiles` 内 `pi.json`

每个 JSON 文件定义了单个配置文件; 文件名( 没有 `.json`)是剖面图名称. 当项目信任下降或得不到时,项目政策就会被忽略.

### JSON 配置实例

现成拷贝样品位于 [`examples/`](https://npmcn.com/package/%40amaster.ai/pi-security/examples) 并使用测试套件:

-   [`examples/reviewer.json`](https://npmcn.com/package/%40amaster.ai/pi-security/examples/reviewer.json) ——项目级文件政策. 对于一个值得信赖的项目,把它扔进 `<project>/.pi/policy/reviewer.json`开始于 `read-only`打开 `workspace-write`,询问 `bash`,否认外部网络.
-   [`examples/auto-review.settings.json`](https://npmcn.com/package/%40amaster.ai/pi-security/examples/auto-review.settings.json) a 包括: `pi.json` 定义自定义的片段 `auto-review` 配置内置 。 扩展 `default` 并在软件包管理器安装之前询问(`npm/pnpm/yarn/pip install|add`)通过 `argsRegex`。 。 。 .

### 配置图

```ts
type SecurityProfileConfig = {
  extends?: string;                   // built-in profile name or another custom profile
  sandbox?: 'read-only' | 'workspace-write' | 'full-access';
  approval?: 'never' | 'on-failure' | 'on-request' | 'untrusted';
  rules?: SecurityRule[];             // appended after parent rules
  defaultDecision?: SecurityDecision; // overrides parent default for unmatched tools
};
```

### 规则方案

规则按优先级(降级)进行评分;第一对比赛取胜.

```ts
type SecurityRule = {
  id: string;
  priority?: number;                  // default 300 for user rules
  tools?: string[];                   // tool name patterns ('*', 'mcp_*', 'bash')
  sources?: ToolSource[];             // 'builtin' | 'mcp' | 'runtime'
  triggers?: Array<'user' | 'agent' | 'scheduler'>;
  senderTrusts?: Array<'owner' | 'trusted' | 'untrusted'>;
  args?: Record<string, string>;      // exact/glob match against args
  argsRegex?: Record<string, string>; // regex match against args
  resources?: ('file' | 'shell' | 'network')[];
  operations?: ('read' | 'write' | 'execute' | 'delete' | 'connect' | 'search')[];
  scopes?: ('workspace' | 'home' | 'system' | 'external' | 'unknown')[];
  sensitivity?: ('normal' | 'source' | 'config' | 'secret' | 'credential')[];
  risk?: ('low' | 'medium' | 'high' | 'critical')[];
  decision: { kind: 'allow' } | { kind: 'deny'; reason: string } | { kind: 'ask'; reason: string; prompt?: string };
};
```

## 图标

-   `/pi-security-status` 显示活动概况、审计数和会期赠款.
-   `/pi-security-audit [limit]` 显示没有原始敏感产出的近期授权决定.
-   `/pi-security-reset` 清除会期批准赠款.

## 信任模式

这个模块是一个执行门,而不是文件系统沙盒本身. 拒绝和批准决定可以执行,因为它们在Pi工具执行之前运行;沙盒执行仍然取决于执行工具的运行时间.

SSH 密钥等敏感路径, `.env`、证书、证物、私人钥匙和 `secrets/` 所有配置的基线政策都否定了目录。 审计条目包括工具名,资源摘要,风险程度,以及决策元数据等,但不应包括纯文本机密.

扩展会同步刷新每个授权决定的内置设置和文件政策,在等待阅读后重新检查信任,并在有效配置或信任改变时清除会话。 政策修改,删除,和项目信任修改适用于下个决定;授权配置不保存在 TTL 缓存中. 政策加载最多接受128个JSON文件,每个文件128个KiB,2个MiB组合,以及1 024个跨层目录条目. 设置文件每个限制1个米B. 限制, 配置错误, 并读取错误块授权, 带有明显的错误而不是丢弃策略 .

配置刷新有一个5秒的最后期限,涵盖队列等待,设置,政策,以及信任触发重装,并接受呼叫者取消. 在读数开始前被允许拥有相同权限范围的同时调用者分享新鲜读数,每个都拥有独立的注销和截止日期。 阅读开始后来电者需要新的刷新. 无法停止的原生文件系统操作会一直被跟踪,直到它们和解;随后在自己的预算范围内读取等待,防止反复被停滞的I/O没有缓存的授权快照. 超时或取消块执行,去掉等待的收听者,并阻止后读发布配置或再开始I/O.

## 常见问题

### @amaster\.ai/pi-security 是什么？

资源意识安全政策引擎和工具授权的扩展

### 如何安装 @amaster\.ai/pi-security？

在项目目录运行 npm install @amaster\.ai/pi-security，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-coding-agent（\>=0\.79\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @amaster\.ai/pi-security 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amaster\.ai/pi-security 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @amaster\.ai/pi-security 可以商用吗？

@amaster\.ai/pi-security 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @amaster\.ai/pi-security 的下载量有多少？

根据 npm 官方下载统计，@amaster\.ai/pi-security 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,821 次，日均约 127 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amaster\.ai/pi-security 还在维护吗？

最新版本 0\.1\.37 发布于 2026/11/09（今天）；至今共发布 131 个版本，其中过去 12 个月发布了 131 个；首次发布于 2026/05/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。