Pi Agent 多平台部署

Pi Agent 支持在 Windows、macOS、Linux 和 Android（Termux）上运行。本章介绍各平台的配置要点。

macOS 配置

macOS 是 Pi Agent 的一等支持平台，大部分功能开箱即用。

终端	安装方式	推荐理由
iTerm2	brew install --cask iterm2	原生 True Color 支持，图片显示效果好，功能丰富
Kitty	brew install --cask kitty	GPU 加速渲染，速度快
Warp	brew install --cask warp	现代化终端，AI 功能集成

验证 True Color 支持

$ echo $COLORTERM
truecolor

Shell 别名

在 ~/.zshrc 中添加常用别名：

实例

# Pi Agent 别名
alias pic='pi -c' # 继续上次会话
alias pir='pi -r' # 恢复历史会话
alias piq='pi -p' # 快速问答

Windows 配置

安装 Node.js

从 nodejs.org 下载安装包，或使用 winget：

> winget install OpenJS.NodeJS.LTS

安装 Pi Agent

在 Windows Terminal 的 PowerShell 或 CMD 中执行：

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

Windows 特有快捷键

功能	Windows 快捷键	macOS/Linux 快捷键
粘贴图片	Alt+V	Ctrl+V
多行输入	Ctrl+Enter	Shift+Enter
发送跟进消息	需重映射	Alt+Enter

在 Windows Terminal 中，Alt+Enter 默认是全屏快捷键。如果想让 Pi Agent 接收到这个快捷键，需要在 Windows Terminal 设置中移除或重映射全屏快捷键。在设置中搜索 "toggleFullscreen"，将其快捷键改为其他组合。

挂起行为

Windows 原生终端不支持 Unix 的作业控制。app.suspend（默认 Ctrl+Z）在 Windows 上没有默认绑定。如果手动配置了绑定，Pi Agent 会显示状态信息而不是真正挂起。

在 WSL 中运行时，Linux 的 Ctrl+Z/fg 行为正常可用。

Termux（Android）配置

Pi Agent 可以在 Android 设备上通过 Termux 运行。

安装步骤

实例

# 1. 安装 Termux（从 F-Droid 获取最新版）

# 2. 更新包并安装 Node.js
pkg update && pkg upgrade
pkg install nodejs

# 3. 安装 Pi Agent
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 4. 验证安装
pi --version

注意事项

Termux 的存储访问路径与常规 Linux 不同，使用 ~/storage/shared/ 访问共享存储
部分终端的图片显示功能可能受限
建议使用蓝牙键盘或 OTG 键盘以获得更好的编辑体验

tmux 集成

Pi Agent 可以在 tmux 会话中正常工作。

优势

会话持久化：即使 SSH 断开，Pi Agent 仍在后台运行
多窗口布局：一个窗口运行 Pi Agent，另一个窗口查看代码
远程开发：SSH 到服务器后使用 Pi Agent

实例

# 确保 True Color 支持
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",*:Tc"

# 增大回滚缓冲区（查看大量 AI 输出时有用）
set -g history-limit 50000

终端设置优化

设置项	建议值	说明
True Color	启用	确保终端支持 24 位色彩
字体	等宽字体（如 JetBrains Mono、Fira Code）	确保代码对齐和特殊字符显示
回滚缓冲区	至少 10000 行	查看大量 AI 输出和历史消息
VS Code 终端	设置 minimumContrastRatio 为 1	确保主题颜色准确渲染

VS Code 集成终端配置

在 VS Code 的 settings.json 中：

实例

{
"terminal.integrated.minimumContrastRatio": 1,
"terminal.integrated.fontFamily": "JetBrains Mono",
"terminal.integrated.fontSize": 13
}

Shell 别名建议

以下是一套完整的 Pi Agent 别名，可添加到 shell 配置文件中：

实例

# Pi Agent 常用别名
alias pi='pi' # 基础启动
alias pin='pi --name' # 命名会话启动
alias pic='pi -c' # 继续最近会话
alias pir='pi -r' # 恢复历史会话
alias piq='pi -p' # 快速一次性问答
alias pip='pi --print' # Print 模式（同 -p）
alias pif='pi --fork' # 分叉会话
alias pii='pi --no-session' # 临时模式（不保存）
alias piro='pi --tools read,grep,find,ls' # 只读模式
alias pirev='pi -p "审查暂存的代码变更（git diff --cached）"'

如果你使用 fish shell，将 alias 改为 abbr 或使用 fish 的 alias 语法。

返回顶部

菜鸟教程