dsh-plugin-mobile-link 0.8.0 → 0.8.1

package/lib/link.js

@@ -5,9 +5,10 @@
  */
 
 import { EventEmitter } from 'node:events'
+import { dirname, join } from 'node:path'
 
 import { DshClient } from './dsh-client.js'
-import { agentEndpoint, decodeFrame, deviceListEndpoint, deviceRevokeEndpoint, encodeFrameChecked, isPlaceholderRelayUrl, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
+import { agentEndpoint, decodeFrame, deviceListEndpoint, deviceRevokeEndpoint, encodeFrameChecked, isPlaceholderRelayUrl, nextBackoff, normalizeRelayUrl, pongFor, qrPayload } from './dlp.js'
 
 /**
  * 进程级登记表：**同一个进程里只允许有一条到中转的 agent 连接**。
@@ -30,11 +31,17 @@ import {
 } from './router.js'
 import { SERVER_VERSION, SERVER_CAPABILITIES, hostVersion } from './hello.js'
 import { createJobsRoster } from './jobs-roster.js'
-import { MissingIdentity, defaultStatePath, readState, resolveIdentity } from './state.js'
+import { MissingIdentity, defaultStatePath, readState, resolveIdentity, writeState } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
 const PROTOCOL_VERSION = 1
 
+// WebSocket 关闭码：中转据此区分"计划内重连"和"需要处理的异常"（SR-08.08）。
+// 4002 已用于中转协议错误；这里补上两类自愈失败的码，不要再把 1000 复用给它们。
+const CLOSE_NORMAL = 1000
+const CLOSE_WATCHDOG = 4003
+const CLOSE_HEARTBEAT = 4004
+
 
 function sleep(ms, signal) {
   return new Promise((resolve) => {
@@ -54,6 +61,55 @@ function numberFromEnv(raw, fallback) {
   return Number.isFinite(value) && value >= 0 ? value : fallback
 }
 
+// ── 持久码缓存 ──────────────────────────────────────────────────────────
+
+/**
+ * 上次铸出来的持久码放在身份文件旁边（0600）。
+ *
+ * 中转只存码的哈希，铸码接口不会把同一张码再给一次，所以「小窗复用同一张持久码」
+ * （docs/PAIRING.md「二维码」一行）只能由连接器自己记住：面板每次打开都会请求一次码，
+ * 没有这份缓存就变成每开一次、每重载一次都多一张永久有效的码。
+ */
+function pairCodeCachePath(config) {
+if (config?.pairCodePath) return config.pairCodePath
+return join(dirname(config?.stateFile || defaultStatePath()), 'pair-code.json')
+}
+
+async function rememberPairCode(config, minted) {
+if (!minted?.code) return
+try {
+  await writeState(pairCodeCachePath(config), {
+    code: minted.code,
+    agentId: minted.agentId,
+    relayUrl: minted.relayUrl,
+    maxPairedDevices: minted.maxPairedDevices ?? null,
+    pairedDevices: Number(minted.pairedDevices ?? 0),
+    savedAt: Date.now(),
+  })
+} catch (error) {
+  // 缓存写不进去只影响"下次还会不会换码"，不该让这次取码失败。
+  config?.logger?.warn?.(`mobile-link: could not remember the pairing code: ${messageOf(error)}`)
+}
+}
+
+async function readRememberedPairCode(config, identity) {
+const file = await readState(pairCodeCachePath(config))
+if (!file || typeof file.code !== 'string' || !file.code) return null
+// 身份变了（重新登记、换了中转）就不是同一台电脑的码，不能拿来复用。
+if (file.agentId !== identity.agentId || file.relayUrl !== identity.relayUrl) return null
+return {
+  code: file.code,
+  expiresAt: null,
+  ttlMs: null,
+  persistent: true,
+  maxPairedDevices: Number(file.maxPairedDevices ?? 0) || null,
+  pairedDevices: Number(file.pairedDevices ?? 0),
+  relayUrl: identity.relayUrl,
+  agentId: identity.agentId,
+  qrPayload: qrPayload({ relay: identity.relayUrl, code: file.code }),
+}
+}
+
 export class MobileLinkAgent extends EventEmitter {
   constructor({
     relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl,
@@ -138,6 +194,9 @@ export class MobileLinkAgent extends EventEmitter {
     /// 历史读取（spec 007）：宿主 `sessionQuery` 就绪后由插件挂上；没挂上时
     /// 路由回 `link/unsupported`，手机继续走 `session/page`。
     this.setHistoryService = (service) => { this.router.history = service }
+    /// 图片两变体（预览 + 可选原图）：宿主 `attachments` / `fileUploads` 就绪后由插件挂上；
+    /// 没挂上时三个 `_link/image*` 方法回 `link/unsupported`（手机显示"原图不可用"）。
+    this.setImageVariants = (service) => { this.router.bindImageVariants(service) }
     /// 活动名单与 `link/jobs` 推帧（spec 018）：帧由 router 广播给在线设备，
     /// 订阅与去抖都在 roster 里。宿主服务由 `setJobsServices` 挂上。
     this.jobsRoster = createJobsRoster({
@@ -147,6 +206,9 @@ export class MobileLinkAgent extends EventEmitter {
     })
     this.router.bindJobsRoster(this.jobsRoster)
     this.setJobsServices = (services) => this.jobsRoster.bindServices(services)
+    /// 提醒口径（SR-02.08）：只报正式会话。宿主 `ctx.sessions` / `ctx.workspaceRegistry`
+    /// 由插件在 `wireSessionScope` 里挂上；缺一个就维持旧行为（全报）。
+    this.setSessionScopeServices = (services) => this.router.bindSessionScope(services)
     this.relay = undefined
     this.socket = undefined
     this.state = 'idle'
@@ -681,7 +743,7 @@ export class MobileLinkAgent extends EventEmitter {
         this.lastError = `relay 超过 ${Math.round(idle / 1000)}s 没有动静（看门狗拆连接）`
         this.journal.record('watchdog.drop', { idleMs: Math.round(idle), state: this.state })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
-        this.#teardownSocket(this.lastError)
+        this.#teardownSocket(this.lastError, CLOSE_HEARTBEAT, 'heartbeat timeout')
         this._lastProgressAt = this.now()
         return
       }
@@ -689,7 +751,7 @@ export class MobileLinkAgent extends EventEmitter {
         this.lastError = `链路 ${Math.round(idle / 1000)}s 没有进展（看门狗重建连接）`
         this.journal.record('watchdog.drop', { idleMs: Math.round(idle), state: this.state })
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
-        this.#teardownSocket(this.lastError)
+        this.#teardownSocket(this.lastError, CLOSE_WATCHDOG, 'watchdog timeout')
         this._lastProgressAt = this.now()
       }
     }, every)
@@ -707,7 +769,7 @@ export class MobileLinkAgent extends EventEmitter {
       if (this.now() - this._lastPong > this.pongTimeoutMs) {
         this.lastError = `relay stopped answering pings (>${this.pongTimeoutMs}ms)`
         this.logger.warn?.(`mobile-link: ${this.lastError}`)
-        this.#teardownSocket(this.lastError)
+        this.#teardownSocket(this.lastError, CLOSE_HEARTBEAT, 'heartbeat timeout')
         return
       }
       this.#rawSend({ t: 'ping', ts: this.now() })
@@ -720,14 +782,14 @@ export class MobileLinkAgent extends EventEmitter {
     this._heartbeat = undefined
   }
 
-  #teardownSocket(reason) {
+  #teardownSocket(reason, closeCode = CLOSE_NORMAL, closeReason = 'reconnecting') {
     this.#stopHeartbeat()
     const socket = this.socket
     const from = this.state
     this.socket = undefined
     if (socket) {
       try {
-        socket.close(1000, 'reconnecting')
+        socket.close(closeCode, closeReason)
       } catch {
         /* already gone */
       }
@@ -744,6 +806,7 @@ export class MobileLinkAgent extends EventEmitter {
     // connectedForMs 用来区分"刚连上就掉"和"挂了很久才掉"。
     this.journal.record('link.close', {
       reason,
+      closeCode,
       from,
       connectedForMs: this.connectedAt === undefined ? undefined : this.now() - this.connectedAt,
       // 有系统错误才带这个字段（正常关闭时不该凭空多一个 null）。
@@ -886,7 +949,7 @@ export class MobileLinkAgent extends EventEmitter {
     this.router.onMuxDown(reason)
   }
 
-  // ── relay-side helpers ──────────────────────────────────────────────────
+// ── relay-side helpers ──────────────────────────────────────────────────
 
   /**
    * Ask the relay to mint a pairing code for this agent (relay NOTES.md §2).
@@ -895,13 +958,23 @@ export class MobileLinkAgent extends EventEmitter {
    */
   async mintPairCode({ ttlMs = null, fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
-    return mintPairCode({ identity, ttlMs, fetchImpl })
+    // 持久码：手上已经有一张就直接给它。中转那边只有哈希，重铸只会多出一张有效码。
+    if (ttlMs == null) {
+      const remembered = await readRememberedPairCode(this.config, identity)
+      if (remembered) return remembered
+    }
+    const minted = await mintPairCode({ identity, ttlMs, fetchImpl })
+    if (minted.persistent) await rememberPairCode(this.config, minted)
+    return minted
   }
 
   /** 用户点「重新生成」：作废旧码、铸新的，**不碰已配对设备**（032）。 */
   async regeneratePairCode({ fetchImpl = fetch } = {}) {
     const identity = this.identity ?? await resolveIdentity(this.config)
-    return regeneratePairCode({ identity, fetchImpl })
+    const minted = await regeneratePairCode({ identity, fetchImpl })
+    // 中转已经把旧码全部作废，这里换成新的那张。
+    await rememberPairCode(this.config, minted)
+    return minted
   }
 
   /** Snapshot for `GET /mobile-link/status`（载荷本身在 status.js，便于守住"只增不改"）。 */

package/lib/router.js

@@ -16,9 +16,11 @@ import { FileInbox, FILE_BEGIN, FILE_CHUNK, FILE_END, isFileMethod } from './fil
 import { FileFetcher, FSGET_CANCEL } from './files-out.js'
 import { GitBridge, isGitMethod } from './git.js'
 import { isHelloMethod, helloPayload, parseClientInfo } from './hello.js'
+import { isImageVariantMethod } from './image-variants.js'
 import { isHistoryMethod } from './history.js'
 import { trimRecordsForWire } from './history/records.js'
 import { isJobsMethod } from './jobs-roster.js'
+import { createSessionScope } from './session-scope.js'
 
 /**
  * 后台大文件上传的桥接帧（relay → 连接器），名字见 `docs/relay-contract.json`
@@ -176,6 +178,12 @@ export class DeviceRouter {
     // 「跑完了 / 待你回应」这类事件到了就报一声（见 `notifyFor`）。默认空函数，
     // 测试与不关心提醒的调用方可以不管它。帧由 link.js 发（router 不发帧）。
     this.notify = notify
+    /**
+     * 提醒口径（SR-02.08）：只报正式会话。`undefined` = 宿主服务还没绑上，按旧行为
+     * 全报；绑上之后由 `session-scope.js` 判定。列表顶部的待答计数在 App 侧另算，
+     * 走同一份「正式会话」定义。
+     */
+    this.sessionScope = undefined
     // 生命周期事件（设备 attach/detach 等）的去处，由 link.js 接到流水（journal.js）。
     // 默认空函数，所以 router 单独用时（单测、本地脚本）不需要日志设施。
     this.onEvent = onEvent
@@ -204,6 +212,15 @@ export class DeviceRouter {
     // 活动名单与 `link/jobs` 推帧（spec 018）。订阅与去抖都在 roster 里，router 只负责
     // 转交设备生命周期与把帧广播出去。
     this.jobsRoster = undefined
+    // 图片的两变体能力（预览 + 可选原图）：由 index.js 注入宿主 `attachments` /
+    // `fileUploads` 后挂上。没挂上时三个保留方法回 `link/unsupported`，
+    // 手机显示"原图不可用"，预览照旧。
+    this.imageVariants = undefined
+  }
+
+  /** 挂上图片变体能力；`undefined` 表示宿主服务缺失（如实报不支持）。 */
+  bindImageVariants(service) {
+    this.imageVariants = service
   }
 
   /**
@@ -218,6 +235,21 @@ export class DeviceRouter {
     for (const deviceId of this.devices.keys()) roster.addDevice(deviceId)
   }
 
+  /**
+   * 挂上提醒口径所需的宿主账本（`ctx.sessions` / `ctx.workspaceRegistry`）。
+   *
+   * 传 `undefined` 摘掉：宿主换代或插件卸载后不能拿着失效服务对象去判定。
+   */
+  bindSessionScope(services) {
+    this.sessionScope = services === undefined ? undefined : createSessionScope(services)
+  }
+
+  /** 这条会话是否值得报一声（只看正式会话；服务未绑上时保持旧行为）。 */
+  #shouldNotify(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '') return false
+    return this.sessionScope === undefined || this.sessionScope.isFormal(sessionId)
+  }
+
   #changed() {
     this.onChange()
   }
@@ -755,6 +787,30 @@ export class DeviceRouter {
       return
     }
 
+    // 图片变体（预览 + 原图）：手机先经 `_link/file*` 把字节落进收件箱，再来这里
+    // 让连接器把它们交给 Host 附件服务并登记关联。自己回答而不是转发：Host
+    // 没有对应的 RPC，而这正是保留方法存在的理由。
+    if (isImageVariantMethod(frame.method)) {
+      let result
+      try {
+        if (this.imageVariants === undefined) {
+          result = {
+            ok: false,
+            error: errorObject('link/unsupported', 'image variants are unavailable on this connector'),
+          }
+        } else {
+          result = { ok: true, value: await this.imageVariants.handle(frame.method, frame.args ?? {}) }
+        }
+      } catch (error) {
+        result = {
+          ok: false,
+          error: errorObject(error?.code ?? 'link/failed', messageOf(error), error?.details ?? {}),
+        }
+      }
+      this.send(deviceId, resultFrame(frame.id, result, deviceId))
+      return
+    }
+
     // Git also runs here, on the machine that holds the work tree: the Host has
     // no endpoint that runs a command, and the review a person wants — what
     // changed, what the diff says, what the last commits were — is all local.
@@ -1018,6 +1074,9 @@ export class DeviceRouter {
    * `api-session/error`（`:3150`）**有意不推**：它不一定是"跑完了"（也可能是一轮中途
    * 报错后继续），拿它当"跑完了"会发出一堆噪音提醒。这是决定，不是漏做。
    *
+   * **只报正式会话**（SR-02.08）：未分组、子会话与已归档的运行结束和待确认不报。
+   * 这就是 `#shouldNotify` 的唯一判据来源；主机服务绑上之前维持旧行为。
+   *
    * 不做去抖、不做队列、不做重试：一轮才一条，发失败（中转断了）就丢。`turnEnd` 丢一条
    * 不值得为它做重试；`attention` 丢不了，它同时被记账，手机回来会补发。
    */
@@ -1025,11 +1084,13 @@ export class DeviceRouter {
     if (!value || typeof value !== 'object') return
     if (value.type === 'emit' && value.event === 'api-session/status' && value.args?.[1] === false) {
       const sid = String(value.args[0] ?? '')
-      if (sid) this.notify({ kind: 'turnEnd', sid })
+      if (this.#shouldNotify(sid)) this.notify({ kind: 'turnEnd', sid })
       return
     }
     if (value.type === 'waterfall') {
-      this.notify({ kind: 'attention', sid: value.agentId, eid: value.eventId })
+      if (this.#shouldNotify(value.agentId)) {
+        this.notify({ kind: 'attention', sid: value.agentId, eid: value.eventId })
+      }
     }
   }
 

package/lib/session-scope.js

@@ -0,0 +1,89 @@
+/**
+ * 哪些会话值得提醒手机（SR-02.08 / SR-02.15）。
+ *
+ * 只有**正式会话**算数：属于某个工作区、未归档、且不是子会话。未分组、子会话与
+ * 已归档会在列表里以行、桶头或转写出现，但它们不该让手机弹窗，也不该进顶部的
+ * 「等你回应」计数——一个子智能体跑完或停下来问问题，不是用户要处理的事。
+ *
+ * 判据全部来自宿主自己的账本，不做目录推断：
+ * - 子会话：`Session.header.origin === 'subagent'`（历史 fork 也可能有
+ *   `parentSession`，所以只认 `origin`，与 `@deepseek-ai/dsh-session` 的分类口径一致）；
+ * - 归档：`workspaceRegistry.archivedSessionIds`；
+ * - 属于工作区：某个 `Workspace.sessionIds` 里含这个 id。
+ *
+ * 服务没绑上时返回 `true`（保持旧行为）：拿不到宿主账本就断言"非正式"会把正式会话的
+ * 提醒一起吞掉。两种失败模式里，漏一条提醒比整类提醒消失更容易被发现。
+ */
+
+function sessionFrom(sessions, sessionId) {
+  if (typeof sessions?.get === 'function') {
+    try {
+      const found = sessions.get(sessionId)
+      if (found !== undefined && found !== null) return found
+    } catch {
+      // 会话在枚举与读取之间消失：交给下面的 list 兜底。
+    }
+  }
+  if (typeof sessions?.list !== 'function') return undefined
+  try {
+    const listed = sessions.list()
+    if (!Array.isArray(listed)) return undefined
+    return listed.find((entry) => (entry?.id ?? entry?.sessionId) === sessionId)
+  } catch {
+    return undefined
+  }
+}
+
+function archivedIds(workspaces) {
+  try {
+    const ids = workspaces?.archivedSessionIds
+    return Array.isArray(ids) ? ids : []
+  } catch {
+    // 账本还没装好：按"没有归档"处理，不让一次读失败吞掉全部提醒。
+    return []
+  }
+}
+
+function workspaceMembers(workspaces) {
+  try {
+    const listed = workspaces?.list?.()
+    return Array.isArray(listed) ? listed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * @param {{
+ *   sessions?: { get?: (id: string) => object | undefined, list?: () => object[] },
+ *   workspaces?: {
+ *     archivedSessionIds?: readonly string[],
+ *     list?: () => Array<{ sessionIds?: readonly string[] }>,
+ *   },
+ * }} [services]
+ * @returns {{ isFormal: (sessionId: string) => boolean }}
+ */
+export function createSessionScope({ sessions, workspaces } = {}) {
+  const canReadSessions = typeof sessions?.get === 'function' || typeof sessions?.list === 'function'
+  const canReadWorkspaces = typeof workspaces?.list === 'function'
+  const available = canReadSessions && canReadWorkspaces
+
+  function isFormal(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '') return false
+    // 宿主服务还没绑上：保持旧行为，见文件头。
+    if (!available) return true
+
+    const session = sessionFrom(sessions, sessionId)
+    if (session === undefined) return false
+    if ((session?.header?.origin ?? session?.origin) === 'subagent') return false
+    if (archivedIds(workspaces).includes(sessionId)) return false
+    const members = workspaceMembers(workspaces)
+    // 工作区账本读不出来：无法判定，维持旧行为，别把整类提醒一起吞掉。
+    if (members === undefined) return true
+    return members.some((workspace) => (
+      Array.isArray(workspace?.sessionIds) && workspace.sessionIds.includes(sessionId)
+    ))
+  }
+
+  return { isFormal }
+}

package/lib/status.js

@@ -8,6 +8,9 @@
 
 import { isPlaceholderRelayUrl } from './dlp.js'
 import { SERVER_CAPABILITIES, SERVER_VERSION, hostVersion } from './hello.js'
+import { T, setLanguage } from './i18n.js'
+
+if (process.env.DSH_LANG) setLanguage(process.env.DSH_LANG)
 
 const PROTOCOL_VERSION = 1
 
@@ -17,10 +20,10 @@ const PROTOCOL_VERSION = 1
  * 锚点标题与 `docs/ONBOARDING.md` 里的小节标题**逐字一致**，这样"锚点存在"可以机械核对。
  */
 export const DSH_HINTS = {
-  config: { hint: '你手工配置的本机地址不对或已失效', docAnchor: '手工指定本机地址' },
-  'host-service': { hint: '当前宿主没有把本机访问方式交给插件（多为插件没装进正在运行的宿主）', docAnchor: '装在哪里：档案与插件入口' },
-  DSH_WEB_URL: { hint: '环境变量里的本机地址已过期', docAnchor: '手工指定本机地址' },
-  unreachable: { hint: '本机 DSH 不可达；请确认宿主正在运行', docAnchor: '排查：连不上时看这里' },
+  config: { hint: '你手工配置的本机地址不对或已失效', i18n: 'status.config', docAnchor: '手工指定本机地址' },
+  'host-service': { hint: '当前宿主没有把本机访问方式交给插件（多为插件没装进正在运行的宿主）', i18n: 'status.hostService', docAnchor: '装在哪里：档案与插件入口' },
+  DSH_WEB_URL: { hint: '环境变量里的本机地址已过期', i18n: 'status.dshWebUrl', docAnchor: '手工指定本机地址' },
+  unreachable: { hint: '本机 DSH 不可达；请确认宿主正在运行', i18n: 'status.unreachable', docAnchor: '排查：连不上时看这里' },
 }
 
 /**
@@ -29,9 +32,9 @@ export const DSH_HINTS = {
  * 锚点标题与 `docs/ONBOARDING.md` 的小节标题逐字一致，`test/status.test.js` 会核对。
  */
 export const HOST_HINTS = {
-  desktop: { hint: '你正在用官方桌面版（连接器已装进它的档案）', docAnchor: '安装：官方桌面版' },
-  web: { hint: '你正在用命令行 web 版', docAnchor: '安装：命令行 web 版' },
-  unknown: { hint: '无法识别当前宿主；若连不上，请按"排查"一节处理', docAnchor: '排查：连不上时看这里' },
+  desktop: { hint: '你正在用官方桌面版（连接器已装进它的档案）', i18n: 'status.desktop', docAnchor: '安装：官方桌面版' },
+  web: { hint: '你正在用命令行 web 版', i18n: 'status.web', docAnchor: '安装：命令行 web 版' },
+  unknown: { hint: '无法识别当前宿主；若连不上，请按"排查"一节处理', i18n: 'status.unknown', docAnchor: '排查：连不上时看这里' },
 }
 
 /** 本机 DSH 侧的诊断块（老字段一个不少，新字段只增）。 */function dshBlock(agent) {
@@ -46,7 +49,7 @@ export const HOST_HINTS = {
     error: agent.dshError ?? null,
     // 新增（只增不改）：失败分类 + 用户可读的一句话 + 文档锚点。
     errorKind,
-    hint: entry?.hint ?? null,
+    hint: entry?.i18n ? T(entry.i18n) : entry?.hint ?? null,
     docAnchor: entry?.docAnchor ?? null,
   }
 }
@@ -108,7 +111,7 @@ export function statusSnapshot(agent) {
     // 新增（只增不改）：宿主形态 + 它对应的一句话与文档锚点，
     // 决定用户该按哪条说明安装/排障（FR-012）。
     host: agent.hostForm,
-    hostHint: hostEntry.hint,
+    hostHint: hostEntry.i18n ? T(hostEntry.i18n) : hostEntry.hint,
     hostDocAnchor: hostEntry.docAnchor,
     protocolVersion: PROTOCOL_VERSION,
     // Same facts as `_link/hello`, which is the channel the app actually uses:
@@ -134,7 +137,7 @@ export function statusSnapshot(agent) {
       relayLocked: Boolean(realConfiguredRelay),
       command: agent.needsEnroll ? agent.enrollHint() : null,
       hint: agent.needsEnroll
-        ? '这台电脑还没有登记到中转。在「移动端连接」面板里确认中转地址，然后点「登记」。'
+        ? T('status.unregistered')
         : null,
     },
     state: agent.state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-link",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Put your PC's DeepSeek Harness in your pocket: dials a relay over WSS so the native iOS client reaches this machine even without a public IP.",
   "keywords": [
     "dsh",