termdock 1.4.248 → 1.4.249

package/dist/server/android/scrcpy.js

@@ -0,0 +1,379 @@
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import net from 'node:net';
+import { delimiter, dirname, join } from 'node:path';
+import { randomInt } from 'node:crypto';
+import { adbSearchPath, resolveAdbBinary } from './adb.js';
+const DEVICE_NAME_LENGTH = 64;
+const VIDEO_HEADER_LENGTH = 12;
+const FRAME_HEADER_LENGTH = 12;
+const CONNECT_TIMEOUT_MS = 12_000;
+const CODEC_IDS = {
+    0x68323634: 'h264',
+    0x68323635: 'h265',
+    0x00617631: 'av1',
+};
+function scrcpyExecutableCandidates() {
+    const override = process.env.TERMDOCK_SCRCPY_BIN;
+    const candidates = [];
+    if (override)
+        candidates.push(override);
+    const names = process.platform === 'win32' ? ['scrcpy.exe', 'scrcpy'] : ['scrcpy'];
+    // 用平台路径分隔符切分；Windows 盘符里的 ':' 在正斜杠分隔下会出错。
+    for (const dir of adbSearchPath().split(delimiter).filter(Boolean)) {
+        for (const name of names)
+            candidates.push(join(dir, name));
+    }
+    return candidates;
+}
+function resolveScrcpyBin() {
+    for (const candidate of scrcpyExecutableCandidates())
+        if (existsSync(candidate))
+            return candidate;
+    return null;
+}
+function serverJarCandidates(bin) {
+    const candidates = [process.env.TERMDOCK_SCRCPY_SERVER || ''];
+    if (bin !== 'scrcpy') {
+        let resolved = bin;
+        try {
+            resolved = realpathSync(bin);
+        }
+        catch { /* keep original path */ }
+        const dir = dirname(resolved);
+        candidates.push(join(dir, 'scrcpy-server'));
+        candidates.push(join(dir, '..', 'share', 'scrcpy', 'scrcpy-server'));
+    }
+    candidates.push('/usr/local/share/scrcpy/scrcpy-server');
+    candidates.push('/usr/share/scrcpy/scrcpy-server');
+    candidates.push('/opt/homebrew/share/scrcpy/scrcpy-server');
+    return candidates.filter(Boolean);
+}
+let cachedBinaries;
+function runCapture(file, args, timeout) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, PATH: adbSearchPath() } });
+        let out = '', err = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('SCRCPY_PROBE_TIMEOUT')); }, timeout);
+        child.stdout.on('data', chunk => { out += chunk; });
+        child.stderr.on('data', chunk => { err += chunk; });
+        child.on('error', error => { clearTimeout(timer); reject(error); });
+        child.on('close', code => {
+            clearTimeout(timer);
+            if (code === 0 || out.trim())
+                resolve(out.trim() || err.trim());
+            else
+                reject(new Error(err.trim() || `SCRCPY_PROBE_FAILED_${code}`));
+        });
+    });
+}
+/** 定位 scrcpy 客户端与随包 scrcpy-server，并从 `scrcpy --version` 取协议版本。 */
+export async function resolveScrcpyBinaries() {
+    if (cachedBinaries !== undefined) {
+        if (!cachedBinaries)
+            throw new Error('SCRCPY_NOT_FOUND');
+        return cachedBinaries;
+    }
+    // 找不到绝对路径时退回 PATH 解析（安装包可能把 scrcpy 放在非常规目录）。
+    const bin = resolveScrcpyBin() ?? 'scrcpy';
+    const serverJar = serverJarCandidates(bin).find(candidate => existsSync(candidate));
+    if (!serverJar) {
+        cachedBinaries = null;
+        throw new Error('SCRCPY_SERVER_NOT_FOUND');
+    }
+    let version = '';
+    try {
+        const output = await runCapture(bin, ['--version'], 6000);
+        version = /^scrcpy\s+([0-9][^\s]*)/m.exec(output)?.[1] ?? '';
+    }
+    catch {
+        version = '';
+    }
+    if (!version) {
+        cachedBinaries = null;
+        throw new Error('SCRCPY_VERSION_UNKNOWN');
+    }
+    cachedBinaries = { bin, serverJar, version };
+    return cachedBinaries;
+}
+function remoteJarPath(version) {
+    return `/data/local/tmp/termdock-scrcpy-server-${version}.jar`;
+}
+function adbBinary() {
+    const binary = resolveAdbBinary();
+    if (!binary)
+        throw new Error('ADB_NOT_FOUND');
+    return binary;
+}
+function runAdbCapture(args, timeout = 30_000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(adbBinary(), args, { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, PATH: adbSearchPath() } });
+        let out = '', err = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('ADB_TIMEOUT')); }, timeout);
+        child.on('error', error => { clearTimeout(timer); reject(error); });
+        child.stdout.on('data', chunk => { out += chunk; });
+        child.stderr.on('data', chunk => { err += chunk; });
+        child.on('close', code => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(out.trim());
+            else
+                reject(new Error((err || out).trim() || `ADB_FAILED_${code}`));
+        });
+    });
+}
+function scidHex(scid) {
+    return scid.toString(16).padStart(8, '0');
+}
+/** 单设备的一条 scrcpy 会话：推送 server → adb reverse → 启动 server → 解析 H.264/H.265 流。 */
+export class ScrcpySession {
+    serial;
+    events;
+    options;
+    scid = randomInt(1, 0x7fffffff);
+    child = null;
+    server = null;
+    videoSocket = null;
+    controlSocket = null;
+    videoBuffer = Buffer.alloc(0);
+    controlBuffer = Buffer.alloc(0);
+    videoStage = 'meta';
+    port = 0;
+    stopped = false;
+    started = false;
+    deviceName = '';
+    resolveHeader = null;
+    logLines = [];
+    constructor(serial, events, options = {}) {
+        this.serial = serial;
+        this.events = events;
+        this.options = options;
+    }
+    get running() { return this.started && !this.stopped; }
+    log(line) {
+        const text = line.trim();
+        if (!text)
+            return;
+        this.logLines.push(text);
+        if (this.logLines.length > 40)
+            this.logLines.shift();
+    }
+    fail(error) {
+        if (this.stopped)
+            return;
+        this.events.onError(error);
+        void this.stop();
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        try {
+            const { serverJar, version } = await resolveScrcpyBinaries();
+            const remoteJar = remoteJarPath(version);
+            await runAdbCapture(['-s', this.serial, 'push', serverJar, remoteJar], 60_000);
+            const server = net.createServer();
+            this.server = server;
+            server.on('connection', socket => this.acceptSocket(socket));
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(0, '127.0.0.1', () => { this.port = server.address().port; resolve(); });
+            });
+            await runAdbCapture(['-s', this.serial, 'reverse', `localabstract:scrcpy_${scidHex(this.scid)}`, `tcp:${this.port}`], 15_000);
+            const args = [
+                '-s', this.serial, 'shell',
+                `CLASSPATH=${remoteJar}`,
+                'app_process', '/',
+                'com.genymobile.scrcpy.Server', version,
+                `scid=${this.scid.toString(16)}`,
+                'log_level=info',
+                'audio=false',
+                'control=true',
+                'tunnel_forward=false',
+                'power_on=true',
+                'stay_awake=true',
+                'clipboard_autosync=false',
+                `max_size=${this.options.maxSize ?? 1600}`,
+                `video_bit_rate=${this.options.videoBitRate ?? 8_000_000}`,
+            ];
+            if (this.options.maxFps && this.options.maxFps > 0)
+                args.push(`max_fps=${this.options.maxFps}`);
+            const child = spawn(adbBinary(), args, { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, PATH: adbSearchPath() } });
+            this.child = child;
+            child.stdout?.on('data', chunk => this.log(String(chunk).replace(/^\[server\]\s*/, '')));
+            child.stderr?.on('data', chunk => this.log(String(chunk)));
+            child.on('error', error => this.fail(error instanceof Error ? error : new Error('SCRCPY_SPAWN_FAILED')));
+            child.on('close', () => { if (!this.stopped)
+                this.fail(new Error(this.logLines.at(-1) || 'SCRCPY_SERVER_EXITED')); });
+            await this.waitForHeader();
+        }
+        catch (error) {
+            const normalized = error instanceof Error ? error : new Error('SCRCPY_START_FAILED');
+            if (!this.stopped)
+                this.fail(normalized);
+            throw normalized;
+        }
+    }
+    waitForHeader() {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.resolveHeader = null; reject(new Error('SCRCPY_CONNECT_TIMEOUT')); }, CONNECT_TIMEOUT_MS);
+            this.resolveHeader = () => { clearTimeout(timer); this.resolveHeader = null; resolve(); };
+        });
+    }
+    acceptSocket(socket) {
+        socket.setNoDelay(true);
+        if (!this.videoSocket) {
+            this.videoSocket = socket;
+            socket.on('data', chunk => this.readVideo(chunk));
+            socket.on('error', error => this.fail(error instanceof Error ? error : new Error('VIDEO_SOCKET_ERROR')));
+            socket.on('close', () => { if (!this.stopped)
+                this.fail(new Error(this.logLines.at(-1) || 'VIDEO_SOCKET_CLOSED')); });
+            return;
+        }
+        if (!this.controlSocket) {
+            this.controlSocket = socket;
+            // 控制通道会回传剪贴板/ACK 等设备消息；v1 只消费，避免读缓冲堆积。
+            socket.on('data', chunk => this.readControl(chunk));
+            socket.on('error', () => { });
+            return;
+        }
+        socket.destroy();
+    }
+    readVideo(chunk) {
+        if (this.stopped)
+            return;
+        this.videoBuffer = Buffer.concat([this.videoBuffer, chunk]);
+        if (this.videoStage === 'meta') {
+            if (this.videoBuffer.length < DEVICE_NAME_LENGTH)
+                return;
+            this.deviceName = this.videoBuffer.subarray(0, DEVICE_NAME_LENGTH).toString('utf8').replace(/\0+$/, '');
+            this.videoBuffer = this.videoBuffer.subarray(DEVICE_NAME_LENGTH);
+            this.videoStage = 'codec';
+        }
+        if (this.videoStage === 'codec') {
+            if (this.videoBuffer.length < VIDEO_HEADER_LENGTH)
+                return;
+            const codec = CODEC_IDS[this.videoBuffer.readUInt32BE(0)];
+            const width = this.videoBuffer.readUInt32BE(4);
+            const height = this.videoBuffer.readUInt32BE(8);
+            this.videoBuffer = this.videoBuffer.subarray(VIDEO_HEADER_LENGTH);
+            this.videoStage = 'frames';
+            if (!codec) {
+                this.fail(new Error('SCRCPY_UNSUPPORTED_CODEC'));
+                return;
+            }
+            this.events.onHeader({ codec, width, height, deviceName: this.deviceName || this.serial });
+            this.resolveHeader?.();
+        }
+        while (this.videoStage === 'frames' && this.videoBuffer.length >= FRAME_HEADER_LENGTH) {
+            const ptsFlags = this.videoBuffer.readBigUInt64BE(0);
+            const size = this.videoBuffer.readUInt32BE(8);
+            if (this.videoBuffer.length < FRAME_HEADER_LENGTH + size)
+                break;
+            const payload = Buffer.from(this.videoBuffer.subarray(FRAME_HEADER_LENGTH, FRAME_HEADER_LENGTH + size));
+            this.videoBuffer = this.videoBuffer.subarray(FRAME_HEADER_LENGTH + size);
+            const config = ((ptsFlags >> 63n) & 1n) === 1n;
+            const keyFrame = ((ptsFlags >> 62n) & 1n) === 1n;
+            this.events.onFrame({ config, keyFrame, pts: ptsFlags & ((1n << 62n) - 1n), data: payload });
+        }
+    }
+    readControl(chunk) {
+        this.controlBuffer = Buffer.concat([this.controlBuffer, chunk]);
+        while (this.controlBuffer.length > 0) {
+            const type = this.controlBuffer[0];
+            if (type === 0) {
+                if (this.controlBuffer.length < 5)
+                    return;
+                const length = this.controlBuffer.readUInt32BE(1);
+                if (this.controlBuffer.length < 5 + length)
+                    return;
+                this.controlBuffer = this.controlBuffer.subarray(5 + length);
+            }
+            else if (type === 1) {
+                if (this.controlBuffer.length < 9)
+                    return;
+                this.controlBuffer = this.controlBuffer.subarray(9);
+            }
+            else {
+                this.controlBuffer = Buffer.alloc(0);
+                return;
+            }
+        }
+    }
+    /** 客户端消费不过来时暂停视频 socket：让内核缓冲填满，把反压传到设备端，
+     * 从而在不丢帧的前提下限制延迟（丢 delta 会让参考帧链断裂、画面花屏）。 */
+    pauseVideo() {
+        if (this.videoPaused)
+            return;
+        this.videoPaused = true;
+        try {
+            this.videoSocket?.pause();
+        }
+        catch { /* ignore */ }
+    }
+    resumeVideo() {
+        if (!this.videoPaused)
+            return;
+        this.videoPaused = false;
+        try {
+            this.videoSocket?.resume();
+        }
+        catch { /* ignore */ }
+    }
+    videoPaused = false;
+    sendControl(data) {
+        const socket = this.controlSocket;
+        if (!socket || socket.destroyed)
+            return false;
+        try {
+            socket.write(data);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        activeSessions.delete(this);
+        const child = this.child;
+        this.child = null;
+        try {
+            this.videoSocket?.destroy();
+        }
+        catch { /* ignore */ }
+        try {
+            this.controlSocket?.destroy();
+        }
+        catch { /* ignore */ }
+        this.videoSocket = null;
+        this.controlSocket = null;
+        try {
+            this.server?.close();
+        }
+        catch { /* ignore */ }
+        this.server = null;
+        if (child) {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            await runAdbCapture(['-s', this.serial, 'reverse', '--remove', `localabstract:scrcpy_${scidHex(this.scid)}`], 8000);
+        }
+        catch { /* reverse 可能已随进程退出被清理 */ }
+        this.events.onClose();
+    }
+}
+const activeSessions = new Set();
+export function createScrcpySession(serial, events, options) {
+    const session = new ScrcpySession(serial, events, options);
+    activeSessions.add(session);
+    return session;
+}
+export async function stopAllScrcpySessions() {
+    await Promise.all([...activeSessions].map(session => session.stop()));
+}

