搜索流程说明（每次搜索都适用）

用户每次发起搜索时（包括首次、后续、重新搜索、换关键词等），智能体都须按以下流程执行，不得省略或合并为一次：

Step 1. 计算两次调用的 pageSize（成片优先配比）

设用户想要总条数为 N（默认 3，上限 5；用户可指定 1-5）：

pageSize_finished = ceil(N / 2) — 成片

pageSize_material = floor(N / 2) — 素材

用户想要 N 成片条数素材条数

1 1 0

2 1 1

3 2 1

4 2 2

5 3 2

Step 2. 两次 POST 调用（顺序执行）

第一次（成片）：请求体 commodityCode = finished_commodity_code，URL pageSize = pageSize_finished

第二次（素材）：请求体 commodityCode = null，URL pageSize = pageSize_material（若为 0 则跳过第二次）

Step 3. 兜底补齐（配比失败时）

若成片实际返回 < pageSize_finished，用素材补齐到 N 条；反之亦然。目标是总条数尽量等于 N。

Step 4. 合并与判定类别

合并两次返回的 datas，按 businessCode/id 去重

逐条以"返回数据本身"的 commodityCode 判定（不是按哪次调用）：

item.commodityCode === finished_commodity_code → category = "成片"

否则 → category = "素材"

Step 5. 展示与汇总（统计必须基于 category 字段，不是请求参数！）
成片条数 = sum(1 for item in results if item.category == "成片")
素材条数 = sum(1 for item in results if item.category == "素材")
汇总行（表格之前）：📽 共找到 N 条资源：成片 **X** 条｜素材 **Y** 条

X、Y 必须与表格里实际带 【成片】/【素材】 徽章的行数严格一致

即使 X=0 或 Y=0 也要写出（说明搜过了但无结果）

表格每行：标题旁强制带 【成片】 / 【素材】 徽章（以 item.category 为准）

绝对禁止：

❌ 省略成片调用，只调一次接口就返回

❌ 汇总行的数字与表格里实际徽章不一致（最常见错误：按"请求参数 commodityCode 是什么"算成片条数，而不是按"返回记录本身的 commodityCode"算）

❌ 输出表格时省略类别徽章

此规则等同于主路径「步骤 1」，优先级最高。

购买流程说明（当前调试阶段）

本 Skill 处于调试阶段，真实交易 API 尚未上线。用户发出「购买」「下单」「买 N」等指令时，当前约定的完整响应流程为：

构造 mock 交易响应：video_url = 搜索结果中该素材的 fragmentUrl（预览地址）

下载视频到本地：调用 bash scripts/download_video.sh "<video_url>" "downloads/{business_code}.mp4" [HLS|MP4]，将视频保存到 downloads/ 目录

告知用户：输出下载完成状态及本地文件路径

此流程由用户购买指令显式触发，搜索和预览阶段不执行任何下载。真实交易 API 上线（TRADE_API_BASE 非空）后，步骤 1 将替换为真实下单请求，步骤 2-3 保持不变。

输出格式规范

智能体应先判断客户端类型，再选择对应的输出格式：

客户端类型判定依据输出格式

桌面端 / Web（ArkClaw、OpenClaw、浏览器等）默认 HTML 表格（<table>、<img>、<video> 等，仅限 index.json 中 html_output.tags 声明的标签）

IM 手机应用（飞书、微信、钉钉、企业微信等）用户提到在飞书/微信/钉钉中使用，或上下文/系统信息表明客户端为 IM 应用 Markdown 表格（`

桌面端 HTML 模式注意事项：

不要将 HTML 放在代码围栏内（围栏内的标签不会被渲染，只会显示源码）

不要使用 <input type="checkbox">（静态 HTML 环境中无法交互）

不要使用 <button>（无 JS 运行环境，无法绑定事件）

所有媒体 URL（<img src>、<video src>）须通过下文「安全：媒体来源校验」

IM 手机端 Markdown 模式注意事项：

使用 Markdown 表格语法（| col |）

缩略图用 ![封面](cover_url) 或省略（手机屏幕窄时可不显示缩略图列）

视频预览无法内嵌，统一用 [▶ 预览](preview_url) 链接

不要输出 HTML 标签（手机 IM 不渲染 HTML，会直接显示标签源码）

通用规则：

选择操作通过用户发送文本指令完成（如「选 1,3」「购买」），智能体重新渲染带状态标记的表格

注：本文档内的 HTML 模板用代码块展示以防文档渲染器误执行；智能体输出给用户时应去掉代码围栏。详见下文「搜索结果展示」。

客户端类型	判定依据	输出格式
桌面端 / Web（ArkClaw、OpenClaw、浏览器等）	默认	HTML 表格（`<table>`、`<img>`、`<video>` 等，仅限 `index.json` 中 `html_output.tags` 声明的标签）
IM 手机应用（飞书、微信、钉钉、企业微信等）	用户提到在飞书/微信/钉钉中使用，或上下文/系统信息表明客户端为 IM 应用	Markdown 表格（`

安全：媒体来源校验

本 Skill 的 HTML 输出包含 <img>、<video> 等标签，客户端会直接向 src 地址发起请求。为防止向不可信主机泄露用户 IP / 元数据，智能体应在嵌入前校验媒体 URL 的来源：

可信来源列表：config.json 的 trusted_media_origins 数组（默认仅包含 api_origin）。
校验规则：<img src="...">、<video src="...">、<video poster="..."> 中的 URL 必须以 trusted_media_origins 中某一项开头（协议 + 主机 + 端口完全匹配）。
不符合时的处理：
- 若 cover_url（breviaryPic）不在可信列表 → 缩略图列显示「—」，不输出 <img>。
- 若 video_url（fragmentUrl）不在可信列表 → 视频预览列不输出 <video>，改为纯文本「[需在浏览器中打开]」+ preview_url 超链接（preview_url 始终为同源站内页面）。
API 响应中的 breviaryPic 和 fragmentUrl 均为完整绝对 URL（指向 wenzhou.data0086.com:9443），须检查是否在 trusted_media_origins 中。
trusted_media_origins 见 config.json，当前包含 https://www.data0086.com、https://test.data0086.com 和 https://wenzhou.data0086.com:9443。

