diff --git a/agentskills/run-command-guide/SKILL.md b/agentskills/run-command-guide/SKILL.md index ca6116d..2591379 100644 --- 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` 的等待参数互斥,务必只传一个。 - 避免交互式命令、超出字符/超时限制,必要时将输出先写到文件再读。 diff --git a/agentskills/terminal-guide/SKILL.md b/agentskills/terminal-guide/SKILL.md index c64f141..3d83625 100644 --- 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 工具的标准流程: diff --git a/config/skill_hints.json b/config/skill_hints.json index 47c1bd2..9a6f987 100644 --- 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", "文档", "报告", "合同", "简历", "信函", "备忘录",