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 集成 | CLI + skill / AGENTS.md（help 即活文档；不写 MCP） | mobkit agent init |

工程形态

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 工程（无 IDE 插件也可闭环）

mobkit cloud create-app --name 我的应用 --template modern
cd <应用目录>
pnpm i
pnpm dev                 # Vite + 同步挂载（端口自 10920 起）+ 终端打印二维码
# AppLoader 扫终端二维码 → 首连自动推 dist → 重进 App 进 Vite HMR
pnpm sync                # 验包：自动 build + 全量推 dist 并退出热更

config.xml 的 content 默认为 dist/index.html（单基座 HTML）。若首页需要原生底栏 Tab，改为 dist/app.json（声明式 tabBar / openTabLayout 语义；各帧仍加载 index.html + pageParam）。热更会话在开发机同步服务内存（GET /_mobkit/dev-lane），不是设备上的门卫 HTML。业务网络请求一律 api.ajax（禁止 WebView fetch，否则跨域）。详见仓库 docs/ai-app-development.md。

vite.config.ts：

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

export default defineConfig({
  base: './', // build 用相对路径；serve 时插件会强制 base:'/' 以适配真机 WebView
  plugins: [
    preact(),
    mobkit({
      syncServer: 'mount'
      // 可选：热更 HTTP 页下代理防盗链图（allowHosts 必填；见 mediaProxy）
      // mediaProxy: { allowHosts: ['example.com'], headers: { Referer: 'https://example.com/' } }
    })
  ],
  server: { host: true } // 端口勿钉 5174：插件从 10920 起找空闲并 strictPort
})

mediaProxy：dev lane 时设备页在 http://，不能加载 file:// 本地图，也不能给 <img> 加 Referer。开启后开发机提供 /_mobkit/media-proxy?url=（白名单主机 + 注入 headers 代拉）。产物 file 页仍应用 api.download+fs://。

契约（单源，浏览器可 import）：

// 客户端 / 业务 H5 —— 勿 import 'mobkit/vite'（Node 插件）
import { mediaProxyUrl, MEDIA_PROXY_PATH } from '@mobkit/runtime'
// 或：import { mediaProxyUrl } from 'mobkit/media'

// vite.config.ts —— 插件侧
import mobkit from 'mobkit/vite'
mobkit({
  mediaProxy: { allowHosts: ['example.com'], headers: { Referer: 'https://example.com/' } }
})
// 默认 path 与 MEDIA_PROXY_PATH 相同；改 path 时客户端 mediaProxyUrl 第三参对齐

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

开发热更（dev lane）

现代工程内环：设备在「Vite 页内 HMR」与「加载 dist 产物」之间切换。

工作原理

1. pnpm dev 挂同步到 Vite 同端口，并在开发机登记热更会话。
2. 设备扫该端口；首连自动全量推 config.xml + dist/（HTML 注入 boot + 同步服务 origin）。
3. 设备开 App → boot 问 {origin}/_mobkit/dev-lane：有会话且 Vite 可达则 location 到 Vite；否则继续 file:// dist。
4. 改码由 Vite HMR 更新；热更中增量 wifi sync 不发 SYNC（避免 AppLoader 整壳重启）。
5. 全量 wifi sync --all / 面板「推构建产物」：自动 build → 推 dist → 退出热更（验包）。

控制方式

| 命令 / 操作 | 作用 | | --------------------- | -------------------------------------- | | pnpm dev | 起 Vite + 挂同步 + 打二维码 + 登记热更 | | mobkit dev --wait | 仅登记热更会话（Vite 已在跑时补登记） | | mobkit dev --off | 清除会话，下次开 App 走 dist | | pnpm sync / --all | 自动 build + 全量推 dist 并退出热更 |

注意事项

• 扫码请用 现代挂载口（10920+），不要扫经典 10918（若 IDE 另起了经典服务）。
• 插件默认 strictPort；端口被占用会启动失败并打印占用者，避免漂到陈旧端口。
• 换网络后重扫码；全量 sync 后若要回热更：再 mobkit dev --wait 或重启 pnpm dev，然后设备重进 App。
• 云端上传打的是 widget 产物包（config + dist），不是完整 TS 工程；现代工程上传前会自动 build。

生产构建产物（file:// 备用）

Android AppLoader 通过 file:// 加载 widget 时，<script type="module"> 会因 MIME 为空被拒。mobkit/vite 默认在 build 时输出单文件 IIFE（经典 script），并剥掉 type=module / crossorigin。dev 走 http:// 不受影响。可设 fileProtocol: false 关闭。

命令行参考

命令附加 --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 | | cloud plugins … | 原生插件 list/add/remove/versions/use-latest/doc | | cloud config … | 端设置：get/set/name/icon/launch（与工作台 CAD 同源） | | cloud certs … | APP 证书：list/tenant/create-android/save-*/bind/download |

环境与工程

| 命令 | 说明 | | -------------- | ----------------------------------------------------------------- | | status | 开发环境总览：同步 / 热更 / 设备 / 工具链 / 云登录（--project） | | project list | 探测工作区工程（与面板概览同源） | | logs | 读沉淀日志（~/.mobkit/logs/）：--cat · --level · --since | | types | 为工程生成 api 类型声明（types/mobkit-api.d.ts） |

真机自动化

| 命令 | 说明 | | ------------------------------------------------ | ------------------------------------------------------------------------ | | 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 | 写入 AGENTS.md 与 .claude/skills/mobkit（CLI 路径；不写 MCP 配置） |

构建插件

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 启动时登记热更会话（开发机内存） | | 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'

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

• @mobkit/runtime：应用入口 apiReady（就绪回调 + 可选 fallback / mount 入参）。渲染由构建插件按工程框架（Preact / React / Vue）适配，导入路径不含框架名。
• @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）。