← Pi Agents

Shell、进程与环境变量

Pi 每条 shell 命令都会用一个全新的非交互式 shell 来运行,所以别名和 shell rc 文件都不在场,除非你配置 shellPath 和 shellCommandPrefix。

你让 Pi 跑 ll,它报告 ll: command not found。你在自己的终端里按上箭头,ll 就能用。没有东西坏掉。Pi 启动的是另一个 shell。

shell-aliases.md 在第一行就说出了原因:Pi 为每条 Bash 命令启动一个单独的非交互式 shell 进程。非交互式 Bash 默认不展开别名,通常也不加载与交互式终端相同的启动文件。

哪个 shell 跑什么

    flowchart TD
  YOU["你的交互式终端"] -->|"别名、rc 文件、你的 PATH"| YSH["你的 shell"]
  PI["从某处启动的 pi"] --> SP["shellPath 设置<br/>默认:解析出的 bash"]
  SP --> FRESH["一个全新的非交互式 shell<br/>每条命令一个"]
  FRESH --> NOALIAS["别名不展开<br/>rc 文件不读取"]
  FRESH --> BANG["你的 !command 和 !!command<br/>也在这里运行"]
  EXT["提供一个 shell 工具的扩展"] -.->|"绕过 shellCommandPrefix"| OWN["它自己的实现"]
  

上方那个方框与下方之间的这道落差,就是本章的全部内容。你的 shell 是交互式的,而且是你的;Pi 的既不是交互式的也不是你的,而且它是每条命令一个全新的。

命令来源 Shell
模型调用内置的 bash 工具 Pi 解析出的 Bash 可执行文件
你输入 !command 或 !!command 同一个解析出的 Bash 可执行文件
模型调用可选的 powershell 工具 PowerShell 7(pwsh.exe)或 Windows PowerShell
一个扩展提供或替换 shell 工具 那个扩展所实现的操作

最后一行是最容易绊住人的那一行。如果一个扩展替换了 bash 工具,shellCommandPrefix 就不再配置它——shell-aliases.md 在它的故障排查小节里直接这么说了。

解析顺序

Pi 通常用 bash -c 调用 Bash。在 Unix 上它先试 /bin/bash,然后是 PATH 上的 bash,再是 Bash 不可用时的 sh。在原生 Windows 上它先检查配置的路径,然后是 Git Bash,再是 PATH 上的 bash.exe。

最后一个后备就是 shopt 失败的原因。如果找不到 shopt,要么 Pi 回退到了 sh,要么 shellPath 指向一个非 Bash 的 shell。在使用 Bash 专有的设置之前,先安装 Bash,或者把 shellPath 指向一个 Bash。

指向一个真的 Bash

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

settings.md 把 shellPath 记录为默认取平台默认值,并支持开头的 ~。在 Windows 上,用正斜杠或转义反斜杠,因为 JSON 用反斜杠作转义序列。windows.md 用一条 Cygwin 路径展示了同一条规则。

改完这个设置后运行 /reload。

每条命令之前都会运行的设置

shellCommandPrefix 会被加在内置的 bash 工具和用户输入的 ! 与 !! 命令前面。Pi 用一个换行符把前缀和请求的命令拼接起来,并且每条命令都会重新运行一次前缀——所以让它保持快速,且不含交互式提示。

{
  "shellCommandPrefix": "export CI=1"
}

有两种有文档记载的失败模式源于"每次都运行"。如果一个设置命令等待输入,它会让每条命令都挂住;从前缀里移除交互式命令。而因为它不是交互式的,依赖终端的输出会行为异常。

让别名生效

把 Pi 需要的别名放在一个与 Bash 兼容的文件里,而不是去解析你的交互式 shell 配置:

# ~/.bash_aliases
alias ll='ls -la'
alias gs='git status --short'

然后启用展开并 source 这个文件:

{
  "shellCommandPrefix": "shopt -s expand_aliases\nsource ~/.bash_aliases"
}

那个 \n 是 JSON 字符串里一个真正的换行符,Pi 会把它和命令拼接起来。从 Pi 里面验证它:

!ll

输出应该与 ls -la 一致。

不要把 .zshrc source 进 Bash。shell-aliases.md 警告说,zsh 的选项、函数和插件在那里可能无法解析或行为不正确。如果 Pi 的模型必须运行一个只存在于你的交互式设置里的命令,诚实的修法是在 PATH 上放一个脚本,而不是在前缀里加一个转接脚本。

交给命令的会话环境

