Pi Config Manager

在一个可搜索的 TUI 浮层中管理 Pi 的工具、技能、上下文文件与扩展。

English | 简体中文

Pi Config Manager 是 Pi Coding Agent 的资源策略扩展。资源的发现、加载、去重与来源标注仍由 Pi 负责；Config Manager 只决定 Pi 已发现的资源是否启用。

主要特性

• 在一个界面中管理 Tools、Skills、Context Files 和 Extensions
• 显示当前真正提供给模型的 Effective 资源状态
• 可搜索、全键盘操作的浮层，并保留当前对话作为背景
• 持久化的 Global 资源设置，Preset 则隔离在当前 Session 中
• Context Monitor 可查看所选资源对模型可见提示词的贡献
• 编辑器上方显示紧凑的资源状态 HUD
• 根据资源来源，通过 Pi 公开设置 API 保存扩展开关
• 内置命名 Preset，可统一配置模型、思考等级、工具、技能和指令
• 提供可选运行时策略层事件 API，方便只读模式等扩展接入
• 无遥测，不发起网络请求

环境要求

• Pi Coding Agent 0.83.x
• 可视化管理器需要交互式 TUI 模式

当前版本已在 Pi 0.83.0 上完成测试。更高版本的 Pi 可能也能运行，但 Pi 的扩展与 TUI API 可能发生变化；升级前请先查看本项目的发布说明。

安装

全局安装，供所有项目使用：

pi install npm:pi-config-manager

仅为当前项目安装：

pi install -l npm:pi-config-manager

不修改设置，临时试用一次：

pi -e npm:pi-config-manager

启动 Pi 后运行：

/config-manager

快速上手

1. 运行 /config-manager。
2. 按 Tab 在资源页签之间切换。
3. 直接输入文字过滤当前列表。
4. 按 Space 或 Enter 在自动选择的目标中切换所选资源。
5. 在 Extensions 页按 S 保存暂存变更并重新加载 Pi。

键盘操作

| 按键 | 操作 | | --- | --- | | Tab | 切换到下一个资源页签 | | 输入文字 | 过滤当前资源列表 | | ↑ / ↓ | 移动选择，或滚动已聚焦的 Monitor | | ← / → | 聚焦资源列表或 Context Monitor | | Space / Enter | 在当前目标中切换所选资源 | | S | 保存暂存的扩展变更并重新加载 Pi | | Esc | 关闭管理器 |

支持 Pi 键位配置的操作会遵循当前 TUI keybindings。

命令

| 命令 | 说明 | | --- | --- | | /config-manager | 打开统一概览 | | /tools | 打开 Tools 页 | | /skills | 打开 Skills 页 | | /contexts | 打开 Context Files 页 | | /extensions | 打开 Extensions 页 | | /preset | 选择或清除命名 Preset | | /preset <名称> | 直接激活命名 Preset |

也可以直接修改全局默认值：

/tools global enable|disable <tool-name>
/skills global enable|disable <skill-name>
/contexts global enable|disable <absolute-path>

Effective 视图与自动编辑目标

可视化管理器始终展示 Effective 资源状态：Pi 默认值、Global/项目设置、活动 Preset、Session 覆盖、外部激活和运行时约束组合后的最终结果。该状态会在下一次 Provider 请求中提供给模型。

编辑目标仍然自动选择，不再提供手动切换目标的按键：

• 未激活 Preset 时，页头显示 View: Effective · Edit: Global。Tools、Skills 和 Context Files 的修改会写入 ~/.pi/agent/resource-settings.json，并由新会话继承。
• 激活命名 Preset 后，页头显示 View: Effective · Edit: Session · preset名称。资源修改只作为该 Preset 的覆盖存入当前 Session 分支，不会修改 Global 设置或 presets.json。

运行时约束具有最高工具优先级。受约束的工具会显示醒目的锁和策略层来源，例如 🔒 edit · blocked by plan-mode 或 🔒 grep · required by plan-mode。这类工具不能从管理器切换；必须先清除对应运行时约束，避免产生无法改变 Effective 状态的修改。

