typesense

typesense — 可安装的容错拼写搜索环境

Typesense 是一款快速、可容忍拼写错误的开源搜索引擎，是 Algolia 的替代方案，也是更易用的 ElasticSearch 替代方案。它是一个无需运行时依赖的单一 C++ 二进制文件，专为低延迟（<50ms）即时搜索而设计。此技能是以路由为先的封装：选择如何运行服务、连接客户端、建模数据，并推动搜索、UI 和生产环境加固。

何时使用此技能

• 用户想为网站、应用、目录、文档或产品浏览体验搭建搜索后端
• 用户想安装或运行 Typesense（二进制文件、Docker 或 Typesense Cloud）
• 用户需要容错拼写、分面/过滤、地理搜索、排序、分组、同义词、内容策划、范围受限的 API 密钥或联邦多重搜索
• 用户想从 Algolia 或 Elasticsearch 迁移到可自托管或托管的开源引擎
• 用户想在 Typesense 前方或周边搭建 InstantSearch.js UI 或 Raft HA 集群

何时不使用此技能

• 用户需要 LLM 跟踪/评估可观测性（幻觉、提示词评分）→ 使用 opik / langsmith
• 用户需要在代码仓库中为 Agent 进行令牌高效的代码搜索 → 使用 semble
• 用户需要通用服务仪表板/运行时间告警（非搜索遥测）→ 使用 monitoring-observability
• 用户需要专为嵌入向量打造的向量数据库——Typesense 支持向量和混合搜索，但在极大规模下，专用存储可能更适合纯 ANN；请先确认工作负载

先决条件

要求	说明
Docker（推荐）	通过官方镜像实现最简单的本地和生产环境部署路径
或二进制文件运行主机	Linux（x86-64）/ macOS 二进制软件包，来自 typesense.org/downloads
或 Typesense Cloud	零运维托管集群（按小时和带宽固定收费，而非按记录收费）
API 客户端	官方支持 Python / JS / PHP / Ruby；社区支持 Go / Dart / C#
API 密钥	在服务启动时设置（--api-key）；为每个租户生成范围受限的密钥

操作说明

步骤 1 — 选择服务模式

模式	适用场景	入口点
Docker（推荐）	从本地开发到生产环境，单条命令即可	docker run typesense/typesense …
二进制文件	裸机环境/无 Docker	从 https://typesense.org/downloads 下载
Typesense Cloud	零运维托管、高可用	https://cloud.typesense.org

本地 Docker 服务（固定使用实际版本标签，并设置强密钥）：

docker run -p 8108:8108 -v /tmp/typesense-data:/data \
  typesense/typesense:27.1 --data-dir /data --api-key=CHANGE_ME_STRONG_KEY

此技能附带 scripts/install.sh，可一键启动本地 Docker 服务并安装 Python 客户端。

步骤 2 — 安装 API 客户端

pip install typesense        # Python (official)
npm install typesense        # JS/TS (official)
# PHP: composer require typesense/typesense-php   Ruby: gem install typesense

优先使用官方客户端，而非原始 CURL——官方客户端为高可用设置提供智能重试策略。完整的客户端和集成对照表见 references/commands.md。

步骤 3 — 设计集合架构

集合是具有类型化架构的索引。将字段标记为 facet: true 以进行过滤/下钻，并设置 default_sorting_field 用于排序：

import typesense
client = typesense.Client({
    "api_key": "CHANGE_ME_STRONG_KEY",
    "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
    "connection_timeout_seconds": 2,
})
client.collections.create({
    "name": "companies",
    "fields": [
        {"name": "company_name", "type": "string"},
        {"name": "num_employees", "type": "int32"},
        {"name": "country", "type": "string", "facet": True},
    ],
    "default_sorting_field": "num_employees",
})

与 Algolia 不同，大多数设置（可搜索字段、分面、排序）都在查询时设定，因此一个集合即可支持多种排序方式——更省内存，也更灵活。

步骤 4 — 为文档编制索引