environment-variables.md 记录了五个会被注入到由 bash 和 powershell 工具运行的命令中的变量:

变量 说明
PI_SESSION_ID 当前会话 ID
PI_SESSION_FILE 当前会话 JSONL 文件的绝对路径;临时会话中未设置
PI_PROVIDER 当前选定的模型 provider
PI_MODEL 当前选定的模型 ID
PI_REASONING_LEVEL 当前生效的推理级别

这些值在每条命令启动时解析,所以切换模型或改变推理级别会影响下一条 shell 命令,无需重启 Pi。PI_PROVIDER 和 PI_MODEL 标识的是选定的 Pi 模型,不是路由器内部可能选择的另一个上游模型。

文档给模型的建议值得逐字抄进你自己的指令里:当被问到正在运行哪个模型或 provider 时,去检查这些变量,而不是从系统提示词里推断答案。

错误:“Pi 的命令在我的终端里跑,所以对我有用的对 Pi 也有用。”

正确:可执行文件是同一个解析出的 Bash,但环境不是。会话变量会被注入到可被 LLM 调用的 bash 和 powershell 工具中,而不会被注入到用户输入的 ! 或 !! 命令中,所以你手动跑的检查看到的环境,可能和模型跑同一个检查看到的环境不一样。

给子进程的进程标记

与会话变量分开,CLI 和 RPC 入口点会设置两个由子进程继承的标记:

  • AI_AGENT=pi——一个通用标记,让工具链能把 Pi 识别为发起它的那个智能体。
  • PI_CODING_AGENT=true——Pi 专有,面向需要检测自己是否运行在 Pi 内部的进程。

它们不针对特定会话,而且当 Pi 通过 SDK 被嵌入时不会自动设置。

Windows:两个 shell,有意为之

windows.md 直白地给出了这个选择。原生 Windows 默认使用 Git Bash,并可以选择把 PowerShell 暴露给模型。WSL 内部的 Pi 使用 Linux 环境和它的 Bash 安装。

要让模型使用 PowerShell,替换面向模型的 shell:

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

["-bash", "+powershell"] 做同样的事,同时保留你配置的其他默认工具。powershell 工具会用 -NoProfile -NonInteractive -ExecutionPolicy Bypass 启动 PowerShell,从 pwsh.exe 回退到 Windows PowerShell。管理员强制执行的执行策略仍然可能优先。

即使做了这个改动,你自己的 ! 和 !! 编辑器命令仍然使用 Bash,而 powershell 工具只在 Pi 作为原生 Windows 进程运行时才可用。

从 Pi 里面验证它

这个检查必须按模型将要运行它的方式来跑,即作为一次工具调用:

运行这个并原样把输出展示给我:
printf 'shell=%s\n' "$BASH_VERSION"; printf 'model=%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"

如果 $BASH_VERSION 回来是空的,说明 Pi 没有在运行 Bash,你配置的任何 Bash 专有设置都被忽略了。你自己用 ! 跑同一条命令,证明的东西比看起来少:那检查的是你自己的环境,不是工具的环境。

环境现在可预测了,这是一次运行中你完全能控制的那部分的先决条件。Pi 不会回头来问"完成"是什么意思,所以那必须在请求送进去之前就定下来。

运行了什么

examples/ch09-shell/ 在一次会话中驱动真实的 bash 工具和真实的 ! 路径,配一个请求命令的脚本化模型:

  • 五个会话变量会被注入到模型的 bash 工具中:PI_SESSION_ID 是会话的 id,PI_PROVIDER 是选定的 provider,PI_SESSION_FILE 是 JSONL 路径;
  • PI_SESSION_FILE 在临时会话中是空的,脚本就是这样判断的;
  • 这些值在每条命令启动时解析:setThinkingLevel("high") 之后,下一条命令打印出 level=high,没有重启;
  • 会话变量不会被注入到用户输入的 ! 命令中,而模型的命令看到了它们。手动跑的检查看到的环境,与模型的检查看到的环境不同;
  • shellCommandPrefix 在模型的命令和 ! 命令之前都运行了;
  • 别名在非交互式 shell 中不存在,而一旦前缀运行 shopt -s expand_aliases 并定义它,它就生效;
  • 一个非零退出码会作为一个模型能读懂的结果返回,里面带着退出码。

这些是在 Windows 上的 Git Bash 下运行的,所以 shell 就是 Pi 在那里解析出的任何一个。在另一个平台上,shell 和别名的结果可能不同。