# 搜索会话

`POST` `/api/session/search`

按关键词全文搜索当前主体名下的会话，匹配范围为会话标题、用户输入和助手输出三个字段。结果按会话折叠：每个会话仅返回相关性最高的一条消息作为代表，total为满足条件的会话数。highlight=true（默认）时命中词以<em>标签包裹返回高亮片段，未命中的字段高亮列表为空；highlight=false时三个高亮字段均返回空列表，查询开销略有降低。支持按agentId、triggerSourceTypeList精确过滤收窄搜索范围，过滤条件可自由组合，不影响相关性排序和高亮。返回的代表消息附带requestId、userMessageId、assistantMessageId，可用于跳转定位到会话内的具体消息（消息ID写入索引时未提供则为空）。用户模式仅搜索当前登录用户名下的会话；应用模式仅搜索请求头X-Principal-Id指定主体名下的会话。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| keyword | string | 是 | 搜索关键词，匹配会话标题、用户输入和助手输出，长度不超过100个字符 |
| agentId | integer | 否 | 智能体ID过滤条件（可选） |
| triggerSourceTypeList | array | 否 | 触发来源类型过滤条件（可选），可传多个，命中列表中任一类型即返回。精确匹配且区分大小写，可选值：human_message(人类消息，用户通过通道发送的消息触发)、scheduled_task(定时任务，由定时调度系统触发)、api_call(API调用，通过API直接调用触发，如Web端调试)；不传则不过滤 |
| highlight | boolean | 否 | 是否返回命中高亮片段，默认true；不需要高亮展示时传false可降低查询开销 |
| page | integer | 否 | 页码，从1开始 |
| pageSize | integer | 否 | 每页记录数，取值范围1~100 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | PageResultSessionSearchItemVO | 响应数据 |
|     items | array | 数据列表 |
|         sessionId | integer | 会话ID |
|         sessionTitle | string | 会话标题 |
|         agentId | integer | 智能体ID |
|         principalId | integer | 主体ID |
|         triggerSourceType | string | 触发来源类型，可选值：human_message(人类消息，用户通过通道发送的消息触发)、scheduled_task(定时任务，由定时调度系统触发)、api_call(API调用，通过API直接调用触发，如Web端调试) |
|         gmtCreate | integer | 代表消息创建时间（毫秒时间戳） |
|         score | number | 相关性得分，值越大越相关 |
|         requestId | string | 代表消息（该会话相关性最高的消息）的请求ID，对应写入索引时的requestId，可用于跳转定位该轮对话 |
|         userMessageId | integer | 代表消息的用户消息ID，可用于跳转定位到会话内的具体消息；写入索引时未提供则为空 |
|         assistantMessageId | integer | 代表消息的助手消息ID，可用于跳转定位到会话内的具体消息；写入索引时未提供则为空 |
|         representativeUserInput | string | 代表消息（该会话相关性最高的消息）的用户输入原文 |
|         representativeAssistantText | string | 代表消息的助手输出原文 |
|         titleHighlights | array | 会话标题高亮片段，命中词以<em>标签包裹，标题未命中时为空列表 |
|         userInputHighlights | array | 用户输入高亮片段，命中词以<em>标签包裹，未命中时为空列表 |
|         assistantTextHighlights | array | 助手输出高亮片段，命中词以<em>标签包裹，未命中时为空列表 |
|     total | integer | 总记录数 |
|     page | integer | 当前页码，从1开始 |
|     pageSize | integer | 每页大小 |
|     totalPages | integer | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |