@tengence/search-cli

通智搜索（Tengence Search）CLI —— @tengence/search-sdk 的 CLI 入口层，面向人 / 脚本 / CI。

与 MCP 服务器（@tengence/search-mcp）共享同一本地身份（~/.tengence/search-mcp/state.json），可混用、互不冲突：CLI 初始化后 MCP 直接用，反之亦然。

安装

npm install -g @tengence/search-cli    # 全局安装
# 或 npx 免安装
npx -y @tengence/search-cli --help

本地开发（monorepo）：

npm run search:cli -- <命令>   # 仓库根目录

命令速查

| 命令 | 作用 | |---|---| | tengence-search init | 初始化（幂等）：自动注册客户端 → 服务端创建「数据集 + 搜索应用」并绑定 → 双 API Key 落盘本地（0600）。首次注册成功时返回激活链接与登录信息（明文仅交付一次并落盘本地）；未激活账号需凭激活链接完成「设置密码 + 绑定手机」后才能推送/搜索 | | tengence-search push <file> | 从文件推送数据（JSON / JSONL / CSV；- 读 stdin）。每条必须含唯一 id：不存在→新增；存在→更新；--delete 仅保留 id（删除）。首次推送成功后自动启动搜索应用 | | tengence-search search "<关键词>" | 搜索：分页 / 排序 / 过滤 / 高亮 / 聚合 / 字段限制（参数映射与官方 API 1:1） | | tengence-search ping [--probe] | 诊断：注册/初始化状态 + 配置概览（密钥掩码）；--probe 探测三个下游连通性 | | tengence-search status | 本地状态：身份 / 资源 / 配置（纯本地，不发网络请求） | | tengence-search claim-link | 重新签发激活链接（首次链接过期/丢失时使用，幂等） |

快速开始

# 1. 初始化（首次会返回激活链接与登录信息，请保存）
tengence-search init

# 2. 推送数据（JSON 数组 / JSONL / CSV）
tengence-search push articles.json
tengence-search push articles.csv --id-field slug
cat articles.jsonl | tengence-search push -          # stdin

# 3. 搜索
tengence-search search "通智" --size 10 --sort publish_time=desc \
  --filter status=eq:published --fields id,title

# 4. 排障
tengence-search ping --probe
tengence-search status

搜索参数

| 选项 | 说明 | 示例 | |---|---|---| | --page N / --size N | 分页（size ≤ 100） | --page 2 --size 20 | | --sort field=asc\|desc | 排序（可重复） | --sort publish_time=desc --sort title=asc | | --filter field=op[:value] | 过滤（可重复）。操作符：eq/ne/gt/gte/lt/lte/in/not_in/exists/not_exists | --filter status=eq:published、--filter brand=in:华为,Apple、--filter price=gte:2000 | | --agg name:field:type | 聚合（可重复），type: terms/range/date_histogram | --agg by_brand:brand:terms | | --agg-json "{...}" | 高级聚合（原样 JSON） | --agg-json '{"name":"x","field":"f","type":"range","ranges":[{"key":"a","to":10}]}' | | --highlight f | 高亮字段（可重复） | --highlight title | | --search-fields a,b | 限定搜索字段 | --search-fields title,keywords | | --fields a,b | 限定返回字段 | --fields id,title |

输出与退出码（脚本/CI 友好）

• --json：stdout 只输出 JSON（成功 {ok:true,...} / 失败 {ok:false,code,message}），日志不混入
• 退出码：0 成功 / 1 业务或网络错误 / 2 参数错误
• 所有输出中的密钥与凭据一律掩码（激活链接与初始凭据仅在 init 首次注册成功时明文交付一次）

环境变量（可选）

| 变量 | 说明 | 默认 | |---|---|---| | TENGENCE_SOLUTION_BASE_URL | 注册/初始化服务地址 | https://console.tengence.com | | TENGENCE_SEARCH_API_KEY | 搜索 API Key（不配也行，init 自动获取落盘） | – | | TENGENCE_DATASET_API_KEY | 数据集 API Key（同上） | – | | TENGENCE_SEARCH_BASE_URL | 搜索 API 地址 | https://api.tengence.com | | TENGENCE_PUSH_BASE_URL | 推送 API 地址 | https://api.mossego.com | | TENGENCE_SEARCH_HOME | 本地状态目录（state.json 0600） | ~/.tengence/search-mcp |

配额与激活

• 激活门槛：账号注册即「待激活」，未完成「设置密码 + 绑定手机」时 push / search 返回错误并附激活链接；激活链接过期/丢失可执行 tengence-search claim-link 重签
• 免费版额度：配额用满时（服务端返回 QUOTA_EXCEEDED 等错误码）自动附加登录控制台升级套餐的指引（登录地址 + 账号，密码掩码提示已存本地）