dsh-plugin-mobile-gateway 0.10.2 → 0.10.3

package/PROTOCOL.md

@@ -1,6 +1,8 @@
 # dsh Mobile Gateway — WebSocket 协议参考
 
-移动端通过经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现。当前源码适配 DSH 0.2.0-rc.2 / Session format 4；移动端实时流接入见 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md)，插件管理见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+移动端通过经过设备鉴权的 WebSocket 连接与 dsh 通信：订阅 agent 实时输出、发送文字和图片、处理 Human-in-the-loop 提问与操作审批、查询会话/工作区/历史、调整会话配置。本协议由持久化插件 `dsh-plugin-mobile-gateway` 实现。当前源码适配 DSH 0.2.1-rc.2 / Session format 4；移动端实时流接入见 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md)，插件管理见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+
+DSH Remote 要求的 `peer` 由网关在 Host 内部创建并注入，身份沿用已配对设备的本机用户权限，生命周期随插件释放；移动端请求帧不增加 `peer` 字段，`dsh-mobile-v1` 协议不变。
 
 - **本机端点**：`ws://127.0.0.1:3080/ws/mobile`（与 dsh web GUI 同端口）
 - **局域网端点**：`ws://<电脑的私有局域网 IP>:3081/ws/mobile`（插件独立监听，只提供经过鉴权的 WebSocket）
@@ -1175,7 +1177,8 @@ DSH Web 的“深度求索中，用时 22 秒 ···”是客户端文案，不
 
 | 版本 | 新增 |
 |---|---|
-| v0.10.2（当前源码） | 补齐 `deliverables/presented` 文件卡片实时字段；新增 `file-references-v1` 能力与 `file-resolve` 安全文件引用解析；复用现有分块下载支持移动端预览接入 |
+| v0.10.3（当前源码） | 适配 DSH 0.2.1-rc.2；为 Remote 请求及实时订阅补齐 Connection Peer，修复读取 `signal` 时的空值报错，并随网关停止释放 Peer；移动端协议保持不变 |
+| v0.10.2 | 补齐 `deliverables/presented` 文件卡片实时字段；新增 `file-references-v1` 能力与 `file-resolve` 安全文件引用解析；复用现有分块下载支持移动端预览接入 |
 | v0.10.1 | 新增官方 speech Remote 语音输入桥接；模型准备与状态同步；移动端音频转文字与取消转写；连接关闭时清理语音任务 |
 | v0.10.0 | 响应式居中控制面板与主题同步；自定义下拉菜单；独立配对模态窗口与缩放动画；按运行实例关闭重启提醒；在线设备折叠列表与移动端设备名称上报；Tunnel 配置交互优化 |
 | v0.9.0 | DSH 0.2.0-rc.2 插件管理；PC 端 Cloudflare Quick / 命名 Tunnel 及独立重启；插件私有 `cloudflared` 缓存及校验；配对入口选择指引；网关重启与 DSH Web 停止工具 |

package/README.md

@@ -6,11 +6,13 @@
 
 DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排队消息同步及编辑/删除/Steer、Session 归档和重命名的双向同步、停止当前生成并稍后继续、任务列表和当前 Goal 同步及管理、服务端驱动的命令和技能菜单、Human-in-the-loop、图片及文件传输。安装后，Harness WebUI 左侧边栏会出现“移动设备”入口，可直接开启网关、生成配对二维码和管理可信设备。
 
-> 当前源码以 **DSH 0.2.0-rc.2** 为适配基线，使用 Session format 4；旧版历史游标需重新取得基线。
+> 当前源码以 **DSH 0.2.1-rc.2** 为适配基线，需要 Connection Peer 接口，使用 Session format 4；旧版历史游标需重新取得基线。
 >
 > 实时流已改为独立 `assistant-stream` 帧，移动端需要按 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md) 更新订阅、缓存与分页处理。当前修改尚未发布。
 >
-> v0.10.2（当前源码）：新增文件卡片事件透传与安全文件引用解析，复用现有分块下载，为移动端文件卡片和正文文件链接预览提供协议支持。App 接入方式见 [文件卡片与预览接入说明](docs/file-cards-mobile-integration.md)。
+> v0.10.3（当前源码）：适配 DSH 0.2.1-rc.2，为 Remote 请求及实时订阅补齐 Connection Peer，修复 `Cannot read properties of undefined (reading 'signal')` 报错，并在网关停止时释放 Peer。移动端协议保持不变。
+>
+> v0.10.2：新增文件卡片事件透传与安全文件引用解析，复用现有分块下载，为移动端文件卡片和正文文件链接预览提供协议支持。App 接入方式见 [文件卡片与预览接入说明](docs/file-cards-mobile-integration.md)。
 >
 > v0.10.1：新增官方语音输入接入，支持语音模型准备与状态同步、移动端音频转文字、取消转写及连接关闭后的任务清理。通过官方 speech Remote 处理识别，移动网关无需打包 ASR 模型。
 >
