前言¶
DeepSeek Harness (DSH) 侧重于插件化架构。在进行智能体开发或代码调试时，快速定位源码中的具体逻辑往往比简单的文本匹配更高效。传统的搜索工具依赖关键词匹配，难以理解代码语义。semantic-search 插件解决了这一问题，它将代码库片段转化为向量索引，支持自然语言查询。
是什么¶
这是一个为 DeepSeek Harness (DSH) 提供的本地语义代码搜索插件，由开发者 JohnXu22786 维护。插件的核心价值在于无需联网即可完成代码的语义理解与检索，支持片段级索引与混合检索策略。
核心功能¶
该插件包含以下主要能力：
- 代码索引：支持片段级、符号感知的索引构建。它能够识别函数、类等边界，并支持 16 种以上的编程语言（包括 TypeScript、Python、Go、Rust、Java、C/C++、Ruby、PHP、Swift、Bash、Markdown、JSON、YAML 等）。
- 离线嵌入：默认使用离线词法嵌入，无需网络或 API Key。同时也支持配置 OpenAI 兼容的端点。
- 混合检索：结合向量余弦相似度与 BM25 算法，并通过倒数排名融合 (RRF) 策略合并结果。
- 工具集：提供三个 DSH 工具 (
sema_search、sema_reindex、sema_stats) 和一个独立的sema命令行工具。 - 增量更新：支持增量刷新与文件监听，并持久化索引到
<root>/.sema目录。
安装与启用¶
安装前请确保环境满足要求：Node.js 版本需在 ^22.19.0 或 >=24.0.0 范围内。
- 执行安装命令：
dsh plugin --profile demo add github:JohnXu22786/semantic-search
- 安装完成后，插件会注册相应的工具到 DSH 的工具链中。
典型用法¶
安装后，可以使用 sema 命令进行索引构建、更新与搜索。
- 构建索引：从工作区构建完整索引。
sema index
- 增量更新：根据文件变更进行增量重建，或使用
--full进行完全重建。
sema reindex [--full]
- 语义搜索：混合向量与 BM25 检索，输出排名靠前的结果。
sema search <query...>
- 索引统计：查看索引健康状态、提供者信息及数据大小。
sema stats [--]
常用全局选项包括：
* --root <dir>：指定工作区根目录（默认为当前目录）。
* --provider <kind>：指定嵌入提供者类型（默认为 lexical）。
* --dim <n>：指定嵌入维度。
适用场景与注意¶
- 离线优先：插件默认离线工作，内置的词法提供者不依赖网络。如果配置了远程提供者且连接失败，会优雅降级回退到离线模式。
- 确定性：相同的源码和配置会产生确定的索引和排序结果。
- 权限与安全：插件以 DSH 进程的权限运行，安装前建议检查源码与许可证（MIT）。
- 生态说明：该插件为社区维护项目，通过 SkillHub 等目录发布，与 DeepSeek 或幻方官方无从属关系。
短结尾¶
semantic-search 为 DSH 生态提供了一个轻量、本地化的语义代码搜索方案。通过片段级索引和混合检索，它能够显著提升代码定位的准确性。更多细节可参考插件目录或 GitHub 仓库。
