dsh-phone-control 0.1.2 → 0.1.3

package/README.md

@@ -23,7 +23,8 @@ The settings panel appears under *Settings → Phone bridge*.
 
 1. Install the Android app from the repository's releases page.
 2. Enable its **Accessibility service**.
-3. Open *Settings → Phone bridge* in DSH and read the 8-digit code.
+3. Open *Settings → Phone bridge* in DSH and read the 8-digit code — or scan the QR code the same panel renders
+   (*Scan pairing* in the app fills in code, port and host).
 4. Type the code into the app and tap **Connect**.
 5. The panel turns green; the phone keeps a 30-day token and reconnects by itself afterwards.
 
@@ -38,13 +39,20 @@ The settings panel appears under *Settings → Phone bridge*.
 | `phone_tap` / `phone_long_press` / `phone_swipe` | Coordinate input |
 | `phone_input` / `phone_key` | Type text; send `back` / `home` / `recents` / `notifications` |
 | `phone_open_app` / `phone_current_app` / `phone_list_apps` | Launch, identify, enumerate apps |
+| `phone_fs_list` / `phone_fs_stat` | List a directory (default `/sdcard`) / stat a path |
+| `phone_fs_read` / `phone_fs_write` | Read a file (UTF-8 or base64, paged) / write text or base64 |
+| `phone_fs_mkdir` / `phone_fs_rm` | Create a directory tree / delete a file or directory |
 | `phone_status` / `phone_pair_code` / `phone_disconnect` | Listener state, pairing code, drop session |
 
+While the phone's foreground app is the bridge itself, the input tools answer `SELF_PROTECTED`; the app's
+*Permissions & security* card has a switch (off by default) that lifts it. The file tools stay inside the app's
+private directory until all-files access is granted (`PERMISSION_DENIED` otherwise).
+
 ## Settings panel
 
-Pairing code with countdown and a *New code* button, listening address/port (`0` = auto), bind address,
-paired devices, open sessions, failed attempts, and a *Disconnect* button. Port changes rebind immediately and
-persist to `<profile>/phone-bridge.json`.
+Pairing code with countdown and a *New code* button, a live QR code of the pairing payload (`GET /dsh-phone-control/qr`
+on the DSH web port), listening address/port (`0` = auto), bind address, paired devices, open sessions, failed
+attempts, and a *Disconnect* button. Port changes rebind immediately and persist to `<profile>/phone-bridge.json`.
 
 ## Protocol
 
@@ -54,7 +62,7 @@ AES-256-GCM with the sequence number in the nonce. Only the SHA-256 of the pairi
 
 ## Node version
 
-Requires Node.js 20 or newer. Runtime dependency: `ws`.
+Requires Node.js 20 or newer. Runtime dependencies: `ws`, `qrcode` (the SVG QR route).
 
 ## License
 

package/index.js

@@ -248,6 +248,138 @@ export function apply(ctx, config) {
         )
       },
     }),
