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、模型和凭据。 |