dsh-mobile-plugin 0.0.0-stage → 0.1.57

package/lib/session-cleanup.cjs

@@ -0,0 +1,153 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { execFileSync } = require('node:child_process')
+
+const DEFAULT_OLDER_THAN_MINUTES = 30
+const MINUTES = 60 * 1000
+
+const { envelopeValue } = require('./mobile/envelope.js')
+
+function asItems(response) {
+  const value = envelopeValue(response)
+  return (value && Array.isArray(value.items) ? value.items : [])
+}
+
+function asWorkspaceState(response) {
+  const value = envelopeValue(response)
+  return value && typeof value === 'object' ? value : {}
+}
+
+function projectItems(items, cwd) {
+  return items.filter(item => item?.cwd === cwd)
+}
+
+function candidates(items, archivedSessionIds, args, now = Date.now()) {
+  const ids = new Set(Array.isArray(args.sessionIds) ? args.sessionIds.filter(id => typeof id === 'string' && id) : [])
+  const cutoff = now - (Number.isFinite(args.olderThanMinutes) ? args.olderThanMinutes : DEFAULT_OLDER_THAN_MINUTES) * MINUTES
+  return items.filter(item => {
+    if (item?.blank || item?.running || typeof item?.sessionId !== 'string') return false
+    if (ids.size > 0) return ids.has(item.sessionId)
+    if (typeof args.cwd === 'string' && args.cwd && item.cwd !== args.cwd) return false
+    if (!Number.isFinite(item.updatedAt) || item.updatedAt >= cutoff) return false
+    if (args.action === 'delete' && !archivedSessionIds.has(item.sessionId)) return false
+    return true
+  })
+}
+
+function projectCount(items, cwd) {
+  return projectItems(items, cwd).filter(item => !item?.blank).length
+}
+
+const { dshHome } = require('./shared/paths')
+
+function readHeader(file) {
+  try {
+    const firstLine = execFileSync('zstd', ['-dc', file], { encoding: 'utf8', maxBuffer: 16384 }).split('\n', 1)[0]
+    return JSON.parse(firstLine)
+  } catch {
+    return undefined
+  }
+}
+
+function sessionFiles(root) {
+  const result = []
+  const visit = directory => {
+    let entries
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const file = path.join(directory, entry.name)
+      if (entry.isDirectory()) visit(file)
+      else if (entry.name === 'session.jsonl.zstd') result.push(file)
+    }
+  }
+  visit(root)
+  return result
+}
+
+function deleteSessionData(sessionIds) {
+  const ids = new Set(sessionIds)
+  const removed = []
+  const root = path.join(dshHome(), 'sessions')
+  for (const file of sessionFiles(root)) {
+    const header = readHeader(file)
+    if (!header || !ids.has(header.id)) continue
+    try {
+      fs.rmSync(path.dirname(file), { recursive: true, force: true })
+      removed.push(header.id)
+    } catch (error) {
+      throw new Error(`删除会话 ${header.id} 失败：${error.message}`)
+    }
+  }
+  const cacheRoot = path.join(dshHome(), 'storages', 'session_projcache', 'sessions')
+  for (const id of ids) {
+    for (const name of [`${id}.json`, `session-${id}.json`]) {
+      try { fs.rmSync(path.join(cacheRoot, name), { force: true }) } catch { /* cache cleanup is best effort */ }
+    }
+  }
+  return removed
+}
+
+async function cleanupSessions(ctx, args) {
+  const list = ctx.apiProxy?.sessions?.list
+  const workspaceList = ctx.apiProxy?.workspace?.list
+  const archive = ctx.apiProxy?.workspace?.archiveSession
+  if (typeof list !== 'function' || typeof workspaceList !== 'function' || typeof archive !== 'function') throw new Error('会话清理能力不可用')
+  // 兼容桥总是提供这三个方法（它就是 apiProxy 的实现），所以「方法在不在」不再是宿主
+  // 能力探针 —— 真正要看的是调用结果：宿主没这个能力时会回 host-unavailable。
+  const listResponse = await list({ rpcId: 'dsh-mobile-plugin-session-cleanup', method: 'session.list', payload: {} })
+  const workspaceResponse = await workspaceList({ rpcId: 'dsh-mobile-plugin-session-cleanup', method: 'workspace.list', payload: {} })
+  for (const [name, response] of [['session.list', listResponse], ['workspace.list', workspaceResponse]]) {
+    const failure = response && response.result && response.result.ok === false ? response.result.error : null
+    if (failure) throw new Error(`${name} 失败：${failure.message || failure.code || '未知错误'}`)
+  }
+  const items = asItems(listResponse)
+  const workspace = asWorkspaceState(workspaceResponse)
+  const archived = new Set(Array.isArray(workspace.archivedSessionIds) ? workspace.archivedSessionIds : [])
+  const selected = candidates(items, archived, args)
+  const cwd = args.cwd || selected.find(item => item.cwd)?.cwd || ''
+  if (args.minProjectSessions && cwd && projectCount(items, cwd) < args.minProjectSessions) return { action: args.action, cwd, selected: 0, archived: 0, deleted: 0, failed: 0, sessionIds: [] }
+  if (args.action === 'archive') {
+    let count = 0
+    const failures = []
+    for (const item of selected) {
+      try {
+        const result = await archive({ rpcId: 'dsh-mobile-plugin-session-cleanup', method: 'workspace.archiveSession', payload: { sessionId: item.sessionId } })
+        const failure = result && result.result && result.result.ok === false ? result.result.error : null
+        if (failure) throw new Error(failure.message || '归档被拒绝')
+        count += 1
+      } catch (error) { failures.push({ sessionId: item.sessionId, error: error.message }) }
+    }
+    return { action: args.action, cwd, selected: selected.length, archived: count, deleted: 0, failed: failures.length, failures, sessionIds: selected.map(item => item.sessionId) }
+  }
+  if (args.confirm !== true) throw new Error('永久删除需要 confirm: true')
+  const ids = selected.map(item => item.sessionId)
+  const deletedIds = deleteSessionData(ids)
+  return { action: args.action, cwd, selected: ids.length, archived: 0, deleted: deletedIds.length, failed: ids.length - deletedIds.length, sessionIds: deletedIds }
+}
+
+function registerSessionCleanupTool(ctx) {
+  const { defineTool } = require('@deepseek-ai/dsh-tools')
+  ctx.tools.register(defineTool({
+    name: 'session_cleanup',
+    description: 'Archive or permanently delete old DSH sessions. Delete only targets already archived sessions and requires confirm=true.',
+    parameters: {
+      action: { type: 'string', required: true, enum: ['archive', 'delete'], description: 'archive hides sessions; delete permanently removes their logs and local projection cache.' },
+      cwd: { type: 'string', description: 'Project directory to target. Required when selecting by age across multiple projects.' },
+      olderThanMinutes: { type: 'number', description: 'Only target sessions not updated within this many minutes. Defaults to 30.' },
+      minProjectSessions: { type: 'integer', description: 'Skip the operation when the selected project has fewer sessions than this number.' },
+      sessionIds: { type: 'array', items: { type: 'string' }, description: 'Explicit session IDs. When provided, age and project filters are ignored.' },
+      confirm: { type: 'boolean', description: 'Must be true for permanent deletion.' },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: {
+        action: { type: 'string' }, cwd: { type: 'string' }, selected: { type: 'integer' }, archived: { type: 'integer' }, deleted: { type: 'integer' }, failed: { type: 'integer' }, sessionIds: { type: 'array', items: { type: 'string' } }, failures: { type: 'array', items: { type: 'object' } },
+      } },
+      render: (_args, value) => [{ type: 'text', text: `${value.action === 'archive' ? 'Archived' : 'Deleted'} ${value.action === 'archive' ? value.archived : value.deleted} sessions.` }],
+    },
+    execute: (args) => cleanupSessions(ctx, args),
+  }))
+}
+
+module.exports = { cleanupSessions, registerSessionCleanupTool }

package/lib/shared/credentials-entry.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * 凭据包 `dsh-mobile-credentials` 的入口。
+ *
+ * 它在盘上有**两代布局**：
+ *
+ *   - 新布局：嵌在插件包内 —— `<插件包>/dsh-mobile-credentials/lib/credentials.js`
+ *     （一代自包含，回滚时凭据版本跟着一起回滚）；
+ *   - 旧布局：与插件包同级 —— `node_modules/dsh-mobile-credentials/…`，
+ *     代际目录下则是 `<代>/dsh-mobile-credentials/…`。
+ *
+ * 往哪里落由**外壳**（`lib/shell/ota.js` 的资产重映射）决定，而外壳在进程启动时就被 Node
+ * 缓存住、换不掉。布局迁移那一次，旧外壳把凭据放进同级目录、新实现却按嵌套路径 require，
+ * 结果是「装完激活才炸 Cannot find module」——热更半装成功，留下的一代还是残缺的。
+ *
+ * 所以这里两条路都试，谁在就用谁：旧外壳配新实现也能跑起来，布局迁移不再是地雷。
+ */
+
+/** 新布局：`<插件包>/dsh-mobile-credentials/`（本文件在 `<插件包>/lib/shared/`）。 */
+const NESTED = '../../dsh-mobile-credentials/lib/credentials.js';
+/** 旧布局：与插件包同级。 */
+const SIBLING = '../../../dsh-mobile-credentials/lib/credentials.js';
+
+let cached = null;
+
+/** 找到凭据包入口；两条布局都没有时抛 MODULE_NOT_FOUND，并说清试过哪两条路。 */
+function credentialsEntry() {
+  if (cached) return cached;
+  const tried = [];
+  for (const candidate of [NESTED, SIBLING]) {
+    try {
+      cached = require(candidate);
+      return cached;
+    } catch (error) {
+      if (!error || error.code !== 'MODULE_NOT_FOUND') throw error;
+      tried.push(candidate);
+    }
+  }
+  const error = new Error(
+    `找不到凭据包 dsh-mobile-credentials（试过 ${tried.join('、')}）：它要么嵌在插件包内，`
+    + '要么与插件包同级。请重新完整安装插件。',
+  );
+  error.code = 'MODULE_NOT_FOUND';
+  throw error;
+}
+
+module.exports = { credentialsEntry, CREDENTIALS_CANDIDATES: [NESTED, SIBLING] };

