dsh-android-tool 0.0.0-stage → 0.1.0

package/lib/tools.js

@@ -0,0 +1,179 @@
+/**
+ * 面向模型的 Android 工具。
+ *
+ * 注册在 host 层（所有会话可见）。工具名用 snake_case，与 DSH 自带工具一致。
+ * 所有工具只做参数校验并转给 AndroidService；失败返回结构化 { ok:false, error }。
+ */
+
+const OUTPUT = {
+  schema: { type: 'object', additionalProperties: true },
+  render: (_args, value) => {
+    const blocks = [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+    const image = value?.image
+    if (image !== undefined && image !== null && typeof image.attachmentId === 'string') {
+      blocks.push({ type: 'image', attachment: image })
+    }
+    return blocks
+  },
+}
+
+/**
+ * @param {object} deps
+ * @param {import('./service.js').AndroidService} deps.service
+ */
+export function buildTools(deps) {
+  const service = deps.service
+
+  const view = {
+    name: 'android_view',
+    description: [
+      'Capture the current screen of the selected Android device and return it as an image so you can see it.',
+      'The screenshot is also pushed to the right-side "安卓设备" panel. Use it before/after any control action.',
+      'Returns serial, model, current package/activity, width/height, capture time, and the image itself.',
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        serial: { type: 'string', description: 'Optional device serial. Defaults to the selected device in settings.' },
+        savePath: { type: 'string', description: 'Optional absolute path to also save the PNG to.' },
+        includeState: { type: 'boolean', description: 'Include current model/package/activity in the result. Default true.' },
+      },
+    },
+    output: OUTPUT,
+    isConcurrencySafe: () => false,
+    timeoutMs: 40000,
+    async execute(args) {
+      return service.screencapture({
+        serial: args?.serial,
+        savePath: args?.savePath,
+        includeState: args?.includeState !== false,
+        mark: true,
+      })
+    },
+    presentCall() {
+      return { card: 'generic', title: 'Android 截图', kind: 'read' }
+    },
+  }
+
+  const state = {
+    name: 'android_state',
+    description: [
+      'Query the selected Android device status: model, brand, Android version, battery (level/temperature/charging),',
+      'WiFi (enabled/SSID/IP/airplane mode), memory, storage, screen size/density/wakefulness, and the current foreground app.',
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        serial: { type: 'string', description: 'Optional device serial. Defaults to the selected device.' },
+      },
+    },
+    output: OUTPUT,
+    isConcurrencySafe: () => false,
+    timeoutMs: 40000,
+    async execute(args) {
+      return service.deviceState({ serial: args?.serial })
+    },
+    presentCall() {
+      return { card: 'generic', title: 'Android 设备状态', kind: 'read' }
+    },
+  }
+
+  const control = {
+    name: 'android_control',
+    description: [
+      'Simulate touch/key input on the selected Android device. When the live screen stream is running, it uses the',
+      'low-latency scrcpy control channel (touch/key/text/scroll); otherwise it falls back to `adb shell input`. Actions:',
+      '- tap: {x,y}; long_press: {x,y,durationMs}; swipe: {x1,y1,x2,y2,durationMs}',
+      '- key: {key} (back/home/recents/enter/volume_up/volume_down/power/menu/wakeup or a numeric keycode)',
+      '- text: {text} (scrcpy channel supports Unicode; adb fallback is ASCII only)',
+      '- scroll: {direction: up|down|left|right, amount}; wake; open_app: {package}',
+      'Coordinates are device-screen pixels; when using scrcpy they are scaled to video coordinates automatically.',
+      'By default it captures a screenshot after the action and returns it as an image (capture:false to skip).',
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          required: true,
+          enum: ['tap', 'long_press', 'swipe', 'key', 'text', 'scroll', 'wake', 'open_app'],
+          description: 'The input action.',
+        },
+        x: { type: 'number', description: 'Tap/long-press/swipe start X (device pixels).' },
+        y: { type: 'number', description: 'Tap/long-press/swipe start Y (device pixels).' },
+        x2: { type: 'number', description: 'Swipe end X.' },
+        y2: { type: 'number', description: 'Swipe end Y.' },
+        durationMs: { type: 'integer', description: 'Long-press / swipe duration in milliseconds.' },
+        key: { type: 'string', description: 'Key name or numeric Android keycode.' },
+        text: { type: 'string', description: 'ASCII text to type.' },
+        direction: { type: 'string', enum: ['up', 'down', 'left', 'right'], description: 'Scroll direction.' },
+        amount: { type: 'integer', description: 'Scroll distance in pixels.' },
+        package: { type: 'string', description: 'Package name for open_app.' },
+        serial: { type: 'string', description: 'Optional device serial.' },
+        capture: { type: 'boolean', description: 'Capture a screenshot after the action. Default true.' },
+      },
+    },
+    output: OUTPUT,
+    isConcurrencySafe: () => false,
+    timeoutMs: 90000,
+    async execute(args) {
+      return service.control({
+        action: args?.action,
+        x: args?.x,
+        y: args?.y,
+        x2: args?.x2,
+        y2: args?.y2,
+        durationMs: args?.durationMs,
+        key: args?.key,
+        text: args?.text,
+        direction: args?.direction,
+        amount: args?.amount,
+        package: args?.package,
+        serial: args?.serial,
+        capture: args?.capture !== false,
+      })
+    },
+    presentCall(args) {
+      return { card: 'generic', title: `Android ${String(args?.action ?? 'control')}`, kind: 'write' }
+    },
+  }
+
+  const adb = {
+    name: 'android_adb',
+    description: [
+      'Last-resort: run a raw adb command against the selected device using the plugin-configured adb.',
+      'Prefer android_view / android_state / android_control for normal work; use this only when they cannot express it.',
+      'mode=shell (default) runs `adb -s <serial> shell <command>`; mode=adb treats `command` as adb arguments.',
+      'Returns exit code, stdout, stderr, elapsed time. Interactive commands are not supported and will time out.',
+    ].join('\n'),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        command: { type: 'string', required: true, description: 'Shell command (mode=shell) or adb argv (mode=adb).' },
+        mode: { type: 'string', enum: ['shell', 'adb'], description: 'How to interpret command. Default shell.' },
+        serial: { type: 'string', description: 'Optional device serial.' },
+        timeoutMs: { type: 'integer', description: 'Timeout in milliseconds (default 20000, max 120000).' },
+      },
+    },
+    output: OUTPUT,
+    isConcurrencySafe: () => false,
+    timeoutMs: 130000,
+    async execute(args) {
+      return service.adbCommand({
+        command: args?.command,
+        mode: args?.mode,
+        serial: args?.serial,
+        timeoutMs: args?.timeoutMs,
+      })
+    },
+    presentCall(args) {
+      return { card: 'generic', title: `adb ${String(args?.command ?? '').slice(0, 40)}`, kind: 'write' }
+    },
+  }
+
+  return [view, state, control, adb]
+}

