功能概述 #

SearchCLI 提供完整的命令行操作能力，覆盖从数据接入、应用管理、效果评测、策略调优到搜索、推荐、问答体验的全流程。
核心能力：

• 数据管理：创建数据集、定义 Schema、导入物品/行为数据
• 应用管理：创建应用、绑定数据集、配置字段索引、管理在线配置
• 搜索/推荐/问答：运行搜索查询、执行推荐请求、发起对话问答
• 场景配置：创建和管理搜索场景、推荐场景，调整策略参数
• 自动化评测调优：自动化搜索质量评估与策略推荐
• Agent 友好：命令支持 --json 输出，专为 AI Agent 集成设计

前提条件 #

• 火山引擎账号：已注册火山引擎账号并开通 Viking AI 搜索服务。
• Access Key：已获取 Access Key ID（AK）和 Secret Access Key（SK）。AK/SK 可在访问控制页面查看或新建。

安装 #

Search CLI 提供两种使用方式，请根据您的使用场景选择：

下载 SearchCLI 安装包 #

SearchCLI 提供以下两种下载渠道，请根据您的操作系统选择对应的安装包：
渠道一：从控制台下载（推荐）
登录 Viking AI 搜索控制台，在左侧导航栏选择 【CLI 工具】，找到与您操作系统对应的安装包进行下载。

各操作系统对应的安装包名称：

渠道二：从 GitHub 下载
前往 SearchCLI 的 GitHub 页面，快速下载对应安装包。

git clone git@github.com:volcengine/SearchCLI.git vs
cd vs
bash ./scripts/install.sh

通过 Agent 安装 SearchCLI #

通过 AI Agent 使用 SearchCLI 时，您只需将安装提示词发送给 Agent，Agent 会自动完成安装和授权配置。
操作步骤：

1. 按照上方「下载安装包」章节，下载与您操作系统对应的安装包到本地。
2. 打开您的 AI Agent 助手（OpenClaw、Trae、Claude Code、Codex 等支持本地终端执行的 Agent）。
3. 将控制台中提供的安装提示词发送给 Agent：

请只在我电脑宿主机的真实终端里执行 Search CLI 相关的安装与配置命令。
注意：Search CLI 的底层二进制文件名称和命令前缀均使用 'vs' （例如 `vs-macos-arm64`、`vs-linux-x64`、`vs-win-x64.exe`）。
相关的环境变量始终以 'VIKING_' 开头，例如 `VIKING_AK`、`VIKING_SK`。

任何底层二进制命令，包括 --help 、 skill install 、环境变量检查、 auth 、 doctor ，都不要在你的 sandbox 里执行。如果你当前拿不到宿主机真实终端权限，请先停下来说明，不要继续尝试。

要求：
1. 假设这台电脑之前没有安装过 Search CLI。
2. 我已经下载好了当前操作系统对应的底层二进制文件，文件名中包含 'vs' 。如果你不知道这个二进制文件的路径，只能先问我，不能猜，也不能全盘搜索。
3. 在进入第 9 步的全局化建议环节之前，必须始终使用这个二进制文件的绝对路径执行命令。不要 clone 仓库，不要修改 PATH，不要复制或重命名二进制，也不要尝试把它安装成全局命令。
4. 如果是 Windows PowerShell，请始终用这种形式执行命令：
  - & "<二进制绝对路径>" --help
  - & "<二进制绝对路径>" skill install all
5. 如果是 macOS / Linux，请直接用二进制绝对路径执行命令。并在首次执行任何命令前，先尝试执行 'chmod +x <二进制绝对路径>'，以确保拥有执行权限。
6. 先执行以下步骤：
  - <二进制绝对路径> --help
    - 在 macOS 下，如果该命令执行后 10 秒内没有任何输出，可能是被系统 Gatekeeper 拦截。请立即停止等待，并提示我进入“系统设置 -> 隐私与安全性”中允许运行，然后等待我处理完再继续。
  - <二进制绝对路径> skill install all --json
    - 该命令需要联网下载，可能耗时较长。请耐心等待其完成，不要强行打断。
