@hex4c59/pi-ext-permissions
Tool permissions for Pi with a learner mode for guided practice, investigation-focused navigator mode, temporary research scripts, manual approval, selectable Guardian-based AI review, full-argument audit logging, and explicit full access.
Package details
Install @hex4c59/pi-ext-permissions from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@hex4c59/pi-ext-permissions- Package
@hex4c59/pi-ext-permissions- Version
0.10.1- Published
- Nov 20, 2026
- Downloads
- 1,267/mo · 1,049/wk
- Author
- hex4c59
- License
- MIT
- Types
- extension
- Size
- 441.2 KB
- Dependencies
- 1 dependency · 4 peers
Pi manifest JSON
{
"extensions": [
"./extensions/permissions.ts",
"./plan-mode/extensions/plan-mode.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
permissions
Pi 工具权限审批扩展,包名为 @hex4c59/pi-ext-permissions,当前版本 0.10.0。提供人工审批 ask、调查导航 navigator、学习模式 learner、独立模型审批 auto 和完全放行 full;没有启动参数、会话选择或配置时默认 ask。Navigator 允许查询、读取项目外文档,以及为调查创建、运行和清理临时脚本;阻止直接实现最终任务。普通读取和已核实的只读工具走快速路径,其余调用由 Guardian 同时审查风险和用途,不因组合命令、正则转义或未知工具名直接拒绝。每次新模型运行都会更新当前模式提示并清除过期的 Navigator 指令,模式切换后另补一条作废旧模式的上下文说明。每个审批终态都会把完整工具参数写入审计日志。Guardian 的策略、风险/授权分级和审核会话管理由 OpenAI 官方 Codex Guardian 改编,固定来源与许可证见 THIRD_PARTY.md。
Navigator 默认采用逐步讨论或教学式指导的回复节奏:每轮只做一个教学动作,解释正文以约 200 个中文字或 120 个其他语言单词为目标,通常用 1–2 个短段落或最多 3 个简短要点。用户自己写代码时,代理不直接给完整实现;每次只指出下一步要用的概念、API、文件或错误,并提出一个具体问题,让用户推导出代码。看到用户的尝试后,先说明哪里正确,再指出失败的行或现象并询问预期,由用户自己修改;确实卡住后才给更强的提示或不完整语法片段。用户尝试前不提供类、结构体或函数骨架,只用文字描述成员和职责;存在现成 API 时,先确认是使用还是从零实现。宽泛问题只简述最多 3 个方向,再解释第一个重点;追问只解释当前困惑;“继续”承接同一教学步骤的下一个提示,不重复旧内容。解释和注释直接描述行为,避免“确认门”等生造名称。用户明确要求完整方案时,按该请求提供一次,然后恢复教学。
Navigator 的工具边界不限制回复中的代码,但默认回复不提供可直接抄写的完整实现。用户要求自己手写时,代理通过问题、API 名称、位置和最小语法片段引导,由用户写出并修改代码;只有用户明确要求某个片段,或卡住需要语法参照时才展示代码,并要求用户用自己的话说明。这个分工跨轮延续,无需每轮重新索取要求或确认。用户说“继续”时推进同一教学步骤的下一个提示,不因文件尚未修改而重复原步骤。例如,已经讨论“自己手写 permissions,先做 ask”后,再说“那就先做 ask”,应开始 ask 的第一个教学提问,而不是给出完整入口代码,也不应要求先执行 /permissions ask。用户明确要求代理实际改一处时,可用 单次编辑。需要更大范围的实现时切换到 ask、auto 或 full。功能名 ask 与当前会话权限模式分别理解。普通概念讨论仍保持简短,不主动堆出完整实现或结尾问题菜单。
为减少上下文占用,Navigator 提示模型先复用已有证据;代码或类型已经给出的概念问题直接解释,只有具体事实缺失、版本变化或用户要求检查修改时才重新查询。检索优先使用文档、.d.ts 和源码,避免为基础 API 问题递归搜索压缩包产物;搜索时同时限制字节、行宽和行数,head -10 不能限制单行很长的压缩文件。可使用 rg -o,或 --max-columns 200 --max-columns-preview 获取短片段。代理应自行获取可访问的事实,不把文件查询推给用户。建议开发依赖时采用已核对的运行版本;只有读到明确规则时才声称某参数是仓库要求。以上回复和检索方式仍依赖模型遵循;下文的工具结果预览由扩展实际执行,不限制回复字数,也不会清除已有历史。
开启、切换与关闭
发布到 npm 后可直接安装:
pi install npm:@hex4c59/pi-ext-permissions
本地源码安装与临时试用方式如下。
从本仓库根目录临时加载,不写安装配置。-ne 关闭扩展自动加载,避免 npm 版和源码版同时运行。需要一起测试自定义 provider 或其他扩展时,分别用 -e 指定其入口。
pi -ne -e ./permissions/extensions/permissions.ts
临时加载完整包时使用:
pi -ne -e ./permissions
会话内命令:
| 命令 | 行为 |
|---|---|
/permissions |
TUI 中打开权限模式选择菜单;单击模式可直接切换,也可用键盘操作;RPC 中打开标准选择菜单;print / JSON 中显示当前状态 |
/permissions ask |
普通项目只读操作直接放行,其他操作人工确认;无其他模式来源时的默认值 |
/permissions plan |
加载 plan-mode 后进入真正的只读计划模式;保留当前基础审批策略;Navigator 下也可进入,批准后的实施仍受基础权限限制 |
/permissions navigator |
允许读取、搜索及调查所需的临时脚本和清理。普通读取直接执行,其他调用由 Guardian 审查风险及调查用途。最终任务的工具写入默认阻止 |
/permissions learner |
学习模式:保留只读调查边界,并允许编译和运行用户自己的练习程序;目标、验收条件与步骤由 learn_progress 写入会话,/learn 查看 |
/permissions edit-once <path> |
在空闲的 Navigator TUI 或 RPC 会话中,准备下一次用户请求对指定文件的一次确认编辑 |
/permissions auto |
普通只读操作直接放行,其他符合条件的调用交给 Guardian。压缩后从当前分支恢复可核对的用户原文。审阅失败时,已证明只读的本地读取降级放行,其余转人工 |
/permissions full |
本扩展完全放行后续工具调用 |
/permissions status |
查看当前模式、审批模型、本轮审批次数和降级放行次数 |
/permissions model |
TUI 中打开按 provider 分组、可搜索的审批模型选择器;RPC 使用模型列表 |
/permissions model <provider>/<model-id> |
精确指定独立审批模型并跨会话保存,不切换主代理模型 |
/permissions model session |
跨会话保存“跟随主代理模型”的选择;未设置时的默认行为 |
/permissions log |
显示审计日志路径和最近的写入错误 |
/learn |
显示当前学习目标、验收条件、正在进行的步骤和已完成步骤 |
Ctrl+Alt+P |
TUI 主输入框中按 ask → plan → navigator → learner → auto → full → ask 循环;未加载 plan-mode 时跳过 plan |
在主输入框按 Ctrl+Alt+P 会切换模式并更新底栏,不弹出切换成功通知,输入草稿保持原样。每次新模型运行都会重建当前权限模式提示,并清除不再生效的 Navigator 指令。切换模式后,下一次模型请求还会追加一条权限变更说明:它作为用户可见上下文进入 transcript(不写入会话分支),明确作废此前所有权限模式分区。这是因为部分 provider 会丢弃会话中段的 system 补丁,只靠重建系统提示时模型可能继续沿用旧模式。同一模式只补一次,说明追加在完整 transcript 末尾,保留已有 system 消息和缓存前缀。它取代旧的 F7 权限循环,并将原 Ctrl+Alt+P 计划快捷键改为统一权限循环;fullscreen TUI 中同时加载 compact-footer 时,单击底栏权限徽标会打开同一选择器,再次单击该徽标可关闭选择器;模式保存、计划切换和旧审批失效都复用此处逻辑。通过 /hotkeys 可查看已加载的快捷键。快捷键与权限命令、菜单共用状态变更流程,保存当前会话分支的选择并取消旧审批;恢复、分支切换和 /reload 仍遵守现有启动参数优先级。RPC、JSON 和 print 继续通过命令或启动参数选择模式。显式状态查询和切换失败的提示仍会显示。
带参数的命令可以直接执行,例如 /permissions auto。单独输入 /permissions 并按 Enter 会打开交互式选择菜单:当前模式默认排在第一项,用上下键选择 ask、plan、navigator、learner、auto 或 full,Enter 确认,Esc / Ctrl+C 取消。fullscreen TUI 下单击任一模式会立即应用;滚轮只移动高亮,每步一个选项,同方向短间隔的密集事件会合并,避免一次滚轮动作跳过多项,反向滚动立即响应,到列表边界停止;regular TUI 仍可使用键盘。plan-mode 已加载时即提供 plan 选项,不受当前基础权限模式影响,也可通过 /permissions plan 选择;已有独立恢复的活动计划时仍会列出,以便切换离开。未加载时请求 plan 会报告错误,不创建虚假的计划状态。模式菜单没有倒计时或自动关闭时限,会一直等待选择或取消;菜单打开期间会话、模式、模型发生变化时,不应用旧选择。RPC 客户端通过官方 select 协议显示菜单;print / JSON 没有交互菜单,单独输入命令时只显示状态。
状态栏使用英文,仅显示当前权限模式:Permissions: ask、Permissions: navigator、Permissions: learner、Permissions: auto 或 Permissions: full;审批期间也保持这一简洁显示。审批模型和本轮审批次数可通过 /permissions status 查看。命令说明、确认框、通知和错误消息也使用英文;文档和代码注释使用中文。参数输入到一半时可用 Tab 补全。Navigator 下也会补全 edit-once,然后填写目标文件路径。切换到 full 就能关闭本扩展的审批;其他扩展仍可能阻止工具执行。full 不增加操作系统权限。
与本仓库 plan-mode 一起加载时,可选 permissions:tool-check 事件会先应用计划模式的限制,避免先请求普通工具许可、随后又被计划模式拒绝。plan-mode 会按实际注册来源识别其四个内部工具,并自行处理进入确认、固定路径的计划保存、计划审批和进度;在 ask、auto、full 下,这些工具不重复经过 permissions 审批或写入其工具审计日志。Navigator 下则仅活动规划期间的 save_plan 与 exit_plan_mode 例外交由 plan-mode 处理,其余内部工具仍按只读策略检查。计划状态由会话条目保存。批准计划保留当前基础审批策略,不能由基础策略 full 绕过只读限制。Navigator 保留最终任务的实现限制;计划进行中仅允许 plan-mode 专用的 save_plan 与 exit_plan_mode 通过固定计划存储和审批流程。批准计划不会改变基础 Navigator 权限;项目交付文件的修改仍会被阻止。
两包通过可选 plan-mode:control / plan-mode:changed 事件协作。Ctrl+Alt+P 读取真实计划状态,按 ask → plan → navigator → learner → auto → full → ask 循环;plan-mode 未加载时跳过 plan。从 /plan 命令或恢复会话进入的规划、待审批状态都视为 plan。plan 期间 compact-footer 显示浅蓝色纯文字 plan(无背景块),通过 /permissions status 可同时查看基础审批策略。切到 navigator、auto、ask 或 full 会主动结束计划限制并恢复原工具;这不记录计划批准,也不自动开始实施。Navigator 下也可进入计划草稿;保存与提交由 plan-mode 的专用工具完成,但批准不会解除 Navigator 的任务实现限制。可在计划执行阶段用 edit-once 确认一处小改动,更大范围的修改需要切换到 ask、auto 或 full。手工切换计划模式需要会话空闲,运行中可先用 Esc 中断。计划内容、工具快照和计划状态仍由 plan-mode 保存,--permissions 和 permissions.defaultMode 接受 ask / navigator / learner / auto / full;启动规划使用 --plan。
可在启动时明确选择模式,适用于 TUI、RPC、print 和 JSON:
pi -e ./permissions --permissions navigator
pi -e ./permissions --permissions navigator --print "Inspect the source and propose the required change"
pi -e ./permissions --permissions auto --print "Create the requested project source file"
--permissions ask|navigator|learner|auto|full 显式指定时,优先于已保存的会话选择和配置,并在新会话、恢复、分叉、/tree 和 /reload 时重新应用。不传参数时,使用当前分支保存的模式或 permissions.defaultMode;均不存在时为 ask,完整规则见默认模式与继承。
模式切换通过 permissions-mode 条目保存到当前会话分支。没有显式启动参数时,恢复会话、分叉、/tree 和 /reload 会沿用该分支的选择;新会话没有分支记录,使用配置默认值。会话内命令可临时改选模式;存在显式启动参数时,下次恢复或重载仍以启动参数为准。模式切换、会话结束、主模型或审批模型切换、收到新的运行请求和取消执行会使待审批的操作失效。没有供模型切换模式或审批模型的工具。审批模型偏好单独跨会话保存,具体规则见下文。
需要长期使用时,由使用者在仓库根目录安装:
pi install ./permissions
卸载:
pi remove ./permissions
修改本地源码后用 /reload 重新加载。通过 -e 临时加载时,退出该进程即结束本次加载。通过 npm 升级到新版本后同样需要重启 Pi 或执行 /reload;仅新建会话不会重新加载已安装的扩展代码。
Auto 压缩续接修复从 0.10.0 起生效。若 0.9.0 在压缩后提示 Compaction removed the latest user request,可先用上述命令临时加载源码测试。使用 npm 安装的会话需要更新到包含修复的版本,再重启 Pi 或执行 /reload。
本次默认模式修复的更新方式:从修复前的版本更新时,需完整退出并重新启动一次 Pi。Pi 1.5.0 的 /reload 会复制旧运行时的参数值,包括旧扩展注册的 ask 默认值;仅重载无法清除它。重启后,后续 /reload 按下文的新优先级恢复模式。
Auto 下的计划分流
空闲的 Auto 会话收到「先给方案,再实施」「写详细实施计划」等明确指令时,会在首次模型请求前进入只读 Plan,并启用 save_plan 和 exit_plan_mode。中文和英文的常见指令均可触发。普通问答、引用、扩展注入的消息和小范围修复沿用原流程。明确要求「不用写计划,直接实施」可让当前任务继续使用 Auto。已有活动计划仍需审批或手动退出。
跨模块契约、迁移旧数据库等明确的复杂改动直接进入 Plan。范围难以判断的实施请求最多用当前会话模型分类一次,限时 5 秒。模型只收到本轮去掉常见引用的文本,无工具及历史,超过 4096 UTF-8 字节或疑似含凭据时跳过。超时、服务异常或无效回答沿用 Auto。调查期间如果发现范围扩大,代理可在一次核实的内置只读操作成功后,单独调用 enter_plan_mode。发起可能改变状态的工具、切换会话或收到新输入会结束本轮的自动进入资格。
明确规划请求在会话忙碌或进入失败时暂停。等当前运行结束或中断后重发。自动开始的新计划使用空草稿,旧版本保存在原会话记录中。TUI 和支持 extension UI 的 RPC 使用当前版本的审批。JSON / print 可保存并提交,恢复到有界面的会话后用 /plan approve 审阅。批准后按基础 Auto 审查每个工具。
计划正文采用 Codex 风格的可实施 Markdown,TUI 在聊天中展示 Proposed Plan,通过底部 Implement this plan? 提供实施、修订和继续规划。范围、接口与验证写法见 计划正文。
选择审批模型
首次使用默认 session 跟随主代理模型。用 /permissions model 打开选择器,可以选择已配置认证的聊天模型;确认后跨会话保存,新终端、新会话和其他项目会沿用。设置了 Pi 的 scoped models 时,选择器沿用该范围,否则列出全部可用聊天模型。
TUI 采用与 compact-footer 的 /model 相同的分组交互:上方显示 provider 标签,左右键切换 provider,直接输入文字搜索当前 provider 的模型名或 ID;F2 打开可搜索的 provider 列表,Enter 浏览,Esc 返回并恢复先前搜索。模型列表最多显示 5 项,上下键移动,PageUp / PageDown 翻页;选中项与快捷键沿用 Pi 自定义键位。模型名旁显示上下文容量,有倍率信息的 provider 显示独立倍率列。默认定位当前审批模型所在的 provider 和选项;session 在每个 provider 的列表首项提供,搜索时可输入 session 找到它。鼠标滚轮移动,单击选中,双击确认。选择器独立于 compact-footer,单独安装 permissions 也可使用。RPC 保留官方 select 模型列表。
模型选择菜单不设自动关闭时限,Esc / Ctrl+C 或取消均保留原偏好。菜单打开期间会话、模式、主模型或审批模型发生变化时,取消旧选择;确认时重新检查所选模型是否仍在可用范围。选择模型本身不会开启 auto,使用者仍需显式切换模式。
也可直接指定完整标识,例如:
/permissions model my-provider/review-model
/permissions auto
/permissions status
只接受精确的 provider/model-id,不做模糊匹配,不接受仅有模型名的写法;模型 ID 自身可以含斜杠。模型来自 Pi 已有的内置、models.json 或扩展注册表,复用所选提供方自己的 API 地址和认证,不新增密钥文件。图片和分类模型不在选择范围。主代理的 /model、默认配置和推理级别均不受该选择影响;审批请求继续使用 minimal 推理及原有预算,提供方按模型能力处理。
可通过启动参数配置,适用于 TUI、RPC、print 和 JSON:
pi -e ./permissions --permissions auto --permissions-model my-provider/review-model
my-provider/review-model 是占位示例,请替换为 Pi 中已配置且具有认证的实际模型标识。上下文容量、输出限制、支持的推理等级和费用由所选模型及提供方配置决定,本扩展不附带个人模型配置或凭据。
审批模型偏好保存在 getAgentDir()/permissions/preferences.json,默认位置是 ~/.pi/agent/permissions/preferences.json;设置了 PI_CODING_AGENT_DIR 时跟随该目录。文件只保存 { "model": "provider/model-id" } 或 { "model": "session" },没有认证或审批正文,不改写 Pi 的主模型配置、settings.json 或其他扩展设置。通过选择器或完整命令选择都会保存;即使使用 --no-session,这项独立的全局偏好也会保留。
恢复优先级为:显式 --permissions-model → 已保存的跨会话偏好 → 旧会话分支记录 → session。首次从旧版本升级、尚无全局偏好且没有 CLI 覆盖时,自动把当前旧会话的模型选择迁移一次。迁移后,恢复旧会话、分叉、/tree 和 /reload 都读取全局偏好,历史记录不会覆盖较新的全局选择。全新会话没有旧记录时,保持默认 session,不自动创建偏好文件。
--permissions-model session 明确临时选择跟随主模型;完整模型标识同样只覆盖当前进程。显式启动参数在启动、重新加载、恢复或新会话时重新应用,本身不写入全局偏好。命令选择仍会更新全局偏好并立即用于当前会话,重新加载时若存在启动参数则重新采用该参数。JSON / print 没有选择弹窗,可使用启动参数或完整命令;不带参数的 /permissions model 仅显示当前偏好和用法。其他已经打开的终端在新会话或 /reload 时读取最新偏好。
命令指定不存在、无认证或格式错误的模型时,保留原偏好并提示。偏好写入失败时也保留当前审核模型。已经保存或经 CLI 指定的模型后来不可用、缺少认证或配置无效,或全局偏好文件损坏、不可读时,auto 转人工,不会静默换回主模型或其他提供方。显式重新选择有效模型可以修复损坏的偏好文件。切换审批模型会取消正在等待的旧审批;下一次调用使用新模型。/permissions model session 可跨会话恢复跟随主模型。
审查提示词缓存
启动 Pi 前,将 PI_PERMISSIONS_REVIEW_CACHE_MODEL 设为要启用短缓存的完整 provider/model-id。只有实际选中的审查模型精确匹配该值、且使用 openai-responses 时,扩展才请求 short。PowerShell 示例使用的是占位模型名。
$env:PI_PERMISSIONS_REVIEW_CACHE_MODEL = 'my-provider/review-model'
pi
short 使用兼容端点的普通提示词缓存,同一审查会话可复用缓存键。有效期和命中由端点决定。未设置或未匹配时使用 none,Pi 会省略审查请求的缓存键和会话路由头,端点仍可能自动命中。重建审查上下文时,扩展生成新的审查会话 ID。
ask 的放行范围
| 操作 | 规则 |
|---|---|
内置 read |
当前工作目录内、实际指向普通文件且不涉及敏感路径时放行 |
内置 ls、find |
当前工作目录内的普通目录浏览、文件名搜索放行 |
内置 grep |
普通文件可直接搜索;目录内容搜索先检查整个树的名称、文件类型和链接 |
write、edit |
每次均由使用者确认 |
bash、powershell |
只有下表列出的命令形式可能自动放行,仍检查完整参数和实际路径 |
| MCP 和其他自定义工具 | 每次均需确认,不采信工具自报的 readOnlyHint |
codemode |
ask 下每次均需确认;仅 Navigator 的严格形状、有界超时只读脚本经核实可放行,见下文 |
这里的“项目范围”是当前会话的工作目录及其子目录,不自动扩大到父目录或 Git 仓库根目录。ask 模式下,项目之外的读取也需确认;auto 对内置 read 的范围见下文。
内置 read 的可选 offset、limit 支持省略或传 null,两者都表示未指定。获准后会移除这些空字段,避免原工具将 limit: null 当成读取零行;负数、非数字和未知字段仍需确认。
识别的常见敏感路径包括 .env 及其变体、.ssh、.gnupg、.aws、.azure、.kube、.docker、.pi、.git、.npmrc、认证文件、凭据目录以及常见私钥和密钥库文件。路径中的大小写、尾部点、@、file URL、Windows 盘符路径和 MSYS 盘符形式均参与判断;Windows 网络共享、设备路径、盘符相对路径和备用数据流需确认。
已有文件使用 realpath 检查实际位置;同一项目经不同本地联接入口访问时,按真实目录身份识别。ask 下指向项目之外的符号链接、Windows 目录联接需确认;敏感位置、不能可靠解析的路径、非普通文件和未知参数也交给人工。
内置目录内容搜索最多检查 4096 个目录项和 32 层目录;自动放行的 rg 内容搜索使用 65536 项预算并补充 --no-follow,因此链接项可直接跳过而不进入搜索范围。两种检查都不读取文件正文、不缓存结果。范围内存在敏感项、未跳过的符号链接、联接、特殊文件,或检查失败、超出预算时,需要确认。不会依赖 .gitignore 或 glob 来证明整个范围安全:即使搜索 *.ts,包含 .env 或 .git 的范围仍会询问。将路径缩小到普通 src 目录或单个文件可减少确认。ls、find 只列出名称,正常浏览普通目录不会因此询问。
Navigator 的调查边界
navigator 用于了解、分析和讨论最终任务,也可指导用户手动实现。边界按工具操作的用途判断:允许收集证据和临时调查工作,阻止代理通过工具直接改动最终任务的源码、测试、配置、文档及其他交付文件。修改任务文件的脚本、重命名、删除和嵌套工具调用也属于实现;把它们放进临时目录不会改变用途。在回复中给出代码或 diff,由用户自行应用,不属于代理执行任务修改;回复默认仍以提问和提示引导用户自己写。
| 操作 | 处理方式 |
|---|---|
| 普通内置读取、目录列举与文件查找 | 核验真实路径后直接放行,包括项目外普通本地文件;Pi .pi/agent/install/releases/*/node_modules/ 的安装文档可直接读取;同路径中的 auth.json、.env 等仍检查 |
| 项目内受限 shell 查询、已核实的只读 LSP 和简单 codemode 批处理 | 保留静态快速路径;Bash 单引号中的正则反斜杠按字面参数解析 |
| 组合命令、管道、递归搜索、普通 JavaScript codemode、MCP、其他注册工具 | 提交完整参数和注册来源,由 Guardian 判断实际风险及用途;不因语法不在静态解析子集而直接拒绝 |
| 创建、修改、运行和删除临时调查脚本、探针与一次性产物 | 可经 Guardian 放行;审阅实际内容和副作用,不能只凭临时文件名认定安全 |
| 删除或清理文件、测试、构建、下载、安装等辅助操作 | 不按操作名一律禁止;确认它们服务于调查或已授权的文件操作,并遵守风险策略和最终任务边界 |
| 直接实现最终任务,包括脚本或工具间接修改交付文件 | 默认阻止。一处小替换可走下文的单次确认,较大改动需切到 ask、auto 或 full |
Guardian 在 Navigator 中必须额外返回 navigator_scope:research、implementation 或 uncertain。只有 research 可自动获准;即使模型返回低风险 allow,宿主仍将 implementation 转为拒绝、将 uncertain 转为人工确认。缺失或无效分类不会自动放行。用途分类依赖审批模型判断,并非文件系统隔离。
Navigator 与 auto 共用 /permissions model 选择的审核模型;未显式选择时跟随主模型。命中快速路径的读取不调用模型;其余操作会发送当前分支的用户证据、宿主约束、完整调用和注册元数据,必要时通过有界只读 API 调查本地事实。审核失败或仍有重要事实不明时,TUI / RPC 使用 Allow once / Deny;print / JSON 无法人工确认时阻止该调用。一次性确认不改变后续权限。
回复提醒
TUI 和 RPC 会在 Navigator 本轮结束后检查最后一条成功回复的可见正文,符合条件时独立显示一条中性通知,完整保留原回复。首版检查至少 20 行非空代码的代码块、至少 12 行实际增删的 diff,或同时包含至少 3 个编号步骤和约 500 个中文字符或 300 个英文词的说明。短代码、日志和单独的字数超限不触发提醒。工具中间回复、失败和中断均跳过检查,print 和 JSON 保留原有输出。
在请求开头加 完整方案: 或 Full solution: 可跳过该请求的提醒。检查只是粗略判断,短但完整的实现可能漏报。
单次编辑
先在空闲的 Navigator TUI 或 RPC 会话中输入 /permissions edit-once src/foo.ts。收到准备成功的通知后,另发一条普通请求,例如「请把 src/foo.ts 的默认重试次数从 2 改为 3」。
- 本轮允许已核验的只读查询,以及对指定文件的一次直接内置
edit。write、Shell 写入、嵌套edit和其余未经核验的调用会被拦截。普通 Navigator 调查仍由现有策略和 Guardian 审查。 - 目标必须是工作目录内已存在的 UTF-8 普通文件,大小至多 1 MiB。只接受一组能唯一精确匹配的
oldText/newText,前后片段合计至多 12 行和 2,048 个 UTF-8 字节。检查会拒绝文件符号链接、目录联接、硬链接、外部路径、敏感路径和疑似含凭据的参数。 - 扩展先以内存副本核对宿主
edit的输出。确认框显示实际路径及包含真实换行符的完整转义文本,默认选中Deny。如果内置工具会改变匹配片段之外的内容,例如统一文件中混用的换行符,审批会终止。主动选择Allow once后,扩展复查当前请求、工具、参数、文件身份和内容,通过后执行。终端放不下完整预览时终止审批。RPC 将完整预览和Deny、Allow once按此顺序发给客户端。 - 首次合格调用在打开确认框前消耗机会。拒绝、取消、确认失效、显示或执行失败都不会产生第二次机会。权限只存于进程内,本轮结束、模型或模式变更、换分支、换会话或
/reload都会使其失效。规划和待审批阶段优先应用计划限制。
验证记录来自同一尺寸与主题下的真实 Pi 1.5.2 会话。对比 GIF 保存在维护者工作副本的 quality/ui/:navigator-reply-reminder-0.8.9-*.gif 与 navigator-edit-once-0.8.9-*.gif,该目录不入库、不随 npm 包分发。
调查结果预览
Navigator 下,来源核实为 Pi 内置的 read、bash、powershell、grep、find、ls,以及可信 shell-encoding 覆盖,在单个纯文本结果超过 120 行或 8 KiB 时只返回首尾预览。预览最多保留 120 行、8 KiB 原文,另附省略提示和完整工具结果的临时文件路径;首行自身过长时保留末尾片段。模型应缩小搜索范围或按段读取,不能把预览当成完整证据。
完整工具正文保存到系统临时目录的 pi-navigator-output-*/output.txt。若原工具此前已经截断,临时文件保存的是原工具返回的正文,不会还原此前省略的内容;shell 原有的 full_output_path 保持不变,预览也保留原全文路径,避免丢失上游日志入口。写入结束后才返回路径;保存失败时不返回裁剪补丁,由 Pi 报告扩展错误。临时文件可能包含私有内容,按普通工具日志保管,需要时由用户清理;扩展不启动后台清理任务。
预览适用于 TUI、RPC、print、JSON,也适用于经过工具管线的嵌套读取。内置 read 的结构化字符串和 shell 的 output 同步返回预览;shell 的 truncated 标记省略,没有上游全文路径时才将 full_output_path 指向本次缓存。图片、多块内容、未知结构化格式和来源未核实的工具保留原样;details、错误状态、退出码、耗时与用量不变。其他权限模式仍使用各工具原来的输出限制。预览只减少工具执行完成后返回给模型和程序调用方的正文,不限制操作本身、流式进度、主代理回复或已有会话历史。
快速路径与执行复核
只读 LSP 快速路径仍要求来源为 @ian-pascoe/pi-lsp、操作在固定查询清单内、参数形状和项目内真实文件路径通过核验。可信 shell-encoding 只替换输出解码,沿用内置命令检查;其他同名覆盖需审核。readOnlyHint 本身不能建立信任。
codemode 的快速路径仍接受有界 // @options: 和单条 return await Promise.allSettled([...]) 字面调用模板;普通变量、过滤、工具发现及其他脚本形式进入用途审核。所有嵌套工具仍逐条经过 tool_call,外层脚本获准不能替内层任务写入取得许可。
LSP 的 file_path 按已核对的 pi-lsp 0.15.5 语义解析:只移除开头一个 @,保留 Unicode 空格,不套用内置文件工具的路径转换。PowerShell 主目录相对路径等无法静态解析的形式转入审核,不因解析器不支持而直接拒绝。
审核批准后继续复核精确参数、工具注册、用户证据、计划版本及已调查事实,再冻结实际执行参数。auto 与 Navigator 的审核 checkpoint 分离,切换模式会使旧审核失效。审计日志中,直接放行记为 allowed,模型放行记为 reviewed_allow,模型未完成时对已证明只读的本地操作降级放行记为 degraded_allow,人工批准记为 approved,模型拒绝记为 denied。
Navigator 的逐步讨论和按需读取约定保持;被阻止的工具修改应在回复中给出下一教学提示,或用户明确要求的片段,无需为此切换模式。它仅覆盖 Pi 工具调度,不拦截用户自己的 ! / !! 命令或其他扩展的直接 I/O。与 plan-mode 同时加载时,planning / review 期间仍遵循更严格的计划工具边界;批准计划不会解除 Navigator 的工具修改限制。
pi -e ./permissions --permissions navigator
pi -e ./permissions --permissions navigator --print "Inspect the source and propose the required change"
学习模式(learner)
learner 用于“用户自己写、代理只教、程序真的跑起来”的学习循环。适用场景不限语言:C++ 基础语法、后续 Rust / TypeScript,以及音视频、agent 开发这类边做边学的主题。
它与 navigator 的差别只有两处:
- 保留只读研究边界。普通读取、已核实只读工具仍走快速路径,其余调用仍由 Guardian 审查风险与用途;修改用户的源码、测试、配置或文档仍被阻止。代理不得替用户写实现,回复以问题、API 名称、文档位置和最小语法片段为主。
- 可以直接编译并运行用户的练习程序。学习循环每轮都要看真实运行结果,逐次调用审核模型会把反馈拖到不可用。
learner对满足下列形状的命令直接放行,不调用模型、不弹确认框。
| 允许直接运行的形式 | 说明 |
|---|---|
| 单条字面命令 | 一次调用只跑一条命令;管道、重定向、&&、;、` |
| 首词为固定工具链 | g++、gcc、clang++、clang、c++、cc、cl、clang-cl、rustc、cargo、node、tsx、ts-node、tsc、python、python3、deno、bun |
| 解释器需带脚本 | node、tsx、ts-node、python、python3、deno、bun 必须执行一个工作目录内已存在的脚本文件;node --version、bun install、deno task build、python -c1 都不在快速路径内(`deno run |
MSVC /Option |
cl、clang-cl 的 / 开头的选项单独处理:形如 /EHsc、/std:c++17、/DNAME=1 可以直接放行;含 /、\ 或额外 : 的(如 /Fe:..\out.exe)回到常规路径检查,通常被拒绝 |
cargo 子命令 |
子命令必须是第一个词,只限 build、run、test、check、clippy、fmt、doc;cargo -Z build install x、cargo install、cargo publish 仍需审核 |
| 工作目录内的可执行文件 | ./main 这类显式相对路径允许尚未生成(按上级目录核定范围),所以编译完再单独跑一次即可;裸 main 必须已存在于工作目录,才不会被 PATH 解析代替 |
| 参数路径 | 每个非选项参数都必须解析到工作目录内且非敏感路径;不存在的输出文件按最近的已存在上级目录判定 |
| 选项里的路径 | --outDir=../x、-isystem/usr/inc、-include../x.h、-o../x、-Wl,-rpath,/tmp、-Wp,-include,../x.h 里的路径片段都按路径核验;普通开关值(如 -O2、-std=c++17、/std:c++17)不受影响 |
| 响应文件 | 任何参数里出现 @ 都回到审核(含 -Wl,@file):响应文件内容不解析,无法证明范围 |
以下形式仍进入 Guardian 审核或人工确认:bash -c、sh/npm/pnpm/npx/make、解释器的内联代码开关(-c、-e、-m、-p、--eval、--require 等,只对解释器生效)、标准输入、cargo install/publish/add、管道、||、重定向、cmd.exe /c 包装、NAME=VALUE 前缀、&& 串联,以及任何路径超出工作目录的参数。
注意 -c 只对解释器受限:g++ -c main.cpp(只编译)与 cl /c 仍在快速路径内,但不算“运行过程序”。
代价说清楚:编译和运行现在是两次调用(cl /EHsc main.cpp → ./main.exe)。把两句写在一条命令里能少一轮,但需要额外处理 && 分段、cmd 包装与环境变量前缀,这一版选择不做。
已知边界:白名单只看命令形状和参数路径,不解析配置文件内容。tsconfig.json、Cargo.toml、CMakeLists.txt、build.rs 等可以自己把输出目录指到工作目录外,也能执行构建脚本。这类差异不再逐条追修:命令形状一旦超出白名单就回去审核,而需要真正的强限制请用 ask、auto、容器或虚拟机。
放行即等于在本机真实执行代码,没有沙箱。 g++ 的 -include、模板实例化和 cargo run 的构建脚本都可能在编译或运行时执行任意代码。只在你愿意自己跑这些命令的项目里使用 learner;它不增加操作系统权限,也不隔离网络或进程。
白名单是便利措施,不是安全边界。 它只做两件事:省掉每轮编译运行的审核往返,减少误触到危险命令的机会。它挡不住你运行的代码本身:./main 一旦被允许,程序内部想做什么都做得到。所以不要再指望靠它隔离不可信代码——这个模式的前提就是“这些代码是我自己的”。判断标准用一句话:愿不愿意在这个目录里自己敲同一条命令。不愿意,就换 ask、auto,或把练习环境放进容器/虚拟机。
学习进度与强制项
learn_progress 工具把目标、验收条件、当前步骤和已完成步骤写入 permissions-learn 会话条目,不进入模型上下文;恢复会话、/reload 和 /tree 切换分支时按当前分支重建,/learn 随时查看。
- 第一轮只要求两件事:这轮要能跑的程序,以及能证明它工作的输出。没有目标就调用
set-goal,不存在“先写代码后补目标”。 set-step写入当前步骤;advance完成当前步骤并归档到已完成列表。advance必须自上次推进以来有一次成功的程序运行;没有运行、运行失败、运行被拒绝,或刚设定新步骤时都会被拒绝并返回原因。只编译、只查询(g++ -c、cargo build、tsc --noEmit、node --version)不算运行。这是本模式唯一由扩展强制执行的规则,其余节奏靠提示词约束。- 会话切换、
/tree换分支和切模式都会清掉这条运行证据,需要重新运行。 - 用户明确要求代理直接改文件时,说明
learner不改练习文件,需要代改就切到ask、auto或full。learner不提供edit-once。
与 plan 一起使用时,plan-mode 的 permissions:tool-check 仍先生效,规划期间只允许 save_plan 与 exit_plan_mode;批准计划不会解除 learner 的文件修改限制。
本地直接放行的命令子集
本节只描述无需模型审阅的快速路径。ask 下未通过这些检查的调用需人工确认;auto 下进入 Guardian 风险审阅;navigator 与 learner 下则额外审查是否属于调查,命令形式不在快速路径不会直接导致拒绝。
扩展使用保守的字面参数解析,不尝试理解任意 shell 程序。支持单个命令和简单的独立单、双引号参数。
| Shell | 可自动放行的形式 |
|---|---|
| Bash | pwd,可带 -P、-L |
| Bash | ls,只接受 -a、-A、-l、-h、-1、-d、-F 及其组合;目标须通过路径检查 |
| Bash | cat [--] <一个或多个普通文件> |
| Bash | grep 的受限只读参数(含 -n、-i、-F、-r、-E、-w、--include、--exclude-dir 等);按实际目标执行与内置搜索相同的范围检查 |
| Bash | head、tail、wc、sort、uniq 作为只读过滤器;可单独读文件,也可作为管道末端消费输入 |
| Bash / PowerShell | git --version;git status 的受限显示参数;git diff 的受限统计参数或以 -- 指定的普通文件;status/diff 还须通过过滤器配置检查 |
| Bash / PowerShell | rg 的受限搜索参数;按实际目标执行与内置搜索相同的范围检查 |
| Bash / PowerShell | 安全复合命令:每一段都必须是上表可放行的只读命令。cd <字面目录> && 仅切换后续段的工作目录;` |
| PowerShell | Get-Location;Get-Content -LiteralPath <普通文件>;Get-ChildItem -LiteralPath <普通目录> |
Git status 接受 --short、-s、--branch、-b、--porcelain[=v1|=v2] 和明确的 --untracked-files=... 参数。Git diff 接受 --stat、--numstat、--shortstat、--name-only、--name-status、--cached、--staged、--no-ext-diff、--no-textconv;输出正文时必须以 -- 指定普通文件。版本范围、目录 pathspec、magic pathspec、输出文件选项和未限定范围的正文差异需确认。
Git status/diff 自动放行前,还会用受限的 git config --includes --null --name-only --get-regexp 查询有效配置键,包含系统、全局、仓库、条件 include 和继承的 Git 环境配置。只要存在 filter.<name>.clean 或 filter.<name>.process,就需要人工确认,因为这两种过滤器可能启动外部程序。即使过滤器尚未绑定当前文件,或者命令带 --cached,也采用同样的保守规则。
配置查询最多等待 2 秒、接收 16KiB 输出;查询失败或超出限制时需确认,取消时阻止调用。查询只检查配置键,不执行待审批的 status/diff,也不展示配置值。没有这些过滤器且参数检查通过时,普通 Git status/diff 仍可自动放行。
自动放行的 Git status/diff 会补充 --no-pager、--no-optional-locks、-c core.fsmonitor=false、-c core.untrackedCache=false;diff 还补充 --no-ext-diff、--no-textconv,以抑制分页器、fsmonitor、外部 diff/textconv 和可选写入。自动放行的 rg 会补充 --no-config;内容搜索还会补充 --no-follow,避免继承配置中的 --pre / --follow 或跨越链接。
rg 接受 -n、--line-number、-i、--ignore-case、-F、--fixed-strings、--hidden、-l、--files-with-matches、--files、--no-config、--no-follow、独立的 -g/--glob 及 -m/--max-count 参数。混合 --files 与内容搜索参数、其他未知参数需确认。
重定向(>、>>、<)、分号、||、后台执行 &、变量和命令展开、未加引号的通配符、多行脚本、拼接引号及未知语法都需确认。&& 与 | 只在每一段都能静态证明只读时放行(见上表):任一段包含写操作、未知命令或越界读,整段转人工。Bash 参数中的反斜杠仅在完整单引号字面参数内支持直接放行;其他位置仍需后续审批。Windows Bash 路径优先使用正斜杠。PowerShell 使用通配路径、-Recurse、脚本块、弯引号、未加引号的逗号数组或非 ASCII 空白分隔参数时需确认。逗号属于单个文件名时,应使用 ASCII 引号包住整个路径,例如 Get-Content -LiteralPath 'src/main.ts,.env';这样仍按单个普通路径检查。
ask 不通过命令前缀自动授权:git status; ...、rg --pre ...、find ... -exec ...、python ...、npm test 等都不会直接放行。auto 会将未直接放行的完整工具调用送审,包括脚本、组合命令和其他已注册工具,规则如下。
auto 的审批范围与数据
普通本地只读操作沿用本地快速放行规则。核实来源为 Pi 内置 read 后,项目内外普通本地文件均可直接读取,包括 SDK 文档、其他目录源码与临时截图;不调用审批模型。offset: null、limit: null 按省略处理。自定义或被替换的同名工具不会继承内置工具的快速放行。
Auto 提示模型用内置 read 的 offset 和 limit 读取指定行,优先选用可用的 grep、find 和 ls。内容搜索应指定如 src/ 的源目录。Shell 已在目标工作目录运行时省略 cd 前缀。
其余已注册工具的完整调用交给 Guardian;不再用命令、文件名、目录范围或 LSP 包版本白名单决定是否转人工。 工具参数首先经过 Pi 自身的 schema 校验;校验失败的调用不会执行。
| 操作 | 审阅方式 |
|---|---|
write、edit |
审阅完整拟写入或替换正文、目标及实际路径元数据;项目外文件、配置、锁文件、指令文件、脚本和链接也可送审 |
| Bash / PowerShell | 审阅完整原始命令;支持脚本运行、构建、安装、管道、重定向、组合命令等,不改写模型获准的命令 |
| LSP、MCP、codemode 和其他注册工具 | 送入工具描述、schema、来源、annotations 与完整调用参数;名称或 readOnlyHint 不是安全或授权证明 |
| 未通过只读快速检查的读取/搜索 | 由模型评估实际范围和风险,不因敏感文件名或项目外路径直接要求人工 |
安装、联网、删除、发布、部署或配置修改按具体风险、目标、数据和用户约束评估;不会因类别名称自动允许,也不会在审阅前一律转人工。明确的用户禁止与后来撤销必须遵守。
默认阈值与固定 Codex 上游一致:先应用具体安全策略;没有更严格规则时,low / medium 可允许,不额外要求授权达到 medium;high 只有范围明确、授权至少 medium 且不违反禁止规则时可允许;critical 始终拒绝。明确 deny 阻止调用;必要事实仍不明确时 ask 转人工。缺少先前授权本身不会把普通低风险操作变成高风险。
审批模型通过 Pi 的 modelRegistry.streamSimple() 复用所选模型的提供方、base URL 和认证。每次包含工作目录、主代理的宿主指令、工具注册信息、完整操作参数及当前分支证据。permission_mode 和 plan_phase 由两入口在宿主内核实。送审时从可核对的结构化系统段中排除本包的模式和流程说明,保留项目规则、自定义宿主指令与明确用户约束。主代理宿主指令发送前会尽力脱敏。完整原始用户文字可以提供授权,助手、摘要、工具状态、描述、schema 和源码作为未经授权的上下文。来源标签表示 Pi 会话角色。每次许可只针对当前调用。
带图片的用户消息保留文字,显式标记图片内容未送审;图片正文不会发送给审批模型。完整可读的纯“继续”仍会标记先前具体请求是否缺失并送审。单条用户文字最多 65536 UTF-8 字节,投影最多 4096 项,证据最多 1024 条及 262144 字节;用户证据不截断。助手正文最多 2048 字节、摘要最多 4096 字节,超出或疑似含凭据时只保留省略标记。主代理的隐藏推理与工具结果正文不发送。
收集期间累计证据条数和序列化大小。任一项超预算时立即结束收集,并按证据不可用处理。
上下文收集区分完整可用、确实没有用户消息和用户证据不可安全取得。用户消息超长、历史用户文字疑似含凭据、投影改写或省略用户正文、证据超预算及收集异常均归为不可安全取得:清空审核 checkpoint、跳过 Guardian 并转人工;无 UI 时阻断,已有批准计划也不能覆盖。原因只记录固定描述,不包含隐藏的用户正文。现有只读快速路径继续生效。确实没有用户消息时才可将 user_request: null、missing_prior_context: true 交给 Guardian,按现有风险阈值判断;low / medium 风险不额外要求授权,high 风险授权未知时不能自动放行,critical 始终拒绝。实际工具参数含凭据、模型不可用/失败、审阅输出无效或审阅证据超预算时仍阻止或转人工。
压缩如果移除了当前请求,或只保留了「继续」这类短句,扩展会从当前分支、压缩边界之前找回用户原文,按消息顺序交给主模型和 Guardian。此前的范围、限制和后续撤销一起参加审核。回补限 64 条、共 16 KiB,图片保持省略。任何待回补消息存在 context_edit、疑似凭据或超出预算时,工具调用走人工确认,无 UI 时阻止。新发的完整请求按当前投影处理。压缩前的审批结果会失效,Guardian 按恢复后的证据重新审查。
审阅器的只读调查
审阅器只能调用三个内部接口,不复用主代理的 shell、扩展或 MCP:
| 接口 | 能力 |
|---|---|
review_stat_path |
查看本地路径是否存在、实际位置、链接及文件元数据 |
review_read_file |
每次最多读取 8192 字节,可用零起始的字节 offset 继续读取;标记截断,隐藏敏感路径正文、疑似凭据和二进制正文 |
review_list_directory |
最多列出 128 个目录项,名称总字节最多 8192;不递归,标记截断 |
这些接口不执行命令、不写文件、不访问网络路径。模型可在必要时检查脚本、npm 生命周期、配置或删除目标,不再依赖本地脚本白名单。一次审阅最多 12 次调查调用,合用 30 秒截止时间和模型上下文预算。每次执行前重新核对用于裁决的调查事实;脚本、配置或链接变化会使旧批准失效。文件正文仍是不可信事实,不能改变授权或审阅策略。
调查读取的普通文件片段会发送给所选审批模型,可能包含项目私有信息;敏感名称与格式检查不能识别所有秘密。普通 read 的工具结果则进入主代理对话,可能发送给主代理服务。审批网络目标仍是使用者配置的模型服务域名,没有额外固定审批服务或遥测域名;虚拟模型沿用已有路由。请只在所选服务允许接收相应数据时开启 auto。
输出、预算与状态绑定
支持上游的低风险短格式 {"outcome":"allow"}。其他判断使用 risk_level、user_authorization、outcome、rationale;缺省风险与授权按上游的 outcome 默认规则处理。本地保留 ask 扩展。仍拒绝重复键、额外字段、包装文字、非法枚举或控制字符,不对任意非 JSON 输出猜测允许。
每次模型响应最多 4096 输出 token(不超过模型自身上限)。模型未给出完整结论(输出截断、格式无效或提供方异常)时有限重试一次,重试重新发送完整证据;仍失败则标记审查失败。auto 下,若该操作已被静态证明是只读的本地读取(含项目外普通本地文件),则降级放行并记 degraded_allow,不把明显安全的读操作推给人工;写、敏感或范围未知的操作仍转人工。单次完整 JSON 证据最多 262144 字节,包含提示词及历史的会话预算最多 524288 字节,两者均受模型上下文大小减去 8192 余量限制。历史最多复用 16 次;前缀、边界、模型或调查事实变化、达到预算时,重新发送完整现存证据,不压缩或裁掉用户约束。完整请求仍放不下时转人工。
没有每轮 32 次的固定审批次数上限;/permissions status 显示本轮逻辑审阅次数,调查续轮不另增该计数。每次操作仍独立裁决,复用的是上下文,不是许可。完整证据、精确参数、工具来源、目标及调查事实在执行前重新核对,获准后冻结 JSON 参数。上下文状态与计划阶段也纳入审批指纹和上下文复用检查;审核期间证据变为不可用时,旧允许结果失效并记录阻断原因。模式、模型、运行、会话变化或取消使待审操作失效。审核正文只短期保留在内存;需要完整记录时由下节的审计日志负责。
无认证、服务失败、超时、输出不完整、无法解释的结果、非法调查工具或超过调查预算时转人工;无 UI 时阻止执行。模型明确拒绝则直接阻止。每轮调查可能产生额外模型请求和费用,未计入主代理消息费用;上下文复用不保证服务端缓存命中、降低费用或延迟。
审计日志
启用后,每个进入审批流程的工具调用都会在终态时追加一行 JSON 到审计日志,便于事后核对当时到底批准了什么。
位置:~/.pi/agent/permissions/logs/permissions-audit.jsonl(Windows 为 %USERPROFILE%\.pi\agent\permissions\logs\permissions-audit.jsonl)。可用环境变量 PERMISSIONS_AUDIT_DIR 指定其他目录。日志位于 Pi 用户目录,不属于任何项目仓库。
内容:每行是一条完整记录,包含 timestamp、sessionId、mode(基础权限)、planPhase(计划阶段)、toolName、cwd、outcome、reason、reviewModel、targets 和 input(完整工具参数)。Guardian 实际完成判定时另记 reviewDecision(allow / deny / ask)和 reviewAssessment;后者保留已校验、说明已脱敏的 risk_level、user_authorization、outcome、rationale,Navigator 还包含 navigator_scope(research / implementation / uncertain)。短格式回复中缺省的风险和授权按解析器规则补全,不代表模型显式提供过这些字段,不保存隐藏推理。显示人工确认框时记 manualDecision(allow_once / deny / cancel)。人工确认后的 reason 保留触发审批的原始策略或 Guardian 理由;审批失效或人工等待期间取消也保留已经完成的审核信息。快速放行、审核失败或未取得有效 assessment 时不伪造 reviewAssessment。
Auto 或 Navigator 的送审预检发现工具参数可能含凭据时,审计行另记首个 credentialMatch,如 {"rule":"credential_assignment","parameter":["command"]}。rule 是固定规则码,parameter 是参数位置。command、code、path、content、edits、oldText、newText 直接使用字段名,其余层级用该层枚举顺序中的零起始编号。诊断只包含这两项。完整参数继续由 input 保存。
单次编辑运行的工具记录另带 workflow: "navigator_edit_once"。批准记为 approved,用户拒绝或关掉确认框时分别用 manualDecision: "deny" 或 "cancel"。复查发现目标或授权已失效时记为 blocked。若用户已点选 Allow once,仍保留该选择供事后核对。
outcome 取值:
| 值 | 含义 |
|---|---|
allowed |
本地策略直接放行,无需人工确认;包括 Navigator 的只读检查通过 |
approved |
人工点选 Allow once |
denied |
人工拒绝,或 AI 审阅明确拒绝 |
reviewed_allow |
AI 审阅后放行 |
degraded_allow |
AI 审阅未完成时,对已静态证明只读的本地操作降级放行;区别于 reviewed_allow |
blocked |
无 UI、窗口过小、参数在执行前变化等原因阻止 |
error |
审批流程本身出错 |
这是敏感数据。 与确认框不同,日志刻意保留原始参数,包括完整命令、文件路径、write/edit 的正文,以及参数中出现的凭据。它等同于把命令历史落盘,因此:
- 不要把日志目录放入项目、提交到 Git 或同步到不信任的位置;
- 分享或备份前先脱敏;
- 需要清理时直接删除该文件即可,扩展不读取历史记录做判断。
失败不影响审批:目录不可写、磁盘满或轮转失败都只记录在内存中,不会阻止或改变审批结果。单个文件超过 20 MiB 时轮转为 permissions-audit.jsonl.1,旧 .1 会被覆盖,不做无限保留。轮转失败时本条日志不写入,通过 /permissions log 显示错误;后续写入成功会清除该错误。
full 下常规调用直接放行。若计划限制阻止调用,审计记为 blocked。需要逐次工具审批记录时使用 ask、navigator 或 auto。
默认模式与继承
模式不再每次启动都回到 ask。生效顺序从高到低:
- 启动参数
--permissions ask|navigator|learner|auto|full:显式指定时,在启动、新会话、恢复、分叉、/tree和/reload时优先应用;会话内可通过命令临时改选 - 当前分支保存的选择:没有显式启动参数时,用
/permissions auto切换后,/reload、恢复(resume)、分叉(fork)和/tree切回该分支都会沿用 - 可信项目配置
permissions.defaultMode:仅在当前ctx.isProjectTrusted()明确返回true时读取 - 用户配置
permissions.defaultMode:没有上述来源时使用 - 以上都没有时为
ask
配置写在 settings.json,可信项目级优先于用户级:
{
"permissions": {
"defaultMode": "auto"
}
}
- 项目级:
<项目>/.pi/settings.json - 用户级:官方
getAgentDir()返回目录中的settings.json,遵循PI_CODING_AGENT_DIR;默认是~/.pi/agent/settings.json
未信任项目、信任接口不可用或检查异常时,完全忽略项目权限配置,包括其中的 full。判断使用当前会话的信任状态,涵盖临时信任和 CLI 覆盖;启动、恢复、分叉、/tree 与 /reload 使用同一优先级。
设成 auto 后,没有显式启动参数和分支模式记录的新会话直接进入 auto;navigator、learner 和 full 同理。恢复会话、重载或切换分支时,仍按上述优先级解析。
模式选择以 permissions-mode 自定义条目写入会话分支,只保存模式名,不包含审批正文;先保存再切换,保存失败时会显示错误,--no-session 只在内存中保存。
人工确认与运行模式
完整布局放得下时,TUI 确认框采用纵向布局:审批区域上下各留一整行空白,与上方 provider 信息行及下方状态栏分开;正文左右各留一格,统一标题、字段、命令、分隔线和键盘提示的左边距。上方依次显示工具标题、完整的 Working directory 和单独一行的 Target;当目标为 current working directory (./) 时,表示目标就是本次会话的工作目录,./ 是相对工作目录的当前目录写法,不表示项目根目录,也不构成命令的沙箱边界。命令或操作摘要上下用低对比度虚线分隔,下方依次显示 Reason、单次许可说明、确认问题和编号选项。Reason 自动换行后的续行与原因正文起点对齐;选项预留两格箭头位置,切换选择时编号保持同列。标题与当前选项使用 Pi 主题强调色,原因和一次性许可提示使用警示色,正文使用正文色,字段名与辅助说明使用灰色;命令沿用终端底色,不加行号或外框。无论 ask、plan 还是 auto 转人工确认,选项都从上到下固定为 Allow once(允许一次)、Deny(拒绝),并默认选中 Allow once;按 Enter 允许当前调用,上下键选择,Esc / Ctrl+C 始终可以取消。选择与确认按键沿用 Pi 自定义键位。人工审批没有倒计时或超时限制,会一直等待选择;取消、UI 错误或执行中止均拒绝。RPC 继续使用官方 select 协议和纯文本审批描述,也不设置审批超时;由于该协议没有独立的默认选中项字段,选项同样按 Allow once、Deny 的顺序传入。
一次许可只对应当前完整工具参数,不授予同类操作的后续许可。审批期间参数变化后,操作会被阻止并要求重新发起。确认框按调用到达顺序串行显示。除 full 外,获准后递归冻结 JSON 参数及 event.input 绑定;后续 hook 不能改写目标、正文或嵌套替换项。依赖在本扩展之后改写参数的扩展会使调用失败,应在审批前完成转换。
普通审批消息中的 write、edit 分别显示写入字符数和替换次数,具体修改可结合 Pi 自带工具调用视图检查。Navigator 单次编辑按上文显示完整的转义前后文本,并以 Deny 作为默认选择。项目内的解析目标显示为相对工作目录的路径,Windows 工作目录和解析目标使用正斜杠。TUI 中的 shell 命令保留真实 LF 换行和空格缩进;字面量 \\n 不会转换为换行。其他终端控制字符(包括 CR、Tab、ANSI 与 OSC)以及方向控制符和不可见分隔符转为可见的 Unicode 转义。RPC 原始操作参数仍按 JSON 转义显示。其他参数和命令中的常见凭据格式会尽力隐藏。
描述超过 12000 字符时直接阻止。TUI 先尝试完整布局,包含上下留白、原因续行缩进、编号选项、实际快捷键提示、宿主页脚和显示余量;完整布局放不下时改用紧凑布局:保留标题、工作目录、目标、原因和选项,操作内容只显示开头 8 行,并用 … N lines hidden · ctrl+o to expand 明确标注隐藏行数。按 Pi 的 app.tools.expand(默认 ctrl+o,可在 keybindings.json 中改键或解绑)原地展开,展开后操作区使用窗口可用行数;仍有隐藏内容时继续标注上方、下方的行数,并用 tui.select.pageUp / tui.select.pageDown(默认 PgUp / PgDn)翻页。折叠状态下可以直接允许或拒绝,不会强制先展开;隐藏行数始终显示。快捷键解绑后仍显示隐藏行数,但不提供展开或翻页。窗口连折叠视图都放不下时阻止并提示扩大窗口或拆分操作。审批期间缩小窗口、导致折叠视图也放不下时,会取消当前审批并要求重新发起。Navigator 单次编辑的预览始终完整显示,放不下时直接取消。RPC 客户端负责自身的布局,仍受字符上限约束。本扩展把审批模型标识保存到独立的全局偏好文件。
| Pi 模式 | 行为 |
|---|---|
| TUI | 状态栏和纵向自定义确认框;完整命令(放不下时折叠并可展开)、独立字段配色,等待选择且无超时 |
| RPC | 使用官方 setStatus、notify、select UI 协议,客户端需支持交互响应 |
| print / JSON | 普通只读操作放行;auto 可运行模型批准的候选操作,仍需人工的调用因无 UI 而阻止;显式 full 放行 |
能力边界
- 扩展通过官方
tool_call审批所有到达该接口的调用,包括通过ctx.executeTool()发起的嵌套调用。未知工具不会自动放行。 - 用户手输的
!、!!属于user_bash,本扩展不拦截。Pi 自身的启动、包安装、其他扩展直接读写文件或启动进程,也可能不经过tool_call。 - 其他扩展与本扩展拥有相同的进程权限。获批参数冻结能阻止后续 hook 改写该对象;它不能隔离恶意扩展的直接 I/O、伪造会话来源或绕开工具管线的行为。
- 默认信任系统工具、PATH、shell 环境及其正常启动配置。工具同名替换、别名/函数、恶意启动配置不能靠命令参数白名单解决。
- 名称规则只能识别常见敏感路径和凭据格式。单次编辑额外拒绝具有多个硬链接的目标。文件复查发生在调用内置
edit前,复查和实际写入之间仍存在并发更换目标的时间窗口。 - 本扩展提供审批层;强制限制文件、网络和进程访问需要操作系统沙箱或虚拟机配合。
learner的构建/运行白名单不是沙箱:放行后命令在本机真实执行,编译器和解释器都可能执行任意代码。它只限定命令形状与路径范围。
开发验证
运行时使用 Pi 提供的 SDK 和 TUI 文字换行工具,不需要第三方运行库。宿主包在 peerDependencies 中声明,由 Pi 提供。开发依赖保留 Pi 1.5.0 的 SDK、TUI、Node.js 22 类型声明和 TypeScript。Navigator 回复提醒和单次编辑在 Pi 1.5.0 与 1.5.2 上通过隔离回归,界面对比使用已安装的 Pi 1.5.2。升级 Pi 后需要同步核对开发依赖版本及审批布局。
在仓库根目录安装开发依赖并检查:
npm --prefix permissions ci --ignore-scripts
npm --prefix permissions run typecheck
npm --prefix permissions test
tsconfig.json 覆盖扩展入口、策略代码和测试,启用严格类型检查,并允许 Pi 直接加载的 .ts 导入。typecheck 不生成 JavaScript。测试运行器只擦除类型后执行代码,因此测试通过不能代替类型检查;修改 TypeScript 后应同时运行两项检查。
内部代码直接使用 Pi 保证提供的会话、事件、主题与模型注册表接口;计划授权在权限门统一核验,参数冻结由 permissions 与包内 plan-mode 共用。工具参数的 JSON 类型由 Pi schema 校验,冻结阶段只负责阻止获批后改写。内部接口异常向上传播,工具审批入口统一阻断;外部配置、磁盘、模型响应、项目信任和异步取消仍在对应边界处理,不以空会话、unknown 身份或默认模型掩盖内部故障。
测试使用 Node.js 22.19+ 的 TypeScript 类型擦除和内置测试运行器。测试包括原有 ask/full 的路径、命令、PowerShell、Git 与人工审批回归,以及 auto 的完整操作送审、只读调查、模型输出解析、超时/取消、并发、上下文预算、生命周期脚本调查与事实复核、自选审批模型、来源/认证隔离、跨会话和独立运行时恢复、旧会话迁移、全局选择优先于历史分支、CLI 临时覆盖、并发写入与迁移、写入失败和损坏配置处理,以及无 UI 回退。Guardian 测试还覆盖风险/授权阈值、Pi 真实会话投影、压缩/分支/上下文编辑、checkpoint 提交、增量与预算重建、隐藏推理清除和获批参数冻结。Git 测试在独立进程中隔离配置环境;文件操作均在独立临时目录中完成。实际 PowerShell 执行测试需要 Windows,其他平台会跳过该项,解析规则测试仍会运行。
各历史版本的本机 TUI、SDK、模型请求、RPC / JSON / print 及自主编码验证保存在维护者工作副本的 quality/ 目录,不入库、不随 npm 包分发,结论分别对应当时源码。升级 Pi、修改键位或使用自定义页脚后,应重新检查确认框能否完整显示;这些本机验证不代替其他平台和长期日常使用反馈。
压缩续接用例在同一 Pi 1.5.2、112×38 终端和隔离任务下触发真实的 claude-compact 自动压缩。录制脚本核对修复前任务中断,修复后 Guardian 审核写入并在同一轮读回结果。对比录像位于 permissions/quality/ui/permissions-compaction-resume-0.9.0-412e4baae35e-vs-working.gif。
学习模式的界面证据是 permissions/quality/ui/learner-mode-0.9.0-vs-0.10.0.gif,由 scripts/ui-capture/scenarios/permissions-learner-mode.mjs 在 120×30 终端、Cascadia Mono 15px、pi-signal 主题下录制:before 侧 /permissions learner 只得到用法提示、选择器仍为 4 档;after 侧底栏变为 Permissions: learner,选择器增出 learner。该目录不入库、不随 npm 包分发。
权限边界回归覆盖项目可信状态与自定义 agent 目录优先级、用户证据不可用时跳过 Guardian、批准计划不能绕过、证据变化取消与审计、Unicode 空格及项目外/敏感目录联接、直接与 codemode 嵌套 LSP、PowerShell 字面 ~ 目录与真实路径解析。运行测试使用隔离配置和离线模拟提供方,不调用真实模型服务;可通过 PI_TEST_CLI 指定已安装版本的 dist/bundle/cli.js,验证完整包在 JSON / RPC 下的阻断和 reload 后的可信配置判断。
上游策略、类型契约、会话管理和本地阈值发生变化时,应结合 来源与差异 复核。