pi-profile-switch

English | 中文

工具介绍

pi-profile-switch 为 Pi 提供命名 profile，让你按任务或场景来配置 Pi 的运行资源：

• 支持 skills、extensions、tools、MCP servers 以及 MCP server tools 过滤。
• 支持为 profile 指定默认模型、thinking level、以及追加的 instructions。
• 支持 pi-subagents 的子 agent 角色设定。
• 在同一会话内切换 profile，无需重启，保留会话历史。
• 同时使用全局 profile 和项目级 profile。
• 可以使用 overlay 在profile会话中临时禁用资源。

安装与使用

安装

npm install -g pi-profile-switch

需要 Pi 0.99.1 或更新版本，npm 会将其作为 peer dependency 安装。本包提供 pi-profile 启动器，请用 npm install -g，而不是 pi install。

启动

# 使用上次记住的 profile；没有记录时使用 default
pi-profile

# 明确使用 default，保持原生 Pi 行为
pi-profile default

# 使用初始 ask profile，进行问答与代码阅读
pi-profile ask

# -- 后的 Pi 参数原样传递
pi-profile ask -- --model openai/gpt-5.4

不指定名称时，先使用已信任项目记住的选择，再使用全局记住的选择，最后使用 default。命令行指定的 profile 只影响这次启动。

全局 profile 目录为空时，安装或启动会写入初始 ask。它关闭用户级 skills 和 extensions，只保留只读文件工具；MCP servers 仍按 Pi 的配置可用。你可以修改或删除它。

创建与修改 profile

可以直接保存 JSON 文件，格式和位置见下方配置详解。也可以使用随包提供的 profile-config skill，通过对话创建、修改和删除 profile：

创建一个名为 review 的全局 profile，只保留只读文件工具，禁用用户级 MCP servers。

使用对话配置时，当前 profile 需要允许 profile-config skill 和文件写入工具。可以先切换到 default。

profile-config 创建带有 skills 列表的 profile 时，默认加入自身，除非你明确排除它，或列表已有覆盖它的 glob。手动编辑 JSON 不会自动加入 skill。

会话内命令

命令	作用
/profile	查看并选择 profile；非交互模式下打印列表。
/profile use <name>	切换 profile，并记住选择供下次启动使用；切换失败时恢复原 profile。
/profile reload	重新读取当前 profile，应用文件修改。
/profile status	查看当前 profile、已解析资源、路径、overlay、MCP 状态和诊断。
/profile overlay disable|enable skill|extension|mcp|tool <name-or-glob>	添加或移除当前会话的资源禁用条目。
/profile overlay clear	清除全部 overlay，恢复 profile 的资源选择。

这些命令也适用于 Pi 的非交互模式，包括 --mode text、--mode json 和 --mode rpc。

临时禁用资源

/profile overlay disable tool bash
/profile overlay enable tool bash
/profile overlay clear

overlay 只作用于当前运行，不修改 profile 文件，重启后失效。enable 需要与原禁用条目完全一致；使用 glob 禁用时，也要用同一个 glob 恢复。

overlay 只能收窄资源，不能增加 profile 未选中的资源。default profile 不支持通过 overlay 禁用 MCP server。

配置详解

文件位置与命名

每个 profile 对应一个 <name>.json 文件，文件名就是启动和切换时使用的名称。

路径	生效范围
~/.pi-profile-switch/profiles/<name>.json	全局。设置 PI_PROFILE_SWITCH_DIR 后，改为该目录下的 profiles/<name>.json。
<项目>/.pi/profiles/<name>.json	当前项目，仅在项目已信任时读取。

同名的项目级 profile 完全替换全局 profile，不合并字段。删除项目级文件后，全局定义重新生效。

名称必须以 ASCII 字母或数字开头，后续可包含 ASCII 字母、数字、点、下划线和连字符。default 是保留名称，不能创建 default.json，也不能编辑或删除 default profile。

项目尚未信任时，可以在 Pi 中执行 /trust 后重新启动，或通过以下方式仅信任本次启动：

pi-profile review -- --approve

完整示例