package/lib/shared/dshtoken.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * 插件侧 LAN/mobile token（HMAC-SHA256 base64url）共享实现。
+ *
+ * token 格式：<instanceId>.<exp>.<hmac-sha256(secret, "<instanceId>.<exp>") base64url>
+ * 其中 exp 为秒级过期时间戳。signLanToken/verifyLanToken 显式收 ttlSec / secret 参数，
+ * 由调用方显式传入各自历史缺省值（本函数不隐藏调用点差异）。
+ */
+
+const crypto = require('node:crypto');
+
+/** 常数时间字符串比较（长度不等直接 false，恰好相等时用 timingSafeEqual）。 */
+function safeEqual(a, b) {
+  const ba = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  return ba.length === bb.length && crypto.timingSafeEqual(ba, bb);
+}
+
+/** HMAC 迭代中安全地把 secret 规整为字符串（与各调用点历史一致，字符串 secret 等价）。 */
+function hmacPayload(secret, payload) {
+  return crypto.createHmac('sha256', secret).update(payload).digest('base64url');
+}
+
+/**
+ * 签发 LAN/mobile token：<instanceId>.<exp>.<sig>。
+ * 缺省 ttlSec=30d（与 relay core / browser core 历史缺省一致），但**消费方必须显式传原值**
+ * （LAN 主进程 3600、30d 处 30*24*3600），本函数不隐藏调用点的默认值差异。
+ * @param {string} secret      lanSecret（~/.dsh/relay.json 密钥）
+ * @param {string} instanceId  实例 id（~/.dsh/relay.json）
+ * @param {number} ttlSec      有效期（秒），缺省 30*24*3600
+ * @param {number} [nowSec]    秒级「当前时间」覆盖（测试/主进程签名用）；缺省 Date.now()/1000
+ * @returns {string}
+ */
+function signLanToken(secret, instanceId, ttlSec = 30 * 24 * 3600, nowSec) {
+  const sec = Number(ttlSec);
+  const ttl = Number.isFinite(sec) && sec > 0 ? sec : 30 * 24 * 3600;
+  const now = Number.isFinite(nowSec) && nowSec >= 0 ? nowSec : Math.floor(Date.now() / 1000);
+  const exp = now + ttl;
+  const payload = `${instanceId}.${exp}`;
+  const sig = hmacPayload(secret, payload);
+  return `${payload}.${sig}`;
+}
+
+/**
+ * 校验 token：实例匹配、未过期、签名一致（常数时间）。
+ * @param {string} secret      lanSecret
+ * @param {string} token       <instanceId>.<exp>.<sig>
+ * @param {string} instanceId  期望实例 id
+ * @returns {boolean}
+ */
+function verifyLanToken(secret, token, instanceId) {
+  if (!token) return false;
+  const [id, expStr, sig] = String(token).split('.');
+  if (id !== instanceId || !expStr || !sig) return false;
+  const exp = Number(expStr);
+  if (!Number.isFinite(exp) || exp < Math.floor(Date.now() / 1000)) return false;
+  const expect = hmacPayload(secret, `${id}.${expStr}`);
+  return safeEqual(expect, sig);
+}
+
+module.exports = { signLanToken, verifyLanToken, safeEqual };

package/lib/shared/fresh-request.js

@@ -0,0 +1,35 @@
+'use strict'
+
+// 「读己所写」(read-your-writes) 标记：移动端做完一次写操作之后紧接着的那次列表刷新，
+// 必须反映出这次写入，不能被任何「代读副本」顶掉。
+//
+// 背景（真机缺陷，探针实测）：移动端的读请求会经过两层代读副本——
+//   1. sidecar 的镜像快照（mirror-snapshot.cjs 判定新鲜度）直接把 /sessions、
+//      /workspaces 回给手机，根本不连宿主插件；桌面侧 500ms 推一次，所以正常最多
+//      旧 500ms；
+//   2. 宿主插件自己的 10s 会话列表缓存（lib/mobile/sessions.js 的
+//      SESSION_LIST_CACHE_MS）。
+// 两层对「每 15s 一次的轮询」都无所谓，但写操作之后的第一次刷新撞上任何一层，就会把
+// 用户刚做完的事显示成没生效。
+//
+// 实测（Mac 宿主 + MI 9，时间戳相对点击「归档」按钮）：
+//   + 311ms  HOST archive-session session-63acd828-…      ← 宿主侧已经改对了
+//   + 375ms  SNAPSHOT /api/mobile/v1/sessions fresh        ← App 的刷新读到 +286ms 推来的旧镜像
+//   +17233ms SNAPSHOT /api/mobile/v1/sessions fresh        ← 直到 15s 轮询才拿到新列表
+//
+// 于是约定 `?fresh=1`：带这个标记的读跳过所有代读副本，直接回源宿主插件。
+// 轮询、首屏、下拉刷新不带，快路径照旧。
+//
+// 权威实现在本文件；`dsh-mobile-server/lib/fresh-request.js` 是它的手工同步副本，
+// 两侧由 `test/shared-helpers-parity.test.cjs` 钉住。**改一边必须改另一边。**
+// 中转侧同样必须认这个标记：中转自己也持有镜像与响应缓存，它若把带 fresh 的读
+// 当普通读缓存掉，App 的下拉刷新就失去了唯一的自救手段。
+
+const FRESH_QUERY_RE = /(?:^|[?&])fresh=1(?:&|$)/
+
+/** 判断一次请求（完整 url 或 path，可带 query）是否要求「必须读出最新状态」。 */
+function isFreshRequest(target) {
+  return FRESH_QUERY_RE.test(String(target || ''))
+}
+
+module.exports = { FRESH_QUERY_RE, isFreshRequest }

package/lib/shared/http-util.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * 插件侧 HTTP 小工具共享实现（sendJson / 读取 body）。
+ *
+ * 中转服务器（dsh-mobile-server）独立部署，保留自身实现，仅作参考。
+ */
+
+/**
+ * 写 JSON 响应（UTF-8）。连接已关闭时静默忽略。
+ * @param {object} res    node:http ServerResponse
+ * @param {number} status HTTP 状态码
+ * @param {object} body   响应体（JSON.stringify）
+ */
+function sendJson(res, status, body) {
+  try {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+  } catch { /* 连接已关闭 */ }
+}
+
+/**
+ * 写 HTML 响应（UTF-8）。连接已关闭时静默忽略。
+ *
+ * 面板页是整页吐给浏览器的，所以必须显式声明 charset：少了它浏览器会按本地编码猜，
+ * 中文标题直接变乱码。`no-store` 是刻意的——这份 HTML 就是「改完刷新即生效」的那一份，
+ * 缓存住反而会把刚发布的版式藏起来。
+ *
+ * @param {object} res    node:http ServerResponse
+ * @param {number} status HTTP 状态码
+ * @param {string} html   响应体
+ */
+function sendHtml(res, status, html) {
+  try {
+    res.writeHead(status, {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'no-store',
+    });
+    res.end(html);
+  } catch { /* 连接已关闭 */ }
+}
+
+/**
+ * 读取请求体并 JSON.parse；超限/非法 JSON/IO 错误 → null。
+ * @param {object} req         node:http IncomingMessage
+ * @param {number} [maxBytes]  请求体上限（字节），缺省 256KB
+ * @returns {Promise<object|null>}
+ */
+function readJsonBody(req, maxBytes = 256 * 1024) {
+  return new Promise((resolve) => {
+    let raw = '';
+    req.on('data', (chunk) => {
+      raw += chunk;
+      if (raw.length > maxBytes) {
+        req.destroy();
+        resolve(null);
+        return;
+      }
+    });
+    req.on('end', () => {
+      try {
+        resolve(raw.length > 0 ? JSON.parse(raw) : null);
+      } catch {
+        resolve(null);
+      }
+    });
+    req.on('error', () => resolve(null));
+  });
+}
+
+module.exports = { sendJson, sendHtml, readJsonBody };

package/lib/shared/list-revision.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * 清单内容指纹（sessions / workspaces 共用）。
+ *
+ * 存在的理由：手机端有两件事需要「这份清单和上次是不是同一份」——
+ *
+ *  1. 数据新鲜度：列表响应带 `revision`，App 把它连同 `generatedAt` 一起存进快照，
+ *     就能把「数据是谁在什么时候给的」显示给用户，而不是让用户自己猜；
+ *  2. 镜像推送判重（见 lib/mirror/pusher.cjs）：后台 500ms tick 每轮都会完整构建
+ *     sessions + workspaces，内容没变时推送一份字节完全相同的 payload 纯属浪费，
+ *     比对 revision 就能安全跳过。
+ *
+ * 为什么用内容哈希而不是自增序号：插件随桌面 harness 频繁重启，内存里的序号每次
+ * 都从 0 开始，重启后第一份快照会因为「序号变了」而被当成新内容重推一遍；内容哈希
+ * 跨重启稳定（同样的清单 → 同样的 revision），这才是判重想要的性质。
+ *
+ * 为什么用 sha1 而不是更省的 32 位哈希：这个值会被用来**跳过推送**，一次碰撞就等于
+ * 一份该推的新数据被静默丢掉。sha1 足够便宜（清单量级下每 tick 亚毫秒），不值得为
+ * 几个字节冒这个风险。截断到 16 个十六进制字符只是为了让日志短一点。
+ */
+
+const crypto = require('node:crypto');
+
+/**
+ * 语义内容的稳定指纹。
+ *
+ * `JSON.stringify` 保留键的插入顺序，而同一份清单在不同构建路径上键序是稳定的
+ * （都由同一段投影代码生成），所以这里不做键排序；调用方换投影字段时自然得到新
+ * revision，这正是我们要的（字段变了就是内容变了）。
+ *
+ * @param {unknown} value 任意可序列化值
+ * @returns {string} 16 个十六进制字符；不可序列化时返回空串（调用方按「未知」处理）
+ */
+function stableRevision(value) {
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    return '';
+  }
+  if (typeof text !== 'string') return '';
+  return crypto.createHash('sha1').update(text).digest('hex').slice(0, 16);
+}
+
+/** 清单数组的 revision；空清单也有一个稳定的值（不是空串）。 */
+function listRevision(items) {
+  return stableRevision(Array.isArray(items) ? items : []);
+}
+
+module.exports = { stableRevision, listRevision };

package/lib/shared/list-signal.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * 设备级「清单变了」信号总线：插件内部唯一一条「有内容值得让手机立刻刷新」的通道。
+ *
+ * 存在的理由（真机现象）：侧边栏的实时性此前完全押在设备级 SSE 上，而那条流在宿主的
+ * 0.2.0 兼容桥里只订阅了 workspace/follow 与 session/control —— 会话状态变化表现为
+ * session/projection 帧，被手机侧白名单（lib/mobile/events.js 的 listRelevantPayload）
+ * 丢掉。于是流「连着但一句话都不说」，App 却因为 open 就把兜底轮询从 15s 降到 60s，
+ * 侧栏变成一分钟才动一次。
+ *
+ * 而插件这边**本来就知道列表何时变了**：镜像推送调度器（lib/mirror/pusher.cjs）每
+ * 500ms 完整构建一次会话清单，清单自带内容指纹 revision。缺的只是「把这件事说给手机
+ * 听」的出口，本模块就是那个出口。
+ *
+ * 为什么是模块级单例而不是 ctx 上的服务：生产端（pusher.cjs，CJS）与消费端
+ * （mobile/events.js，CJS）都通过 require 拿到同一个实例，两边都不需要认识对方；
+ * 测试可以 createListSignal() 造一个独立实例注入。
+ *
+ * 为什么订阅者抛错要被吞掉：bus 的调用方是推送调度器的 500ms tick，一个写坏的 SSE
+ * 连接不能把镜像推送整条链拖垮（真故障会从连接自身的 close 反映出来）。
+ */
+
+const NOOP_RELEASE = () => {};
+
+function createListSignal() {
+  const listeners = new Set();
+  let watchers = 0;
+  let revision = '';
+  let at = 0;
+
+  return {
+    /**
+     * 广播一次清单变更。同一个 revision 连着广播两次只算一次（幂等）。
+     *
+     * @param {string} nextRevision 清单内容指纹（lib/shared/list-revision.js 的 listRevision）
+     * @returns {boolean} 是否真的广播了
+     */
+    bump(nextRevision) {
+      const value = typeof nextRevision === 'string' ? nextRevision : '';
+      if (value && value === revision) return false;
+      revision = value;
+      at = Date.now();
+      for (const listener of [...listeners]) {
+        try { listener({ revision, at }); } catch { /* 订阅者自己的异常不该影响推送方 */ }
+      }
+      return true;
+    },
+
+    /** 订阅变更；返回退订函数（可重复调用）。 */
+    onBump(listener) {
+      if (typeof listener !== 'function') return NOOP_RELEASE;
+      listeners.add(listener);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        listeners.delete(listener);
+      };
+    },
+
+    /**
+     * 登记一个「有人在听」的观众（每条设备级 SSE 连接一个），返回注销函数。
+     *
+     * watching() 决定推送调度器在**隧道断开**时还要不要空转构建：没有观众时那份快照
+     * 没有任何去处，构建纯属浪费；有观众时它是手机唯一的变更来源，必须继续构建。
+     */
+    watch() {
+      watchers += 1;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        watchers = Math.max(0, watchers - 1);
+      };
+    },
+
+    watching() { return watchers > 0; },
+
+    /** 最近一次变更（供诊断面板观测）。 */
+    snapshot() { return { revision, at }; },
+  };
+}
+
+const listSignal = createListSignal();
+
+module.exports = { createListSignal, listSignal };

package/lib/shared/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/shared/paths.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * 插件与中转共用的 DSH 数据目录路径。
+ *
+ * 原先这里还包含内置浏览器、桌面更新器、配对授权弹窗握手的落盘路径，
+ * 那些都属于已删除的桌面端外壳，本模块已收窄为插件真正使用的两处。
+ * 均为纯函数（按调用时 env 解析，测试可注入 DSH_HOME）。
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+
+/** DSH 数据目录：DSH_HOME 可覆盖，缺省 ~/.dsh。 */
+function dshHome() {
+  return process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+}
+
+/** 远程连接（relay）插件状态文件：~/.dsh/relay.json */
+function relayStateFile() {
+  return path.join(dshHome(), 'relay.json');
+}
+
+module.exports = {
+  dshHome,
+  relayStateFile,
+};

