Tanyuan Search

---
name: tanyuan-search
description: |
  腾讯探元文博检索工具集（Agentic RAG）。封装两个 HTTP API 为 Node.js 脚本，由 Agent 依据问题特征选择工具并构造 query：
  - search-relics（文物/世界遗产数据库 NL→SQL）：适合结构化事实的详情、列表、统计与排行查询
  - search-knowledge（关键词+向量语义检索）：适合开放/语义问题（背景/原因/工艺/故事/鉴赏/对比论证/攻略/研学）
  触发词：文物 / 查文物 / 馆藏 / 朝代 / 年号 / 青铜器 / 瓷器 / 出土 / 世界遗产 / 入选年份 / 评定标准 / 濒危 / 背后故事 / 工艺 / 历史 / 对比 / 参观 / 研学 / 攻略
---

# Tanyuan Search 探元检索技能

为「腾讯探元文博专家」提供两个后端 HTTP API 的调用能力，覆盖文物与世界遗产结构化查询、文博知识检索。使用时遵循 **Agentic RAG** 思路：先按问题形态选择工具和数据源，再为 Text2SQL 保留完整问题语义，或为向量检索提炼核心 query。

## 运行要求

- **Node.js ≥ 18**（使用内置 `fetch`、`AbortController`，无第三方依赖）
- 无需 `chmod +x`；直接用 `node <脚本路径>` 调用即可
- **外网连接**：脚本运行时需能访问探元后端 API 域名 `api-ai-creation.tanyuan.qq.com`；当前接口无需鉴权，脚本未硬编码任何密钥。

## 工具怎么选（Agentic RAG）

| 来源 | 最擅长 |
|------|--------|
| `search-relics.js` | **精确事实查询**：按明确的馆藏机构/出土地/年代/类别/等级等条件查询数据库内文物；世界遗产的国家、洲别、入选年份、类别、评定标准、濒危状态及关联数据 |
| `search-knowledge.js` | **单件/单主题细节**：某件文物或某专题的背景、原因、工艺、故事、鉴赏、对比论证，以及非遗/传统技艺等主题 |
| 平台联网检索 | **总结/评价/全局类**：代表作、著名/最重要、十大、排名、跨馆汇总等需要全局知名度与共识的问题 |

- **探元两个库覆盖有限、都不是全集**：relics 只收录部分馆藏且不按知名度排序，knowledge 条目也不足以覆盖全局评选。**"代表作/著名/最重要/十大/排名"这类总结问题不能仅靠探元库判定**——应以**联网检索建立清单与知名度判断**，再用探元库补单件细节。
- **组合**：联网建代表作清单 → `search-knowledge` 补名器工艺/背景细节 → `search-relics ... 0` 对确有明确馆藏的器物补馆藏事实；不要用 relics 有限馆藏充当代表作清单，也不要仅凭 knowledge 片面下"最重要"结论。
- **不要混库**：`search-relics` 的 `datasourceType=1` 是世界遗产结构化数据库，不是通用非遗或传统技艺数据库。

## 脚本清单

### 1. `scripts/search-relics.js` — 文物 / 世界遗产结构化检索

对应接口：`POST /tanyuanAiAssistant/tool/searchRelics`

**调用方式**：

```bash
node skills/tanyuan-search/scripts/search-relics.js "<query>" [datasourceType]
```

**适用场景**：后端将自然语言 `query` 转为只读 SQL，执行结构化详情、列表、统计或排行查询。

- `datasourceType=0`（文物数据库）：可按文物名称/通识名、年代、类型、类别、等级、馆藏机构、创作者、出土地和普通文本概念检索；可按需返回尺寸、封面、基本介绍、特征介绍等。馆藏机构与出土地是不同字段；颜色是普通文本概念，不是可直接过滤的颜色字段。**注意：本库仅收录部分馆藏，不代表全集，不用于"代表作/著名"类知名度评选。**
- `datasourceType=1`（世界遗产数据库）：可查询世界遗产名称、国家、洲别、入选年份、类别、评定标准、濒危状态、坐标、图片和简介，以及 OUV、保护状态、历史事件、引用、知识卡片、叙事、媒体、推荐和用户贡献等关联数据。

脚本只透传自然语言问题，不在本地拆词或生成 SQL。

**参数**：

| 位置 | 含义 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `argv[2]` | `query` | 是 | — | 保留全部有效过滤条件、问题形态和返回意图的自然语言问题；不得传 SQL 或关键词堆砌 |
| `argv[3]` | `datasourceType` | 否 | `0` | `0`=文物数据库；`1`=世界遗产数据库 |

**stdout**（成功时，扁平化 JSON）：

```json
{
  "requestId": "abc-123",
  "rowCount": 3,
  "items": [
    { "name": "青铜器示例", "years": "明", "category": "青铜器", "museum_name": "故宫博物院", "basic_introduce": "..." },
    { "name": "青花人物故事罐", "...": "..." }
  ]
}
```

