采用示例

这些示例展示 indexbind 在更大系统中的位置。

它们的模式是一致的：

宿主应用决定文档集合是什么
indexbind 构建或更新检索工件
宿主应用仍拥有路由、过滤、排序策略与渲染

带浏览器搜索的文档站点

当你希望文档站点把搜索工件随站点一起交付时，使用这种形态。

典型流程：

从文档语料构建规范化 bundle
把 bundle 与站点一起发布
在浏览器或 worker 运行时中加载

npx indexbind build-bundle ./docs ./public/index.bundle

import { openWebIndex } from 'indexbind/web';

const index = await openWebIndex('/index.bundle');
const hits = await index.search('canonical bundle');

宿主应用仍然拥有：

路由生成
URL 结构
摘要渲染
UI 状态与过滤器
叠加在上层的任何宿主特定排序规则

这与 indexbind 文档站点今天的组织方式很接近。

发布或博客系统

当你已经有一套规范化内容流水线、希望检索留在流水线内部时，使用这种形态。

典型流程：

在宿主应用中解析 frontmatter 与 markdown
把规范化后的文档传入 indexbind/build
导出与最终部署目标匹配的运行时工件

import {
  buildCanonicalBundle,
} from 'indexbind/build';

await buildCanonicalBundle('./dist/search.bundle', [
  {
    relativePath: 'posts/retrieval.md',
    canonicalUrl: '/posts/retrieval',
    title: 'Retrieval Notes',
    summary: 'How the publishing pipeline builds search artifacts.',
    content: '# Retrieval Notes\n\nBuild artifacts during publish.',
    metadata: {
      section: 'blog',
      visibility: 'public',
    },
  },
], {
  embeddingBackend: 'hashing',
});

当宿主已经拥有以下能力时，这种形态很合适：

frontmatter 解析
规范 URL
分类体系
发布状态
产品级排序先验

当博客或发布系统希望搜索只是构建产物之一、而不是一个独立搜索服务时，这也是个好选择。

面向基本默认仓库的索引级约定

当默认目录扫描器已经够用、只是某个被索引的根目录还需要少量仓库特定行为时，使用这种形态。

典型流程：

继续使用 indexbind build、build-bundle 或 update-cache
把 indexbind.build.js 放在被索引根目录旁边
当 CLI 或 Node 搜索需要默认 profile 时，把 indexbind.search.js 也放在那里

docs/
  indexbind.build.js
  indexbind.search.js
  .indexbind/

indexbind.build.js 示例：

export function includeDocument(relativePath) {
  return relativePath !== 'archive/notes.md';
}

export function transformDocument(document) {
  return {
    ...document,
    canonicalUrl: `https://example.com/${document.relativePath.replace(/\.md$/i, '')}`,
    metadata: {
      ...(document.metadata ?? {}),
      is_default_searchable: 'true',
      directory_weight: 1.0,
    },
  };
}

indexbind.search.js 示例：

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

export function transformQuery(query) {
  return {
    query: query.replace(/btc/ig, 'bitcoin'),
  };
}

当宿主只需要以下能力时，这种形态很合适：

从默认扫描中跳过少数文件
推导 canonicalUrl
注入宿主元数据，例如 source_root、content_kind、is_default_searchable 或 directory_weight
定义默认的 CLI/Node 搜索 profile
增加轻量的查询别名扩展

当仓库不需要完整的自定义构建脚本、但零配置默认又不够时，这是恰当的中间地带。

混合本地知识库的自定义索引构建器

当宿主应用希望精确决定扫描哪些目录、如何分类文档、以及把哪些元数据或权重规则写进索引时，使用这种形态。

典型流程：

遍历宿主特定的内容根
把每个 markdown 文件规范化为 BuildDocument
推断元数据，例如来源根、内容类型、可见性或目录权重
把规范化后的文档传入 indexbind/build

import { buildCanonicalBundle } from 'indexbind/build';

const documents = [
  {
    docId: 'public/post-a/README.md',
    sourcePath: '/workspace/public/post-a/README.md',
    relativePath: 'public/post-a/README.md',
    canonicalUrl: 'https://example.com/post-a/',
    title: 'Post A',
    summary: 'Host-defined summary for workspace search.',
    content: '# Post A\n\nHost-controlled markdown content for the public post.',
    metadata: {
      source_root: 'public',
      content_kind: 'public_post',
      is_default_searchable: true,
      directory_weight: 1.0,
    },
  },
  {
    docId: 'research/notes/layer2.md',
    sourcePath: '/workspace/research/notes/layer2.md',
    relativePath: 'research/notes/layer2.md',
    title: 'Layer2 Notes',
    content: '# Layer2 Notes\n\nHost-controlled markdown content for research search.',
    metadata: {
      source_root: 'research',
      content_kind: 'research',
      is_default_searchable: true,
      directory_weight: 0.92,
    },
  },
];

await buildCanonicalBundle('./dist/workspace.bundle', documents, {
  embeddingBackend: 'model2vec',
  sourceRootId: 'workspace',
  sourceRootPath: process.cwd(),
});

当宿主希望拥有以下控制权时，这种形态很合适：

多根目录选择
frontmatter 解析与自定义标题、摘要规则
内容分类，例如 public_post、draft、research 或 archive_doc
元数据驱动的排序提示，例如目录权重或可见性标志
分离的搜索 profile，例如默认搜索与穷尽搜索

这与 workspace 项目使用 indexbind 的方式很接近：宿主先规范化异构内容，再把受控的文档集交给 indexbind/build。

本地知识库或智能体工作区

当文档反复变化、宿主希望增量触发索引时，使用这种形态。

典型流程：

刷新构建缓存
从缓存导出全新运行时工件
让宿主工具在本地打开新工件

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

import { openIndex } from 'indexbind';

const index = await openIndex('./workspace.sqlite');
const hits = await index.search('incremental indexing');

适合：

宿主定义工作流的本地知识库
智能体驱动的文档刷新
git 钩子或任务运行器触发的重建
希望内嵌检索层、而不是可变本地存储搜索产品的产品

五种形态之间如何选

运行时目标以浏览器或 worker 为主时，优先文档站点模式。
宿主已有结构化内容流水线时，优先发布流水线模式。
默认扫描器已接近需求、只需给一个被索引根挂少量宿主策略时，优先索引级约定模式。
宿主需要在索引前对混合本地内容分类时，优先自定义构建器模式。
增量重建与本地 Node 查询比浏览器分发更重要时，优先本地知识库模式。

如果需要完整的决策框架，回到如何选择 indexbind。想看本地参考数据与当前自用说明，参见基准测试与案例。