@@ -24,7 +26,15 @@ DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排
 
 ## 协议与 DSH 兼容层
 
-移动端连接的是本项目维护的 `dsh-mobile-v1`，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH 0.2.0-rc.2 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals、Schedule、Permission Presets、Plugin Manager 等 namespace 和严格参数只存在于该适配层。插件管理的请求帧及 DSH Mobile 页面方案见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+移动端连接的是本项目维护的 `dsh-mobile-v1`，不是 DSH 的内部 Remote 协议。插件内部通过独立 Host Adapter 对接 DSH 0.2.1-rc.2 的 Remote Gateway；Session、Workspace、Settings、Commands、Goals、Schedule、Permission Presets、Plugin Manager 等 namespace 和严格参数只存在于该适配层。插件管理的请求帧及 DSH Mobile 页面方案见 [RC2 插件管理对接方案](docs/dsh-0.2.0-rc.2-plugin-management-mobile-integration.md)。
+
+DSH 0.2.1-rc.2 要求每次 Remote 调用携带 `peer`。网关通过 `ctx.connection.createPeer()` 创建一个随插件释放的本机用户 Peer，普通请求、首帧读取和实时订阅都由 Host Adapter 注入它；移动端不能设置调用方身份。问答与审批继续由网关的 Host 监听器处理。旧网关漏传此字段时会出现 `Cannot read properties of undefined (reading 'signal')`，升级 DSH 后需重新安装本源码版本并重启 `dsh web`，手机无需更改协议。
+
+可用本机已安装的官方 DSH 验证此契约（真实 Gateway / Connection，业务服务使用测试数据，不读写用户会话）：
+
+```bash
+DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/host-official.test.mjs
+```
 
 配对鉴权和 `dsh-mobile-v1` / `hello.protocol = 3` 保持不变。新版实时 token 不占用持久事件的 `seq`：客户端显式订阅 `assistantStream: true`，接收原子的 `session-snapshot` 和独立增量；普通 `event` 只携带持久事件。未接入新订阅的客户端只能收到持久消息。
 

package/lib/dsh-host-adapter.mjs

@@ -13,7 +13,7 @@ function requireArray(value, endpoint) {
   return value
 }
 
-export const DSH_VERSION = '0.2.0-rc.2'
+export const DSH_VERSION = '0.2.1-rc.2'
 export const SESSION_FORMAT_VERSION = 4
 
 export function readHistoryRecords(records) {
@@ -44,12 +44,12 @@ export function readSessionSnapshot(frame, sessionId) {
   }
 }
 
-async function firstStreamFrame(gateway, namespace, method, args, signal) {
+async function firstStreamFrame(stream, namespace, method, args, signal) {
   const ownedAbort = new AbortController()
   const streamSignal = signal ? AbortSignal.any([signal, ownedAbort.signal]) : ownedAbort.signal
   let iterator
   try {
-    const iterable = await gateway.stream({ namespace, method, args, signal: streamSignal })
+    const iterable = await stream(namespace, method, args, streamSignal)
     const iteratorFactory = iterable?.[Symbol.asyncIterator] ?? iterable?.[Symbol.iterator]
     if (typeof iteratorFactory !== 'function') throw new Error(`${namespace}/${method} returned an invalid stream`)
     iterator = iteratorFactory.call(iterable)
@@ -78,21 +78,28 @@ function sessionListArgs(request) {
  * descriptors. Its public methods intentionally match mobile-gateway domain
  * operations, not the upstream transport envelope.
  */
-export function createDshHostAdapter(typertGateway) {
+export function createDshHostAdapter(typertGateway, peer) {
   if (!typertGateway || typeof typertGateway.invoke !== 'function' || typeof typertGateway.stream !== 'function') {
     throw new Error('mobile-gateway requires the DSH Remote Gateway host service')
   }
+  if (!peer || !(peer.signal instanceof AbortSignal)) {
+    throw new Error('mobile-gateway requires a DSH Connection Peer (DSH 0.2.1-rc.2 or later)')
+  }
 
   const invoke = (namespace, method, args, signal) => typertGateway.invoke({
     namespace,
     method,
     args,
+    peer,
     ...(signal === undefined ? {} : { signal }),
   })
+  const stream = (namespace, method, args, signal) => typertGateway.stream({
+    namespace, method, args, peer, signal,
+  })
 
   const sessionSnapshot = async (request, signal) => {
     const frame = requireRecord(await firstStreamFrame(
-      typertGateway,
+      stream,
       'session',
       'follow',
       requestArgs(request),
@@ -200,7 +207,7 @@ export function createDshHostAdapter(typertGateway) {
   return {
     speech: {
       catalog: (signal) => invoke('speech', 'catalog', {}, signal),
-      follow: (signal) => typertGateway.stream({ namespace: 'speech', method: 'follow', args: {}, signal }),
+      follow: (signal) => stream('speech', 'follow', {}, signal),
       configure: (patch, signal) => invoke('speech', 'configure', { patch }, signal),
       prepare: (providerId, options, signal) => invoke('speech', 'prepare', {
         providerId, ...(options === undefined ? {} : { options }),
@@ -248,7 +255,7 @@ export function createDshHostAdapter(typertGateway) {
     },
     workspace: {
       async list(_payload = {}, signal) {
-        const frame = requireRecord(await firstStreamFrame(typertGateway, 'workspace', 'follow', {}, signal), 'workspace/follow')
+        const frame = requireRecord(await firstStreamFrame(stream, 'workspace', 'follow', {}, signal), 'workspace/follow')
         if (frame.type !== 'baseline') throw new Error('workspace/follow returned an invalid opening baseline')
         return requireRecord(frame.value, 'workspace/follow baseline')
       },
@@ -371,18 +378,17 @@ export function createDshHostAdapter(typertGateway) {
       if (event.type === 'turn/start') admittedPrompts.delete(sessionId)
     },
     openSessionStream(sessionId, signal) {
-      return typertGateway.stream({
-        namespace: 'session', method: 'follow',
+      return stream('session', 'follow',
         // Bound the opening window at the Host; older records remain available via session.page.
-        args: requestArgs({ address: { kind: 'session', sessionId }, maxMessages: 12, assistantStream: true }),
+        requestArgs({ address: { kind: 'session', sessionId }, maxMessages: 12, assistantStream: true }),
         signal,
-      })
+      )
     },
     openControlStream(signal) {
-      return typertGateway.stream({ namespace: 'session', method: 'control', args: {}, signal })
+      return stream('session', 'control', {}, signal)
     },
     openWorkspaceStream(signal) {
-      return typertGateway.stream({ namespace: 'workspace', method: 'follow', args: {}, signal })
+      return stream('workspace', 'follow', {}, signal)
     },
   }
 }

package/lib/index.mjs

@@ -2193,13 +2193,19 @@ const plugin = {
   // Hard dependencies: the gateway registers on the host web server and
   // admits mobile messages through the Host Remote Gateway. Cordis must not
   // activate this row before either service exists.
-  inject: ['webServer', 'typertGateway', 'agentDefaultModel'],
+  inject: ['webServer', 'typertGateway', 'connection', 'agentDefaultModel'],
   // exported for local tests; Cordis ignores unknown plugin fields
   admitMessage,
   handleQuery,
   apply(ctx, config) {
     const webServer = ctx.webServer
-    const api = createDshHostAdapter(ctx.typertGateway)
+    if (typeof ctx.connection?.createPeer !== 'function') {
+      throw new Error('mobile-gateway requires DSH 0.2.1-rc.2 or later with Connection.createPeer')
+    }
+    // 已配对设备沿用本机用户权限；身份只由 Host 创建，不能由移动端参数指定。
+    // 问答与审批仍由本插件的 Host 监听器处理，无需另开 Remote 交互流。
+    const peer = ctx.connection.createPeer({ principal: { kind: 'owner' }, interactions: 'none' })
+    const api = createDshHostAdapter(ctx.typertGateway, peer)
     const host = api
     const agentDefaultModel = ctx.agentDefaultModel
     const options = {
@@ -3471,6 +3477,9 @@ const plugin = {
       if (waitTimer) clearTimeout(waitTimer)
       clearInterval(fileTransferExpiryTimer)
       backgroundStreamAbort.abort()
+      peer.dispose().catch((error) => {
+        log(`Host peer disposal failed: ${error && error.message ? error.message : String(error)}`)
+      })
       speechInput.dispose()
       for (const pending of [...pendingQuestions.values()]) fallbackQuestion(pending)
       for (const pending of [...pendingApprovals.values()]) fallbackApproval(pending)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.10.2",
-  "description": "DeepSeek Harness 移动网关，支持安全设备配对、实时会话同步、插件管理、官方语音输入、局域网及 Cloudflare Tunnel，以及自适应深浅色控制面板。0.10.2 新增文件卡片事件透传与安全文件引用解析，复用分块下载为移动端文件卡片和正文文件链接预览提供协议支持。",
+  "version": "0.10.3",
+  "description": "DeepSeek Harness 移动网关，支持安全设备配对、实时会话同步、插件管理、官方语音输入、文件卡片与安全文件预览、局域网及 Cloudflare Tunnel，以及自适应深浅色控制面板。0.10.3 适配 DSH 0.2.1-rc.2，为 Remote 请求及实时订阅补齐 Connection Peer，修复读取 signal 时的空值报错，并在网关停止时释放 Peer。",
   "main": "lib/index.mjs",
   "files": [
     "bin",