dsh-vectordb 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 he fangsheng (https://github.com/dongsheng123132)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,139 @@
-# dsh-vectordb · 本地向量库
+# dsh-vectordb · 本地纯向量存储 + 两步检索
 
-> **定义**：本地零依赖向量库，支持元数据过滤与混合检索（BM25 + 余弦），不起服务、不接 SaaS。
->
-> **English**: A local, dependency-free vector store for embeddings with metadata filters and hybrid (BM25 + cosine) search — no server, no SaaS.
+dsh-vectordb 是一个 DSH（DeepSeek Harness）插件，用于在本地存向量、按元数据过滤做近似检索：多集合、`vectors.jsonl` 追加日志 + 墓碑 + `compact` 重写、幂等 `opId`；检索走**两步**——先对 k-means 质心粗筛，再对候选算真距离，返回里永远带 `scanned` / `candidates` / `returned` 与 `exact` 标记。安装：`dsh plugin --profile web add dsh-vectordb`。
 
-状态：**0.0.1 名称占位**（name reservation）。实现中；能力说明即本包目标范围，完成前请勿依赖。
+包 `dsh-vectordb@0.1.0` · 已实测宿主 DSH 0.2.2-rc.1、Node 23.11.0 · 许可 MIT · 作者主页 https://github.com/dongsheng123132 · 仓库 https://github.com/dongsheng123132/dsh-vectordb（发布时创建）
 
-## 它补上 DSH 的哪一块
+**零依赖、不联网、不接 ANN 库**：不引 hnswlib/faiss，不用任何外部服务；测试逐条锁死「没有网络模块、没有子进程、零运行时依赖」。
 
-本地零依赖向量库，支持元数据过滤与混合检索（BM25 + 余弦），不起服务、不接 SaaS。
+## 它解决什么？
 
-## 安装（可用版本发布后）
+想在 agent 会话里做 RAG，常见两条路：接一个 SaaS 向量库（要联网、要 Key、数据出门），或者装 ANN 库（要编译、要依赖）。这个插件走第三条：**本地文件 + 手写聚类**，把「真向量检索的存储层」做小做对：
+
+- 多集合，每个集合自己声明 `dim` 与 `metric`；
+- 写入是追加日志，删了只是墓碑，`compact` 才真正重写；
+- 检索分两步，**近似就是近似**——`exact:false` 时明说「只扫了 1/15 个簇」；
+- 同一 `opId` 重复提交不会重复写（网络重试/agent 重放安全）；
+- 坏行跳过并计数，一行坏 JSON 不会毁掉整个集合。
+
+## 它不是什么？（边界写死）
+
+| 想做的事 | 本包的态度 |
+|---|---|
+| 本地存向量、按元数据过滤检索、删、压缩 | ✅ |
+| 接 hnswlib / faiss / 任何 ANN 库 | ❌ 不接：零依赖，粗筛用内存 k-means |
+| 联网、调嵌入 API | ❌ 不做：向量由你（或别的插件）生成后传进来 |
+| BM25 / 关键词混合检索 | ❌ 不是本包：那是 `dsh-vector-kit` 的活 |
+| 把近似结果说成精确结果 | ❌ 绝不：`exact` 只有候选覆盖全量时才为 true |
+| 维度不一致时截断/补零 | ❌ 绝不：直接 `dimension_mismatch` 拒绝 |
+
+## 怎么装、怎么用？
+
+```sh
+dsh plugin --profile web add dsh-vectordb
+```
+
+装好后在 DSH 会话里直接说，模型会调 `dsh_vectordb`：
+
+```text
+建一个 768 维的向量集合 docs，用 cosine
+把这批 chunk 写进 docs（带 lang 元数据）
+在 docs 里找最像这段的 5 条，只要 lang=zh
+这条为什么是近似结果？扫了多少条、候选多少
+把删掉的向量压掉，看看文件小了多少
+```
+
+不装插件也能用 CLI（零依赖，只要 Node ≥22）：
+
+```sh
+node lib/cli.js create  --collection docs --dim 768 --metric cosine --base-dir ./data
+node lib/cli.js upsert  --collection docs --items-file chunks.json --op-id ingest-1 --base-dir ./data
+node lib/cli.js search  --collection docs --query '[0.1,0.2,...]' --top-k 5 --filter '{"lang":"zh"}' --base-dir ./data
+node lib/cli.js delete  --collection docs --ids a,b --base-dir ./data
+node lib/cli.js compact --collection docs --base-dir ./data
+node lib/cli.js stats   --collection docs --base-dir ./data
+```
+
+退出码：`0` 成功｜`1` 参数错误｜`2` 集合不存在或 IO 失败｜`3` 输入被拒（维度/度量/向量/元数据）。
+
+## 六个动作
+
+| 动作 | 做什么 | 关键返回 |
+|---|---|---|
+| `create` | 建集合，声明 `dim` + `metric` | `created` / `dim` / `metric` |
+| `upsert` | 写 chunk：`id` + 向量 + 元数据 + 可选摘要 | `applied` / `seqStart..seqEnd` / `idempotent` |
+| `search` | 两步检索（top-k + 元数据过滤） | `results` + **`scanned` / `candidates` / `returned` / `exact`** |
+| `delete` | 墓碑删除（日志里留 delete 记录） | `tombstoned` / `missing` / `live` |
+| `compact` | 物理清理并重写日志 | `kept` / `removedOps` / `beforeBytes` → `afterBytes` |
+| `stats` | 概览（含坏行数、opId 历史长度） | `live` / `tombstones` / `ops` / `badLines` |
+
+## 两步检索口径（exact 判据写死）
+
+```
+search(query):
+  1) 过滤：先按元数据把候选集缩到 filtered
+  2) 如果 filtered ≤ exactThreshold（默认 64）→ 暴力扫全量，mode=brute，exact=true
+  3) 否则：k = √filtered 个 k-means 质心（确定性初始化，同数据同结果）
+     粗筛 = 扫离 query 最近的 nprobe 个质心（默认 1）
+     精确重排 = 对候选算真距离，取 top-k
+     exact = (candidates == filtered)   ← 只有覆盖全量才为 true
+```
+
+返回里永远有：
+
+- `scanned`：集合里存活多少条（过滤前）；
+- `filtered`：过滤后多少条；
+- `candidates`：粗筛后真正算过距离的多少条；
+- `returned`：实际返回几条；
+- `exact`：**候选是否覆盖了 filtered 的全部**；
+- `note`：人话解释这次为什么是（或不是）精确的。
+
+`nprobe = k` 时覆盖全量 → `exact:true`；小集合默认暴力扫 → `exact:true`；其余一律 `exact:false`。近似的 `note` 会直接写「**这是近似结果**：真近邻可能在没扫的簇里」。
+
+## 持久化、墓碑与幂等
+
+- 目录：`<baseDir>/collections/<名字>/{vectors.jsonl, meta.json, .lock}`；`baseDir` 默认 `$DSH_VECTORDB_DIR` 或 `<DSH_HOME>/vectordb`。
+- `vectors.jsonl` 只追加：`upsert` / `delete` 各一行；读时从头重放（重启即可重建）。
+- 删除是**墓碑**：`live` 减一、`tombstones` 加一，日志里仍在；`compact` 才物理重写。
+- `meta.json` 原子写（临时文件 → fsync → rename），记录 `dim` / `metric` / `nextSeq` / 已应用的 `opId`。
+- 写路径加锁（`open(..., 'wx')` 独占创建 `.lock`，陈旧 15s 可接管）；**`search` / `stats` 不加锁、不写盘**。
+- 坏行（坏 JSON / 形状不对）跳过并计数，`stats.badLines` 能看到。
+- 同一 `opId` 重复提交 → `idempotent:true`、`applied:0`，不再写第二遍。
+
+## 与 dsh-vector-kit 怎么分工？
+
+| | `dsh-vector-kit` | `dsh-vectordb`（本包） |
+|---|---|---|
+| 检索 | BM25 + 余弦混合 | **纯向量 + 两步检索**（粗筛 + 精确重排） |
+| 索引 | 倒排索引 + 可选向量 | k-means 质心（内存，确定性） |
+| 返回诚实度 | 混合分 | `scanned/candidates/returned/exact` |
+| 适合 | 关键词 + 语义混合召回 | 「我要一个真向量库，并且知道它近不近似」 |
+
+## 事实
+
+- **6 个动作**：create / upsert / search / delete / compact / stats；**2 个度量**：cosine、l2（其它 `unsupported_metric`）
+- **exact 判据 3 条**：过滤后 ≤64 条 → brute/exact；`nprobe=k` → 覆盖全量/exact；其余 → two-step/近似
+- **测试 53 条 / 8 个测试文件**：建集合、维度拒绝、度量拒绝、幂等 opId、两度量排序、元数据过滤、近似 `exact:false`（300 条）、小集合 `exact:true`、墓碑不返回、compact 变小且结果一致、重启重建、坏行跳过、只读快照、命名同源、CLI 四档退出码、插件契约
+- **源码 1890 行**（`plugin.mjs` + `lib/` 共 10 个文件），**零运行时依赖**
+- `npm pack --dry-run`：17 文件 / 79 KB / tarball 26 KB
+
+## 已知局限
+
+- **不做 ANN 索引**：粗筛是内存 k-means，每次查询现算；数据大时比 hnswlib 慢。
+- **粗筛会漏真近邻**：`exact:false` 时结果只是「候选里的最优」；要精确就调大 `nprobe`/`k` 或用小集合模式。
+- **写路径串行**：同机文件锁，不是分布式锁；多机写同一目录没有保证。
+- **向量以 JSON 数字存**：比二进制大 2-4 倍，没有量化/压缩。
+- **过滤能力有限**：元数据子集相等 / 数组包含；不支持范围、表达式或全文检索。
+- **删除不立即回收**：墓碑要 `compact` 才真正消失。
+- **不生成嵌入**：向量由调用方提供，本包不联网调模型。
+
+## 开发与自检
 
 ```sh
-dsh plugin --profile desktop add dsh-vectordb
+node --test test/            # 或 node --test test/*.test.mjs
+npm run check                # 包结构 + 语法 + 命名四处同源 + 宿主 schema + 临时目录冒烟
+npm run verify:install       # 走宿主安装代码路径装进临时 profile（DSH_HOME 指向 mkdtemp）
+node ../dsh-geo-audit/lib/cli.js --file README.md   # 用 GEO 插件审这份 README
 ```
 
 ## 许可

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# dsh-vectordb：往宿主挂一个 host 侧插件，注册模型可调用工具 dsh_vectordb。
+# 行 id 与包名同名（三个名字同源），避免「行 id ≠ 包名」两个命名空间带来的重复注册。
+- insert:
+    - id: dsh-vectordb
+      name: dsh-vectordb
+      config:
+        # 数据根；留空 = $DSH_VECTORDIR 或 <DSH_HOME>/vectordb
+        baseDir: ''
+        # 新建集合的默认度量（cosine | l2）
+        metric: cosine
+        # search 默认返回条数
+        topK: 10
+        # 粗筛默认扫几个质心
+        nprobe: 1
+        # 小集合暴力扫全量的阈值
+        exactThreshold: 64

package/dsh-plugin.naming.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "policy": "dsh-plugin-naming/v1",
+  "plugin": {
+    "namespace": "hfshfg",
+    "name": "vectordb",
+    "coordinate": "hfshfg/vectordb",
+    "packageName": "dsh-vectordb"
+  },
+  "names": {
+    "pluginNames": [
+      "dsh-vectordb"
+    ],
+    "loaderIds": [
+      "dsh-vectordb"
+    ],
+    "services": [],
+    "tools": [
+      "dsh_vectordb"
+    ],
+    "commands": [],
+    "skills": [],
+    "skillProviders": [],
+    "events": [],
+    "settingsNamespaces": [],
+    "routes": []
+  }
+}

