在 VS Code 侧边栏中使用本机已安装的 PI coding agent,完成聊天、工具调用和会话管理,无需为日常对话打开终端。
插件通过 pi --mode rpc 桥接本机 PI:界面与编辑器上下文由插件提供,推理、模型、工具、技能和会话仍由 PI 管理。交互组织参考 Codex / Claude Code 的侧栏方式,视觉优先参考 PI 自身的文本布局、消息配色和紧凑状态栏,并适配 VS Code 主题。
当前版本为 1.1.1(正式版),扩展标识为 SilasPaul.pi-agent-coding。PI 协议验证基线为 1.5.2,兼容目标为 Windows 与 macOS 本地环境;首次上架完成前可通过 VSIX 安装。具体变更见 更新记录。
验收范围:Windows 保留既有本地验证基线;本轮在 macOS 验证了自动发现、真实 PI RPC 握手、模拟进程清理和原生 VS Code 扩展宿主,跨平台 CI 尚未配置;真实模型生成、真实 MCP / 扩展交互和长会话成功压缩尚未完成端到端验收。模拟进程、浏览器夹具和扩展宿主测试不代表这些真实环境已经通过。完整说明见“范围与限制”。
当前表单已使用 Web Awesome 统一按钮、输入框、下拉菜单和开关:输入区呈现附件、箭头发送按钮以及模型与思考强度;运行中默认发送后续消息,可在队列消息旁点击“引导”。设置和命令表单提供标签及说明。控件颜色跟随 VS Code 的暗色、浅色和高对比度主题,组件、样式与图标均随插件本地打包。
界面强调色参考 PI 官网的暖金与陶土色:暗色主题使用暖金色按钮和柔和选中底色,浅色主题使用陶土色;背景与正文继续适配编辑器,高对比度主题保留 VS Code 的可访问配色。
聊天正文、思考过程与输入区统一使用 VS Code 界面字号,不额外放大;状态提示略小一级,代码保留等宽字体。
PI 运行时显示暖金色心电图折线,高亮沿波形从左向右循环扫过,并配有节奏稍快的 Working:柔光与轻微上浮按字母从左向右依次游走,其余字母保持低亮度但可读,结束后自动移除。执行过程入口沿用相同的心电图图标,运行时扫描、结束后保持静态完整折线。图标和文字跟随主题配色,高对比度模式使用实色文字;启用系统“减少动态效果”时显示静态折线和文字。
同一轮任务中的进度说明、思考和工具调用收进一条可展开的执行过程入口 Activity,最终回复直接显示。阶段标题统一使用英文:Waiting(等待响应)、Thinking(思考)、Writing(生成回复)、Preparing(准备工具)、Running(执行工具)、Input needed(等待用户操作)、Retrying(重试)、Compacting(压缩上下文)与 Interrupted(中断);操作数量、耗时和具体说明保留中文。运行期间,入口显示当前阶段和运行耗时;收到思考或工具输出时,自动露出最新内容的最多三行预览。预览仅使用 PI 实际返回的文本,最多保留末尾 600 个字符(插件预览限制),完整内容可展开查看;思考结束或活动切换后撤下旧预览,整轮任务以 PI 的 agent_settled 事件为准结束,恢复折叠入口。没有思考文本时仍显示真实运行状态。等待用户操作、重试、压缩和连接中断分别显示对应提示,异常工具数量以中性色的“N 项异常”徽标在折叠状态下显示,悬停提示可展开查看详情;该计数记录工具返回的异常,不表示整轮任务失败。
入口沿用插件的暖金强调色,使用浅渐变、状态图标及独立的操作数量与异常计数徽标;运行时心电图高亮循环扫描,背景有缓慢流光,展开时内容柔和淡入。启用系统“减少动态效果”时停止这些动画,高对比度主题沿用 VS Code 的可访问配色。展开后可逐条查看工具参数、完整命令、输出与修改差异。工具摘要使用紧凑单行,长路径和命令省略显示,完整参数保留在详情中。手动展开完整过程后不会自动收走;手动收起后,本轮后续更新不再自动露出预览,新一轮恢复自动预览。执行过程与工具的展开状态在流式刷新和搜索往返时保留,搜索当前对话时直接显示匹配的消息。
流式输出复用未变化的消息和工具节点,保留历史正文的文字选择、焦点和展开状态。侧栏可见时合并高频状态更新,隐藏期间暂停展示快照,重新打开时显示最新状态;隐藏侧栏仍会继续执行任务。
输入框下方不显示本地工作区路径;保留发送快捷键、用量和 PI 扩展状态,无扩展状态时不占位。
顶部的新建会话、历史会话、设置和更多操作使用图标按钮;悬停可查看中文提示。时钟图标打开历史,齿轮图标打开设置。
| 能力 | 插件提供的操作 |
|---|---|
| 对话 | 流式 Markdown、代码块、可折叠思考、运行与错误状态 |
| 工具结果 | 展示参数、文本和图片结果,通用处理未知工具名称;展示 PI edit 工具实际返回的修改差异 |
| 编辑器上下文 | @ 搜索工作区文件和文件夹,@open: / @current: 选择文档;未保存内容、选区、诊断与资源管理器右键附件 |
| 输入效率 | @ / / 键盘补全、最近 50 条输入、上下方向键回看、Ctrl/Cmd+R 搜索输入历史 |
| 内容操作 | 文件引用跳转行列、复制回复和代码、在未保存编辑器打开代码、从用户消息分叉修改 |
| 图片 | 文件选择、粘贴或拖入 PNG / JPEG / GIF / WebP;发送前检查模型图片能力 |
| 模型与命令 | 发现并选择 PI 模型和思考强度;通过 / 菜单选择 PI 发现的技能、提示模板和扩展命令 |
| 运行中交互 | 补充指示、后续消息、队列展示、清空并恢复到输入框、停止全部 |
| 会话与历史 | 恢复上次工作区会话、筛选索引、搜索当前对话及 PI 完整历史、新建、重命名、只读历史树、分叉、复制和导出 HTML |
| 工作导航 | 成功 write / edit 工具的文件导航、打开 VS Code 源代码管理、查看 PI 技能与模板来源 |
| 快捷操作 | ! 独立命令、队列逐条/全部处理、轮换模型与思考强度;后台完成、失败和等待交互通知 |
| 上下文与重试 | token、费用和上下文占用;自动压缩设置、手动压缩、自动重试设置与取消 |
| PI 扩展交互 | 选择、确认、输入和编辑对话框;文本状态、widget、标题和输入框更新 |
| 独立命令 | 经 PI 执行 shell 命令、查看输出、取消执行,选择是否加入后续模型上下文 |
各项操作是否可用取决于所安装 PI 的 RPC 能力、模型和扩展配置。真实 MCP 环境与长会话成功压缩尚未完成验收。
在聊天输入框输入 /,可选择 PI 发现的技能、提示模板、扩展命令,以及以下插件快捷操作。方向键选择,鼠标点击或按 Tab / Enter 确认后立即执行,无需再次发送;需要附带参数时,手动输入完整命令和参数后再发送。
| 快捷命令 | 操作 |
|---|---|
/new |
新建会话;当前正在运行时先停止全部任务 |
/compact [摘要要求] |
手动压缩上下文,例如 /compact 保留文件名和待办;需等待当前任务完成 |
/model |
从 PI 返回的可用模型中选择 |
/thinking |
从 PI 返回的可用思考强度中选择 |
/resume |
打开当前工作区的会话历史;也可从历史面板选择会话文件 |
/name [名称] |
重命名当前会话;省略名称时弹出输入框 |
/fork |
选择用户消息并分叉,不回滚文件 |
/clone |
复制当前会话,不回滚文件 |
/tree |
只读浏览会话历史树 |
/export |
导出对话为 HTML |
/settings |
打开侧栏内的设置面板 |
/stop |
清空队列并停止当前任务 |
这些快捷操作复用插件已有的服务与 PI RPC,不作为普通消息交给模型。除 /compact 和 /name 外不接收参数;除 /stop 保留已有附件并直接停止外,其他快捷操作不接收附件。失败或取消对话框时保留命令草稿。PI 已发现的同名命令优先,保持现有技能、模板与扩展的行为;其余插件快捷操作在补全列表中优先显示。
/model、/thinking、/resume、/settings 打开侧栏已有的选择器或面板。/stop 在压缩等待或队列重排期间仍可输入执行,其完成通知不会清除其他待发送草稿。这里的快捷操作只覆盖插件已实现的 RPC 与界面能力,例如 /tree 仍是只读浏览,不提供 PI 终端中的分支切换。
- 本机已安装并配置 PI,已有可用模型;首次登录和供应商配置需在 PI 自身完成。
- VS Code 满足扩展声明的
1.106.0或更高版本,当前实测版本为1.145.3。 - 打开一个本地文件夹,并在 VS Code 中信任该工作区。
- 使用 JS 入口或脚本启动器时,本机需有能运行该 PI 版本的 Node.js。PI 1.5.2 要求 Node.js ≥ 22.19.0,建议安装 Node.js 24 LTS;项目可继续使用 Node 14 等旧版本,插件会自动查找兼容的已安装版本,也可通过
pi.nodePath指定。
Windows 与 macOS 使用相同的 RPC 桥接;macOS 已验证本地扩展宿主与 PI 1.5.2 的连接。远程、虚拟和未受信任工作区不启动 PI;Linux 尚未实测。
上架后,可在扩展视图中搜索 @id:SilasPaul.pi-agent-coding,核对发布者为 SilasPaul 后安装;也可通过命令 code --install-extension SilasPaul.pi-agent-coding 安装。首次上架前请使用下面的 VSIX 方式。
打开 VS Code 命令面板(Windows:Ctrl+Shift+P;macOS:Cmd+Shift+P),运行 Extensions: Install from VSIX…,选择 pi-agent-coding-1.1.1.vsix。
如果从源码开始,在仓库根目录执行以下命令生成安装包:
npm ci
npm run package安装包生成于仓库根目录,文件名随 package.json 中的版本变化。也可以用 VS Code CLI 安装已生成的包:
code --install-extension .\pi-agent-coding-1.1.1.vsix- 运行 PI: Open Sidebar,默认在右侧辅助侧边栏打开 PI。
- 插件在 VS Code 启动完成后激活并自动连接本机 PI,无需点击连接;多根工作区会提示选择本次 PI 的工作目录。仅在受信任的本地文件工作区自动连接。
- 如果找不到 PI,插件会提示 打开安装说明 或 配置 PI 路径。按官方说明在本机安装 PI,完成 PI 自身的登录或模型配置后重启 VS Code;如果已经安装,在用户设置中填写
pi.executablePath后运行 PI: Reconnect。插件只提供安装引导,不自动执行安装命令。 - 输入问题并按
Enter发送;Shift+Enter换行,中文输入法选字期间的Enter不会发送。
插件会启动一个独立的 PI RPC 进程,不会接管已有终端中的 PI 进程。模型、技能和工具由该进程按 PI 原有配置加载,插件不额外保存供应商凭证。
在 VS Code 设置中搜索 @ext:SilasPaul.pi-agent-coding,或从侧栏的 ⋯ → 插件设置 进入。
| 设置 | 默认值 | 说明 |
|---|---|---|
pi.executablePath |
空,自动检查 PATH 与常见目录 |
本机 PI 入口的绝对路径;支持可执行文件、JS 入口及可识别的官方 / npm 脚本启动器 |
pi.nodePath |
空,自动检查 Node.js 安装目录 | 运行 PI JS 入口时使用的 Node.js 可执行文件 |
pi.requestTimeoutMs |
10000 |
普通控制请求的等待时间,单位毫秒 |
pi.startupTimeoutMs |
60000 |
PI 版本检测与启动握手的等待时间,单位毫秒 |
pi.shutdownTimeoutMs |
5000 |
断开时等待 PI 正常退出的时间,超时后清理本次启动的进程树 |
路径设置为机器级设置,请配置在 用户设置,不要写入仓库的 .vscode/settings.json。超时设置最小为 1000 毫秒;模型生成、压缩等长操作不使用普通控制请求的短超时。
以下仅为 Windows 路径写法示例,请将路径替换为自己的实际安装位置:
{
"pi.executablePath": "C:\\path\\to\\pi.ps1",
"pi.nodePath": "C:\\Program Files\\nodejs\\node.exe",
"pi.requestTimeoutMs": 10000,
"pi.startupTimeoutMs": 60000,
"pi.shutdownTimeoutMs": 5000
}Windows 官方 .ps1 / .cmd 启动器、npm shim 与 macOS npm 符号链接会解析到对应 JS 入口。macOS 官方托管安装器按 current-version 读取当前 PI 入口,每次重连重新解析,避免固定到旧版本;插件不执行任意自定义 shell 包装脚本。
自动发现优先使用显式设置,其次使用 VS Code 继承的 PATH。缺少 PATH 时,配置的 pi.nodePath 所在目录也可用于查找 PI;已找到 PI 时,会在启动器及其符号链接目标所在目录查找 Node.js,然后检查环境变量指定的安装位置和常见目录。支持自定义 VOLTA_HOME、npm prefix、Windows NVM_SYMLINK 与 POSIX NVM_BIN,也检查用户 .local/bin、PI 托管目录、Windows 用户 npm 与系统 Node.js / Volta 目录,以及 macOS 的 Apple Silicon / Intel Homebrew 路径;POSIX 另识别 nvm 默认版本与 fnm 默认别名。路径按所在平台规则解析,不依赖固定用户名或盘符。
运行 JS 入口前,插件会检测候选 Node 的版本,跳过低于 PI 1.5.2 运行基线 22.19.0 的版本或无法运行的候选,并补查 nvm、Volta、fnm 常见目录中未激活的已安装版本;已通过版本管理器为项目选择 Node 14 时,也可找到其他兼容版本。版本检测使用 PI 将要运行的工作目录,单个候选的版本检测在 3 秒后触发终止;清理命令和等待管道关闭也有单独超时(均为插件限制)。连接取消或资源管理服务销毁时,会取消检测;断开连接会等待检测清理结束。显式配置的 pi.nodePath 不合适时直接报错,不自动覆盖用户选择。发现的 Node 与安装目录只加入本次 PI 子进程的 PATH,不改写系统或项目配置。此机制不让 PI 在 Node 14 上运行,也不自动下载 Node;仅安装旧 Node 时,需另行安装兼容版本。未覆盖的自定义安装布局仍需手动配置 pi.executablePath 和 pi.nodePath。后续 PI 版本可能有更高的运行要求。
Windows 自动发现按大小写不敏感的规则读取环境变量(例如 ProgramFiles / PROGRAMFILES),并优先使用 USERPROFILE 定位用户 PI 目录,避免 Git Bash 的 HOME 指向其他位置时漏掉原生安装。除用户 Volta 目录外,也检查 Program Files\Volta 中的 Node.js。环境中同时存在 PATH / Path 时,沿用 Node.js 的 Windows 优先级,向 PI 子进程只传递一个 PATH 变量。
macOS 如果从 Dock 启动 VS Code 后提示找不到 PI,请先在终端运行 command -v pi 和 command -v node 核对安装。必要时将 PI 官方 JS 入口与 Node 的绝对路径分别填入 pi.executablePath、pi.nodePath。找不到 PI、找不到 Node、无法识别启动器和文件不可执行会分别提示;版本检测失败会附带有界 stderr 诊断。更改设置后,通过 PI: Reconnect 或侧栏重新连接使其生效。
选中文本后,在编辑器右键菜单运行 PI: Attach Selection,或从命令面板运行同名命令。插件读取当前编辑器内容,因此未保存修改也能发送。
点击输入区的 + 图标添加 UTF-8 文本或图片;模型和思考强度位于它右侧的同一行。也可以在输入框粘贴图片,或将图片拖入侧栏。发送前可移除附件。切换到不支持图片的模型时,插件会阻止携图发送并提示处理。
在输入框输入 @ 搜索当前工作区文件和文件夹,文件夹候选以 / 结尾并标注“文件夹”;也可选择列表中的 选择文件夹…,从当前工作区选择目录,包括空目录和未被初始路径枚举覆盖的目录。文件夹作为路径引用发送,由 PI 根据任务按需读取其中的文件,不会自动把整个目录的正文递归加入消息。点击文件夹附件名称可在资源管理器中定位该目录。
输入 @open: 选择已打开文档,@current: 选择当前编辑器文档。用上下键选择、Enter 或 Tab 确认、Escape 关闭;搜索仅枚举路径,明确选择文件后才读取内容。已打开的未保存修改和未命名文档使用编辑器当前文本。文件搜索遵循 files.exclude / search.exclude 的布尔排除规则,跳过 .git 和 node_modules;插件最多枚举 2,000 个初始文件路径,并从这些路径提取父目录,展示最多 30 个候选(含文件夹选择入口)。大工程请输入更完整路径以触发定向搜索,不保证完整模糊检索。
新发送的附件在聊天和待处理队列中只显示名称及必要信息(文本 / 图片类型和大小,或文件夹引用),聊天中的文件名称可点击跳转;文件正文仍完整发送给 PI。恢复会话后继续显示附件摘要。此前发送且没有附件标记的历史消息保留原有显示方式。
资源管理器选中文件后右键 PI: 添加到 PI,可一次附加多个文件。通过 ⋯ → 选择诊断作为附件 搜索并选择一条诊断;不会自动收集工程诊断或文件正文。聊天中的 Markdown 文件链接(例如 src/main.ts:12:3、main.ts#L12)和附件名称可以跳转到文件;只允许当前工作区或用户已明确附加的文件。
回复和代码块旁提供复制按钮;在编辑器打开 创建未保存文档,供继续编辑。输入框在起始位置按上方向键回看输入历史,再按下方向键返回草稿;Ctrl/Cmd+R 搜索最近输入,最多保存 50 条,每条不超过 100,000 字符。历史仅保存在侧栏状态中,不保证跨窗口永久保存。
点击底部模型名称或思考强度,在对应按钮旁展开的侧栏下拉菜单中选择 PI 返回的可用选项。下拉选项以背景高亮表示选中状态,不显示对勾。菜单支持键盘导航和 Escape 关闭。在输入框键入 / 可筛选 PI 发现的技能、提示模板和扩展命令,选择后立即发送执行,内容的解释与展开由 PI 完成。需要补充参数时,可手动输入完整命令,例如 /compact 保留重点,然后发送。
菜单展示 PI 通过 RPC 发现的命令及前述插件快捷操作,不等同于 PI 终端界面的全部内置命令。需要交互登录、终端设置或自定义终端 UI 的操作仍应在 PI 自身完成。
/ 候选支持上下键、Enter / Tab 和 Escape。通过 ⋯ → 技能与模板来源 查看 PI 返回的来源信息;选择有本地来源路径的条目可在编辑器查看。PI 未返回路径的资源只显示已有信息。侧栏获得焦点时,Alt+Shift+M 轮换 PI 模型,Alt+Shift+T 轮换思考强度;也可从更多菜单或命令面板操作。
- 默认发送:点击箭头或按 Enter,空闲时开始对话;运行中将消息加入 PI 的 follow-up 队列,作为后续消息,无需选择发送方式。
- 引导:点击某条后续消息旁的“引导”,将它转为补充指示,由 PI 在当前工具执行结束后的可处理时机接收;不会中止当前任务。入队成功不代表模型已经处理。
- 清空并恢复到输入框:清空队列,并将返回的队列文本追加到草稿,便于修改后重新发送。
- 停止全部:先清空队列,再中止当前运行,避免停止后又执行已排队的消息。
点击侧栏顶部的 设置 → 队列处理(高级),可分别设置后续队列和引导队列的 逐条处理 或 一次处理全部。这两项保留 PI 的队列批量处理能力,仅决定每次取出多少条消息,不会改变默认发送为后续消息的交互;实际处理时机由 PI 决定。高级区域默认折叠,设置未知时显示未知,不推算默认值。
引导限制(插件):PI 1.5.2 没有单条队列转换 RPC,插件使用清空队列并重新提交的方式实现,仅适用于未被输入扩展改变的纯文本队列。插件会禁用已知含图片、斜杠命令、相同文本或来源不明的队列,并说明原因。RPC 只回传队列文本,无法识别输入扩展在保留原文时自动添加的图片;此类队列不支持“引导”,请勿使用该按钮,以免丢失扩展添加的内容。重新提交会再次运行输入扩展,可能改变内容或重复产生副作用。
重排期间不能发送、清空或切换会话,停止仍可用。目标已经被 PI 消费时不会重复发送它。重排不是原子操作;如请求失败,不自动重试结果不确定的消息,确定尚未重新提交的文本会追加回草稿,请检查错误提示、对话和队列后处理。若点击停止时仍有未确认的引导提交,插件会先尝试清空队列和中止运行,再断开本窗口的 PI 进程,防止在途输入稍后继续执行;需要重新连接。
顶部 + 新建会话,历史 在按钮下方展开当前工作区曾通过插件打开的会话,点击记录即可切换;点击外部或按 Escape 关闭列表。⋯ 中可重命名、打开其他 PI .jsonl 会话文件、分叉、复制或导出 HTML。
历史列表使用插件自己的工作区索引,不会扫描 PI 的全局会话库。历史树用于只读浏览,选择节点不会切换对话。分叉与复制仅改变对话上下文,不会撤销 PI 已经写入的文件。
连接后自动恢复当前工作区索引中最近打开的会话;恢复失败会显示错误并保留可用连接。历史弹层可按名称、ID 或路径筛选。聊天顶部 搜索对话 只筛选当前可见消息;搜索 PI 完整历史 通过 get_entries 搜索压缩前及其他分支的文本,最多列出 100 条匹配,每条最多预览 4,000 字符,不切换历史节点。
用户消息旁的 修改后重新提问 使用 PI 分叉,当前分支回到该消息之前,后续回复不再显示;原问题会立即放回输入框并聚焦,修改后自行发送。从第一条问题分叉时,当前分支会暂时显示空对话。后续信息刷新失败不会丢失已恢复的草稿。若压缩等原因使可见消息无法准确对应 PI 分叉点,请改用更多菜单里的分叉操作。本次对话修改的文件 只列出当前加载消息中已观察到的成功 write / edit 路径,不声称覆盖 shell、MCP 或外部进程的全部修改;打开源代码管理 使用 VS Code 自身的 Git/SCM 视图。
点击历史记录右侧的移除按钮可将其从当前工作区历史列表移除,列表会立即刷新。此操作仅移除插件索引,保留 PI 的 .jsonl 会话文件,也不会中断当前对话;仍可通过“打开其他 PI 会话文件…”重新打开。移除当前会话记录后,后续重命名、刷新或重新打开该会话时,记录可能重新加入历史。
底部状态行显示 PI 返回的 token、费用和上下文占用;暂不可用或尚未更新的上下文会显示相应提示。点击这行用量信息可发起 手动压缩上下文,也可用 Tab 聚焦后按 Enter 或空格打开;在弹出的输入框中可填写摘要需要保留的信息,留空确认使用 PI 默认策略,按 Escape 取消。未连接、任务运行或压缩期间入口不可用,压缩时显示“正在压缩…”,完成后刷新用量,失败时显示 PI 返回的错误。压缩是整理上下文,不等于删除指定问答。点击侧栏顶部的 设置 打开面板,可调整自动压缩、自动重试或发起手动压缩;点击关闭、面板外部或按 Escape 关闭。插件不叠加自己的模型请求重试循环。
展开 Bash 命令(由 PI 执行) 可通过 PI 的 bash RPC 执行独立命令,例如 git status 或 echo PI。自然语言问题(例如“你好”)请在上方聊天输入框发送;Bash 命令面板会将输入直接作为命令执行。默认情况下,其输出会在下一次模型请求时加入上下文;勾选 不加入上下文 可排除本次输出。该面板不提供持续交互式终端。
面板中的 命令退出码 属于本次 Bash 命令;127 通常表示未找到命令,不代表 PI 进程退出。检查命令名称及 PI 使用的 Bash 环境;若要与 AI 对话,改用聊天输入框。
也可以在聊天输入框以 ! 开头输入命令,例如 !git status,发送后自动展开命令面板,取消仍使用 PI 的 bash 取消 RPC。此快捷方式不接收附件;命令最多 100,000 字符(插件限制)。侧栏隐藏或 VS Code 窗口不在前台时,插件在任务结束、失败或等待扩展交互时发送 VS Code 通知;当前前台侧栏不会重复通知。
PI 默认注册在右侧辅助侧边栏,可与左侧文件资源管理器同时显示。右侧被隐藏时,运行 View: Toggle Secondary Side Bar Visibility,再运行 PI: Open Sidebar。
更新已有安装后,VS Code 可能保留之前的左侧布局。右键 PI 视图标题,选择 Move View → Secondary Side Bar(移动视图 → 辅助侧边栏);也可将 PI 视图拖到右侧。需要放回左侧时选择 Primary Side Bar(主侧边栏)。移动的是同一个视图,会话和 PI 进程继续使用。
隐藏侧栏不会停止 PI 的当前任务。通过 ⋯ → 断开 或关闭扩展会清理插件创建的 PI 进程;异常断开后需主动重新连接,插件不会自动重放上次消息。
发送尚未确认时断开会保留输入草稿,重新连接后可自行检查对话并决定是否再次发送。重命名、压缩和导出对话框打开期间若切换会话或重新连接,插件会提示重新操作,避免操作落到其他会话;旧连接或旧会话的延迟刷新结果不会覆盖当前数据。PI 取消新建、分叉或复制时,相关快捷命令也会保留在输入框。
点击侧栏 设置 → MCP / Skills / 扩展管理、更多菜单中的同名入口,或运行命令 PI: 管理 MCP / Skills / 扩展,打开资源管理面板。三个页签支持搜索及“当前项目 / 用户”范围切换。
- MCP:查看
mcp.json中的服务器配置,添加 stdio / HTTP 服务器,启用、禁用、移除,选择 codemode / deferred / direct / hidden 暴露方式;用户服务器可单独设置当前项目的启用覆盖。登录、退出登录和独立诊断调用 PI 自身的pi mcp命令,结果显示在任务终端。环境变量、认证头及其他高级字段通过原生编辑器修改,侧栏摘要不包含命令参数、URL 或凭证。 - Skills:发现用户、项目和
.agents/skills中的本地技能,创建SKILL.md、添加本地路径、打开来源,以及通过精确路径规则启用或禁用。包内技能也可通过 PI 包配置管理。 - 扩展 / 包:发现本地扩展入口,添加路径,调整内置扩展和本地资源的启用规则;调用 PI 安装、更新、移除包。包过滤可保留默认、禁用某类资源,或编辑对应的过滤规则数组;复杂包选择也可打开 PI 原生
config终端界面。更新全部使用pi update --extensions,其范围由 PI 决定,包含用户和项目包。
项目配置位于当前 PI 工作目录的 .pi/settings.json 和 .pi/mcp.json;用户配置位于 PI_CODING_AGENT_DIR 指定的目录,未设置时使用 ~/.pi/agent。项目配置仍受 PI 自身的项目信任控制,VS Code 的工作区信任不会自动替代它;若 PI 拒绝读取或修改项目配置,请先在该项目目录通过 PI 原生信任提示完成授权。界面修改使用原生编辑器 API 保存,保留其他字段;遇到无效 JSON、未保存的编辑或配置已被其他操作改变时会提示先处理并刷新。
保存资源配置后,点击 重连并应用。插件在当前任务、压缩、独立命令、队列及资源管理任务均已结束时,重连本窗口的 PI,并尝试恢复原来的会话文件;恢复失败会明确提示。重连期间在编辑器保存的新变更会保留“待应用”提示,需要再次重连。运行中仍可使用面板的“停止全部”。外部修改保存后也需刷新列表并应用。资源管理命令在 VS Code 任务终端运行,关闭面板不会取消它,可在任务终端终止。
列表明确区分“文件配置”“本地发现”和“PI 当前命令”。本地资源读取失败会单独显示提示,不中断其他资源的发现。这些记录不构成完整的运行时资源清单:无命令的扩展、动态注册的 MCP 和资源加载错误没有完整 RPC 查询接口。独立诊断会启动另一个 PI 进程连接服务器,不能代表侧栏进程的实时状态。此功能不提供通用热重载,也不保证任意第三方扩展的终端自定义 UI 能在侧栏呈现。
| 命令面板名称 | 命令 ID | 用途 |
|---|---|---|
| PI: Open Sidebar | pi.open |
打开 PI 侧栏 |
| PI: Attach Selection | pi.attachSelection |
将当前选区添加为附件 |
| PI: Reconnect | pi.reconnect |
按当前配置重新连接本机 PI |
| PI: 添加到 PI | pi.attachFiles |
附加资源管理器明确选中的文件 |
| PI: 轮换模型 | pi.cycleModel |
调用 PI cycle_model |
| PI: 轮换思考强度 | pi.cycleThinking |
调用 PI cycle_thinking_level |
| PI: 管理 MCP / Skills / 扩展 | pi.manageResources |
管理用户和项目的 PI 资源配置 |
| 情况 | 处理方式 |
|---|---|
| 找不到 PI | 点击提示中的“打开安装说明”安装本机 PI;安装后重启 VS Code 以更新环境变量,或通过“配置 PI 路径”设置 pi.executablePath 后重新连接 |
| 提示启动器无法识别 | 改用 PI 官方启动器、JS 入口或可执行文件;自定义 shell 包装脚本不会直接执行 |
| 提示 Node 不存在、不兼容或启动失败 | PI 1.5.2 需要 Node ≥ 22.19.0;安装 Node.js 24 LTS 后重连,插件会自动跳过旧版本;自定义路径可配置 pi.nodePath |
| 无工作区、工作区未信任或是远程窗口 | 打开并信任本地文件夹后连接;首版不支持远程宿主 |
| 登录失败、模型不可用 | 在 PI 自身完成登录或模型配置,再重新连接;插件不提供凭证管理 |
| 图片发送被阻止 | 选择 PI 报告支持图片输入的模型,或移除图片;同时检查格式与大小限制 |
| 历史中找不到终端创建的会话 | 使用 ⋯ → 打开 PI 会话文件 手动打开 .jsonl 文件 |
| 压缩提示会话内容较少 | PI 返回 Nothing to compact (session too small) 时,插件显示无需压缩的普通提示,可继续对话;不按上下文百分比推算压缩门槛 |
| 连接超时、进程退出或输出协议错误 | 查看侧栏错误及 输出 → PI 中的启动诊断,修正路径、Node 或 PI 配置后主动重连 |
插件负责 UI、配置编辑和 PI 协议桥接,不打包 PI 智能体运行库,不直接调用模型 API,也不安装或自动改写 PI。资源的安装、加载、执行和认证仍由 PI 处理。
- 修改结果:工具差异来自 PI 实际执行后的返回结果,不提供逐块审批、文件快照或自动回滚。
- 工具与 MCP:由 PI 自己加载和执行;插件展示工具结果并管理原生配置,不建立第二套 MCP 客户端。真实 MCP 连接、OAuth 及第三方扩展交互环境尚未验收。
- 终端能力:不桥接终端主题同步或任意自定义终端 UI;PI 原生配置与 MCP 登录在独立任务终端中交互。
- 兼容性:PI 1.5.2 是验证基线,不代表所有 PI 版本都兼容;macOS 当前只验证连接、进程生命周期及现有扩展宿主用例,真实模型、MCP、完整辅助功能矩阵与长会话成功压缩仍未验收;Linux 尚未实测。
插件自身的输入与展示限制如下,不代表 PI 或模型服务的限制:
| 项目 | 限制 |
|---|---|
| 文件 / 单张图片 | 每个不超过 5 MiB |
| 图片合计 | 不超过 15 MiB |
| 附件数量 | 最多 100 个 |
| 工具文本 / 修改差异预览 | 每个文本块或差异最多 30,000 字符 |
| 独立命令输出预览 | 保留末尾 200,000 字符,插件截断会标注;PI 返回完整输出路径时同时展示 |
| 资源配置读取 | 每个配置文件不超过 1 MiB |
| 本地资源发现 | 每次遍历最多 1500 个节点、10 层目录、300 项;不递归子符号链接 |
| 资源管理列表 | 最多显示 700 项;复杂过滤的实际效果由 PI 决定 |
开发验证环境为 Node.js 24.22.3、npm 11.19.1,package.json 的 volta 字段已将 Node 固定到 Node 24 的最新版本(安装 Volta 后在该目录即自动使用)。在仓库根目录运行:
npm ci
npm run compile随后在 VS Code 中按 F5,选择 Run PI Extension 启动扩展开发宿主。可用 npm run watch 监听源码并重新构建。
| 命令 | 作用 |
|---|---|
npm run check |
TypeScript 类型检查 |
npm run validate |
类型检查、单元测试和模拟 PI 进程集成测试 |
npm test |
单元测试 |
npm run test:integration |
模拟 PI 子进程的集成测试 |
npm run test:vscode |
真实 VS Code 扩展宿主测试,使用模拟 PI |
npm run test:webview |
真实浏览器夹具,检查控件交互及 12 种尺寸/主题/缩放组合 |
npm run compile |
构建扩展宿主与 Webview 产物 |
npm run package |
构建并生成 VSIX |
test:vscode 使用隔离的测试配置、扩展目录和临时工作区;Windows 与 macOS 下优先使用本机 VS Code,也可通过 PI_TEST_VSCODE 指定可执行文件。没有可用本机路径时,测试工具可能下载 VS Code。测试宿主中的模拟 PI 通过不代表真实模型或 MCP 验收通过。
test:webview 使用现有 Playwright Core,本机 Windows 优先查找 Edge / Chrome,也可通过 PI_TEST_BROWSER 指定浏览器路径。截图输出到系统临时目录,属于浏览器夹具,不是原生 VS Code 截图。资源面板已覆盖 320px / 480px、暗色 / 浅色 / 高对比度和 200% 缩放,以及搜索、范围切换和 Escape 关闭。原生 VS Code 用例使用临时配置验证资源编辑和进程任务参数;模拟测试不代表真实 MCP、OAuth、远程包安装或第三方扩展兼容性已通过。
npm test 在 Windows 基线使用 Vitest 的 vmThreads 池,避免默认池无法收集测试的问题。当前资源管理补充验证在 Windows 完成:真实 PI 1.5.2 使用专用临时工作区及隔离的 agent 目录,验证了本地包安装和移除、Skill / 扩展命令发现、包过滤在重启后生效,以及禁用 MCP 服务器的独立诊断。临时项目使用 PI 的单次 --approve 授权;未调用模型、真实 MCP 服务器或 OAuth,未修改用户供应商配置,也未验收远程 npm / Git 包安装及更新。
2026-11-12 另在专用临时目录完成真实 PI 1.5.2 的基础 RPC 冒烟验证:连接、会话读取与新建、模型与思考强度发现、命令发现、统计、重命名、Bash、历史树与分叉点查询、停止,以及空会话导出拒绝和无需压缩提示。该验证关闭扩展、MCP、技能与模板发现,使用离线启动模式,未调用模型,不代表真实生成、扩展交互或长会话成功压缩已通过。
npm run package 和 VS Code 发布前钩子会先执行 validate,任一检查失败即停止。构建会根据依赖生成 THIRD_PARTY_NOTICES.txt 并随包分发,缺少依赖许可全文时会报错。VS Code 宿主和浏览器测试需在发布前另行运行。安装包不会随源码构建自动更新,需运行 npm run package 重新生成 VSIX。
核心代码分为三部分:webview/ 提供界面,src/pi/ 管理启动与 JSONL RPC,src/features/ 连接编辑器、附件、会话和扩展交互。Webview 无法直接读取本机文件、启动进程或连接模型供应商。
消息与所选附件交给本机 PI;PI 可能按你的供应商配置将内容发送到外部模型服务。插件不另外保存供应商凭证,也不包含分析遥测。会话索引、草稿及 PI 会话的存储范围见 隐私说明。
问题和建议请提交到本仓库的 Issues,附上扩展、VS Code、PI 版本及复现步骤。请在分享诊断前移除凭证、私人路径和会话内容。
MIT。本仓库许可证适用于插件代码;打包依赖的许可与版权声明见 第三方许可。本机安装的 PI 及相关服务遵循其各自的许可与条款。
当前仓库尚未包含 Windows / macOS CI 工作流,需分别执行类型检查、单元测试、进程集成测试、构建及扩展宿主测试;本地通过不代表另一平台已经通过。两平台的现有用例覆盖含空格和中文路径、stdin EOF、启动取消、协议损坏与强制清理子进程;macOS 使用插件独占的进程组,Windows 使用当前 PID 的 taskkill /T。
本轮 macOS 实测:PI 1.5.2 在移除用户 PATH 且不配置入口的情况下自动发现并完成 get_state 握手;未发送模型请求。UI 样式未改动,未重新执行完整主题、缩放和响应式截图矩阵。
自动发现回归用例使用临时目录和独立环境变量,覆盖自定义 PI / Node 路径、便携目录、自定义 Volta / npm / nvm 位置及配置优先级;目录生成用例还覆盖多个 Windows 盘符与 POSIX 路径规则。这些模拟用例不等同于在所有操作系统、Node.js 管理器和自定义安装布局上的实机验证。
本轮 Windows 补充实测:在含空格和中文的专用临时目录中,移除继承的 PATH 后自动发现官方 PI 启动器和系统 Volta,完成 PI 1.5.2 版本检测与 get_state 握手。独立测试环境清除了上游代理进程携带的 Volta 内部递归标记;关闭扩展、技能与模板发现,使用离线模式且不保存会话,未发送模型请求或修改用户配置。
Node 版本筛选的回归用例模拟了 Node 14 / 16 / 18 / 20 / 22.18 候选、兼容版本回退、未激活的版本管理器安装、显式路径拒绝和检测取消;另验证了检测超时、输出上限、取消与清理竞态、资源管理销毁,以及 Windows 清理命令失败或卡住时的兜底。Windows 已通过单元测试、进程集成测试、构建与 8 项原生 VS Code 扩展宿主用例,并在临时目录自动选中真实 Node 24.22.3,执行真实 PI 1.5.2 的 --version。本次未在真实 Node 14 环境或 macOS 重跑,也未调用模型;这些结果不代表 PI 可以直接在 Node 14 上运行。