@kln-mcp/ctrl-mobile-cn 0.0.6

package/config/index.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CONFIG_FILES = {
+  dev: 'dev.json',
+  pro: 'pro.json'
+};
+
+function normalizeEnv(value) {
+  const env = String(value || 'dev').trim().toLowerCase();
+  if (env === 'dev' || env === 'development') {
+    return 'dev';
+  }
+  if (env === 'pro' || env === 'prod' || env === 'production') {
+    return 'pro';
+  }
+  throw new Error(`Invalid config environment "${env}". Expected dev or pro.`);
+}
+
+function resolveConfigPath(runtimeEnv) {
+  const env = normalizeEnv(runtimeEnv || process.env.KLN_ENV || process.env.NODE_ENV);
+  return path.join(__dirname, CONFIG_FILES[env]);
+}
+
+function loadConfig(runtimeEnv) {
+  const file = resolveConfigPath(runtimeEnv);
+  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+
+  validateConfig(config, file);
+
+  return {
+    env: normalizeEnv(runtimeEnv || process.env.KLN_ENV || process.env.NODE_ENV),
+    api_url: config.api_url,
+    relay_urls: config.relay_urls,
+    openobserve: config.openobserve
+  };
+}
+
+function validateConfig(config, file) {
+  if (typeof config.api_url !== 'string' || config.api_url.trim() === '') {
+    throw new Error(`Invalid config ${file}: api_url must be a non-empty string`);
+  }
+
+  if (!Array.isArray(config.relay_urls) || config.relay_urls.length === 0) {
+    throw new Error(`Invalid config ${file}: relay_urls must be a non-empty string array`);
+  }
+
+  for (const relayUrl of config.relay_urls) {
+    if (typeof relayUrl !== 'string' || relayUrl.trim() === '') {
+      throw new Error(`Invalid config ${file}: relay_urls must contain only non-empty strings`);
+    }
+  }
+
+  validateOpenObserve(config.openobserve, file);
+}
+
+function validateOpenObserve(openobserve, file) {
+  if (!openobserve || typeof openobserve !== 'object') {
+    throw new Error(`Invalid config ${file}: openobserve must be an object`);
+  }
+  if (typeof openobserve.enabled !== 'boolean') {
+    throw new Error(`Invalid config ${file}: openobserve.enabled must be a boolean`);
+  }
+  if (typeof openobserve.upload_url !== 'string' || openobserve.upload_url.trim() === '') {
+    throw new Error(`Invalid config ${file}: openobserve.upload_url must be a non-empty string`);
+  }
+  if (typeof openobserve.service_name !== 'string' || openobserve.service_name.trim() === '') {
+    throw new Error(`Invalid config ${file}: openobserve.service_name must be a non-empty string`);
+  }
+}
+
+module.exports = {
+  loadConfig,
+  normalizeEnv,
+  resolveConfigPath
+};

package/config/pro.json

@@ -0,0 +1,12 @@
+{
+  "api_url": "http://192.168.3.33:30001",
+  "relay_urls": ["http://192.168.3.33:80"],
+  "openobserve": {
+    "enabled": true,
+    "upload_url": "http://192.168.3.33:30001/api/default/kln_mcp/_json",
+    "service_name": "mcp",
+    "batch_max_records": 500,
+    "batch_flush_ms": 5000,
+    "disk_buffer_dir": "./runtime/openobserve-buffer/mcp"
+  }
+}

package/core/index.d.ts

