evolclaw 3.1.4 → 3.1.6

package/dist/cli/net-check.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import os from 'os';
 import net from 'net';
 import tls from 'tls';
 import dns from 'dns/promises';
@@ -7,7 +8,7 @@ import https from 'https';
 // @ts-ignore
 import { WebSocket } from 'ws';
 import { aunPath as defaultAunPath } from '../paths.js';
-import { createAunClient } from '../aun/aid/client.js';
+import { getAidStore, loadClient, SLOT } from '../aun/aid/store.js';
 import { isHelpFlag } from './help.js';
 const GREEN = '\x1b[32m';
 const RED = '\x1b[31m';
@@ -21,7 +22,7 @@ function ok(msg) { return `  ${GREEN}✓${RST} ${msg}`; }
 function fail(msg) { return `  ${RED}✗${RST} ${msg}`; }
 function skip(msg) { return `  ${YELLOW}○${RST} ${DIM}${msg}${RST}`; }
 function ms(n) { return `${DIM}${n}ms${RST}`; }
-function step(n, label) { return `${DIM}[${n}/10]${RST} ${CYAN}${label}${RST}`; }
+function step(n, label) { return `${DIM}[${n}/11]${RST} ${CYAN}${label}${RST}`; }
 const isZh = (process.env.LANG || process.env.LC_ALL || process.env.LANGUAGE || Intl.DateTimeFormat().resolvedOptions().locale || '').toLowerCase().startsWith('zh');
 const i18n = {
     resolve: isZh ? '解析' : 'resolve',
@@ -124,7 +125,7 @@ function suppressSdkOutput(fn) {
     });
 }
 // ==================== Check pipeline ====================
