# @czottmann/pi-automode 中文文档

规范地址：https://npmcn.com/package/%40czottmann/pi-automode/

版本：1\.17\.0
npm 元数据更新时间：2026-09-22T15:40:02.494Z
中文译文更新时间：2026-11-11T09:08:57.975Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：299 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-06-14T14:13:15.519Z
- 最新版本发布：2026-09-22T15:40:02.053Z
- 近 30 天下载量：2552（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

Claude代码式的自动护栏.

## 安装

```sh
npm install @czottmann/pi-automode
```

也可以使用：`pnpm add @czottmann/pi-automode`、`yarn add @czottmann/pi-automode`、`bun add @czottmann/pi-automode`

## README

# pi- 自动调制

Claude Code-style 为 Pi 设计的自动模式.

这是护栏的延伸 它会截取执行前的代理工具呼叫,并屏蔽与许可匹配的动作拒绝规则,确定硬性检查,或者自动模式分类器的块决定.

这不是沙盒。 扩展运行于 Pi 进程 。 恶意扩展可以做任何用户账户可以做的.

Pi- automode 不守护用户 `!` 或者说 `!!` 贝壳命令。 它只保护代理工具呼叫。 用它来减少不安全的自主工具使用. 不要将其作为OS安全边界.

## 兼容性

Pi-automode)支持Pi和Oh My Pi(OMP) 18. 它会自动使用OMP的后遗症完成API. 整合不需要办公室管理计划的具体配置.

## 安装

从 npm :

```bash
pi install npm:@czottmann/pi-automode
```

从本地取出 :

```bash
pi install .
```

一次从本地取出:

```bash
pi -e ./extensions/auto-mode.ts
```

## 图标

```text
/automode status    # current state, rules, and classifier
/automode on        # re-enable for this session
/automode off       # disable for this session
/automode reload    # reload config from disk
/automode reset     # reset denial counters only
/automode defaults  # print the built-in rule lists
/automode config    # effective config, resolved log file path, + diagnostics
/automode denials   # denial history for this session
/automode model     # open classifier model selector and save to ~/.pi/agent/extensions/pi-automode/config.json
/automode model provider/model-id # save classifier model to ~/.pi/agent/extensions/pi-automode/config.json
```

`/auto-mode` 是一个别名.

## 代理诊断

软件包登记了一个可调用、只读的工具:

`automode_inspect` 接受一个 `action`数字 :

-   `status`: 活动状态和计数器
-   `config`: 主动有效的配置、日志路径和诊断
-   `defaults`: 内置规则列表
-   `denials`: 最近的拒绝时间戳、类型和工具名称

该工具读取了相同的内存配置并声明由护栏执行. 允许和确定性检查在绕行前运行.

绕道不会改变自动码计数器,持续状态,或可观察日志. 扩展在应用豁免前核查工具的来源。 因此,名称相撞并不能使一个工具免于另一个扩展.

该工具不能启用或禁用自动模式 。 它不能重新装入配置, 重新设置状态, 选择一个模型, 或更改配置 .

Pi向当前模型发送工具输出. 这个 `status` 财务报告和审定财务报表 `denials` 视图忽略了否定理由和动作有效载荷.

如果诊断需要理由,则检查当地可观察性日志中已知的安全条目。 这个 `config` 视图包括有效的规则文本。 它从诊断中移除了原始的JSON解析器细节.

不要把证书或其他秘密放在自动码规则中.

