终端 Shell 集成

终端 Shell 集成是一个关键功能，使 itBuilder 能够在您的终端中执行命令并智能处理其输出。AI 与您的开发环境之间的这种双向通信解锁了强大的自动化功能。

什么是 Shell 集成？

Shell 集成在 itBuilder 中自动启用，直接连接到您终端的命令执行生命周期，无需您进行任何设置。这个内置功能允许 Roo：

通过 execute_command 工具代表您执行命令
实时读取命令输出，无需手动复制粘贴
自动检测并修复运行应用程序中的错误
观察命令退出代码以确定成功或失败
跟踪工作目录变化，当您导航项目时
智能响应终端输出，无需用户干预
使用聊天界面中出现在命令执行消息旁边的停止按钮直接从聊天界面停止运行命令

当您要求 Roo 执行安装依赖项、启动开发服务器或分析构建错误等任务时，shell 集成在后台工作，使这些交互变得流畅有效。

Shell 集成故障排除

Shell 集成内置于 itBuilder 中，在大多数情况下自动工作。如果您看到"Shell Integration Unavailable"消息或遇到命令执行问题，请尝试这些解决方案：

更新 VSCode/Cursor 到最新版本（需要 VSCode 1.93+）
确保选择了兼容的 shell：命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）→ "Terminal: Select Default Profile" → 选择 bash、zsh、PowerShell 或 fish
Windows PowerShell 用户：运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 然后重启 VSCode
WSL 用户：将 . "$(code --locate-shell-integration-path bash)" 添加到您的 ~/.bashrc

命令执行回退

itBuilder 有一个执行命令的回退机制。如果您选择使用 VS Code 的终端集成（通过取消选中 Disable terminal shell integration 设置）并且该集成随后失败，这最相关。

工作原理：如果 itBuilder 配置为使用 VS Code 的终端集成但无法连接或遇到问题，它可能会自动尝试使用后台进程直接执行命令。这是确保命令仍然尝试运行的回退。
通知：如果使用此回退，您可能会在聊天中看到通知，表明命令正在运行，但没有 Roo 的内联终端或 VS Code 的 shell 集成的完整功能（例如，实时输出流或精确的退出代码检测可能有限）。

解决方案：如果您遇到此回退，通常表示您的 VS Code shell 集成设置有问题。查看本文档中的故障排除步骤，或考虑通过确保 Disable terminal shell integration 设置被选中来使用 itBuilder 推荐的内联终端。

itBuilder 推荐的内联终端示例。

终端集成设置

itBuilder 提供设置来微调它与终端的交互方式。要访问这些设置：

点击 itBuilder 侧边栏右上角的图标。
在打开的设置窗格中，从左侧菜单选择"Terminal"组。

基本设置

终端输出限制

此设置控制 itBuilder 从您的命令中捕获多少输出。如果您担心令牌使用量或 Roo 处理非常长的输出时似乎很慢，请考虑降低它（您仍然会得到开头和结尾）。如果您经常需要直接在 Roo 的上下文中获得长命令的更多中间内容，请考虑增加它，但要注意潜在的令牌成本。默认值：500 行。

压缩进度条输出

保持此启用（默认）以获得更清洁的输出和令牌节省。它使 itBuilder 像真实终端一样处理动态输出如进度条或旋转器，只显示最终状态。仅在您特别需要调试进度条或类似动态显示的中间原始输出的罕见情况下禁用此功能。

高级设置

重要

这些设置需要重启终端

高级终端设置的更改只有在重启终端后才会生效。要重启终端：

