Kilo Code 语义搜索工具 semantic_search 完全指南从 Embedding 原理到实战查询【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocodesemantic_search是 Kilo Code 基于 AI Embedding 与向量检索实现的代码库语义搜索工具。与传统文本匹配不同它能理解查询的含义即使关键词不完全一致也能定位相关代码。本文以该工具的官方文档为主体结合仓库内semantic_search工具源码、索引引擎调用链与测试用例系统讲解它的参数、工作原理、配置前提、查询最佳实践与结果解读帮助你在 Kilo Code 中把语义搜索用到实处。工具概览semantic_search是 Kilo Code 中一个面向 Agent 的代码检索工具其完整描述在 packages/opencode/src/kilocode/tool/semantic-search.txt 中定义。它属于 Codebase Indexing代码库索引 功能的一部分需要额外的 Embedding Provider 与向量数据库配置后才能使用。Setup Required需要配置该工具依赖代码库索引功能使用前必须配置 Embedding Provider如 OpenAI 或 Ollama与向量数据库如 Qdrant。与传统基于字符串匹配的搜索不同它基于语义相似度工作把你的自然语言查询转化为 Embedding 向量再在向量数据库中检索最相近的代码块。参数定义工具接受两个参数其 Schema 定义位于 packages/opencode/src/kilocode/tool/semantic-search.ts参数必填类型说明query是string自然语言搜索查询描述你想找的代码含义path否string限定搜索范围的子目录路径相对当前工作区。留空则搜索整个工作区从源码可以看出两个关键细节query为空时会直接抛出query is required错误测试用例 packages/opencode/test/kilocode/semantic-search.test.ts 验证了这一行为path会被normalizeSearchPath处理为相对工作区的规范化路径若路径指向工作区之外如../outside会抛出path must be within the current workspace错误且不会发起任何搜索见测试 semantic-search.test.ts。路径中的./src/../src/tool会被规范化为src/tool。工具能做什么该工具在已索引的代码库中进行语义相似度检索而非精确文本匹配。它能找到与查询在概念上相关的代码块即使这些代码块不包含你输入的确切词语。返回结果包含相关代码片段Code Chunk文件路径File Path工作区相对路径行号范围Line Range相似度分数Similarity Score从实现上看工具执行后通过KiloIndexing.search(query, prefix)调用索引引擎见 semantic-search.ts并对返回的 payload 做类型校验filePath、codeChunk、startLine、endLine缺一不可非法结果会被过滤掉。最终输出文本格式例如Found 1 result for verify token. 1. src/auth/index.ts:10-18 (score 0.8123) export const verify () true这一格式由测试 semantic-search.test.ts 精确断言。何时使用该工具官方文档列出以下典型场景需要跨项目查找与特定功能相关的代码时寻找实现模式或相似代码结构时搜索错误处理、认证等概念性代码模式时探索陌生代码库、理解功能实现方式时查找可能受变更或重构影响的关联代码时工具描述 semantic-search.txt 还给出了更细的使用建议应当使用开放式探索早期你只知道意图、但不知道确切标识符或语义时一旦找到可能的文件或符号应改用Grep和Read跟进。不应使用查找精确符号或正则模式 → 用Grep按文件名或扩展名找文件 → 用Glob读取已知文件内容 → 用Read探索工作区之外的文件 → 用Grep、Glob、Read这一语义搜索探路、精确工具收尾的工作流在工具注册代码中也有体现packages/opencode/src/kilocode/tool/registry.ts 中引导模型在做开放式搜索、不知道确切符号名时先用semantic_search缩小范围再用Grep和/或Read跟进。核心特性语义理解Semantic Understanding按含义而非精确关键词查找代码跨项目搜索Cross-Project Search搜索整个已索引代码库而非仅限已打开文件上下文结果Contextual Results返回带文件路径与行号的代码片段便于跳转导航相似度评分Similarity Scoring结果按相关性排序相似度分数范围为 0-1范围过滤Scope Filtering可选path参数将搜索限定到特定目录智能排序Intelligent Ranking结果按语义相关性排序UI 集成UI Integration结果以语法高亮和导航链接展示性能优化Performance Optimized基于向量的快速搜索结果数量可配置前置条件该工具仅在 Codebase Indexing 正确配置后可用条件说明功能已配置必须在设置中启用 Codebase IndexingEmbedding Provider需要 OpenAI API Key 或 Ollama 配置向量数据库需要运行可访问的 Qdrant 实例索引状态代码库必须完成索引状态为 Indexed 或 Indexing从源码看可用性由两层机制保障注册期检查semanticTool在构建工具列表时先调用KiloIndexing.ready()只有索引初始化完成且状态非 Disabled 时semantic_search工具才会被注册进模型可用工具列表见 registry.ts执行期检查KiloIndexing.search在运行时再次校验entry.initialized与状态若未初始化或已禁用则直接返回空结果见 packages/opencode/src/kilocode/indexing.ts。也就是说索引未配置或未启用时Agent 甚至看不到这个工具从而避免无谓的调用失败。关于 Codebase Indexing 的完整配置启用开关、Embedding Provider 选型、向量库选择、kilo.jsonc配置项、Qdrant 部署等请阅读 Codebase Indexing 文档其中包括searchMinScore默认 0.4与searchMaxResults默认 50等直接影响本工具行为的关键参数。工作原理当semantic_search被调用时执行以下流程1. 可用性校验确认 CodeIndexManager 可用且已初始化确认设置中已启用代码库索引检查索引配置完整API Key、Qdrant URL 等校验当前索引状态允许搜索对应实现中工具执行前会先发起ctx.ask权限请求权限名semantic_search携带 query 与 path 元数据再调用索引引擎见 semantic-search.ts。测试 semantic-search.test.ts 验证了权限请求中的permission字段与元数据内容。2. 查询处理接收自然语言查询并生成 Embedding 向量使用与索引阶段相同的 Embedding ProviderOpenAI 或 Ollama将查询的语义含义转化为数学表示3. 向量搜索执行在 Qdrant 向量数据库中检索相似的代码 Embedding使用余弦相似度cosine similarity寻找最相关的代码块应用最低相似度阈值默认 0.4可配置过滤结果将结果限制为最多 50 条以保证性能这里的阈值与条数分别对应索引配置中的searchMinScore与searchMaxResults二者均可在 Codebase Indexing 的 Tuning Parameters 中调整。4. 路径过滤若指定path仅保留指定目录路径内的文件结果使用规范化路径比较确保过滤准确在过滤范围内保持相关性排序需要说明的是path过滤在工具层先把用户输入规范化为工作区相对路径normalizeSearchPath再作为directoryPrefix传给KiloIndexing.search引擎层处理见 indexing.ts。5. 结果处理与格式化将绝对文件路径转换为工作区相对路径以文件路径、行范围、相似度分数、代码内容组织结果同时为 AI 消费与 UI 展示语法高亮进行格式化从源码看工具层对 payload 做了防御性校验类型不符的条目被丢弃并把 Windows 风格路径中的\统一替换为/normalizePath保证跨平台输出一致。6. 双输出格式AI 输出结构化文本格式包含查询、文件路径、分数与代码块UI 输出JSON 格式支持语法高亮与导航能力查询最佳实践有效查询模式好的示例概念明确且具体semantic_search queryuser authentication and password validation/query /semantic_search好的示例聚焦功能semantic_search querydatabase connection pool setup/query /semantic_search好的示例面向问题semantic_search queryerror handling for API requests/query /semantic_search效果较差的示例过于笼统semantic_search queryfunction/query /semantic_search表现良好的查询类型功能描述Functional Descriptionsfile upload processing、email validation logic技术模式Technical Patternssingleton pattern implementation、factory method usage领域概念Domain Conceptsuser profile management、payment processing workflow架构组件Architecture Componentsmiddleware configuration、database migration scripts此外工具描述中明确要求查询请用英文书写Write the query in English.这有助于 Embedding 模型发挥最佳效果。目录范围限定Directory Scoping使用可选的path参数将搜索聚焦到代码库的特定部分在 API 模块内搜索semantic_search queryendpoint validation middleware/query pathsrc/api/path /semantic_search在测试文件中搜索semantic_search querymock data setup patterns/query pathtests/path /semantic_search搜索特定功能目录semantic_search querycomponent state management/query pathsrc/components/auth/path /semantic_search注意两个使用边界path必须位于当前工作区之内越界会直接报错由normalizeSearchPath强制校验默认不传path搜索整个当前工作区且无法搜索工作区之外的内容这类需求请改用其他工具。结果解读相似度分数分数区间含义0.8 - 1.0高度相关的匹配很可能正是你要找的0.6 - 0.8良好匹配具有较强概念相似性0.4 - 0.6可能相关但需要人工复核低于 0.4被过滤视为差异过大注分数下限对应searchMinScore默认 0.4可配置调整提高阈值可要求更精确的匹配降低阈值可纳入更多边缘相关代码。该参数在 Codebase Indexing 的 Search Results Configuration 中有详细说明。结果结构每条搜索结果包含File Path匹配文件的工作区相对路径Score相似度分数表示相关性0.4 - 1.0Line Range代码块的起始与结束行号Code Chunk与查询匹配的实际代码内容在 Agent 消费的文本输出中分数会保留 4 位小数例如(score 0.8123)并附带可跳转的文件路径:起-止行号定位信息。典型应用场景实现新功能时Kilo Code 会先搜索 authentication middleware 以理解现有模式再编写新代码排查问题时搜索 error handling in API calls 以跨代码库定位相关错误模式重构代码时搜索 database transaction patterns 以确保所有数据库操作的一致性接手新代码库时搜索 configuration loading 以理解应用如何启动引导这与注册代码中对模型的引导一致——semantic_search定位为开放式探索的第一站精确符号与内容读取交给Grep、Glob、Read。使用示例在整个项目中搜索认证相关代码semantic_search queryuser login and authentication logic/query /semantic_search在特定目录中查找数据库相关代码semantic_search querydatabase connection and query execution/query pathsrc/data/path /semantic_search查找 API 代码中的错误处理模式semantic_search queryHTTP error responses and exception handling/query pathsrc/api/path /semantic_search搜索测试工具与 Mock 设置semantic_search querytest setup and mock data creation/query pathtests/path /semantic_search查找配置与环境搭建代码semantic_search queryenvironment variables and application configuration/query /semantic_search限制与注意事项依赖外部服务需要 Embedding Provider 与向量数据库Qdrant 等配合依赖索引只能搜索已索引的代码块未索引内容无法命中结果数量上限单次搜索最多 50 条结果对应searchMaxResults相似度阈值仅返回高于相似度阈值的结果默认 0.4可配置文件大小限制仅限成功索引的 1MB 以下文件语言覆盖效果取决于 Tree-sitter 的语言支持范围当没有命中任何结果时工具会返回明确的空结果提示例如No relevant code found for verify token.或带范围的No relevant code found for authentication middleware in src/tool.便于 Agent 判断是否需要切换检索策略如改用Grep。源码指引如果你想深入理解该工具的完整实现链路建议按以下路径阅读工具定义与执行逻辑参数 Schema、权限请求、路径规范化、结果过滤与格式化工具描述提示词何时用、何时不用的完整说明索引引擎接入层KiloIndexing.search的初始化检查与搜索调用工具注册逻辑semantic_search仅在索引就绪时注册单元测试空查询报错、路径规范化、越界拒绝、结果格式化等行为的权威验证配套配置文档索引启用、Provider 选择、向量库与调参参数【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kilo Code 语义搜索工具 semantic_search 完全指南：从 Embedding 原理到实战查询
Kilo Code 语义搜索工具 semantic_search 完全指南从 Embedding 原理到实战查询【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocodesemantic_search是 Kilo Code 基于 AI Embedding 与向量检索实现的代码库语义搜索工具。与传统文本匹配不同它能理解查询的含义即使关键词不完全一致也能定位相关代码。本文以该工具的官方文档为主体结合仓库内semantic_search工具源码、索引引擎调用链与测试用例系统讲解它的参数、工作原理、配置前提、查询最佳实践与结果解读帮助你在 Kilo Code 中把语义搜索用到实处。工具概览semantic_search是 Kilo Code 中一个面向 Agent 的代码检索工具其完整描述在 packages/opencode/src/kilocode/tool/semantic-search.txt 中定义。它属于 Codebase Indexing代码库索引 功能的一部分需要额外的 Embedding Provider 与向量数据库配置后才能使用。Setup Required需要配置该工具依赖代码库索引功能使用前必须配置 Embedding Provider如 OpenAI 或 Ollama与向量数据库如 Qdrant。与传统基于字符串匹配的搜索不同它基于语义相似度工作把你的自然语言查询转化为 Embedding 向量再在向量数据库中检索最相近的代码块。参数定义工具接受两个参数其 Schema 定义位于 packages/opencode/src/kilocode/tool/semantic-search.ts参数必填类型说明query是string自然语言搜索查询描述你想找的代码含义path否string限定搜索范围的子目录路径相对当前工作区。留空则搜索整个工作区从源码可以看出两个关键细节query为空时会直接抛出query is required错误测试用例 packages/opencode/test/kilocode/semantic-search.test.ts 验证了这一行为path会被normalizeSearchPath处理为相对工作区的规范化路径若路径指向工作区之外如../outside会抛出path must be within the current workspace错误且不会发起任何搜索见测试 semantic-search.test.ts。路径中的./src/../src/tool会被规范化为src/tool。工具能做什么该工具在已索引的代码库中进行语义相似度检索而非精确文本匹配。它能找到与查询在概念上相关的代码块即使这些代码块不包含你输入的确切词语。返回结果包含相关代码片段Code Chunk文件路径File Path工作区相对路径行号范围Line Range相似度分数Similarity Score从实现上看工具执行后通过KiloIndexing.search(query, prefix)调用索引引擎见 semantic-search.ts并对返回的 payload 做类型校验filePath、codeChunk、startLine、endLine缺一不可非法结果会被过滤掉。最终输出文本格式例如Found 1 result for verify token. 1. src/auth/index.ts:10-18 (score 0.8123) export const verify () true这一格式由测试 semantic-search.test.ts 精确断言。何时使用该工具官方文档列出以下典型场景需要跨项目查找与特定功能相关的代码时寻找实现模式或相似代码结构时搜索错误处理、认证等概念性代码模式时探索陌生代码库、理解功能实现方式时查找可能受变更或重构影响的关联代码时工具描述 semantic-search.txt 还给出了更细的使用建议应当使用开放式探索早期你只知道意图、但不知道确切标识符或语义时一旦找到可能的文件或符号应改用Grep和Read跟进。不应使用查找精确符号或正则模式 → 用Grep按文件名或扩展名找文件 → 用Glob读取已知文件内容 → 用Read探索工作区之外的文件 → 用Grep、Glob、Read这一语义搜索探路、精确工具收尾的工作流在工具注册代码中也有体现packages/opencode/src/kilocode/tool/registry.ts 中引导模型在做开放式搜索、不知道确切符号名时先用semantic_search缩小范围再用Grep和/或Read跟进。核心特性语义理解Semantic Understanding按含义而非精确关键词查找代码跨项目搜索Cross-Project Search搜索整个已索引代码库而非仅限已打开文件上下文结果Contextual Results返回带文件路径与行号的代码片段便于跳转导航相似度评分Similarity Scoring结果按相关性排序相似度分数范围为 0-1范围过滤Scope Filtering可选path参数将搜索限定到特定目录智能排序Intelligent Ranking结果按语义相关性排序UI 集成UI Integration结果以语法高亮和导航链接展示性能优化Performance Optimized基于向量的快速搜索结果数量可配置前置条件该工具仅在 Codebase Indexing 正确配置后可用条件说明功能已配置必须在设置中启用 Codebase IndexingEmbedding Provider需要 OpenAI API Key 或 Ollama 配置向量数据库需要运行可访问的 Qdrant 实例索引状态代码库必须完成索引状态为 Indexed 或 Indexing从源码看可用性由两层机制保障注册期检查semanticTool在构建工具列表时先调用KiloIndexing.ready()只有索引初始化完成且状态非 Disabled 时semantic_search工具才会被注册进模型可用工具列表见 registry.ts执行期检查KiloIndexing.search在运行时再次校验entry.initialized与状态若未初始化或已禁用则直接返回空结果见 packages/opencode/src/kilocode/indexing.ts。也就是说索引未配置或未启用时Agent 甚至看不到这个工具从而避免无谓的调用失败。关于 Codebase Indexing 的完整配置启用开关、Embedding Provider 选型、向量库选择、kilo.jsonc配置项、Qdrant 部署等请阅读 Codebase Indexing 文档其中包括searchMinScore默认 0.4与searchMaxResults默认 50等直接影响本工具行为的关键参数。工作原理当semantic_search被调用时执行以下流程1. 可用性校验确认 CodeIndexManager 可用且已初始化确认设置中已启用代码库索引检查索引配置完整API Key、Qdrant URL 等校验当前索引状态允许搜索对应实现中工具执行前会先发起ctx.ask权限请求权限名semantic_search携带 query 与 path 元数据再调用索引引擎见 semantic-search.ts。测试 semantic-search.test.ts 验证了权限请求中的permission字段与元数据内容。2. 查询处理接收自然语言查询并生成 Embedding 向量使用与索引阶段相同的 Embedding ProviderOpenAI 或 Ollama将查询的语义含义转化为数学表示3. 向量搜索执行在 Qdrant 向量数据库中检索相似的代码 Embedding使用余弦相似度cosine similarity寻找最相关的代码块应用最低相似度阈值默认 0.4可配置过滤结果将结果限制为最多 50 条以保证性能这里的阈值与条数分别对应索引配置中的searchMinScore与searchMaxResults二者均可在 Codebase Indexing 的 Tuning Parameters 中调整。4. 路径过滤若指定path仅保留指定目录路径内的文件结果使用规范化路径比较确保过滤准确在过滤范围内保持相关性排序需要说明的是path过滤在工具层先把用户输入规范化为工作区相对路径normalizeSearchPath再作为directoryPrefix传给KiloIndexing.search引擎层处理见 indexing.ts。5. 结果处理与格式化将绝对文件路径转换为工作区相对路径以文件路径、行范围、相似度分数、代码内容组织结果同时为 AI 消费与 UI 展示语法高亮进行格式化从源码看工具层对 payload 做了防御性校验类型不符的条目被丢弃并把 Windows 风格路径中的\统一替换为/normalizePath保证跨平台输出一致。6. 双输出格式AI 输出结构化文本格式包含查询、文件路径、分数与代码块UI 输出JSON 格式支持语法高亮与导航能力查询最佳实践有效查询模式好的示例概念明确且具体semantic_search queryuser authentication and password validation/query /semantic_search好的示例聚焦功能semantic_search querydatabase connection pool setup/query /semantic_search好的示例面向问题semantic_search queryerror handling for API requests/query /semantic_search效果较差的示例过于笼统semantic_search queryfunction/query /semantic_search表现良好的查询类型功能描述Functional Descriptionsfile upload processing、email validation logic技术模式Technical Patternssingleton pattern implementation、factory method usage领域概念Domain Conceptsuser profile management、payment processing workflow架构组件Architecture Componentsmiddleware configuration、database migration scripts此外工具描述中明确要求查询请用英文书写Write the query in English.这有助于 Embedding 模型发挥最佳效果。目录范围限定Directory Scoping使用可选的path参数将搜索聚焦到代码库的特定部分在 API 模块内搜索semantic_search queryendpoint validation middleware/query pathsrc/api/path /semantic_search在测试文件中搜索semantic_search querymock data setup patterns/query pathtests/path /semantic_search搜索特定功能目录semantic_search querycomponent state management/query pathsrc/components/auth/path /semantic_search注意两个使用边界path必须位于当前工作区之内越界会直接报错由normalizeSearchPath强制校验默认不传path搜索整个当前工作区且无法搜索工作区之外的内容这类需求请改用其他工具。结果解读相似度分数分数区间含义0.8 - 1.0高度相关的匹配很可能正是你要找的0.6 - 0.8良好匹配具有较强概念相似性0.4 - 0.6可能相关但需要人工复核低于 0.4被过滤视为差异过大注分数下限对应searchMinScore默认 0.4可配置调整提高阈值可要求更精确的匹配降低阈值可纳入更多边缘相关代码。该参数在 Codebase Indexing 的 Search Results Configuration 中有详细说明。结果结构每条搜索结果包含File Path匹配文件的工作区相对路径Score相似度分数表示相关性0.4 - 1.0Line Range代码块的起始与结束行号Code Chunk与查询匹配的实际代码内容在 Agent 消费的文本输出中分数会保留 4 位小数例如(score 0.8123)并附带可跳转的文件路径:起-止行号定位信息。典型应用场景实现新功能时Kilo Code 会先搜索 authentication middleware 以理解现有模式再编写新代码排查问题时搜索 error handling in API calls 以跨代码库定位相关错误模式重构代码时搜索 database transaction patterns 以确保所有数据库操作的一致性接手新代码库时搜索 configuration loading 以理解应用如何启动引导这与注册代码中对模型的引导一致——semantic_search定位为开放式探索的第一站精确符号与内容读取交给Grep、Glob、Read。使用示例在整个项目中搜索认证相关代码semantic_search queryuser login and authentication logic/query /semantic_search在特定目录中查找数据库相关代码semantic_search querydatabase connection and query execution/query pathsrc/data/path /semantic_search查找 API 代码中的错误处理模式semantic_search queryHTTP error responses and exception handling/query pathsrc/api/path /semantic_search搜索测试工具与 Mock 设置semantic_search querytest setup and mock data creation/query pathtests/path /semantic_search查找配置与环境搭建代码semantic_search queryenvironment variables and application configuration/query /semantic_search限制与注意事项依赖外部服务需要 Embedding Provider 与向量数据库Qdrant 等配合依赖索引只能搜索已索引的代码块未索引内容无法命中结果数量上限单次搜索最多 50 条结果对应searchMaxResults相似度阈值仅返回高于相似度阈值的结果默认 0.4可配置文件大小限制仅限成功索引的 1MB 以下文件语言覆盖效果取决于 Tree-sitter 的语言支持范围当没有命中任何结果时工具会返回明确的空结果提示例如No relevant code found for verify token.或带范围的No relevant code found for authentication middleware in src/tool.便于 Agent 判断是否需要切换检索策略如改用Grep。源码指引如果你想深入理解该工具的完整实现链路建议按以下路径阅读工具定义与执行逻辑参数 Schema、权限请求、路径规范化、结果过滤与格式化工具描述提示词何时用、何时不用的完整说明索引引擎接入层KiloIndexing.search的初始化检查与搜索调用工具注册逻辑semantic_search仅在索引就绪时注册单元测试空查询报错、路径规范化、越界拒绝、结果格式化等行为的权威验证配套配置文档索引启用、Provider 选择、向量库与调参参数【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考