pi-agent-switcher

Pi 扩展：通过 Markdown 定义的 Agent 文件，在主会话中手动切换 Agent 角色。

每个 Agent 拥有独立的系统提示词、工具集、模型和思考级别。Agent 定义为简单的 Markdown 文件 + YAML frontmatter。

功能特性

• Markdown 定义 Agent — 用 .md 文件 + YAML frontmatter 定义 Agent 角色
• 两级作用域 — 全局 Agent（~/.pi/agent/k-priagent/）和项目 Agent（.pi/k-priagent/）
• 项目覆盖全局 — 同名项目 Agent 优先于全局 Agent
• 与 subagent 分离 — 本扩展只管主会话角色（primary agent），读取 k-priagent/；~/.pi/agent/agents/ 留给 @agwab/pi-subagent 等子代理运行时独占，互不干扰
• 系统提示词切换 — Agent 身份前置，Pi 内置上下文包裹在 <environment_context> 中
• 工具集切换 — 按 Agent 限制可用工具
• 模型切换 — 按 Agent 切换模型/提供商（如 anthropic/claude-sonnet-4-20250514）
• 思考级别切换 — 按 Agent 设置思考级别（off / low / medium / high）
• 会话持久化 — Agent 状态在会话分支间持久保存
• 交互式选择器 UI — 搜索、导航、数字快捷选择

安装

pi install npm:pi-agent-switcher

使用方式

命令

命令	说明
/agent <name>	切换到指定 Agent
/agent	打开交互式 Agent 选择器
/agent reset	重置为 Pi 默认行为
/agents	列出所有可用 Agent

快捷键

按键	动作
Alt+A	打开交互式 Agent 选择器

交互式选择器

选择器 UI 支持：

• ↑↓ 方向键 — 列表导航
• 1-9 数字键 — 快捷选择
• Enter — 确认选择
• Esc — 取消
• 输入过滤 — 按名称/描述模糊搜索

定义 Agent

在以下目录创建 .md 文件：

• 全局 Agent：~/.pi/agent/k-priagent/ — 所有项目可用
• 项目 Agent：.pi/k-priagent/ — 仅当前项目可用

Agent 文件格式

---
name: my-agent
description: 简短描述此 Agent 的职责
tools: read,write,bash,edit
model: anthropic/claude-sonnet-4-20250514
thinking: medium
---

你是一个专注于 [特定任务] 的专业 Agent。

你的职责：

- ...
- ...

规范：

- ...

Frontmatter 字段

字段	必需	说明
name	✅	Agent 唯一标识（用于 /agent <name>）
description	✅	简短描述，显示在 Agent 列表中
tools	❌	逗号分隔的允许工具列表（如 read,write,bash,edit）
model	❌	模型，格式为 provider/modelId（如 anthropic/claude-sonnet-4-20250514）
thinking	❌	思考级别：off、low、medium、high

Markdown 正文（frontmatter 之后的内容）即为 Agent 的系统提示词。

示例 Agent

代码审查员（~/.pi/agent/k-priagent/code-reviewer.md）：

---
name: code-reviewer
description: 专注于代码审查和质量
tools: read,bash
thinking: high
---

你是一位资深代码审查员。关注以下方面：

- 代码正确性与边界情况
- 性能影响
- 安全漏洞
- 可读性与可维护性

始终提供可操作的建议和具体代码示例。

前端开发（.pi/k-priagent/frontend.md）：

---
name: frontend
description: 前端专家，精通 React/Vue
model: anthropic/claude-sonnet-4-20250514
tools: read,write,bash,edit
---

你是一位前端开发专家，精通 React、Vue 和现代 CSS。
偏好组件化架构，遵循无障碍最佳实践。

工作原理

当 Agent 激活时，扩展通过 before_agent_start 事件修改 Pi 的行为：

1. 系统提示词：Agent 的系统提示词前置（高注意力位置），Pi 内置上下文包裹在 <environment_context> 标签中
2. 工具：若 Agent 定义了 tools 列表，则仅启用这些工具
3. 模型：若 Agent 定义了 model，Pi 切换到该模型
4. 思考级别：若 Agent 定义了 thinking，Pi 使用该思考配置

会话启动时，扩展从会话历史中恢复上次激活的 Agent。

调试

如果想查看 Agent 切换后最终拼装出的完整系统提示词（Agent 身份 + <environment_context>），可以使用 pi-message-capture，它能捕获并展示每次发送给模型的完整消息内容。

许可证

MIT