将下面的内容保存为 review.json。示例中的资源名称需要替换为你已安装或配置的名称，模型需要使用你可访问的 provider 和 model。

{
  "label": "Code Review",
  "description": "Review code with selected resources",
  "skills": ["profile-config", "code-review"],
  "extensions": ["pi-subagents"],
  "mcps": ["github", "linear"],
  "tools": ["read", "grep", "find", "ls"],
  "mcp_tools": {
    "github": ["search", "get_issue"],
    "linear": []
  },
  "defaultProvider": "openai",
  "defaultModel": "gpt-5.4",
  "defaultThinkingLevel": "high",
  "instructions": "Focus on correctness and security. Do not modify files.",
  "subagents": {
    "defaultModel": "openai/gpt-5.4",
    "defaultThinking": "medium",
    "agentOverrides": {
      "reviewer": {
        "model": "inherit",
        "thinking": "high",
        "description": "Independent code review",
        "advertise": true
      }
    }
  }
}

JSON 顶层直接写 profile 对象。所有字段都可省略；省略的字段不增加 profile 控制，保留 Pi 的原生行为。字段类型可通过 schemas/profiles.schema.json 校验。

字段参考

字段	类型	用途
label	string	选择列表中的显示名称，不改变 profile 的文件名。
description	string	选择列表中的说明。
skills	string[]	选择 skills，支持名称和 glob。
extensions	string[]	选择 extensions，支持标识、glob 和指定路径。
mcps	string[]	选择用户级 MCP servers，支持名称和 glob。
tools	string[]	选择非 MCP 工具，支持名称和 glob，包含内置工具及 extension 提供的工具。
mcp_tools	Record<string, string[]>	按 MCP server 选择工具，见下方 MCP 配置。
defaultProvider	string	默认模型的 provider，需与 defaultModel 同时声明。
defaultModel	string	provider 中的 model ID，需与 defaultProvider 同时声明。
defaultThinkingLevel	string	默认模型的 thinking level；仅在上述两个模型字段均已声明时生效，使用 Pi 支持的值。
instructions	string	追加到系统提示词的文本，不替换原系统提示词。
subagents	object	pi-subagents 的默认值和指定角色设置，见下方子 agent 配置。

模型是否可用、认证和命令行参数的优先级由 Pi 处理。只声明 defaultProvider 或 defaultModel，不会设置 profile 的默认模型。同时声明两个模型字段时，无效的 defaultThinkingLevel 字符串会产生警告并被忽略，不会移除模型声明。

资源选择

profile 引用已有资源，不安装或复制资源。各类引用的写法如下：

资源字段	引用方式与示例
skills	skill 名称，例如 "profile-config"；glob，例如 "review-*"。
extensions	已安装的 package 名称或 source alias；多入口 package 的 <package>:<relative path>；独立文件的标识；glob；绝对路径或 ~/ 路径。
mcps	MCP 配置中的 server 名称，例如 "github"；glob，例如 "internal-*"。
tools	Pi 中的非 MCP 工具名称，例如 "read"、"bash"；glob，例如 "test_*"。

独立 extension 文件的标识是相对于 extensions 目录的路径，去掉 .ts 或 .js 后缀。例如 conventions.ts 对应 conventions，sub/index.ts 对应 sub。extension 路径必须为绝对路径或 ~/ 路径，不能使用相对路径。

资源列表中，省略字段表示不收窄该类资源；[] 表示不选择该类资源；非空数组表示只选择匹配的资源。例如：

{
  "skills": [],
  "extensions": [],
  "mcps": [],
  "tools": ["read", "grep", "find", "ls"]
}

skill、extension 和 MCP server 的选择只收窄用户级资源。项目级资源的可见性由 Pi 的项目信任决定，不会被 profile 隐藏。Pi 原有的资源排除设置仍然有效。

tools 不限制 MCP 工具，也不会关闭 Pi 调用 MCP 所需的入口。要限制 MCP 工具，需要配置 mcp_tools；因此只读文件工具列表不会自动禁止 MCP 写入操作。

MCP 配置

MCP server 的地址、启动命令和认证信息保存在 Pi 的 MCP 配置中。profile 只选择 server 和工具。

