Roo Code 在 macOS 上 ZSH 终端集成问题的解决方案

问题背景

Roo Code 是一款功能强大的 VSCode 扩展，它提供了智能代码补全和终端命令执行等功能。然而，许多 macOS 用户在使用 ZSH 作为默认 shell 时遇到了终端集成问题，表现为无法执行 shell 命令并出现"shell integration unavailable"错误提示。

问题表现

当用户尝试通过 Roo Code 执行简单的 shell 命令（如 echo "Hello, world!"）时，终端会显示以下错误信息：

Shell integration initialization sequence was not received within 5s. Shell integration has been disabled for this terminal instance.

根本原因

这个问题主要由以下几个因素导致：

1. ZSH 初始化时间过长，特别是在使用 Oh My Zsh 或 powerlevel10k 等复杂配置时
2. VSCode 终端环境变量继承设置不当
3. 缺少必要的 shell 集成脚本配置
4. PATH 环境变量中缺少 VSCode 二进制路径

解决方案

方法一：调整终端环境继承设置

在 VSCode 设置中搜索并修改以下选项：

• 将 terminal.integrated.inheritEnv 设置为 false

这个简单的调整已经帮助许多用户解决了问题。

方法二：手动配置 ZSH 集成

1. 在用户主目录创建或编辑 .zshrc 文件
2. 添加以下内容：

   [[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"
   

3. 确保 VSCode 的 code 命令在 PATH 中可用

方法三：调整终端集成超时设置

对于初始化较慢的 ZSH 配置，可以增加超时时间：

1. 在 Roo Code 设置中找到"Terminal Shell Integration Timeout"
2. 将值设置为 30 秒或更高

方法四：使用 ZDOTDIR 选项

在 Roo Code 设置中启用 ZDOTDIR 选项，这可以帮助解决终端集成问题，同时保持 ZSH 作为默认 shell。

高级解决方案

对于使用复杂 ZSH 配置（如 Oh My Zsh + powerlevel10k）的用户：

1. 在终端完全加载后手动执行 source ~/.zshrc
2. 或者使用 zsh 命令重新加载 shell

针对 VSCodium 用户的特殊说明

VSCodium 用户需要使用以下命令替代：

source "$(vscodium --locate-shell-integration-path zsh)"

最佳实践建议

1. 保持 VSCode 和 Roo Code 扩展为最新版本
2. 定期检查 shell 集成配置，特别是在系统或软件更新后
3. 对于性能较慢的系统，考虑简化 ZSH 配置或增加超时时间
4. 在遇到问题时，尝试完全关闭并重新打开 VSCode

通过以上方法，大多数用户应该能够解决 Roo Code 在 macOS 上 ZSH 终端的集成问题，恢复正常的命令执行功能。