企业官网建设流程全解析

1. 为什么要把 pi 从 VS Code 里“搬”出来

1.1 先用一句话说清楚 pi 到底是个什么工具

pi 这类 AI 编程智能体，本质上是一个能理解代码上下文、能帮你写代码、改代码、解释代码的对话式工具。你跟它说“帮我把这个函数改成异步的”，它会在你的项目目录下读文件、分析逻辑、生成改动方案，然后在你的确认下修改文件。这个能力放在 VS Code 扩展里用起来确实流畅，因为你一抬头就能看到被改动的文件长什么样，红色绿色 diff 一目了然。

但这里有个常被忽略的事实：pi 的核心逻辑并不依赖 VS Code。它真正干活的核心是一个命令行程序，加上一层用于对话聊天的交互界面。VS Code 扩展只是把这个命令行工具包了一层 IDE 皮肤。也就是说，你完全可以绕过 VS Code，用终端直接跟它对话，前提是你愿意自己搭一个舒服的“聊天窗口”。终端加启动脚本，就是成本最低的方案。

我这次折腾的起因很简单：有阵子我每天都要跟 pi 聊代码，但很多对话根本不需要打开整个项目，不需要看文件树，不需要调试器。我就想让它生成一段正则、解释一个报错、写个几十行的数据清洗脚本。为了这点事去启动一个完整的 IDE，属实杀鸡用牛刀。于是花了不到一个下午，给 pi 配了一个 Windows 桌面端，同一个聊天界面，但全程不用装 VS Code。

1.2 不装 VS Code 的三个真实理由

先说资源占用。VS Code 完整跑起来，渲染进程、扩展宿主、代码索引加起来轻松吃掉 800MB 以上内存。我这台开发机是 16GB 内存，平时开着浏览器、数据库、容器这些就已经很紧张了，为了一个聊天窗口长期挂着一个 IDE，太奢侈。而终端里跑 pi，整个会话进程的内存占用通常在 100MB 上下，差距不是一个量级。

再说启动速度。VS Code 冷启动大概要 3 到 5 秒，扩展装多了能到 8 秒。终端方案呢？从双击快捷方式到 pi 的聊天界面进入可输入状态，实测 1 到 2 秒。这个时间差看起来不大，但真实体感差别很明显。尤其是当你只是临时冒出一个问题想顺手问一下的时候，等 IDE 打开的那几秒足够打消一半的提问欲望。

第三个理由可能更主观，但我认为是长期用得最舒服的原因：专注度。VS Code 一开，文件树、Git 面板、终端、调试控制台，各种信息都在“勾引”你顺手改点东西。我本来只是想让 pi 解释一段报错，最后莫名其妙开了一堆文件，思绪也被带跑了。终端里只有一个对话界面，没有多余的信息流，反而不容易走神。

1.3 什么情况下我仍然会老老实实打开 VS Code

桌面端方案不是万能的，它替代的是“轻量对话”和“临时脚本”这两个场景。如果是正经开发一个项目，需要频繁查看改动后的文件内容、需要断点调试、需要配合其他扩展一起工作，那 VS Code 扩展仍然是最优选择。我自己用的分配方式很简单，给大家参考：

这么一拆，其实大部分日常对话需求都落到了“终端桌面壳”这一边，真正需要完整 IDE 的场景反而没那么多。这也解释了为什么我值得花时间折腾这套东西。

2. 桌面端方案选型：CLI 才是核心

2.1 先搞明白 pi 的运行机制，才知道该动哪里

在动手之前，我先把 pi 的结构理了一遍。一个典型的 AI 编程智能体，不管它叫什么名字，架构上基本都是三层：交互层、执行层、模型接口层。交互层负责把用户输入接进来，可能是 IDE 的侧边栏聊天框，也可能是终端里的对话界面；执行层负责调起命令、读写文件、执行测试；模型接口层就是跟大模型 API 打交道的那部分。