用户级配置按下面的顺序读取；后一个来源的同名 server 完全替换前一个来源的定义，不合并字段：

1. ~/.config/mcp/mcp.json
2. ~/.agents/mcp.json
3. ~/.agents/mcp/mcp.json
4. <agentDir>/mcp.json，其中 <agentDir> 是 Pi 的用户目录，通常为 ~/.pi/agent

已信任项目的 .pi/mcp.json 由 Pi 读取，其中的 servers 不受 mcps 或 mcp_tools 收窄。选择某个 server 不会强制启用源配置中已禁用的 server。

mcp_tools 的 key 必须是 server 名称，数组中的值必须是 Pi 原生 MCP 接口显示的工具名称，均不支持 glob。

写法	效果
省略 mcp_tools，或写 {}	保持各 server 的原工具配置。
在 mcp_tools 中省略某个 server	保持该 server 的原工具配置。
"github": ["search", "get_issue"]	替换该 server 原有的工具选择，只允许匹配的工具。
"github": []	禁止该 server 的全部工具，不禁用 server 本身。

MCP 工具名称不会预先校验。写错名称仍会保留限制，但不会产生工具名称诊断；配置前应通过 Pi 查看 server 暴露的实际名称。

要长期保存 MCP 连接配置，请修改上述用户级文件。在 pi-profile 会话中通过 pi mcp add 修改的内容，会在下次切换或 reload 时被覆盖。

子 agent 配置

subagents 不会加载 pi-subagents，也不会自动添加 extension、授权委派工具或创建角色。使用这些设置前，需要通过 Pi 正常安装并加载 pi-subagents，并允许相应工具。

字段	类型	用途
subagents.defaultModel	string	没有指定模型的子 agent 使用的默认模型。模型字符串采用 pi-subagents 的原生格式，例如 openai/gpt-5.4。
subagents.defaultThinking	string	没有指定 thinking level 的子 agent 使用的默认值。
subagents.agentOverrides	object	按精确角色名称设置覆盖值；名称区分大小写，不允许 glob 或前后空白。
subagents.agentOverrides.<name>.model	string | false	设置角色模型；"inherit" 使用当前父会话模型，false 清除角色的显式模型设置。
subagents.agentOverrides.<name>.thinking	string | false	设置角色 thinking level；false 清除角色的显式 thinking 设置。
subagents.agentOverrides.<name>.description	string	角色描述元数据，不是子 agent prompt。
subagents.agentOverrides.<name>.advertise	boolean	是否列入父 prompt；false 隐藏这项介绍，不控制角色能否运行。

子 agent 的 thinking level 使用 schema 中的 thinkingLevel 支持值。所有子 agent 文本字段必须非空。

省略 subagents、写 {} 或只提供空角色对象，不增加子 agent 控制。声明某个角色不会排除其他角色。未声明的角色字段保留原生设置，显式 false 不等同于省略。

pi-subagents 的项目设置、provider 设置和每次调用的设置仍可能覆盖这些声明。/profile status 展示 profile 声明；/subagents-models 查看实际模型映射。模型格式和原生优先级见 pi-subagents 模型文档。

应用修改与诊断

修改当前 profile 文件后，在会话中执行：

/profile reload
/profile status

情况	处理方式
JSON 格式错误、顶层不是对象或字段类型错误	激活失败；按错误中的文件路径和字段名修正后重试。
未知顶层字段	字段被忽略并产生警告；按提示改用支持的字段。
subagents 中出现不支持的嵌套字段	激活失败；按提示删除或改正该字段。
skill、extension、MCP server 或非 MCP tool 引用未匹配	激活继续，报告警告并保留可用匹配；修正名称或安装资源后 reload。全部未匹配时，选择保持为空，不恢复全部资源。
MCP server 未知、已禁用或只属于项目级配置	报告警告，不创建 server、不强制启用，也不修改项目级 server；检查用户级 MCP 配置和名称。
用户级 MCP 配置格式错误	报告配置路径并跳过该来源，继续使用其他有效来源；修正该文件后 reload。
模型或认证错误	按 Pi 的原生提示检查 provider、模型和凭据。