KMS Coder RAG（KmsCoderRagController）

提供 KMS 知识管理模块「Coder RAG 域」的能力：对用户查询文本向量化后，在 Coder cookbook 向量索引（disk 固定为 coder）中检索 top-k 相似代码片段。供 obpm-ai 通过 Feign 调用 CoderRagService（据类 Javadoc）。本控制器共 1 个端点，响应非统一 Resource，直接返回 KmsSimilarSnippetsResponse。

• 接口类型：REST 资源（@RestController，方法级 consumes/produces = MediaType.APPLICATION_JSON_VALUE）
• 基址：${myapps.context-path.kms:}/api/kms/coder/rag（类级 @RequestMapping 仅声明单一前缀）
• Tag：kms Coder RAG 模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/coder/rag/** 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此所有端点均需 accessToken（或前置过滤器标记 pass=true 的系统 Feign 调用——obpm-ai 经 Feign 携带合法 systemToken 时会被放行，详见 index.md「鉴权说明」）。accessToken 可通过以下任一方式传递：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。
• 执行用户：控制器继承 AbstractBaseController，但本端点未调用 getUser()，固定对 coder 向量库检索。
• 响应结构：非统一 Resource。端点直接以 ResponseEntity<KmsSimilarSnippetsResponse> 返回，HTTP 200，body 为 KmsSimilarSnippetsResponse（chunks 数组）。参数有误时由全局异常处理器抛 InvalidRequestException（HTTP 400）。
• 请求体：JSON 对象，类型为 KmsCoderRagSearchRequest（cn.myapps.common.dto.kms）。

---

1. Coder 相似片段检索

对 message 向量化后在 coder 向量索引中检索 top-k（disk 固定 coder）（据 @Operation.summary「Coder 相似片段检索」）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/search（完整：{kms-context}/api/kms/coder/rag/search）
• 鉴权：是（需 accessToken 或系统 Feign pass=true，据源码）
• Tag：kms Coder RAG 模块

请求参数

参数名	位置	类型	必填	说明
body	body	object	是	JSON 对象，见下方请求体

请求体

字段	类型	必填	说明
message	string	是	检索查询文本（用于向量相似度 embedding）；为空抛 InvalidRequestException
topK	int	否	返回片段数，默认 10；源码校验上限 100（超过抛 InvalidRequestException）

{
  "message": "如何用 iScript 获取当前登录用户",
  "topK": 10
}

请求示例

POST /api/kms/coder/rag/search?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "message": "如何用 iScript 获取当前登录用户", "topK": 10 }

响应

结构：非统一 Resource。HTTP 200，body 为 KmsSimilarSnippetsResponse，仅含字段 chunks（数组）。每项为 KmsSimilarSnippetDTO，字段如下：

字段	类型	说明
id	long	片段向量记录Id
diskId	string	所属网盘Id（Coder RAG 固定为 coder）
content	string	片段正文（不截断，与 KmsWikiRagController 不同）
title	string	片段/文档标题（入库时写入，可为 null）
filePath	string	文件内容校验和（历史字段名为 filePath，实为 checksum）
score	float	相似度分数
keywords	string	片段关键词（多为逗号分隔）

成功示例：

{
  "chunks": [
    {
      "id": 3001,
      "diskId": "coder",
      "content": "// 获取当前登录用户\nvar user = getCurrentUser();",
      "title": "iScript 获取当前用户",
      "filePath": "__CHECKSUM__",
      "score": 0.9123,
      "keywords": "iscript,用户,getCurrentUser"
    }
  ]
}

失败示例（参数有误，HTTP 400）：

{ "errcode": 400, "errmsg": "message 不能为空", "data": null, "errors": null }

注：失败响应由全局异常处理器包装为统一 Resource（与 KMS 其他端点一致）；成功响应**不**经 Resource 包装。

---