package/lib/shared/session-signal.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * 设备级「某个会话的正文水位涨了」信号总线。
+ *
+ * 与 list-signal.js（清单变了）是同一形状的第二条通道，存在的理由是对话页的第二种场景：
+ * 手机上**没有打开**某个会话时，那条会话的正文此前完全没人订阅 —— 只有打开的会话才建
+ * `session/stream`（app/src/hooks/useChatStream.ts 的唯一调用点），所以「在别的地方盯着
+ * 列表」时，运行中的助手回复只能等下一次点开该会话才被拉下来。
+ *
+ * 而插件这边本来就把正文推到了中转镜像：镜像调度器（lib/mirror/pusher.cjs）每轮为高优先
+ * 会话（运行中 / 5 分钟内动过）构建 200 条消息快照，冷会话每 500ms 轮转补一个。缺的只是
+ * 「这个会话的正文又长了，你（手机）可以来取」这一句通知，本模块就是那个出口。
+ *
+ * 与 list-signal 的关键差别：清单信号是**全局**的（一个 revision），这条是**按会话**的
+ * （sessionId → 已广播到的消息水位 seq）。水位取的是快照里**真正装上的消息的最大 seq**
+ * （见 pusher 的 messageWatermarkOf），也就是 App 侧会话缓存的水位口径（同一个 seq 空间），
+ * 手机拿它和自己的缓存水位一比就知道该不该增量拉一次。
+ *
+ * 为什么是模块级单例：生产端（mirror/pusher.cjs，CJS）与消费端（mobile/events.js，CJS）
+ * 都 require 到同一个实例，两边不需要认识对方；测试可以 createSessionSignal() 造独立实例。
+ * 为什么订阅者抛错要吞掉：bus 的调用方是镜像推送链，一条写坏的 SSE 连接不能把推送拖垮
+ * （真故障会从连接自身的 close 反映出来）。
+ */
+
+const NOOP_RELEASE = () => {};
+
+/**
+ * 最多记多少会话的水位。
+ *
+ * 键是 sessionId、只增不减：一个长期运行的插件会见过成千上万个会话（归档的、一次性的），
+ * 而水位只用来判「这次广播是不是新的」，旧会话的水位没有任何价值。超限时丢最早活动的那条。
+ */
+const MAX_TRACKED = 512;
+
+function createSessionSignal() {
+  const listeners = new Set();
+  /** sessionId -> { seq, at }：最近一次广播出去的水位。 */
+  const watermarks = new Map();
+
+  const pruneOldest = () => {
+    let oldestKey = null;
+    let oldestAt = Infinity;
+    for (const [key, value] of watermarks) {
+      if (value.at < oldestAt) { oldestAt = value.at; oldestKey = key; }
+    }
+    if (oldestKey !== null) watermarks.delete(oldestKey);
+  };
+
+  return {
+    /**
+     * 广播一个会话的正文水位。
+     *
+     * 同一个会话的水位不变（或更低）时什么都不做（幂等）：镜像推送每轮都带着所有高优先
+     * 会话的快照，没有这一层判重就会变成每 500ms 给手机发一遍同样的帧。
+     *
+     * @param {string} sessionId
+     * @param {number} seq 快照里真正装上的消息的最大 seq
+     * @returns {boolean} 是否真的广播了
+     */
+    bump(sessionId, seq) {
+      const id = typeof sessionId === 'string' ? sessionId : '';
+      const value = Number(seq);
+      if (!id || !Number.isFinite(value) || value <= 0) return false;
+      const previous = watermarks.get(id);
+      if (previous && value <= previous.seq) return false;
+      const at = Date.now();
+      watermarks.set(id, { seq: value, at });
+      if (watermarks.size > MAX_TRACKED) pruneOldest();
+      for (const listener of [...listeners]) {
+        try { listener({ sessionId: id, seq: value, at }); } catch { /* 订阅者自己的异常不该影响推送方 */ }
+      }
+      return true;
+    },
+
+    /** 订阅水位变化；返回退订函数（可重复调用）。 */
+    onBump(listener) {
+      if (typeof listener !== 'function') return NOOP_RELEASE;
+      listeners.add(listener);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        listeners.delete(listener);
+      };
+    },
+
+    /** 某个会话当前已广播到的水位（0 = 还没广播过）。 */
+    peek(sessionId) {
+      const entry = watermarks.get(sessionId);
+      return entry ? entry.seq : 0;
+    },
+
+    /** 全部水位（供诊断面板观测）；键为 sessionId，值为 seq。 */
+    snapshot() {
+      const out = {};
+      for (const [key, value] of watermarks) out[key] = value.seq;
+      return out;
+    },
+
+    /** 测试用：清空状态。 */
+    reset() {
+      watermarks.clear();
+    },
+  };
+}
+
+const sessionSignal = createSessionSignal();
+
+module.exports = { createSessionSignal, sessionSignal, MAX_TRACKED };