VTRIP·旅游知识检索
在本 Skill 目录执行一次查询，脚本生成结果页并返回回答素材：
node scripts/knowledge-search.js --query "纽约有什么好玩的" --output-dir "$PWD/outputs"
正常查询直接执行，凭据由脚本读取，不要阅读 scripts/。只有配置失败或用户要求排查时，才读取配置指引。
交付形态（固定，勿混用）
| 位置 | 内容 | 工具 |
|---|---|---|
| 对话正文 | 根据 materials 写的推荐文字 |
直接输出 markdown |
| 对话底部 + 右侧内置浏览器 | card-html 结果页（自动打开预览 + artifact 卡片） | present_files 中的 htmlFile（本地路径） |
单文件交付：files: [htmlFile]。 只传本地 HTML 文件的绝对路径——宿主会自动在内置浏览器打开实时预览（获得焦点），同时在对话底部生成 artifact 卡片，一个路径同时覆盖两个入口，无需再传 htmlUrl。htmlUrl 仅是脚本内部短链服务地址，不得作为 present_files 参数传入。
不调用 present_files，用户看不到结果页；禁止用文字或正文链接代替。
成功时 stdout 被 WORKBUDDY_VISUAL_JSON_START / END 包裹，内含：query、counts、htmlFile、htmlUrl、previewHint、presentFiles、materials 等。
解析该 JSON 后，只做两步，然后立刻结束：
- 根据
materials写完对话回答（见下）。正文末尾写「完整清单与卡片详情见下方结果页」；不可只写推荐却不提结果页。不要把htmlFile/htmlUrl写成可点 markdown 链接（聊天里点 http 常进系统浏览器）。 - 必须
present_files({ files: presentFiles.files })，且files严格等于脚本返回的presentFiles.files。这是本轮最后一个工具调用；调用后零文字。
previewHint 为 file-card+browser-preview：本地 HTML 文件由宿主自动在内置浏览器打开并生成卡片，无需额外操作。
本地短链服务不可用时，materials 不带 shortUrl，正文相应名称标注「暂无详情」即可，交付方式不变。
materials 是扁平数组，每条自带 type（poi 景点 / article 攻略 / daytour 跟团游）。含名称、目的地、简介或摘要，以及实际存在的地址、时长、评分、标签、价格、币种、天数、途经景点；空字段省略。linkable 表示有无详情链接；有链接且本地服务可用时带 shortUrl（http://127.0.0.1:<端口>/r/<scope>/<序号>），不返回完整 url。
HTML 按接口顺序展示全部可识别条目，不筛选、不截断。智能体只用同次 materials 回答，不读 HTML、不另建中间文件。
回答按目的地、主题和内容质量挑选，注意城市与州的区别，排除异地、重复与促销。先概括能玩什么，再按主题写亮点及素材支持的游玩节奏；攻略作延伸阅读；跟团游用返回的价格、币种、天数和途经景点。景点若 materials.price 有值，正文写出门票价格（可写「起」）；没有该字段则不提票价。完整清单和详情留在结果页，不重复罗列。除非用户明确要求导出，否则不另建回答文件。
统计时区分接口返回数量与正文推荐数量。counts.daytour 为 0 时说明「本次未返回跟团游商品」；有返回但不相关时说明未推荐。三类均为 0 才说「暂无相关结果」；有候选但均不相关时说「本次候选未筛选出相关结果」。不能只给文件链接或统计；也不能只写推荐却不在正文中表达结果页（card-html / htmlUrl 或 htmlFile）。
正文里景点名称、攻略标题、跟团游商品名称，凡 materials 带 shortUrl 的，必须写成 markdown 超链接 [名称](shortUrl)，三类规则相同。没有 shortUrl 的用普通名称并标注「暂无详情」。不要把完整长链接写进对话。完整清单仍留在结果页，不把全部条目都链进正文。
数据与权限边界
- 只调用本 Skill 的
knowledge/search，渠道固定ai_trip。脚本从环境变量或.env读取VTRIP_OPEN_API_KEY，放入X-Api-Key；不回显完整密钥。运行时配置读 Skill 根目录config.json，不存在则读config.example.json。 - 只引用素材支持的事实，不补写未返回的开放时间、票价、交通、预约政策、天气、最佳季节或人均消费。景点门票只引用
materials.price（来自接口min_price/model_price/avg_price）；没有该字段就不提价格。景点原始text中的促销票价不可引用；异常时长（如「30天」）忽略。 - 正文名称链接只用
materials.shortUrl；无短链标注「暂无详情」，不拼接详情地址或搜索页。输出目录按查询隔离，可能含签名参数，不公开上传。短链由本地服务 302 到接口详情页，空闲退出后失效。 - 查询失败就反馈错误，不编造结果，不用历史文件伪装本次成功。401/403 提示「Key 无效或未授权当前业务场景，请核对开放平台是否选择了配置中的业务场景」。进一步排查才读错误处理或接口约定。
- 无凭据时返回
status: requires_api_key，退出码 1，不生成 HTML。保留申请链接和返回的channelName（来自配置defaults.channelName）。读取配置指引，向用户完整展示三种配置方式（不要展示自检命令或脚本路径）。引导申请时必须说明：视旅开放平台共有 3 个业务场景（AI定制、AI商旅、VTRIPCLaw）；本 Skill 的业务场景是返回的channelName；申请 API Key 时须确认已选择该场景，否则可能鉴权失败。配置完成后由 Agent 内部验证并重试原问题。