package/dist/server/entry.js

@@ -30,6 +30,8 @@ import cookieParser from 'cookie-parser';
 import { fileURLToPath } from 'url';
 import { WebSocketServer } from 'ws';
 import terminalRoutes, { handleTerminalWebSocket, handleControlWebSocket, resolveStableFederationSessionId } from './routes/terminal.js';
+import androidRoutes, { handleAndroidWebSocket } from './routes/android.js';
+import { stopAllScrcpySessions } from './android/scrcpy.js';
 import filesystemRoutes from './routes/filesystem.js';
 import authRoutes from './routes/auth.js';
 import notificationRoutes from './routes/notifications.js';
@@ -336,6 +338,11 @@ export function createApp(options = {}) {
     app.use('/api/terminal', terminalRoutes);
     // 文件系统路由（继承 /api/terminal 上的 auth + CSRF 保护）
     app.use('/api/terminal/fs', filesystemRoutes);
+    // 本机 Android 设备桥接（adb/scrcpy）。经加密隧道时按业务 API 处理，
+    // 仅全权服务授权可达；投屏 WS 在 federation runtime 中按 full-service 校验。
+    app.use('/api/android', requireAuth({ bypass: isTrustedLocalCliRequest }));
+    app.use('/api/android', csrfProtection.verifyMiddleware({ bypass: isTrustedLocalCliRequest }));
+    app.use('/api/android', androidRoutes);
     if (fs.existsSync(bundledClientIndexPath)) {
         const selectedClientPath = resolveRuntimeClientDist(bundledClientDistPath);
         const clientPath = selectedClientPath === bundledClientDistPath
@@ -449,8 +456,9 @@ export function startServer(options = {}) {
     server.once('close', () => { clearInterval(desktopRoutesTimer); for (const target of dynamicDirectTargets.values())
         target.close(); });
     server.once('close', () => relayRouter.close());
+    server.once('close', () => { void stopAllScrcpySessions(); });
     const federation = createFederationRuntime(app, path.join(homedir(), '.termdock', 'federation'), {
-        terminal: handleTerminalWebSocket, control: handleControlWebSocket,
+        terminal: handleTerminalWebSocket, control: handleControlWebSocket, android: handleAndroidWebSocket,
     }, {
         resolveSessionId: resolveStableFederationSessionId,
         collaborationConnected: (subjectId, rpc) => {

package/dist/server/federation/runtime.js

@@ -252,7 +252,12 @@ export async function createFederationRuntime(app, directory, handlers, options
                 }
             }
             revokeTimer = setInterval(() => {
-                for (const { socket: logical, sessionId } of sockets.values()) {
+                for (const { socket: logical, sessionId, android } of sockets.values()) {
+                    if (android) {
+                        if (!full(subjectId))
+                            logical.close(4003, 'Authorization revoked');
+                        continue;
+                    }
                     if (!allowed(subjectId, sessionId ? 'session.view' : 'service.view', sessionId))
                         logical.close(4003, 'Authorization revoked');
                 }
@@ -558,14 +563,19 @@ export async function createFederationRuntime(app, directory, handlers, options
                             throw new Error('API_NOT_ALLOWED');
                         const url = new URL(packet.path, 'http://inner');
                         const match = /^\/api\/terminal\/([^/%]+)\/ws$/.exec(url.pathname);
+                        const androidMatch = /^\/api\/android\/([^/%]+)\/ws$/.exec(url.pathname);
                         if (match)
                             check('session.view', match[1]);
                         else if (url.pathname === '/api/control/ws')
                             check('service.view');
+                        else if (androidMatch) {
+                            if (!full(subjectId))
+                                throw new Error('API_NOT_ALLOWED');
+                        }
                         else
                             throw new Error('API_NOT_ALLOWED');
-                        const logical = new LogicalSocket(channel, packet.id, () => allowed(subjectId, match ? 'session.view' : 'service.view', match?.[1]));
-                        sockets.set(packet.id, { socket: logical, sessionId: match?.[1] });
+                        const logical = new LogicalSocket(channel, packet.id, () => androidMatch ? full(subjectId) : allowed(subjectId, match ? 'session.view' : 'service.view', match?.[1]));
+                        sockets.set(packet.id, { socket: logical, sessionId: match?.[1], android: Boolean(androidMatch) });
                         logical.once('close', () => sockets.delete(packet.id));
                         send({ type: 'ws-ready', id: packet.id });
                         if (match)
@@ -574,6 +584,15 @@ export async function createFederationRuntime(app, directory, handlers, options
                                 flowControl: url.searchParams.get('flow') === '2', outputActive: url.searchParams.get('active') !== '0',
                                 independentTmux: full(subjectId) && url.searchParams.get('transport') === 'tmux-client',
                             }, allowed(subjectId, 'session.resize', match[1]) ? readTerminalHandshakeDimensions(url.searchParams) : undefined);
+                        else if (androidMatch) {
+                            if (!handlers.android)
+                                throw new Error('API_NOT_ALLOWED');
+                            handlers.android(logical, androidMatch[1], randomUUID(), {
+                                maxSize: Number(url.searchParams.get('max_size')) || undefined,
+                                bitRate: Number(url.searchParams.get('bit_rate')) || undefined,
+                                maxFps: Number(url.searchParams.get('max_fps')) || undefined,
+                            });
+                        }
                         else
                             handlers.control(logical, randomUUID());
                     }
@@ -582,7 +601,13 @@ export async function createFederationRuntime(app, directory, handlers, options
                         if (!item || typeof packet.data !== 'string')
                             throw new Error('INVALID_STREAM');
                         const data = JSON.parse(packet.data);
-                        if (item.sessionId) {
+                        if (item.android) {
+                            if (!full(subjectId))
+                                throw new Error('AUTHORIZATION_DENIED');
+                            if (!['control', 'ack', 'ping'].includes(data?.type))
+                                throw new Error('ACTION_NOT_ALLOWED');
+                        }
+                        else if (item.sessionId) {
                             const action = terminalMessageAction(data.type);
                             if (!action)
                                 throw new Error('ACTION_NOT_ALLOWED');

package/dist/server/routes/android.js

@@ -0,0 +1,205 @@
+import { Router } from 'express';
+import { connectDevice, disconnectDevice, listDevices, resolveAdbBinary } from '../android/adb.js';
+import { createScrcpySession, resolveScrcpyBinaries } from '../android/scrcpy.js';
+const router = Router();
+const SERIAL_PATTERN = /^[0-9a-zA-Z_.:\-]{1,128}$/;
+/** 逐帧/逐控件的诊断日志默认关闭，需要时 TERMDOCK_ANDROID_DEBUG=1 打开。 */
+const DEBUG_ANDROID = process.env.TERMDOCK_ANDROID_DEBUG === '1';
+export function isValidAndroidSerial(serial) {
+    return SERIAL_PATTERN.test(serial);
+}
+router.get('/devices', async (_req, res) => {
+    try {
+        const devices = await listDevices();
+        let scrcpyVersion = null;
+        const adbAvailable = resolveAdbBinary() !== null;
+        try {
+            scrcpyVersion = (await resolveScrcpyBinaries()).version;
+        }
+        catch {
+            scrcpyVersion = null;
+        }
+        res.json({ adbAvailable, scrcpyVersion, devices });
+    }
+    catch (error) {
+        res.status(503).json({ error: error instanceof Error ? error.message : 'ADB_UNAVAILABLE', code: 'ADB_UNAVAILABLE' });
+    }
+});
+router.post('/connect', async (req, res) => {
+    const address = typeof req.body?.address === 'string' ? req.body.address : '';
+    try {
+        const result = await connectDevice(address);
+        res.json({ ok: true, serial: result.serial, output: result.output });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'ADB_CONNECT_FAILED';
+        res.status(400).json({ error: message, code: message });
+    }
+});
+router.post('/disconnect', async (req, res) => {
+    const address = typeof req.body?.address === 'string' ? req.body.address : '';
+    try {
+        res.json({ ok: true, output: await disconnectDevice(address) });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'ADB_DISCONNECT_FAILED';
+        res.status(400).json({ error: message, code: message });
+    }
+});
+export default router;
+function clampInt(value, min, max, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.round(value)));
+}
+/** 加密隧道打开 `/api/android/:serial/ws` 后的桥接：视频帧下发、控制消息回写。 */
+export function handleAndroidWebSocket(socket, serial, _clientId, requested = {}) {
+    if (!isValidAndroidSerial(serial)) {
+        socket.close(4400, 'INVALID_SERIAL');
+        return;
+    }
+    // 网络差时客户端可主动降码率/分辨率；这里对入参做边界收敛。
+    const quality = {
+        maxSize: clampInt(requested.maxSize, 360, 2160, 1600),
+        videoBitRate: clampInt(requested.bitRate, 300_000, 30_000_000, 8_000_000),
+        maxFps: clampInt(requested.maxFps, 0, 60, 0),
+    };
+    let closed = false;
+    let inflight = 0;
+    let seq = 0;
+    let sent = 0;
+    let acked = 0;
+    let controlCount = 0;
+    let lastAckAt = 0;
+    let lastFrameAt = Date.now();
+    let videoPaused = false;
+    let androidSendSkipLogged = false;
+    let session = null;
+    // 客户端 ack 丢失时不能让视频永久暂停：超时视为丢包并恢复。
+    const flowTimer = setInterval(() => {
+        if (videoPaused && Date.now() - Math.max(lastAckAt, lastFrameAt) > 3000) {
+            if (DEBUG_ANDROID)
+                console.log(`[android] flow resume after ack timeout serial=${serial} inflight=${inflight} sent=${sent} acked=${acked}`);
+            videoPaused = false;
+            session?.resumeVideo();
+        }
+    }, 1000);
+    const statsTimer = DEBUG_ANDROID ? setInterval(() => {
+        if (sent > 0)
+            console.log(`[android] stats serial=${serial} sent=${sent} acked=${acked} inflight=${inflight} controls=${controlCount} paused=${videoPaused}`);
+    }, 10_000) : null;
+    const FRAME_WINDOW = 3;
+    const send = (payload) => {
+        if (closed || socket.readyState !== 1) {
+            if (!androidSendSkipLogged) {
+                androidSendSkipLogged = true;
+                console.log(`[android] send skipped serial=${serial} closed=${closed} readyState=${socket.readyState} type=${String(payload.type)}`);
+            }
+            return;
+        }
+        try {
+            socket.send(JSON.stringify(payload));
+        }
+        catch (error) {
+            console.log(`[android] send failed serial=${serial} type=${String(payload.type)} ${error instanceof Error ? error.message : 'unknown'}`);
+        }
+    };
+    const shutdown = (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(flowTimer);
+        if (statsTimer)
+            clearInterval(statsTimer);
+        if (DEBUG_ANDROID)
+            console.log(`[android] session end serial=${serial} sent=${sent} acked=${acked} reason=${reason ?? 'ok'}`);
+        if (reason)
+            send({ type: 'error', message: reason });
+        try {
+            session?.stop();
+        }
+        catch { /* ignore */ }
+        session = null;
+        try {
+            socket.close(1000, reason ? 'error' : 'closed');
+        }
+        catch { /* ignore */ }
+    };
+    socket.on('close', () => { closed = true; clearInterval(flowTimer); if (statsTimer)
+        clearInterval(statsTimer); void session?.stop(); session = null; });
+    socket.on('error', () => { closed = true; clearInterval(flowTimer); if (statsTimer)
+        clearInterval(statsTimer); void session?.stop(); session = null; });
+    session = createScrcpySession(serial, {
+        onHeader: header => { send({ type: 'header', ...header }); },
+        onFrame: frame => {
+            if (closed)
+                return;
+            // 不丢任何帧：客户端慢时暂停视频 socket，用反压换低延迟。
+            inflight++;
+            if (DEBUG_ANDROID && (sent < 12 || frame.keyFrame))
+                console.log(`[android] send frame #${sent} serial=${serial} config=${frame.config} key=${frame.keyFrame} bytes=${frame.data.length}`);
+            sent++;
+            lastFrameAt = Date.now();
+            send({
+                type: 'frame', seq: ++seq, config: frame.config, key: frame.keyFrame,
+                pts: frame.pts.toString(), data: frame.data.toString('base64'),
+            });
+            if (!videoPaused && inflight >= FRAME_WINDOW) {
+                videoPaused = true;
+                session?.pauseVideo();
+            }
+        },
+        onError: error => shutdown(error.message || 'SCRCPY_ERROR'),
+        onClose: () => { if (!closed) {
+            send({ type: 'closed' });
+            closed = true;
+            try {
+                socket.close(1000, 'closed');
+            }
+            catch { /* ignore */ }
+        } },
+    }, quality);
+    void session.start().catch(error => shutdown(error instanceof Error ? error.message : 'SCRCPY_START_FAILED'));
+    socket.on('message', raw => {
+        if (closed || !session)
+            return;
+        let message;
+        try {
+            message = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf8'));
+        }
+        catch {
+            return;
+        }
+        switch (message.type) {
+            case 'control': {
+                if (typeof message.data !== 'string' || message.data.length > 64 * 1024)
+                    return;
+                const bytes = Buffer.from(message.data, 'base64');
+                const ok = session.sendControl(bytes);
+                if (DEBUG_ANDROID && controlCount++ < 8) {
+                    const detail = bytes[0] === 2 && bytes.length >= 32
+                        ? ` touch action=${bytes[1]} x=${bytes.readUInt32BE(10)} y=${bytes.readUInt32BE(14)} size=${bytes.readUInt16BE(18)}x${bytes.readUInt16BE(20)}`
+                        : ` type=${bytes[0]}`;
+                    console.log(`[android] control #${controlCount} serial=${serial} bytes=${bytes.length} written=${ok}${detail}`);
+                }
+                break;
+            }
+            case 'ack': {
+                if (typeof message.seq === 'number') {
+                    inflight = Math.max(0, inflight - 1);
+                    acked++;
+                    lastAckAt = Date.now();
+                    if (videoPaused && inflight < FRAME_WINDOW) {
+                        videoPaused = false;
+                        session?.resumeVideo();
+                    }
+                }
+                break;
+            }
+            case 'ping':
+                send({ type: 'pong' });
+                break;
+            default: break;
+        }
+    });
+}