pi 放到 VS Code 里跑的时候，VS Code 扩展只是充当了交互层，干活的还是底下的命令行程序。所以我只需要搞清楚两件事：第一，pi 有没有独立于 VS Code 的 CLI 入口；第二，它在终端里的对话体验跟扩展里差多少。答案都是肯定的。

pi 的 CLI 入口用起来很直接，安装完成后在终端里敲对应的命令就会进入一个交互式聊天界面。这个界面和 VS Code 扩展里的聊天面板基本是同一套逻辑，能打字、能多轮对话、能看到它的执行过程。区别只是它没有展示在编辑器侧边栏，而是占据整个终端窗口。对多数对话场景来说，这个差异完全不影响使用。

2.2 终端选哪个：Windows Terminal 是我的答案

既然决定走终端路线，下一步就是选终端模拟器。Windows 上可选的有这么几类：系统自带的 conhost、Windows Terminal、Cmder、Alacritty 这类第三方终端。我直接说结论：Windows Terminal 是最省事且体验最好的选择。

Windows Terminal 的好处是配置是 JSON 文件，意味着你可以给 pi 单独建一个 profile，指定启动目录、字体、配色、图标，甚至启动时自动执行一段命令。这套配置可以跟着你的 dotfiles 走，换机器也方便迁移。

另外提醒一句，Windows Terminal 一定要从微软商店或者官方 GitHub Releases 下载，别去第三方下载站，否则很可能装到带捆绑软件的版本。装完在开始菜单能看到 Windows Terminal 就算成功。

2.3 为什么不走 WSL，也不直接用 Web 版

有些人可能想问：Windows 上跑命令行工具不是有 WSL 吗？为什么不直接装在 WSL 里？这里我踩过坑，说点实在的。WSL 里跑 pi 确实能用，但有两个绕不开的麻烦。第一是文件系统跨界问题，你的项目代码在 D 盘，WSL 里访问 /mnt/d 虽然能读，但 IO 性能明显下降，pi 这种要频繁读文件、遍历目录的工具，体感会变卡。第二是路径表示问题，pi 返回的文件路径可能是 /mnt/d/code/xxx，你复制出来在 Windows 环境用还得转换，很烦。

Web 版我也看了。如果你对数据安全不太在意、只是偶尔用一下，那 Web 版其实也可以。但问题在于它通常没法读取你本地的项目文件，也就没法完成“帮我改一下当前目录下那个 config 文件”这种最常见的任务。所以对本地开发场景来说，CLI 是唯一能完整发挥 pi 能力的路径。

3. 实操：给 pi 配一个 Windows 桌面“壳子”

3.1 Step 1：装好 Node.js 运行时

pi 这类 CLI 工具绝大多数是用 Node.js 写的，所以第一步是确保机器上有 Node 运行时。如果之前装过，直接在 PowerShell 里验证一下版本：

node -v npm -v

如果提示“不是内部或外部命令”，说明 Node 还没装或者没进 PATH。去 Node.js 官网下载 LTS 版本的安装包，一路下一步就行。这里有一点要重点提醒：一定选 LTS（长期支持版），不要追最新版。很多 CLI 工具对 Node 的最新大版本兼容还没跟上，装个奇数版本或者刚发布的版本，后面跑 pi 很可能报各种奇怪的错。

安装完成后重新开一个 PowerShell 窗口，让 PATH 环境变量生效。看到 node 和 npm 都能正常输出版本号，这一步就算过了。

3.2 Step 2：安装 pi CLI 本体

Node 就绪后，安装 pi CLI 就一条命令的事。通常官方 GitHub 仓库的 README 会给出全局安装命令，一般长这样：

npm install -g @pi/cli

具体包名以你看到的官方文档为准，这里我强调的不是命令本身，而是两个容易踩的坑。

