docs: 终端skill补充完成后缀标记最佳实践与反例

agentskills/terminal-guide/SKILL.md

@@ -94,7 +94,7 @@ terminal_session(
 
 ```python
 terminal_input(
-    command="pip install -r requirements.txt",
+    command="pip install -r requirements.txt ; echo '__PipInstall_DONE__'",
     session_name="main",
     output_wait=30  # 收集输出的窗口期（秒）
 )
@@ -143,7 +143,7 @@ terminal_input(
 ```python
 # 例如：下载大文件
 terminal_input(
-    command="wget https://example.com/large-file.zip",
+    command="wget https://example.com/large-file.zip ; echo '__Download_DONE__'",
     output_wait=30  # 30秒确认下载开始
 )
 # 下载继续进行，稍后用 snapshot 检查进度
@@ -153,7 +153,7 @@ terminal_input(
 ```python
 # 例如：运行测试套件（预计 2 分钟完成）
 terminal_input(
-    command="pytest tests/",
+    command="pytest tests/ ; echo '__Pytest_DONE__'",
     output_wait=150  # 设置足够长，确保完成
 )
 ```
@@ -161,17 +161,23 @@ terminal_input(
 **场景 4：可能长时间无输出的任务**
 ```python
 # 例如：git clone 大仓库（可能长时间无输出）
-# 技巧：在命令后加 ; echo "__DONE__" 作为完成标记
+# 技巧：在命令后加“便于识别的后缀标记”作为完成信号
 terminal_input(
-    command="git clone https://github.com/large/repo.git ; echo '__DONE__'",
+    command="git clone https://github.com/large/repo.git ; echo '__GitClone_DONE__'",
     output_wait=30  # 30秒确认开始
 )
-# 稍后用 snapshot 检查，看到 __DONE__ 就知道完成了
+# 稍后用 snapshot 检查，看到 __GitClone_DONE__ 就知道完成了
 
-# 例如：批量处理文件
+# 例如：构建任务
 terminal_input(
-    command="for f in *.mp4; do ffmpeg -i \"$f\" \"${f%.mp4}.mp3\"; done ; echo '__DONE__'",
+    command="npm run build ; echo '__Build_DONE__'",
-    output_wait=60  # 给足时间，或稍后用 snapshot 检查 __DONE__
+    output_wait=60
+)
+
+# 例如：安装依赖
+terminal_input(
+    command="python3 -m pip install requests ; echo '__Pip_DONE__'",
+    output_wait=60
 )
 ```
 
@@ -214,7 +220,7 @@ terminal_session(action="open", session_name="download")
 
 # 2. 启动下载（加完成标记）
 terminal_input(
-    command="wget https://example.com/dataset.tar.gz ; echo '__DONE__'",
+    command="wget https://example.com/dataset.tar.gz ; echo '__Download_DONE__'",
     session_name="download",
     output_wait=20  # 20秒确认下载开始
 )
@@ -228,7 +234,7 @@ terminal_snapshot(session_name="download")
 # 5. 再次检查
 terminal_snapshot(session_name="download")
 # 输出：100% [=============] 1024MB  10.5MB/s  in 98s
-#       __DONE__  ← 看到这个就知道完成了
+#       __Download_DONE__  ← 看到这个就知道完成了
 ```
 
 ### 场景 3：运行测试套件（需要等待完成）
@@ -239,7 +245,7 @@ terminal_session(action="open", session_name="test", working_dir="backend")
 
 # 2. 运行测试（预计 2 分钟）
 terminal_input(
-    command="pytest tests/ -v",
+    command="pytest tests/ -v ; echo '__Pytest_DONE__'",
     session_name="test",
     output_wait=150  # 设置足够长，等待完成
 )
@@ -257,7 +263,7 @@ terminal_session(action="open", session_name="process")
 
 # 2. 批量转换（预计 5 分钟）
 terminal_input(
-    command="for img in *.png; do convert \"$img\" -resize 800x600 \"thumb_$img\"; done",
+    command="for img in *.png; do convert \"$img\" -resize 800x600 \"thumb_$img\"; done ; echo '__Convert_DONE__'",
     session_name="process",
     output_wait=300  # 5分钟
 )
@@ -281,7 +287,7 @@ terminal_input(
 
 # 3. 在虚拟环境中安装依赖
 terminal_input(
-    command="pip install -r requirements.txt",
+    command="pip install -r requirements.txt ; echo '__PipInstall_DONE__'",
     session_name="main",
     output_wait=60
 )
@@ -326,14 +332,14 @@ terminal_input(command="npm run build", output_wait=10)
 
 ✅ **正确：**
 ```python
-terminal_input(command="npm install", output_wait=10)
+terminal_input(command="npm install ; echo '__NpmInstall_DONE__'", output_wait=10)
 
 # 检查是否完成
 terminal_snapshot(session_name="main")
 # 如果看到还在运行，等待或增加 output_wait
 
-# 确认完成后再继续
+# 确认完成后再继续（也可加完成标记）
-terminal_input(command="npm run build", output_wait=60)
+terminal_input(command="npm run build ; echo '__Build_DONE__'", output_wait=60)
 ```
 
 ### 3. 在终端中启动交互式程序
@@ -389,17 +395,17 @@ terminal_session(action="reset", session_name="main")
 ❌ **问题：**
 ```python
 # pip install 可能需要 30-60 秒
-terminal_input(command="pip install tensorflow", output_wait=5)
+terminal_input(command="pip install tensorflow ; echo '__PipTensorflow_DONE__'", output_wait=5)
 # 5秒后返回，只看到 "Collecting tensorflow..."，看不到安装结果
 ```
 
 ✅ **改进：**
 ```python
-# 方案 1：设置足够长的 output_wait
+# 方案 1：设置足够长的 output_wait，并加完成标记
-terminal_input(command="pip install tensorflow", output_wait=90)
+terminal_input(command="pip install tensorflow ; echo '__PipTensorflow_DONE__'", output_wait=90)
 
-# 方案 2：短 output_wait 确认开始，稍后用 snapshot 检查
+# 方案 2：短 output_wait 确认开始，稍后用 snapshot 检查完成标记
-terminal_input(command="pip install tensorflow", output_wait=10)
+terminal_input(command="pip install tensorflow ; echo '__PipTensorflow_DONE__'", output_wait=10)
 # ... 做其他事情 ...
 terminal_snapshot(session_name="main")  # 检查是否完成
 ```
@@ -410,24 +416,48 @@ terminal_snapshot(session_name="main")  # 检查是否完成
 
 ### 技巧 1：使用完成标记（推荐）
 
-对于可能长时间无输出的任务，在命令后加 `; echo "__DONE__"`：
+对于可能长时间无输出的任务，在命令后加“便于识别的后缀标记”（推荐格式：`__<Task>_DONE__`）：
 
 ```python
-# git clone 大仓库
+# ✅ 好的做法（有清晰后缀）
 terminal_input(
-    command="git clone https://github.com/large/repo.git ; echo '__DONE__'",
+    command="git clone https://github.com/large/repo.git ; echo '__GitClone_DONE__'",
     output_wait=30
 )
+terminal_input(
+    command="npm run build ; echo '__Build_DONE__'",
+    output_wait=60
+)
+terminal_input(
+    command="python3 -m pip install requests ; echo '__Pip_DONE__'",
+    output_wait=60
+)
 
 # 稍后检查
 terminal_snapshot(session_name="main")
-# 看到 __DONE__ 就知道完成了
+# 看到对应的 __XXX_DONE__ 就知道完成了
+```
+
+```python
+# ❌ 不好的做法（不加后缀，难以快速判断完成）
+terminal_input(
+    command="git clone https://github.com/large/repo.git",
+    output_wait=30
+)
+terminal_input(
+    command="npm run build",
+    output_wait=60
+)
+terminal_input(
+    command="python3 -m pip install requests",
+    output_wait=60
+)
 ```
 
 **为什么有用：**
 - git clone、wget、scp 等命令可能长时间无输出
 - 完成后也可能没有明显的提示信息
-- `__DONE__` 是明确的完成信号，不会误判
+- 自定义后缀（如 `__Build_DONE__`）是明确完成信号，不会误判
 
 ### 技巧 2：看提示符