terminal-operator

name	terminal-operator
description	终端命令执行——通过 run_terminal_command 用一次性 shell 子进程执行命令。wait_ms 决定阻塞时长；wait_ms:0 立即背景化，命令完成时 push 通知会激活下一轮 turn。 Agent 起的命令会出现在用户的 Terminal Tab transcript 中，用户可实时观察。
metadata	{"version":"1.0.0","tabtin":{"category":"developer","displayName":"Terminal Operator","tags":["terminal","shell","automation","pty"],"autoActivateFor":["terminal"],"tools":["run_terminal_command"]}}

Terminal Operator

LLM 通过 run_terminal_command 工具执行 shell 命令。命令由一次性 shell 子进程执行，工作目录默认 workspace；Terminal Tab 只是 transcript 展示面，不参与命令完成判定。

用户要「打开终端」→ 应用内可交互终端

用户说「打开终端 / 开个终端 / 给我一个终端」时，优先打开 TabTin 应用内可交互终端：

run_terminal_command(command="tabtin terminal open")
# 可选：tabtin terminal open --cwd <path> --title "项目终端"
# 聚焦已有：tabtin terminal list → tabtin terminal open --session-id <id>

这会新建（或聚焦）一个 可手动打字输入 的 Terminal Tab（xterm + node-pty），用户可以自己敲命令。

意图	正确做法	错误做法
给用户一个可交互终端	tabtin terminal open	tabtin desktop open "PowerShell" / Start-Process powershell
Agent 自己跑一条命令	run_terminal_command(command="...")	打开外部系统终端再打字
用户明确要系统 PowerShell / Windows Terminal	tabtin desktop open "PowerShell" --external	默认 desktop open（会被拦截）

不要把「打开终端」理解成启动 OS 级 PowerShell / cmd / Windows Terminal 窗口。

Agent 起的命令对用户可见

调 run_terminal_command 时，命令会自动开一个独立的 Terminal Tab（D3：每次新 tab，不复用），用户能：

• 实时看输出——命令 stdout / stderr 合流后出现在 tab 里
• 手动停止 background 任务——用户关闭 Agent tab 或 LLM 跑 run_terminal_command("kill <pid>") 都会让 bridge 终止仍在跑的 child process

这是 TabTin 的产品基本盘：Agent 在做的每一步都看得见、能干预。不要刻意隐藏命令输出——LLM 看到的 stdout 与用户在 tab 看到的是同源。

工作流

单次命令（wait_ms 内 sync 完成，最常用）

run_terminal_command(command="pnpm test")

返回 status="completed" + stdout / exit_code / duration_ms / exited_by。exit_code === 0 表示命令成功，非 0 是命令本身失败（不是工具失败）。

stderr 字段始终为空字符串——Agent shell bridge 合流后 stderr 已经在 stdout 里，不需要读。

大输出（超 30KB 落盘）

stdout 超 30KB 时返回会带 full_output_path 字段，stdout 字段是 head + tail preview。

run_terminal_command(command="git log --all --decorate")
# 返回 status="completed", stdout="..head..\n[truncated]\n..tail..", full_output_path="/tmp/...log"
# 看完整内容
read_file(path="<full_output_path>")  # 不要用 cat / head / tail

长任务（dev server / build / log tail）— wait_ms: 0

run_terminal_command(command="pnpm dev", wait_ms=0)
# 立即返回：status="running", session_id="agent-<spaceId>-<ts>-<rand>",
#         pid=12345, output_file="{tmpdir}/tabtin-agent-tasks/<sessionId>.log"
# （{tmpdir} 是 OS 临时目录：macOS 是 /var/folders/...，Linux 通常是 /tmp/...）

bridge 持续把命令输出 tail 到 output_file。不要再调一次同样命令。

任务完成时 push 通知会激活下一轮 turn——你可以继续做别的事不用主动等。想看实时进度用 read_file(path="<output_file>")，bridge 持续 tail 增量内容。

真路径用 envelope 里的 output_file 字段，不要假设路径——macOS 的 tmpdir 不是 /tmp/，硬编码会 ENOENT。直接把 envelope 返回的 output_file 值喂给 read_file 即可。

dev server 起动早早 ready：传 pattern="Server listening on port" 让本工具命中即返。

主动停止 background 任务

run_terminal_command(command="kill <pid>")
# 卡死进程用 kill -9 <pid>；模拟 Ctrl+C 用 kill -INT <pid>
# pid 在 status="running" envelope 里返回

kill 是幂等的（对已自然 exit 的 PID 不算错误，shell 返回退出码非 0 但不影响）。

交互式命令

普通 run_terminal_command 不支持交互输入。命令本身有 prompt 时会卡住，直到 timeout 或用户取消。最常用的做法是用命令本身的非交互参数（见下方非交互优先表）。