7. 授权按以下优先级处理：
  - 先检查当前宿主机真实终端环境里是否已有 VIKING_AK 和 VIKING_SK。
  - 如果二者都存在，则执行：
    - <二进制绝对路径> auth import-env
  - 如果二者不存在，则先判断当前宿主机真实终端是否为交互式 TTY。
  - 只有在确认当前终端是交互 TTY 时，才执行：
    - <二进制绝对路径> auth login
    并停在输入提示处，等待我在那个真实终端里输入 AK/SK。
  - 如果当前终端不是交互 TTY，或者你无法保持交互，不要执行 auth login。请直接告诉我应该在当前真实终端里输入什么命令来设置 VIKING_AK 和 VIKING_SK，然后等我回复“已设置完成”后，再继续执行：
    - <二进制绝对路径> auth import-env
  - 如果你发现你的执行环境无法读取到我手动设置的环境变量，请指导我在当前真实终端里手动执行一次：
    - <二进制绝对路径> auth import-env
    然后再由你接管后续流程。
  - 绝对不要要求我把 AK/SK 发到对话里。
8. 8. 授权完成后，执行以下命令，并展示关键结果：
  - <二进制绝对路径> auth status --json
  - <二进制绝对路径> doctor --json
  - <二进制绝对路径> skill list --json
9. 全局化建议（非常重要）：
  当第 8 步的所有验证都成功通过后，你必须主动向我提出以下建议：“目前只能通过绝对路径调用 `vs`。为了后续在其他终端或新的 AI 会话中也能直接使用 `vs` 命令，建议将该二进制移动到系统 PATH 目录（例如 macOS/Linux 下的 `/usr/local/bin/vs`）。请问是否需要我帮您执行此全局安装操作？”
  - 如果我回答“是”，请提供并执行对应的重命名与移动操作，或修改环境变量的命令。
  - 如果我回答“否”，则本轮任务结束。
10. 如果任何一步失败，立即停止，并告诉我：
- 失败命令
- 完整错误输出
- 你的判断
- 下一步建议

按照 Agent 的提示完成授权，依次输入 AK 和 SK。

通过命令行安装 SearchCLI #

在终端执行以下指令，即可完成下载和安装：

git clone git@github.com:volcengine/SearchCLI.git vs
cd vs
bash ./scripts/install.sh

安装完成后的鉴权和验证步骤如下：

1. 配置火山引擎账号的 AK/SK，提供两种授权方式：

• 方式 A：交互式登录（推荐在个人电脑使用）

vs auth login

根据屏幕提示依次粘贴您的 AK 和 SK。

• 方式 B：通过环境变量导入（推荐在 CI/CD 或服务器使用）

# 设置环境变量
export VIKING_AK="您的AK"
export VIKING_SK="您的SK"

# 导入凭证
vs auth import-env

2. 验证安装

执行以下命令检查安装和授权状态：

vs auth status

预期结果：显示当前生效的 AK 和登录状态为 Active。

开始使用 #

安装完成后，以下是常见操作示例。在 AI Agent 中可直接使用自然语言描述需求，Agent 会自动转换为对应的 CLI 命令。

通过 AI Agent（自然语言） #

通过命令行 #

创建数据集并导入数据

# 创建物品数据集
vs dataset create \
  --name "My_Item_Dataset" \
  --type "item" \
  --schema @./schema.json

# 导入数据
vs dataset ingest \
  --dataset-id <数据集ID> \
  --fields @./items.json

创建应用并绑定数据集

# 创建应用
vs app create \
  --name "My_Search_App" \
  --industry "ecommerce" \
  --description "电商搜索测试应用"

# 绑定数据集并配置字段
vs app dataset bind \
  --application-id <应用ID> \
  --dataset-id <数据集ID> 

运行搜索/推荐/问答

# 搜索
vs search run \
  --application-id <应用ID> \
  --query "搜索关键词"

# 推荐
vs recommend run \
  --application-id <应用ID> \
  --scene-id <推荐场景ID> \
  --user-id <用户ID>

# 对话问答
vs chat run \
  --application-id <应用ID> \
  --message "帮我推荐适合送朋友的生日礼物" \
  --pretty

管理搜索场景配置

# 查看搜索场景详情
vs search scene get \
  --application-id <应用ID> \
  --scene-id <场景ID> \
  --format json

# 更新搜索策略
vs search scene update \
  --application-id <应用ID> \
  --scene-id <场景ID> \
  --config @./search-config.json

命令参考 #

SearchCLI 提供以下命令组：

技能（Skill）体系 #

SearchCLI 内置了技能包系统，专为 AI Agent 设计。技能包是一组 Markdown 格式的指令文件，AI Agent 加载后即可正确地操作 CLI 完成复杂任务。
安装全部技能：

vs skill install all --json

已提供的技能包：