简言之：只有 config 中声明的可信域名才允许直接嵌入媒体，其余一律用 preview_url 超链接代替。

目标

让智能体用自然语言检索数游神州平台（data0086.com）上的文旅素材资源。每条结果必须结构化保留下游交易要用的字段，尤其是 fragmentUrl（视频预览流）、commodityCode 和 businessCode。

用 解析后的搜索 URL 直接 POST 请求，并按本文「输出映射」组装标准 JSON。

流程总览：先调试「预览 → 选择/购买」

当前阶段（交易 API 未定时）：智能体优先走通 搜索 → 列表 → 预览 → 选择/购买 → Mock 交易返回 → 视频下载。不在此阶段调用真实交易接口；购买后 mock 交易返回数据（video_url 复用搜索 API 的 fragmentUrl），然后 将视频下载到本地 并输出文件路径。

真实交易 API：TRADE_API_BASE / trade_api_base 配置为非空后将替换 mock 流程（见「交易 API」）。当前为空 → 使用 mock + 下载。

智能体按顺序引导；上一步未就绪时不要进入下一步。用户可随时要求「重新搜索」。

主路径（调试优先）

步骤	行为要点
1. 搜索（两次调用）	针对同一关键词，智能体依次发起两次 `POST {api_origin}/ms-base/home/getList?pageNum=1&pageSize=3` 请求，合并结果：① 第 1 次：请求体 `commodityCode` 填 config.json 的 `finished_commodity_code`（当前 `CommodityType-7bf0aa3057bc`）。② 第 2 次：请求体 `commodityCode` 填 `null`。合并时按每条记录自身的 `commodityCode` 字段判定类别：若 `item.commodityCode === finished_commodity_code` → `category = "成片"`，否则 → `category = "素材"`。展示时可在标题后加 `<small>` 徽章区分。`pageSize` 对每次调用独立生效，默认 `3`（最多 5）；用户要更少时按用户数量传。保留 P0/P1 字段。
2. 列出结果	用表格展示（HTML 或 Markdown，取决于客户端类型），不要把工具/API 返回的整段 JSON 当作对用户的主回复（见下「搜索结果展示」与「展示与 JSON」）：列状态｜标题｜缩略图｜视频预览｜详情；首列用颜色徽章标记选中状态（非 checkbox）。表格下方附操作说明（见「选择与购买」）。
3. 预览	引导用户打开 `preview_url`（数游神州商品详情页 `/#/multimodal?businessCode=…`，统一处理视频播放）；可同时说明 `stream_type` 与原始 `video_url` 供技术核对。预览仅用于选片，不等于已购原片。
4. 选择 / 购买	支持两种操作模式，无需额外确认步骤：模式 A — 先选后买：用户先发送选择指令（「选 1、3」「全选」），智能体重新渲染表格标记选中状态；之后用户发送「购买」或「下单」，直接进入步骤 5，不再要求二次确认。模式 B — 直接购买：用户直接发送「购买 1,2」「下单 3」「买第1条」等包含序号的购买指令，智能体一步完成选中并立即进入步骤 5，跳过选择环节。⚠️ 禁止在用户发出购买指令后回复"接口未开放""暂不支持下单"等拒绝性文字——当前阶段购买指令的执行方式就是步骤 5 的 mock + 下载。用户在选择阶段可追加/移除（「加上第2条」「去掉第3条」），智能体每次都重新渲染完整表格。
5. Mock 交易返回 + 视频下载（必须执行）	用户发出购买/下单指令后，智能体必须立即执行以下操作，不得跳过或以"接口未就绪"为由拒绝：A. 构造 mock 交易响应：为每条选中素材生成 `{"code":0, "resData":{"video_url":"..."}}` ，其中 `video_url` = 该素材搜索结果的 `fragmentUrl`（预览地址）。B. 下载视频到本地：调用 `bash scripts/download_video.sh "<video_url>" "<output_path>" [HLS\|MP4]` 将视频保存到 `downloads/` 目录，文件名为 `{business_code}.mp4`。C. 输出本地文件路径：下载完成后向用户展示每条素材的 `local_path`。详见「购买后输出」。

搜索结果展示 — 根据客户端类型选择输出格式

输出前应先判断客户端类型，选择对应格式。

桌面端 / Web 客户端（HTML 模式）

客户端（ArkClaw / OpenClaw）支持 HTML 渲染。展示搜索结果时，直接输出 HTML 标签（仅限 index.json 中 html_output.tags 声明的标签）。

注意事项（HTML 模式）：

不要使用 <input type="checkbox"> 或 <button>（聊天气泡无 JS，无法交互）

不要把 HTML 放在代码块里（代码块只会显示源码，不会渲染）

所有 <img src> 和 <video src> 的 URL 须属于 trusted_media_origins（见「安全：媒体来源校验」）

正确做法：在回复中直接书写 HTML 标签，不加代码围栏，让客户端渲染。选择状态用颜色徽章表示，用户通过发送文本指令选择/购买。（本文档内的模板为防止文档自身渲染 <video> 导致页面刷新，使用了代码块包裹——这仅限于文档展示，智能体输出时应去掉代码围栏。）

IM 手机应用（Markdown 模式）

飞书、微信、钉钉等 IM 手机应用不渲染 HTML，会将标签作为纯文本显示。此时应使用 Markdown 表格。

注意事项（Markdown 模式）：

不要输出 HTML 标签（手机 IM 会直接显示标签源码）

不要把表格放在代码围栏内

正确做法：使用 Markdown 表格语法，缩略图用 ![](url) 或省略，预览链接用 [▶ 预览](preview_url)。

表格列定义（固定五列）