如果非交互参数不够用，先评估用 ask_user 让用户改用真正的手动 Terminal Tab（tabtin terminal open）操作，或等待未来的 interactive terminal 工具；不要把交互流程塞进普通 shell tool，也不要用 tabtin desktop open 打开系统终端来「凑合」。

非交互优先原则

终端命令必须优先用非交互模式。交互式 REPL（裸 python / node / irb 等）与编辑器（vim / nano）绝对不要启动。

非交互命令替代表

交互式（禁止）	非交互替代（必须）
npm init	npm init -y
npx create-*（有提示时）	加 --yes 或预先准备好答案文件
pip install（需确认时）	pip install --yes / pip install -q
apt-get install	apt-get install -y 或 DEBIAN_FRONTEND=noninteractive
git commit（无 -m）	git commit -m "message"
git rebase -i	git rebase --autosquash 或 GIT_SEQUENCE_EDITOR="sed -i ..." git rebase -i
crontab -e	crontab <<'EOF'\n...\nEOF
vim / nano / vi	用 edit_file / write_file 工具，不走 shell
mysql -p / psql 直连	用 tabtin table query CLI
ssh（密码认证）	ssh -o StrictHostKeyChecking=no + key 认证
裸 python / node（进 REPL）	python -c "..." / python script.py / node -e "..." / node script.js

管道输入模式

简单确认场景用管道代替交互：

yes | some_command                       # 自动回复 y
echo -e "input1\ninput2" | some_command  # 多行输入

命令安全分级

自动放行（regular）：

• tabtin *（所有 CLI 子命令）
• 只读命令：ls / cat / head / tail / grep / wc / echo / pwd / whoami / date
• 网络查询：curl（GET）/ ping / dig / nslookup

需要用户审批（explicit_permission）：

• 文件写入：cp / mv / mkdir / touch / tee
• 软件安装：pip install / npm install / brew install
• 进程操作：kill
• 脚本执行：python -c "..." / python script.py / node -e "..." / node script.js（需服务端放行）

禁止执行（prohibited）：

• 破坏性命令：rm -rf / / mkfs / dd / > /dev/sda
• 权限提升：sudo / su / chmod 777
• 数据库直连：mysql / psql（走 tabtin table query / tabtin table execute CLI）
• 系统修改：systemctl / launchctl / crontab -e
• 编辑器：vim / nano / vi（用 edit_file / write_file 工具）
• 交互式 REPL：裸 python / node（不带 -c/-e 或脚本文件参数）
• 输出重定向写文件：echo "x" > file（被 critical denylist 拦截）—— 用 write_file 工具

工作目录

• 默认 cwd = 工作目录根；绝对路径只通过环境变量 $TABTIN_WORKSPACE（Windows：$env:TABTIN_WORKSPACE / %TABTIN_WORKSPACE%）访问
• 相对路径相对工作目录根本身——不要再套一层 workspace/ 前缀
• 切其他目录：在命令内部 cd /path && <cmd> 或用绝对路径
• 长路径含空格用引号：cd "/path with spaces" && <cmd>
• 不要传 working_directory 参数——run_terminal_command 没这个字段，统一用 cwd-in-command 模式

错误恢复

• exit_code !== 0 → 分析 stdout 末尾（错误信息通常在那里）
• 命令超 wait_ms 仍在跑 → 不杀进程，转 status="running"；长任务直接 wait_ms=0 起后台 + push 通知回头
• hard_timeout_ms 超时 → 进程被 SIGTERM；envelope 带 killed_reason="hard_timeout"
• degraded: true → bridge 因 policy 降级到 sandbox 跑，输出真实但跟标准 shell process 行为有差异
• 权限拒绝 → 不要尝试 sudo，向用户说明需要的权限

绝不用 run_terminal_command 做有专门工具的事

• 找文件 → glob_search（不是 find / ls -R）
• 搜内容 → grep_search（不是 grep / rg）
• 读文件 → read_file（不是 cat / head / tail）
• 编辑文件 → edit_file（不是 sed / awk）
• 写文件 → write_file（不是 echo > / cat <<EOF）
• 跟用户说话 → 直接输出文本（不是 echo / printf）

CLI 命令参考

终端环境可用 tabtin CLI 快速调平台能力：

tabtin table query "SELECT ..."
tabtin table record insert --table-id <id> --data '{"字段":"值"}'
tabtin table record update --table-id <id> --record-id <rid> --data '{"字段":"值"}'
tabtin browser print --url "<url>" --save /tmp/page.md

各 App 的 CLI 全集见对应 Skill：

• 表格操作 → skills_read("app:tabdata/table-operator")
• 浏览器操作 → skills_read("app:tabweb/browser-operator")