mobkit

MobKit 为 APICloud / YonBuilder / AVM 移动工程提供现代前端工具链。在保留经典 webview 工作方式的同时，支持以 Vite + Preact/React + TypeScript 开发，并提供真机同步、开发热更、真机自动化与用友云集成。

一个包，多个入口：命令行（mobkit / mk）、构建插件（mobkit/vite、mobkit/rsbuild）、程序化库。浏览器端运行时为独立包 @mobkit/runtime。

要求 Node ≥ 20.18.1（或 Bun ≥ 1.3）。VS Code 与 JetBrains 插件内置同源 CLI，安装插件后无需单独安装本包。

目录

• 概述
• 工程形态
• 安装
• 快速开始
• 开发热更（dev lane）
• 命令行参考
• 构建插件
• 运行时
• 程序化库

概述

MobKit 面向混合移动工程（以 config.xml 为工程标志）的开发、调试与发布，封装了 WiFi 同步协议、设备工具链（adb / xcrun / hdc）、用友云接口与构建集成。

| 能力 | 说明 | 入口 | | ------------ | ---------------------------------------------------------------- | --------------------------- | | 真机同步 | 前端改动增量推送到真机 AppLoader，无需重新打包 | mobkit wifi | | 开发热更 | 现代 Vite 工程连接本机 dev server，保存后经 HMR 更新 | mobkit dev、mobkit/vite | | 多窗口运行时 | 单基座工程实现原生多窗口 | @mobkit/runtime | | 真机自动化 | 截屏、控件树、点击、WebView 求值、安装包（Android / iOS / 鸿蒙） | mobkit device | | 用友云集成 | 登录、切换租户、检出应用、上传源码、云打包 | mobkit cloud | | 脚手架 | 云端创建应用并初始化本地工程 | mobkit cloud create-app | | IDE 扩展 | VS Code / JetBrains 统一工作台 | 安装插件 | | AI 集成 | 以 MCP 协议暴露工具链 | mobkit mcp |

工程形态

MobKit 支持两类工程，命令与工作流据此区分。

| | 经典 webview | 现代构建（Vite / rsbuild） | | ---------- | ----------------------------- | -------------------------------- | | 产物 | 源码即产物 | 源码构建为 dist/ | | 改动生效 | mobkit wifi sync 推送源文件 | dev lane 热更 | | 技术栈 | HTML / JS / AVM | Vite + Preact/React + TypeScript | | 多窗口 | 每个页面独立 HTML | 单基座 HTML + @mobkit/runtime | | 脚手架模板 | webview（默认） | modern |

设备端两类工程均由 AppLoader 通过 file:// 加载 widget。现代构建的产物形态处理见生产构建产物。

安装

# 全局命令
npm i -g mobkit

# 或在现代工程中作为构建插件与运行时
pnpm add -D mobkit
pnpm add @mobkit/runtime

mobkit help              # 列出全部命令（mk 为等价短别名）
mobkit version
mobkit <command> --help  # 单个命令的完整参数

快速开始

经典 webview 工程

mobkit wifi start        # 启动同步服务并打印二维码
# 真机 AppLoader 扫码连接（手机与电脑处于同一局域网）
mobkit wifi sync         # 推送改动到真机（--all 全量）
mobkit wifi log          # 查看 App 内 console 输出

现代 Vite 工程

前置条件：工程内置门卫页 public/dev.html，config.xml 的 content 指向 dist/dev.html，且已至少构建一次。使用 mobkit cloud create-app --template modern 脚手架会自动准备上述结构。

pnpm dev                 # mobkit/vite 插件在 dev server 启动时开启 dev lane
# 真机扫码连接后，保存源文件即经 HMR 更新

vite.config.ts 引入插件：

import { defineConfig } from 'vite'
import preact from '@preact/preset-vite'
import mobkit from 'mobkit/vite'

export default defineConfig({
  base: './',
  plugins: [preact(), mobkit({ syncServer: 'mount' })],
  server: { host: true, port: 5174, strictPort: true }
})

