Skip to content

About

VS Code 侧栏插件:通过 pi --mode rpc 驱动本机已安装的 PI coding agent,提供对话、工具结果、编辑器上下文与会话管理。

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

PI

在 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 终端中的分支切换。

安装与快速开始

1. 准备环境

  • 本机已安装并配置 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 尚未实测。

2. 安装扩展

上架后,可在扩展视图中搜索 @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

3. 连接 PI

  1. 运行 PI: Open Sidebar,默认在右侧辅助侧边栏打开 PI。
  2. 插件在 VS Code 启动完成后激活并自动连接本机 PI,无需点击连接;多根工作区会提示选择本次 PI 的工作目录。仅在受信任的本地文件工作区自动连接。
  3. 如果找不到 PI,插件会提示 打开安装说明 或 配置 PI 路径。按官方说明在本机安装 PI,完成 PI 自身的登录或模型配置后重启 VS Code;如果已经安装,在用户设置中填写 pi.executablePath 后运行 PI: Reconnect。插件只提供安装引导,不自动执行安装命令。
  4. 输入问题并按 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

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 和扩展包

点击侧栏 设置 → 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 兼容性验证

当前仓库尚未包含 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 上运行。

About

VS Code 侧栏插件:通过 pi --mode rpc 驱动本机已安装的 PI coding agent,提供对话、工具结果、编辑器上下文与会话管理。

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages