@ntdgy/dsh-remote-bridge-plugin 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,535 @@
+/**
+ * dsh-remote-bridge —— DSH host 侧插件。
+ *
+ * 职责：
+ *   1. 主动出站连接到公网网关（DSH → VPS，VPS 永不主动连入）
+ *   2. 自证身份（同进程内直接使用 sessionController，不走 HTTP、不碰 token）
+ *   3. 只响应白名单 RPC，绝不透传任意请求
+ *
+ * 硬性纪律见 docs/decisions/ADR-002-no-http-fallback.md。
+ */
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { RelayClient } from "./relay/client.js";
+import { Dispatcher } from "./relay/dispatcher.js";
+import { forwardToUpstream } from "./relay/http-forward.js";
+import { WsForwarder } from "./relay/ws-forward.js";
+import { collectRegisteredPrefixes } from "./relay/route-observer.js";
+/**
+ * 读取路由表，空则短暂重试。
+ *
+ * 为什么要重试：插件激活顺序不保证 —— 我们在其它插件注册路由之前就可能发 hello，
+ * 那一刻 exact/prefixes/upgrades 都是空的。实测 hello 在 :16，dsh-market 的路由在 :17 才有。
+ *
+ * 上限 3 秒、每 100ms 一次：够覆盖正常激活抖动，又不会让 hello 无限延迟
+ * （hello 迟发会拖慢整条链路的可用时间）。
+ */
+async function collectWithRetry(webServer) {
+    let report = collectRegisteredPrefixes(webServer);
+    const deadline = Date.now() + 3000;
+    while (report.observed === 0 && Date.now() < deadline) {
+        // 必须是**异步**等待：别的插件的注册回调要靠事件循环才跑得起来，
+        // 同步忙等只会把 loop 堵死，路由表永远补不上（我第一版就是这么写的）。
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        report = collectRegisteredPrefixes(webServer);
+    }
+    return report;
+}
+import { encodeWsDataFrame } from '@ntdgy/dsh-remote-proto';
+/**
+ * 解析 DSH webServer 的本机 origin（ADR-005 转发目标）。
+ *
+ * 拿不到时返回 undefined —— 调用方必须回明确的 upstream_unreachable，
+ * 而不是静默失败（否则前端只会看到超时，不知道该去查什么）。
+ */
+function resolveUpstreamOrigin(ctx) {
+    // webServer 不在 inject 里、因此这里必须能接受 undefined ——
+    // 完整理由见 inject 定义处的大段注释（唯一事实源，避免两处注释再次漂移）。
+    const webServer = ctx.get('webServer');
+    if (!webServer?.getOrigin)
+        return undefined;
+    try {
+        return webServer.getOrigin();
+    }
+    catch {
+        // getOrigin 在 listen 之前会 throw，此时转发能力确实不可用。
+        return undefined;
+    }
+}
+/**
+ * 取本实例的**已认证**应用 URL，上报给网关代持 DSH 会话。
+ *
+ * DSH 的 `connection` 服务暴露 `authenticatedUrl(baseUrl)`：把本进程当前的
+ * launch token 拼进干净的 URL。token **每次 DSH 重启都会变**，且绑定 DSH
+ * 看到的 authority —— 只有 DSH 自己知道，网关拼不出来。所以由插件上报。
+ *
+ * 拿不到就返回 undefined（不是错误）：网关会退化为「用户自行带 ?token=」，
+ * 功能不受影响，只是需要手动登录。
+ */
+function resolveLaunchUrl(ctx) {
+    // 逐层返回原因而不是笼统的 undefined —— 上一版只说「不可用」，
+    // 排查时不得不再翻一遍代码才知道是哪一步断的。
+    // strict=false：cordis 的 ctx.get(name, strict=true) 会要求目标服务的 fiber
+    // 处于**就绪态**（state === 2），否则当成不存在。实测我们这里拿到 undefined
+    // 就是这个原因 —— connection 已注册但 fiber 尚未就绪（激活时序早于它）。
+    // 非严格模式拿到的可能是「已注册但未就绪」的实例，这里用得上：
+    // authenticatedUrl 只依赖已构造好的 BrowserAuth，不要求服务已发布。
+    const connection = ctx.get('connection', false);
+    if (connection === undefined)
+        return { reason: 'ctx.get(connection, false) 仍返回 undefined' };
+    if (typeof connection.authenticatedUrl !== 'function') {
+        return { reason: 'connection.authenticatedUrl 不是函数（DSH 版本可能不支持）' };
+    }
+    const origin = resolveUpstreamOrigin(ctx);
+    if (origin === undefined) {
+        return { reason: 'webServer.getOrigin() 不可用（webServer 未注入或尚未 listen）' };
+    }
+    try {
+        const url = connection.authenticatedUrl(origin);
+        if (typeof url !== 'string' || !/^https?:\/\//.test(url)) {
+            return { reason: 'authenticatedUrl 返回值不是绝对 http(s) URL: ' + String(url) };
+        }
+        return { url };
+    }
+    catch (error) {
+        return { reason: 'authenticatedUrl 抛错: ' + String(error) };
+    }
+}
+import { FollowRegistry } from "./relay/follow.js";
+/**
+ * 运行期校验 sessionController 的**行为面**，而不是相信一次类型断言。
+ *
+ * 背景（T14）：原来这里写的是 `ctx.get('sessionController') as unknown as DshFollowSource`。
+ * 断言把「服务可能不在」这一事实从类型系统里抹掉了，于是 undefined 被赋给
+ * FollowRegistry.source，直到第一次 follow 才炸成
+ * "Cannot read properties of undefined (reading 'follow')"——离故障点很远，极难定位。
+ *
+ * 现在改为按**方法**校验：只要这不是一个带 follow() 的对象就立刻拒绝。
+ *
+ * T18 教训（**守卫比缺陷更严格**）：这里最初写的是 `!'follow' in value`。
+ * 服务的常见形态是只实现 get 的惰性代理，`in` 走默认 [[Has]] 落在空 target 上恒为 false，
+ * 于是**健康服务**被判成装配错误，history 100% 不可用——守卫自己成了新的单点障碍。
+ *
+ * 规则：守卫必须比它守护的缺陷更**宽松**，且检查方式必须与被检查对象的**形态**匹配。
+ * 对代理/惰性对象要用 `typeof x.prop` 取真实属性值，不要用 `in` / `hasOwnProperty`。
+ */
+function isFollowSource(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    // typeof 会真实触发一次 get：对惰性代理同样可靠，且比 `in` 宽松。
+    return typeof value.follow === 'function';
+}
+export const name = 'remote-bridge';
+/**
+ * 只注入我们真正需要的服务。connection 用于兜底自证，sessionController 是主路径。
+ *
+ * cordis 语义（@deepseek-ai/cordis 4.0.5，fiber.ts:611-623 `_refresh`）：
+ * 任一 inject 服务缺失，fiber 停在 PENDING —— 不报错、不加载、不打日志。
+ * 也就是说"服务名写错"的表现是**插件静默不工作**，而不是启动失败。
+ * 因此服务名必须与实装一致（0.2.1-rc.2：`super(ctx, "sessionController")` lib/index.js:2952，
+ * `connection` lib/index.js:710），任何服务名调整都要同时改这里。
+ *
+ * ── 为什么 webServer **不在这里**（I-3）────────────────────────────────
+ *
+ * 它是**可选能力**，不是主能力。JS 侧三条使用点全部是防御式读取：
+ *   - resolveUpstreamOrigin / collectHttpPrefixes：ctx.get('webServer')，取不到即降级；
+ *   - 状态路由：走 ctx.inject(['webServer'], …)，本来就是可选注入。
+ * 既然没有任何一条路径依赖它"必须就绪"，把它写进 inject 只会带来一个后果：
+ * 在**没有 web 服务的 profile** 里整插件停在 PENDING（cordis 语义：任一 inject 缺失
+ * 即不加载、不报错、不打日志）。那等于用一个可选能力换掉主能力——
+ * 窄 RPC 会一起消失，而且**没有任何日志**说明为什么。
+ *
+ * 这正是本文件历史上踩过的坑：同一段代码上方曾有过一条"webServer 不在 inject 里，
+ * 这是刻意的"的注释，而 inject 里却真的写着 webServer —— 注释与代码互相矛盾，
+ * 直到有部署在没有 webServer 的环境里静默不工作才可能暴露。
+ * 现在两者一致：**inject 里每一项都必须被主路径无条件需要**，可选能力一律走 ctx.inject。
+ *
+ * 代价（明确接受）：在非 web profile 里 ctx.get('webServer') 返回 undefined，
+ * 转发与状态路由不可用。这是可接受的：没有 web 服务时本来也没有 GUI 可转发。
+ * 调用方会回明确的 upstream_unreachable / 打印 "webServer unavailable"，前端能看到原因。
+ */
+export const inject = ['connection', 'sessionController'];
+export default class RemoteBridge extends Service {
+    static Config = z.object({
+        relayUrl: z.string().required().description('公网网关的 WebSocket 地址，例如 wss://dsh.example.com/agent'),
+        instanceId: z.string().required().description('本实例的唯一标识'),
+        instanceKey: z.string().required().role('secret').description('与网关共享的密钥，用于 HMAC 挑战应答'),
+        reconnectBaseMs: z.natural().default(3000).description('重连初始退避'),
+        reconnectMaxMs: z.natural().default(60_000).description('重连退避上限'),
+        heartbeatIntervalMs: z.natural().default(15_000).description('心跳间隔（毫秒）'),
+    });
+    // 由 ctx.effect 在插件激活时创建、卸载时销毁；PENDING 期间不持有任何 socket。
+    client;
+    /**
+     * 面板用的运行时快照（只读）。
+     *
+     * 全部取自既有状态，不新增采集：连接态、断线原因、各类计数都在这里汇合，
+     * 供 /bridge-plugin/status 路由读取。
+     */
+    panelState = { registered: false, reconnects: 0 };
+    /**
+     * 以下三个引用只用于**观测**（诊断/测试），不参与业务逻辑。
+     *
+     * T14 的教训：dispatcher / follows 曾完全是 ctx.effect 闭包里的局部量，
+     * 插件实例上完全不可达，导致 "Cannot read properties of undefined (reading 'follow')"
+     * 这类问题无法从实例外部观察，只能靠复刻缩小范围。暴露成只读字段是为了让同类
+     * 问题下次能一眼看到。
+     */
+    dispatcherRef;
+    followsRegistry;
+    config;
+    constructor(ctx, config) {
+        // 注意：cordis 4.0.5 的 Service 基类构造函数只有 (ctx, name)，没有
+        // config 形参（lib/types/service.d.ts:38），config 归插件自己的签名所有。
+        // 归一化由 cordis 在**喂构造参数之前**完成（resolveConfig 在 module 作用域，
+        // 对任何 class 插件只调用一次，与是否继承 Service 无关）。
+        // 服务名带项目命名空间：'remoteBridge' 已被 @linxin666/dsh-remote-bridge 占用，
+        // 两者独立开发、无共享命名空间，同名会让后注册者直接失败。
+        super(ctx, 'dshRemoteBridge');
+        this.config = config;
+        // 最后一道闸：绝不能带着空凭据静默出站。
+        //
+        // schemastery 的 object schema 把「缺字段」当作「未提供」而不是错误：
+        // validate({}) 会返回 { reconnectBaseMs: 3000, ... }，**静默丢掉**
+        // relayUrl / instanceId / instanceKey。一旦配置层再以空对象喂一次，
+        // 插件就会带着空 instanceId 去握手，网关 4401 拒绝、插件无限重连，
+        // 而全链路没有任何一条日志——P1 实机验收正是卡在这里。
+        // 显式抛错，让它在 dsh 启动诊断里立刻可见，而不是静默空转。
+        for (const key of ['relayUrl', 'instanceId', 'instanceKey']) {
+            if (typeof config?.[key] !== 'string' || config[key] === '') {
+                // ⚠️ 绝不能把整个 config 打进错误信息：instanceKey 是凭据，
+                // 审查实测过它会被完整打印到日志/异常里。只报缺了哪个字段。
+                throw new Error(`remote-bridge: config.${key} is required but missing or empty`);
+            }
+        }
+        // 生命周期必须挂在 ctx.effect 上，否则热重载会泄漏 socket 与在途请求。
+        ctx.effect(() => {
+            const lifecycle = new AbortController();
+            // client 与 registry 互相引用：帧出口需要 client，client 的 sub-control
+            // 回调需要 dispatcher。出口在订阅真实产帧时才会被调用（晚于本函数返回），
+            // 因此这里用延迟绑定，避免为构造顺序引入 null 检查。
+            let client;
+            // 帧流注册表（D1/D4）。
+            //
+            // 两条出口必须分别接线，**不能合并**：FollowRegistry 的 onFrame 只承载
+            // subscribe() 泵出的数据帧（snapshot / event / assistant-stream），终止信号
+            // 由 subscribe() 的 onEnd 回调投递，注册表**不会**把 RpcFrameEnd 交给 onFrame。
+            // 曾经只接 onFrame，结果是除非正常泵完，否则浏览器永远收不到 frame-end。
+            //
+            // 服务解析：惰性 + 校验（治本 + 保底）。
+            //
+            // 惰性：不在 effect 立即执行体里抓快照，每次取用都重新 ctx.get，
+            // 这样服务在 PENDING 期间出现、或热重载换实现，都能拿到当下有效的对象。
+            //
+            // 这里**不缓存**解析结果：T18 的教训是任何"装配期抓一次"的东西都会成为
+            // 新的形态假设（缓存住一个后来被替换/尚未就绪的对象）。ctx.get 本身很便宜。
+            const resolveSource = () => {
+                const candidate = ctx.get('sessionController');
+                // 注意：这里**不再**记录历史结果。
+                // 面板需要的是「现在能不能用」，而这里是「本次解析是否成功」——
+                // 两者语义不同。面板改为每次请求现探（见 probeSessionController）。
+                if (!isFollowSource(candidate)) {
+                    throw new Error('remote-bridge: sessionController is unavailable (ctx.get returned ' +
+                        `${candidate === undefined ? 'undefined' : typeof candidate}` +
+                        '); cannot follow sessions. This usually means the inject dependency was not ready.');
+                }
+                return candidate;
+            };
+            // 装配体：所有需要"活服务"的动作都推迟到第一次真正使用。
+            //
+            // 为什么要推迟而不是在这里直接 new FollowRegistry(resolveSource(), …)：
+            // effect body 的执行时机**可能早于 inject 解析完成**（T14 那个缺陷正是
+            // 这种时序的表现）。构造期调用 resolveSource() 会把"此刻服务还没好"
+            // 变成一次启动崩溃，等于把守卫挪到最脆弱的位置。
+            // 装配体本身是纯数据，不碰任何服务；第一个碰服务的人是 followStream 里的 resolveSource()。
+            const follows = new FollowRegistry({
+                follow: (request, signal) => resolveSource().follow(request, signal),
+            }, (frame) => {
+                client.sendFrame(frame);
+            });
+            this.followsRegistry = follows;
+            // ADR-005 T34：WS 升级转发器。sink 直接走 client 的同一通道，
+            // 保证 WS 数据帧与 HTTP/窄 RPC 共用一条出站连接（C7）。
+            const wsForwarder = new WsForwarder(() => resolveUpstreamOrigin(ctx), {
+                ack: (id, ok, error) => client.sendControl({ kind: 'ws-open-ack', id, ok, error }),
+                data: (id, opcode, payload) => client.sendBinary(encodeWsDataFrame(id, opcode, payload)),
+                close: (id, code, reason, from) => client.sendControl({ kind: 'ws-close', id, code, reason, from }),
+            });
+            /** 订阅并保证终止信号一定送到浏览器（ADR-004：frame-end 必须显式发送）。 */
+            const subscribe = (sessionId, subscriptionId) => {
+                follows.subscribe({ sessionId, subscriptionId }, (end) => {
+                    client.sendFrameEnd(end);
+                });
+            };
+            const dispatcher = new Dispatcher(ctx, config.instanceId, lifecycle.signal, follows, subscribe);
+            this.dispatcherRef = dispatcher;
+            client = new RelayClient({
+                url: config.relayUrl,
+                instanceId: config.instanceId,
+                instanceKey: config.instanceKey,
+                reconnectBaseMs: config.reconnectBaseMs ?? 3000,
+                reconnectMaxMs: config.reconnectMaxMs ?? 60_000,
+                heartbeatIntervalMs: config.heartbeatIntervalMs ?? 15_000,
+                onRequest: (req) => dispatcher.handle(req),
+                // ADR-005：HTTP 转发。用 webServer 的 origin 反向请求本机 loopback。
+                // 拿不到 origin（webServer 未注入/未监听）时明确回报，不静默失败。
+                // ADR-005 运行时自声明：hello 时读 DSH webServer 已注册路由，归并成前缀上报。
+                // 读不到就上报空数组（网关侧按「未声明」处理并打印提示），绝不猜测。
+                // 只读状态路由：面板取数用。注册在真实 webServer 上，
+                // 因此 T37 的运行时自声明会自动把它算进前缀（顺带验证那个机制对自家插件也生效）。
+                // 代持 DSH 会话所需的已认证 URL。每次 hello 现取 —— token 随 DSH 重启变化。
+                collectLaunchUrl: () => {
+                    const resolved = resolveLaunchUrl(ctx);
+                    if (resolved.url === undefined) {
+                        process.stderr.write('remote-bridge: 未取到已认证应用 URL：' + String(resolved.reason) +
+                            '；网关将退化为要求用户自行带 ?token= 登录。\n');
+                    }
+                    return resolved.url;
+                },
+                collectHttpPrefixes: async () => {
+                    const webServer = ctx.get('webServer');
+                    // 时序：本插件可能在其它插件之前激活，此刻路由表还是空的。
+                    // 因此先读一次；若为空，短暂重试等待别人注册完（总时长有界）。
+                    // 这是实测暴露的：hello 发生在 08:10:16，而 dsh-market 的路由在 :17 才就绪。
+                    const report = await collectWithRetry(webServer);
+                    // 同时写 stderr：ctx.logger 落到 DSH 自己的日志系统，
+                    // 排查时用 tail -f 启动输出看不到，容易误以为「什么都没发生」。
+                    if (report.observed === 0) {
+                        process.stderr.write('remote-bridge: 未观测到已注册路由（' + report.diagnostic + '）\n');
+                    }
+                    if (report.observed === 0) {
+                        // 带上 webServer 是否存在、三张表的实际类型与条数 —— 只打「未观测到」
+                        // 无法区分「服务没注入」与「别人还没注册」，会让排查回到翻代码。
+                        ctx.logger?.warn?.('remote-bridge: 未观测到任何已注册的 HTTP 路由（' + report.diagnostic +
+                            '）；插件路由将不可经网关访问。');
+                    }
+                    for (const r of report.rejected) {
+                        ctx.logger?.warn?.('remote-bridge: 拒绝上报前缀 ' + r.value + '（' + r.reason + '）');
+                    }
+                    return report.accepted;
+                },
+                onHttpRequest: async (frame, body) => {
+                    const origin = resolveUpstreamOrigin(ctx);
+                    if (!origin) {
+                        return {
+                            frame: {
+                                kind: 'http-response-error',
+                                id: frame.id,
+                                code: 'upstream_unreachable',
+                                message: 'DSH webServer is not reachable from the plugin (no origin available)',
+                            },
+                        };
+                    }
+                    return forwardToUpstream(origin, frame, body);
+                },
+                // ADR-005 T34：WS 升级转发。与 HTTP 共用同一条出站连接。
+                onWsOpen: (frame) => wsForwarder.open(frame),
+                onWsFlow: (id, action) => wsForwarder.setFlow(id, action),
+                onWsClose: (id, code, reason) => wsForwarder.closeUpstream(id, code, reason),
+                onWsData: (id, opcode, payload) => wsForwarder.toUpstream(id, opcode, payload),
+                onOpen: (connId) => {
+                    this.panelState.registered = true;
+                    this.panelState.connectedAt = Date.now();
+                    if (this.panelState.lastClosedAt !== undefined)
+                        this.panelState.reconnects += 1;
+                    ctx.logger.info('remote-bridge: registered as %s (connection %s)', config.instanceId, connId);
+                },
+                onClose: (reason, code) => {
+                    // 面板要能反映「为什么断了」，所以这里记原因与时刻（不记凭据）。
+                    this.panelState.registered = false;
+                    this.panelState.lastCloseReason = reason + (code >= 0 ? ' (code ' + code + ')' : '');
+                    this.panelState.lastClosedAt = Date.now();
+                    // 本地自止（ADR-004 纪律 2）。
+                    //
+                    // sub-control 是"网关主动要求终止"，socket close 是"对方已不在"：
+                    // 两者意图相同但触发源不同。前者**不可靠**——连接已断就收不到，
+                    // 所以不能把清理寄托在网关的通知上。插件断连后网关卡 dropInstance
+                    // 已作废全部订阅，重连后继续泵的每一帧都会被 audit 成 frame_dropped，
+                    // 等于拿 DSH 侧的 follow 资源烧孤儿帧。这里 abort 是主动止损，不是冗余。
+                    //
+                    // 幂等：订阅 end() 只收口一次，与 onSubscriptionControl 可能的重叠调用是 no-op。
+                    dispatcher.abortAllSubscriptions();
+                    // I-4：上游 WS 也要在这里收口。
+                    //
+                    // 上游 socket 的 close 事件确实也会走到 closeUpstream，所以这不是"永久泄漏"；
+                    // 但它依赖对端**先**关，而我们断开网关后上游两端都已无人驱动——
+                    // 上游连接会多活一段时间（取决于上游自己的 keepalive），期间白占 DSH 侧资源。
+                    // 主动收口把"迟早会清"变成"现在就清"。
+                    wsForwarder.closeAll();
+                    if (code === 4408) {
+                        ctx.logger.warn('remote-bridge: heartbeat timeout, gateway closed the connection: %s', reason);
+                        return;
+                    }
+                    ctx.logger.warn('remote-bridge: disconnected: %s', reason);
+                },
+                onProtocolWarning: (detail) => ctx.logger.warn('remote-bridge: %s', detail),
+                // I-5：发送缓冲爆掉、本端主动断连。与网络故障分开报，否则会去查错方向。
+                onBackpressure: (buffered) => ctx.logger.error('remote-bridge: outbound buffer overflow (%d bytes) — the gateway is not draining; reconnecting', buffered),
+                // 认证被拒不等于网络故障：密钥配错时网络是好的，必须让人一眼看出来。
+                // 文案只用网关给的 code/message，永不回显 instanceKey。
+                onAuthFailure: (code, message) => ctx.logger.error('remote-bridge: handshake rejected by gateway (%s): %s — check instanceKey for instance %s', code, message, config.instanceId),
+                // 网关的退订指令（控制帧，非业务 RPC）：定位到订阅即 abort。
+                onSubscriptionControl: (subscriptionId, reason) => {
+                    if (!dispatcher.cancelSubscription(subscriptionId, reason)) {
+                        ctx.logger.warn('remote-bridge: sub-control for unknown subscription %s (%s)', subscriptionId, reason);
+                    }
+                },
+            });
+            this.client = client;
+            client.start();
+            // ── 只读状态路由（面板取数）────────────────────────────────────────
+            //
+            // 用 ctx.inject 而不是在 effect 里 ctx.get：实测在 effect 体内
+            // ctx.get('webServer') 返回 undefined（即使 webServer 已在 inject 列表里），
+            // inject 回调拿到的 context 才保证该服务已就绪 —— dshmarket 也是这么写的。
+            // 注册后 T37 的运行时自声明会读到它，从而自动放行 /bridge-plugin/。
+            ctx.inject(['webServer'], (hostCtx) => {
+                const webServer = hostCtx.get('webServer');
+                if (!webServer || typeof webServer.register !== 'function') {
+                    // 不静默：面板会表现为「打不开状态」，没有这条很难查。
+                    process.stderr.write('remote-bridge: webServer unavailable; /bridge-plugin/status not registered\n');
+                    return;
+                }
+                hostCtx.effect(() => {
+                    const dispose = webServer.register?.({
+                        kind: 'exact',
+                        path: '/bridge-plugin/status',
+                        handler: (req, res) => {
+                            const response = res;
+                            const method = req?.method ?? 'GET';
+                            // I-6：只读状态只回应 GET / HEAD。
+                            //
+                            // 这条路由**不在网关的放行白名单里**（prefix-registry.ts），公网到不了，
+                            // 所以真实风险只是"本机其他进程可读"。因此这里不引入鉴权，
+                            // 只把"不限方法"收成 405 —— 一个只读端点没有理由接受 PUT/DELETE，
+                            // 而允许它们会让人误以为它是可写接口。
+                            if (method !== 'GET' && method !== 'HEAD') {
+                                response.writeHead(405, {
+                                    'content-type': 'application/json; charset=utf-8',
+                                    allow: 'GET, HEAD',
+                                    'cache-control': 'no-store',
+                                });
+                                // HEAD 不该有 body；405 对 HEAD 也不会发生（上面已放行），这里只处理其余方法。
+                                response.end(JSON.stringify({ error: 'method_not_allowed', allow: ['GET', 'HEAD'] }));
+                                return;
+                            }
+                            const body = JSON.stringify(this.buildStatusPayload(ctx, config));
+                            response.writeHead(200, {
+                                'content-type': 'application/json; charset=utf-8',
+                                'cache-control': 'no-store',
+                            });
+                            // HEAD：头照发、body 不发（语义要求）。
+                            response.end(method === 'HEAD' ? '' : body);
+                        },
+                    });
+                    return () => dispose?.();
+                }, 'remote-bridge: status route');
+            });
+            return () => {
+                this.client = undefined;
+                this.dispatcherRef = undefined;
+                this.followsRegistry = undefined;
+                // 连接断开即 abort 全部订阅（ADR-004 纪律 2）：结构性保证，不靠调用方记得。
+                dispatcher.abortAllSubscriptions();
+                // I-4：插件卸载同样要收口上游 WS。与 onClose 里的那次是两处独立触发点，
+                // 都由 closeAll() 自身的幂等性兜住（已删的 id 再关一次是 no-op）。
+                wsForwarder.closeAll();
+                client.stop();
+                // 卸载即取消一切在途 DSH 调用，避免请求落到已销毁的插件上。
+                lifecycle.abort();
+            };
+        }, 'remote-bridge: relay lifecycle');
+    }
+    /** 供调试/测试读取当前连接状态（已收到 hello 回执才算就绪）。 */
+    get connected() {
+        return this.client?.ready ?? false;
+    }
+    /**
+     * 组装面板所需的只读状态。
+     *
+     * 七项全部取自既有运行态，**不新增采集、不猜值**：
+     *   连接状态 / instanceId + relayUrl / 心跳间隔 / authFailures /
+     *   droppedFrames + 已上报前缀 / 断线原因 / sessionControllerReady
+     *
+     * 安全：绝不包含 instanceKey 或任何凭据。
+     */
+    buildStatusPayload(ctx, config) {
+        const stats = this.client?.stats;
+        const webServer = ctx.get('webServer');
+        // 已上报前缀现读一次：与 hello 时上报的是同一份计算，不会与线上不一致。
+        const report = collectRegisteredPrefixes(webServer);
+        return {
+            /** 1. 连接状态：只有收到 hello.auth 回执才算 registered。 */
+            connection: {
+                registered: this.panelState.registered,
+                connected: this.client?.ready ?? false,
+                connectedAt: this.panelState.connectedAt ?? null,
+                reconnects: this.panelState.reconnects,
+            },
+            /** 2. 身份与网关地址（不含任何密钥）。 */
+            identity: {
+                instanceId: config.instanceId,
+                relayUrl: config.relayUrl,
+            },
+            /** 3. 心跳间隔（毫秒）：网关 hello 回执的权威值。 */
+            heartbeat: {
+                intervalMs: stats?.heartbeatIntervalMs ?? config.heartbeatIntervalMs ?? null,
+            },
+            /** 4. 认证失败次数（密钥配错的直接信号）。 */
+            authFailures: stats?.authFailures ?? 0,
+            /** 5. 丢弃帧数 + 已上报前缀。 */
+            droppedFrames: stats?.droppedFrames ?? 0,
+            httpPrefixes: {
+                reported: report.accepted,
+                observed: report.observed,
+            },
+            /** 6. 断线原因（最近一次）。 */
+            lastClose: {
+                reason: this.panelState.lastCloseReason ?? null,
+                at: this.panelState.lastClosedAt ?? null,
+            },
+            /** 7. sessionController 是否可用（T14 的 ready 探针）。 */
+            // 现探一次，而不是读「上次调用是否成功」。
+            //
+            // 探针的语义是「现在能不能用」：运维打开面板时服务可能是坏的，也可能从没被调用过。
+            // 用历史值会在「从未调用」时恒为 false，把人误导成「服务坏了」——
+            // 那是错误信息，比没信息更糟。
+            sessionControllerReady: this.probeSessionController(ctx),
+            /** 面板自身的时间戳，用于判断数据新鲜度。 */
+            sampledAt: Date.now(),
+        };
+    }
+    /** 只读诊断：当前 dispatcher（插件未激活时为 undefined）。 */
+    get dispatcher() {
+        return this.dispatcherRef;
+    }
+    /** 只读诊断：当前帧流注册表（插件未激活时为 undefined）。 */
+    get follows() {
+        return this.followsRegistry;
+    }
+    /**
+     * 只读诊断：sessionController 当下是否可解析且具备 follow()。
+     *
+     * 不抛错——诊断接口不该在健康检查时炸掉调用方。
+     */
+    /**
+     * 即刻探测 sessionController 是否可用。
+     *
+     * 每次调用都真实取一次服务并检查形状，不复用历史结果 ——
+     * 面板要回答的是「现在能不能用」。
+     */
+    probeSessionController(ctx) {
+        try {
+            return isFollowSource(ctx.get('sessionController'));
+        }
+        catch {
+            // 取服务本身抛错也算不可用，但绝不让它把面板请求打挂。
+            return false;
+        }
+    }
+    /** 供调试/测试读取当前 sessionController 可用性（实时探测）。 */
+    get sessionControllerReady() {
+        return isFollowSource(this.ctx.get('sessionController'));
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/local/sessions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 会话数据归一化。
+ *
+ * 标题的真实来源（已按 dsh 0.2.1-rc.2 实装核对，见下）：
+ * `@deepseek-ai/dsh-session-title` 通过 module augmentation 向
+ * `SessionProjectionMap` 注册了 `title: string | null`
+ * （dsh-session-title/lib/types/types.d.ts:91-100），
+ * 而 sessionController 的列表行在 live 与 cold 两条路径上都会带上它：
+ *
+ *   - live ：projectionsFor(header, session)
+ *            → sessionProjections.cachedSnapshot(session)            // 纯投影读
+ *   - cold ：projectionsFor(header, undefined)
+ *            → sessionProjectionCache.cachedSnapshot(header)
+ *              ?? cachedPredecessorTitle(header)                     // 纯缓存读
+ *   （dsh-api-session-controller/lib/index.js:2092-2103 / 1941 / 1991）
+ *
+ * 关键结论：这两条路径都**不激活 Agent**，
+ * 所以 `sessionTitle.get(session)` 那种“要活对象”的写法
+ * （design-revision.md D2）既不是唯一解，也不该用。
+ * 列表只读 `projections.values.title`，N6（list 永不激活 Agent）因此自然成立。
+ *
+ * 注意：这里读的是 `projections.values`，不是 `projections` 本身。
+ * `projections` 是 SessionProjectionHints `{ kind, asOfSeq, values }`
+ * （dsh-api-session-controller/lib/types/types.d.ts:52-65），
+ * 基线代码在 `projections` 顶层找 title，因此恒为 null。
+ *
+ * 冷会话在投影缓存尚未写入时仍会拿不到标题——此时回退 null 并如实呈现，
+ * 绝不为取标题去 resume 会话。
+ */
+import type { SessionListItem } from '@ntdgy/dsh-remote-proto';
+/** DSH 原始 SessionSummary 的最小形状（只取我们需要的字段）。 */
+interface RawSessionProjectionHints {
+    readonly kind?: 'cached' | 'sequenced';
+    readonly asOfSeq?: number;
+    readonly values?: Record<string, unknown>;
+}
+interface RawSessionSummary {
+    sessionId: string;
+    updatedAt: number;
+    running: boolean;
+    projections?: RawSessionProjectionHints;
+}
+export declare function normalizeSessionList(items: readonly RawSessionSummary[]): SessionListItem[];
+/**
+ * 从 SessionProjectionHints.values.title 取标题。
+ *
+ * 只认 DSH 自己注册的 `title` key（字符串或 null）；
+ * 其它形状一律当作“暂无标题”，不做猜测性展开——
+ * 猜测会让前端拿到不属于该会话的标题，比 null 更糟。
+ */
+export declare function extractTitle(projections?: RawSessionProjectionHints): string | null;
+export {};

package/lib/local/sessions.js

@@ -0,0 +1,25 @@
+/** `SessionProjectionHints.values` 里我们唯一消费的 key。 */
+const TITLE_PROJECTION_KEY = 'title';
+export function normalizeSessionList(items) {
+    return items.map((item) => ({
+        id: item.sessionId,
+        title: extractTitle(item.projections),
+        updatedAt: item.updatedAt,
+        running: item.running,
+    }));
+}
+/**
+ * 从 SessionProjectionHints.values.title 取标题。
+ *
+ * 只认 DSH 自己注册的 `title` key（字符串或 null）；
+ * 其它形状一律当作“暂无标题”，不做猜测性展开——
+ * 猜测会让前端拿到不属于该会话的标题，比 null 更糟。
+ */
+export function extractTitle(projections) {
+    const value = projections?.values?.[TITLE_PROJECTION_KEY];
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+//# sourceMappingURL=sessions.js.map

package/lib/local/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/local/sessions.ts"],"names":[],"mappings":"AA+BA,oDAAoD;AACpD,MAAM,oBAAoB,GAAG,OAAO,CAAA;AAgBpC,MAAM,UAAU,oBAAoB,CAAC,KAAmC;IACtE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,EAAE,EAAE,IAAI,CAAC,SAAS;QAClB,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACrC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,WAAuC;IAClE,MAAM,KAAK,GAAG,WAAW,EAAE,MAAM,EAAE,CAAC,oBAAoB,CAAC,CAAA;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC"}