Windows 原生环境调教 Pi Coding Agent 的踩坑与优化指南
在 Windows 环境下运行 Pi Coding Agent 一段时间了，目前的配置运行得相当稳定，基本没遇到什么大毛病，所以特地来分享一下我的经验。
需要说明的是，这篇分享并不涉及具体的插件开发或 Pi 的核心内部机制，而是专注于如何通过优化系统配置，让 Pi 在 Windows 原生环境下更好用。如果你将 Pi 直接安装在 Windows 而不是 WSL2 中，我强烈推荐采用这种配置，它能帮你避开传统 bash 工具带来的一系列“水土不服”问题。
首先，请确认你的电脑已安装以下软件/工具：
- ripgrep (
rg) - pi-coding-agent
- PowerShell 7 (
pwsh) - Windows Terminal
以下所有配置都是围绕这几个基础工具进行的。
替换 bash 工具
为什么不推荐在 Windows 上使用默认或第三方的 bash 工具？
- 路径转换问题：WSL 或类似 bash 工具接受的路径是
/mnt/c这种格式，而大模型在执行 read、write 或读取 system prompt 时，默认使用的是C:/格式，这导致 bash 工具在调用时极易出现路径识别错误。 - 兼容性差异：许多在 Linux 上运行良好的 bash 命令，放在 Windows 环境下会出现兼容性问题，甚至完全不可用。
事实上，现在的模型（像 GPT-5.6 或 DeepSeek 4 Flash）已经能非常熟练地编写 PowerShell 脚本了。在这种前提下，我们可以修改配置文件 %USERPROFILE%/.pi/agent/settings.json，让模型直接去运行 PowerShell 命令而不是 bash 命令：
{
"shellPath": "C:/Program Files/PowerShell/7/pwsh.exe",
"externalEditor": "code --wait",
"showHardwareCursor": true
}
配置项说明：
externalEditor：配置为 VS Code 后，可以通过Ctrl + G唤起编辑器，方便辅助编写较长的提示词。showHardwareCursor：开启此项是为了修复中文输入法在终端里可能出现的候选窗位置显示不正确的问题。
统一编码为 UTF-8
Windows 环境下最折磨人的莫过于祖传的编码问题。如果不做处理，命令行输出极易出现中文乱码。既然前面我们已经将 pwsh 设置为默认的 Shell 环境，现在还需要强制将其编码修改为 UTF-8。
强烈推荐遇到乱码问题时加上这段配置。根据实测，在 Win10 上如果不做修改会导致输出乱码，而在 Win11 上即便不修改有时也能正常显示，暂不清楚具体的原因。
打开 PowerShell 7，运行 code $PROFILE.CurrentUserCurrentHost，在打开的配置文件中注入以下强制编码逻辑：
$utf8 = [System.Text.UTF8Encoding]::new($false)
[Console]::InputEncoding = $ utf8
[Console]::OutputEncoding = $utf8
$global:OutputEncoding =$utf8
if ($IsWindows) { chcp.com 65001 >$null }
配置全局 Prompt
把底层 Shell 换成 PowerShell 后，你必须明确告诉大模型当前处于 PowerShell 环境，否则默认情况下它依然会凭借惯性输出 bash 命令。
我们可以在全局的 Prompt 中添加对应的提示词来约束其行为规范。打开或创建 %USERPROFILE%/.pi/agent/AGENTS.md 文件，添加以下内容：
- 当前环境是 PowerShell 7，必须使用 PowerShell 语法。
- 在进行搜索文件内容或文件名等操作时，优先用 `rg`。
强烈推荐加上类似“优先使用 rg”的提示。虽然现在的模型基本都知道 ripgrep，但默认情况下它往往还是会先尝试较慢的 find 或 grep。在全局直接定死规矩，能显著加快模型检索代码的速度。
Windows Terminal 快捷键
如果你在 Windows Terminal 中使用 Pi，会发现默认情况下有两个核心快捷键（Shift+Enter 和 Alt+Enter）存在冲突或无法被识别，需要额外修改配置才能让 Pi 正常接收键盘指令。
在 Windows Terminal 中按 Ctrl+Shift+, 打开 Windows Terminal 的 JSON 设置文件，在 actions 数组中硬塞入以下两段配置：
{
"command": { "action": "sendInput", "input": "\u001b[13;2u" },
"keys": "shift+enter"
},
{
"command": { "action": "sendInput", "input": "\u001b[13;3u" },
"keys": "alt+enter"
}
保存后，Shift+Enter 就能正常换行，Alt+Enter 即可进入 Follow-up 队列。