表格之前必须输出一行类别汇总，格式示例： 🎬 共找到 **5** 条资源：成片 **2** 条｜素材 **3** 条 即便成片为 0 也要明示 成片 0 条，以表明已执行两次搜索。

HTML 模式（桌面端 / Web）：

列名	HTML 元素	内容
状态	`<span>` 带背景色	未选中：灰底序号 `<span style="background:#e0e0e0;padding:2px 8px;border-radius:4px;">1</span>`；选中：绿底 ✅ `<span style="background:#67c23a;color:#fff;padding:2px 8px;border-radius:4px;">✅ 1</span>`
标题	纯文本 + `<small>` + 类别徽章	title + 必标类别徽章：成片 → `<small style="background:#f56c6c;color:#fff;padding:1px 6px;border-radius:3px;margin-left:4px;">成片</small>`素材 → `<small style="background:#909399;color:#fff;padding:1px 6px;border-radius:3px;margin-left:4px;">素材</small>`可附 `<br><small style="color:#999;">id</small>`
缩略图	`<img src="..." width="120">`	cover_url；无封面写「—」
视频预览	`<video controls width="240" poster="..." src="...">`	src 用 video_url（fragmentUrl），poster 用 cover_url
详情	纯文本 + `<a href="...">`	分辨率/时长/大小，附 preview_url 超链接兜底

Markdown 模式（IM 手机端）：

列名	Markdown 写法	内容
状态	纯文本序号或 ✅	未选中：`1`；选中：`✅ 1`
标题	纯文本 + 类别前缀	必标类别：`【成片】title` 或 `【素材】title`（即使列表只有一类也要标）
缩略图	`![封面](cover_url)` 或省略	手机屏幕窄时可不显示此列
预览	`[▶ 预览](preview_url)`	链接到站内播放页
详情	纯文本	分辨率/时长/大小

选择与购买（表格下方操作区）

表格下方直接输出操作提示 HTML。

注意：以下模板在本文档中用代码块展示，防止文档渲染器误执行。智能体输出给用户时应去掉代码围栏，直接输出 HTML。

核心规则：无需二次确认，购买 = mock 交易 + 下载视频

「购买 1,2」「下单 3」等带序号的购买指令→ 直接选中 → 立即执行 mock 交易返回 + 视频下载到本地 + 输出文件路径，一步到位

「选 1,3」→ 仅标记选中，渲染表格；之后用户说「购买」/「下单」→ 立即执行 mock + 下载

不要在用户已发出购买指令后再要求「请确认」或「确认购买」

不要回复"接口未开放""暂不支持""请到官网购买"——当前阶段购买就是 mock + 下载

初始状态（无选中）— HTML 模式：

<div style="background:#f6f8fa; border-left:4px solid #409eff; padding:10px 14px; margin:10px 0; border-radius:4px;">
<b>💡 操作说明</b><br>
· 回复「<b>购买 1、3</b>」或「<b>下单 2</b>」直接购买并下载视频到本地<br>
· 回复「选 1、3」先标记，之后回复「<b>购买</b>」一键下载<br>
· 回复「取消 3」取消已选
</div>

初始状态（无选中）— Markdown 模式（IM 手机端）：

💡 **操作说明**
· 回复「**购买 1、3**」或「**下单 2**」直接购买并下载视频到本地
· 回复「选 1、3」先标记，之后回复「**购买**」一键下载
· 回复「取消 3」取消已选

有选中时 — HTML 模式：

<div style="background:#f0f9eb; border-left:4px solid #67c23a; padding:10px 14px; margin:10px 0; border-radius:4px;">
✅ 已选 <b>N</b> 条素材 | 总时长 XXs | 总大小 <b>XXXM</b><br><br>
👉 回复「<b>购买</b>」或「<b>下单</b>」立即购买并下载到本地<br>
👉 回复序号可继续追加或取消选择
</div>

有选中时 — Markdown 模式（IM 手机端）：

✅ 已选 **N** 条素材 | 总时长 XXs | 总大小 **XXXM**
👉 回复「**购买**」或「**下单**」立即购买并下载到本地
👉 回复序号可继续追加或取消选择

当用户发送选择指令后，智能体重新渲染完整表格：

选中行首列显示绿色 ✅ 徽章，行背景加 style="background:#f0f9eb;"
未选行首列显示灰色序号徽章
表格下方显示选中汇总 + 购买提示

展示与 JSON（必读）

对用户：搜索列表的默认形态是表格（桌面端用 HTML 表格，IM 手机端用 Markdown 表格）。禁止用 JSON 代码块替代。
对程序/联调：若用户明确说「给我原始 JSON」「导出结构」或已进入购买阶段，再按「标准结果 JSON 形状」或「购买后输出」给出 JSON。
条数：URL 参数 pageSize 默认传 5（上限），用户要求更少时按用户数量传；若接口返回超出请求数量，只取前 N 条映射为表格。

完整输出模板（直接复制替换真实值）

智能体输出搜索结果时，按照以下模板逐行输出 HTML，将 {变量} 替换为真实值。

注意：以下模板在本文档中用代码块展示，防止文档渲染器误加载 <video>/<img> 导致页面刷新。智能体输出给用户时应去掉代码围栏，直接输出 HTML 标签。

初始状态（全部未选中）— HTML 模式：

<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse; width:100%;">
<thead style="background:#f5f7fa;">
<tr><th>状态</th><th>标题</th><th>缩略图</th><th>视频预览</th><th>详情</th></tr>
</thead>
<tbody>
<tr>
<td><span style="background:#e0e0e0;padding:2px 8px;border-radius:4px;">1</span></td>
<td>{title}<br><small style="color:#999;">{id}</small></td>
<td><img src="{cover_url}" width="120"></td>
<td><video controls width="240" poster="{cover_url}" src="{video_url}"></video></td>
<td>{resolution}<br>{duration_seconds}s / {file_size}<br><a href="{preview_url}">浏览器播放</a></td>
</tr>
<tr>
<td><span style="background:#e0e0e0;padding:2px 8px;border-radius:4px;">2</span></td>
<td>{title}<br><small style="color:#999;">{id}</small></td>
<td><img src="{cover_url}" width="120"></td>
<td><video controls width="240" poster="{cover_url}" src="{video_url}"></video></td>
<td>{resolution}<br>{duration_seconds}s / {file_size}<br><a href="{preview_url}">浏览器播放</a></td>
</tr>
</tbody>
</table>
<div style="background:#f6f8fa; border-left:4px solid #409eff; padding:10px 14px; margin:10px 0; border-radius:4px;">
<b>💡 操作说明</b><br>
· 回复「<b>购买 1、3</b>」或「<b>下单 2</b>」直接购买指定素材<br>
· 回复「选 1、3」先标记，之后回复「<b>购买</b>」一键下单
</div>

初始状态（全部未选中）— Markdown 模式（IM 手机端）：

| 状态 | 标题 | 预览 | 详情 |
|------|------|------|------|
| 1 | {title} | [▶ 预览]({preview_url}) | {resolution} / {duration_seconds}s / {file_size} |
| 2 | {title} | [▶ 预览]({preview_url}) | {resolution} / {duration_seconds}s / {file_size} |

💡 **操作说明**
· 回复「**购买 1、3**」或「**下单 2**」直接购买指定素材
· 回复「选 1、3」先标记，之后回复「**购买**」一键下单

选中第 1、2 条后（用户发送「选 1,2」后智能体重新渲染）— HTML 模式：

<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse; width:100%;">
<thead style="background:#f5f7fa;">
<tr><th>状态</th><th>标题</th><th>缩略图</th><th>视频预览</th><th>详情</th></tr>
</thead>
<tbody>
<tr style="background:#f0f9eb;">
<td><span style="background:#67c23a;color:#fff;padding:2px 8px;border-radius:4px;">✅ 1</span></td>
<td>{title}</td>
<td><img src="{cover_url}" width="120"></td>
<td><video controls width="240" src="{video_url}"></video></td>
<td>{resolution}<br>{duration_seconds}s / {file_size}</td>
</tr>
<tr style="background:#f0f9eb;">
<td><span style="background:#67c23a;color:#fff;padding:2px 8px;border-radius:4px;">✅ 2</span></td>
<td>{title}</td>
<td><img src="{cover_url}" width="120"></td>
<td><video controls width="240" src="{video_url}"></video></td>
<td>{resolution}<br>{duration_seconds}s / {file_size}</td>
</tr>
</tbody>
</table>
<div style="background:#f0f9eb; border-left:4px solid #67c23a; padding:10px 14px; margin:10px 0; border-radius:4px;">
✅ 已选 <b>2</b> 条素材 | 总时长 236.6s | 总大小 <b>273.9M</b><br><br>
👉 回复「<b>购买</b>」或「<b>下单</b>」立即下单<br>
👉 回复序号可追加或取消选择
</div>

选中第 1、2 条后 — Markdown 模式（IM 手机端）：

| 状态 | 标题 | 预览 | 详情 |
|------|------|------|------|
| ✅ 1 | {title} | [▶ 预览]({preview_url}) | {resolution} / {duration_seconds}s / {file_size} |
| ✅ 2 | {title} | [▶ 预览]({preview_url}) | {resolution} / {duration_seconds}s / {file_size} |

✅ 已选 **2** 条素材 | 总时长 236.6s | 总大小 **273.9M**
👉 回复「**购买**」或「**下单**」立即下单
👉 回复序号可追加或取消选择

其中：

{preview_url} = {api_origin}/#/multimodal?businessCode={businessCode}（数游神州商品详情页）。
{cover_url} = breviaryPic（已是完整 URL），{video_url} = fragmentUrl。嵌入前须校验来源属于 trusted_media_origins（见「安全：媒体来源校验」），不符合则不输出 <img> / <video>。

❌ 错误输出 vs ✅ 正确输出

错误（HTML 模式下使用 checkbox / 代码围栏）：

| □ | # | 标题 | 缩略图 | 预览 |
|---|---|------|--------|------|
| □ | 1 | 雁荡山素材 | [封面](url) | [预览 · HLS](url) |

或使用 <input type="checkbox">（渲染出来但无法勾选）、<button>（无法点击触发）。

错误（IM 手机端输出 HTML 标签）： 在飞书/微信中输出 <table><tr><td>... — 用户看到的是一堆 HTML 源码文本。

✅ 正确 — HTML 模式（桌面端 / Web，无代码围栏）：

智能体回复中应直接包含如下 HTML（不被 ``` 包裹）：

<table border="1" cellpadding="6" cellspacing="0" style="border-collapse:collapse; width:100%;"> <tr> <td><span style="background:#e0e0e0;padding:2px 8px;border-radius:4px;">1</span></td> <td>雁荡山素材</td> <td><img src="https://…/cover.jpg" width="120"></td> <td><video controls width="240" src="https://…/index.m3u8"></video></td> <td>2560×1440<br>118.5s / 98.3M</td> </tr> </table>

✅ 正确 — Markdown 模式（IM 手机端）：

状态	标题	预览	详情
1	雁荡山素材	▶ 预览	240.9s / ¥45

`<video>` 标签用法

src 必须用 video_url（即 fragmentUrl，实际媒体流），不是 preview_url（商品详情页）。
来源校验：嵌入前须确认 video_url 的来源在 trusted_media_origins 中（见「安全：媒体来源校验」）。不在列表中 → 不输出 <video>，改用 preview_url 超链接。
poster 用 cover_url（封面图）。无封面时省略 poster。同样须通过来源校验。
MP4：浏览器原生支持。
HLS（m3u8）：Safari 原生支持；Chrome 依赖客户端 hls.js。若 <video> 无法播放，详情列的 preview_url 链接兜底。

预览与本地播放（能力边界）

SKILL 无法在对话气泡内嵌入可执行的 HLS 播放器（多数客户端会拦截脚本、iframe，且 OpenClaw / 飞书等需产品侧组件才能内嵌播放）。本 Skill 通过下列方式支持用户在本机观看预览：

浏览器打开 preview_url（推荐）
- 数游神州商品详情页已统一处理视频播放，用户直接点击表格中的「预览」链接即可。
- 若需在系统播放器中打开原始流，再使用 video_url + stream_type（见下文）。
仅当无可用 HTML 播放页、且必须直接拉流时：再考虑 video_url
- stream_type 为 MP4：多数浏览器可直接打开直链。
- stream_type 为 HLS：裸 m3u8 在 Chrome 常下载或无法播放；Safari 相对友好。
- 智能体应优先推 preview_url，避免向非技术用户丢裸 m3u8 链。
本仓库脚本（本地用浏览器打开某 URL）
- 路径：scripts/open_preview.sh（相对本 Skill 根目录）。
- 用法：优先 bash scripts/open_preview.sh "<preview_url>" MP4（播放页为 HTML 时按 HTTP 打开即可）；若需直接拉流，再传入 video_url 与 HLS/MP4。
- 适用于 Cursor / 终端；飞书/OpenClaw 仍以点击 preview_url 为主。
可选：本机播放器（原始流）
- VLC / ffplay 可粘贴 video_url；日常选片以 preview_url 为主。

飞书 / OpenClaw：卡片按钮 URL 与表格一致，指向 preview_url（即 {api_origin}/#/multimodal?businessCode={businessCode}）；若产品另有独立 H5 域名，以产品为准，但须能播同一条素材。

购买后输出（调试 / 联调）⚠️ 必须执行

强制规则：用户发出「购买」「下单」等购买指令后，智能体必须立即执行下述步骤 A + B。禁止回复"交易接口未开放""暂不支持""请到官网购买"等拒绝性、引导性文字。当前阶段的"购买"就是 mock + 下载。

触发条件：仅当用户显式发送「购买」「下单」「买第 N 条」等购买指令时触发，搜索、浏览、预览阶段不写入任何本地文件。

在未接真实交易 API 时，用户发出购买指令后智能体执行以下两步：

步骤 A：构造 Mock 交易响应

为每条选中素材构造 mock 交易返回数据。核心字段 video_url 直接复用搜索 API 返回的 fragmentUrl（预览地址），模拟交易成功后服务端返回的视频下载链接。

单条 mock 交易响应示例：

{
  "code": 0,
  "msg": "mock: 交易成功（模拟）",
  "resData": {
    "video_url": "https://wenzhou.data0086.com:9443/res/hls/preview/product/77758f136a4648888d1acd615ec24dbe"
  }
}

说明：video_url 的值 = 搜索结果中该素材的 fragmentUrl。当交易 API 真正上线后，此字段将由服务端返回真实的原片/授权下载地址。

批量购买时，智能体为每条素材分别构造一个 mock 响应，汇总后输出完整的购买结果 JSON：

{
  "stage": "purchase_mock_completed",
  "items": [
    {
      "id": 459,
      "title": "雁荡山-飞拉达雾天-一镜到底-无人机航拍",
      "commodity_code": "CommodityType-e744a1044794",
      "business_code": "Commodity-20260406211854879",
      "video_url": "https://wenzhou.data0086.com:9443/res/hls/preview/product/77758f136a4648888d1acd615ec24dbe",
      "stream_type": "HLS",
      "duration_seconds": "240.9",
      "price": 45.0,
      "local_path": ""
    },
    {
      "id": 461,
      "title": "雁荡山-飞拉达-云雾多视频2-无人机航拍",
      "commodity_code": "CommodityType-948a39e64144",
      "business_code": "Commodity-20260406212609534",
      "video_url": "https://wenzhou.data0086.com:9443/res/hls/preview/product/b68efe02182c436dbcf35f045b94ed30",
      "stream_type": "HLS",
      "duration_seconds": "30.5",
      "price": 45.0,
      "local_path": ""
    }
  ],
  "summary": {
    "total_items": 2,
    "total_duration_seconds": "271.4",
    "total_price": 90.0
  }
}

local_path 在步骤 B 下载完成后填入。

步骤 B：视频下载到本地

获得 mock 交易响应中的 video_url 后，智能体 调用下载脚本将视频保存到本地。

下载目录：downloads/（位于 Skill 根目录下；不存在时自动创建）。也可通过 config.json 的 download_dir 配置。
文件命名：{business_code}.{ext}（如 Commodity-20260406211854879.mp4）。扩展名由 stream_type 决定：MP4 → .mp4；HLS → .mp4（ffmpeg 转封装后输出）。
下载命令：调用 bash scripts/download_video.sh "<video_url>" "<output_path>" [HLS|MP4]。
- MP4：直接用 curl 下载。
- HLS：用 ffmpeg 下载 m3u8 并转封装为 MP4（需本机安装 ffmpeg）。
输出：下载完成后，将 local_path 填入结果 JSON 并向用户输出文件路径。

下载完成后的最终输出示例：

{
  "stage": "download_completed",
  "items": [
    {
      "id": 459,
      "title": "雁荡山-飞拉达雾天-一镜到底-无人机航拍",
      "commodity_code": "CommodityType-e744a1044794",
      "business_code": "Commodity-20260406211854879",
      "video_url": "https://wenzhou.data0086.com:9443/res/hls/preview/product/77758f136a4648888d1acd615ec24dbe",
      "stream_type": "HLS",
      "local_path": "downloads/Commodity-20260406211854879.mp4",
      "duration_seconds": "240.9",
      "price": 45.0
    },
    {
      "id": 461,
      "title": "雁荡山-飞拉达-云雾多视频2-无人机航拍",
      "commodity_code": "CommodityType-948a39e64144",
      "business_code": "Commodity-20260406212609534",
      "video_url": "https://wenzhou.data0086.com:9443/res/hls/preview/product/b68efe02182c436dbcf35f045b94ed30",
      "stream_type": "HLS",
      "local_path": "downloads/Commodity-20260406212609534.mp4",
      "duration_seconds": "30.5",
      "price": 45.0
    }
  ],
  "summary": {
    "total_items": 2,
    "total_duration_seconds": "271.4",
    "total_price": 90.0,
    "downloaded": 2,
    "failed": 0
  }
}

向用户展示时，在 JSON 之前/之后用自然语言说明：

已完成 2 条素材的模拟购买与下载：

雁荡山-飞拉达雾天-一镜到底-无人机航拍 → downloads/Commodity-20260406211854879.mp4

雁荡山-飞拉达-云雾多视频2-无人机航拍 → downloads/Commodity-20260406212609534.mp4

错误处理：若某条素材下载失败（网络错误、ffmpeg 未安装等），local_path 设为空字符串 ""，summary.failed 计数 +1，并向用户说明失败原因与重试建议。

单条选择同样使用此结构（items 数组长度为 1），保持输出格式统一。

交易 API（预留，未来替换 mock）

以下仅在 TRADE_API_BASE 或 trade_api_base 已配置为非空值 且产品已约定路径/鉴权后执行。

基址：环境变量 TRADE_API_BASE 优先；否则 config.json 的 trade_api_base 非空字符串。
调用：用已锁定资源的 id、commodityCode、businessCode 按产品约定发起请求；鉴权勿泄露到对话。
接入后替换 mock：交易 API 上线后，步骤 A 的 mock 响应将被真实接口响应替换；video_url 以服务端返回为准。步骤 B 的下载逻辑保持不变。

当前状态：trade_api_base 为空 → 不调用真实交易 API，但必须执行 mock + 下载流程（见上文「购买后输出」）。绝不能因为交易 API 未就绪就拒绝用户的购买指令。

API 基址配置（可更换）

单一默认值：与本 Skill 同目录的 config.json（api_origin + search_path）。

解析规则：

若存在环境变量 WENLV_API_ORIGIN（仅站点根，如 https://test.data0086.com），则以其为 api_origin。
否则使用 config.json 中的 api_origin。
search_url = api_origin（去掉末尾 /）+ search_path（默认 /ms-base/home/getList）+ ?pageNum={pageNum}&pageSize={pageSize}。

项目	说明
基址	`{api_origin}`，当前值见 config.json（`https://test.data0086.com`）
搜索	`POST {api_origin}/ms-base/home/getList?pageNum=1&pageSize=5`
鉴权	无（公开接口，`token` 头可为空）
Content-Type	`application/json`