捆绑起来 `automode-diagnostics` 技能使用此工具来诊断出意料的决定,而不要求用户复制斜线命令的输出. 配置编辑和自动模式状态变化仍然由用户控制. 见 [代理诊断](https://npmcn.com/package/%40czottmann/pi-automode/docs/diagnostics.md) 检查合同、隐私限制和诊断工作流程.

## 状态线

当 Pi TUI 可用时, 扩展会让持续状态线:

```text
AM ● a:12 d:2 ca:5 cd:1
```

-   `AM` ——自动模版前缀. `●` 表示已启用. `○` 表示通过配置被禁用或 `/automode off`。 。 。 .
-   `a:` 迄今允许的动作(选中负数被拒绝).
-   `d:` 迄今以任何理由(许可规则、确定性硬性规定或分类)拒绝采取行动.
-   `ca:` 编号 : `cd:` ——分类决定分为允许和拒绝. 这些段出现在第一个分类器调用后. `d:` 算上所有的否认,所以 `d:` 总是 `>= cd:`。 。 。 .

## 文档

-   [配置](https://npmcn.com/package/%40czottmann/pi-automode/docs/configuration.md)
-   [权限配方](https://npmcn.com/package/%40czottmann/pi-automode/docs/permission-recipes.md)
-   [默认和规则列表行为](https://npmcn.com/package/%40czottmann/pi-automode/docs/defaults.md)
-   [自动模式分类器流](https://npmcn.com/package/%40czottmann/pi-automode/docs/automode-classifier-flow.md)
-   [观察性伐木](https://npmcn.com/package/%40czottmann/pi-automode/docs/observability-logging.md)
-   [结构决定](https://npmcn.com/package/%40czottmann/pi-automode/docs/adr/INDEX.md)

## 在分类器之前运行的

在任何允许或分类决定之前,扩展块 :

-   `permissions.deny` 匹配
-   拒绝 `permissions.ask` 匹配
-   shell 配置文件写入
-   SSH 服务器 `authorized_keys` 写入
-   cron、发射剂和系统服务持久性
-   TLS/证书/自动削弱模式
-   根、家和系统路径的破坏性删除。 经审定的发射装置申报的临时目录的子树被视为可支配的。 被宣布为别名的根 `HOME`, (中文(简体) ), `/`,或系统根,或包含 `HOME`,改为拒绝.
-   编辑到 `.pi/automode*`, (中文(简体) ), `.pi` 自动模式文件, 此扩展名的安全控制文件

这些检查之后,Pi -automode应用 `permissions.allow`保护 `write` 财务报告和审定财务报表 `edit` 目标继续到分类器.

接受的询问规则也延续到分类者。 他们不能使用允许级别。 然后允许只读工具 `read`, (中文(简体) ), `grep`, (中文(简体) ), `find`,以及 `ls`。其余的每个动作都转到分类器.

A 类 `permissions.allow` 规则故意跳过分类策略,包括分类策略 `hard_deny` 规则。 使用狭义的图案和用户拥有的配置. 确定性硬性规定和路径控制仍然是无条件的.

设定 `classifyReadOnlyTools: true` (默认) `false`)通过分级器路径只读工具。 这种配置值增加了模型调用,耐用性和会话成本.

皮-自流体块a `deniedPaths` 在分类审查或允许等级前匹配。 因此,文件工具不能向模型发送匹配的秘密或系统路径.

清单没有规定 `bash`. 分类和确定性硬性检查管理外壳进入这些路径.

数值 `allowInsideWorkingDirectory: true` 允许本地工作目录内的文件访问。 Pi-automode向分类器发送所有外部文件访问,包括读取.

分类从保守的一键过滤器开始. 如果过滤器请求审查, pi- automode 请求一个内部 `classifier_decision` 工具调用.

该工具仅存在于嵌入式分类器请求中. 未在 `pi.registerTool()`,而主要代理人不能称它.

Pi AI 请求使用 chema- contracted 采样 `strict: "prefer"`。支持提供者在生成时执行计划。 Pi-automode 本地验证每个返回的工具调用.

两个阶段都收到专用信件中完整的当前工具输入. 转写截图无法删除动作内容 。 如果准确的输入不能与分类器上下文相适应,自动模式会阻断调用.

两个阶段都使用分类器特定的会话键. 他们要求从支持它的提供者那里保留简短的缓存. 缺少模型, 提供者失败, 或无效的响应会阻碍动作 . Pi-automode 解析 Bash 结构 `unbash` 未经批准,并进行确定性硬性检查。 分析内容包括嵌入式命令和字面的 shell-wrapper脚本. Bash 解析错误会阻碍动作 .

## 实例

-   `examples/automode.local.json`: 复制到 `.pi/automode.local.json` 在工程中编辑域、桶和源控 og .
-   [权限配方](https://npmcn.com/package/%40czottmann/pi-automode/docs/permission-recipes.md): 使用狭义的示例进行通用许可并进行分类政策修改.

## 已知限制

Claude Code的真正分类器和精确的内置规则都是私人的. 此软件包执行被记录的先行和配置行为,并带有本地分类器的即时和决定性硬性检查.

## 发展

```bash
npm run check
npm test
npm pack --dry-run
```

试验涉及这些安全敏感领域:

-   范围权限匹配
-   页:1 `permissions.allow` 等级及其优先顺序
-   配置源优先和诊断
-   `$defaults` 行为
-   确定硬密度检查和Bash AST分析
-   分类器路由 `write` 财务报告和审定财务报表 `edit`
-   协同-意识安全控制检查
-   选择已编入预算的记录
-   阶段分类器工具调用解析和缓存行为
-   钩位允许并屏蔽行为

## 出版

当一个维护者发布一个 GitHub 发布时, GitHub Actions 将软件包发布到 npm. 需要的释放标签格式是 `v<version>`编辑 `<version>` 值必须与版本相同 `package.json`。例如,版本 `1.0.0` 需要标记 `v1.0.0`。 。 。 .

工作流程使用npm Trusted Publishing,因此不需要npm 令牌秘密. 使用此寄存器和工作流程文件配置 npm 上的此软件包( S)`.github/workflows/publish.yml`) (中文(简体) ). 工作流程构建软件包, 运行 `npm run check`,并用 npm出处出版.

### 释放标记必须指向版本的凸起

发布工作流程检查发布标记所识别的承诺. 它比较版本在 `package.json` 标记名称.

**标记必须识别包含新版本的承诺 .**

1.  提交版本更改方式 `chore: release X.Y.Z`。 。 。 .
2.  推开 `main`。 。 。 .
3.  从中创建 GitHub 释放 .

如果标签识别出旧版本,则 `Check release tag` 步骤失败。 报告 `Release tag (vX.Y.Z) does not match package.json version (x.y.z)`。 。 。 .

不要移动正确的释放标签 。 移动标记会更改已公布的引用 .

1.  如果标记识别出错误的实现,则强制将其移动到版本更改实现.
2.  强行推出校正的标签 .
3.  运行 `gh workflow run publish.yml --ref vX.Y.Z`。 。 。 .

当 GitHub 创建标记时 `release` 事件发生。 失败的重运行 `release` 工作流程使用原始参考. 它不使用已移动的标签 .

## 作者

卡罗・佐特曼, [卡尔洛@zottmann.dev](mailto:carlo@zottmann.dev)

-   网站: [https://actions.work (英语)](https://actions.work/)
-   GitHub : (中文(简体) ) [https://github.com/czottmann (中文(简体) )](https://github.com/czottmann)
-   布鲁斯基: [https://bsky.app/profile/zottmann.dev 互联网档案馆的存檔,存档日期2013-12-21](https://bsky.app/profile/zottmann.dev)
-   马斯托登: https://norden.social/@czottmann

## 常见问题

### @czottmann/pi-automode 是什么？

Claude代码式的自动护栏\.

### 如何安装 @czottmann/pi-automode？

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

### @czottmann/pi-automode 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/czottmann\_\_pi-automode 是否存在。

### @czottmann/pi-automode 支持 ESM 还是 CommonJS？

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

### @czottmann/pi-automode 可以商用吗？

@czottmann/pi-automode 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @czottmann/pi-automode 的下载量有多少？

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

### @czottmann/pi-automode 还在维护吗？

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