入口 src/main.tsx：从 @mobkit/runtime/preact 引入并调用 apiReady()（见运行时）。

开发热更（dev lane）

dev lane 用于现代工程在真机上的开发内环：设备在「连接本机 dev server 并热更」与「加载构建产物」之间切换，无需每次构建再同步。

工作原理

设备入口（config.xml 的 content）指向门卫页 dist/dev.html。门卫页内嵌一个指针变量，App 启动时据此决定加载来源：

• 指针为空：直接加载 dist/ 构建产物（file://），不发起网络请求。
• 指针存在：探测其指向的本机 dev server。可达则跳转，页面运行于 Vite dev server 并支持 HMR；不可达则回落到构建产物（默认探测超时 1.5 秒）。

生产构建的产物不受影响：出厂门卫页不含指针，加载路径与开发环境无关。

控制方式

| 命令 | 作用 | | --------------------------------------- | -------------------------------------------------------------------------------- | | pnpm dev（工程含 mobkit/vite 插件） | dev server 启动时写入指针，开启热更 | | mobkit dev --wait | 探测 dev server 后写入指针；适用于 Vite 已运行、需重写指针的场景（如切换网络后） | | mobkit dev --off | 清除指针，设备回落到构建产物 | | vite build | 以无指针门卫覆盖 dist/dev.html |

多数情况下 pnpm dev 已足够——插件在 dev server 启动时自动写入指针。mobkit dev 用于不重启 Vite 而重写指针，或工程未使用插件时手动开启。

注意事项

• vite.config 应设 server.strictPort: true。端口被占用时 Vite 会切换端口，而门卫指针仍指向原端口，导致设备连接到失效地址。
• 切换网络后，指针中的局域网地址会失效，需重新写入（pnpm dev 或 mobkit dev）。
• Android 模拟器（AVD）需清除宿主继承的 http_proxy，且指针使用 10.0.2.2（模拟器到宿主的回环地址）而非局域网地址。

生产构建产物

Android AppLoader 通过 file:// 加载 widget 时，<script type="module"> 会因 MIME 类型为空而被拒绝加载。因此 mobkit/vite 在构建时将产物输出为单文件 IIFE（经典 <script>），并移除 index.html 中的 type=module 与 crossorigin 属性。该处理仅作用于生产构建，dev lane 经 http:// 加载不受影响。此为默认行为（fileProtocol: true），可按需关闭。

命令行参考

命令附加 --json 时输出 NDJSON 事件流，供脚本与 IDE 消费。完整参数见 mobkit <command> --help。

真机同步

| 命令 | 说明 | | ------------------------------------- | ------------------------------------------------------- | | wifi start | 启动同步服务（长驻，打印二维码）。--port、--project | | wifi sync | 推送改动。--all 全量 | | wifi preview | 单页实时预览。--file | | wifi info / wifi qr / wifi stop | 服务信息 / 重新打印二维码 / 停止服务 | | wifi log | 订阅设备 console 输出（长驻） |

开发热更

| 命令 | 说明 | | ------------------------------------------- | -------------------------------------------- | | dev | 将门卫指向本机 Vite dev server | | dev --wait | 等待 dev server 就绪（至多 60 秒）后写入指针 | | dev --off | 清除指针，回落构建产物 | | dev --vite-port / --entry / --project | 指定端口 / 入口 / 工程根目录 |

用友云工作台

| 命令 | 说明 | | --------------------------------- | -------------------------------------------------------------------- | | cloud login | 登录（默认扫码；--username / --password 账密；MFA 短信自动交互） | | cloud whoami / logout | 查看登录状态 / 登出 | | cloud tenants / switch-tenant | 列出租户 / 免登出切换租户 | | cloud apps | 列出当前租户下的应用 | | cloud create-app | 云端创建应用并初始化本地工程。--template webview\|modern | | cloud checkout | 检出应用源码。--app | | cloud upload | 打包并上传源码。--dir（自动读取 config.xml 中的 appId） | | cloud build / build-status | 云打包并查询进度。--platforms android,ios,harmony |