@@ -0,0 +1,57 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface JsH264Packet {
+  kind: number
+  flags: number
+  width: number
+  height: number
+  presentationTimeUs: number
+  capturedAtMs: number
+  data: Buffer
+  endReason?: string
+}
+export interface JsH264StreamStats {
+  packets: number
+  bytes: number
+  endReason: string
+}
+export interface JsJsonRpcMessage {
+  ok: boolean
+  id?: any
+  result?: any
+  error?: any
+}
+export interface JsAgentMessage {
+  version: number
+  messageId: string
+  replyTo?: string
+  unixTime: number
+  senderId: string
+  kind: string
+  body: any
+  summary: string
+}
+export interface ConnectOptions {
+  ticket: string
+  relayUrls?: Array<string>
+  alpn?: string
+  apiKey?: string
+}
+export interface SendOptions {
+  timeoutMs?: number
+  traceId?: string
+}
+export declare class KlnCoreClient {
+  static connect(options: ConnectOptions): Promise<KlnCoreClient>
+  get nodeId(): string
+  sendCommand(name: string, bodyText?: string | undefined | null, options?: SendOptions | undefined | null): Promise<JsAgentMessage>
+  sendText(bodyText: string, options?: SendOptions | undefined | null): Promise<JsAgentMessage>
+  sendOnlyCommand(name: string, bodyText?: string | undefined | null, options?: SendOptions | undefined | null): Promise<string>
+  sendJsonRpc(method: string, params?: any | undefined | null, options?: SendOptions | undefined | null): Promise<JsJsonRpcMessage>
+  startH264Stream(bodyText: string | undefined | null, outputDir: string, options?: SendOptions | undefined | null): Promise<string>
+  startH264Live(bodyText: string | undefined | null, onPacket: (...args: any[]) => any, options?: SendOptions | undefined | null): void
+  close(): Promise<void>
+}

package/core/index.js

