hostpad 0.2.1 → 0.2.2

package/README.md

@@ -27,7 +27,7 @@ npx hostpad
 }
 ```
 
-## MCP 工具（10 个）
+## MCP 工具（12 个）
 
 | 工具 | 作用 |
 |------|------|
@@ -38,8 +38,11 @@ npx hostpad
 | `reload` | 重推工具（激活） |
 | `get_logs` | 读手机回流的日志环形缓冲（工具 console.* 与系统事件，游标分页） |
 | `rpc_call` | 调用手机上运行中工具的 `onMessage` 处理器，返回值回传 |
+| `ui_snapshot` / `ui_screenshot` | UI 调试：拉取手机上**净化后实际渲染**的 DOM 快照（含每元素几何框、用户指认记录、renderSeq）/ 截取当前工具页 JPEG 图直接看效果。需手机上该工具页处于打开状态 |
 
-典型闭环：`create_tool`（写）→ 手机热加载 → `get_logs` 读 `loaded` / console 输出 → `update_tool` 增量迭代 → `rpc_call` 驱动交互。
+典型闭环：`create_tool`（写）→ 手机热加载 → `get_logs` 读 `loaded` / console 输出 → `update_tool` 增量迭代 → `rpc_call` 驱动交互 → `ui_snapshot` 指认元素 → `ui_screenshot` 验收视觉。
+
+UI 调试循环细节：推送后轮询 `ui_snapshot`，`renderSeq` 变化即新帧已渲染；用户在手机工具页右上角十字准星图标开启**指认模式**后，点选的元素路径会出现在下一次 `ui_snapshot` 的 `picks` 里。截图/指认会把界面内容发到电脑端（App 内有日志留痕）。老版本 App 不支持这两个工具时会有明确的升级提示。
 
 ## 命令行
 

package/bin/hostpad.js

@@ -79,6 +79,17 @@ const fileSchema = {
     required: ['path', 'content'],
   },
 };
+// UI 调试保留字（__ui_inspect / __ui_screenshot）响应的形状校验 + 解析。
+// 老 App 没有保留字拦截，会落进工具 onMessage → result 为 nil/杂值，这里转成版本提示。
+function parseUiPayload(r, mustHave) {
+  let parsed;
+  try { parsed = JSON.parse(r.result); } catch { /* 落到下面的版本提示 */ }
+  if (!parsed || typeof parsed !== 'object' || !(mustHave in parsed)) {
+    throw new Error('手机端 App 版本过旧（未实现 UI 调试通道），请在 iPhone 上更新 HostPad 后重试');
+  }
+  return parsed;
+}
+
 const tools = [
   {
     name: 'list_devices',
@@ -208,10 +219,49 @@ const tools = [
       { timeoutMs: timeoutMs ?? 5000 },
     ),
   },
+  {
+    name: 'ui_snapshot',
+    description: 'UI 调试：拉取手机上当前工具实际渲染后的 DOM 快照（净化器处理后的真实结果，'
+      + '每元素含 tag/class/文本/几何框，能看出哪些写法被剥除）+ 用户指认记录（picks，'
+      + '手机上开启指认模式后用户点了哪些元素）+ renderSeq。'
+      + '调试循环：update_tool 推送后轮询本工具，renderSeq 变化说明新帧已渲染',
+    inputSchema: {
+      type: 'object',
+      properties: { toolId: { type: 'string' } },
+      required: ['toolId'],
+    },
+    handler: async ({ toolId }) => {
+      const r = await bridge.rpcCall(toolId, '__ui_inspect', {}, { timeoutMs: 8000 });
+      return parseUiPayload(r, 'dom');
+    },
+  },
+  {
+    name: 'ui_screenshot',
+    description: 'UI 调试：截取手机上当前工具页面的图（JPEG ~800px，以图片内容返回，直接看视觉效果）。'
+      + '需该工具页面在手机上处于打开状态。改完 UI 推送后用它验收',
+    inputSchema: {
+      type: 'object',
+      properties: { toolId: { type: 'string' } },
+      required: ['toolId'],
+    },
+    handler: async ({ toolId }) => {
+      const r = await bridge.rpcCall(toolId, '__ui_screenshot', {}, { timeoutMs: 8000 });
+      const p = parseUiPayload(r, 'image');
+      return {
+        // 哨兵键：mcp.js 直接透传为 MCP content（图片不能 stringify 成文本）
+        __rawContent: [
+          { type: 'text', text: `renderSeq=${p.renderSeq} ${p.width}x${p.height} ${p.mime}` },
+          { type: 'image', data: p.image, mimeType: p.mime },
+        ],
+      };
+    },
+  },
 ];
 
 const mcp = createMcpServer({
   tools,
+  // serverInfo 版本跟随 package.json，发布升版不用改这里
+  serverInfo: { name: 'hostpad-agent', version: require('../package.json').version },
   write: (line) => process.stdout.write(line + '\n'),
 });
 

package/lib/guide.js

@@ -61,6 +61,16 @@ ${FENCE}
 host.ui.onMessage 收到 { name: "load", values: { repo: "apple/swift" } }。
 注意 img 的 data: src 会被剥（base64 内联图不可用，只能 http(s) 远程图）。
 
+## UI 调试循环（不用盲写）
+
+1. ui_snapshot(toolId)：拉取手机上**净化后实际渲染**的 DOM 树（每元素含几何框），
+   看元素是否被剥、层级是否符合预期；响应含 renderSeq 与用户指认记录（picks）
+2. update_tool 推送修改 → 轮询 ui_snapshot 直到 renderSeq 变化（新帧已渲染）
+3. ui_screenshot(toolId)：截取当前工具页（JPEG 图片直接可见），验收视觉效果
+用户在手机上点工具页右上角十字准星（scope）图标开启**指认模式**后，点哪个元素，
+下一次 ui_snapshot 的 picks 里就有该元素的选择器路径/outerHTML/几何框——
+"用户说哪里不对"可直接定位到节点。截图/指认会把界面内容发到电脑端（App 内有日志留痕）。
+
 ## 权限模型
 
 manifest.permissions 声明 "逃出沙盒" 的能力：http / clipboard / notifications。

package/lib/mcp.js

@@ -56,9 +56,14 @@ function createMcpServer({ tools, write, serverInfo }) {
           let result;
           try {
             result = await tool.handler(f.params?.arguments ?? {});
+            // 哨兵透传：handler 返回 { __rawContent: [内容块] } 时直接作为 MCP content
+            // （ui_screenshot 返回 image 块用；其余 handler 照旧统一 stringify）
+            const raw = result && typeof result === 'object' && Array.isArray(result.__rawContent)
+              ? result.__rawContent
+              : null;
             respond({
               jsonrpc: '2.0', id,
-              result: { content: [{ type: 'text', text: JSON.stringify(result ?? null) }] },
+              result: { content: raw ?? [{ type: 'text', text: JSON.stringify(result ?? null) }] },
             });
           } catch (e) {
             respond({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hostpad",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "HostPad 的 MCP 服务器 + iPhone 同步桥：AI agent 经 MCP 管理与调试 iOS 工具（写→推→读日志闭环）",
   "license": "UNLICENSED",
   "bin": {