CLI

安装 npm 包后，通过 npx indexbind ... 或你包管理器的本地 bin 运行公共 CLI。

主要命令：

npx indexbind build [input-dir] [output-file] [--backend <hashing|model-id>]
npx indexbind build-bundle [input-dir] [output-dir] [--backend <hashing|model-id>]
npx indexbind update-cache [input-dir] [cache-file] [--backend <hashing|model-id>] [--git-diff] [--git-base <rev>]
npx indexbind export-artifact <output-file> [--cache-file <path>]
npx indexbind export-bundle <output-dir> [--cache-file <path>]
npx indexbind inspect <artifact-file>
npx indexbind search <artifact-file> <query> [flags]
npx indexbind benchmark <artifact-file> <queries-json>

示例：

npx indexbind build ./docs
npx indexbind build . ./index.sqlite --backend hashing
npx indexbind build-bundle ./docs
npx indexbind update-cache ./docs --git-diff
npx indexbind export-artifact ./index.sqlite --cache-file ./docs/.indexbind/build-cache.sqlite
npx indexbind export-bundle ./index.bundle --cache-file ./docs/.indexbind/build-cache.sqlite
npx indexbind inspect ./docs/.indexbind/index.sqlite
npx indexbind search ./docs/.indexbind/index.sqlite "rust guide"
npx indexbind search ./docs/.indexbind/index.sqlite "rust guide" --text
npx indexbind benchmark ./docs/.indexbind/index.sqlite fixtures/benchmark/basic/queries.json

输出模式

命令默认输出 JSON。

当你想要面向终端的紧凑摘要时，加 --text：

npx indexbind inspect ./docs/.indexbind/index.sqlite --text
npx indexbind search ./docs/.indexbind/index.sqlite "rust guide" --text

这个默认值是有意为之，让智能体、shell 脚本与 CI 任务无需额外解析即可消费 CLI 输出。

默认路径规则：

省略 input-dir 表示当前目录
构建命令省略 output-file、output-dir 或 cache-file 时写入 <input-dir>/.indexbind/
export-* 仍要求显式输出路径；省略 --cache-file 时使用 ./.indexbind/build-cache.sqlite

扫描默认值：

忽略隐藏文件与目录
尊重嵌套的 .gitignore 规则
忽略常见的生成物或依赖目录，例如 node_modules/、target/、dist/ 与 build/

索引级约定文件：

indexbind.build.js 与 indexbind.search.js 只从确切的 input-dir 或工件 sourceRoot 自动发现
如果你索引 ./docs，把它们放在 ./docs/，即 ./docs/.indexbind/ 旁边
它们只影响那个被索引的根；不存在仓库根目录或当前工作目录回退

嵌入后端选择：

传入 --backend hashing
或用 --backend <model-id> 传入任意 model2vec 模型 id

省略 --backend 时使用当前默认后端。

增量缓存流程

推荐顺序：

update-cache 刷新可变构建缓存
export-artifact 写出全新 SQLite 工件
需要时用 export-bundle 写出全新规范化 bundle

update-cache 默认做全量目录扫描。加 --git-diff 用 Git 作为变更检测快速路径。当你想相对特定修订做 diff 且复用同一缓存时，加 --git-base <rev>。

构建约定

可选的 indexbind.build.js 导出可以扩展默认目录扫描器：

export function includeDocument(relativePath, ctx) {
  return true;
}

export async function transformDocument(document, ctx) {
  return document;
}

transformDocument() 接收 frontmatter 解析之后的默认规范化文档形态。它是推导 canonicalUrl、注入元数据或规范化标题/摘要的合适位置，且不需要替换扫描器。

搜索约定

可选的 indexbind.search.js 导出可以为 indexbind search 定义默认 profile：

export const profiles = {
  default: {
    metadata: {
      is_default_searchable: 'true',
    },
    scoreAdjustment: {
      metadataNumericMultiplier: 'directory_weight',
    },
  },
};

export function transformQuery(query, ctx) {
  return { query };
}

先应用 profiles.default，然后显式 CLI 标志覆盖它。transformQuery() 只改写查询字符串。

搜索标志

用 search 在已构建的 SQLite 工件上实验检索设置。

支持的标志：

--top-k <n>
--mode <hybrid|vector|lexical>
--reranker embedding-v1|heuristic-v1
--candidate-pool-size <n>
--relative-path-prefix <prefix>
--metadata key=value（可重复）
--score-adjust-metadata-multiplier <field>
--min-score <float>
--text

示例：

npx indexbind search ./docs/.indexbind/index.sqlite "rust guide" \
  --top-k 5 \
  --mode vector \
  --reranker heuristic-v1 \
  --candidate-pool-size 25 \
  --min-score 0.05 \
  --text

--mode vector 表示仅向量检索。
--mode lexical 表示仅词法检索。

触发示例

一种简单的本地钩子模式是在分支变更后更新缓存：

#!/usr/bin/env bash
set -euo pipefail

npx indexbind update-cache ./docs --git-diff
npx indexbind export-artifact ./index.sqlite --cache-file ./docs/.indexbind/build-cache.sqlite

这只是一个适配器示例。缓存逻辑仍在共享的增量引擎里，因此同一流程也可以由智能体脚本、任务运行器或文件 watcher 调用。