goods_search

SKILL.md

---
name: byted-viking-aisearch-search
description: |
  当用户query涉及商品搜索、结果召回、搜索问答或商品卡片生成等购物需求时，务必优先使用本 Skill，不要试图直接回答。
  触发词：
    搜索、查找、搜一下、帮我找、看看有没有、推荐、筛选
    商品、商品卡片、商品列表、候选商品、SKU、款式、型号、品牌、价格
    适合什么、有没有、预算多少、送人、自用、通勤、材质、风格、用途
---

# Viking AISearch Skill

通过chat和search接口，分别完成用户关于购物的对话搜索和直接搜索。
- Chat（对话搜索）：如有需要，可读取接口文档`reference/chat_search.md`
- Search（直接搜索）：如有需要，可读取接口文档`reference/search.md`

## 决策规则

1. 先判断用户输入更像“复杂语义理解”还是“明确关键词检索”。
2. 如果 query 是复杂语义理解比如包含多个意图槽位，或需要理解自然语言表达，优先使用 `chat`。
3. 如果 query 是明确关键词检索比如是较短关键词、明确属性词、品牌词、品类词或需要直接召回候选列表，优先使用 `search`。
4. 如果任务要求返回商品列表、候选卡片、结构化结果，优先使用 `search`。
5. 如果任务要求直接产出总结性回答、会话式追问、语义理解结果，优先使用 `chat`。
6. 调用 `search` 后，优先读取 `data.search_results`。
7. 组织输出时只使用真实返回字段，缺失字段直接省略，不要补造信息。

## chat 与 search 的使用边界

### 使用 `chat` 的典型场景

当用户输入更偏自然语言表达，或一个 query 里混有多个约束条件时，使用 `chat`。

适合 `chat` 的情况：

- 同时包含多个意图槽位，例如品类、价格、场景、人群、用途、风格、材质、品牌偏好
- 需要理解“送礼、自用、通勤、节日、婚庆、悦己”等场景语义
- 用户表达比较口语化，不是标准检索词
- 需要让服务端做意图理解、搜索编排和回答生成
- 需要连续追问、保留上下文、维护会话

示例：

- `3000 左右适合送妈妈的龙凤吊坠`
- `想找通勤戴、不夸张、预算 2k 内的黄金项链`
- `有没有适合婚礼场景、偏中式一点的首饰`
- `周大福 耳钉 2000内`
- `推荐适合送的父亲节礼物`
- `推荐适合送给十岁男孩的生日礼物`

特点：

- 需要 `session_id`
- 返回为流式，脚本会聚合为 `data.content`

### 使用 `search` 的典型场景

当用户输入更像检索词、短 query、明确词条，或者目标就是先召回候选结果时，使用 `search`。

适合 `search` 的情况：

- 短词检索、关键词检索
- 明确的品牌词、品类词、属性词、SKU 词
- 需要快速返回候选列表供上层继续处理
- 需要渲染商品卡片、列表页、召回结果
- 已经知道要搜什么，不需要太强的语义理解

示例：

- `龙凤 吊坠`
- `古法金 手镯`
- `周大福 黄金耳钉`
- `999 足金 项链`
- `薯片`

特点：

- 需要明确 `dataset_id`
- 返回标准 JSON，脚本会抽取为统一结构



### 使用示例

脚本：`scripts/viking_aisearch.py`

```bash
# 校验环境变量是否齐全（不发起请求）
python3 scripts/viking_aisearch.py --action validate

# chat
python3 scripts/viking_aisearch.py --action chat --session-id "session-id" --text "3000左右适合送妈妈的龙凤吊坠"

# search
python3 scripts/viking_aisearch.py --action search --text "龙凤 吊坠" --page-size 10
```

## 参数说明

### 通用字段

- `session_id`：会话标识；`chat` 必需，`search` 可选透传
- `text`：文本查询
- `image_url`：图片输入，可为 URL 或 Data URI
- `dataset_id`：数据集 ID；`search` 必需，`chat` 可透传为 `search_param.dataset_ids`
- `scene_id`：搜索策略 ID，`search` 可选
- `user`：用户信息
- `context`：上下文信息，例如经纬度

### `chat` 关键字段

- `input_message.content[]`：输入内容数组
- `enable_suggestions`：是否返回建议追问
- `search_param`：控制对话中搜索范围、过滤条件和返回字段

