docs: rebalance terminal vs run_command skill guidance

2026-04-08 16:40:17 +08:00 · 2026-04-08 16:40:17 +08:00 · e742f4c1a5
commit e742f4c1a5
parent a04eca3aab
3 changed files with 72 additions and 42 deletions
--- a/agentskills/run-command-guide/SKILL.md
+++ b/agentskills/run-command-guide/SKILL.md
@ -1,6 +1,6 @@
 ---
 name: run-command-guide
-description: run_command 工具使用指南。介绍前台与后台模式、后台模式的等待方式（command_id + sleep(wait_runcommand_id)）、互斥参数约束以及常见坑与示例。
+description: run_command 工具使用指南。介绍前台与后台模式、后台模式处理长时间命令的标准流程（command_id + sleep(wait_runcommand_id)）、与 terminal 的边界、以及互斥参数约束。
 ---

 # run_command 使用指南
@ -10,7 +10,21 @@ description: run_command 工具使用指南。介绍前台与后台模式、后
 - `run_command` 是 **一次性执行** 的终端命令，适合查询文件信息（`ls`、`file`、`grep -n`）、触发 CLI 工具、做简单的数据转换或运行非交互脚本。它**不能**用于启动交互式程序（如 `python` REPL、`vim`、`top`）。
 - 每次调用必须提供 `timeout`（单位秒，必须大于 0），系统会在超时后强制打断命令并返回当前输出。
 - 输出内容有字符数限制（默认 10000 字符），超过时会被截断或遭拒，因此尽量控制命令输出量，必要时拆分多个命令或保存到文件再读取。
- 如果需要持续交互、长时间运行、反复检查进度，优先使用 `terminal_session`/`terminal_input`；`run_command` 用于“一次性”场景。
+- `run_command` 是当前“单条命令”默认入口：短命令走前台，长命令优先走后台模式。
+- 只有在需要会话状态（`cd`/`source`/`export` 后多步连续）或常驻服务时，才优先使用 `terminal_*`。
+
+## 长时间任务默认策略（重要）
+
+以下场景默认优先 `run_command(run_in_background=true)`：
+- `npm run build` / `cargo build` / `mvn package`
+- `pip install ...` / `npm install ...` / `brew install ...` / `apt install ...`
+- 单次 `git clone`、单次数据导入/导出、单次压缩打包
+
+标准流程：
+1. 后台发起命令并拿到 `command_id`
+2. 先继续处理其他任务
+3. 需要最终结果时调用 `sleep(wait_runcommand_id=command_id)`
+4. 或等待系统完成通知

 ## 执行模式：前台 vs 后台

@ -25,9 +39,16 @@ description: run_command 工具使用指南。介绍前台与后台模式、后
 - timeout 最长 3600 秒。命令在后台继续执行，工具会等约 5 秒收集当前输出并返回，然后 **立即释放控制权**，让你继续处理其他任务。
 - 返回值里会包含 `command_id`，`status` 可能是 `running_background`。你会拿到已经产生的输出片段，但最终结果要靠系统通知或手动等待。
 - 成功或失败完成后，系统会自动发送一条 `system` 消息（内容类似 `后台命令已完成（completed）`，并附带 `command_id`、`command`、`output` 摘要）通知你。不要再依赖 `wait_sub_agent`/手动轮询。
- 适合长时间任务（大规模日志分析、编译/安装、数据处理），或者你想发起命令后继续进行其他工作。
+- 适合长时间任务（构建/安装/批处理）或你想“先发起再继续别的工作”。
 - 返回的 `command_id` 需要保留，用于后续通过 `sleep(wait_runcommand_id=...)` 等待结果或根据通知定位输出。

+## 何时不要用 run_command（改用 terminal）
+
+- 需要 `cd` 后连续执行多条命令
+- 需要 `source venv/bin/activate` 后持续执行
+- 需要常驻服务（如 `npm run dev`）或持续追踪输出（如 `tail -f`）
+- 需要长期复用同一 shell 上下文
+
 ## 等待后台命令完成：command_id + sleep(wait_runcommand_id)

 1. 调用后台命令后记录 `command_id`（形如 `cmd_<时间戳>_<8位hash>`）；
