Skip to main content
Glama
Ekko Studio Travel Plugin

Ekko Studio Travel Plugin

Official
by EKKOLearnAI
README.md
# Ekko Studio 旅行插件

用 Studio 内置浏览器中的已有登录态运行固定站点脚本,采集、清洗酒店展示报价和图文攻略,再通过 MCP 工具把结构化数据交给 AI。

当前是 **v0.2 酒店查询调试版**。新增按城市、地址/商圈/地标、入住和离店日期查询酒店,及本批展示价预算筛选。保留图文采集、价格规范化、来源追溯及失败状态;手机定位、附近美食、路线规划和完整酒店比价尚未实现。

```text
Studio 内置浏览器 → 浏览器 SDK / CDP → 站点脚本 → 契约校验与清洗 → MCP 工具 → AI 整理
```

常规采集不调用模型,不依赖 AI 自动点击。登录及站点要求的验证由用户在浏览器中完成。

## 来源与当前边界

| 来源 | 当前能力 | 边界 |
| --- | --- | --- |
| 携程酒店 | 固定脚本按城市/地址查询;核对日期后采集卡片;无 DOM 匹配时使用固定无障碍树适配器 | 地点与关键词模式分开;预算仅筛本批展示价;缺少完整房型/费用条件 |
| 小红书 | 图文列表摘要与详情页文字 | 列表不是全文;未处理图片 OCR 和视频 |
| 携程攻略、马蜂窝 | 预置入口与正文选择器 | 尚未完成真实页面验证 |
| 美团 | 预置调试入口、阻断识别 | 调试过的酒店入口返回 403;不能据此判断所有美团网页均不可用 |

真实页面调试曾获得携程酒店展示报价和小红书搜索摘要;酒店查询另在内置浏览器手动确认了城市切换、地点/地址关键词提交及日期参数。它们不代表最终固定脚本已在真实站点通过 SDK 完成回归。最终实现仅使用公开 `run.host.browser` SDK,仍需在包含本地浏览器接入修复的 Desktop 版本上验证。自动化测试使用合成页面,不访问个人账号。

## 安装与调试

需要 Node.js 22+、支持插件浏览器 SDK 的 Ekko Studio Desktop,以及启用本地浏览器连接的宿主版本([Studio 修复 PR #3843](https://github.com/EKKOLearnAI/ekko-studio/pull/3843))。Web UI 与 Desktop 必须同时包含该修复;只更新插件不能修复旧 Desktop 的接入限制。

```bash
git clone https://github.com/EKKOLearnAI/ekko-studio-plugin-travel.git
cd ekko-studio-plugin-travel
npm ci --include=dev --ignore-scripts
npm run check
ekko-studio plugins link .
```

在 Studio 插件中心启用“旅行助手 · 采集调试”,打开插件页面:

1. 在“按地址找酒店”填写城市、地址/地标及入住和离店日期,按需设置展示价上限。
2. 点击“查找酒店”;插件新建查询页,选择城市联想项并提交地址,核对结果条件后返回酒店。
3. 检查“已选择站点地点”或“仅关键词匹配”、站点当前入住人数、预算待核实标记及价格原文。
4. 登录、验证或同名地点不明确时停止自动查询;在页面处理后重试。也可手动搜索后通过“采集已有页面”采集,或打开图文来源。

`No authorized active Desktop browser` 表示宿主未连接可用的 Desktop 浏览器,应先检查宿主版本及登录状态。插件不会启动另一个浏览器,也不会从磁盘读取 Cookie 或宿主令牌。

## MCP 工具

安装并启用插件后,Studio 按插件命名空间暴露以下工具:

| 工具 | 输入 | 输出 |
| --- | --- | --- |
| `search_hotels` | `{ "city": "杭州", "address": "杭州东站", "checkIn": "YYYY-MM-DD", "checkOut": "YYYY-MM-DD", "maxPrice": 300 }` | 条件已核对的酒店记录及查询元数据;`maxPrice` 可省略 |
| `list_pages` | `{}` | 支持站点的已打开标签页 |
| `open_page` | `{ "source": "ctrip", "url": "https://hotels.ctrip.com/" }` | 新标签页;`url` 可省略 |
| `collect_page` | `{ "tabId": "标签页 ID" }` | 清洗后的记录、来源、采集时间、状态和诊断 |

酒店查询日期需为有效未来/当日日期,最多 30 晚;不接受人数、房型和距离半径筛选。城市必须精确匹配站点联想项;同名候选不会自动任选。地址不能匹配地点时作为关键词提交,明确不保证附近距离。展示价筛选仅针对当前已采集的最多 40 条记录,条件价/总价/缺价保留待核实。

支持的来源 ID:`ctrip`、`xiaohongshu`、`meituan`、`ctrip-guide`、`mafengwo`。任意脚本输入与非支持来源被拒绝。详情见 [数据契约](docs/CONTRACTS.md)。

价格以分表示,只接受明确的单个人民币金额,保留原文及“起价 / 条件价 / 每晚 / 总价 / 未知”含义。缺失、区间和歧义价格不会填成零;酒店结果始终标记为部分数据,不能直接当作同房型最终成交价。

## 开发与验证

```bash
npm run check                         # 契约、SDK 完整性与 Node 行为测试
npx playwright install chromium
npm run test:browser                   # 合成站点真实 CDP 查询流程、UI、安全与失败路径
```

没有构建步骤,入口是 `server.mjs` 与 `client.mjs`。选择器位于 `src/sources.mjs`;DOM 采集、无障碍树适配及清洗分别位于 `src/capture.mjs`、`src/accessibility.mjs`、`src/clean.mjs`。酒店查询编排与可见表单脚本位于 `src/hotel-search.mjs`、`src/hotel-page.mjs`。修改边界结构时同步更新 `contracts/plugin.json`、文档及测试。

结果仅保留当前用户及 Profile 的最后一次采集。不提交个人网页快照、账号资料、Cookie、存储状态或令牌。公开链接会删除非允许的查询参数,因此部分站点链接可能需要重新在站内打开。

宿主 SDK 指南:[架构](docs/ARCHITECTURE.md)、[上下文](docs/STUDIO_CTX.md)、[返回约定](docs/STUDIO_RETURNS.md)、[字段](docs/FIELD_REFERENCE.md)、[宿主 API](docs/HOST_API.md)、[开发规范](docs/DEVELOPMENT.md)。

## 许可

本仓库新编写的旅行插件代码采用 [MIT](LICENSE)。随脚手架复制的 Studio SDK、harness 和宿主指南保留其原有 BSL-1.1 许可,具体范围见 [NOTICE.md](NOTICE.md);这些文件没有重新许可为 MIT。