真机自动化

| 命令 | 说明 | | ------------------------------------------------ | ------------------------------------------------------------------------ | | device list | 列出设备。--all、--platform | | device shot | 截屏。--out、--id | | device ui | 导出控件树。--clickable（供按文字定位） | | device tap | 点击。<x> <y> 或 --text <文字>（按文字定位，不受键盘、弹窗位移影响） | | device text / device key | 输入文本 / 按键 | | device eval | 在 WebView 中求值 JS。例：device eval 'api.systemType' | | device sniff / device log / device install | 抓取网络与日志 / 设备日志 / 安装包 |

AI 集成

| 命令 | 说明 | | ------------ | ---------------------------------------------------------------------------- | | agent init | 写入 .mcp.json、.cursor/mcp.json、AGENTS.md 与 .claude/skills/mobkit | | mcp | 以 MCP（stdio）向 AI 宿主暴露工具链（Claude Code、Cursor 等） |

构建插件

mobkit/vite

import mobkit from 'mobkit/vite'

plugins: [mobkit({ syncServer: 'mount' })]

插件将现代 Vite 工程接入 MobKit，覆盖开发与构建两侧。

| 选项 | 默认值 | 说明 | | -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | syncServer | 'external' | 'mount'：同步服务挂载到 Vite dev server，设备扫码、文件、console、CLI 通道与 HMR 共用同一端口与源。'external'：使用独立的 mobkit wifi start 服务 | | devLane | true | dev server 启动时自动开启 dev lane（写入指针并同步） | | fileProtocol | true | 构建时按 file:// 加载形态输出（单文件 IIFE，移除 type=module） | | syncOnBuild | 'watch-only' | 构建完成后自动同步：仅 build --watch / true / false | | preserveDevPointer | false | 构建后回写构建前的指针（用于本地构建验证；发布构建应保持关闭） | | windowsDir | 'src/windows' | mobkit:windows 虚拟模块的扫描目录 |

mobkit:windows 虚拟模块（内部契约）

插件与运行时之间的内部契约，应用不直接 import。插件将 src/windows/*/index.tsx 生成为「窗口名到动态导入」的映射（保留代码分割），运行时的 apiReady 消费它按 __page 挂载窗口。实现与具体打包器无关，替代 Vite 专有的 import.meta.glob；每个打包器插件各自提供，从而支持跨打包器。

工程应设 server.strictPort: true（见 dev lane 注意事项）。

mobkit/rsbuild（实验性）

Rspack 生态的适配层，与 mobkit/vite 共用同一插件核心（mobkit:windows 代码生成、dev lane 逻辑）。当前 syncServer 单端口挂载与 fileProtocol 尚未接入，rsbuild 工程需自行处理生产产物形态。

运行时

浏览器端运行时为独立包，用于单基座工程实现原生多窗口，并在浏览器中以 shim 开发。应用入口只需一行：

// src/main.tsx
import { apiReady } from '@mobkit/runtime/preact'

apiReady() // 等待引擎就绪、解析当前窗口、按需加载并渲染

• @mobkit/runtime/preact：应用入口 apiReady（就绪回调 + 可选 fallback / mount 入参）。
• @mobkit/runtime/win：底层原语（whenReady、resolvePage、win、bus、prefs），供自定义引导。
• @mobkit/runtime/shim：window.api 的浏览器 polyfill；真机由引擎注入，shim 不覆盖。

窗口注册（src/windows/*）与热更由构建插件处理，应用无需感知内部的 mobkit:windows 契约。完整 API 见 @mobkit/runtime。

程序化库

构建工具可在进程内调用，避免启动 CLI 子进程：

import { wifiSync } from 'mobkit'

// 构建后将 dist/ 增量推送到已连接的真机
await wifiSync({ project: process.cwd() })

其他导出：runCli、agentInit，以及 wifi / cloud / project / device 命名空间与 VERSION。

许可

闭源，详见随包 dist/EULA.md（SEE LICENSE IN EULA.md）。