@ -63,7 +84,8 @@ description: run_command 工具使用指南。介绍前台与后台模式、后
 5. **命令输出过大（超过 10000 字符）**：会被截断并提示降低输出量，可考虑写入文件再用 `read_file` 读取，或分步执行。
 6. **尝试运行交互式程序**：`run_command` 明确禁止，命令会在 `_validate_command` 阶段失败。
 7. **后台命令属于别的对话**：`sleep(wait_runcommand_id=...)` 会报 “该后台命令不属于当前对话”，只能在原 conversation 中等待。
-8. **误以为 `sleep` 会自动拼接 system message**：`sleep` 只是等待，系统通知仍旧按背景轮询插入，你收到 `system` 消息即可确认状态。
+8. **误把会话型任务交给 run_command**：当任务依赖 shell 上下文时请切换 `terminal_*`。
+9. **误以为 `sleep` 会自动拼接 system message**：`sleep` 只是等待，系统通知仍旧按背景轮询插入，你收到 `system` 消息即可确认状态。

 ## 示例

@ -97,7 +119,8 @@ sleep(wait_runcommand_id=command_id, reason="等待 pip 安装完成")

 ## 总结

- 前台模式适用于“立刻需要结果”的单步命令，后台模式适合“发起后继续干别的”的长任务。
+- 单条命令默认使用 run_command：前台用于快照，后台用于长任务。
 - 后台结果需要 `command_id + sleep(wait_runcommand_id=...)` 或系统通知来确认最终状态。
+- 会话型/常驻型任务请使用 terminal。
 - `sleep` 的等待参数互斥，务必只传一个。
 - 避免交互式命令、超出字符/超时限制，必要时将输出先写到文件再读。
--- a/agentskills/terminal-guide/SKILL.md
+++ b/agentskills/terminal-guide/SKILL.md
@ -1,13 +1,13 @@
 ---
 name: terminal-guide
-description: 持久化终端使用指南。使用 terminal_session、terminal_input、terminal_snapshot 工具前必须阅读此技能。用于理解持久化终端与 run_command 的区别、output_wait 参数的正确含义、以及如何处理长时间运行的任务。
+description: 持久化终端使用指南。使用 terminal_session、terminal_input、terminal_snapshot 工具前必须阅读此技能。用于理解持久化终端与 run_command（含后台模式）的分工、output_wait 参数含义、以及会话型任务的处理方式。
 ---

 # 持久化终端使用指南

 ## 核心原则

-**持久化终端 = 长期运行的命令行会话**
+**持久化终端 = 会话型命令行工具（重点是“会话状态”，不是“单纯时长”）**

 Terminal 工具提供了一个可以持续存在的终端会话，命令在其中运行不会因为你去做其他事情而中断。

@ -15,61 +15,56 @@ Terminal 工具提供了一个可以持续存在的终端会话，命令在其

 | 特性 | terminal 系列 | run_command |
 |------|--------------|-------------|
-| 会话类型 | 持久会话，可以一直存在 | 一次性执行 |
+| 会话类型 | 持久会话，可复用上下文 | 一次性执行 |
 | 超时行为 | output_wait 到期后命令继续运行 | timeout 到期强制终止命令 |
-| 适用场景 | 长时间任务、多步操作、后台服务 | 快速查看信息、一次性命令 |
-| 状态检查 | 可随时用 snapshot 查看 | 执行完就结束，无法再查看 |
-| 典型用途 | pip install、git clone、npm run dev | ls、file、grep -n |
+| 适用场景 | 会话状态依赖、多步串行、常驻服务 | 单步命令、快速查询、长任务后台化 |
+| 状态检查 | 可随时 snapshot 查看会话内容 | 通过 command_id + sleep(wait_runcommand_id) 等待 |
+| 典型用途 | npm run dev、tail -f、先 cd/activate 再连续执行 | npm run build、pip/brew/apt 安装、ls/file/grep |

-**选择标准：**
- 需要运行超过 30 秒？→ terminal
- 需要启动后继续做其他事？→ terminal
- 需要多次检查进度？→ terminal
- 只是快速查看信息？→ run_command
+**选择标准（新）**
+- 单条命令，即使很长（构建/安装）→ **优先 run_command 后台模式**
+- 需要 shell 会话状态（`cd`/`export`/`source venv` 后继续）→ **terminal**
+- 需要常驻服务或持续日志跟踪（`npm run dev`/`tail -f`）→ **terminal**
+- 只是快速查看信息 → **run_command 前台**

 ## 何时使用

 ### 适合 Terminal 的场景