换环境时：改 config.json 或部署侧设置 WENLV_API_ORIGIN 即可，无需改 Skill 正文中的长 URL。交易相关另设 TRADE_API_BASE 或 config.json 的 trade_api_base（非空时生效）。

详情页地址（用户点击「预览」）⚠️ 拼接规则

统一使用数游神州前端的商品详情页（与原始 fragmentUrl 区分）。

拼接公式（唯一正确形式）：

preview_url = {api_origin} + {detail_path} + "?businessCode=" + {businessCode}

api_origin：WENLV_API_ORIGIN 或 config.json 的 api_origin（当前 https://test.data0086.com，无末尾 /）。
detail_path：默认 /#/multimodal（见 config.json 的 detail_path）。
businessCode：搜索结果中每条素材的 businessCode 字段。

✅ 正确格式：

https://test.data0086.com/#/multimodal?businessCode=Commodity-20260406211854879

❌ 错误格式 —— 不要用 fragmentUrl 当预览链接：

https://wenzhou.data0086.com:9443/res/hls/preview/product/77758f136a4648888d1acd615ec24dbe

表格「预览」列、飞书卡片按钮、OpenClaw 内链均应使用 preview_url（商品详情页）。video_url（fragmentUrl）仍须保留在结构化结果中，供交易、调试与核对原始流。

播放页与裸流（必读：避免一点就下载 m3u8）

video_url（fragmentUrl） 指向的是 媒体流（常见为 HLS 预览地址），不是给用户点的「网页预览」。在 Markdown 里若写成 [预览](video_url)，浏览器对 HLS 往往会 下载 m3u8 或无法内联播放。禁止将 video_url 作为表格「预览」列或卡片按钮的主链接。
preview_url 对应数游神州的商品详情页（SPA 页面，内含视频播放器），用户点击后在浏览器页面里播放，而不是下载清单文件。
映射：preview_url 一律只由 {api_origin}{detail_path}?businessCode={businessCode} 按上文公式拼接（见 config.json），不得把 fragmentUrl 填进 preview_url，也不得用 video_url 顶替。

请求 URL 参数

分页通过 URL query 传递：

参数	必填	说明
`pageNum`	否	页码，默认 1
`pageSize`	否	每页条数，接口默认 18；智能体侧默认传 `5`（上限），用户要求更少时按用户数量传（如 1、2、3）

请求体

{
  "commodityCode": null,
  "sceneType": "",
  "tradeType": "",
  "search": "雁荡山飞拉达",
  "city": "330300"
}

字段	必填	说明
`search`	是	关键词，支持中文自然语言
`city`	否	城市行政区划代码，默认 `"330300"`（温州）
`commodityCode`	否	按商品编码精确筛选。本 Skill 通过此字段区分「成片 / 素材」两类资源（见下）
`sceneType`	否	场景类型筛选，如 `"慢直播"`，默认 `""`
`tradeType`	否	交易类型筛选，如 `"cash"`，默认 `""`

两次搜索：成片 + 素材

同一关键词下，本 Skill 依次发起两次搜索，并按"成片优先 50:50"配比分配条数：

pageSize 分配（用户想要总数 N，默认 3，上限 5）：

顺序	请求 `commodityCode`	URL `pageSize`
第 1 次（成片）	config.json 的 `finished_commodity_code`（当前 `CommodityType-7bf0aa3057bc`）	`ceil(N / 2)`
第 2 次（素材）	`null`	`floor(N / 2)`（为 0 则跳过）