受信任项目的 .pi/resource-settings.json 也可能禁用 Global 编辑目标无法重新启用的资源。未激活 Preset 时，这些资源会显示 blocked by project settings 并锁定；需要直接编辑项目配置文件。View、编辑目标和 Constraints 分行渲染，确保在管理器支持的最小宽度下仍然可见。

激活或清除 Preset 会修改当前 Session 的模型、思考等级、资源和指令。恢复会话或切换 Session Tree 分支时，会同时恢复活动 Preset 及其 Session 覆盖。

受信任的项目可以在 .pi/resource-settings.json 中加入项目专属默认值。可视化界面的 Global 编辑目标只修改 Global 设置；项目文件继续由项目单独维护和纳入版本控制。

扩展开关独立于 Effective 资源视图，因此 Extensions 页显示 View/Edit: Pi settings。变更会先在界面中暂存，按 S 并确认重新加载后，再根据资源来源写入对应的全局或项目 Pi 设置。

各类资源的行为

Tools

未受约束的工具变更通过 pi.setActiveTools() 立即生效。Config Manager 使用 Pi 已发现的工具清单，并在能够观察到时保留其他扩展动态加入的工具。Global defaults 同时保存显式启用和禁用，因此 Pi 注册但初始未激活的工具也可以被持久启用。

Skills

已禁用的技能会从 Pi 标准系统提示词的技能目录中移除。调用已禁用的 /skill:<name> 命令时，也会显示通知并阻止展开。

Context Files

已禁用的上下文文件会从 Pi 标准的 project_context 提示词区段中移除。该设置只控制模型可见的提示词内容，不会阻止工具直接读取一个已知文件路径。

Extensions

扩展开关在保存前只处于暂存状态。Config Manager 通过公开的 SettingsManager 写入 Pi 原生扩展/包过滤设置，然后请求 Pi 重新加载。

如果本地包来源直接指向单个扩展文件，Pi 无法为它应用单扩展过滤规则。Config Manager 会报告这个限制，而不是保存一个无效开关。管理器也不会允许在自己的活动界面中禁用自身。

Context Monitor

终端宽度足够时，浮层左侧显示资源，右侧显示 Context Monitor。选择资源后可查看：

• **Tools：**描述、参数 schema、prompt snippet 与 prompt guidelines
• **Skills：**该技能在系统提示词目录中的条目
• **Context Files：**完整的 project_context 区块
• **Extensions：**来源、作用域、包来源类型与路径信息

第一次代理运行前，Monitor 使用 Pi 当前的提示词预览。运行开始后，它会显示在 agent_start 捕获的有效系统提示词，并在其中高亮所选资源。在管理器打开期间做出的策略变更，会在下一次代理运行后反映到捕获的提示词中。

终端较窄时，Config Manager 会退化为不带 Monitor 的资源列表。

配置文件

全局默认值：

~/.pi/agent/resource-settings.json

受信任项目的默认值：

.pi/resource-settings.json

配置格式：

{
  "version": 1,
  "enabledTools": ["ast_grep_search"],
  "disabledTools": ["write"],
  "disabledSkills": ["deploy"],
  "disabledContexts": ["/absolute/path/to/AGENTS.md"]
}

当前 Preset、恢复状态及其 Session 覆盖存储为版本 2 的 pi-config-manager-state 条目，因此 /tree、恢复会话和分支导航都能还原对应的 Session 策略。

版本 2 是有意的破坏性状态重置。版本 1 的 pi-config-manager-state 以及独立的 preset-state、tools-config、skills-manager-state 条目不会被导入。

Preset

Config Manager 从以下位置加载命名 Preset：

~/.pi/agent/presets.json
.pi/presets.json

项目 Preset 只会在项目受信任时加载，并覆盖同名的全局 Preset。每个 Preset 可以配置：

{
  "review": {
    "provider": "openai-codex",
    "model": "gpt-5.6-sol",
    "thinkingLevel": "high",
    "tools": ["read", "bash"],
    "skills": ["preset-settings"],
    "instructions": "修改前先认真审查。"
  }
}