-**长时间运行的任务：**
- 下载大文件（wget、curl、git clone）
- 安装依赖（pip install、npm install、apt install）
- 编译构建（make、cargo build、npm run build）
- 数据处理（批量转换、压缩、解压）
+**会话上下文依赖任务：**
+- `cd` 到目录后连续执行多条命令
+- 激活虚拟环境后连续执行（`source venv/bin/activate`）
+- 设置环境变量后再执行后续命令

 **需要保持运行的服务：**
 - 开发服务器（npm run dev、python -m http.server）
 - 数据库服务（redis-server、mongod）
 - 监控工具（tail -f、watch）

-**多步交互操作：**
- cd 到某个目录后继续执行多个命令
- 激活虚拟环境后运行命令
- 设置环境变量后执行任务
+**需要持续查看同一会话输出：**
+- 长时间跟踪日志
+- 观察服务状态
+- 多步执行中随时 snapshot

-**需要监控进度：**
- 运行测试套件并查看进度
- 批量处理文件并检查完成情况
- 长时间脚本执行并定期查看输出
+### 不适合 Terminal 的场景（优先 run_command）

-### 不适合 Terminal 的场景
-
-**快速信息查看（用 run_command）：**
+**快速信息查看：**
 - 查看文件信息（file、stat、ls -la）
 - 检查编码（iconv -l、file -i）
 - 简单的 grep 定位

+**单条长命令（建议后台模式）：**
+- `npm run build`
+- `pip install -r requirements.txt`
+- `brew install xxx` / `apt install xxx`
+- 单次 `git clone` / 单次打包构建
+
 **交互式程序（禁止使用）：**
 - Python/Node REPL
 - vim、nano、emacs
 - top、htop
 - 任何需要完整 TTY 的程序

-**一次性简单命令（用 run_command）：**
- 创建目录（mkdir）
- 移动文件（mv、cp）
- 查看环境变量（echo $PATH）
-
 ## 三步工作流

 使用 terminal 工具的标准流程：
--- a/config/skill_hints.json
+++ b/config/skill_hints.json
@ -1,12 +1,13 @@
 {
  "terminal-guide": {
    "keywords": [
-      "终端", "terminal", "会话", "session", "长时间", "后台", "持久",
-      "git clone", "下载", "安装", "pip install", "npm install",
-      "开发服务器", "npm run dev", "output_wait", "超时",
-      "background", "long-running", "download", "install", "dev server"
+      "终端", "terminal", "会话", "session", "持久", "持久化终端",
+      "terminal_session", "terminal_input", "terminal_snapshot", "output_wait",
+      "开发服务器", "npm run dev", "常驻服务", "日志跟踪", "tail -f",
+      "cd 后执行", "多步命令", "环境变量后执行", "虚拟环境后执行",
+      "dev server", "persistent terminal", "tail -f", "multi-step shell"
    ],
-    "hint": "检测到用户可能需要下载，克隆仓库或执行长时间运行的任务或使用持久化终端。如果情况符合，必须先阅读 terminal-guide skill。"
+    "hint": "检测到用户可能需要持久化终端（会话状态、多步串行或常驻服务）。如果情况符合，必须先阅读 terminal-guide skill。"
  },
  "sub-agent-guide": {
    "keywords": [
@ -17,6 +18,17 @@
    ],
    "hint": "检测到用户可能需要并行处理多个独立任务，可能创建子智能体为最优解。如果情况符合，必须先阅读 sub-agent-guide skill。"
  },
+  "run-command-guide": {
+    "keywords": [
+      "run_command", "runcommand", "后台指令", "后台命令", "命令后台运行", "后台执行",
+      "command_id", "wait_runcommand_id", "sleep wait_runcommand_id", "run_in_background",
+      "超时", "timeout", "终端命令", "shell命令", "执行命令",
+      "npm run build", "pip install", "brew install", "apt install", "cargo build", "mvn package",
+      "长时间命令", "长时间任务", "构建任务", "安装依赖", "后台等待",
+      "background command", "run command", "background run_command"
+    ],
+    "hint": "检测到用户可能需要使用 run_command（尤其是后台模式处理长时间命令，如构建/安装；以及 command_id 与 sleep(wait_runcommand_id)）。如果情况符合，必须先阅读 run-command-guide skill。"
+  },
  "docx": {
    "keywords": [
      "word", "docx", "文档", "报告", "合同", "简历", "信函", "备忘录",