@@ -0,0 +1,315 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'kln_ctrl_core.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.android-arm64.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'kln_ctrl_core.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'kln_ctrl_core.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'kln_ctrl_core.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'kln_ctrl_core.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'kln_ctrl_core.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./kln_ctrl_core.darwin-universal.node')
+      } else {
+        nativeBinding = require('@kln-ctrl/mobile-core-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'kln_ctrl_core.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.darwin-x64.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'kln_ctrl_core.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'kln_ctrl_core.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./kln_ctrl_core.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@kln-ctrl/mobile-core-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'kln_ctrl_core.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./kln_ctrl_core.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@kln-ctrl/mobile-core-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'kln_ctrl_core.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./kln_ctrl_core.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@kln-ctrl/mobile-core-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { KlnCoreClient } = nativeBinding
+
+module.exports.KlnCoreClient = KlnCoreClient

package/index.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const cli = require('./cli/setup');
+const wrapper = require('./wrapper');
+const core = require('./core');
+const config = require('./config');
+
+module.exports = {
+  ...wrapper,
+  core,
+  config,
+  run: cli.run,
+  parseArgs: cli.parseArgs
+};
+
+if (require.main === module) {
+  cli.run().then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    process.stderr.write(`${error.message || error}\n`);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@kln-mcp/ctrl-mobile-cn",
+  "version": "0.0.6",
+  "description": "KLN mobile control MCP server for OpenClaw (cn)",
+  "bin": {
+    "kln-ctrl-mobile-install": "bin/install.js"
+  },
+  "main": "./index.js",
+  "files": [
+    "bin/",
+    "cli/",
+    "config/",
+    "core/",
+    "skills/",
+    "wrapper/",
+    "index.js"
+  ],
+  "optionalDependencies": {
+    "@kln-ctrl/mobile-core-darwin-arm64": "0.0.6",
+    "@kln-ctrl/mobile-core-darwin-x64": "0.0.6",
+    "@kln-ctrl/mobile-core-linux-x64-gnu": "0.0.6",
+    "@kln-ctrl/mobile-core-linux-arm64-gnu": "0.0.6",
+    "@kln-ctrl/mobile-core-win32-x64-msvc": "0.0.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/kln-mobile-ctrl/SKILL.md

@@ -0,0 +1,122 @@
+# kln-mobile-ctrl
+
+当用户要求 OpenClaw 操作 Android 手机、查看手机屏幕、打开或控制 App、点击/滑动/输入、从移动 App 采集数据，或提到“在我手机上”“帮我点开”“看下 App 里”“截屏”“继续上次”等表达时，使用本 skill。
+
+## 标准循环
+
+处理任何手机控制任务时，必须按以下循环执行：
+
+1. 调用 `kln_get_device_context` 观察当前 App、页面提示、屏幕边界和精简后的可点击元素。
+2. 判断当前页面，并只决定下一步的一个动作。
+3. 使用 `kln_send_command`、`kln_send_text` 或输入类工具执行一个动作。
+4. 动作后必须再次调用 `kln_get_device_context` 确认效果。
+5. 严禁在两次观察之间连续执行多个手机动作。
+6. 如果同一个动作连续 2 次没有明显效果，停止操作并询问用户下一步。
+
+优先使用 `kln_get_device_context` 返回的元素编号和 bounds。若精简上下文不足以判断目标，不要猜，先问用户确认。
+
+## 工具说明
+
+- `kln_get_device_context`：返回精简 JSON，包含 `app`、`page_hint`、`screen_bounds`、`elements`，以及可选的 `truncated` 和 `screenshot_ref`。
+- `kln_send_command`：发送一个原子命令。Android 端支持时，常见命令包括 `tap`、`long_press`、`swipe`、`back`、`open_app`、`wait_idle`。
+- `kln_send_text`：向当前焦点输入框输入文本。
+- `kln_input_tap`、`kln_input_swipe`、`kln_input_text`、`kln_input_clear`、`kln_input_key`：可用时优先使用这些结构化输入工具。
+- `kln_start_screen_stream`：仅用于调试。常规 agent 循环不要依赖投屏流。
+- `kln_task_memory`：本地任务进度 memory，`op` 支持 `list`、`get`、`put`、`delete`。
+
+## 数据采集任务
+
+长任务需要阶段性写入进度：
+
+```json
+{
+  "op": "put",
+  "key": "tiktok-food-20260518",
+  "summary": "TikTok 今日美食爆款抓取",
+  "progress": "已收集 12/30 条",
+  "value": "{\"collected\":[],\"cursor\":\"feed-page-3\"}"
+}
+```
+
+key 使用 `<domain>-<topic>-<YYYYMMDD>` 格式，例如：
+
+- `tiktok-food-20260518`
+- `youtube-food-20260518`
+- `taobao-sneakers-20260518`
+
+每次 `put` 都必须提供 `summary` 和 `progress`。`value` 是不透明 JSON 字符串。不要把账号密码、短信验证码、私有 token 或其他敏感信息写入 task memory。
+
+任务完成后，用 JSON 或紧凑的表格式摘要回复用户。采集结果不要只写散文。
+
+## 任务续接强制流程
+
+当用户表达续接意图，例如“继续”“接着”“上次那个”“还没看完”“恢复”时：
+
+### Step 1：必须先 list
+
+立即调用：
+
+```json
+{ "op": "list" }
+```
+
+不要根据用户话术猜 key。
+
+### Step 2：必须让用户确认
+
+哪怕只有 1 个相关任务，也必须列出来等用户确认。选错 memory 会污染后续采集数据。
+
+多匹配样板：
+
+> 我看到这些进行中的任务，要继续哪个？
+>
+> [1] TikTok 今日美食爆款 - 已 12/30，2 小时前
+> [2] YouTube 今日美食爆款 - 已 5/20，昨天
+>
+> 回复编号，或说“都不是，新开任务”。
+
+单匹配样板：
+
+> 找到 1 个相关任务：
+> “TikTok 今日美食爆款” - 已 12/30，2 小时前
+>
+> 是要继续这个，还是新开任务？
+
+零匹配样板：
+
+> 没找到相关未完成任务，我作为新任务开始，请确认目标：...
+
+### Step 3：确认前不要继续
+
+在用户明确回复编号或确认“是”之前，不要调用 `kln_task_memory` 的 `get`，也不要操作手机。
+
+### Step 4：确认后再恢复
+
+用户确认后：
+
+1. 调用 `kln_task_memory`，使用 `op: "get"` 和确认后的 key。
+2. 调用 `kln_get_device_context` 查看手机当前真实状态。
+3. 从观察到的当前屏幕继续标准循环，不要只依赖 memory 里的进度。
+
+## 示例
+
+用户：“帮我看下今天 TikTok 美食爆款视频”
+
+助手：
+
+1. 调用 `kln_get_device_context`。
+2. 如果 TikTok 未打开，调用 `kln_app_start` 或用 `kln_send_command` 执行 `open_app`。
+3. 再次观察。
+4. 每次只搜索或导航一步。
+5. 有阶段性进展后，调用 `kln_task_memory`，key 例如 `tiktok-food-20260518`。
+6. 最终用 JSON 输出采集结果。
+
+用户：“继续看美食爆款”
+
+助手：
+
+1. `kln_task_memory({ "op": "list" })`
+2. 展示候选并等待用户确认。
+3. 用户确认后才调用 `kln_task_memory({ "op": "get", "key": "..." })`
+4. 用 `kln_get_device_context` 观察手机。
+5. 继续执行“一次观察，一个动作，再观察”的循环。