点击终端面板中的垃圾桶图标关闭当前终端
使用 Terminal → New Terminal 或 Ctrl+`（反引号）打开新终端

更改任何这些设置后，始终重启所有打开的终端。

继承环境变量

此设置控制 itBuilder 的终端会话是否使用与您的主 VSCode/Cursor 环境相同的环境变量（如 PATH、API 密钥等）。它直接镜像 VSCode 全局设置 terminal.integrated.inheritEnv。如果您希望 Roo 命令在您的常规 VSCode 终端中可用的相同上下文和工具下运行，请保持此启用（VSCode 默认）。仅在您需要为 Roo 的终端任务提供完全干净、隔离的环境或正在故障排除复杂的环境变量冲突时才考虑禁用它。

运行时环境

在 macOS（可能还有其他操作系统）上，提供给 VSCode 的环境，因此 itBuilder 的环境可能因 VSCode 的启动方式而异。
如果从命令行 vscode 命令启动，VSCode 和 itBuilder 将从启动它的 shell 继承环境，一切都（通常）会很好。如果从 Finder、Dock 或 Spotlight 启动，从 .zshrc 或 .zprofile 导出的环境可能会丢失。如果您在这些文件之一中设置了环境变量，并发现它们在运行 VSCode 时丢失，请将它们移动到 .zshenv，然后注销并重新登录，这样窗口管理器将获取新的环境设置。

禁用终端 shell 集成

此设置决定 itBuilder 如何执行终端命令。

保持此复选框选中（推荐）： itBuilder 将使用其内置的内联终端执行命令，直接在聊天界面中显示输出。这种方法通常很强大，提供清晰的输出，是大多数用户通过 itBuilder 与终端命令交互的首选方式。它确保命令在 itBuilder 管理的一致环境中运行。

itBuilder 的内联终端，当"禁用终端 shell 集成"被选中时激活。
取消选中此复选框（使用 VS Code 的终端集成）： itBuilder 将尝试在您活动的 VS Code 终端面板中直接运行命令。这种替代方法可能对您明确需要命令在完全自定义的 VS Code shell 环境中运行或需要与 VS Code 终端的特定功能交互以执行命令的特定边缘情况有用。但是，根据您的 shell 设置和 VS Code 版本，这可能有时不太可靠。

以下设置是高级选项，仅当您取消选中'禁用终端 shell 集成'时才适用（选择使用 VS Code 的终端集成而不是 itBuilder 推荐的内联终端）：

终端 shell 集成超时

如果启用了 shell 集成但您仍然看到'Shell Integration Unavailable'，特别是对于复杂的 shell 设置（例如，带有许多插件的 Zsh，或加载缓慢的企业环境），您的 shell 可能需要太长时间来初始化。增加此值以给您的 shell 更多时间来向 itBuilder 发出就绪信号。尝试 5-10 秒的增量。默认值：15s（如 UI 中所示）。

终端命令延迟

如果命令输出看起来不完整或 Roo 似乎错过了命令输出的结尾（即使启用了 shell 集成），小的延迟可能有帮助。引入小延迟（例如，50ms 或 100ms）。这给终端更多时间来刷新所有输出，然后 itBuilder 认为命令完成。这是针对 VSCode 终端或某些 shell 中潜在时序问题的解决方法（见 VSCode 错误 #237208）。默认值：0ms。

启用 PowerShell 计数器解决方法

专门针对 PowerShell 用户。如果您发现 itBuilder 难以连续运行完全相同的 PowerShell 命令多次，或者如果 PowerShell 命令的输出捕获不可靠，请启用此功能。这为命令添加唯一计数器以帮助 PowerShell 区分它们。

清除 ZSH EOL 标记

专门针对 Zsh 用户。如果行不以换行符结尾，Zsh 有时会在行尾添加特殊字符（通常是 %）。如果 itBuilder 似乎误解或对 Zsh 命令的输出感到困惑，特别是如果输出的最后一行似乎包含意外字符，请启用此功能。这尝试删除该标记（PROMPT_EOL_MARK=''）。

启用 Oh My Zsh 集成

对于流行的 Zsh 框架 Oh My Zsh 的用户。如果您使用 Oh My Zsh 并遇到其他设置无法解决的一般终端命令执行或输出渲染问题，请启用此功能。这通过设置 ITERM_SHELL_INTEGRATION_INSTALLED=Yes 帮助 itBuilder 与 Oh My Zsh 的特定 shell 集成机制对齐。可能需要重启 IDE。

启用 Powerlevel10k 集成

对于 Zsh 的 Powerlevel10k 主题的用户。如果您的 Powerlevel10k 提示（可能相当复杂）似乎干扰 itBuilder 正确检测命令边界、解析输出或跟踪当前工作目录的能力，请启用此功能。这设置 POWERLEVEL9K_TERM_SHELL_INTEGRATION=true。

启用 ZDOTDIR 处理

针对具有自定义 Zsh 启动文件位置的 Zsh 用户的高级选项。如果您使用 ZDOTDIR 为您的 Zsh 配置文件（如 .zshrc）指定自定义目录，请启用此功能。此设置通过为其自己的集成脚本创建隔离的临时 ZDOTDIR 来帮助 itBuilder 与这样的设置正确工作，防止与您的个人 Zsh 环境冲突。

Shell 集成如何工作

Shell 集成实时将 Roo 连接到您终端的命令执行过程：

连接：当您打开终端时，VS Code 与您的 shell 建立特殊连接。
命令跟踪：VS Code 通过检测以下内容来监控您的终端活动：
- 何时出现新提示
- 何时输入命令
- 何时命令开始运行
- 何时命令完成（以及是否成功或失败）
- 您当前在哪个目录
不同的 Shell，相同的结果：每种 shell 类型（Bash、Zsh、PowerShell、Fish）在后台实现略有不同，但它们都向 Roo 提供相同的功能。
信息收集：Roo 可以看到正在运行什么命令、在哪里运行、需要多长时间、是否成功以及它们的完整输出 - 所有这些都无需您复制粘贴任何内容。

Shell 集成故障排除

PowerShell 执行策略（Windows）

PowerShell 默认限制脚本执行。要配置：

以管理员身份打开 PowerShell
检查当前策略：Get-ExecutionPolicy
设置适当的策略：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

常见策略：

Restricted：不允许脚本（默认）
RemoteSigned：本地脚本可以运行；下载的脚本需要签名
Unrestricted：所有脚本运行但会警告
AllSigned：所有脚本必须签名

手动 Shell 集成安装

如果自动集成失败，请将适当的行添加到您的 shell 配置中：

Bash (~/.bashrc)：

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

Zsh (~/.zshrc)：

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

PowerShell ($Profile)：

if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }

Fish (~/.config/fish/config.fish)：

string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

终端自定义问题

如果您使用终端自定义工具：

Powerlevel10k：

# 在 ~/.zshrc 中 sourcing powerlevel10k 之前添加
typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

替代方案：在 itBuilder 中启用 Powerlevel10k 集成设置。

验证 Shell 集成状态

使用这些命令确认 shell 集成处于活动状态：

Bash：

set | grep -i '[16]33;'
echo "$PROMPT_COMMAND" | grep vsc
trap -p DEBUG | grep vsc

Zsh：

functions | grep -i vsc
typeset -p precmd_functions preexec_functions

PowerShell：

Get-Command -Name "*VSC*" -CommandType Function
Get-Content Function:\Prompt | Select-String "VSCode"

Fish：

functions | grep -i vsc
functions fish_prompt | grep -i vsc

活动 shell 集成的视觉指示器：

终端标题栏中的 shell 集成指示器
命令检测高亮
终端标题中的工作目录更新
命令持续时间和退出代码报告

WSL 终端集成方法

使用 Windows Subsystem for Linux (WSL) 时，有两种不同的方式在 WSL 中使用 VSCode，每种方式对 shell 集成都有不同的影响：

方法 1：带有 WSL 终端的 VSCode Windows

在此设置中：

VSCode 在 Windows 中本机运行
您使用 VSCode 中的 WSL 终端集成功能
Shell 命令通过 WSL 桥接执行
可能由于 Windows-WSL 通信而经历额外延迟
Shell 集成标记可能受到 WSL-Windows 边界的影响：您必须确保 source "$(code --locate-shell-integration-path <shell>)" 在 WSL 环境中为您的 shell 加载，因为它可能不会自动加载；见上文。

方法 2：在 WSL 内运行的 VSCode

在此设置中：

您使用 code . 直接从 WSL 内启动 VSCode
VSCode 服务器在 Linux 环境中本机运行
直接访问 Linux 文件系统和工具
更好的性能和 shell 集成的可靠性
由于 VSCode 在 Linux 环境中本机运行，shell 集成会自动加载
WSL 开发的推荐方法

对于 WSL 的最佳 shell 集成，我们推荐：

打开您的 WSL 发行版
导航到您的项目目录
使用 code . 启动 VSCode
在 VSCode 内使用集成终端

已知问题和解决方法

Cygwin (bash, zsh)

Cygwin 在 Windows 系统上提供类 Unix 环境。要在 VS Code 中将 Cygwin 配置为您的终端：

从 https://www.cygwin.com/ 安装 Cygwin
打开 VS Code 设置：
- 选择 File > Preferences > Settings
- 点击右上角的"Open Settings (JSON)"图标

将以下配置添加到您的 settings.json（在顶级大括号 {} 内）：

{
  "terminal.integrated.profiles.windows": {
    "Cygwin": {
      "path": "C:\\cygwin64\\bin\\bash.exe",
      "args": ["--login"],
      "env": {"CHERE_INVOKING": "1"}
    }
  },
  "terminal.integrated.defaultProfile.windows": "Cygwin"
}

注意：如果您安装了 32 位 Cygwin，请使用 "C:\\cygwin\\bin\\bash.exe" 作为路径。

理解配置：
- path：指向您 Cygwin 安装中的 Bash 可执行文件
- args：--login 标志确保 shell 读取配置文件
- env：CHERE_INVOKING 环境变量告诉 Cygwin 使用当前目录作为工作目录
- terminal.integrated.defaultProfile.windows：将 Cygwin 设置为默认终端配置文件
要打开新的 Cygwin 终端：
- 按 Ctrl+Shift+(反引号) 打开新终端，或
- 按 F1，输入"Terminal: Create New Terminal (with Profile)"，然后选择"Cygwin"

虽然我们的测试表明这开箱即用，但如果您遇到 Cygwin 的 shell 集成问题，请确保您已按照"手动 Shell 集成安装"部分中的描述将适当的 shell 集成钩子添加到您的 Cygwin bash 配置文件中。

Windows 上 Fish + Cygwin 的 VS Code Shell 集成

对于在 Cygwin 环境中运行 Fish 终端的 Windows 用户，以下是 VS Code 的 shell 集成工作原理：

（可选）定位 Shell 集成脚本： 在 VS Code 内打开您的 Fish 终端并运行以下命令：
```
code --locate-shell-integration-path fish
```
这将输出 shellIntegration.fish 脚本的路径。记下此路径。

更新您的 Fish 配置： 编辑您的 config.fish 文件（通常位于您的 Cygwin 主目录中的 ~/.config/fish/config.fish）。添加以下行，最好在 if status is-interactive 块内或文件的最末尾：

# 示例 config.fish 结构
if status is-interactive
    # 您的其他交互式 shell 配置...
    # 自动定位集成脚本：
    string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

    # 或者如果上述对您失败：
    # 源 VS Code shell 集成脚本
    # 重要：用您在步骤 1 中找到的实际路径替换下面的示例路径。
    # 确保路径是 Cygwin 可以理解的格式（例如，使用 /cygdrive/c/...）。
    # source "/cygdrive/c/Users/YourUser/.vscode/extensions/..../shellIntegration.fish"
end

记住用步骤 1 中的实际路径替换示例路径，正确格式化为 Cygwin。

配置 VS Code 终端配置文件： 打开您的 VS Code settings.json 文件（Ctrl+Shift+P -> "Preferences: Open User Settings (JSON)"）。更新或添加 Fish 配置文件到 terminal.integrated.profiles.windows 下，如下所示：

{
  // ... 其他设置 ...

  "terminal.integrated.profiles.windows": {
    // ... 其他配置文件 ...

    // 推荐：使用 bash.exe 启动 fish 作为登录 shell
    "fish": {
      "path": "C:\\cygwin64\\bin\\bash.exe", // 或您的 Cygwin bash 路径
      "args": [
        "--login", // 确保登录脚本运行（对 Cygwin 环境很重要）
        "-i",      // 确保 bash 交互式运行
        "-c",
        "exec fish" // 用 fish 替换 bash 进程
      ],
      "icon": "terminal-bash" // 可选：使用可识别的图标
    }
    // 替代方案（如果上述失败）：直接启动 fish
    "fish-direct": {
      "path": "C:\\cygwin64\\bin\\fish.exe", // 确保这在您的 Windows PATH 中或提供完整路径
      // 在这里使用 'options' 而不是 'args'；否则，您可能会遇到错误"terminal process terminated exit code 1"。
      "options": ["-l", "-c"], // 示例：登录和交互式标志。
      "icon": "terminal-fish" // 可选：使用 fish 图标
    }
  },

  // 可选：如果希望，将 fish 设置为默认
  // "terminal.integrated.defaultProfile.windows": "fish", // 或 "fish-direct" 取决于您使用什么。

  // ... 其他设置 ...
}

注意：在 Cygwin 环境中，使用 bash.exe --login -i -c "exec fish" 通常更可靠，确保在 fish 启动前正确设置环境。但是，如果该方法不起作用，请尝试 fish-direct 配置文件配置。

重启 VS Code： 完全关闭并重新打开 Visual Studio Code 以应用更改。
验证： 在 VS Code 中打开新的 Fish 终端。Shell 集成功能（如命令装饰、更好的命令历史导航等）现在应该处于活动状态。您可以通过运行简单命令如 echo "Hello from integrated Fish!" 来测试基本功能。

此设置在 Windows 系统上使用 Cygwin、Fish 和 Starship 提示符可靠工作，应该帮助具有类似配置的用户。

VSCode 1.98 后的 Shell 集成失败

问题：在 VSCode 更新到 1.98 版本后，shell 集成可能失败，错误为"VSCE output start escape sequence (]633;C or ]133;C) not received"。

解决方案：

设置终端命令延迟：
- 在 itBuilder 设置中将终端命令延迟设置为 50ms
- 更改此设置后重启所有终端
- 这匹配较旧的默认行为并可能解决问题，但一些用户报告 0ms 的值效果更好。这是针对上游 VSCode 问题的解决方法。
回滚 VSCode 版本：
- 从 VSCode Updates 下载 VSCode v1.98
- 替换您当前的 VSCode 安装
- 不需要备份 Roo 设置
WSL 特定解决方法：
- 如果使用 WSL，确保您使用 code . 从 WSL 内启动 VSCode
ZSH 用户：
- 尝试在 Roo 设置中启用部分或全部 ZSH 相关解决方法
- 无论您的操作系统如何，这些设置都可以帮助

Ctrl+C 行为

问题：如果 Roo 尝试运行命令时终端中已经输入了文本，Roo 会先按 Ctrl+C 清除行，这可能会中断正在运行的进程。

解决方法：在要求 Roo 执行终端命令之前，确保您的终端提示为空（没有部分命令输入）。

多行命令问题

问题：跨多行的命令可能会混淆 Roo，并可能显示与当前输出混合的先前命令的输出。

解决方法：不要使用多行命令，而是使用 && 命令链接将所有内容保持在一行（例如，使用 echo a && echo b 而不是在单独的行上输入每个命令）。

PowerShell 特定问题

过早完成：PowerShell 有时在显示所有输出之前告诉 Roo 命令已完成。
重复命令：PowerShell 可能拒绝连续运行相同的命令。

解决方法：启用"PowerShell 计数器解决方法"设置并在设置中将终端命令延迟设置为 150ms，以给命令更多时间完成。

不完整的终端输出

问题：有时 VS Code 不显示或捕获命令的所有输出。

解决方法：如果您注意到缺少输出，请尝试关闭并重新打开终端标签页，然后再次运行命令。这会刷新终端连接。

故障排除资源

检查调试日志

当发生 shell 集成问题时，检查调试日志：

打开 Help → Toggle Developer Tools → Console
设置"Show All Levels"以查看所有日志消息
查找包含 [Terminal Process] 的消息
检查错误消息中的 preOutput 内容：
- 空的 preOutput ('') 意味着 VSCode 没有发送数据
- 这表明潜在的 VSCode shell 集成问题，或超出我们控制范围的上游错误
- shell 集成标记的缺失可能需要调整设置以解决可能的上游错误或与 shell 初始化和 VSCode 加载特殊 shell 集成钩子相关的本地工作站配置问题

使用 VSCode 终端集成测试扩展

VSCode Terminal Integration Test Extension 通过测试不同设置组合帮助诊断 shell 集成问题：

当命令停滞时：
- 如果您看到"command already running"警告，点击"Reset Stats"重置终端状态
- 这些警告表明 shell 集成不工作
- 尝试不同的设置组合，直到找到有效的组合
- 如果它真的卡住了，通过关闭窗口并按 F5 重启扩展
测试设置：
- 系统性地尝试不同的组合：
  - 终端命令延迟
  - Shell 集成设置
- 记录哪些组合成功或失败
- 这有助于识别 shell 集成问题的模式
报告问题：
- 一旦您找到有问题的配置
- 记录确切的设置组合
- 注意您的环境（操作系统、VSCode 版本、shell 和任何 shell 提示自定义）
- 用这些详细信息打开问题以帮助改进 shell 集成

其他资源

支持

如果您仍然有问题：

检查 itBuilder GitHub Issues
创建新问题，包含：
- 操作系统和 VSCode 版本
- Shell 类型
- 重现步骤
- 错误消息

如需额外帮助，请加入我们的 Discord。

什么是 Shell 集成？​

Shell 集成故障排除​

命令执行回退​

终端集成设置​

基本设置​

终端输出限制​

压缩进度条输出​

高级设置​

继承环境变量​

运行时环境​

禁用终端 shell 集成​

终端 shell 集成超时​

终端命令延迟​

启用 PowerShell 计数器解决方法​

清除 ZSH EOL 标记​

启用 Oh My Zsh 集成​

启用 Powerlevel10k 集成​

启用 ZDOTDIR 处理​

Shell 集成如何工作​

Shell 集成故障排除​

PowerShell 执行策略（Windows）​

手动 Shell 集成安装​

终端自定义问题​

验证 Shell 集成状态​

WSL 终端集成方法​

方法 1：带有 WSL 终端的 VSCode Windows​

方法 2：在 WSL 内运行的 VSCode​

已知问题和解决方法​

Cygwin (bash, zsh)​

Windows 上 Fish + Cygwin 的 VS Code Shell 集成​

VSCode 1.98 后的 Shell 集成失败​

Ctrl+C 行为​

多行命令问题​

PowerShell 特定问题​

不完整的终端输出​

解决方法：如果您注意到缺少输出，请尝试关闭并重新打开终端标签页，然后再次运行命令。这会刷新终端连接。​

故障排除资源​

检查调试日志​

使用 VSCode 终端集成测试扩展​

其他资源​

支持​

什么是 Shell 集成？

Shell 集成故障排除

命令执行回退

终端集成设置

基本设置

终端输出限制

压缩进度条输出

高级设置

继承环境变量

运行时环境

禁用终端 shell 集成

终端 shell 集成超时

终端命令延迟

启用 PowerShell 计数器解决方法

清除 ZSH EOL 标记

启用 Oh My Zsh 集成

启用 Powerlevel10k 集成

启用 ZDOTDIR 处理

Shell 集成如何工作

Shell 集成故障排除

PowerShell 执行策略（Windows）

手动 Shell 集成安装

终端自定义问题

验证 Shell 集成状态

WSL 终端集成方法

方法 1：带有 WSL 终端的 VSCode Windows

方法 2：在 WSL 内运行的 VSCode

已知问题和解决方法

Cygwin (bash, zsh)

Windows 上 Fish + Cygwin 的 VS Code Shell 集成

VSCode 1.98 后的 Shell 集成失败

Ctrl+C 行为

多行命令问题

PowerShell 特定问题

不完整的终端输出

解决方法：如果您注意到缺少输出，请尝试关闭并重新打开终端标签页，然后再次运行命令。这会刷新终端连接。

故障排除资源

检查调试日志

使用 VSCode 终端集成测试扩展

其他资源

支持