语义代码搜索 JohnXu22786/semantic-search

dsh-semantic-search

面向 DeepSeek Harness（dsh）以及任意 Node 脚本的本地语义代码搜索。

English documentation: README.md

sema 为工作区构建片段级索引：源码经语言感知分词器（camel/snake/kebab 拆分、CJK n-gram）处理后，按符号感知边界切块（函数/类保持完整），再嵌入为定长向量——默认完全本地、零依赖（特征哈希的 TF-IDF），也可接入任意 OpenAI 兼容的 embedding 端点。查询基于该索引做混合检索（向量余弦 + BM25，用倒数排名融合 RRF 合并），即使关键词不完全一致也能按语义命中。

以 dsh 插件 bundle 形式交付——在 harness 工具注册表上提供一个 sema 工具（action=search、action=reindex 或 action=stats）——并附带独立的 sema CLI。

特性一览

- 默认离线可用 —— 内置 lexical 提供方无需网络、无需下载模型、无需 API key；可当作快速 BM25 增强的代码搜索使用。
- 符号感知分块 —— 保守的按语言表（16 种语言）提供边界，函数/类保持完整；漏判边界时优雅退化为普通文本块。
- CJK 感知分词 —— n-gram 分词（默认 bigram）让中文查询与文档无需分词库即可对齐；全角标点被折叠而非硬断。
- RRF 混合检索 —— 向量余弦与 BM25 双通道经倒数排名融合，单通道命中的文档也能进入排序。
- 优雅降级 —— 远程 provider 不可达时索引自动回退到本地 lexical provider（可用 allowFallback 控制）。
- 增量刷新 + 文件监听 —— action=reindex 按大小+mtime 差异更新，可选的 watcher 让索引保持新鲜。
- 持久化 —— 索引原子化保存到 <root>/.sema（JSON 元数据 + 二进制向量），provider/维度变化时自动检测失效。
- 确定性 —— 相同的工作区与配置产生相同的索引与排序结果。

支持的语言

TypeScript、JavaScript、Python、Go、Rust、Java、Kotlin、Scala、C、C++、C#、Objective-C、Ruby、PHP、Swift、Bash，以及常见数据/标记格式（JSON、YAML、TOML、Markdown、HTML、XML……）。

安装

作为 dsh bundle

本包声明 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }。补丁插入一行插件项，将 bundle 挂载到 ctx.tools 并注册 sema 工具。

从 npm（包名已保留；发布待访问权限配置完成后执行）
npm install -g dsh-semantic-search

或直接从此仓库安装
dsh plugin --profile demo add github:JohnXu22786/semantic-search

或使用本地检出目录
dsh plugin --profile demo add /path/to/semantic-search

作为独立 CLI

npm install -g dsh-semantic-search # 或: npm run build && node bin/sema.mjs
sema --help

dsh 工具 API

插件只提供一个 sema 工具。将 action 设为 search、stats 或 reindex，参数对象例如：

- 搜索：{ "action": "search", "query": "查找重试循环" }
- 统计：{ "action": "stats" }
- 全量重建：{ "action": "reindex", "full": true }

搜索时必须提供至少包含一个非空白字符的 query。缺少查询词、空字符串或仅含空白字符都会返回校验错误。

CLI 用法

sema index 从工作区构建完整索引 sema reindex [--full] 增量刷新（或加 --full 全量重建） sema search <query...> 混合向量+BM25 搜索，打印 top 命中 sema stats [--json] 索引健康度、provider 与规模数据

全局选项：

--root <dir> 工作区根目录（默认：当前目录） --data-dir <dir> 索引存储目录（默认：<root>/.sema） --provider <kind> embedding provider：lexical | openai（默认：lexical） --dim <n> embedding 维度（lexical 默认 4096；openai 0=自动） --base-url <url> OpenAI 兼容 embeddings 端点根地址 --model <name> embeddings 模型名（仅 openai） --api-key <key> API key（仅 openai；环境变量：SEMA_EMBEDDING_API_KEY） --top <n> search 打印的命中数（默认：20） --json 输出机器可读结果（支持处） --help 显示帮助

CLI 退出码

- 0 —— 成功（包括零命中的搜索，以及 --version/--help）。
- 1 —— 运行时失败（配置错误、构建/索引/搜索出错）。
- 2 —— 用法错误：未知命令、未知参数、缺少或为空白的搜索查询。

配置

可在 bundle 行的 config（示例见 cordis.patch.yml）、上面的 CLI 参数或代码默认值中配置：

| 选项 | 默认 | 含义 |
| root | cwd | 待索引的工作区根目录 |
| dataDir | .sema | 索引存储目录 |
| provider.kind | lexical | lexical（离线）或 openai |
| provider.dimension | 0（lexical: 4096） | embedding 维度；0=从端点自动推断 |
| provider.baseUrl | https://api.openai.com/v1 | OpenAI 兼容端点根地址 |
| provider.apiKey | 空 | 显式配置的 OpenAI API key；优先于环境变量和凭据库 |
| provider.model | text-embedding-3-small | embedding 模型名 |
| provider.apiKeyEnv | SEMA_EMBEDDING_API_KEY | 环境变量名称；也用作凭据库引用 |
| allowFallback | true | 远程 provider 失败时回退到 lexical |
| include / ignore | 默认 | 索引/忽略的 glob 集合 |
| maxLinesPerChunk | 80 | 分块大小硬上限 |
| nGram | 2 | CJK n-gram 大小（1 关闭 n-gram） |
| topK | 20 | 默认返回的命中数 |
| rrfK | 60 | RRF 融合常数 |
| vectorK | 300 | 融合前每通道候选数 |
| autosave | true | 构建后持久化索引 |
| autoIndex | true | 首次搜索时惰性构建 |
| watch | true | 监听工作区变更 |

OpenAI key 按以下顺序选择：provider.apiKey、provider.apiKeyEnv 指定的环境变量值，最后是以 provider.apiKeyEnv 为引用的宿主凭据库条目。凭据库中的 key 会在每次 embedding 操作时重新解析，因此凭据轮换无需重启插件。

开发

npm ci
npm test # 构建 + 运行 node:test 套件（76 个测试）
npm run typecheck
npm run build # tsc -> lib/

许可证

MIT —— 见 LICENSE。© 2026 dsh-semantic-search 贡献者。