- 每个 `item` 已由脚本对原 `response.data.rows[]`（每项是 JSON 字符串）完成 `JSON.parse`，Agent 直接读取即可（字段以实际返回为准）
- 如果某行原字符串解析失败，会降级为 `{ "_raw": "<原字符串>" }`
- **`rowCount` 是本次返回的行数，受后端检索条数上限约束（常见约 10 条），不是符合条件的总数**。达到上限时几乎必然还有更多记录未返回，Agent 不得把它当作"总数/全集"，也不得据返回的若干条臆造统计结论

**失败时**：exit code = 1，stderr 打印 `HTTP <code>: <body>` 或 `API error: <msg>`；参数缺失 exit code = 2。

### 2. `scripts/search-knowledge.js` — 文博知识向量检索

对应接口：`POST /tanyuanAiAssistant/tool/searchKnowledge`

**适用场景**：开放/语义问题（背景、原因、工艺、故事、鉴赏、对比论证、攻略、研学）。快，语义覆盖好，是大多数问答的首选。

**调用方式**：

```bash
node skills/tanyuan-search/scripts/search-knowledge.js "<query>" [datasourceType]
```

**参数**同上，`query` 同样应为**重构后**的检索词（只保留核心实体 + 单一主要意图，query 宜短、不堆砌维度词；需要多维度时拆成多个精简子 query 分别检索）。

**stdout**（成功时，扁平化 JSON）：

```json
{
  "requestId": "abc-124",
  "text": "三星堆青铜面具是……（多段落 Markdown 或纯文本）"
}
```

- 直接使用 `text` 作为知识素材组织回答
- `text` 为空字符串时视作无结果，向用户如实告知

**失败**行为同 `search-relics.js`。

## 参考资料

详细的 API 字段类型、`datasourceType` 语义、响应示例与失败结构，请见 @references/api-spec.md 。

## 使用建议（Agentic RAG）

1. **按问题形态选来源**：数据库内按明确条件的详情、列表、统计用 `search-relics`；某件文物/专题的解释、故事、鉴赏、攻略、研学用 `search-knowledge`；**代表作/著名/最重要/十大/排名等总结评价类以联网检索建立清单为主，再用探元库补单件细节**；复合问题先建清单/取事实，后解读。
2. **为 Text2SQL 构造完整问题**：
   - `relics ... 0`：保留结构化条件、完整文物专名/普通文本概念、详情/列表/统计形态和返回意图；规范化年代、类型、类别、等级。馆藏机构、创作者、出土地须明确区分。不要只留 1–2 个条件，不要把问题压缩成关键词串。
   - `relics ... 1`：保留世界遗产实体、国家/洲别、入选年份、类别、评定标准、濒危状态、目标关联信息和返回意图。类别可规范为文化/自然/混合/预备名单。
   - 例（文物）：`"馆藏机构为故宫博物院的明代青铜器有哪些？请返回名称、年代、类别、馆藏机构和介绍"`。
   - 例（世界遗产）：`"中国有哪些文化类世界遗产？请返回名称、入选年份、评定标准、濒危状态和简介"`。
3. **为知识检索提炼 query**：只保留核心实体 + 主要意图，复杂问题拆成多个精简子 query，不要把所有回答维度堆入一次向量检索。
4. **准确选择数据源**：`search-relics` 中 `0`=文物数据库、`1`=世界遗产数据库；`search-knowledge` 中 `0`=默认/文物知识源、`1`=文化遗产知识源。非遗、传统技艺不属于世界遗产结构化数据库，不得仅因出现"遗产"就调用 `relics ... 1`。
5. **对比场景**：分别查询各对象的结构化事实，必要时再补知识检索论证；不要期待接口一次生成完整对比结论。
6. **迭代**：结构化查询为空时先检查数据源、实体全称/可靠别名和标准值，只能在不改变用户明确过滤条件的前提下调整措辞；不得盲目切换数据源或静默删减条件。仍需放宽时须先征得用户同意，或将结果明确标为“放宽条件后的候选项”。
7. **失败降级（对用户不可见内部失败）**：脚本 exit 非 0 时，Agent 内部感知即可，**不要向用户暴露"检索失败/接口报错/工具异常"等技术性信息**；改为自然地请用户补充线索，或基于既有权威知识稳妥作答，必要时用平台联网检索兜底。
8. **无结果**：`rowCount = 0` 或 `text` 为空时，先按第 6 条迭代；仍无果则以"暂未找到相关权威记录"等自然措辞告知，不要编造，也不要提及内部检索过程。
9. **返回条数≠总数（且内外有别）**：`rowCount > 0` 时，返回的只是受上限约束（常见约 10 条）的**部分**记录，不是符合条件的总数；达到上限时几乎必然还有更多。这属于**内部判断依据**：组织回答时用"其中几件""可能还有更多，可再帮你细看"等自然表述，不得说"共 N 件/完整清单"，也不得据被截断的结果臆造二级统计（如"其中一级文物 8 件"）。**尤其注意：绝不能把"返回的 N 条""检索上限""已达上限""结果被截断"等内部机制词说给用户**（如反例"返回的 10 条已达到检索上限"）。仅当为明确的统计（COUNT）查询并返回统计值时才给出数量，且仍锚定"本库收录范围"。