+    makeTool({
+      name: 'phone_fs_list',
+      description:
+        '列出手机上的一个目录（默认 /sdcard）：名称、完整路径、是否目录、大小、修改时间、是否可读可写。需要手机端已打开「权限与安全 → 文件读写」，否则只能访问 App 私有目录。',
+      properties: {
+        path: { type: 'string', description: '目录路径，默认 /sdcard' },
+        maxEntries: { type: 'number', description: '最多返回多少条，默认 500，上限 5000' },
+      },
+      timeoutMs: 30000,
+      present: { card: 'generic', title: '手机目录', kind: 'read' },
+      async run(args) {
+        return service.request(
+          'fs_list',
+          { path: String(args?.path ?? '/sdcard'), maxEntries: Number(args?.maxEntries ?? 500) },
+          25000,
+        )
+      },
+    }),
+    makeTool({
+      name: 'phone_fs_stat',
+      description: '查看手机上一个文件或目录的信息：类型、大小、修改时间、可读可写。',
+      properties: { path: { type: 'string', description: '文件或目录的绝对路径' } },
+      required: ['path'],
+      timeoutMs: 15000,
+      present: { card: 'generic', title: '手机文件信息', kind: 'read' },
+      async run(args) {
+        return service.request('fs_stat', { path: String(args.path) }, 10000)
+      },
+    }),
+    makeTool({
+      name: 'phone_fs_read',
+      description:
+        '读取手机上的文件。默认按 UTF-8 文本返回（超过 maxChars 会截断），传 base64: true 则返回原始 base64。大文件用 offset/length 分块，默认一次 512 KB、上限 4 MB。',
+      properties: {
+        path: { type: 'string', description: '文件绝对路径' },
+        offset: { type: 'number', description: '从第几字节开始，默认 0' },
+        length: { type: 'number', description: '读多少字节，默认 524288，上限 4194304' },
+        maxChars: { type: 'number', description: '文本模式最多返回多少字符，默认 20000' },
+        base64: { type: 'boolean', description: '为 true 时返回 base64 而不是文本' },
+      },
+      required: ['path'],
+      timeoutMs: 60000,
+      present: { card: 'generic', title: '读取手机文件', kind: 'read' },
+      async run(args) {
+        const raw = await service.request(
+          'fs_read',
+          {
+            path: String(args.path),
+            offset: Number(args?.offset ?? 0),
+            length: Number(args?.length ?? 512 * 1024),
+          },
+          55000,
+        )
+        const buffer = Buffer.from(String(raw?.dataB64 ?? ''), 'base64')
+        const base = {
+          path: raw?.path,
+          offset: raw?.offset,
+          bytes: raw?.bytes,
+          size: raw?.size,
+          eof: raw?.eof,
+          nextOffset: raw?.nextOffset,
+        }
+        if (args?.base64 === true) return { ...base, data: buffer.toString('base64') }
+        const text = buffer.toString('utf8')
+        const limit = Math.max(0, Number(args?.maxChars ?? 20000))
+        return {
+          ...base,
+          text: text.length > limit ? text.slice(0, limit) : text,
+          truncated: text.length > limit,
+        }
+      },
+    }),
+    makeTool({
+      name: 'phone_fs_write',
+      description:
+        '往手机写文件：文本用 text，二进制用 dataB64；offset 默认 0，truncate 默认 true（覆盖原文件），传 false 可续写。父目录不存在会自动建。',
+      properties: {
+        path: { type: 'string', description: '文件绝对路径' },
+        text: { type: 'string', description: '要写入的文本（UTF-8）' },
+        dataB64: { type: 'string', description: '要写入的二进制（base64），与 text 二选一' },
+        offset: { type: 'number', description: '写入起始偏移，默认 0' },
+        truncate: { type: 'boolean', description: '是否先截断，默认 true' },
+      },
+      required: ['path'],
+      timeoutMs: 60000,
+      present: { card: 'generic', title: '写入手机文件', kind: 'action' },
+      async run(args) {
+        const hasText = typeof args?.text === 'string'
+        const hasData = typeof args?.dataB64 === 'string'
+        if (!hasText && !hasData) throw new Error('要写什么？text 和 dataB64 至少给一个')
+        const dataB64 = hasData ? String(args.dataB64) : Buffer.from(String(args.text), 'utf8').toString('base64')
+        return service.request(
+          'fs_write',
+          {
+            path: String(args.path),
+            dataB64,
+            offset: Number(args?.offset ?? 0),
+            truncate: args?.truncate !== false,
+          },
+          55000,
+        )
+      },
+    }),
+    makeTool({
+      name: 'phone_fs_mkdir',
+      description: '在手机上创建目录（父目录一起建）。',
+      properties: { path: { type: 'string', description: '目录绝对路径' } },
+      required: ['path'],
+      timeoutMs: 15000,
+      present: { card: 'generic', title: '建目录', kind: 'action' },
+      async run(args) {
+        return service.request('fs_mkdir', { path: String(args.path) }, 10000)
+      },
+    }),
+    makeTool({
+      name: 'phone_fs_rm',
+      description: '删除手机上的文件或目录（目录必须 recursive: true）。',
+      properties: {
+        path: { type: 'string', description: '要删除的路径' },
+        recursive: { type: 'boolean', description: '删目录时传 true' },
+      },
+      required: ['path'],
+      timeoutMs: 30000,
+      present: { card: 'generic', title: '删除手机文件', kind: 'action' },
+      async run(args) {
+        return service.request(
+          'fs_rm',
+          { path: String(args.path), recursive: args?.recursive === true },
+          25000,
+        )
+      },
+    }),
     makeTool({
       name: 'phone_tap',
       description: '点击手机屏幕上的一个坐标。坐标系与 phone_screenshot 返回图片的像素坐标一致。',

package/lib/client.js

@@ -72,6 +72,7 @@ window.__ModuleLoader__.load({
 .dshpb-banner { border-radius: 8px; padding: 8px 12px; font-size: 13px; }
 .dshpb-ok { background: rgba(47,168,95,.12); color: var(--dsw-alias-text-primary, inherit); }
 .dshpb-err { background: rgba(220,60,60,.14); color: var(--dsw-alias-text-primary, inherit); }
+.dshpb-qr { width: 200px; height: 200px; border-radius: 10px; background: #fff; padding: 8px; }
 `;
 
     function ensureStyle() {
@@ -115,17 +116,51 @@ window.__ModuleLoader__.load({
       const [busy, setBusy] = React.useState(null);
       const [port, setPort] = React.useState("");
       const [bindHost, setBindHost] = React.useState("0.0.0.0");
+      const [qrAddr, setQrAddr] = React.useState("");
       const [now, setNow] = React.useState(Date.now());
 
+      React.useEffect(() => {
+        try {
+          setQrAddr(window.localStorage.getItem("dshpb.qr.address") ?? "");
+        } catch (error) {
+          setQrAddr("");
+        }
+      }, []);
+
+      const saveQrAddr = (value) => {
+        setQrAddr(value);
+        try {
+          window.localStorage.setItem("dshpb.qr.address", value);
+        } catch (error) {
+          /* 隐私模式下写不了 localStorage，不影响这次显示 */
+        }
+      };
+
       React.useEffect(() => {
         ensureStyle();
       }, []);
 
       React.useEffect(() => {
         let alive = true;
+        let rotating = false;
         const tick = async () => {
           try {
-            const next = await call("/state");
+            let next = await call("/state");
+            if (!alive) return;
+            // 配对码 5 分钟一换：宁可面板上永远显示一个当下的码，
+            // 也不要让用户照着过期码去配、白吃一次 BAD_CODE / CODE_EXPIRED。
+            const expiresAt = Number(next?.status?.codeExpiresAt ?? 0);
+            if (expiresAt > 0 && expiresAt <= Date.now() && !rotating) {
+              rotating = true;
+              try {
+                const fresh = await call("/refresh", {});
+                if (fresh !== undefined) next = fresh;
+              } catch (cause) {
+                /* 换码失败就先把旧状态画出来，下一轮再试 */
+              } finally {
+                rotating = false;
+              }
+            }
             if (!alive) return;
             setState(next);
             setError(null);
@@ -159,6 +194,21 @@ window.__ModuleLoader__.load({
           : "#9AA0A6";
       const remainMs = status === null ? null : status.codeExpiresAt - now;
 
+      // 二维码里放的就是「手机连接电脑需要的最小信息」：配对码 + 端口（可选地址）。
+      // 手机端扫完自动填好，再点一次连接即可；配对码换新时二维码必须跟着变，
+      // 所以 src 里带上 code 当缓存钥匙。
+      const qrCode = status?.pairingCode ?? "";
+      const qrPayload = (() => {
+        if (qrCode === "") return "";
+        const parts = [`v=1`, `c=${qrCode}`, `p=${status?.port ?? 0}`];
+        const addr = qrAddr.trim();
+        if (addr !== "") {
+          if (/^wss?:\/\//iu.test(addr)) parts.push(`w=${encodeURIComponent(addr)}`);
+          else parts.push(`h=${encodeURIComponent(addr)}`);
+        }
+        return `dsh-phone://pair?${parts.join("&")}`;
+      })();
+
       const run = async (key, action, okText) => {
         setBusy(key);
         setNotice(null);
@@ -251,6 +301,44 @@ window.__ModuleLoader__.load({
             ),
           ),
         ),
+        // ---- 扫码配对
+        h(
+          "div",
+          { className: "dshpb-card" },
+          h("div", { className: "dshpb-card-title" }, "扫码配对"),
+          qrPayload === ""
+            ? h("div", { className: "dshpb-dim" }, "配对码还没生成，稍等一秒。")
+            : h(
+                "div",
+                { className: "dshpb-row" },
+                h("img", {
+                  className: "dshpb-qr",
+                  alt: "配对二维码",
+                  width: 200,
+                  height: 200,
+                  src: `${BASE}/qr?s=200&d=${encodeURIComponent(qrPayload)}`,
+                }),
+                h(
+                  "div",
+                  { className: "dshpb-dim", style: { maxWidth: "320px" } },
+                  "手机 App 里点「扫码配对」，对着这块图扫一下：自动填好配对码",
+                  qrAddr.trim() === "" ? "和端口" : "、端口和地址",
+                  "，再点「立即连接」即可。配对码每 5 分钟换新，图会跟着自动变。",
+                ),
+              ),
+          h(
+            "div",
+            { className: "dshpb-row" },
+            h("span", { className: "dshpb-label" }, "对外地址"),
+            h("input", {
+              className: "dshpb-input",
+              value: qrAddr,
+              placeholder: "可选，如 wss://你的域名/ws",
+              onChange: (event) => saveQrAddr(event.target.value),
+            }),
+            h("span", { className: "dshpb-dim" }, "填了会一并写进二维码，手机扫码就不用再手填"),
+          ),
+        ),
         // ---- 监听设置
         h(
           "div",

package/lib/routes.js

@@ -11,12 +11,17 @@
  * behave the same way on the same web server.
  */
 
+import qrcode from 'qrcode'
+
 /** Base path every route lives under. Keep in sync with lib/client.js. */
 export const BASE_PATH = '/dsh-phone-control'
 
 /** Largest request body accepted, in bytes. */
 const MAX_BODY_BYTES = 64 * 1024
 
+/** Longest text we are willing to turn into a QR code. */
+const MAX_QR_TEXT = 512
+
 /**
  * Whether a request may reach these routes.
  *
@@ -123,6 +128,24 @@ export function createHandler(service, options = {}) {
         return
       }
 
+      if (method === 'GET' && action === 'qr') {
+        // Render an arbitrary pairing payload as an SVG QR code. Doing it here
+        // keeps the browser bundle script-only (no bundler, no extra deps on
+        // the client side) while the phone just scans the picture.
+        const text = String(url.searchParams.get('d') ?? '').slice(0, MAX_QR_TEXT)
+        const size = Math.min(Math.max(Number(url.searchParams.get('s') ?? 260) || 260, 120), 640)
+        const svg = text === ''
+          ? ''
+          : await qrcode.toString(text, { type: 'svg', margin: 1, width: size, errorCorrectionLevel: 'M' })
+        res.writeHead(svg === '' ? 400 : 200, {
+          'content-type': 'image/svg+xml; charset=utf-8',
+          'cache-control': 'no-store',
+          'content-length': Buffer.byteLength(svg),
+        })
+        res.end(svg)
+        return
+      }
+
       if (method === 'POST' && action === 'refresh') {
         service.refreshCode(true)
         sendJson(res, 200, snapshot())

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-phone-control",
-  "version": "0.1.2",
-  "description": "Control an Android phone from DeepSeek Harness: read the accessibility tree, tap by text, type text, take screenshots. Pair the companion app once.",
+  "version": "0.1.3",
+  "description": "Control an Android phone from DeepSeek Harness: read the accessibility tree, tap by text, type text, take screenshots, read and write files. Pair the companion app once — by code or by scanning a QR code.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -31,6 +31,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "qrcode": "^1.5.4",
     "ws": "^8.18.0"
   },
   "dsh": {

package/skills/phone-control/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: phone-control
-description: 通过 DSH 手机桥操控已配对的 Android 手机：先截图确认画面，再按截图像素坐标点击、长按、滑动、输入文本、返回/桌面/最近任务或打开应用。
+description: 通过 DSH 手机桥操控已配对的 Android 手机：读控件树/按文字点击/输入文字，必要时截图和坐标操作，还能列目录、读写文件、建删目录。手机 App 需已连接电脑并开启无障碍服务。
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -17,6 +17,7 @@ disable-model-invocation: false
 4. **操作后验证。** 点击、输入、滑动后重新 `phone_ui_dump`（或截图）确认界面确实变化；没有变化就报告，不要连续盲点。
 5. **敏感操作先问。** 支付、转账、发消息、删除数据、修改账号设置前，先向用户确认；用户没有明确要求就不要做。
 6. **失败就说失败。** `NO_DEVICE` 表示手机没连接；`TIMEOUT` 表示手机没响应；`NOT_EDITABLE` 表示该输入框拒绝直接写入（改用 `phone_input` 或让用户手输）；`NODE_NOT_FOUND` 表示树上没有这个文字（先 `phone_ui_dump` 看看实际文案）。
+7. **文件操作先看清再动手。** 写之前先 `phone_fs_stat` / `phone_fs_read` 确认目标（`truncate` 默认覆盖！）；`phone_fs_rm` 删的是用户手机上的真实文件，除非用户明确点名，否则不要删，也不要对 `/sdcard` 之类的大目录跑递归删除。
 
 ## 工具
 
@@ -34,6 +35,10 @@ disable-model-invocation: false
 - `phone_open_app`：按包名打开应用。
 - `phone_current_app`：查看当前前台应用。
 - `phone_list_apps`：列出已安装且可启动的应用（约 250 个）。
+- `phone_fs_list` / `phone_fs_stat`：列目录（默认 `/sdcard`，`maxEntries` 默认 500）、看某个路径的类型/大小/读写权限。
+- `phone_fs_read`：读文件，默认 UTF-8 文本（`maxChars` 默认 20000 会截断），`base64: true` 返回原始字节；大文件用 `offset` + `length` 分块（默认 512 KB，上限 4 MB）。
+- `phone_fs_write`：写文件，文本用 `text`、二进制用 `dataB64`；`truncate` 默认 `true`（覆盖），传 `false` 才续写；父目录自动建。
+- `phone_fs_mkdir` / `phone_fs_rm`：建目录（父目录一起建）/ 删文件或目录（删目录必须 `recursive: true`）。
 - `phone_disconnect`：从电脑端断开当前会话。
 
 ## 坐标建议（iQOO V2425A，截图 1260×2800）
@@ -52,6 +57,8 @@ disable-model-invocation: false
 | `BAD_CODE` | 配对码错误 | 核对 8 位数字，注意剩余次数 |
 | `TOKEN_INVALID` | 登录凭证失效 | 手机 App 会清空旧 token，重新配对 |
 | `TIMEOUT` | 手机未在超时内响应 | 重新截图确认设备是否卡死 |
+| `SELF_PROTECTED` | 输入类命令打到手机桥自己的界面（默认保护） | 先把前台切走；或让用户打开「允许远程操作本 App」 |
+| `PERMISSION_DENIED` | 文件路径越出 App 沙箱，或没开「所有文件访问」 | 让用户在 App 设置页「权限与安全」里授权，或改用 App 私有目录 |
 
 ## 典型流程