# TaskStop

按运行时 handle 停止正在运行的后台任务——shell 命令、派发的代理或远程会话。用它释放资源、取消无用的工作，或从卡住的任务中恢复。

## 何时使用

- 后台 shell 命令运行时间超出预期，且你不再需要其结果。
- 本地代理陷入循环或停滞，需要中止。
- 用户改变方向，原方向上的后台工作应被放弃。
- 远程会话即将超时，或持有你需要的资源。
- 在开始同一任务的新运行前，你需要一个干净的起点。

短时的后台工作宁可让它自行结束。`TaskStop` 用于继续执行没有价值或反而有害的情况。

## 参数

- `task_id` (string, 必填)：后台任务启动时返回的运行时 handle。它就是 `TaskOutput` 接收的那个标识符，而不是任务列表中的 `taskId`。

## 示例

### 示例 1

停止失控的后台 shell 命令。

```
TaskStop(task_id: "bash_01HXYZ...")
```

命令会收到终止信号；迄今已写入缓冲的输出在其输出路径仍可读。

### 示例 2

在用户改变方向后取消派发的代理。

```
TaskStop(task_id: "agent_01ABCD...")
```

## 注意事项

- `TaskStop` 请求终止，但不保证瞬时关闭。行为良好的任务会迅速退出；但执行阻塞 I/O 的进程可能需要片刻才会清理。
- 停止任务不会删除其输出。对后台 shell 任务，磁盘上的输出文件会被保留，并可用 `Read` 读取。对代理和会话，在停止前捕获的任何输出仍可通过 `TaskOutput` 访问。
- 未知的 `task_id`，或已结束的任务，会返回错误或无操作。这是安全的——你可以防御性地调用 `TaskStop`，无需先检查状态。
- 若打算重启同一工作，先停止旧任务再派发新任务，以免两次并行运行争用共享资源（文件、端口、数据库行）。
- `TaskStop` 不影响团队任务列表中的条目。要取消被跟踪的任务，请用 `TaskUpdate` 将其状态更新为 `deleted`。