第一个坑是全局安装路径权限。如果你的 Node 是默认安装的，npm 全局包会装到用户目录下，一般不涉及权限问题。但如果你之前手动改过 npm prefix 或者用了 nvm-windows，全局安装路径可能在系统盘某个受保护目录，安装时会报 EACCES 错误。解决办法是重新设置 npm 的全局目录：

npm config set prefix "$env:APPDATA\npm"

设置完再装一次。

第二个坑是安装后命令找不到。npm 全局安装完成后，会提示装到了哪个目录，但那个目录不一定在你的 PATH 里。常见表现是安装过程没报错，结果敲 pi 命令显示“不是内部或外部命令”。这时去检查用户环境变量 PATH 里有没有 npm 全局目录，Windows 下通常是 C:\Users\你的用户名\AppData\Roaming\npm，没有就手动加进去，然后重开终端。

装完验证一下：

pi --version

能输出版本号，说明 CLI 本体没问题了。

3.3 Step 3：配置模型 API Key

pi 只是一个壳，真正回答问题的是背后的大模型 API。所以还需要把 API Key 配置好。不同工具配置方式略有差异，但基本都在官方文档里有明确说明。最常见的两种方式：

方式一，环境变量。在 PowerShell 里输入：

setx PI_API_KEY "你的API Key"

setx 是永久写入用户环境变量，设置完重开终端生效。方式二，配置文件。很多工具支持在用户目录下放一个配置文件，比如 ~/.pi/config.json，里面写模型、API Key、默认参数。我建议用配置文件，因为它可以把多个参数一次性写好，而且方便备份。

这里多说一句 API Key 的管理心得：不要把 Key 写死在启动脚本里，也别随便提交到 Git 仓库。用环境变量或者配置文件的方式，既方便切换，也降低泄露风险。我自己是把配置文件放在用户目录下，并且用文件系统权限做了限制。

3.4 Step 4：在 Windows Terminal 里建一个专属 Profile

Windows Terminal 装好后，它的配置是个 JSON 文件。在终端里按 Ctrl + , 可以直接打开 settings.json，在里面为 pi 单独建一个 profile，这样每次启动就是干净的对话环境。思路是加一个独立的 profile，指定启动参数和图标：

{ "profiles": { "list": [ { "name": "pi chat", "commandline": "powershell.exe -ExecutionPolicy Bypass -File C:\\scripts\\pi-chat.ps1", "icon": "C:\\icons\\pi.ico", "startingDirectory": "D:\\code", "font": { "face": "Cascadia Code", "size": 11 }, "colorScheme": "Campbell" } ] } }

其中 commandline 指向一个启动脚本，startingDirectory 可以指定默认目录，这样一打开就是在你想让 pi 工作的项目目录里。字体我用的 Cascadia Code，是微软家出的，对编程字符和中文支持都不错。你也可以用 JetBrains Mono 或者更极客的 Maple Mono，这个纯看个人偏好。

3.5 Step 5：写启动脚本，双击即用

这个 profile 里的 pi-chat.ps1 脚本是整套方案的核心。它做的事情很简单：先设置一些环境变量，然后进入目标目录，最后启动 pi 聊天。一个示例脚本长这样：

# C:\scripts\pi-chat.ps1 # pi chat desktop launcher # 设置模型接入配置 if (Test-Path "$env:USERPROFILE\.pi\config.json") { Write-Host "Found pi config, loading..." } # 进入常用项目目录 Set-Location "D:\code" # 启动交互式聊天 pi chat

写好脚本后，建议先手动执行一遍确认没问题，再把快捷方式发送到桌面。为了让这个桌面端更“像”一个应用，可以找个图标文件放到固定目录，然后在快捷方式的属性里改图标。如果你用一个简单的 PowerShell 脚本壳，Windows 默认图标是个黑色窗口，换一个带颜色的图标会好区分很多。

