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