Skip to content
| Marketplace
Sign in
Visual Studio Code>SCM Providers>Pi Shadow AgentNew to Visual Studio Code? Get it now.
Pi Shadow Agent

Pi Shadow Agent

xiaobing

|
1 install
| (0) | Free
Run the Pi AI coding agent in a native VS Code sidebar and review every AI file change with a per-turn shadow Git diff — no stash, no commits.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

Pi Shadow Agent

在 VS Code 原生侧栏里使用 Pi coding agent,并用独立的影子 Git 仓库逐轮记录 AI 造成的文件改动。

Use the Pi coding agent inside a native VS Code sidebar — and keep every file change it makes in a per-turn shadow Git history, without ever touching your own .git.

扩展把 Pi CLI 以 --mode rpc 子进程方式接入 VS Code:聊天视图是原生 webview(可选中、Ctrl+C/Ctrl+F、代码块复制、path:line 跳转),改动记录落在插件自有的裸仓库里,可随时按「轮次」回看 diff。


为什么用它

AI 改动全程留痕 影子 Git 仓库按「一轮对话一次提交」记录 AI 带来的每一个文件改动,Ctrl+Alt+D 一键看本轮 / 本次会话 diff,不用 git stash 也不会污染你的工作分支
原生 VS Code 体验 活动栏 + 右侧辅助栏两个入口(共用同一份 Pi 会话)、状态栏用量、树视图、原生 QuickPick diff、编辑器标题栏「查看历次差异」
会话可追溯可导出 磁盘会话历史浏览、按消息 fork / clone、导出 HTML、/share 预览、跨会话成本统计
工程外改动单独归类 AI 写到工程目录之外的文件全部进 external/ 独立分组,UI 显著警示,绝不静默
只读、不越权 不自动改工作区、不自动 commit、不自动回滚;未授信工作区不启动任何进程;疑似密钥文件只记哈希不存原文

环境要求

依赖 版本 说明
VS Code ≥ 1.96 需要 secondarySidebar(右侧辅助栏)容器
Pi CLI ≥ 1.5.2 见下方 安装 Pi
Node.js ≥ 22.19 运行 Pi 子进程(不要是 Code.exe;扩展会自动探测 node.exe)
Git ≥ 2.40 影子仓库用 hash-object / mktree / commit-tree 等 plumbing 命令

实测环境:VS Code 1.108.2 · Pi 1.5.2 · Node v24.14 · Git 2.52。Windows 10/11 优先,同时兼容 macOS / Linux / WSL / Remote-SSH。

安装 Pi

# Windows
powershell -c "irm https://pi.dev/install.ps1 | iex"
# macOS / Linux
curl -fsSL https://pi.dev/install.sh | sh

安装脚本会装到 ~/.pi/agent/(本扩展会自动探测该托管安装)。也可用 npm 全局安装:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

自检:

pi --version      # ≥ 1.5.2
node --version    # ≥ v22.19.0
git --version     # ≥ 2.40

安装

从 Marketplace 安装:扩展面板搜索 Pi Shadow Agent,或

code --install-extension xiaobing.pi-shadow-agent

从 VSIX 安装(离线 / 内测版本):

code --install-extension pi-shadow-agent-0.3.0.vsix

安装后重新加载窗口即可。


快速开始

  1. 打开面板:点活动栏的 Pi 图标(或 Ctrl+Alt+P),聊天视图出现在侧栏;想让它在右侧辅助栏(Codex / Claude Code 同位置)就按 Ctrl+Alt+Shift+P。
  2. 信任工作区:弹出提示时选择「信任并启用」。未授信工作区不会启动 Pi 进程。
  3. 直接对话:输入需求,回车。AI 改动的文件会实时出现在 Pi 变更 视图和状态栏的 Pi 变更 N 计数里。
  4. 回看改动:Ctrl+Alt+D 打开变更总览,或点聊天视图标题栏的 $(diff-multiple) 按对话轮次挑选某一轮看 diff。

首次使用若提示「未找到 Pi CLI」,运行 Pi: 检查运行环境,它会指出具体缺哪一环。见下方 故障排查。


功能一览

对话与模型

  • 流式输出、思考块折叠、工具卡片(含耗时 / 错误态 / 参数与结果折叠)、/ 斜杠命令补全、@ 文件引用、图片粘贴与拖拽
  • 运行中可 steer 插话或 follow-up 排队;Pi: 取回排队消息 收回
  • 模型 / 思考级别随时切换,状态栏显示上下文占用与累计花费,Pi: 压缩上下文 手动 compact
  • 扩展 UI 请求(确认 / 选择 / 输入 / 进度 / 通知)自动映射到原生 QuickPick 与输入框