package/lib/cli.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * `dsh-vectordb` 命令行：建集合 / 写向量 / 两步检索 / 墓碑删除 / 压缩 / 概览。
+ *
+ * 约定：
+ * - 正常结果写 stdout，错误写 stderr；`--json` 时 stdout 只有一个对象
+ * - 退出码：0 成功｜1 参数错误｜2 集合不存在或 IO 失败｜3 输入被拒（维度/度量/向量/元数据）
+ */
+
+import { readFileSync, realpathSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ACTIONS, runAction } from './engine.mjs'
+import { describeError } from './errors.mjs'
+import { renderJson, renderText } from './format.mjs'
+import { VERSION } from './version.mjs'
+
+const USAGE = `dsh-vectordb ${VERSION} —— 本地纯向量存储与两步检索（零依赖、不联网）
+
+用法：
+  node lib/cli.js create   --collection <名> --dim <n> [--metric cosine|l2] [--base-dir <目录>]
+  node lib/cli.js upsert   --collection <名> --items-file <json 文件> [--op-id <幂等键>]
+  node lib/cli.js search   --collection <名> --query <向量> [--top-k 10] [--filter <json>] [--nprobe 1] [--k <簇数>]
+  node lib/cli.js delete   --collection <名> --ids <id,id...> [--op-id <幂等键>]
+  node lib/cli.js compact  --collection <名>
+  node lib/cli.js stats    --collection <名>
+
+选项：
+  --collection <名>        集合名（字母/数字/_/-，≤63）
+  --base-dir <目录>        数据根（默认 $DSH_VECTORDIR 或 <DSH_HOME>/vectordb）
+  --dim <n>                create 用：向量维度（1..4096）
+  --metric <m>             create 用：cosine（默认）| l2；其它一律 unsupported_metric
+  --items-file <路径>      upsert 用：JSON 数组，每项 {id, vector, metadata?, text?}
+  --query <向量>           search 用：JSON 数组，或 1,2,3 逗号分隔
+  --top-k <n>              search 用：返回几条（默认 10）
+  --filter <json>          search 用：元数据子集匹配，如 {"lang":"zh"}
+  --nprobe <n>             search 用：粗筛扫几个质心（默认 1；越大越准越慢）
+  --k <n>                  search 用：强制质心数（默认 √n）
+  --exact-threshold <n>    search 用：≤ 这个数就暴力扫全量（默认 64）
+  --ids <id,...>           delete 用：要墓碑删除的 id
+  --op-id <字符串>         写操作幂等键：同一个 opId 重复提交不会重复写
+  --json                   输出 JSON（stdout 只有一个对象）
+  --brief                  文本模式少说两句
+  --help, -h               显示本帮助
+  --version, -v            只打印版本
+
+退出码：0 成功｜1 参数错误｜2 集合不存在/IO｜3 输入被拒（维度/度量/向量/元数据）`
+
+/** 参数错误（退出码 1）。 */
+class UsageError extends Error {}
+
+/**
+ * 解析 argv。
+ * @param {string[]} argv 参数
+ * @returns {{action:string|null,flags:object}} 结果
+ */
+function parseArgs(argv) {
+  const flags = { json: false, brief: false }
+  let action = null
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index]
+    const take = (name) => {
+      const next = argv[++index]
+      if (next === undefined) throw new UsageError(`${name} 需要一个值`)
+      return next
+    }
+    const int = (name) => {
+      const value = Number(take(name))
+      if (!Number.isInteger(value)) throw new UsageError(`${name} 需要整数`)
+      return value
+    }
+    switch (arg) {
+      case '--help': case '-h': flags.help = true; break
+      case '--version': case '-v': flags.version = true; break
+      case '--json': flags.json = true; break
+      case '--brief': flags.brief = true; break
+      case '--collection': case '-c': flags.collection = take('--collection'); break
+      case '--base-dir': flags.baseDir = take('--base-dir'); break
+      case '--dim': flags.dim = int('--dim'); break
+      case '--metric': flags.metric = take('--metric'); break
+      case '--items-file': flags.itemsFile = take('--items-file'); break
+      case '--query': flags.query = take('--query'); break
+      case '--top-k': flags.topK = int('--top-k'); break
+      case '--filter': flags.filter = take('--filter'); break
+      case '--nprobe': flags.nprobe = int('--nprobe'); break
+      case '--k': flags.k = int('--k'); break
+      case '--exact-threshold': flags.exactThreshold = int('--exact-threshold'); break
+      case '--ids': flags.ids = take('--ids'); break
+      case '--op-id': flags.opId = take('--op-id'); break
+      default:
+        if (arg.startsWith('--')) throw new UsageError(`未知参数 ${arg}`)
+        if (action !== null) throw new UsageError(`一次只能跑一个动作，多了 ${arg}`)
+        if (!ACTIONS.includes(arg)) throw new UsageError(`不认识的动作 ${arg}（可选：${ACTIONS.join(' / ')}）`)
+        action = arg
+    }
+  }
+  return { action, flags }
+}
+
+/**
+ * 解析向量参数：JSON 数组或逗号分隔。
+ * @param {string} raw 原值
+ * @returns {number[]} 向量
+ */
+function parseVector(raw) {
+  const text = String(raw).trim()
+  try {
+    const parsed = JSON.parse(text)
+    if (Array.isArray(parsed)) return parsed.map((value) => Number(value))
+  } catch {
+    // 落到逗号分隔
+  }
+  return text.split(',').map((part) => Number(part.trim()))
+}
+
+/**
+ * 解析 JSON 参数。
+ * @param {string} raw 原值
+ * @param {string} name 名称
+ * @returns {object} 对象
+ */
+function parseJsonObject(raw, name) {
+  try {
+    const parsed = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('不是对象')
+    return parsed
+  } catch (error) {
+    throw new UsageError(`${name} 需要 JSON 对象：${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/**
+ * 读 items 文件。
+ * @param {string} file 路径
+ * @returns {Array<object>} 条目
+ */
+function readItems(file) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    throw new UsageError(`读不了 --items-file：${error instanceof Error ? error.message : String(error)}`)
+  }
+  try {
+    const parsed = JSON.parse(text)
+    if (!Array.isArray(parsed)) throw new Error('顶层必须是数组')
+    return parsed
+  } catch (error) {
+    throw new UsageError(`--items-file 不是合法 JSON 数组：${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/**
+ * 错误码 → 退出码。
+ * @param {string} code 错误码
+ * @returns {number} 退出码
+ */
+function exitCodeOf(code) {
+  if (code === 'collection_not_found' || code === 'read_failed' || code === 'lock_failed' || code === 'lock_timeout') return 2
+  if (['dimension_mismatch', 'unsupported_metric', 'invalid_vector', 'invalid_metadata', 'invalid_text', 'invalid_dim', 'invalid_id', 'invalid_item', 'empty_batch', 'batch_too_large', 'collection_exists'].includes(code)) return 3
+  return 1
+}
+
+/**
+ * 组装动作参数。
+ * @param {string} action 动作
+ * @param {object} flags 参数
+ * @returns {object} 动作参数
+ */
+function argsOf(action, flags) {
+  const base = {
+    action,
+    collection: flags.collection,
+    base_dir: flags.baseDir,
+    op_id: flags.opId,
+  }
+  switch (action) {
+    case 'create': return { ...base, dim: flags.dim, metric: flags.metric }
+    case 'upsert': {
+      if (!flags.itemsFile) throw new UsageError('upsert 需要 --items-file <json>')
+      return { ...base, items: readItems(flags.itemsFile) }
+    }
+    case 'search': {
+      if (!flags.query) throw new UsageError('search 需要 --query <向量>')
+      return {
+        ...base,
+        query: parseVector(flags.query),
+        top_k: flags.topK,
+        filter: flags.filter === undefined ? undefined : parseJsonObject(flags.filter, '--filter'),
+        nprobe: flags.nprobe,
+        k: flags.k,
+        exact_threshold: flags.exactThreshold,
+      }
+    }
+    case 'delete': {
+      if (!flags.ids) throw new UsageError('delete 需要 --ids <id,...>')
+      return { ...base, ids: flags.ids.split(',').map((id) => id.trim()).filter(Boolean) }
+    }
+    default: return base
+  }
+}
+
+/**
+ * CLI 主流程。
+ * @param {string[]} argv 参数
+ * @returns {Promise<number>} 退出码
+ */
+async function main(argv) {
+  let parsed
+  try {
+    parsed = parseArgs(argv)
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${USAGE}\n`)
+    return 1
+  }
+  const { action, flags } = parsed
+  if (flags.help) { process.stdout.write(`${USAGE}\n`); return 0 }
+  if (flags.version) { process.stdout.write(`${VERSION}\n`); return 0 }
+  if (!action) {
+    process.stderr.write(`需要一个动作（${ACTIONS.join(' / ')}）\n\n${USAGE}\n`)
+    return 1
+  }
+  if (!flags.collection) {
+    process.stderr.write('缺少 --collection <集合名>\n')
+    return 1
+  }
+
+  try {
+    const args = argsOf(action, flags)
+    const report = await runAction({}, args)
+    process.stdout.write(flags.json
+      ? `${renderJson(report)}\n`
+      : `${renderText(report, { detail: flags.brief ? 'brief' : 'full' })}\n`)
+    return 0
+  } catch (error) {
+    const info = describeError(error)
+    if (info.code === 'invalid_dim' || info.code === 'invalid_name' || info.code === 'empty_batch') {
+      // 这些是动作参数错，按参数错误处理
+      process.stderr.write(`✗ ${info.message}\n`)
+      return 1
+    }
+    if (flags.json) process.stderr.write(`${JSON.stringify({ ok: false, error: info }, null, 2)}\n`)
+    else {
+      process.stderr.write(`✗ ${info.message}\n`)
+      if (info.hint) process.stderr.write(`  → ${info.hint}\n`)
+    }
+    return exitCodeOf(info.code)
+  }
+}
+
+/**
+ * 是否被直接执行（被 import 时不跑）。
+ * @returns {boolean} 是否直接执行
+ */
+function isInvokedDirectly() {
+  const entry = process.argv[1]
+  if (!entry) return false
+  const self = fileURLToPath(import.meta.url)
+  try {
+    return realpathSync(entry) === realpathSync(self)
+  } catch {
+    return resolve(entry) === self
+  }
+}
+
+if (isInvokedDirectly()) {
+  main(process.argv.slice(2))
+    .then((code) => { process.exitCode = code })
+    .catch((error) => {
+      process.stderr.write(`✗ 未捕获异常：${error instanceof Error ? error.stack ?? error.message : String(error)}\n`)
+      process.exitCode = 1
+    })
+}
+
+export { main, parseArgs }

package/lib/cluster.mjs

@@ -0,0 +1,120 @@
+/**
+ * 粗筛用的**确定性**聚类（不引 ANN 库：hnswlib/faiss 都要装依赖）。
+ *
+ * 做法：k-means，k 默认 √n；初始化不用随机数（按 id 排序后等距取点），保证同一份数据
+ * 每次算出的质心一致——否则「同一查询两次结果不同」会让人无法复现。
+ *
+ * 检索时先挑离查询最近的 nprobe 个质心（粗筛），只对它们的成员做真距离（精确重排）。
+ * 这就是「两步检索」的全部：**粗筛可能漏掉真近邻**，所以返回值必须带 exact 标记。
+ */
+
+import { METRICS, scoreOf, unit } from './vector.mjs'
+
+/** 默认质心数：√n（上取整）。 */
+export function defaultK(n) {
+  if (!Number.isFinite(n) || n <= 0) return 1
+  return Math.max(1, Math.ceil(Math.sqrt(n)))
+}
+
+/**
+ * 建索引（确定性 k-means）。
+ * @param {Array<{id:string,vector:number[]}>} records 记录（按 id 排序后传入）
+ * @param {{k?:number,metric?:string,iterations?:number}} [options] 选项
+ * @returns {{k:number,metric:string,dim:number,centroids:number[][],assignments:Map<string,number>,sizes:number[],iterations:number}} 索引
+ */
+export function buildIndex(records, options = {}) {
+  const metric = METRICS.includes(options.metric) ? options.metric : 'cosine'
+  const n = records.length
+  const dim = records[0]?.vector.length ?? 0
+  const k = Math.min(Math.max(1, Number.isInteger(options.k) ? options.k : defaultK(n)), Math.max(1, n))
+  const iterations = Math.min(Math.max(1, Number.isInteger(options.iterations) ? options.iterations : 8), 32)
+
+  if (n === 0) {
+    return { k: 0, metric, dim, centroids: [], assignments: new Map(), sizes: [], iterations: 0 }
+  }
+
+  // 确定性初始化：按 id 排序后等距取点
+  let centroids = []
+  for (let index = 0; index < k; index++) {
+    const position = Math.min(n - 1, Math.floor(((index + 0.5) * n) / k))
+    centroids.push(records[position].vector.slice())
+  }
+
+  const assignments = new Map()
+  let currentIterations = 0
+  for (let iteration = 0; iteration < iterations; iteration++) {
+    currentIterations = iteration + 1
+    let changed = false
+    for (const record of records) {
+      const best = nearestCentroid(record.vector, centroids, metric)
+      const previous = assignments.get(record.id)
+      if (previous !== best) {
+        assignments.set(record.id, best)
+        changed = true
+      }
+    }
+    const next = centroids.map(() => new Array(dim).fill(0))
+    const counts = new Array(centroids.length).fill(0)
+    for (const record of records) {
+      const cluster = assignments.get(record.id)
+      if (cluster === undefined) continue
+      counts[cluster] += 1
+      const target = next[cluster]
+      for (let index = 0; index < dim; index++) target[index] += record.vector[index]
+    }
+    for (let cluster = 0; cluster < next.length; cluster++) {
+      if (counts[cluster] === 0) continue
+      const centroid = next[cluster].map((value) => value / counts[cluster])
+      next[cluster] = metric === 'cosine' ? unit(centroid) : centroid
+    }
+    centroids = next
+    if (!changed) break
+  }
+
+  const sizes = new Array(centroids.length).fill(0)
+  for (const record of records) {
+    const cluster = assignments.get(record.id)
+    if (cluster !== undefined) sizes[cluster] += 1
+  }
+  return { k, metric, dim, centroids, assignments, sizes, iterations: currentIterations }
+}
+
+/**
+ * 找最近的质心。
+ * @param {number[]} vector 向量
+ * @param {number[][]} centroids 质心
+ * @param {string} metric 度量
+ * @returns {number} 质心下标
+ */
+function nearestCentroid(vector, centroids, metric) {
+  let bestIndex = 0
+  let bestScore = -Infinity
+  for (let index = 0; index < centroids.length; index++) {
+    const score = scoreOf(metric, vector, centroids[index]).better
+    if (score > bestScore) {
+      bestScore = score
+      bestIndex = index
+    }
+  }
+  return bestIndex
+}
+
+/**
+ * 粗筛：挑 nprobe 个离查询最近的质心。
+ * @param {number[]} query 查询向量
+ * @param {{centroids:number[][],metric:string}} index 索引
+ * @param {{nprobe?:number}} [options] 选项
+ * @returns {{probed:number[],nprobe:number,probeAll:boolean}} 粗筛结果
+ */
+export function probeClusters(query, index, options = {}) {
+  const total = index.centroids.length
+  if (total === 0) return { probed: [], nprobe: 0, probeAll: true }
+  const requested = Number.isInteger(options.nprobe) && options.nprobe > 0 ? options.nprobe : 1
+  const nprobe = Math.min(requested, total)
+  const ranked = index.centroids
+    .map((centroid, position) => ({ position, score: scoreOf(index.metric, query, centroid).better }))
+    .sort((a, b) => b.score - a.score || a.position - b.position)
+    .slice(0, nprobe)
+    .map((item) => item.position)
+  return { probed: ranked, nprobe, probeAll: nprobe >= total }
+}