Floating Terminal（Orca IDE）是一个面向 AI 编程智能体的终端技能，用于在 Orca IDE 环境下运行那些需要真人参与或需要真实 TTY 的命令。
用途
智能体自带的 Bash 工具没有人类可见、可应答的终端，而某些工具在没有终端时拒绝运行，例如生物识别解锁、密码管理器的应用集成、sudo、passkey，以及任何会弹出提示的命令。在 Orca IDE 下，解决办法是使用 Orca 的浮动终端，并且只通过 Orca 自己的 CLI 来驱动：这是一个存在于每个 Orca 桌面上的面板，无需其他应用即可打开和读取。scripts/orca-float 一次调用即可完成操作并返回结果。
使用时机与默认顺序
- 智能体自身的 Bash 工具：用于任何非交互式任务，始终是第一选择。
- orca-float run：用于任何需要真人、需要 TTY 或应当保持可见的任务。这是 Orca 下智能体的默认终端。
- 只有在 Orca 缺失（orca-float doctor 退出码为 3）或其浮动终端被禁用时，才请用户自行运行。
不要为此打开 iTerm、Terminal.app、gnome-terminal、osascript … do script 或 open -a Terminal：这些窗口在 Orca 之外，不会返回退出码，还会留下残留窗口。
使用方式
FLOAT="$(cc-plugin-root orca-tools)/skills/floating-terminal/scripts/orca-float" "$FLOAT" doctor # 此处浮动终端是否可用？（会创建并关闭一个探测） "$FLOAT" run --title "Unlock" -- some-cli signin # 运行、等待、返回 JSON；由真人在面板中应答提示 "$FLOAT" run --cwd ~/repo --timeout 600 -- ./script.sh --flag "two words" "$FLOAT" open --title "Shell" # 为真人打开一个交互式浮动 shell；打印其句柄
参数说明
--title T：标签页标题（默认 agent）。应说明正在请真人做什么。 --cwd DIR：运行目录（默认当前目录）。 --timeout SEC：等待完成的时间（默认 1800）。真人触摸传感器可能需要一些时间。 --tail N：返回的输出行数（默认 40；0 表示不返回）。 --no-log：不记录输出（用于会打印密钥的命令）。退出码仍会返回。 --keep：即使成功也保留标签页。失败的运行总是保留标签页，以便真人阅读。 --no-focus：创建标签页但不将面板置于前台。 --dry-run：打印将要运行的启动器，不创建任何内容。
-- 之后的一个参数会作为 shell 命令行运行（-- 'a | b'）；多个参数则逐词加引号。
输出：stdout 是一个 JSON 对象；进度信息输出到 stderr。
{ "ok": true, "state": "finished", "exit_code": 0, "handle": "term_…", "tab_closed": true, "seconds": 4, "output": "…last lines…" }
state 为 finished、timeout（仍在运行；标签页保留）或 gone（真人关闭了标签页）。退出状态：0 表示成功，1 表示命令失败或未完成，2 表示用法错误，3 表示未找到 Orca CLI。
调用前应告知真人——例如“将打开一个浮动终端并要求 Touch ID”——因为运行会阻塞，直到对方应答或 --timeout 超时。
密钥处理
如果命令会打印密钥：使用 --no-log，并且不要索取其输出。更好的做法是让命令自行将密钥写入目标位置（如 vault、keychain）。
绝不要把密钥放在命令行中：它会被写入临时脚本（目录权限 700，运行后删除）并显示在面板中。
输出日志与面板显示的字节相同。运行后会被删除；只有 --tail 指定的行数会返回。
工作原理与实测事实
在 macOS 上的 Orca 1.4.2xx 实测：
orca terminal create --worktree id:global-floating-terminal --command … 会在浮动终端中打开一个标签页，并在其中的登录 shell 里运行命令。orca terminal show 会报告该标签页的 worktreeId 为 global-floating-terminal；doctor 正是检查这一点。
orca terminal wait --for exit 的退出码不可信：对于一个实际退出码为 7 的命令，它报告 exitCode 0（exitCause host_status_unavailable）。而 orca terminal read 在 shell 退出后不返回任何内容。因此脚本不依赖这两者：命令在 script 下运行（真实 TTY，因此提示和生物识别解锁可用，且显示的每个字节都会被记录），自行将退出状态写入文件，脚本轮询该文件——最多 --timeout 次、每秒一次，每 15 秒检查一次标签页是否仍存在。
script 在 BSD（macOS）和 util-linux 之间不同；启动器在运行时选择正确的形式。
每次 orca terminal 调用都会指定其句柄。若省略，Orca 会使用活动终端，可能是其他会话的。只有本次运行创建的标签页会被关闭，绝不使用 --all。
Linux：使用相同的 Orca CLI 和相同的启动器（util-linux script）。CLI 由插件的共享查找器（scripts/lib/orca-cli.sh）查找：$ORCA_CLI、$ORCA_CLI_BIN_DIR/orca、PATH 上确实是 Orca 的 orca、orca-ide（CLI 在 Linux 上的名称：/opt/Orca/resources/bin/orca-ide，链接为 ~/.local/bin/orca-ide），然后是 Orca 自身的安装位置。在 Linux 桌面上 /usr/bin/orca 通常是 GNOME 屏幕阅读器，因此绝不信任裸 orca。
Orca CLI 与同一用户的 Orca 应用通信：以另一账户通过 SSH 使用时，doctor 会报告 Orca 自身的 runtime_unavailable 原因。浮动终端是本地面板：此技能驱动其运行所在机器上的 Orca，而非配对的运行时。
要求
启用浮动终端的 Orca IDE CLI、bash ≥ 3.2、python3 ≥ 3.9，以及 script（macOS 自带，util-linux 中也有）。
执行后反思
JSON 是否与真人在面板中看到的一致？如果退出码或输出不同，修复启动器并添加测试。
成功运行后是否残留标签页，或失败后是否关闭了标签页？修复关闭规则。
输出中是否出现密钥？该次运行本应使用 --no-log；如果上述情况未覆盖，请在此说明。