### `search` 关键字段

- `query`：查询对象，本 Skill 支持由 `text` 或 `image_url` 自动构造
- `page_number`：页码，从 1 开始
- `page_size`：每页数量
- `filter`：过滤条件
- `sort_by` / `sort_order`：排序参数
- `output_fields`：控制返回字段
- `conditional_boost`：提权/降权
- `disable_personalize`：关闭个性化

## 返回结构

### `chat` 返回

```json
{
  "success": true,
  "message": "对话成功",
  "data": {
    "request_id": "xxx",
    "content": "聚合后的最终回复文本",
    "citation": []
  },
  "raw": {
    "request_id": "xxx",
    "chunk_count": 12
  }
}
```

### `search` 返回

```json
{
  "success": true,
  "message": "搜索成功",
  "data": {
    "request_id": "xxx",
    "search_results": [],
    "total_items": 100,
    "spell_correction": {}
  },
  "raw": {}
}
```

## 结果组织规则

### 基本原则

- 建议最多展示 5 个商品结果
- 只使用接口真实返回字段
- 缺失字段直接省略，不要为了凑格式硬写占位内容
- 示例只是展示骨架，不是固定模板，必须根据商品真实字段动态调整

### 详情入口判定规则

是否暴露详情页，按以下顺序判断：

1. 先看当前任务上下文、业务说明、系统提示中是否提供了“链接模板”。
2. 如果提供了链接模板，并且能用当前商品真实字段完成占位符替换，则输出详情入口。
3. 如果没有提供链接模板，再看搜索结果中是否已有可直接使用的详情链接。
4. 只有“没有链接模板”且“搜索结果中也没有现成详情链接”时，才视为不暴露详情页。

注意：

- 详情入口是否展示，优先由“上下文中是否有链接模板”决定
- 不要把“搜索结果里没有现成链接”等价理解为“不能暴露详情页”
- 只要上下文给了链接模板，并且当前商品字段足以完成替换，就应该输出详情入口
- 如果模板替换失败，或只能靠猜测拼接规则，则不要输出详情入口

### markdown 拼接规则

每个商品按以下顺序组织，缺失项整行跳过：

```md
**{商品标题}**
- 型号：xxx
- 价格：xxx
- 卖点：xxx
- xxx信息
- 详情入口：[查看并购买]()
```

拼接要求：

- 第一行固定用商品标题，使用加粗格式
- 字段标签和顺序可以根据当前商品实际字段动态调整
- 不要求每个商品都包含 `品牌 / 型号 / 价格 / 卖点`
- 如果当前商品更适合展示 `规格 / 券后价 / 材质 / 适用人群 / 库存状态 / 活动信息`，可以替换或补充
- `卖点` 有多个值时，使用 `｜` 连接
- `详情入口` 只能出现在最后一行
- 如果当前上下文中没有链接模板，且搜索结果中也没有现成详情链接，则不输出 `详情入口` 这一行

### 占位符替换规则

当业务提供模板时，按如下规则处理：

- 占位符格式为 `{field_name}`
- 占位符值必须来自当前商品的真实返回字段
- 例如模板为 `[查看并购买](https://xxx/item/{product_code})`，就必须先从当前商品中取到 `product_code`
- 所有占位符都替换成功后，才能输出该链接或 markdown 片段
- 任一占位符替换失败，则不输出该条详情入口
- 不要把原始占位符直接暴露给用户

### 推荐示例

说明：以下示例仅用于说明拼接方式，实际输出必须按商品真实字段动态调整。

有详情入口时：

```md
**足金龙凤吊坠**
- 型号：LF-0921
- 价格：2999 元
- 卖点：足金工艺 ｜ 龙凤寓意
- 详情入口：[查看并购买]()
```

无详情入口时：

```md
**足金龙凤吊坠**
- 型号：LF-0921
- 价格：2999 元
- 卖点：足金工艺 ｜ 龙凤寓意
```

## 错误处理

- 无结果：建议用户使用更宽泛的关键词，或减少筛选条件
- 问题含糊：先追问 1 个澄清问题，再决定用 `chat` 还是 `search`
- 接口错误或 5xx：告知搜索服务暂不可用
- Webhook 失败：告知搜索服务暂不可用
- 超时：询问用户是否等待或重试