@xiuchang-midscene/android 2.0.3 → 2.0.4

package/dist/lib/mcp-server.js

@@ -463,352 +463,130 @@ var __webpack_exports__ = {};
         AndroidMCPServer: ()=>AndroidMCPServer
     });
     const mcp_namespaceObject = require("@xiuchang-midscene/shared/mcp");
-    var external_node_fs_ = __webpack_require__("node:fs");
-    var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_);
-    var external_node_path_ = __webpack_require__("node:path");
-    var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_);
     const agent_namespaceObject = require("@xiuchang-midscene/core/agent");
     var logger_ = __webpack_require__("@xiuchang-midscene/shared/logger");
     const utils_namespaceObject = require("@xiuchang-midscene/shared/utils");
-    const fliggyKnowledge = `---
-name: fliggy-app-guide
-description: >
-  飞猪 App 页面结构、功能入口和操作指南。适用于 iOS、Android、鸿蒙全端。
-  当需要在飞猪 App 上进行任何操作时，优先阅读此 Skill 了解页面结构和导航路径。
-  包含首页、搜索（猪搜）、飞猪千问（问一问）、结果页等核心页面的布局和操作方式。
-  包含门票、酒店、机票下单链路的页面描述和操作规则。
-
-  Trigger keywords: 飞猪, fliggy, 猪搜, 飞猪千问, 问一问, 飞猪搜索, 飞猪app, 商卡, 结果页, 默认页, 品专, SUG, 联想词, 底纹词, 金刚词, 景点货架, POI, 门票, 酒店, 机票, 下单, 预订
----
-
-# 飞猪 App 操作指南（全端通用）
-
-> 本指南适用于 iOS、Android、鸿蒙端的飞猪 App 操作。
-> 在执行任何飞猪 App 相关任务前，先参考本文档了解页面结构和导航路径。
-
-## App 版本区分
-
-- 手机上可能有两个"飞猪旅行" App：**测试包**和**正式包**
-- 区分方式：测试包图标右上角有"测试版"标记，正式包没有
-- **默认打开正式包**，除非用户明确要求打开测试包
-
-## 首页（即"推荐"页）
-
-- 飞猪 App 首页是所有操作的默认起点
-- 除非用户明确要求"继续操作"或指定其他页面，否则每次任务都先回到首页
-
-### 顶部导航栏（从左到右）
-
-| 导航项 | 说明 | 别名 |
-|---|---|---|
-| 飞猪千问 | 飞猪 AI 助手，可以对话提问 | 也叫"问一问" |
-| 推荐 | 飞猪 App 首页（默认停留页） | 首页 |
-| [城市名] | 基于定位显示的城市（如"杭州"） | 目的地推荐 |
-
-### 搜索区域
-
-- **搜索框**：内有滚动词（称为"底纹词"），点击搜索框进入搜索页，这个搜索叫"飞猪搜索"（简称"猪搜"）
-- **搜索按钮**：搜索框右侧，点击可以用当前滚动到的"底纹词"直接搜索
-- **热词**：搜索框下方，推荐的搜索关键词
-
-### 类目入口（热词下方）
-
-用户要求"进入XX类目"时，优先从这里进入。包括：
-- 酒店、机票、火车票、汽车票、景点门票、旅游、用车、签证、邮轮、特价机票等
-
-### 中间内容区
-
-- 活动 Banner（轮播图）
-- 推荐内容（酒店、旅游产品推荐卡片）
-
-### 底部 Tab 导航栏
-
-- 首页 | 消息 | 行程 | 我的
-
-### 首页弹窗处理
-
-当 App 不在后台（冷启动）时，首页可能出现以下弹窗，需要先处理：
-
-1. **全屏广告**：覆盖整个屏幕的推广广告
-   - 处理方式：点击右上角"跳过"按钮，或等待几秒自动消失
-2. **领券弹窗**：弹出的优惠券领取提示
-   - 处理方式：点击弹窗上的 X 按钮关闭
-
-**操作顺序**：打开 App → 处理弹窗（如有） → 确认在首页 → 执行任务
-
-## 默认页（从首页点击搜索框进入）
-
-入口：首页 → 点击搜索框
-
-页面布局（从上到下）：
-
-1. **搜索框**：
-   - 内有灰色的"底纹词"（从首页进入时滚动停留的词，进入默认页后不再滚动）
-   - 未输入内容时显示底纹词，输入内容后底纹词消失
-   - 输入内容后点击搜索 → 进入搜索结果页（简称"结果页"）
-   - 输入过程中，搜索框下方会动态出现 **SUG（联想词）**，对用户输入内容进行补全
-2. **金刚词**：搜索框下方的推荐词，点击可直接搜索
-3. **搜索历史**：之前搜索过的词，点击也会跳转到结果页
-4. **榜单**：搜索历史下方，包含一些榜单内容，可左右滑动，一般有 3-4 个
-
-## SUG（联想词）
-
-- 用户在搜索框输入过程中，搜索框下方会动态显示联想补全词
-- 出现场景：
-  1. 默认页搜索框输入时
-  2. 搜索结果页点击搜索框输入时
-- SUG 内容可点击，不同类型的 SUG 会进入不同的页面
-
-## 搜索结果页（结果页）
-
-入口：默认页 → 输入内容点击搜索 / 点击金刚词 / 点击搜索历史
-
-页面布局（从上到下）：
-
-1. **顶部搜索框**：
-   - 点击可以不退出当前页面重新搜索
-   - 左侧：返回按钮（回到上一页，很多页面都有）
-   - 右侧："我的收藏"（收藏夹，首页也有入口）
-2. **品专**（可能出现）：
-   - 广告位，不一定每次都有，只有特定的搜索词才会有投放
-3. **筛选**：品专下方的筛选条件
-4. **商品卡片（商卡）**：
-   - 左上角标注商卡类型（如"景点"、"酒店"等）
-   - 景点也叫 POI
-   - 左侧：图片；右侧：标题、标签、价格
-   - 点击商卡 → 进入商品详情页（但景点商卡点击进入的是"景点货架"，待补充）
-
-## 飞猪千问（问一问）
-
-- **入口**：首页顶部导航栏最左侧的"飞猪千问"
-- 这是飞猪的 AI 助手对话页面，可以输入问题进行对话
-- **注意**：飞猪千问 ≠ 飞猪搜索（猪搜）
-  - 飞猪千问：从顶部导航栏点击"飞猪千问"进入，是 AI 对话页面
-  - 飞猪搜索：从搜索框进入，是商品搜索结果页
-
-### 千问页面布局
-
-1. **顶部导航栏**：
-   - 左侧 icon：历史会话（查看之前的对话记录）
-   - 右侧 icon：新建会话（开始一个新的对话）
-2. **中间对话区域**：显示 AI 对话内容，包含推荐问题卡片
-3. **底部输入框**：输入问题并发送消息
-
-### 操作流程
-
-- 在底部输入框输入问题 → 点击发送 → 等待 AI 回复完成
-- 回复内容可能包含文字、卡片、推荐商品等
-
-## 门票下单链路
-
-### 门票列表页
-
-在上方的搜索框里可以搜索对应的景点
-
-### 门票详情页
-
-- 页面描述
-  - 顶部是图片或者相关介绍视频，下方是预订、评价、推荐tab
-- 预订tab
-  - 左侧是是可以可以快速锚定的索引，包括门票、联票或者更多套餐
-  - 购买的话点击景点门票，此时会有不同的sku，成人票、儿童票等，选择其中一个开始预订。此时会直接调到下单页或者唤起一个浮层。在浮层里从上到下依次选择对应的选项，比如种类、日期等
-  - 选择日期应该点日历图标来选择
-
-### 门票下单页
-
-- 页面描述
-  - 在该页面确保联系电话是否正确填写
-  - 如果要填写出行人信息，请确保出行人信息右侧的勾选框已经勾选
-- **⚠️ 支付时唤起收银台即可，不要真正支付，否则会对用户的资产造成损失！！！**
-
-## 酒店下单链路
-
-### 飞猪首页 for 酒店
-
-- 页面描述
-  - 头部搜索框和搜索按钮
-  - 头部我的收藏按钮
-  - 顶部金刚区域, 有各行业的入口, 一般为图片+文字，如酒店文案+酒店logo
-- 该页面操作限制规则:
-  - 酒店应点击金刚区域的酒店按钮所在金刚（它在金刚区域第一个，在机票金刚的前一个）, 点击即可进入酒店首页
-
-### 酒店首页
-
-- 页面描述
-  - 顶部4个tab: 国内(默认是被选中的)、国际、钟点房、民宿, 购买酒店流程中, 一般不需要切换点击
-  - 国内tab下有五行，第一行左侧城市选择按钮（一般有城市名显示, 如: 北京/杭州/上海）、右侧关键字输入栏
-  - 国内tab下有五行，第二行左侧酒店入住日期，右侧酒店离店日期
-  - 国内tab下有五行，第三行左侧是房间数/成人数/儿童数选择按钮（点击出现浮层，可以修改房间数/成人数/儿童数），右侧是星级选择按钮（点击出现浮层，可以修改每间每晚价格/星级）
-  - 国内tab下有五行，第四行是特殊关键字标签行，横向显示多个关键字标签，点击单个关键字标签，可以跳转带默认关键搜索词的酒店列表页
-  - 国内tab下有五行，第五行是搜索酒店按钮，一般通过点击搜索酒店按钮，跳转酒店列表页。
-  - 国内tab下的五行下方，是酒店猜你喜欢卡片列表。
-  - 其他不常用按钮不做过多赘述
-- 页面操作限制规则
-  - 只点击酒店详情页中的某一张房型卡片，不点击其他元素
-
-### 酒店列表页
-
-- 页面描述
-  - 顶部搜索栏左侧返回按钮，中间搜索栏（包含城市名称/酒店入离日期/房间数+人数/关键词栏（文字可能为空）），右侧地图icon按钮及三个点按钮
-  - 搜索栏下方是筛选栏（包含推荐排序按钮、位置距离、价格/星级、筛选等按钮）
-  - 筛选栏下方是卡片列表，由多张酒店卡片上下排列而成，点击卡片可以进入酒店详情页
-  - 其他不常用按钮不做过多赘述
-- 页面操作限制规则
-  - 只点击国内tab下第五行搜索酒店按钮
-
-### 酒店详情页
-
-- 页面描述：
-  - 顶部导航栏（导航栏一般为透明色）及按钮（按钮主要包括左侧返回按钮、右侧搜索Icon按钮、收藏星星Icon按钮、转发Icon按钮、三个点Icon的更多按钮）
-  - 顶部导航栏下方是多媒体头图容器，支持横向滚动的视频、图片。
-  - 头图容器下方是酒店标题组件（上下排布，上面是酒店标题文字，下方是酒店文字标签）
-  - 酒店标题组件下方是一排三按钮（左中右三部分区块构成，左侧是酒店评分，中间是装修信息，右侧是地址信息）
-  - 一排三按钮下方是会员及广告栏
-  - 会员及广告栏下方是入离日期栏（包含左侧酒店入住离店日期、右侧房间数及人员数）
-  - 入离日期栏下方是酒店房型卡片列表（一个由酒店房型卡片组成的支持上下滑动的卡片列表，每张卡片左侧是图片，右侧是上下多行文字描述，右下角带价格显示及预订按钮）
-  - 其他不常用按钮不做过多赘述
-- 页面操作限制规则：
-  - 当用户要下单某个房型时，应该先找到目标房型卡片（比如：大床房），可以先点击快捷筛选按钮，选择对应房型，再点击房型卡片中的 "订" 或者 "抢" 按钮操作进入下单页
-
-### 酒店下单页
-
-- 页面描述
-  - 头部有房型信息、入离日期等
-  - 中间有入驻人信息和手机号
-  - 底部有支付按钮和价格
-- **⚠️ 页面操作限制规则：判断到达该页面后，即可返回END结束，不要真实操作下单。**
-
-### AI酒店组件校验列表页
-
-- 页面描述：
-  - 顶部导航栏左侧返回按钮，中间文字标题"AI酒店组件校验列表"
-  - 导航栏下方是一个列表页，由多个列表项的行组件组成，每个行组件左侧是icon，中间是上下两行文字，右侧是一个右箭头
-  - 其他不常用按钮不做过多赘述
-- 页面操作限制规则
-  - 可以点击单个列表项行组件进行跳转
-  - 一次只可以点击单个行组件
-
-## 机票下单链路
-
-### 飞猪首页 for 机票
-
-- 页面描述
-  - 头部搜索框和搜索按钮
-  - 头部我的收藏按钮
-  - 顶部金刚区域, 有各行业的入口, 一般为图片+文字，如机票文案+飞机logo
-- 该页面操作限制规则:
-  - 机票应点击金刚区域的飞机按钮所在金刚（它在金刚区域第二个，酒店金刚后，火车票金刚前）, 点击即可进入机票首页
-
-### 机票首页
-
-- 页面描述：
-  - 顶部4个tab: 机票/特价机票(默认)、火车票、汽车票、接送/租车, 购买机票流程中, 一般不需要切换点击
-  - 顶部3个tab切换行程类型: 单程(默认), 多程, 往返, 如果没有特别说明, 一般是单程机票购买流程
-  - **注意**：出发城市、到达城市位于页面左右两侧, 并且在搜索按钮前, OCR结果一般因为在左右两侧所有分为两个独立的元素, 在搜索按钮后, 可能存在出发城市-到达城市相关的快捷操作文案, 这不是入口, 在candidate_elements, 以及locate里都不要选择那些快捷操作文案
-  - 出发城市: 一般有城市名（在页面左侧）, 如: 北京
-  - 到达城市: 一般有城市名（在页面右侧）, 如: 杭州
-  - 搜索机票: 按钮, 点击进入机票列表页
-  - 其他不常用按钮不做过多赘述
-
-### 机票首页-城市选择页
-
-- 页面描述: 城市选择页是机票首页的弹窗, 从点击出发地、目的地进入, 主要特征是一个遮罩在机票首页的半弹窗, 顶部有单目的地、多目的地的切换tab、中间有国内、国际城市的切换tab、主体内容是各个热门城市、地区的选项
-- 该页面操作限制规则:
-  1. 机票首页, 点击默认出发地、或目的地, 进入城市选择页
-  2. 返回Input, 参数是点击的搜索框以及输入的机场/城市内容
-  3. 选择对应的机场/城市
-
-### 机票列表页
-
-- 页面描述：
-  - 机票日期选择器: 页面顶部, 点击可切换日期, 会刷新列表
-  - 机票列表, 点击进入不同机票详情
-- 页面操作限制规则
-  - 机票日期选择器 (如无特殊要求, 请不要操作这部分): 如果最终目标中没有明确说明, 请不要在这里操作切换日期
-  - 机票列表(请在此部分选择航班, 进入机票详情页): 一般展示航班的出发时间/机场、到达时间/机场, 以及机票价格, 如果最终目标提到了对应信息请选择对应的航班, 如果没有说明请任选一个进入机票详情页
-
-### 机票详情页
-
-- 页面描述:
-  - 头部信息: 展示机票航班信息, 只做展示都不可点击
-  - 仓位切换tab: 默认经济舱, 可点击切换成公务/头等舱
-  - 航班报价列表: 只有 "订" (完全一致, 不包含: 预订, 下订单等其他字)关键字的才可点击, 点击后进入填单页
-- 页面操作限制规则
-  - 弹窗处理逻辑: 点击订后, 如果出现弹窗, 请点击继续购买相关的选项
-
-### 机票下单页
-
-- 页面描述:
-  - 头部信息: 展示机票航班信息, 只做展示都不可点击
-  - 选择完乘机人后点击底部的按钮就行下单。按钮可能是"去支付"或者"预订"
-  - 支付按钮
-- **⚠️ 该页面操作限制规则：判断到达该页面后，即可返回END结束，不要真实操作下单。**`;
-    const debug = (0, logger_.getDebug)('android:app-knowledge');
-    const MAX_SCREENSHOTS_PER_PAGE = 2;
-    const packageConfigMap = {
-        'com.taobao.trip': {
-            knowledge: fliggyKnowledge,
-            screenshotDirName: 'fliggy',
-            defaultPage: 'home',
-            pageIds: [
-                'home',
-                'search-default',
-                'search-sug',
-                'search-result',
-                'fliggy-qwen',
-                'ticket-detail',
-                'hotel-list',
-                'hotel-detail',
-                'flight-list',
-                'flight-detail',
-                'ticket-order',
-                'hotel-order',
-                'flight-order'
-            ]
+    const debug = (0, logger_.getDebug)('android:app-knowledge:oss');
+    function getOSSKnowledgeBaseUrl() {
+        const domain = process.env.MIDSCENE_OSS_DOMAIN;
+        if (domain) return `${domain.replace(/\/$/, '')}/app-knowledge`;
+        const bucket = process.env.MIDSCENE_OSS_BUCKET || 'xrayandroid';
+        const region = process.env.MIDSCENE_OSS_REGION || 'oss-cn-beijing';
+        return `https://${bucket}.${region}.aliyuncs.com/app-knowledge`;
+    }
+    async function fetchText(url) {
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                debug('HTTP %d for %s', response.status, url);
+                return null;
+            }
+            return await response.text();
+        } catch (error) {
+            debug('fetch failed for %s: %s', url, error.message);
+            return null;
         }
-    };
-    function getKnowledgeForPackage(packageName) {
-        const config = packageConfigMap[packageName];
-        if (config) {
-            debug('found knowledge for package: %s', packageName);
-            return config.knowledge;
+    }
+    async function fetchBuffer(url) {
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                debug('HTTP %d for %s', response.status, url);
+                return null;
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            return Buffer.from(arrayBuffer);
+        } catch (error) {
+            debug('fetch failed for %s: %s', url, error.message);
+            return null;
         }
-        debug('no knowledge found for package: %s', packageName);
-        return null;
     }
