diff --git a/harness-api.md b/harness-api.md new file mode 100644 index 0000000..c284b99 --- /dev/null +++ b/harness-api.md @@ -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": "错误信息" +} +``` \ No newline at end of file diff --git a/harness-chat.md b/harness-chat.md index 663c8ac..bd1b643 100644 --- a/harness-chat.md +++ b/harness-chat.md @@ -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" + } + ] + } + ] } ```