可以使用 /preset、/preset <名称>、pi --preset <名称> 或 Ctrl+Shift+U。选择 (none) 会恢复进入第一个 Preset 前记录的模型与思考等级，清除 Preset 专属资源覆盖，并让资源回到当前 Global/项目策略。显式空的 tools 或 skills 数组表示全部禁用；省略字段表示保留对应的正常策略。Preset 激活期间，其 instructions 会追加到系统提示词。

该包同时提供 preset-settings Skill，用于安全编辑这些配置文件。

策略优先级

运行时约束 > Preset Session 覆盖 > Preset > 项目/Global 设置 > Pi 默认值

目前运行时约束只作用于工具，主要供只读模式、沙箱模式等扩展集成使用。

策略架构

Config Manager 只有一个扩展入口和一个 PolicyManager。Pi 默认值、Global/项目设置、第一方 Session Preset Feature 及其 Session 覆盖和外部运行时策略层都向该核心提交策略，只有核心负责计算并应用最终资源状态。因此 Preset 使用包内类型化 Profile Policy 接口，而不是兼容事件桥；外部插件无法共享包内 controller，所以继续使用下方具备生命周期防护的运行时策略层事件 API。

扩展集成事件

Config Manager 可以独立运行。其他扩展也可以选择通过 pi.events 协调策略。

运行时工具层

pi.events.emit("config-manager:layer-set", {
  id: "read-only-mode",
  disableTools: ["edit", "write"],
  requireTools: ["read"],
});

pi.events.emit("config-manager:layer-clear", {
  id: "read-only-mode",
});

每个策略层以 ID 区分并参与组合。每层中的必需工具会在禁用工具之后加入，而且只能激活 Pi 已发现的工具。调用方可以在任意时刻设置或清除策略层，包括 Config Manager 的 session_start 之前；提前到达的事件会先保存，等默认工具清单初始化后才应用。

如需监听资源数量，可以订阅 config-manager:state-changed。发送 config-manager:request-snapshot 可以请求管理器立即发布一次快照。

原来的 preset:tools-changed、preset:skills-changed 和 config-manager:preset-state 集成事件已删除；Preset 现在由 Config Manager 直接拥有。

限制与安全说明

• Pi 扩展拥有当前用户的完整系统权限，安装第三方包前请先审查源码。
• Config Manager 是提示词/资源策略工具，不是文件系统或进程沙箱。
• 技能和上下文过滤依赖 Pi 的标准提示词区段。如果自定义系统提示词删除或重写了这些区段，Config Manager 会保留原提示词并警告用户。
• 可视化管理器只支持 TUI 模式；RPC、JSON 和 print 模式不能打开浮层。
• 扩展变更需要重新加载 Pi。

开发

需要 Node.js 22.19+、Bun 与 Pi 0.83.0+。

git clone https://github.com/Hor1zonZzz/pi-config-manager.git
cd pi-config-manager
npm install
npm run check

直接加载本地扩展：

pi --no-extensions -e ./src/index.ts

自动发布

发布稳定版 GitHub Release 时，.github/workflows/publish.yml 会自动把对应版本发布到 npm。工作流会检出 Release tag，验证该 tag 与 v<package.json version> 完全一致，运行完整检查，然后通过 npm Trusted Publishing 发布。Prerelease 会被跳过。

首次自动发布前，需要在 npmjs.com 的包设置中打开 Settings → Trusted Publisher → GitHub Actions，并填写：

• Organization or user：Hor1zonZzz
• Repository：pi-config-manager
• Workflow filename：publish.yml
• Allowed action：npm publish

之后更新 package.json 和 package-lock.json、整理 CHANGELOG.md、提交并推送，再创建匹配的 tag（例如 v0.1.1）和对应 GitHub Release。该工作流使用 OIDC，不需要保存长期 NPM_TOKEN Secret。npm 配置和工作流文件名区分大小写。

许可证

MIT