配比参考表（N=1~5）：

N	成片	素材
1	1	0
2	1	1
3	2	1
4	2	2
5	3	2

兜底补齐：某一类返回不足时（如成片只返回 1 条而期望 2 条），用另一类补齐，总条数尽量达到 N。

类别判定规则（核心）：

以返回的每条记录自身的 commodityCode 字段为准，而不是按哪一次调用：

if item.commodityCode === finished_commodity_code:
    item.category = "成片"
else:
    item.category = "素材"

这样即便两次调用返回数据有重复或交叉，最终每条记录的类别依然由其自身 commodityCode 决定，去重与标记逻辑一致。

合并策略：

两次调用按配比表分配 pageSize（不是各自独立的 N）。
合并两次返回的 resData.datas，按 businessCode 或 id 去重（避免两次调用返回同一条记录时重复展示）。
按上述判定规则为每条记录打 category 标签。
排序：成片在前、素材在后；同类内部保留接口返回顺序。
若某一类无数据，用另一类兜底补齐到 N 条；两类都无数据时，向用户说明"未找到相关资源"。

展示要求（强制）：

汇总行（必须，统计口径以 category 字段为准）：
- 格式示例：📽 共找到 5 条资源：**成片 3 条** | **素材 2 条**
- 即使某类为 0 也要写出（如 📽 共找到 3 条资源：**成片 0 条** | **素材 3 条**），让用户知道两次搜索确实都执行过。
- ⚠️ 统计算法：成片条数 = 表格里 category == "成片" 的行数、素材条数 = 表格里 category == "素材" 的行数；不要按"请求参数里 commodityCode 是什么"来算，以免出现"请求成片 3 条但返回的有 1 条实际是素材"时汇总错位。
- 自检：汇总行的 X 和 Y 必须等于表格里实际打 【成片】/【素材】 徽章的行数，加起来 = 总条数。
类别徽章（必须，每行都标）：
- HTML 模式：标题旁追加 <small style="background:#f56c6c;color:#fff;padding:1px 6px;border-radius:3px;margin-left:4px;">成片</small> 或 <small style="background:#909399;color:#fff;padding:1px 6px;border-radius:3px;margin-left:4px;">素材</small>
- Markdown 模式：标题前加 【成片】 或 【素材】 文本前缀
- 不允许只在混合类型时才标注；即使全部是同一类别也要每行标出。

finished_commodity_code 可配置：

修改 config.json 的 finished_commodity_code 即可调整成片归类的商品编码，无需改 Skill 正文。
值为空字符串或未配置时，跳过第 1 次搜索，仅按「素材」单次搜索——此时所有返回记录都标记为 category: "素材"。

响应约定

业务成功：code === 0，列表在 resData.datas，总数 resData.total。
HTTP 非 2xx 或 code !== 0：向用户说明错误，勿伪造结果。

更完整的原始字段说明见 references/api_reference.md。标准接口规范（含交易下单）见 api.md。

字段优先级

P0 — 核心（交易直连，缺一不可）

来源字段	输出键名	说明
`id`	`id`	素材唯一 ID（数字）
`commodityName`	`title`	标题
`fragmentUrl`	`video_url`	原始预览流（HLS），交易/核对用，表格「预览」列不用作主链
`commodityCode`	`commodity_code`	商品编码，交易下单必需
`businessCode`	`business_code`	业务编码，交易下单必需，也用于详情页 URL

派生（必选，用于展示与点击）

派生规则	输出键名	说明
`{api_origin}{detail_path}?businessCode={businessCode}`	`preview_url`	表格「预览」列、卡片按钮统一用此链接（商品详情页）；`detail_path` 默认 `/#/multimodal`，见 config.json

同时必须输出 stream_type（由 video_url / fragmentUrl 判定）：

URL 含路径片段 /hls/ → "HLS"（需 HLS 播放器，如 hls.js）
URL 以 .mp4 结尾 → "MP4"（浏览器可直接播）
若 fragmentUrl 为空：不要编造 video_url；可省略 stream_type 或标为无法判定（勿写假链接）

P1 — 重要（展示与交易辅助）

来源	输出键名
`explain`	`description`（HTML 格式，包含清晰度/格式等信息）
`fragmentTime`	`duration_seconds`（建议保留一位小数，字符串或数字均可）
`price`	`price`（元）
`breviaryPic`	`cover_url`：已是完整 URL，嵌入前须属于 `trusted_media_origins`
`sceneType`	`scene_type`（逗号分隔的场景类型）
`tag`（JSON.parse）	`tags`：逗号分隔或数组
`createUser`	`merchant`（商家名称）

P2 — 辅助（可选）

videoProductCode、contactName、contactPhone、merchantBusinessCode、priceJson、location 等，在用户需要排查或对接数据源时再输出。

标准结果 JSON 形状（解析/转发用）

智能体整理输出时，每条结果建议符合：

{
  "total": 185,
  "pageNum": 1,
  "pageSize": 5,
  "results": [
    {
      "#": "1",
      "id": 459,
      "title": "雁荡山-飞拉达雾天-一镜到底-无人机航拍",
      "commodity_code": "CommodityType-e744a1044794",
      "business_code": "Commodity-20260406211854879",
      "preview_url": "https://test.data0086.com/#/multimodal?businessCode=Commodity-20260406211854879",
      "video_url": "https://wenzhou.data0086.com:9443/res/hls/preview/product/77758f136a4648888d1acd615ec24dbe",
      "stream_type": "HLS",
      "duration_seconds": "240.9",
      "price": 45.0,
      "cover_url": "https://wenzhou.data0086.com:9443/res/covers/77758f136a4648888d1acd615ec24dbe.jpg",
      "scene_type": "慢直播,创作素材,无人机航拍",
      "tags": "视频创作, 无人机航拍",
      "merchant": "温州鼎诚体育发展有限公司"
    }
  ]
}

curl 示例

默认站点根须与 config.json 中 api_origin 保持一致（换域名时改 config 并同步下面默认值，或只用 export）。

