Pi Agent 终端 Shell 别名启用指南通过 shellCommandPrefix 让 bash 别名在 Pi 中生效【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本指南针对 Piminimal terminal coding harness中「终端别名shell aliases默认不生效」这一高频问题给出根因分析与完整解决方案通过全局设置文件~/.pi/agent/settings.json中的shellCommandPrefix字段为每一条由 Pi 发起的 bash 命令注入expand_aliases与别名加载逻辑。读完本文你将掌握 JSON 转义规则、多 shell 配置zsh/bash/Windows Git Bash的适配方法以及该前缀机制与 Pi 项目信任、!命令、bash 工具等功能的实际交互边界。为什么别名在 Pi 里默认不生效Pi 执行 shell 命令时使用的是非交互式 bash即通过bash -c方式调用。Bash 在非交互模式下默认不会展开别名alias expansion这是 shell 的标准行为与终端里手敲命令交互式 shell 自动读取并展开.bashrc/.zshrc中的别名完全不同。因此即使你在.zshrc或.bashrc中定义了大量别名直接让 Pi 运行alias定义的快捷命令时也会得到 command not found。该结论来源于 shell-aliases.md 的开篇描述也是本文要解决的核心问题。解决方案设置 shellCommandPrefix要让别名生效需要在全局设置文件~/.pi/agent/settings.json中添加shellCommandPrefix字段{ shellCommandPrefix: shopt -s expand_aliases\neval \$(grep ^alias ~/.zshrc)\ }该前缀会被拼接prepend到 Pi 运行的每一条 bash 命令之前。也就是说每条命令实际执行时都会先完成两件事shopt -s expand_aliases开启非交互模式下的别名展开开关shopt 是 bash 内置选项expand_aliases正是控制非交互 shell 是否展开别名的选项eval $(grep ^alias ~/.zshrc)从你的 zsh 配置文件中过滤出所有alias开头的行并执行从而在当前命令上下文中注册这些别名。之后 Pi 运行形如mypy、gs之类的别名命令时bash 就能正确展开它们。JSON 字符串转义详解shellCommandPrefix的取值是一个 JSON 字符串文档明确指出了两处关键转义参见 shell-aliases.md\n是转义后的换行符用于将多条命令分隔为多行等同于 shell 中多行命令依次执行前缀内部的双引号必须使用\反斜杠转义否则 JSON 解析会提前终止字符串。同理~/.zshrc路径中的~由 bash 负责展开不需要在 JSON 中特殊处理。按你的 shell 配置调整路径示例中默认读取~/.zshrc。请根据你实际使用的登录 shell 与配置文件位置进行替换你的 shell建议的 grep 目标zsh~/.zshrcbash~/.bashrcmacOS 上的 bash登录 shell 读取逻辑不同~/.bash_profile自定义路径指向实际存在的别名定义文件例如 bash 用户可配置为{ shellCommandPrefix: shopt -s expand_aliases\neval \$(grep ^alias ~/.bashrc)\ }注意grep ^alias 只匹配行首为alias的定义行这是有意为之的过滤策略——避免执行配置文件中可能存在的函数定义、环境变量赋值等与别名无关的内容降低副作用。前缀与 Pi 各功能的实际交互边界作用于每一条 bash 命令shellCommandPrefix是 Pi 设置体系 settings.md 中Shell分组下的一个字段与shellPath、npmCommand并列。它会对 Pi 发起的所有bash 命令统一生效包括模型LLM通过内置bash工具执行的命令交互界面中用户输入的!command执行并把输出发送给模型与!!command执行但不把输出发送给模型见 usage.md 的编辑器功能说明。因此设置一次即可让别名在模型工具调用和手动 shell 注入两种场景下保持一致的行为。与 shellPathWindows 场景配合shellCommandPrefix由 bash 解释执行因此前提是 Pi 确实在使用 bash。在 Windows 上Pi 要求一个 bash 环境其查找顺序是~/.pi/agent/settings.json中的自定义shellPath→ Git BashC:\Program Files\Git\bin\bash.exe→ PATH 中的bash.exeCygwin/MSYS2/WSL详见 windows.md。Windows 用户若使用 Git Bash 作为 shell可将别名加载目标指向 Git Bash 的配置文件{ shellPath: C:\\Program Files\\Git\\bin\\bash.exe, shellCommandPrefix: shopt -s expand_aliases\neval \$(grep ^alias ~/.bashrc)\ }注意 JSON 中 Windows 路径的反斜杠需写成双反斜杠\\且shellPath支持前导~见 settings.md。全局设置 vs 项目设置shellCommandPrefix建议放在全局设置~/.pi/agent/settings.json中因为它是与个人 shell 环境强相关的偏好。Pi 的设置机制是项目设置.pi/settings.json覆盖全局设置嵌套对象逐键合并全局文件中的资源路径相对~/.pi/agent解析项目文件中的资源路径相对.pi解析见 settings.md。如果你希望某个项目强制使用不同的前缀行为也可以在项目级.pi/settings.json中覆盖该字段。安全与注意边界设置shellCommandPrefix意味着 Pi 的每条 bash 命令都会额外执行你 shell 配置中定义的别名行这属于「以当前用户权限执行代码」的范畴。结合 security.md 的原则有几点值得注意Pi 是本地 agent没有内置沙箱bash 命令以 Pi 进程的权限运行别名本身也是可执行代码请确保你的别名定义来源可信项目信任project trust只控制是否加载项目本地设置与资源不是安全边界若在.pi/settings.json中配置了前缀也请遵循对未受信仓库的常规处理隔离运行、只读挂载等不要在设置文件中写入密钥或敏感命令密钥应通过环境变量、~/.pi/agent/auth.json或 OAuth 管理参见 security.md 与 environment-variables.md。此外别名展开仅作用于命令层面不会改变 Pi 注入 bash 工具的环境变量如PI_SESSION_ID、PI_MODEL等见 environment-variables.md两者互不干扰。验证是否生效完成配置后重启 Pi或用/reload重新加载资源然后任选一种方式验证在 Pi 中直接输入一个已定义的别名命令如!gs观察是否按预期展开用pi -p 运行你的别名命令并告诉我输出让模型调用 bash 工具执行检查返回结果若仍失败请按顺序排查JSON 转义是否正确重点检查\n与\、grep 目标文件路径是否真实存在、目标文件中别名是否以alias开头、以及当前是否使用了非 bash 的 shell。若同时需要排查终端键盘或 TUI 相关问题例如ShiftEnter多行输入在特定终端不生效可参考 Pi 的终端设置文档 terminal-setup.md而有关 bash 工具自身环境变量、进程标记AI_AGENTpi、PI_CODING_AGENTtrue的更多细节可查阅 environment-variables.md。本项目中的完整 Pi 技能入口与文档地图见 SKILL.md。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pi Agent 终端 Shell 别名启用指南：通过 shellCommandPrefix 让 bash 别名在 Pi 中生效
Pi Agent 终端 Shell 别名启用指南通过 shellCommandPrefix 让 bash 别名在 Pi 中生效【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本指南针对 Piminimal terminal coding harness中「终端别名shell aliases默认不生效」这一高频问题给出根因分析与完整解决方案通过全局设置文件~/.pi/agent/settings.json中的shellCommandPrefix字段为每一条由 Pi 发起的 bash 命令注入expand_aliases与别名加载逻辑。读完本文你将掌握 JSON 转义规则、多 shell 配置zsh/bash/Windows Git Bash的适配方法以及该前缀机制与 Pi 项目信任、!命令、bash 工具等功能的实际交互边界。为什么别名在 Pi 里默认不生效Pi 执行 shell 命令时使用的是非交互式 bash即通过bash -c方式调用。Bash 在非交互模式下默认不会展开别名alias expansion这是 shell 的标准行为与终端里手敲命令交互式 shell 自动读取并展开.bashrc/.zshrc中的别名完全不同。因此即使你在.zshrc或.bashrc中定义了大量别名直接让 Pi 运行alias定义的快捷命令时也会得到 command not found。该结论来源于 shell-aliases.md 的开篇描述也是本文要解决的核心问题。解决方案设置 shellCommandPrefix要让别名生效需要在全局设置文件~/.pi/agent/settings.json中添加shellCommandPrefix字段{ shellCommandPrefix: shopt -s expand_aliases\neval \$(grep ^alias ~/.zshrc)\ }该前缀会被拼接prepend到 Pi 运行的每一条 bash 命令之前。也就是说每条命令实际执行时都会先完成两件事shopt -s expand_aliases开启非交互模式下的别名展开开关shopt 是 bash 内置选项expand_aliases正是控制非交互 shell 是否展开别名的选项eval $(grep ^alias ~/.zshrc)从你的 zsh 配置文件中过滤出所有alias开头的行并执行从而在当前命令上下文中注册这些别名。之后 Pi 运行形如mypy、gs之类的别名命令时bash 就能正确展开它们。JSON 字符串转义详解shellCommandPrefix的取值是一个 JSON 字符串文档明确指出了两处关键转义参见 shell-aliases.md\n是转义后的换行符用于将多条命令分隔为多行等同于 shell 中多行命令依次执行前缀内部的双引号必须使用\反斜杠转义否则 JSON 解析会提前终止字符串。同理~/.zshrc路径中的~由 bash 负责展开不需要在 JSON 中特殊处理。按你的 shell 配置调整路径示例中默认读取~/.zshrc。请根据你实际使用的登录 shell 与配置文件位置进行替换你的 shell建议的 grep 目标zsh~/.zshrcbash~/.bashrcmacOS 上的 bash登录 shell 读取逻辑不同~/.bash_profile自定义路径指向实际存在的别名定义文件例如 bash 用户可配置为{ shellCommandPrefix: shopt -s expand_aliases\neval \$(grep ^alias ~/.bashrc)\ }注意grep ^alias 只匹配行首为alias的定义行这是有意为之的过滤策略——避免执行配置文件中可能存在的函数定义、环境变量赋值等与别名无关的内容降低副作用。前缀与 Pi 各功能的实际交互边界作用于每一条 bash 命令shellCommandPrefix是 Pi 设置体系 settings.md 中Shell分组下的一个字段与shellPath、npmCommand并列。它会对 Pi 发起的所有bash 命令统一生效包括模型LLM通过内置bash工具执行的命令交互界面中用户输入的!command执行并把输出发送给模型与!!command执行但不把输出发送给模型见 usage.md 的编辑器功能说明。因此设置一次即可让别名在模型工具调用和手动 shell 注入两种场景下保持一致的行为。与 shellPathWindows 场景配合shellCommandPrefix由 bash 解释执行因此前提是 Pi 确实在使用 bash。在 Windows 上Pi 要求一个 bash 环境其查找顺序是~/.pi/agent/settings.json中的自定义shellPath→ Git BashC:\Program Files\Git\bin\bash.exe→ PATH 中的bash.exeCygwin/MSYS2/WSL详见 windows.md。Windows 用户若使用 Git Bash 作为 shell可将别名加载目标指向 Git Bash 的配置文件{ shellPath: C:\\Program Files\\Git\\bin\\bash.exe, shellCommandPrefix: shopt -s expand_aliases\neval \$(grep ^alias ~/.bashrc)\ }注意 JSON 中 Windows 路径的反斜杠需写成双反斜杠\\且shellPath支持前导~见 settings.md。全局设置 vs 项目设置shellCommandPrefix建议放在全局设置~/.pi/agent/settings.json中因为它是与个人 shell 环境强相关的偏好。Pi 的设置机制是项目设置.pi/settings.json覆盖全局设置嵌套对象逐键合并全局文件中的资源路径相对~/.pi/agent解析项目文件中的资源路径相对.pi解析见 settings.md。如果你希望某个项目强制使用不同的前缀行为也可以在项目级.pi/settings.json中覆盖该字段。安全与注意边界设置shellCommandPrefix意味着 Pi 的每条 bash 命令都会额外执行你 shell 配置中定义的别名行这属于「以当前用户权限执行代码」的范畴。结合 security.md 的原则有几点值得注意Pi 是本地 agent没有内置沙箱bash 命令以 Pi 进程的权限运行别名本身也是可执行代码请确保你的别名定义来源可信项目信任project trust只控制是否加载项目本地设置与资源不是安全边界若在.pi/settings.json中配置了前缀也请遵循对未受信仓库的常规处理隔离运行、只读挂载等不要在设置文件中写入密钥或敏感命令密钥应通过环境变量、~/.pi/agent/auth.json或 OAuth 管理参见 security.md 与 environment-variables.md。此外别名展开仅作用于命令层面不会改变 Pi 注入 bash 工具的环境变量如PI_SESSION_ID、PI_MODEL等见 environment-variables.md两者互不干扰。验证是否生效完成配置后重启 Pi或用/reload重新加载资源然后任选一种方式验证在 Pi 中直接输入一个已定义的别名命令如!gs观察是否按预期展开用pi -p 运行你的别名命令并告诉我输出让模型调用 bash 工具执行检查返回结果若仍失败请按顺序排查JSON 转义是否正确重点检查\n与\、grep 目标文件路径是否真实存在、目标文件中别名是否以alias开头、以及当前是否使用了非 bash 的 shell。若同时需要排查终端键盘或 TUI 相关问题例如ShiftEnter多行输入在特定终端不生效可参考 Pi 的终端设置文档 terminal-setup.md而有关 bash 工具自身环境变量、进程标记AI_AGENTpi、PI_CODING_AGENTtrue的更多细节可查阅 environment-variables.md。本项目中的完整 Pi 技能入口与文档地图见 SKILL.md。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考