-async function runCheck(aid, formatJson) {
+async function runCheck(aid, formatJson, kickTest) {
     const results = [];
     const log = (r) => {
         results.push(r);
@@ -216,18 +217,23 @@ async function runCheck(aid, formatJson) {
         }
     }
     // ── Step 7: AID 认证 ──
-    let accessToken;
+    let authResult;
     try {
         const start = Date.now();
         const aunPath = process.env.AUN_HOME || defaultAunPath();
-        const result = await suppressSdkOutput(async () => {
-            const client = await createAunClient({ aunPath });
-            await client.auth.createAid({ aid });
-            const authResult = await client.auth.authenticate({ aid });
-            await client.close().catch(() => { });
-            return authResult;
+        authResult = await suppressSdkOutput(async () => {
+            const store = await getAidStore({ slotId: SLOT.netcheck, aunPath });
+            try {
+                const client = await loadClient(store, aid);
+                const result = await client.authenticate();
+                await client.close();
+                return result;
+            }
+            finally {
+                store.close();
+            }
         });
-        accessToken = result?.access_token;
+        const accessToken = authResult?.access_token;
         const elapsed = Date.now() - start;
         if (accessToken) {
             log({ step: 'Auth', index: 7, ok: true, detail: `${aid} ${i18n.authOk} (login1→login2→token)`, ms: elapsed });
@@ -270,16 +276,17 @@ async function runCheck(aid, formatJson) {
     try {
         const start = Date.now();
         const aunPath = process.env.AUN_HOME || defaultAunPath();
-        const sendResult = await suppressSdkOutput(async () => {
-            const client = await createAunClient({ aunPath });
-            await client.auth.createAid({ aid });
-            const authResult = await client.auth.authenticate({ aid });
-            const at = authResult?.access_token || client._access_token;
-            const gw = client._gatewayUrl || authResult?.gateway;
-            await client.connect({ access_token: at, gateway: gw, connection_kind: 'short' }, { auto_reconnect: false });
-            const r = await client.call('meta.ping', {});
-            await client.close().catch(() => { });
-            return r;
+        await suppressSdkOutput(async () => {
+            const store = await getAidStore({ slotId: SLOT.netcheck, aunPath });
+            try {
+                const client = await loadClient(store, aid);
+                await client.connect();
+                await client.call('meta.ping', {});
+                await client.close();
+            }
+            finally {
+                store.close();
+            }
         });
         const elapsed = Date.now() - start;
         log({ step: 'Ping', index: 9, ok: true, detail: `meta.ping ${i18n.pingOk}`, ms: elapsed });
@@ -362,14 +369,14 @@ async function runCheck(aid, formatJson) {
             return results;
         }
         if (!formatJson) {
-            console.log(`  ${DIM}[10/10]${RST} ${CYAN}Echo${RST}  ${DIM}${targets.length} target(s)${RST}`);
+            console.log(`  ${DIM}[10/11]${RST} ${CYAN}Echo${RST}  ${DIM}${targets.length} target(s)${RST}`);
         }
         const echoResults = [];
         // 读取所有目标的 agent.md（含签名验证）获取昵称和类型
         const { agentmdGet: agentmdGetFn } = await import('../aun/aid/index.js');
         const targetMeta = new Map();
         if (!formatJson) {
-            console.log(`  ${DIM}[10/10]${RST} ${CYAN}Echo${RST}  ${DIM}reading agent.md for ${targets.length} target(s)...${RST}`);
+            console.log(`  ${DIM}[10/11]${RST} ${CYAN}Echo${RST}  ${DIM}reading agent.md for ${targets.length} target(s)...${RST}`);
         }
         await Promise.all(targets.map(async (t) => {
             const start = Date.now();
@@ -420,29 +427,31 @@ async function runCheck(aid, formatJson) {
             const label = targetLabel(target);
             try {
                 const replyText = await suppressSdkOutput(async () => {
-                    const client = await createAunClient({ aunPath });
-                    await client.auth.createAid({ aid });
-                    const authResult = await client.auth.authenticate({ aid });
-                    const at = authResult?.access_token || client._access_token;
-                    const gw = client._gatewayUrl || authResult?.gateway;
-                    await client.connect({ access_token: at, gateway: gw, slot_id: 'net-check', connection_kind: 'short' }, { auto_reconnect: false });
-                    // 取基线 seq
-                    const baseline = await client.call('message.pull', { limit: 100 });
-                    const baselineSeq = baseline?.latest_seq ?? 0;
-                    if (baselineSeq > 0) {
-                        await client.call('message.ack', { seq: baselineSeq });
+                    const store = await getAidStore({ slotId: SLOT.netcheck, aunPath });
+                    try {
+                        const client = await loadClient(store, aid);
+                        await client.connect();
+                        // 取基线 seq
+                        const baseline = await client.call('message.pull', { limit: 100 });
+                        const baselineSeq = baseline?.latest_seq ?? 0;
+                        if (baselineSeq > 0) {
+                            await client.call('message.ack', { seq: baselineSeq });
+                        }
+                        await client.call('message.send', {
+                            to: target,
+                            payload: { type: 'text', text: 'echo[nc]' },
+                            encrypt: false,
+                        });
+                        await new Promise(r => setTimeout(r, 1500));
+                        const pullResult = await client.call('message.pull', { after_seq: baselineSeq, limit: 10 });
+                        await client.close();
+                        const messages = pullResult?.messages || [];
+                        const reply = messages.find((m) => m.from === target && m.payload?.text?.includes('[EvolClaw.'));
+                        return reply?.payload?.text || null;
+                    }
+                    finally {
+                        store.close();
                     }
-                    await client.call('message.send', {
-                        to: target,
-                        payload: { type: 'text', text: 'echo[nc]' },
-                        encrypt: false,
-                    });
-                    await new Promise(r => setTimeout(r, 1500));
-                    const pullResult = await client.call('message.pull', { after_seq: baselineSeq, limit: 10 });
-                    await client.close().catch(() => { });
-                    const messages = pullResult?.messages || [];
-                    const reply = messages.find((m) => m.from === target && m.payload?.text?.includes('[EvolClaw.'));
-                    return reply?.payload?.text || null;
                 });
                 const elapsed = Date.now() - targetStart;
                 if (replyText) {
@@ -481,6 +490,77 @@ async function runCheck(aid, formatJson) {
     catch (e) {
         log({ step: 'Echo', index: 10, ok: false, detail: `echo ${i18n.failed}: ${e.message?.slice(0, 100) || String(e)}` });
     }
+    // ── Step 11: 踢人测试 / extra_info 验证 ──
+    if (kickTest) {
+        try {
+            const kickStart = Date.now();
+            const aunPath = process.env.AUN_HOME || defaultAunPath();
+            const hostname = os.hostname();
+            const kickResult = await suppressSdkOutput(async () => {
+                const store = await getAidStore({ slotId: SLOT.netcheck, aunPath });
+                try {
+                    const client = await loadClient(store, aid);
+                    const disconnectEvents = [];
+                    client.on('gateway.disconnect', (payload) => {
+                        disconnectEvents.push(payload);
+                    });
+                    await client.connect({
+                        connection_kind: 'long',
+                        extra_info: {
+                            app: 'evolclaw',
+                            role: 'netcheck-kicktest',
+                            pid: process.pid,
+                            hostname,
+                        },
+                    });
+                    // 等待 3 秒收集可能的 disconnect 事件
+                    await new Promise(r => setTimeout(r, 3000));
+                    await client.close();
+                    return { connected: true, disconnectEvents };
+                }
+                finally {
+                    store.close();
+                }
+            });
+            const elapsed = Date.now() - kickStart;
+            const { connected, disconnectEvents } = kickResult;
+            if (connected) {
+                if (disconnectEvents.length > 0) {
+                    const evt = disconnectEvents[0];
+                    const selfInfo = evt.detail?.self_extra_info ? JSON.stringify(evt.detail.self_extra_info) : 'none';
+                    const newInfo = evt.detail?.new_extra_info ? JSON.stringify(evt.detail.new_extra_info) : 'none';
+                    log({
+                        step: 'KickTest',
+                        index: 11,
+                        ok: true,
+                        detail: `connected, received disconnect (code=${evt.code}, self=${selfInfo}, new=${newInfo})`,
+                        ms: elapsed,
+                    });
+                    if (!formatJson) {
+                        console.log(`    ${YELLOW}⚠${RST} ${DIM}This test may have disconnected the running daemon (it will auto-reconnect)${RST}`);
+                    }
+                }
+                else {
+                    log({
+                        step: 'KickTest',
+                        index: 11,
+                        ok: true,
+                        detail: `connected, no disconnect event (daemon may not be running or already disconnected)`,
+                        ms: elapsed,
+                    });
+                }
+            }
+            else {
+                log({ step: 'KickTest', index: 11, ok: false, detail: `failed to connect`, ms: elapsed });
+            }
+        }
+        catch (e) {
+            log({ step: 'KickTest', index: 11, ok: false, detail: `kick test failed: ${e.message?.slice(0, 100) || String(e)}` });
+        }
+    }
+    else {
+        log({ step: 'KickTest', index: 11, ok: true, detail: `skipped (use --kick-test to enable)`, skipped: true });
+    }
     return results;
 }
 // 添加这个常量到 ANSI 块（如果还没有）
@@ -563,10 +643,11 @@ function shuffle(arr) {
 export async function cmdNet(args) {
     const sub = args[0];
     const formatJson = args.includes('--format') && args.includes('json');
+    const kickTest = args.includes('--kick-test');
     if (isHelpFlag(sub)) {
-        console.log(`用法: evolclaw net check [<aid>] [--format json]
+        console.log(`用法: evolclaw net check [<aid>] [--format json] [--kick-test]
 
-检查 AUN 网络链路连通性（10 步逐层诊断）。
+检查 AUN 网络链路连通性（11 步逐层诊断）。
 
 步骤:
   1.  DNS (AID)      AID 域名解析
@@ -578,13 +659,15 @@ export async function cmdNet(args) {
   7.  Auth           AID 认证（login1 + login2 → token）
   8.  Session        会话建立
   9.  Ping           meta.ping RPC
-  10. Message        self-to-self 消息收发
+  10. Echo           self-to-self 消息收发
+  11. KickTest       踢人测试 / extra_info 验证（可选）
 
 参数:
   <aid>    要检查的 AID（可选，默认取前 3 个本地 AID）
 
 选项:
-  --format json    JSON 格式输出`);
+  --format json    JSON 格式输出
+  --kick-test      启用踢人测试（会断开 daemon 长连接，daemon 会自动重连）`);
         return;
     }
     if (sub && sub !== 'check' && !sub.startsWith('-') && !sub.includes('.')) {
@@ -616,7 +699,7 @@ export async function cmdNet(args) {
         if (!formatJson) {
             console.log(`\n${BOLD}── ${targetAid} ──${RST}\n`);
         }
-        const results = await runCheck(targetAid, formatJson);
+        const results = await runCheck(targetAid, formatJson, kickTest);
         allResults.push({ aid: targetAid, checks: results });
     }
     if (formatJson) {

package/dist/cli/watch-msg.js

@@ -131,11 +131,11 @@ function shortAid(aid) {
     return aid.split('.')[0];
 }
 // ==================== Data Layer ====================
-function getSessionsAunDir() {
+export function getSessionsAunDir() {
     const p = resolvePaths();
     return path.join(p.sessionsDir, 'aun');
 }
-function listLocalAids(aunDir) {
+export function listLocalAids(aunDir) {
     try {
         return fs.readdirSync(aunDir, { withFileTypes: true })
             .filter(e => e.isDirectory())
@@ -145,7 +145,7 @@ function listLocalAids(aunDir) {
         return [];
     }
 }
-function listPeers(aunDir, localAid) {
+export function listPeers(aunDir, localAid) {
     const aidDir = path.join(aunDir, encodeSegment(localAid));
     try {
         return fs.readdirSync(aidDir, { withFileTypes: true })
@@ -156,7 +156,7 @@ function listPeers(aunDir, localAid) {
         return [];
     }
 }
-function readMessages(aunDir, localAid, peerId) {
+export function readMessages(aunDir, localAid, peerId) {
     const msgPath = path.join(aunDir, encodeSegment(localAid), encodeSegment(peerId), 'messages.jsonl');
     return readAllJsonlLines(msgPath);
 }
@@ -173,7 +173,7 @@ function readPeerName(aunDir, localAid, peerId) {
 function encodeSegment(s) {
     return s.replace(/[/%\\:*?"<>|]/g, ch => '%' + ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0'));
 }
-function loadAidInfo(aunDir, aid) {
+export function loadAidInfo(aunDir, aid) {
     const peers = listPeers(aunDir, aid);
     let totalIn = 0, totalOut = 0;
     for (const peer of peers) {
@@ -187,7 +187,7 @@ function loadAidInfo(aunDir, aid) {
     }
     return { aid, totalIn, totalOut, peerCount: peers.length };
 }
-function loadPeerInfos(aunDir, localAid) {
+export function loadPeerInfos(aunDir, localAid) {
     const peers = listPeers(aunDir, localAid);
     const infos = [];
     for (const peerId of peers) {
@@ -207,7 +207,7 @@ function loadPeerInfos(aunDir, localAid) {
     infos.sort((a, b) => b.lastAt - a.lastAt);
     return infos;
 }
-function loadAllMessages(aunDir, localAid) {
+export function loadAllMessages(aunDir, localAid) {
     const peers = listPeers(aunDir, localAid);
     const all = [];
     for (const peer of peers) {

package/dist/cli/watch-web/debug-log.js

@@ -0,0 +1,18 @@
+/**
+ * watch-web 调试日志 — 写入 $EVOLCLAW_HOME/logs/watch-web.log。
+ *
+ * cmdWatchWeb 启动时清空该文件并调用 setDebugLog 注入 writer，
+ * 各 source / server 通过 dlog() 写调试信息，建立「运行→看日志→定位」的闭环。
+ */
+let _writer = null;
+export function setDebugLog(writer) {
+    _writer = writer;
+}
+export function dlog(line) {
+    if (_writer) {
+        try {
+            _writer(line);
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/cli/watch-web/server.js

@@ -0,0 +1,306 @@
+/**
+ * Watch Web 服务 — 本地浏览器监控面板的后端。
+ *
+ * - HTTP: 静态资源 + 配对 API
+ * - WebSocket: 订阅式实时推送（aid / msg / session）
+ * - 鉴权: 6 位配对码（5 分钟有效）→ token（24h，有访问自动续期），持久化到磁盘
+ * - 安全: 绑定 0.0.0.0（支持远程访问），token 校验，只读
+ *
+ * 借鉴 Kite 控制台：配对码换 token、首消息鉴权、订阅式推送、访问日志。
+ */
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+import { WebSocketServer } from 'ws';
+import { resolvePaths } from '../../paths.js';
+import { setDebugLog } from './debug-log.js';
+import { aidSource } from './sources/aid.js';
+import { msgSource } from './sources/msg.js';
+import { sessionSource } from './sources/session.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const STATIC_DIR = path.join(__dirname, 'static');
+const TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 小时
+const PAIRING_TTL_MS = 5 * 60 * 1000; // 配对码 5 分钟
+const DEFAULT_PORT = 20030;
+const SOURCES = {
+    aid: aidSource,
+    msg: msgSource,
+    session: sessionSource,
+};
+// ── Token 持久化 ──
+function tokenStorePath() {
+    return path.join(resolvePaths().instanceDir, 'watch-web-tokens.json');
+}
+function loadTokens() {
+    try {
+        const raw = fs.readFileSync(tokenStorePath(), 'utf-8');
+        const store = JSON.parse(raw);
+        if (Array.isArray(store.tokens))
+            return store;
+    }
+    catch { /* missing or corrupt */ }
+    return { tokens: [] };
+}
+function saveTokens(store) {
+    try {
+        fs.mkdirSync(resolvePaths().instanceDir, { recursive: true });
+        const tmp = tokenStorePath() + '.tmp';
+        fs.writeFileSync(tmp, JSON.stringify(store, null, 2));
+        fs.renameSync(tmp, tokenStorePath());
+    }
+    catch { /* best effort */ }
+}
+function pruneExpired(store, now) {
+    const before = store.tokens.length;
+    store.tokens = store.tokens.filter(t => now - t.lastActive < TOKEN_TTL_MS);
+    return store.tokens.length !== before;
+}
+/** 校验 token，命中则续期（更新 lastActive）并持久化 */
+function validateAndRenew(token, now) {
+    if (!token)
+        return false;
+    const store = loadTokens();
+    const changed = pruneExpired(store, now);
+    const rec = store.tokens.find(t => t.token === token);
+    if (rec) {
+        rec.lastActive = now;
+        saveTokens(store);
+        return true;
+    }
+    if (changed)
+        saveTokens(store);
+    return false;
+}
+// ── 静态资源 ──
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+};
+function serveStatic(req, res) {
+    let urlPath = (req.url || '/').split('?')[0];
+    if (urlPath === '/')
+        urlPath = '/index.html';
+    // 防目录穿越
+    const safe = path.normalize(urlPath).replace(/^(\.\.[/\\])+/, '');
+    const file = path.join(STATIC_DIR, safe);
+    if (!file.startsWith(STATIC_DIR)) {
+        res.writeHead(403).end('Forbidden');
+        return;
+    }
+    fs.readFile(file, (err, data) => {
+        if (err) {
+            res.writeHead(404).end('Not Found');
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': MIME[path.extname(file)] || 'application/octet-stream' });
+        res.end(data);
+    });
+}
+function genPairingCode() {
+    return String(crypto.randomInt(0, 1000000)).padStart(6, '0');
+}
+function clientIp(req) {
+    const fwd = req.headers['x-forwarded-for'];
+    if (typeof fwd === 'string' && fwd)
+        return fwd.split(',')[0].trim();
+    return req.socket.remoteAddress || '?';
+}
+export async function startWatchWebServer(opts = {}) {
+    const log = opts.log || (() => { });
+    setDebugLog(log); // 把日志 writer 注入各 source，建立调试闭环
+    const pairingCode = genPairingCode();
+    const pairingExpiry = Date.now() + PAIRING_TTL_MS;
+    const server = http.createServer((req, res) => {
+        const url = req.url || '/';
+        if (req.method === 'POST' && url === '/api/pair') {
+            handlePair(req, res, pairingCode, pairingExpiry, log);
+            return;
+        }
+        serveStatic(req, res);
+    });
+    const wss = new WebSocketServer({ noServer: true });
+    server.on('upgrade', (req, socket, head) => {
+        const { query } = parseUrl(req.url || '');
+        const token = query.token || '';
+        if (!validateAndRenew(token, Date.now())) {
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            log(`✗ WS 拒绝（无效 token） from ${req.socket.remoteAddress}`);
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            handleConnection(ws, req, log);
+        });
+    });
+    const port = await bindPort(server, opts.port ?? DEFAULT_PORT);
+    const url = `http://0.0.0.0:${port}`;
+    return {
+        url,
+        port,
+        pairingCode,
+        close() {
+            return new Promise((resolve) => {
+                for (const client of wss.clients) {
+                    try {
+                        client.close();
+                    }
+                    catch { /* ignore */ }
+                }
+                wss.close();
+                server.close(() => resolve());
+            });
+        },
+    };
+}
+// ── 配对 ──
+function handlePair(req, res, pairingCode, pairingExpiry, log) {
+    let body = '';
+    req.on('data', (chunk) => {
+        body += chunk;
+        if (body.length > 4096)
+            req.destroy();
+    });
+    req.on('end', () => {
+        const ip = clientIp(req);
+        let code = '';
+        try {
+            code = String(JSON.parse(body).code || '');
+        }
+        catch { /* bad json */ }
+        if (Date.now() > pairingExpiry) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, reason: '配对码已过期，请重启 watch web' }));
+            log(`✗ 配对失败（码已过期） from ${ip}`);
+            return;
+        }
+        if (code !== pairingCode) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, reason: '配对码错误' }));
+            log(`✗ 配对失败（码错误: ${code}） from ${ip}`);
+            return;
+        }
+        // 配对成功，发放持久 token
+        const now = Date.now();
+        const token = crypto.randomBytes(32).toString('hex');
+        const store = loadTokens();
+        pruneExpired(store, now);
+        store.tokens.push({ token, createdAt: now, lastActive: now, label: ip });
+        saveTokens(store);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, token }));
+        log(`✓ 配对成功 from ${ip}（token 已缓存，24h 有效）`);
+    });
+}
+// ── URL 解析 ──
+function parseUrl(rawUrl) {
+    const qIdx = rawUrl.indexOf('?');
+    if (qIdx === -1)
+        return { path: rawUrl, query: {} };
+    const query = {};
+    for (const pair of rawUrl.slice(qIdx + 1).split('&')) {
+        const [k, v] = pair.split('=');
+        if (k)
+            query[decodeURIComponent(k)] = decodeURIComponent(v || '');
+    }
+    return { path: rawUrl.slice(0, qIdx), query };
+}
+// ── WebSocket 连接 ──
+function handleConnection(ws, req, log) {
+    const ip = clientIp(req);
+    let unsubscribe = null;
+    let currentView = null;
+    log(`◆ WS 连接 from ${ip}`);
+    const send = (obj) => {
+        if (ws.readyState === ws.OPEN) {
+            try {
+                ws.send(JSON.stringify(obj));
+            }
+            catch { /* ignore */ }
+        }
+    };
+    const switchSubscription = async (view, params) => {
+        if (unsubscribe) {
+            unsubscribe();
+            unsubscribe = null;
+        }
+        currentView = view;
+        const source = SOURCES[view];
+        if (!source) {
+            send({ type: 'error', message: `unknown view: ${view}` });
+            return;
+        }
+        try {
+            const snap = await source.snapshot(params);
+            send({ type: 'snapshot', view, data: snap });
+        }
+        catch (e) {
+            send({ type: 'error', message: `snapshot failed: ${e?.message || e}` });
+        }
+        unsubscribe = source.subscribe(params, (data) => {
+            if (currentView === view)
+                send({ type: 'delta', view, data });
+        });
+    };
+    ws.on('message', async (raw) => {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch {
+            return;
+        }
+        if (msg.type === 'ping') {
+            send({ type: 'pong' });
+            return;
+        }
+        if (msg.type === 'subscribe' && msg.view) {
+            const params = {};
+            if (msg.aid)
+                params.aid = msg.aid;
+            if (msg.peer)
+                params.peer = msg.peer;
+            if (msg.sessionId)
+                params.sessionId = msg.sessionId;
+            if (msg.project)
+                params.project = msg.project;
+            log(`▸ 订阅 ${msg.view}` +
+                `${msg.project ? ` project=${String(msg.project).slice(-24)}` : ''}` +
+                `${msg.aid ? ` aid=${String(msg.aid).split('.')[0]}` : ''}` +
+                `${msg.peer ? ` peer=${String(msg.peer).split('.')[0]}` : ''}` +
+                `${msg.sessionId ? ` session=${String(msg.sessionId).slice(0, 8)}` : ''} from ${ip}`);
+            await switchSubscription(msg.view, params);
+        }
+    });
+    ws.on('close', () => {
+        if (unsubscribe) {
+            unsubscribe();
+            unsubscribe = null;
+        }
+        log(`◇ WS 断开 from ${ip}`);
+    });
+    ws.on('error', () => { });
+}
+// ── 端口绑定（首选端口被占则 +1，最多尝试 10 次）──
+function bindPort(server, preferred) {
+    return new Promise((resolve, reject) => {
+        let attempt = 0;
+        const tryBind = (port) => {
+            server.once('error', (err) => {
+                if (err.code === 'EADDRINUSE' && attempt < 10) {
+                    attempt++;
+                    tryBind(port + 1);
+                }
+                else {
+                    reject(err);
+                }
+            });
+            server.listen(port, '0.0.0.0', () => resolve(port));
+        };
+        tryBind(preferred);
+    });
+}