package/lib/webapi.js

@@ -0,0 +1,187 @@
+/**
+ * 面板与设置页的 HTTP / WebSocket 接口（host 半边）。
+ *
+ * 前缀统一 `/x-android-tool`；WS 用精确 upgrade 路径。
+ * 读接口在没设备时也返回 200 + 结构化原因，不让前端白屏。
+ */
+
+/** 各路由完整路径。 */
+export const WEB_ROUTES = {
+  state: '/x-android-tool/state.json',
+  screenshot: '/x-android-tool/screenshot.png',
+  command: '/x-android-tool/command',
+  logcat: '/x-android-tool/logcat.json',
+  logcatExportText: '/x-android-tool/logcat/export.txt',
+  logcatExport: '/x-android-tool/logcat/export',
+  packages: '/x-android-tool/packages.json',
+  perf: '/x-android-tool/perf.json',
+  exec: '/x-android-tool/exec',
+  videoWs: '/x-android-tool/video.ws',
+}
+
+const MAX_BODY_BYTES = 512 * 1024
+
+/** 读 JSON 请求体。 */
+async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > MAX_BODY_BYTES) throw new Error('请求体过大')
+    chunks.push(chunk)
+  }
+  const text = Buffer.concat(chunks).toString('utf8').trim()
+  if (text.length === 0) return {}
+  const parsed = JSON.parse(text)
+  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+}
+
+/** 统一 JSON 响应。 */
+function sendJson(res, status, payload) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(payload))
+}
+
+/** 从 URLSearchParams 取过滤参数。 */
+function filtersFrom(search) {
+  return {
+    serial: search.get('serial') ?? undefined,
+    cursor: Number(search.get('cursor') ?? 0) || 0,
+    pkg: search.get('pkg') ?? '',
+    q: search.get('q') ?? '',
+    level: search.get('level') ?? 'V',
+    limit: Number(search.get('limit') ?? 0) || undefined,
+  }
+}
+
+/**
+ * 注册 HTTP 前缀路由与视频 WebSocket。
+ * @param {object} webServer
+ * @param {{service: import('./service.js').AndroidService, logger?: object}} source
+ * @returns {() => void}
+ */
+export function registerWebRoutes(webServer, source) {
+  const service = source.service
+
+  const stopHttp = webServer.register({
+    kind: 'prefix',
+    path: '/x-android-tool',
+    async handler(req, res) {
+      const url = new URL(req.url ?? '/', 'http://x')
+      const pathname = url.pathname
+      const method = req.method ?? 'GET'
+      const search = url.searchParams
+
+      try {
+        if ((method === 'GET' || method === 'HEAD') && pathname === WEB_ROUTES.state) {
+          const state = await service.uiState()
+          return sendJson(res, 200, state)
+        }
+
+        if ((method === 'GET' || method === 'HEAD') && pathname === WEB_ROUTES.screenshot) {
+          const shot = await service.screenshotBuffer(search.get('serial') ?? undefined)
+          if (shot.ok !== true || !Buffer.isBuffer(shot.buffer)) {
+            res.statusCode = 404
+            res.setHeader('cache-control', 'no-store')
+            res.end(shot.error ?? 'no screenshot')
+            return
+          }
+          res.statusCode = 200
+          res.setHeader('content-type', 'image/png')
+          res.setHeader('content-length', String(shot.buffer.length))
+          res.setHeader('cache-control', 'no-store')
+          res.end(method === 'HEAD' ? undefined : shot.buffer)
+          return
+        }
+
+        if (method === 'GET' && pathname === WEB_ROUTES.logcat) {
+          const result = await service.logcatRead(filtersFrom(search))
+          return sendJson(res, 200, result)
+        }
+
+        if (method === 'GET' && pathname === WEB_ROUTES.logcatExportText) {
+          const filters = filtersFrom(search)
+          const result = await service.exportLogcatText(filters)
+          if (result.ok !== true) return sendJson(res, 200, { ok: false, error: result.error })
+          const name = `logcat-${new Date().toISOString().replace(/[:.]/gu, '-')}.txt`
+          res.statusCode = 200
+          res.setHeader('content-type', 'text/plain; charset=utf-8')
+          res.setHeader('content-disposition', `attachment; filename="${name}"`)
+          res.setHeader('cache-control', 'no-store')
+          res.end(result.text)
+          return
+        }
+
+        if (method === 'GET' && pathname === WEB_ROUTES.packages) {
+          const result = await service.packages({ serial: search.get('serial') ?? undefined })
+          return sendJson(res, 200, result)
+        }
+
+        if (method === 'GET' && pathname === WEB_ROUTES.perf) {
+          const result = await service.perfSample({
+            serial: search.get('serial') ?? undefined,
+            pkg: search.get('pkg') ?? '',
+          })
+          return sendJson(res, 200, result)
+        }
+
+        if (method === 'GET' || method === 'HEAD') {
+          return sendJson(res, 404, { ok: false, error: '未知路由' })
+        }
+        if (method !== 'POST') {
+          res.statusCode = 405
+          res.setHeader('allow', 'GET, HEAD, POST')
+          res.end()
+          return
+        }
+
+        let body
+        try {
+          body = await readJsonBody(req)
+        } catch (error) {
+          return sendJson(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) })
+        }
+
+        if (pathname === WEB_ROUTES.command) {
+          const result = await service.humanCommand(body)
+          return sendJson(res, 200, result)
+        }
+        if (pathname === WEB_ROUTES.logcatExport) {
+          const result = await service.exportLogcat(body)
+          return sendJson(res, 200, result)
+        }
+        if (pathname === WEB_ROUTES.exec) {
+          const result = await service.adbCommand(body)
+          return sendJson(res, 200, result)
+        }
+
+        return sendJson(res, 404, { ok: false, error: '未知路由' })
+      } catch (error) {
+        return sendJson(res, 200, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      }
+    },
+  })
+
+  const stopUpgrade = webServer.registerUpgrade({
+    path: WEB_ROUTES.videoWs,
+    handler(req, socket, head) {
+      try {
+        service.handleVideoUpgrade(req, socket, head)
+      } catch (error) {
+        try {
+          socket.destroy()
+        } catch {
+          // 忽略
+        }
+        source.logger?.warn?.(`dsh-android-tool: video ws 失败 ${error instanceof Error ? error.message : String(error)}`)
+      }
+    },
+  })
+
+  return () => {
+    stopUpgrade?.()
+    stopHttp?.()
+  }
+}