最后一步，把快捷方式固定到任务栏或者开始菜单。右键快捷方式选择“固定到任务栏”就行。以后点击就是秒开状态，直接进入 pi 的聊天界面。

3.6 Step 6：让窗口变成“伪应用”的小技巧

Windows Terminal 有一个在专注模式挺好用的功能：默认配置文件里把 window 的样式改成无边框，或者保存一份单独的布局。如果你的场景是长时间挂在桌面上，可以把 Terminal 的设置里“始终在顶部”打开，把透明度调高一点，放在屏幕角落，看起来就像一个小号桌面助手。当然这属于锦上添花的操作，不折腾也完全不影响使用。

还有一种玩法是配置快捷键。Windows Terminal 默认支持 Ctrl + T 新开标签、Ctrl + W 关闭标签，你可以给 pi 的 profile 绑定一个前缀键，比如 Alt + P 直接切到 pi 标签。这样跟 IDE 里的聊天面板比，手势习惯也不会差太多。

4. 日常使用与配置细节

4.1 会话管理：多开、恢复、历史记录

用终端跑 pi 跟用 VS Code 扩展最大的体验差异在会话管理。扩展里你可以在一个项目里开多个聊天窗口，终端里则是靠多标签页模拟。Windows Terminal 支持一个窗口多个标签页，每个标签页可以跑一个独立的 pi 会话。比如你同时在维护两个项目，开两个标签页，各自 cd 到各自目录，再分别启动 pi，互不干扰。

关于会话恢复，要看 pi 本身有没有提供 chat history 之类的命令。如果支持，尽量每次结束会话前主动保存；如果不支持，也可以用终端自身的滚动缓冲区配合日志输出做简单记录。我自己会定期把重要的对话过程用 tee 命令落一份日志，方便事后回头翻。

pi chat 2>&1 | Tee-Object -FilePath "D:\logs\pi-session.log"

4.2 目录策略：先 cd 再干活，别让 pi 瞎找上下文

pi 这类工具的文件操作能力通常基于当前工作目录。你启动 pi 的目录决定了它能“看到”和修改哪些文件。所以一个好习惯是：启动前先明确告诉自己这次对话的关注范围。只聊一个小脚本，就在临时目录里启动；要处理某个项目，就 cd 到项目根目录再启动。

千万不要在 C:\Users\你的用户名 这种根目录启动 pi 然后让它改文件，它可能会在大量文件里找上下文，既慢又容易误操作。我在脚本里已经把默认 startingDirectory 指到了 D:\code，但如果临时要处理别的目录，我会先 Ctrl + D 退出当前会话，再重新启动，而不是试图在会话中途切目录——切了会让 pi 的路径上下文变得混乱，很多奇怪的“找不到文件”问题就是这么来的。

4.3 让它干活的几个实用技巧

这里分享几个我在实际使用中摸索出来的小技巧，比官方示例更带实战味：

第一，任务描述要带目录锚点。比如“把当前目录下 src/utils/date.js 文件里的 formatDate 函数改成支持时区参数”，比“帮我把日期函数改一下”效率高得多，pi 不用猜，直接定位。

第二，小步提交，别让它一口气干太大的活。有一次我让它“重构整个模块”，它改了十几个文件，结果一半逻辑不是我想要的，回滚都费劲。后来改成一次只让它改一个函数或一个文件，改完我看一遍再让它改下一个，效果好很多。这个习惯在终端里尤其重要，因为终端里看 diff 没有 IDE 里直观。

第三，让它先解释再动手。遇到不熟悉的工具或者逻辑，先问“解释一下这段代码是干什么的，再说说如果我要改成 X，你会怎么改”，让它先给方案，你确认了再让它执行。终端里没有撤销按钮那么显眼，谨慎一点不亏。

4.4 字体、配色与提示词微调

