tmp/harness-api.md

# SE智能体相关接口

以下是对应 `/harness` 路由前缀的 SE 智能体 HTTP 接口文档。

## 根据用户意图选子智能体

### 基本信息

| 项目 | 说明 |
|------|------|
| 接口地址 | `/harness/choose/subagent` |
| 请求方式 | `POST` |
| Content-Type | `application/json` |
| 响应类型 | `text/event-stream` (SSE) |
| 接口描述 | 根据用户意图选择子智能体 |

### 请求参数 (Request Body)

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | Long | 是 | 会话ID |
| username | String | 是 | 用户名 |
| input | String | 是 | 用户输入内容 |

#### 请求示例

```json
{
  "sessionId": 1001,
  "username": "zhangsan",
  "input": "帮我查看代码中的空指针异常"
}
```

### 响应参数 (Response Body)

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | int | 状态码 (200=成功, 500=失败) |
| msg | String | 消息内容 |
| data | Object | 响应数据对象 |
| data.sessionId | String | 会话ID |
| data.username | String | 用户名 |
| data.input | String | 用户输入 |
| data.output | String | 主智能体的输出 |
| data.subAgentId | String | 子智能体ID |

#### 成功响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "sessionId": "1001",
    "username": "zhangsan",
    "input": "帮我查看代码中的空指针异常",
    "output": "正在为您分配合适的子智能体...",
    "subAgentId": "code-review-agent"
  }
}
```

#### 失败响应示例

```json
{
  "code": 500,
  "msg": "参数[sessionId]不能为空",
  "data": null
}
```

---

## 保存子智能体回复

### 基本信息

| 项目 | 说明 |
|------|------|
| 接口地址 | `/harness/subagent/output` |
| 请求方式 | `POST` |
| Content-Type | `application/json` |
| 响应类型 | `text/event-stream` (SSE) |
| 接口描述 | 保存来自paw的子智能体回复内容 |

### 请求参数 (Request Body)

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | Long | 是 | 会话ID |
| username | String | 是 | 用户名 |
| subagentOutput | String | 是 | 子智能体回复内容 |

#### 请求示例

```json
{
  "sessionId": 1001,
  "username": "zhangsan",
  "subagentOutput": "在第42行发现潜在的空指针异常，建议添加空值检查..."
}
```

### 响应参数 (Response Body)

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | int | 状态码 (200=成功, 500=失败) |
| msg | String | 消息内容 |
| data | Long | 保存的消息ID |

#### 成功响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": 12345
}
```

#### 失败响应示例

```json
{
  "code": 500,
  "msg": "参数[username]不能为空",
  "data": null
}
```

---

## 通用说明

### 状态码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 500 | 操作失败 |

### 错误码说明

| 错误信息 | 说明 |
|----------|------|
| 参数[sessionId]不能为空 | sessionId为必填参数 |
| 参数[username]不能为空 | username为必填参数 |
| 参数[input]不能为空 | input为必填参数 |
| 参数[subagentOutput]不能为空 | subagentOutput为必填参数 |
| 操作失败 | 服务器内部错误 |


## 开启一个会话窗口

- 请求地址：{gateway}/harness/session
- 请求方式：PUT

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| username | 是 | String | 用户名称 |

### 请求示例

```bash
curl -X PUT {gateway}/harness/session -H "Content-Type: application/json" -d '{
    "username": "zhangsan"
}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | String | 新开启的会话ID（sessionId） |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": "1872639000000000001"
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 查看聊天记录列表

- 请求地址：{gateway}/harness/session/history
- 请求方式：POST

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| pageNum | 否 | Number | 页码，默认1 |
| pageSize | 否 | Number | 每页行数，默认20 |
| username | 否 | String | 用户名，不传则从token获取 |
| keywords | 否 | String | 根据用户的问题去搜索 |

### 请求示例

```bash
curl -X POST {gateway}/harness/session/history -H "Content-Type: application/json" -d '{
    "pageNum": 1,
    "pageSize": 20,
    "username": "zhangsan",
    "keywords": "如何配置"
}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| total | Number | 总记录数 |
| rows | Array | 会话列表数据 |
| rows.sessionId | String | 会话ID |
| rows.userQuestion | String | 用户的第一个问题 |
| rows.createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |
| rows.createAt | String | 创建人 |
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| extraData | Object | 列表之外的额外数据 |

### 成功示例

```json
{
    "total": 1,
    "rows": [
        {
            "sessionId": "1872639000000000001",
            "userQuestion": "如何配置聊天模型",
            "createTime": "2026-09-20 10:30:00",
            "createAt": "zhangsan"
        }
    ],
    "code": 200,
    "msg": "查询成功",
    "extraData": null
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 查看会话聊天记录

- 请求地址：{gateway}/harness/session/message/{sessionId}
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| sessionId | 是 | Number | 会话ID |

### 请求示例

```bash
curl -X GET {gateway}/harness/session/message/1872639000000000001
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Array | 聊天消息列表 |
| data.messageId | String | 消息ID |
| data.messageType | String | 消息类型（USER=用户输入，AGENT=智能体输出） |
| data.message | String | 消息内容（markdown格式） |
| data.context | Object | 扩展上下文信息 |
| data.createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "messageId": "1872639000000001001",
            "messageType": "USER",
            "message": "你好，请问如何配置聊天模型？",
            "context": null,
            "createTime": "2026-09-20 10:30:00"
        },
        {
            "messageId": "1872639000000001002",
            "messageType": "AGENT",
            "message": "你好！配置聊天模型可以参考以下步骤：...",
            "context": null,
            "createTime": "2026-09-20 10:30:05"
        }
    ]
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 预设的热门问题

- 请求地址：{gateway}/harness/hot/question
- 请求方式：GET

### 请求参数

无

### 请求示例

```bash
curl -X GET {gateway}/harness/hot/question
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Array | 热门问题列表 |
| data.questionShortName | String | 热门问题简写 |
| data.questionContent | String | 问题实际内容 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "questionShortName": "如何配置模型",
            "questionContent": "如何为智能体配置聊天模型？"
        }
    ]
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 预设的子智能体

- 请求地址：{gateway}/harness/subagent/config
- 请求方式：GET

### 请求参数

无

### 请求示例

```bash
curl -X GET {gateway}/harness/subagent/config
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Array | 子智能体配置列表 |
| data.name | String | 子智能体名称 |
| data.dataId | String | Nacos的配置文件ID |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "name": "代码助手",
            "dataId": "se-agent-code-helper"
        }
    ]
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

## 保存用户输入的内容

- 请求地址：{gateway}/harness/user/input
- 请求方式：POST

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| sessionId | 是 | Long | 会话ID |
| username | 是 | String | 用户名 |
| userInput | 是 | String | 用户输入的内容 |

### 请求示例

```bash
curl -X POST {gateway}/harness/user/input -H "Content-Type: application/json" -d '{
    "sessionId": 1872639000000000001,
    "username": "zhangsan",
    "userInput": "帮我查看代码中的空指针异常"
}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Long | 保存的消息ID |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": 1872639000000001001
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "参数[sessionId]不能为空"
}
```

## 重写用户输入

- 请求地址：{gateway}/harness/user/input/rewrite
- 请求方式：PUT

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| sessionId | 是 | Long | 会话ID |
| username | 是 | String | 用户名 |
| userId | 是 | Long | 用户ID |
| userInput | 是 | String | 用户输入的内容 |

### 请求示例

```bash
curl -X PUT {gateway}/harness/user/input/rewrite -H "Content-Type: application/json" -d '{
    "sessionId": 1872639000000000001,
    "username": "zhangsan",
    "userId": 1001,
    "userInput": "帮我查看代码中的空指针异常"
}'
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | String | 重写后的用户输入内容 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": "帮我查看代码中的空指针异常\n\n变量表提示信息：..."
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "参数[sessionId]不能为空"
}
```

## 删除会话

- 请求地址：{gateway}/harness/session/{sessionId}
- 请求方式：DELETE

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| sessionId | 是 | Long | 会话ID（路径参数） |

### 请求示例

```bash
curl -X DELETE {gateway}/harness/session/1872639000000000001
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Long | 被删除的会话ID |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": 1872639000000000001
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "删除失败"
}
```