package/lib/ws.js

@@ -0,0 +1,187 @@
+/**
+ * 最小 WebSocket 服务端工具（RFC 6455）。
+ *
+ * 只做本项目需要的事：握手、发送文本/二进制、回复 ping/close、解析客户端
+ * 的 close/ping/pong。不处理分片消息和扩展协商——浏览器发来的控制帧都很小。
+ */
+
+import { createHash } from 'node:crypto'
+
+export const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+/** 计算 Sec-WebSocket-Accept。 */
+export function acceptKey(key) {
+  return createHash('sha1').update(`${String(key ?? '')}${WS_GUID}`).digest('base64')
+}
+
+/**
+ * 生成 101 响应文本；缺少 key 时返回 undefined。
+ * @param {{ headers: Record<string, string|string[]|undefined> }} req
+ */
+export function handshakeResponse(req) {
+  const raw = req?.headers?.['sec-websocket-key']
+  const key = Array.isArray(raw) ? raw[0] : raw
+  if (typeof key !== 'string' || key.length === 0) return undefined
+  return [
+    'HTTP/1.1 101 Switching Protocols',
+    'Upgrade: websocket',
+    'Connection: Upgrade',
+    `Sec-WebSocket-Accept: ${acceptKey(key)}`,
+    '',
+    '',
+  ].join('\r\n')
+}
+
+/** 编码一个服务端帧（不掩码）。 */
+export function encodeFrame(opcode, payload) {
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload ?? ''), 'utf8')
+  const length = body.length
+  let header
+  if (length < 126) {
+    header = Buffer.from([0x80 | opcode, length])
+  } else if (length < 65536) {
+    header = Buffer.alloc(4)
+    header[0] = 0x80 | opcode
+    header[1] = 126
+    header.writeUInt16BE(length, 2)
+  } else {
+    header = Buffer.alloc(10)
+    header[0] = 0x80 | opcode
+    header[1] = 127
+    header.writeBigUInt64BE(BigInt(length), 2)
+  }
+  return Buffer.concat([header, body])
+}
+
+export const encodeText = (text) => encodeFrame(0x1, text)
+export const encodeBinary = (buffer) => encodeFrame(0x2, buffer)
+export const encodePing = () => encodeFrame(0x9, Buffer.alloc(0))
+export const encodePong = (payload) => encodeFrame(0xa, payload ?? Buffer.alloc(0))
+export const encodeClose = () => encodeFrame(0x8, Buffer.alloc(0))
+
+/**
+ * 解析客户端发来的帧（客户端帧一定带掩码）。
+ * @param {Buffer} buffer
+ * @returns {{frames:Array<{opcode:number,payload:Buffer,fin:boolean}>, rest:Buffer}}
+ */
+export function parseFrames(buffer) {
+  const frames = []
+  let offset = 0
+  while (offset + 2 <= buffer.length) {
+    const first = buffer[offset]
+    const second = buffer[offset + 1]
+    const fin = (first & 0x80) !== 0
+    const opcode = first & 0x0f
+    const masked = (second & 0x80) !== 0
+    let length = second & 0x7f
+    let cursor = offset + 2
+    if (length === 126) {
+      if (cursor + 2 > buffer.length) break
+      length = buffer.readUInt16BE(cursor)
+      cursor += 2
+    } else if (length === 127) {
+      if (cursor + 8 > buffer.length) break
+      const big = buffer.readBigUInt64BE(cursor)
+      if (big > BigInt(Number.MAX_SAFE_INTEGER)) break
+      length = Number(big)
+      cursor += 8
+    }
+    let mask
+    if (masked) {
+      if (cursor + 4 > buffer.length) break
+      mask = buffer.subarray(cursor, cursor + 4)
+      cursor += 4
+    }
+    if (cursor + length > buffer.length) break
+    let payload = buffer.subarray(cursor, cursor + length)
+    if (mask !== undefined) {
+      const copy = Buffer.allocUnsafe(payload.length)
+      for (let index = 0; index < payload.length; index += 1) copy[index] = payload[index] ^ mask[index % 4]
+      payload = copy
+    }
+    frames.push({ opcode, payload: Buffer.from(payload), fin })
+    offset = cursor + length
+  }
+  return { frames, rest: buffer.subarray(offset) }
+}
+
+/** 一个已升级的连接。 */
+export class WsConnection {
+  /**
+   * @param {import('node:stream').Duplex} socket
+   * @param {object} req
+   */
+  constructor(socket, req) {
+    this.socket = socket
+    this.req = req
+    this.closed = false
+    this.buffer = Buffer.alloc(0)
+    this.onClose = undefined
+    this.onMessage = undefined
+
+    socket.on('data', (chunk) => this.handleData(chunk))
+    socket.on('error', () => this.destroy())
+    socket.on('close', () => {
+      this.closed = true
+      this.onClose?.()
+    })
+  }
+
+  handleData(chunk) {
+    this.buffer = Buffer.concat([this.buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)])
+    const { frames, rest } = parseFrames(this.buffer)
+    this.buffer = rest
+    for (const frame of frames) {
+      if (frame.opcode === 0x8) {
+        this.send(encodeClose())
+        this.destroy()
+        return
+      }
+      if (frame.opcode === 0x9) {
+        this.send(encodePong(frame.payload))
+        continue
+      }
+      if (frame.opcode === 0xa) continue
+      this.onMessage?.(frame)
+    }
+  }
+
+  send(buffer) {
+    if (this.closed) return false
+    try {
+      this.socket.write(buffer)
+      return true
+    } catch {
+      this.destroy()
+      return false
+    }
+  }
+
+  sendText(text) {
+    return this.send(encodeText(text))
+  }
+
+  sendBinary(buffer) {
+    return this.send(encodeBinary(buffer))
+  }
+
+  ping() {
+    return this.send(encodePing())
+  }
+
+  close() {
+    this.send(encodeClose())
+    this.destroy()
+  }
+
+  destroy() {
+    if (this.closed) return
+    this.closed = true
+    try {
+      this.socket.destroy()
+    } catch {
+      // 忽略
+    }
+    this.onClose?.()
+  }
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "dsh-android-tool",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "把 Android 设备接进 DSH：设置页配置无线调试与 adb，右侧四 Tab 看画面 / Logcat / 性能 / 指令，并给 AI android_view / android_state / android_control / android_adb 四个工具",
+  "private": false,
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE",
+    "scrcpy-win64-v5.0.1"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "android",
+    "adb",
+    "scrcpy",
+    "logcat"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TouMingQAQ/dsh-android-tool.git"
+  },
+  "homepage": "https://github.com/TouMingQAQ/dsh-android-tool#readme",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": ">=3.18.4"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@yume-chan/scrcpy": "^3.0.0-beta.4"
+  }
+}