# 环境变量优先；未设置时读取 config.json 的 api_origin（当前为 https://test.data0086.com）
ORIGIN="${WENLV_API_ORIGIN:-https://test.data0086.com}"
FINISHED_CODE="CommodityType-7bf0aa3057bc"  # config.json finished_commodity_code

# 第 1 次：成片
curl -sS "${ORIGIN}/ms-base/home/getList?pageNum=1&pageSize=5" \
  -H 'Content-Type: application/json' \
  -H "Origin: ${ORIGIN}" \
  -H "Referer: ${ORIGIN}/" \
  -H 'token;' \
  --data-raw "{\"commodityCode\":\"${FINISHED_CODE}\",\"sceneType\":\"\",\"tradeType\":\"\",\"search\":\"雁荡山\",\"city\":\"330300\"}"

# 第 2 次：素材
curl -sS "${ORIGIN}/ms-base/home/getList?pageNum=1&pageSize=5" \
  -H 'Content-Type: application/json' \
  -H "Origin: ${ORIGIN}" \
  -H "Referer: ${ORIGIN}/" \
  -H 'token;' \
  --data-raw '{"commodityCode":null,"sceneType":"","tradeType":"","search":"雁荡山","city":"330300"}'

合并两次返回的 resData.datas（按 businessCode/id 去重），然后对每条记录按其自身的 commodityCode 判定：commodityCode === finished_commodity_code → category = "成片"，否则 → category = "素材"。最终输出 results 数组（成片在前、素材在后）。

智能体行为要点

须同时保留 preview_url（详情列超链接兜底）与 video_url（<video> 播放源）；列表展示须用五列表格：状态（颜色徽章）｜标题｜缩略图｜视频预览｜详情（见「搜索结果展示」）。桌面端用 HTML 表格，IM 手机端用 Markdown 表格。不要使用 <input>、<button> 等需要 JS 交互的元素。
面向用户的列表：桌面端以 HTML 表格 为主（含颜色徽章状态、<img>、<video> 元素），IM 手机端以 Markdown 表格 为主；结构化字段在表格列中体现。不要用整段 JSON 代替表格。仅在用户索要导出、或购买后的约定 JSON 块中再输出 JSON。
分页：默认只拉第 1 页且 pageSize 默认 5（上限），用户要求更少时按用户数量传；用户要「更多」时递增 pageNum，注意 total 边界。跨页选择：翻页时保留已选中条目；若用户在第 1 页选了第 1、3 条，翻到第 2 页后再选第 2 条，最终选中列表包含累计选中的所有条目。
两次搜索 + 成片优先配比（每次搜索都必须执行，无例外）：不管是用户第 1 次搜索还是第 N 次搜索、同一关键词还是换关键词，智能体对每一次搜索都顺序发起两次 POST，按 50:50 成片优先 配比分配 pageSize：
- 成片：commodityCode = config.finished_commodity_code，pageSize = ceil(N / 2)
- 素材：commodityCode = null，pageSize = floor(N / 2)
- 示例：N=3 → 成片 2 条 + 素材 1 条；N=5 → 成片 3 条 + 素材 2 条
- 禁止因为"已经搜过""连续搜索""结果相似"等理由跳过成片那次调用
- 合并两次返回的 datas（按 businessCode/id 去重），按每条记录自身的 commodityCode 判定 category；某类不足时用另一类兜底补齐到 N 条
- 展示时强制输出：(a) 汇总行 📽 共找到 N 条资源：成片 X 条 | 素材 Y 条，X/Y 必须按 category 字段统计而非请求参数，即便 X=0 也要写；(b) 每行标题带 【成片】/【素材】 徽章
- finished_commodity_code 为空时才可跳过第一次调用，汇总行写明 未配置 finished_commodity_code，仅搜素材
- 详见「两次搜索：成片 + 素材」
预览与成单分离：用户点击的预览必须是 preview_url（商品详情页），不要把 video_url（HLS 流） 做成主链接以免下载或无法播放。预览仅用于选片。当前调试阶段：用户发出购买指令后，智能体必须执行 mock 交易 + 视频下载（步骤 5），不得以"接口未就绪"为由拒绝或引导用户去官网手动购买。
交易安全（启用交易 API 后）：不在对话中输出完整密钥；失败时返回接口错误摘要，不猜测成功。
多选与购买（无需二次确认）：支持两种下单方式：① 直接购买——用户发送「购买 1,3」「下单 2」等带序号的购买指令，智能体一步完成选中 + mock 交易 + 视频下载；② 先选后买——用户先「选 1,3」标记，再发送「购买」/「下单」直接执行 mock 交易 + 下载，不再要求二次确认。选择过程中用户可随时追加（「加上第2条」）或移除（「取消 3」），智能体每次都重新渲染完整表格，用绿色/灰色徽章标记选中状态。
Mock 交易与视频下载：购买确认后，智能体构造 mock 交易响应（video_url = 搜索结果的 fragmentUrl），然后调用 scripts/download_video.sh 将视频下载到 downloads/ 目录（HLS 用 ffmpeg 转 MP4，MP4 用 curl 直接下载），最终向用户输出每条素材的本地文件路径。详见「购买后输出」。
交互约束：聊天气泡是静态 HTML（无 JavaScript），禁止使用 <input>、<button>、<form> 等需要 JS 交互的元素。所有用户操作通过发送文本消息完成，智能体解析后重新渲染表格。
客户端适配：智能体应根据客户端类型选择输出格式（HTML 或 Markdown）。判定方式见文首「输出格式规范」。若无法确定客户端类型，默认使用 HTML 模式；当用户反馈看到 HTML 源码时，切换为 Markdown 模式。

具体包名与发布流程以实际 npm 包为准；本 Skill 约束 行为、配置解析顺序、API 路径与输出字段。

搜索流程说明（每次搜索都适用）

购买流程说明（当前调试阶段）

culturetour-search

文旅素材搜索（API）