会话

  • 新建 / 重命名 / fork / clone / 导出 HTML / /share 预览
  • 磁盘历史会话:扫描 ~/.pi/agent/sessions/**/*.jsonl,按首条用户消息命名、本工作区优先、时间倒序;恢复前会校验文件存在
  • 崩溃后自动恢复上一次会话
  • 并行会话:会话栏的「⧉ 并行」、标签栏的 +、/parallel 或 Ctrl+Alt+T 新开一个标签,每个标签是独立的 Pi 进程,可同时运行;后台标签运行中显示转圈、完成后显示蓝点,切回即看到完整输出。中键或 × 关闭标签(会停止该进程),Ctrl+Alt+S 列出全部标签切换;在「Pi 会话」视图右键历史会话可「在新标签中打开」。同一会话文件不会被两个标签同时打开
  • Pi: 在终端中打开(TUI) 拉起真终端 Pi(与原生面板共用同一会话 JSONL)

影子 Git 改动记录

  • 一轮对话一次提交:工具执行只累积候选路径,agent_settled 时统一落一次提交;abort / IPC / settle 多信号合并改写同一 commit(不会产生重复提交)
  • 三个层次的采集:L1 Pi 事件 / L2 Pi 扩展 sidecar IPC / L3 git status + 编辑器变更,任一失败自动降级
  • Pi 变更 树按 scope → 轮次 → 文件 组织;原生 vscode.diff 左右对比;可复制文件内容 / 复制 diff 补丁 / 导出会话快照包
  • 变更总览面板:过滤、搜索、导出;编辑器标题栏「查看当前文件历次差异」
  • 工程外改动进 external/ 独立树,只读导出目录浏览,绝不写回原绝对路径
  • 自动 GC + 保留期(默认 90 天),Pi: 清除本会话影子数据 随时清空

与编辑器集成

  • 右键发送:选区 / 当前文件 / 资源管理器文件
  • 发送 Problems 诊断、Git 差异、暂存区差异
  • 生成 Git 提交信息(SCM 标题栏按钮)
  • 改动逐条「应用 / 拒绝」草稿:只生成补丁草稿 + 二次确认,绝不自动覆盖
  • 保存即审查(可选,带 debounce)
  • MCP 服务列表面板、子代理(subagent)树视图、诊断面板

其他入口

  • @pi chat participant:内置 Chat 视图需要任意提供 chat agent 的扩展(Copilot Chat、ChatGPT/Codex 等均可,扩展按 manifest 的 chatParticipants 贡献自动识别,不绑定具体扩展);没有任何 agent 时 Pi: 在原生 Chat 里选择 @pi 会说明原因并提供「仍尝试打开 / 使用右侧 Pi 面板」两个选项
  • /bug 报告向导

常用命令

命令面板输入 Pi: 可列出全部 50 个命令,最常用的:

命令 说明
Pi: 新建会话 / Pi: 历史会话(浏览并恢复) 会话起点
Pi: 打开变更总览 全部改动列表(过滤 / 搜索 / 导出)
Pi: 历史变更(按对话轮次查看改动)… 挑某一轮看 diff
Pi: 查看本轮全部差异 / Pi: 查看本会话累计差异 直接出补丁
Pi: 查看最近一轮改动(原生差异) 原生左右对比
Pi: 在终端中打开(TUI) 切到真终端 Pi
Pi: 逐条审查改动(应用 / 拒绝) 补丁草稿流程
Pi: 生成 Git 提交信息 基于暂存区 / 改动生成 message
Pi: 跨会话成本 / 变更统计 全局汇总
Pi: 检查运行环境 Node / Pi / Git / 信任四项体检 + 一键修复
Pi: 重启 Pi 进程 改完 pi.nodePath、pi.model 等设置后生效
Pi: 打开诊断面板 运行时、RPC 状态、候选路径、日志排障

快捷键

快捷键 命令
Ctrl+Alt+P / Cmd+Alt+P 聚焦左侧 Pi 聊天
Ctrl+Alt+Shift+P / Cmd+Alt+Shift+P 在右侧辅助栏打开 Pi
Ctrl+Alt+D 打开变更总览
Ctrl+Alt+Shift+D / Cmd+Alt+Shift+D 查看最近一轮改动(原生差异)
Ctrl+Alt+Enter 把选中代码发送给 Pi
Ctrl+Alt+X 中断当前运行(仅运行中生效)
Ctrl+Alt+T / Cmd+Alt+T 新开并行会话标签
Ctrl+Alt+S / Cmd+Alt+S 切换会话标签

配置

全部设置都在 Settings → Pi。运行时相关:

设置 默认 说明
pi.executablePath "" Pi 启动器路径;空 = 自动探测
pi.cliEntryPath "" Pi 的 cli.js;空 = 自动探测托管安装与 npm 全局安装
pi.nodePath "" 运行 Pi 的 node(Windows 上优先真 node.exe)
pi.model "" provider/modelId,空 = 沿用 Pi 默认模型
pi.thinkingLevel medium off … max
pi.enableTui true 是否显示 TUI 入口
pi.multiSession false 已废弃:并行会话始终可用

带 ⚠ 的设置会写入 Pi 的启动参数,改动后需 Pi: 重启 Pi 进程 生效(扩展会主动提示):pi.executablePath、pi.cliEntryPath、pi.nodePath、pi.model、pi.thinkingLevel、pi.shadowGit.enabled、pi.shadowGit.usePiExtension、pi.shadowGit.location、pi.shadowGit.customPath。

影子 Git 相关:

设置 默认 说明
pi.shadowGit.enabled true 总开关
pi.shadowGit.location globalStorage globalStorage / workspaceStorage / custom
pi.shadowGit.customPath "" location=custom 时使用
pi.shadowGit.scope workspaceAndExternal 是否记录工程外改动
pi.shadowGit.externalPolicy explicitWrites explicitWrites(推荐)/ allowlistOnly / all
pi.shadowGit.externalAllowlist [] 额外允许记录的工程外根目录(绝对路径)
pi.shadowGit.maxFileBytes 2097152 单文件上限
pi.shadowGit.maxTotalBytes 67108864 base 快照总量上限
pi.shadowGit.baseMode auto 超限自动降级为仅候选
pi.shadowGit.excludeGlobs 见设置 默认排除 node_modules / .git / dist / build / *.log / 会话目录
pi.shadowGit.redactSecrets true 疑似密钥只记路径 + 大小 + sha256
pi.shadowGit.retentionDays / autoGc 90 / true 保留期与自动清理
pi.shadowGit.usePiExtension true 注入 Pi 扩展做精确采集,失败自动降级

保存即审查:pi.reviewOnSave.enabled(默认 false)、.debounceMs(3000)、.prompt(模板,${files} 占位)。


影子仓库原理

hash-object -w  →  update-index -z --index-info  →  write-tree
                →  commit-tree  →  update-ref (CAS)

全程使用独立的临时索引和裸仓库(默认 globalStorageUri/pi-vscode/shadow/<repoKey>.git),不设 --work-tree,因此不受你的 .gitignore、暂存区、分支、子模块影响;内容按内容寻址自动去重,元数据存 refs/pi/meta/<commit>(不产生 notes 噪音提交)。