-    function getScreenshotsForPage(packageName, pageId) {
-        const config = packageConfigMap[packageName];
-        if (!config) {
-            debug('no config for package: %s, skipping screenshots', packageName);
+    async function fetchAppManifest(appDirName) {
+        const baseUrl = getOSSKnowledgeBaseUrl();
+        const url = `${baseUrl}/${appDirName}/manifest.json`;
+        debug('fetching manifest from %s', url);
+        const text = await fetchText(url);
+        if (!text) return null;
+        try {
+            const manifest = JSON.parse(text);
+            debug('manifest loaded for %s: %d pageIds', appDirName, manifest.pageIds?.length ?? 0);
+            return manifest;
+        } catch (error) {
+            debug('failed to parse manifest for %s: %s', appDirName, error.message);
+            return null;
+        }
+    }
+    async function fetchTextKnowledge(appDirName) {
+        const baseUrl = getOSSKnowledgeBaseUrl();
+        const url = `${baseUrl}/${appDirName}/knowledge.txt`;
+        debug('fetching text knowledge from %s', url);
+        const text = await fetchText(url);
+        if (!text) return null;
+        debug('text knowledge loaded for %s (%d chars)', appDirName, text.length);
+        return text;
+    }
+    async function fetchScreenshotAsBase64(appDirName, pageId, fileName) {
+        const baseUrl = getOSSKnowledgeBaseUrl();
+        const url = `${baseUrl}/${appDirName}/screenshots/annotated/${pageId}/${fileName}`;
+        debug('fetching screenshot from %s', url);
+        const buffer = await fetchBuffer(url);
+        if (!buffer) return null;
+        const ext = fileName.split('.').pop()?.toLowerCase() || 'jpeg';
+        const mimeType = 'png' === ext ? 'image/png' : 'image/jpeg';
+        return {
+            name: `${pageId}-${fileName}`,
+            url: `data:${mimeType};base64,${buffer.toString('base64')}`
+        };
+    }
+    const app_knowledge_debug = (0, logger_.getDebug)('android:app-knowledge');
+    const packageOssDirMap = {
+        'com.taobao.trip': 'fliggy'
+    };
+    function getOssDirForPackage(packageName) {
+        return packageOssDirMap[packageName] ?? null;
+    }
+    async function getKnowledgeForPackage(packageName) {
+        const ossDirName = getOssDirForPackage(packageName);
+        if (!ossDirName) {
+            app_knowledge_debug('no OSS dir mapping for package: %s', packageName);
+            return null;
+        }
+        const knowledge = await fetchTextKnowledge(ossDirName);
+        knowledge ? app_knowledge_debug('loaded OSS text knowledge for package: %s', packageName) : app_knowledge_debug('no OSS text knowledge available for package: %s', packageName);
+        return knowledge;
+    }
+    async function getScreenshotsForPage(packageName, pageId) {
+        const ossDirName = getOssDirForPackage(packageName);
+        if (!ossDirName) {
+            app_knowledge_debug('no OSS dir mapping for package: %s, skipping screenshots', packageName);
             return [];
         }
-        const pageDir = external_node_path_.join(__dirname, 'screenshots', config.screenshotDirName, pageId);
-        if (!external_node_fs_.existsSync(pageDir)) {
-            debug('screenshot directory not found: %s', pageDir);
+        const manifest = await fetchAppManifest(ossDirName);
+        if (!manifest) {
+            app_knowledge_debug('no manifest available for %s, skipping screenshots', ossDirName);
             return [];
         }
-        try {
-            const files = external_node_fs_.readdirSync(pageDir);
-            const imageFiles = files.filter((f)=>/\.(jpg|jpeg|png)$/i.test(f)).map((f)=>external_node_path_.join(pageDir, f));
-            if (0 === imageFiles.length) {
-                debug('no image files in directory: %s', pageDir);
-                return [];
-            }
-            const result = imageFiles.slice(0, MAX_SCREENSHOTS_PER_PAGE);
-            debug('found %d screenshot(s) for %s/%s (returning %d)', imageFiles.length, packageName, pageId, result.length);
-            return result;
-        } catch (err) {
-            debug('error reading screenshot directory %s: %s', pageDir, err);
+        const fileNames = manifest.screenshots?.[pageId];
+        if (!fileNames?.length) {
+            app_knowledge_debug('no screenshot files listed for %s/%s', ossDirName, pageId);
             return [];
         }
+        const results = await Promise.all(fileNames.map((fileName)=>fetchScreenshotAsBase64(ossDirName, pageId, fileName)));
+        const screenshots = results.filter((r)=>null !== r);
+        app_knowledge_debug('fetched %d/%d screenshot(s) for %s/%s', screenshots.length, fileNames.length, packageName, pageId);
+        return screenshots;
     }
-    function getDefaultPageForPackage(packageName) {
-        const config = packageConfigMap[packageName];
-        return config?.defaultPage ?? null;
+    async function getDefaultPageForPackage(packageName) {
+        const ossDirName = getOssDirForPackage(packageName);
+        if (!ossDirName) return null;
+        const manifest = await fetchAppManifest(ossDirName);
+        return manifest?.defaultPage ?? null;
     }
-    function getPageIdsForPackage(packageName) {
-        const config = packageConfigMap[packageName];
-        return config?.pageIds ?? [];
+    async function getPageIdsForPackage(packageName) {
+        const ossDirName = getOssDirForPackage(packageName);
+        if (!ossDirName) return [];
+        const manifest = await fetchAppManifest(ossDirName);
+        return manifest?.pageIds ?? [];
     }
     const defaultAppNameMapping = {
         微信: 'com.tencent.mm',
@@ -909,7 +687,11 @@ description: >
     const external_node_assert_namespaceObject = require("node:assert");
     var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
     const external_node_child_process_namespaceObject = require("node:child_process");
+    var external_node_fs_ = __webpack_require__("node:fs");
+    var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_);
     var external_node_module_ = __webpack_require__("node:module");
+    var external_node_path_ = __webpack_require__("node:path");
+    var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_);
     const core_namespaceObject = require("@xiuchang-midscene/core");
     const device_namespaceObject = require("@xiuchang-midscene/core/device");
     const core_utils_namespaceObject = require("@xiuchang-midscene/core/utils");
@@ -2282,20 +2064,21 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 command
             });
         }
-        loadAppKnowledge(packageName) {
+        async loadAppKnowledge(packageName) {
             if (this.lastKnowledgePackageName === packageName) return void debugAgent('knowledge already loaded for package: %s, skipping', packageName);
-            const knowledge = getKnowledgeForPackage(packageName);
+            const knowledge = await getKnowledgeForPackage(packageName);
             if (knowledge) {
                 this.setAIActContext(knowledge);
                 debugAgent('loaded app knowledge for package: %s', packageName);
             } else debugAgent('no app knowledge available for package: %s', packageName);
-            const pageIds = getPageIdsForPackage(packageName);
+            const pageIds = await getPageIdsForPackage(packageName);
             if (pageIds.length > 0) {
                 this.availablePageIds = pageIds;
+                const defaultPage = await getDefaultPageForPackage(packageName);
                 this.referenceScreenshotProvider = async (pageId)=>{
-                    const effectivePageId = pageId ?? getDefaultPageForPackage(packageName);
+                    const effectivePageId = pageId ?? defaultPage;
                     if (!effectivePageId) return [];
-                    return this.resolveReferenceScreenshots(effectivePageId, packageName);
+                    return getScreenshotsForPage(packageName, effectivePageId);
                 };
                 debugAgent('screenshot knowledge provider set for package: %s (%d pages)', packageName, pageIds.length);
             } else {
@@ -2304,25 +2087,11 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             }
             this.lastKnowledgePackageName = packageName;
         }
-        async resolveReferenceScreenshots(pageId, packageName) {
-            const screenshotPaths = getScreenshotsForPage(packageName, pageId);
-            if (!screenshotPaths.length) return [];
-            return Promise.all(screenshotPaths.map(async (p, i)=>{
-                const base64 = await external_node_fs_.promises.readFile(p, {
-                    encoding: 'base64'
-                });
-                const ext = external_node_path_.extname(p).slice(1) || 'jpeg';
-                return {
-                    name: `${pageId}-${i + 1}`,
-                    url: `data:image/${ext};base64,${base64}`
-                };
-            }));
-        }
         async detectAndLoadAppKnowledge() {
             try {
                 const dumpsysOutput = await this.runAdbShell('dumpsys activity activities | grep -E "mResumedActivity|mTopActivityRecord"');
                 const packageName = parseForegroundPackageName(dumpsysOutput);
-                if (packageName) this.loadAppKnowledge(packageName);
+                if (packageName) await this.loadAppKnowledge(packageName);
                 else debugAgent('could not detect foreground app package name');
             } catch (error) {
                 debugAgent('failed to detect foreground app for knowledge injection:', error);

package/dist/types/index.d.ts

@@ -61,14 +61,7 @@ export declare class AndroidAgent extends Agent<AndroidDevice> {
      * Skips if the same package knowledge is already loaded.
      * @param packageName - The Android package name (e.g. "com.taobao.trip")
      */
-    loadAppKnowledge(packageName: string): void;
-    /**
-     * Resolve annotated reference screenshots for a given page to base64 data URLs.
-     * @param pageId - The page identifier
-     * @param packageName - The Android package name
-     * @returns Array of base64 image data objects, empty if no screenshots found
-     */
-    private resolveReferenceScreenshots;
+    loadAppKnowledge(packageName: string): Promise<void>;
     /**
      * Detect the foreground Android app and automatically load its business knowledge.
      * Uses ADB to get the currently resumed activity and extract the package name,

package/dist/types/mcp-server.d.ts

@@ -60,14 +60,7 @@ declare class AndroidAgent extends Agent<AndroidDevice> {
      * Skips if the same package knowledge is already loaded.
      * @param packageName - The Android package name (e.g. "com.taobao.trip")
      */
-    loadAppKnowledge(packageName: string): void;
-    /**
-     * Resolve annotated reference screenshots for a given page to base64 data URLs.
-     * @param pageId - The page identifier
-     * @param packageName - The Android package name
-     * @returns Array of base64 image data objects, empty if no screenshots found
-     */
-    private resolveReferenceScreenshots;
+    loadAppKnowledge(packageName: string): Promise<void>;
     /**
      * Detect the foreground Android app and automatically load its business knowledge.
      * Uses ADB to get the currently resumed activity and extract the package name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiuchang-midscene/android",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Android automation library for Midscene",
   "keywords": [
     "Android UI automation",
@@ -42,8 +42,8 @@
     "@yume-chan/stream-extra": "2.1.0",
     "appium-adb": "12.12.1",
     "sharp": "^0.34.3",
-    "@xiuchang-midscene/shared": "^2.0.3",
-    "@xiuchang-midscene/core": "^2.0.3"
+    "@xiuchang-midscene/shared": "^2.0.4",
+    "@xiuchang-midscene/core": "^2.0.4"
   },
   "optionalDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0"