client.collections["companies"].documents.create({
    "id": "124", "company_name": "Stark Industries",
    "num_employees": 5215, "country": "USA",
})
# Bulk import (JSONL) for large datasets:
# client.collections["companies"].documents.import_(jsonl_lines, {"action": "upsert"})

步骤 5 — 搜索（容错拼写 + 分面 + 过滤 + 地理位置）

client.collections["companies"].documents.search({
    "q": "stork",                       # typo of "stark" — handled out of the box
    "query_by": "company_name",
    "filter_by": "num_employees:>100",
    "sort_by": "num_employees:desc",
    "facet_by": "country",
})

可用能力包括：分面/过滤、地理搜索（按距离排序）、分组和去重、同义词、内容策划/商品陈列（固定记录）、在一个请求中跨集合执行联邦多重搜索，以及向量/混合搜索。详情见 references/commands.md。

第 6 步 — 搜索 UI + 生产环境

• UI：InstantSearch.js 适配器 可快速提供筛选、排序、分页和输入即搜 UI。
• 多租户：生成范围受限的 API 密钥，限制对特定记录的访问——切勿将管理员密钥发送给客户端。
• 高可用：运行基于 Raft 的集群（通常为 3 个节点）以实现高可用；升级只需替换二进制文件并重启。

第 7 步 — 与 jeo-skills 一起以插件方式安装

此技能文件夹可通过标准的 jeo-skills 流程以插件形式安装，让包装器、参考资料和安装程序落盘，以供任何受支持的 Agent 运行时使用：

# Project install (writes into .agents/skills/typesense/)
npx skills add https://github.com/akillness/jeo-skills --skill typesense

# Global install for every detected agent
npx skills add -g https://github.com/akillness/jeo-skills --skill typesense

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill typesense -a claude-code -a codex -y

输出格式

当用户向 typesense 寻求帮助时，返回简短的摘要：

# typesense Routing Brief

## Scope
- Server mode: docker | binary | cloud | undecided
- Client: python | js | php | ruby | community
- Stage: install-server | install-client | schema-design | index | search | ui | production-ha

## Recommended next move
- start-docker-server | install-client | create-collection | import-docs | run-search | wire-instantsearch | scoped-keys | cluster

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `opik` / `langsmith` for LLM trace/eval observability
- `semble` for agent-facing code search over a repo
- `monitoring-observability` for non-search service telemetry

最佳实践

1. 固定版本标签，切勿使用 latest — 使用 typesense/typesense:27.1，并将数据目录放在实际卷上，以免重启时丢失索引。
2. 在查询时设置选项 — 可搜索字段、分面、排序和排名均按查询设置；通常无需为不同排序顺序创建多个集合。
3. 在架构中标记分面 — 对字段进行筛选／下钻时，必须设置 facet: true。
4. 为客户端使用范围受限的 API 密钥 — 管理员密钥应保留在服务端；范围受限的密钥可强制执行各租户的记录访问权限。
5. 使用 upsert 以 JSONL 批量导入 — 对大型数据集而言，这比逐个创建文档快得多；RAM 容量应与索引大小相匹配（索引驻留在内存中）。
6. 注意许可证 — 服务端采用 GPL，客户端库采用 Apache-2.0；应将服务端作为独立守护进程运行（这是预期用途）。

参考资料

• 上游代码库：https://github.com/typesense/typesense
• API 文档：https://typesense.org/api
• 指南／演练：https://typesense.org/guide
• 下载（二进制文件）：https://typesense.org/downloads
• Docker 镜像：https://hub.docker.com/r/typesense/typesense
• Typesense Cloud：https://cloud.typesense.org
• InstantSearch 适配器：https://github.com/typesense/typesense-instantsearch-adapter
• 安装脚本：scripts/install.sh
• 客户端与集成矩阵：references/commands.md
• 相关技能：../opik/SKILL.md、../semble/SKILL.md、 ../monitoring-observability/SKILL.md
• 许可证：GPL-3.0（服务端）；Apache-2.0（API 客户端）