安全与边界

  • 只读记录:不自动应用到工作区、不自动 commit、不自动回滚;「应用」只生成待人工检查的补丁草稿。
  • 未授信不启动:工作区未授信时不会 spawn 任何 Pi 进程。
  • 不碰用户仓库:影子仓库与 refs/pi/* 完全独立。
  • 密钥脱敏:疑似密钥文件默认只存路径 / 大小 / sha256。
  • 工程外只读:external/ 中的文件只用于查看与导出,绝不写回原绝对路径。
  • 采集局限:L3 只能覆盖已知候选路径,bash 脚本在别处创建且从未被提及的文件不保证记录 —— 可用 Pi: 手动重新扫描当前工作区 补一次。

故障排查

第一步永远是 Pi: 检查运行环境。 它会分别检查 Node.js、Pi CLI、Git、工作区信任四项,指出具体是哪一环失败,并给出可点击的修复入口。

现象 处理
未找到 Pi CLI(需要 >= 1.5.2) 运行 Pi: 检查运行环境。扩展会自动探测官方安装脚本布局(~/.pi/agent/install/releases/*)与 npm 全局安装(<npm root -g>/@earendil-works/pi-coding-agent);两者都不中时再手动指定 pi.nodePath(真 node.exe)+ pi.cliEntryPath
进程启动即退出 Pi: 检查运行环境 会先确认 pi.nodePath 没有误指 Code.exe;仍失败时看 Pi: 打开诊断面板 里的 spawn 命令行、stderr 和候选路径列表
改了设置没反应 pi.nodePath / pi.cliEntryPath / pi.model 等会写入启动参数,改完会提示「需要重启」;点「立即重启」或执行 Pi: 重启 Pi 进程
变更视图为空 先看视图里是否有红色错误行(Git 缺失/过旧会显示);否则 Pi: 手动重新扫描当前工作区,并确认 pi.shadowGit.enabled
聊天框能输入但没回复 聊天视图顶部应出现带「重启 Pi 进程 / 检查运行环境 / 打开诊断面板」按钮的横幅;按提示处理
历史会话列表为空 会话文件在 ~/.pi/agent/sessions/;已删除的文件不会列出(这是有意的,避免 Pi 把缺失路径当成新会话)
选项里没有 @pi 内置 Chat 需要任一提供 chat agent 的扩展(不限于 Copilot Chat)。若完全没有,Pi: 在原生 Chat 里选择 @pi 会提示原因;也可检查设置 chat.disableAIFeatures 是否关闭了内置 Chat
右侧栏打不开 VS Code ≥ 1.96 才有 secondarySidebar;或手动把 Pi 图标拖到辅助栏

诊断面板 + 输出通道 Pi 是排障首选,日志包含完整 spawn 命令行、候选路径与 RPC 状态。


开发

npm install
npm run build          # esbuild → dist/extension.js、dist/chat.js
npm run watch          # 增量构建
npm run typecheck      # tsc --noEmit
npm test               # 构建 + node --test 集成测试
npm run package        # 产出 pi-shadow-agent-0.3.0.vsix(文件名取自 package.json 版本)

调试:VS Code 打开本目录按 F5(.vscode/launch.json 已配好扩展开发宿主)。

测试全部使用 mkdtemp 临时目录与临时 bare 仓库,不触碰真实工程:JSONL framing、影子 Git 纯对象层、工程外策略与脱敏、PathMapper/glob、扩展激活、真实 pi --mode rpc 冒烟、/model 切换、历史会话发现、会话切换防护、EditTracker 逐轮 diff。

目录结构:

src/core/          Config / Log / WorkspaceRegistry / Diagnostics / AppController
                   I18n(l10n() 运行时)/ catalogs(语言目录装载)
src/pi/            Resolver / Jsonl / protocol / RpcGateway / UiBridge
src/changes/       PathMapper / ShadowGit / Collector / SnapshotService
                   ChangeTree / ShadowDocProvider / DiffCommands / OverviewPanel
                   ExternalBrowser / ExtensionIpc / EditTracker
src/session/       SessionTree / SessionDiscovery / TuiLauncher
src/views/         ChatViewProvider / StatusBar / PiChatParticipant
src/editor/        SendCommands / McpPanel
media/chat/        webview 前端(main.ts / render.ts / i18n.ts / clipboard.ts / style.css)
pi-extensions/     shadow-snapshot.ts(Pi 侧扩展,jiti 直接加载 .ts)
l10n/              en.json / zh-cn.json(所有界面文案,唯一真源)
test/integration/  helpers + l10n + shadow-git + rpc-smoke + session-*

完整的架构、命令规范与验收标准见仓库内 DESIGN.md(不随 VSIX 分发)。

国际化(i18n)

界面文案不写在代码里,代码只使用消息 ID:

this.panel = vscode.window.createWebviewPanel('pi.changesOverview', l10n('overview.changeOverview'), …);
vscode.window.showWarningMessage(l10n('info.items', count));
文件 作用
l10n/en.json 基准目录:key → 英文文案;新增 key 必须先加在这里
l10n/zh-cn.json 简体中文;必须与 en.json 的 key 完全一致
package.nls.json / package.nls.zh-cn.json package.json 里贡献点(命令名、设置项、视图名)的文案
src/core/catalogs.ts 目录装载、{0} 占位符插值、locale 归一化(zh-Hans/zh-tw → zh-cn,未知 → en)
src/core/I18n.ts 扩展宿主 l10n();media/chat/i18n.ts 是 webview 版的同一份语义

新增一种语言:

  1. 复制 l10n/en.json 为 l10n/<locale>.json 并翻译;
  2. 在 src/core/catalogs.ts 的 CATALOGS 里注册,并在 NLS_LOCALES 中加上;
  3. 复制 package.nls.json 为 package.nls.<locale>.json(VS Code 按此文件名识别清单语言)。

不需要改任何业务代码。占位符统一写成 {0}、{1}(按位置),翻译里可以调换顺序、加空格,但集合必须一致。

自动化守卫(test/integration/l10n.mjs,随 npm test 运行):

  • 各语言 key 集合一致、l10n/en.json 有中文残留时报错;
  • 占位符在两种语言之间必须匹配;
  • 源码里出现中文字符串即失败(防止文案重新写回代码);
  • l10n() 引用的 key 必须存在,目录里的 key 必须被引用(防止改名后留下死翻译)。

版本

当前 0.3.0。P0 + P1 + P2 全量能力已实现,P2 部分(多会话、保存即审查、子代理视图)为可选 / 实验性。

License

MIT

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft