add

2026-09-20 14:54:37 +08:00
1 parent eee6640952
commit 32adcaaa48
@@ -0,0 +1,278 @@
+# SE智能体相关接口
+
+以下是对应 `/harness` 路由前缀的 SE 智能体 HTTP 接口文档。
+
+## 开启一个会话窗口
+
+- 请求地址：{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": "错误信息"
+}
+```
@@ -35,17 +35,9 @@
 | 字段 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `sessionId` | String | ✅ | 会话 ID；同一用户不同会话相互隔离 |
-| `userId` | String | ✅ | 用户 ID；用于智能体命名空间隔离 / 会话路由 |
+| `username` | String | ✅ | 用户名；用于智能体命名空间隔离 / 会话路由 |
 | `input` | String | ✅ | 用户输入内容 |
-| `chatModel` | Object | ❌ | 聊天模型配置（`name`、`stream`、`temperature`） |
-
-`chatModel` 结构：
-
-| 字段 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `name` | String | - | 模型名称，如 `gpt-oss-120b` |
-| `stream` | Boolean | `true` | 是否流式 |
-| `temperature` | Double | `0.2` | 温度 |
+| `confirmResults` | Array | ❌| （HITL）当工具需要用户确认时，提交用户确认结果，Agent将继续执行|

 ### 2.3 请求示例

@@ -56,14 +48,50 @@ Content-Type: application/json
 Accept: text/event-stream

 {
-  "sessionId": "sess-20260918-001",
-  "userId": "user-10001",
-  "input": "帮我梳理今天的任务清单，生成一份 markdown 并保存到工作区",
-  "chatModel": {
-    "name": "gpt-oss-120b",
-    "stream": true,
-    "temperature": 0.2
-  }
+    "sessionId": "1872639000000000001",
+    "username": "zhangsan",
+    "input": "你好，帮我查询一下上个月的销售数据并生成报表。",
+    "confirmResults": [
+        {
+            "confirmed": true,
+            "toolCall": {
+                "id": "call_001",
+                "name": "query_sales_data",
+                "input": {
+                    "month": "2026-08"
+                },
+                "content": null,
+                "metadata": {},
+                "state": "submitted"
+            },
+            "rules": [
+                {
+                    "tool_name": "query_sales_data",
+                    "rule_content": "month=2026-08",
+                    "behavior": "allow",
+                    "source": "userSettings"
+                },
+                {
+                    "tool_name": "export_report",
+                    "rule_content": null,
+                    "behavior": "deny",
+                    "source": "userSettings"
+                },
+                {
+                    "tool_name": "delete_record",
+                    "rule_content": null,
+                    "behavior": "ask",
+                    "source": "userSettings"
+                },
+                {
+                    "tool_name": "send_mail",
+                    "rule_content": "to=*",
+                    "behavior": "passthrough",
+                    "source": "userSettings"
+                }
+            ]
+        }
+    ]
 }
 ```