dsh-plugin-mobile-link 0.3.1 → 0.4.0

package/lib/index.js

@@ -43,7 +43,6 @@ const DEFAULTS = {
   agentSecret: '',
   stateFile: '',
   dshUrl: '',
-  endpointFile: '',
   inviteCode: '',
   heartbeatMs: 20000,
   pongTimeoutMs: 60000,
@@ -56,15 +55,34 @@ function asRecord(value) {
   return value !== null && typeof value === 'object' ? value : {}
 }
 
+/**
+ * 当前宿主属于哪一种形态。**只看进程自己的证据，不看继承来的环境变量**：
+ *   - 官方桌面版：入口脚本是私有的 `dsh-desktop-host`，可执行文件在应用包里
+ *     （它用 Electron 当 Node 跑）；
+ *   - 其余把本插件加载进宿主进程的情况都是命令行 web 版。
+ *
+ * 为什么不能用 `ELECTRON_RUN_AS_NODE` 这类环境变量：从桌面版里启动的 `dsh web`
+ * （例如 agent 在桌面版宿主下敲命令）会**继承**它，于是把一个 web 宿主误判成桌面版。
+ * 这个错误由 2026-10-07 的慢闸实测抓到。
+ *
+ * 形状契约见 `specs/001-connector-host-compat/data-model.md` §1。
+ *
+ * @param {{argv?: string[], execPath?: string}} [context]
+ * @returns {'desktop' | 'web'}
+ */
+export function detectHostForm({ argv = process.argv, execPath = process.execPath } = {}) {
+  if (/dsh-desktop-host/.test(argv[1] ?? '')) return 'desktop'
+  if (/DeepSeek Harness\.app|dsh-desktop-host/.test(execPath)) return 'desktop'
+  return 'web'
+}
+
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
  * @param {Record<string, unknown>} rawConfig
  */
-export function apply(ctx, rawConfig) {
-  const config = { ...DEFAULTS, ...asRecord(rawConfig) }
-  const logger = ctx.logger ?? console
-
-  const agent = new MobileLinkAgent({
+/** 构造 agent：把配置逐字段钳制成 agent 认的类型。 */
+function buildAgent(config, logger) {
+  return new MobileLinkAgent({
     enabled: config.enabled !== false,
     relayUrl: typeof config.relayUrl === 'string' ? config.relayUrl : DEFAULTS.relayUrl,
     agentId: typeof config.agentId === 'string' ? config.agentId : '',
@@ -74,15 +92,18 @@ export function apply(ctx, rawConfig) {
     // otherwise the agent reads DSH_MOBILE_LINK_INVITE (see enroll.js).
     inviteCode: typeof config.inviteCode === 'string' && config.inviteCode ? config.inviteCode : undefined,
     dshUrl: typeof config.dshUrl === 'string' && config.dshUrl ? config.dshUrl : undefined,
-    endpointFile: typeof config.endpointFile === 'string' && config.endpointFile ? config.endpointFile : undefined,
     heartbeatMs: Number(config.heartbeatMs) || DEFAULTS.heartbeatMs,
     pongTimeoutMs: Number(config.pongTimeoutMs) || DEFAULTS.pongTimeoutMs,
     maxBackoffMs: Number(config.maxBackoffMs) || DEFAULTS.maxBackoffMs,
     logger,
   })
+}
 
+/** 启动/停止 agent 的生命周期 effect。 */
+function startAgent(ctx, agent, logger) {
   ctx.effect(() => {
     let disposed = false
+    agent.setHostForm(detectHostForm())
     agent.emit('status')
     agent.start().catch((error) => {
       if (!disposed) logger.warn?.(`mobile-link: start failed: ${error}`)
@@ -92,9 +113,10 @@ export function apply(ctx, rawConfig) {
       void agent.stop().catch(() => {})
     }
   }, 'mobile-link: DLP agent')
+}
 
-  // Routes ride on DSH's web server when that service exists. `ctx.inject`
-  // scopes them without making the service a hard requirement for the agent.
+/** 三条本机 HTTP 路由；只依赖 `webServer`，缺了也不影响链路。 */
+function registerRoutes(ctx, agent, logger, config) {
   try {
     ctx.inject(['webServer'], (scope) => {
       const disposers = registerMobileLinkRoutes(scope, { agent, logger, config })
@@ -112,17 +134,49 @@ export function apply(ctx, rawConfig) {
   } catch (error) {
     logger.warn?.(`mobile-link: routes unavailable (the link itself keeps running): ${error}`)
   }
+}
+
+/**
+ * 进程内发现（本特性的核心）：宿主把"当前带凭据的回环地址"交给我们。
+ *
+ * 必须声明注入（`ctx.inject(['webServer','connection'])`）——`ctx.get('connection')` 在插件
+ * 作用域里取不到，官方桌面版与 web 版都一样（实测）。与路由分开注入：`connection` 缺失时
+ * 路由照常注册，agent 也照常跑。
+ */
+function wireEndpointResolver(ctx, agent, logger) {
+  try {
+    ctx.inject(['webServer', 'connection'], (scope) => {
+      agent.setHostService(() => scope.connection.authenticatedUrl(`http://127.0.0.1:${scope.webServer.port}`))
+      logger.info?.('mobile-link: in-process endpoint resolver ready')
+    })
+  } catch (error) {
+    logger.warn?.(`mobile-link: in-process endpoint resolver unavailable: ${error}`)
+  }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, unknown>} rawConfig
+ */
+export function apply(ctx, rawConfig) {
+  const config = { ...DEFAULTS, ...asRecord(rawConfig) }
+  const logger = ctx.logger ?? console
+  const agent = buildAgent(config, logger)
 
+  startAgent(ctx, agent, logger)
+  registerRoutes(ctx, agent, logger, config)
+  wireEndpointResolver(ctx, agent, logger)
   logger.info?.(`mobile-link: ready (relay ${config.relayUrl})`)
 }
 
 export { MobileLinkAgent } from './link.js'
-export { DshClient, discoverEndpoint, DshUnavailable } from './dsh-client.js'
+export { DshClient, discoverEndpoint, discoverCandidates, DshUnavailable } from './dsh-client.js'
+export { writeHandoff, handoffFromEndpoint } from './handoff.js'
 export {
   MAX_FRAME_BYTES, StreamTable, WaterfallDedupe, agentEndpoint, decodeFrame, encodeFrame,
   joinRelayPath, nextBackoff, normalizeRelayUrl, pairCodeEndpoint, qrPayload,
 } from './dlp.js'
-export { resolveIdentity, defaultStatePath, defaultEndpointFile, MissingIdentity } from './state.js'
+export { resolveIdentity, defaultStatePath, defaultHandoffFile, MissingIdentity } from './state.js'
 export { enrollAgent, enrollPlan, enrollCommand, describeEnrollFailure } from './enroll.js'
 export { INVITE_ENV, DEFAULT_AGENT_NAME } from './state.js'
 export { qrMatrix, qrSvg, versionFor } from './qr.js'

package/lib/link.js

@@ -9,9 +9,11 @@ import { EventEmitter } from 'node:events'
 import { DshClient } from './dsh-client.js'
 import { agentEndpoint, decodeFrame, encodeFrame, nextBackoff, normalizeRelayUrl, pongFor } from './dlp.js'
 import { enrollAgent, enrollCommand, inviteFrom } from './enroll.js'
+import { handoffFromEndpoint, writeHandoff } from './handoff.js'
+import { statusSnapshot } from './status.js'
 import { mintPairCode } from './pairing.js'
 import {
-  DEFAULT_EVENTS_BACKLOG, DEFAULT_EVENTS_GRACE_MS,
+  DEFAULT_EVENTS_BACKLOG,
   EVENTS_ENDPOINT, EVENTS_RESULT, DeviceRouter, messageOf,
 } from './router.js'
 import { SERVER_VERSION, SERVER_CAPABILITIES } from './hello.js'
@@ -20,6 +22,7 @@ import { connect as wsConnect } from './ws.js'
 
 const PROTOCOL_VERSION = 1
 
+
 function sleep(ms, signal) {
   return new Promise((resolve) => {
     const timer = setTimeout(resolve, ms)
@@ -40,18 +43,16 @@ function numberFromEnv(raw, fallback) {
 
 export class MobileLinkAgent extends EventEmitter {
   constructor({
-    relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, endpointFile,
+    relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl,
     logger = console, heartbeatMs = 20000, pongTimeoutMs = 60000, maxBackoffMs = 30000,
     random = Math.random, now = Date.now, dshClient, connectImpl = wsConnect, enabled = true,
     inviteCode, fetchImpl = fetch, env = process.env,
-    // 「手机不在时替它留着 $events 流」的宽限期与缓冲上限（见 router.js 的说明）；
-    // 环境变量给部署用，构造参数给测试用。
-    eventsGraceMs = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_GRACE_MS, DEFAULT_EVENTS_GRACE_MS),
+    // 手机不在时替它攒下来的提问条数上限（见 router.js）；环境变量给部署用，
+    // 构造参数给测试用。**没有"留多久"这个旋钮**：`$events` 一直留到设备被撤销。
     eventsBacklog = numberFromEnv(env.DSH_MOBILE_LINK_EVENTS_BACKLOG, DEFAULT_EVENTS_BACKLOG),
-    setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout,
   } = {}) {
     super()
-    this.config = { relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, endpointFile, inviteCode }
+    this.config = { relayUrl, agentId, agentSecret, agentName, stateFile, dshUrl, inviteCode }
     this.logger = logger
     this.heartbeatMs = heartbeatMs
     this.pongTimeoutMs = pongTimeoutMs
@@ -65,21 +66,25 @@ export class MobileLinkAgent extends EventEmitter {
     //: Set when this computer has no identity yet: a setup problem for a person
     //: to fix, not a transport problem to retry.
     this.needsEnroll = false
-    this.dsh = dshClient ?? new DshClient({ endpointFile, explicitUrl: dshUrl, logger })
+    this.dsh = dshClient ?? new DshClient({ explicitUrl: dshUrl, logger })
     this.router = new DeviceRouter({
       dsh: this.dsh,
       logger,
       now,
       protocolVersion: PROTOCOL_VERSION,
-      eventsGraceMs,
       eventsBacklog,
-      setTimeoutFn,
-      clearTimeoutFn,
       send: (deviceId, frame) => this.sendToDevice(deviceId, frame),
+      // 「跑完了 / 待你回应」到了就报一声（`{t:'notify'}`）。这是 agent 侧控制帧，
+      // **不带 deviceId**：连接器不知道、也不需要知道这台电脑配了哪些手机，
+      // 「该不该推给某台手机」由中转判（它手里才有"这台设备此刻在不在线"）。
+      // `#rawSend` 自己处理"socket 不在就丢掉"，这里不必另判。
+      notify: (payload) => this.#rawSend({ t: 'notify', ...payload }),
       onChange: () => this.emit('status'),
     })
 
     this.identity = undefined
+    /** Which host form we are running in (`desktop` / `web` / `unknown`); set by the plugin. */
+    this.hostForm = 'unknown'
     this.relay = undefined
     this.socket = undefined
     this.state = 'idle'
@@ -122,6 +127,70 @@ export class MobileLinkAgent extends EventEmitter {
     return this.lastError ?? this.router.lastError
   }
 
+  /**
+   * Wire the in-process resolver the plugin learned from `ctx.inject`.
+   *
+   * Only the plugin can obtain it (it needs `webServer` + `connection`), and it
+   * arrives asynchronously, so this is a setter rather than a constructor option.
+   *
+   * @param {(() => string | undefined) | undefined} resolver
+   */
+  setHostService(resolver) {
+    if (typeof this.dsh?.setHostService === 'function') this.dsh.setHostService(resolver)
+    // 解析器一到就试一次本机发现：交接文件服务的是"进程外工具"，**与中转链路无关**，
+    // 因此不能只在连上中转之后才写（未登记的机器上那样永远写不出来）。
+    if (typeof resolver === 'function') void this.refreshLocal()
+    return this
+  }
+
+  /**
+   * 与中转无关的本机发现：拿到带凭据地址就刷新交接文件。
+   *
+   * 这是 `/mobile-link/status` 与"进程外工具能不能工作"的共同前提，所以它在
+   * 链路还没建立（甚至没登记）时也要跑。失败只记进 `dshError`，不影响链路。
+   */
+  async refreshLocal() {
+    try {
+      await this.dsh.refresh()
+      this.dshError = undefined
+      await this.#writeHandoff()
+      this.emit('status')
+      return this.dsh.endpoint
+    } catch (error) {
+      this.dshError = messageOf(error)
+      this.emit('status')
+      return undefined
+    }
+  }
+
+  /**
+   * Record which host form we are in, so the status payload can tell the user
+   * which installation instructions apply to this machine.
+   *
+   * @param {'desktop' | 'web' | 'unknown'} form
+   */
+  setHostForm(form) {
+    this.hostForm = form === 'desktop' || form === 'web' ? form : 'unknown'
+    this.emit('status')
+    return this
+  }
+
+  /**
+   * Publish the current authenticated loopback address for out-of-process tools
+   * (our dev/test scripts and the iOS test helpers).
+   *
+   * Best effort: a failed write must never take the link down.
+   */
+  async #writeHandoff() {
+    const payload = handoffFromEndpoint(this.dsh?.endpoint)
+    if (!payload) return
+    try {
+      await writeHandoff(payload)
+    } catch (error) {
+      this.logger.debug?.(`mobile-link: handoff file not written: ${messageOf(error)}`)
+    }
+  }
+
   // ── lifecycle ───────────────────────────────────────────────────────────
 
   async start() {
@@ -135,6 +204,8 @@ export class MobileLinkAgent extends EventEmitter {
     this._abort = new AbortController()
     this.startedAt = this.now()
     this.state = 'connecting'
+    // 解析器可能在上一次会话里就已经装好；这里补一次本机发现（失败无妨）。
+    void this.refreshLocal()
     this._loop = this.#run().catch((error) => {
       this.lastError = messageOf(error)
       this.state = 'failed'
@@ -275,6 +346,9 @@ export class MobileLinkAgent extends EventEmitter {
     try {
       await this.dsh.refresh()
       this.dshError = undefined
+      // 进程外工具（本机脚本、iOS 集成测试辅助）靠这份交接文件拿带凭据地址；
+      // 写入失败不影响链路（`#writeHandoff` 自己吞异常）。
+      await this.#writeHandoff()
     } catch (error) {
       this.dshError = messageOf(error)
       this.lastError = this.dshError
@@ -345,6 +419,9 @@ export class MobileLinkAgent extends EventEmitter {
   }
 
   sendToDevice(deviceId, frame) {
+    // `deviceId` 为空＝这是一条**不带寻址**的帧（`fsPutAck`/`fsPutDone`/`fsErr` 那一族）：
+    // relay 靠 `bid` 把回复对回发起的那个 HTTP 请求，多一个 deviceId 反而会让它对不上。
+    if (deviceId === undefined || deviceId === null) return this.#rawSend(frame)
     return this.#rawSend({ ...frame, deviceId })
   }
 
@@ -407,51 +484,9 @@ export class MobileLinkAgent extends EventEmitter {
     return mintPairCode({ identity, ttlMs, fetchImpl })
   }
 
-  /** Snapshot for `GET /mobile-link/status`. */
+  /** Snapshot for `GET /mobile-link/status`（载荷本身在 status.js，便于守住"只增不改"）。 */
   status() {
-    return {
-      ok: true,
-      enabled: this.enabled !== false,
-      protocolVersion: PROTOCOL_VERSION,
-      // Same facts as `_link/hello`, which is the channel the app actually
-      // uses: this route only exists on the direct path.
-      serverVersion: SERVER_VERSION,
-      capabilities: SERVER_CAPABILITIES,
-      enroll: {
-        // A phone (or the user's browser) can read this to find out that the
-        // computer half is installed but not yet registered, and what to run.
-        registered: !this.needsEnroll,
-        needsEnroll: this.needsEnroll,
-        stateFile: this.identity?.stateFile ?? this.config.stateFile ?? null,
-        relayUrl: this.config.relayUrl ?? null,
-        command: this.needsEnroll ? this.enrollHint() : null,
-        hint: this.needsEnroll
-          ? '这台电脑还没有登记到中转。请带上邀请码运行一次登记命令，然后重启 DSH。'
-          : null,
-      },
-      state: this.state,
-      connected: this.state === 'connected',
-      relayUrl: this.identity?.relayUrl ?? this.config.relayUrl ?? null,
-      agentId: this.identity?.agentId ?? this.config.agentId ?? null,
-      agentName: this.identity?.agentName ?? null,
-      stateFile: this.identity?.stateFile ?? this.config.stateFile ?? null,
-      dsh: {
-        endpoint: this.dsh?.endpoint?.base ?? null,
-        source: this.dsh?.endpoint?.source ?? null,
-        port: this.dsh?.endpoint?.port ?? null,
-        authenticated: Boolean(this.dsh?.cookie),
-        muxUp: Boolean(this.dsh?.muxReady),
-        error: this.dshError ?? null,
-      },
-      devices: this.router.snapshot(),
-      deviceCount: this.devices.size,
-      openStreams: this.streams.size,
-      pendingWaterfalls: this.dedupe.size,
-      lastError: this.failure ?? null,
-      startedAt: this.startedAt ?? null,
-      connectedAt: this.connectedAt ?? null,
-      reconnectAttempts: this.reconnectAttempts,
-    }
+    return statusSnapshot(this)
   }
 }
 

package/lib/pairing.js

@@ -1,6 +1,6 @@
 /**
  * Pairing helper: ask the relay to mint a one-time code and build the QR
- * payload the desktop shows. Spec §2.1 plus relay/NOTES.md §2 (the endpoint the
+ * payload the desktop shows. Spec §2.1 plus docs/RELAY-NOTES.md §2 (the endpoint the
  * spec's table is missing).
  */