使用体验的最后一公里是视觉。Windows Terminal 的配色方案可以在 settings.json 里自定义，也可以从 Windows Terminal Themes 这类社区仓库直接抄一份。我的建议是选一种对比度适中、长时间看不累的暗色主题，然后把光标样式改成实心块，这样在对话界面里定位比较清晰。

如果你在 GitHub 上看到过 oh-my-pi 这类社区配置管理项目，它做的事情跟 oh-my-zsh 之于 zsh 类似，把 prompt 主题、常用指令别名统一管理起来。我实际体验下来，配置管理类的增强工具用好了确实能提升操作一致性，但前提是你已经熟悉了原生用法。建议初期先别装，等用熟了再折腾这些锦上添花的东西。

5. 常见问题与排查实录

5.1 “pi 不是内部或外部命令”

这个报错出现频率最高，本质就是 PATH 里没找到可执行文件。按优先级排查：第一，npm 全局安装目录是否在 PATH 里，检查用户变量 PATH 是否有 C:\Users\你的用户名\AppData\Roaming\npm；第二，如果用了 nvm-windows，确认当前激活的 Node 版本里确实装了 pi，不同 Node 版本之间全局包是不共享的；第三，重开终端再试，环境变量修改后必须新开窗口才生效。

5.2 中文乱码和编码问题

Windows 终端跑 Node CLI 出现中文乱码，十有八九是代码页问题。Windows 默认的 GBK 代码页跟 UTF-8 工具链不对付。解决方式是在启动脚本最前面加一行：

chcp 65001 > $null

把代码页切到 UTF-8。如果你用的是 Windows Terminal，还可以设置 profile 的“命令行”为 powershell.exe 并勾选“使用旧版控制台”的相反选项。另外，确保你的终端字体支持中文，Cascadia Code 和大部分等宽字体都支持，但如果用了一些偏门字体，中文可能显示成方块。

5.3 连不上模型服务

pi 聊天时提示连接失败或者超时，第一步先确认是不是网络环境的问题。如果在公司内网或者有特殊网络策略的环境里，API 域名可能被拦截。这个没法一概而论，但按经验先做两步：第一，用命令测试目标 API 域名是否可访问；第二，检查是否有系统级流量过滤软件影响。不要一上来就怀疑 pi 本体坏了，先排除网络层。

然后是配置问题。确认环境变量或配置文件里的 API Key 没写错，Key 不要带多余的空格和引号。我以前犯过低级错误：复制 Key 时多复制了一个换行符，结果服务端一直报鉴权失败，排查了半天才发现在配置文件末尾有个看不见的换行。

5.4 换机器后配置丢失

桌面端方案的配置文件分散在两处：一个是 pi 自己的用户配置目录（通常在 C:\Users\用户名.pi 下），另一个是 Windows Terminal 的 settings.json。换机器的时候，把这两处备份一下就能无缝迁移。我自己的操作是把 .pi 目录整体打包放进云盘，Windows Terminal 的 settings.json 用 Git 管理，定期提交。这样不管换哪台机器，十分钟内就能恢复完整环境。

5.5 常见问题速查表

写在最后

这套方案我实际用了三个多月，整体感受是“回不去了”。VS Code 扩展我仍然会在正经开发时打开，但日常跟 pi 的对话，超过八成已经改在终端里完成。它省下的不只是几百 MB 内存和几秒启动时间，更重要的是那种“打开一个对话窗口”的低门槛感——不用先想清楚要不要开 IDE，想到就问，问完就走，整个交互的负担小了很多。

最后分享一个小技巧，也是在踩过几次坑之后总结出来的：给 pi 配上桌面壳之后，一定要把“记住上次会话目录”这件事做进启动脚本里。做法很简单，在 pi-chat.ps1 里加一行，把上次退出时的路径写到一个小文件里，下次启动自动读取。这样每次打开它都会回到你上次干活的地方，比每次手动 cd 顺畅得多。这个细节看着不起眼，但长期用下来，能省掉大量“我在哪、要去哪”的重复操作。