---
title: "任务控制流 WebSocket"
method: GET
path: "/api/v1/users/tasks/control"
tags: ["【用户】任务管理"]
---

# 任务控制流 WebSocket

`GET /api/v1/users/tasks/control`

数据格式约定：当前仅支持文本帧透传。服务端将 Agent 的原始文本数据包装为如下结构返回给前端（对应 domain.TaskStream）：
```json
{ "type": "string", "data": "string", "kind": "string", "timestamp": 0 }
```
独立于 stream 的长生命周期 WebSocket 连接，用于处理 call/call-response（文件浏览、diff 查看等同步请求）。
task 结束后连接不断开，仍可用于文件操作。
支持同一 taskID 多 tab 并发连接。

## 上行消息

### Type=call, Kind=repo_file_diff — 获取文件 diff
请求 Data:
```json
{"request_id":"string","path":"string","unified":true,"context_lines":3}
```
响应 Data:
```json
{"request_id":"string","path":"string","diff":"string","success":true,"error":"string?"}
```

### Type=call, Kind=repo_file_list — 列出目录文件
请求 Data:
```json
{"request_id":"string","path":"string","glob_pattern":"string?","include_hidden":false}
```
响应 Data:
```json
{"request_id":"string","path":"string","files":[{"name":"string","path":"string","entry_mode":0,"size":0,"modified_at":0}],"success":true,"error":"string?"}
```

### Type=call, Kind=repo_read_file — 读取文件内容
请求 Data:
```json
{"request_id":"string","path":"string","offset":0,"length":0}
```
响应 Data:
```json
{"request_id":"string","path":"string","content":"bytes","total_size":0,"offset":0,"length":0,"is_truncated":false,"success":true,"error":"string?"}
```

### Type=call, Kind=repo_file_changes — 查询变更文件列表
请求 Data:
```json
{"request_id":"string"}
```
响应 Data:
```json
{"request_id":"string","changes":[{"path":"string","status":"string","additions":0,"deletions":0,"old_path":"string?"}],"branch":"string?","commit_hash":"string?","success":true,"error":"string?"}
```

### Type=call, Kind=port_forward_list — 获取端口转发列表
请求 Data:
```json
{"request_id":"string"}
```
响应 Data:
```json
{"request_id":"string","ports":[{"port":0,"status":"string","process":"string","forward_id":"string?","access_url":"string?","label":"string?","error_message":"string?","whitelist_ips":["string"]}]}
```

### Type=call, Kind=restart — 重启任务
请求 Data:
```json
{"request_id":"string","load_session":true}
```
响应 Data:
```json
{"id":"uuid","request_id":"string?","success":true,"message":"string","session_id":"string"}
```

### Type=call, Kind=switch_model — 切换运行中任务模型
请求 Data:
```json
{"request_id":"string","model_id":"uuid","load_session":true}
```
响应 Data:
```json
{"id":"uuid","request_id":"string?","success":true,"message":"string","session_id":"string","model":{}}
```

### Type=call, Kind=switch_agent_resources — 运行中更新任务 skill/plugin 列表
请求 Data (全量声明当前所选，非增量)：
```json
{"request_id":"string","skill_ids":["uuid"],"plugin_ids":["uuid"]}
```
响应 Data:
```json
{"request_id":"string","success":true,"message":"string","session_id":"string"}
```

### Type=sync-my-ip — 同步 Web 客户端真实 IP
请求 Data:
```json
{"client_ip":"string"}
```

## 下行消息

- Type=call-response: 同步请求响应（Kind 与请求一致）。失败时 Data 为:
```json
{"request_id":"string","success":false,"error":"string"}
```
- Type=task-event: 任务事件（从 TaskLive 订阅转发）
- Type=ping: 心跳（无 Data）

## Query parameters

- `id` string, required

## Response `200`

成功

- WebResp
  - `code` integer
  - `data` unknown
  - `message` string

## Other responses

- `500` — 服务器内部错误

---

[API](https://skmtc.net/chaitin/apis/untitled-api.md) · [All operations](https://skmtc.net/chaitin/apis/untitled-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/chaitin/untitled-api/revisions/5a5929cb17f2/schema)