dsh-plugin-mobile-gateway 0.11.0 → 0.11.1

package/PROTOCOL.md

@@ -866,6 +866,38 @@ DSH `present` 工具成功后持久化 `deliverables/presented`，移动端根
 - 默认每块为 512 KiB、同时最多 4 个下载、单个文件最多 512 MiB。部署方可用 `fileDownloadChunkBytes`、`fileDownloadMaxTransfers`、`fileDownloadMaxBytes`、`fileDownloadIdleMs` 调整；`fileDownloadsEnabled: false` 会关闭该能力，且 `hello.capabilities` 不再包含 `file-downloads`。
 - 绝对路径、空路径（`file-download-open`）、`..` 路径段、NUL 字符、工作目录外的符号链接、目录和其他非普通文件都会被拒绝。`file-list` 不返回符号链接，避免客户端误认为其可下载。
 
+### 普通文件上传
+
+已配对连接在启用 `fileUploadsEnabled` 时公布 `file-upload-v1`。上传请求走 control 连接（兼容 legacy），消息走 conversation 连接（兼容 legacy）。普通文件按原始字节进入官方附件存储，取得会话专属 `receiptId`，不接受客户端指定的主机路径。自定义 Host 未组合官方文件上传服务时返回 `file-upload-unavailable`。
+
+| type | 必填参数 | 成功 kind |
+|---|---|---|
+| `file-upload-open` | `requestId`, `sessionId`, `name`, `size`, `sha256` | `file-upload-opened` |
+| `file-upload-chunk` | `requestId`, `uploadId`, `offset`, `data` | `file-upload-chunk-accepted` |
+| `file-upload-finish` | `requestId`, `uploadId` | `file-upload-completed` |
+| `file-upload-cancel` | `requestId`, `uploadId` | `file-upload-cancelled` |
+
+`requestId` 为 1 至 128 字符的非空字符串，所有上传响应和错误均回显。`sessionId` 必须是已有普通会话；新草稿先使用 `session-create`，子智能体暂不支持文件附件。`name` 只允许不带目录和控制字符的 1 至 255 字符文件名。`size` 为非负安全整数，`sha256` 是完整原始字节的 64 位十六进制摘要，允许空文件。
+
+`file-upload-opened` 返回 `uploadId/sessionId/name/size/chunkBytes/maxBytes/idleTimeoutMs`。chunk 使用标准 Base64，`offset` 按解码字节计数，必须等于当前已确认位置；每次等待 `file-upload-chunk-accepted.nextOffset` 后再发下一块，不支持分块流水线或跨连接续传。finish 校验长度和 SHA-256 后通过官方流式接口提交：
+
+```json
+{ "kind": "file-upload-completed", "requestId": "finish-1", "uploadId": "upload-uuid", "sessionId": "s1",
+  "receiptId": "host-receipt-uuid", "sha256": "<64 位十六进制摘要>",
+  "file": { "attachmentId": "opaque-file-id", "name": "报告.pdf", "bytes": 1234 } }
+
+{ "type": "message", "requestId": "submission-uuid", "sessionId": "s1", "text": "分析这个报告",
+  "files": [{ "receiptId": "host-receipt-uuid" }], "mode": "queue" }
+```
+
+含文件消息必须有 `requestId`，会原样传给 Host 用于相同提交的重试去重。`files` 最多 20 项，不允许重复凭证；可以纯文件发送或与已有图片、文字混合。Host 校验凭证所属的准确 Session，并将其转换为原生 file 内容块；上传完成不会自动发送消息。
+
+实时 `user/message` 新增 `event.files: [{attachmentId,name,bytes}]`；历史 `data.content[]` 保留 `{type:"file",attachment:{attachmentId,name,bytes}}`。附件 ID 不等于工作区路径，现有图片 `attachment` 和工作区 `file-download-*` 不能用于按此 ID 下载文件。
+
+默认单文件 512 MiB、每块 256 KiB、全网关最多 4 个活动上传、空闲 2 分钟、Host 提交超时 180 秒。可配置 `fileUploadMaxBytes/fileUploadChunkBytes/fileUploadMaxTransfers/fileUploadIdleMs/fileUploadCommitTimeoutMs`，实际分块上限还受 `maxPayloadBytes` 限制。上传开关独立于下载开关。
+
+uploadId 仅归属创建它的 socket；取消、断线、空闲超时和网关停止会清理网关暂存并中止活动提交。原连接可在短期完成缓存内重试 finish 取得同一结果，缓存最多 128 条、默认保留 2 分钟；不提供断点续传或 Host 附件回滚删除。更完整的官方 WebUI 源码对应关系、JSON 示例、错误表、App 状态机和验收步骤见 [移动端普通文件上传对接指南](docs/file-upload-app-integration.md)。
+
 ### `session-stats` 详细（输入框统计条）
 ```json
 { "type": "session-stats", "sessionId": "session-abc" }
@@ -1155,7 +1187,7 @@ Control/旧单连接接收全局模式状态增量，不受所订阅会话过滤
   "event": { "type": "assistant/message", "turn": 1, "step": 0, "text": "已完成", "reasoning": "", "toolCalls": [] } }
 ```
 `event.type` 覆盖（精炼字段）：
-- `user/message` → `{text, source, images?: ImageAttachmentRef[]}`
+- `user/message` → `{text, source, images?: ImageAttachmentRef[], files?: [{attachmentId,name,bytes}]}`
 - 实时 token 使用独立 `assistant-stream`，不是带持久 seq 的 `assistant/chunk`；详见 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md)。
 - `assistant/attempt` → `{turn, step, stream[], finish?: {kind, failure?}}`
 - `assistant/message` → `{turn, step, text, reasoning, toolCalls[], interrupted?, usage?, finish?: {kind, failure?}}`

package/README.md

@@ -10,7 +10,9 @@ DeepSeek Harness 的设备鉴权移动网关，支持会话与实时事件、排
 >
 > 实时流已改为独立 `assistant-stream` 帧，移动端需要按 [rc.2 接入说明](docs/dsh-rc2-mobile-integration.md) 更新订阅、缓存与分页处理。当前修改尚未发布。
 >
-> v0.11.0（当前源码，尚未发布）：新增智能体团队与子会话协议，支持团队成员、共享任务看板、多层子智能体目录和运行状态实时同步，以及子智能体独立历史、视图切换、继续对话、图片输入与停止执行。APP 需按能力发现接入，详见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)。
+> v0.11.1（当前源码，尚未发布）：新增普通文件分块上传，支持 SHA-256 校验、进度确认、取消与断线清理，复用 DSH 官方附件存储和会话专属凭证，支持文件随消息发送及实时和历史文件引用。App 需按 `file-upload-v1` 能力接入，详见 [移动端普通文件上传对接指南](docs/file-upload-app-integration.md)。
+>
+> v0.11.0：新增智能体团队与子会话协议，支持团队成员、共享任务看板、多层子智能体目录和运行状态实时同步，以及子智能体独立历史、视图切换、继续对话、图片输入与停止执行。APP 需按能力发现接入，详见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)。
 >
 > v0.10.4：精简会话列表投影，仅保留标题与投影切点，修复大量会话通过公网隧道传输时超时的问题；保留会话元信息和历史完整投影，现有移动客户端无需配套修改。
 >
@@ -54,6 +56,8 @@ DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/host-official.test
 
 当前源码新增 `turn-outline-v1`：透传 WebUI 使用的完整轮次大纲及实时更新，支持 App 在未加载全部正文时展示会话刻度、问答预览并按需分页跳转。控制连接重建和新设备连接会恢复大纲基线；Host 未提供大纲时可降级为已加载轮次导航。详见 [App 会话轮次导航接入指南](docs/turn-outline-app-integration.md)。App 界面需单独接入，本次源码尚未发布。
 
+当前源码新增 `file-upload-v1`：已配对移动端可通过控制连接分块上传 PDF、Office、压缩包、音频等普通文件，校验 SHA-256 后存入 DSH 官方附件存储，再以会话专属凭证随消息发送。支持进度确认、取消、断线清理及实时/历史文件引用；复用官方 WebUI 的附件准入，不写入客户端指定的主机路径。帧示例、App 状态机、限制及验收见 [移动端普通文件上传对接指南](docs/file-upload-app-integration.md)。App 页面需单独接入，本次源码尚未发布。
+
 当前源码新增 `agent-team-v1`、`subagent-conversations-v1`：支持团队成员与共享任务板查询、各层子智能体目录、团队投影和成员运行状态实时同步，以及子会话独立历史、订阅、继续对话与停止执行。APP 的目标地址、完整 JSON 示例、看板规则、切换与重连状态机、错误处理和验收清单见 [智能体团队 APP 详细接入指南](docs/agent-team-app-integration.md)。本次只提供网关能力，APP 页面需单独接入，源码尚未发布。
 
 ## 多网关第一阶段（当前源码）

package/docs/file-upload-app-integration.md

@@ -0,0 +1,250 @@
+# 移动端普通文件上传对接指南
+
+## 功能与接入前提
+
+网关通过 `file-upload-v1` 支持 PDF、Office 文档、压缩包、音频及其他普通文件上传。文件先由网关分块接收和校验，再通过 DSH 官方流式接口进入附件存储，得到会话专属的上传凭证；App 随后把凭证与文字一起发送。文件不会被写到用户指定的工作区路径，也不会仅以文字路径代替附件。
+
+基线为 DSH 0.2.1-rc.2、`dsh-mobile-v1`、`hello.protocol: 3`、Session format 4。App 必须已完成设备配对。新增能力只在 `fileUploadsEnabled: true` 的已配对连接中公布；Host 还需组合官方文件上传服务和支持文件流式存储的附件后端。能力声明表示网关协议可用，实际 Host 不提供上传服务时返回 `file-upload-unavailable`。
+
+本功能提供上传、原生附件消息和历史引用。文件内容能否被 Agent 解析，仍取决于 DSH 的工具、技能和文件类型；上传 PDF 不等于模型直接获得 PDF 模态输入。图片继续使用原有 `images` 协议，语音转文字继续使用 `speech-transcribe`。
+
+## 官方 WebUI 的实现方式
+
+源码基于本机安装的 DSH 0.2.1-rc.2：
+
+| 官方模块与入口 | 行为 | App 对应实现 |
+|---|---|---|
+| `dsh-client-ui-conversation` 的 `beginFileUpload` | 创建可取消任务，维护 `uploading/ready/error`，上传成功保存 `receiptId/file` | 共享层保存每个草稿附件的状态、进度和凭证 |
+| 同模块的 `pumpFileUploads` | 按并发限制调度，不一次启动全部上传 | 客户端使用有界上传队列 |
+| 同模块的 `sendSession` | 非图片附件必须为 ready，发送 `{type:"file", receiptId}` | 等所有文件获得完成响应后再发送消息 |
+| `dsh-client-file-upload` 的 `ctx.fileUpload.upload` | Blob 经 Worker/XHR 上传并报告进度；stream 经 Worker/Fetch 传输；精确字节可走 Remote | 移动端改走现有已鉴权 WebSocket 的分块协议 |
+| 官方 Host 路由 `/api/session/uploadFileBinary` | 接收原始二进制流，返回 Session 专属凭证与持久附件引用 | 网关在进程内通过 Connection 路由注册表和固定 owner Peer 调用，不要求手机访问此 HTTP 路由 |
+| 官方 `SessionCommandController.prompt` | 校验同 Session 的凭证，转成原生 file 内容块，再进入 inbox | App 发送网关 `message.files`，不提交任意 `attachmentId` 或主机路径 |
+
+WebUI 切换 Session 时会为携带的文件重新上传和绑定。发送失败时保留草稿，成功后再清理。上传和消息发送是两个独立步骤，上传成功不会自动唤醒 Agent。凭证绑定精确的 Session 实例；Host 处理成功消息后会退休凭证，不能把它当作永久附件 ID。
+
+## 推荐流程与状态
+
+1. 检查 `hello.capabilities` 包含 `file-upload-v1`，并保留当前 `gatewayId` 和连接代际。
+2. 新草稿尚无会话时，先用已有 `session-create` 创建空白普通 Session。上传请求必须指定现有 `sessionId`，不能自动创建会话，也不支持子智能体会话。
+3. 系统选择器取得文件后，复制到 App 私有草稿目录。后台流式计算字节长度和 SHA-256；不要把文件全部读入内存。上传期间固定这份副本，不能改用可能变化的外部文件。
+4. 控制连接发送 open，按返回的 `chunkBytes` 逐块编码、发送并等待确认。
+5. 所有字节确认后发送 finish。UI 显示“处理中”，直到收到 `file-upload-completed`，才能标记为 ready。
+6. 对话连接发送 `message`，包含原始文字、可选图片和所有 ready 文件的 `receiptId`。没有文字的纯文件消息也可发送。
+7. 收到 `sent` 后清理对应草稿；实时和历史渲染使用持久 `file` 引用。发送失败保留草稿，根据错误决定重试还是重新上传。
+
+建议状态为：`preparing → opening → uploading → committing → ready → sending → sent`。各阶段允许进入 `error`；未完成上传可进入 `cancelling → cancelled`。每个草稿附件应有本地稳定 ID，并记录其所属网关、会话、连接代际、uploadId、字节数、摘要、已确认偏移、receiptId 和 file 引用。
+
+## 通道与请求关联
+
+上传的四类请求使用 **control 连接**，兼容 legacy 单连接。`message` 使用 **conversation 连接**，同样兼容 legacy 单连接。文件上传与消息发送可以位于两条不同连接，上传凭证由同一 Host 的目标 Session 校验。
+
+所有上传请求必须带 1 至 128 字符的非空 `requestId`，响应和错误回显。建议每次 RPC 使用新的 UUID；消息发送的 requestId 则固定为该次提交的 UUID，重试同一次提交时保持不变。`uploadId` 仅标识传输，不代替 requestId。
+
+上传中的 uploadId 只属于创建它的 WebSocket；即使另一个 socket 属于同一设备，也不能继续写入或取消。切换网关、Session 或连接代际后，不得把旧回调应用到新草稿。
+
+## 协议帧
+
+### 开始上传
+
+```json
+{
+  "type": "file-upload-open",
+  "requestId": "open-1",
+  "sessionId": "s1",
+  "name": "分析报告.pdf",
+  "size": 7,
+  "sha256": "7d1a54127b222502f5b79b5fb0803061152a44f92b37e23c6527baf665d4da9a"
+}
+```
+
+上例摘要对应 ASCII 内容 `abcdefg`，size 为解码后的精确字节数。摘要为 64 位十六进制，大小写均可；响应规范化为小写。允许零字节文件，使用空文件摘要，open 后直接 finish。
+
+```json
+{
+  "kind": "file-upload-opened",
+  "requestId": "open-1",
+  "uploadId": "upload-uuid",
+  "sessionId": "s1",
+  "name": "分析报告.pdf",
+  "size": 7,
+  "chunkBytes": 262144,
+  "maxBytes": 536870912,
+  "idleTimeoutMs": 120000
+}
+```
+
+`name` 仅为显示文件名，最多 255 个 UTF-16 code unit，不得包含目录分隔符、控制字符、NUL，也不能是 `.` 或 `..`。不要发送移动端完整路径。Host 仍会对最终文件名做清理，后续展示以完成响应中的 `file.name` 为准。
+
+不传 `path`、`cwd`、`parentSessionId` 或 `subagentMode`。通用文件不做扩展名白名单，字节原样存储，不执行、不解压。传输大小使用 64 位整数，并保证落在 JSON 安全整数范围；不要用字符串替代数值。
+
+### 发送分块
+
+```json
+{
+  "type": "file-upload-chunk",
+  "requestId": "chunk-1",
+  "uploadId": "upload-uuid",
+  "offset": 0,
+  "data": "YWJjZGVmZw=="
+}
+```
+
+```json
+{
+  "kind": "file-upload-chunk-accepted",
+  "requestId": "chunk-1",
+  "uploadId": "upload-uuid",
+  "sessionId": "s1",
+  "nextOffset": 7
+}
+```
+
+- `offset` 按解码后的字节计数，必须等于网关当前已接收字节数。下一块必须使用确认帧的 `nextOffset`。
+- 每块为非空、标准带 padding 的 Base64，不带 data URL 前缀、空白或换行。每块独立编码，不能按字符直接切割整文件 Base64。
+- 每个 uploadId 同时只进行一项操作，采用“发一块、等确认、再发下一块”。不同文件可以在服务端并发限制内并行。
+- `chunkBytes` 为解码后的块上限，会同时受 WebSocket payload 配置约束；不能硬编码为 256 KiB。最后一块可以更短。
+- 界面进度根据已确认字节数计算，不使用客户端已发出的 Base64 长度。100% 字节已传输仍须等待 finish 完成。
+
+### 校验并提交
+
+```json
+{ "type": "file-upload-finish", "requestId": "finish-1", "uploadId": "upload-uuid" }
+```
+
+```json
+{
+  "kind": "file-upload-completed",
+  "requestId": "finish-1",
+  "uploadId": "upload-uuid",
+  "sessionId": "s1",
+  "receiptId": "host-receipt-uuid",
+  "file": {
+    "attachmentId": "sha256:7d1a54127b222502f5b79b5fb0803061152a44f92b37e23c6527baf665d4da9a",
+    "name": "分析报告.pdf",
+    "bytes": 7
+  },
+  "sha256": "7d1a54127b222502f5b79b5fb0803061152a44f92b37e23c6527baf665d4da9a"
+}
+```
+
+网关先校验接收长度与摘要，再流式交给官方附件存储。只有 Host 返回合法凭证后才发送完成响应，并删除网关私有暂存文件。`attachmentId` 是不透明持久引用，即使当前带 `sha256:` 前缀，也不要依赖其字符串结构；`receiptId` 是发送新消息所需的会话权限凭证，两者不可互换。
+
+完成结果在原连接上短暂缓存，默认最多 2 分钟，且全网关最多保留 128 条，较早结果可能被逐出。同一连接再次发送相同 uploadId 的 finish，可以取得相同凭证，不重复创建 Host 上传。它不是跨连接断点续传，也不是永久查询接口。
+
+### 取消
+
+```json
+{ "type": "file-upload-cancel", "requestId": "cancel-1", "uploadId": "upload-uuid" }
+```
+
+```json
+{ "kind": "file-upload-cancelled", "requestId": "cancel-1", "uploadId": "upload-uuid", "sessionId": "s1" }
+```
+
+取消会中止接收或正在执行的 Host 提交，等待操作退出，再释放临时文件和并发名额；被取消的活动请求可能同时返回 `file-upload-cancelled` 错误，App 需按各自 requestId 结算。取消已完成的上传不会删除 Host 持久附件。提交与取消竞争时，Host 可能已经完成存储，因此不能承诺取消能回滚已落盘的附件。
+
+## 发送文件消息
+
+```json
+{
+  "type": "message",
+  "requestId": "submission-uuid",
+  "sessionId": "s1",
+  "text": "帮我分析这个报告",
+  "files": [{ "receiptId": "host-receipt-uuid" }],
+  "mode": "queue"
+}
+```
+
+```json
+{ "kind": "sent", "requestId": "submission-uuid", "sessionId": "s1", "mode": "queue" }
+```
+
+`files` 最多 20 项，不允许重复凭证；每项只需 `receiptId`。网关不会采信客户端提供的主机路径或持久 attachmentId。含文件消息必须有已存在的普通 sessionId 和 1 至 128 字符的 requestId。`text` 可省略，可同时携带已有 `images`，`mode` 可为 `queue` 或 `steer`。当前移动协议组装顺序为图片、文件、文字，不表达图片与文件任意交错排序。
+
+网关将文件项转成官方 `{type:"file", receiptId}`。Host 校验该凭证属于当前 Session，准入后转换为 `{type:"file", attachment}` 并处理凭证生命周期；跨 Session、伪造或已退休凭证返回 `session/attachment-invalid`。
+
+含文件消息的 requestId 会原样传给 Host。消息回执丢失但连接可恢复时，用同一个 requestId 重试完全相同的提交，Host 可根据 inbox 或已记录用户消息去重。不要给同一 ID 换正文，也不要在不明确是否送达时用新 ID 自动重复发送。Host 重启或 Session 实例替换后应先核对队列和原始历史中的 `source.rpcId`，凭证可能已失效。
+
+上传成功、消息发送失败时保留草稿；普通可恢复错误可重试原提交，凭证失效则重新上传。切换 Session 必须重新上传并取得新凭证，不能把旧会话凭证携带过去。关闭后重新打开 App 时，也不要仅凭数据库存过 receiptId 就判定文件 ready，应重新校验草稿所属连接与 Host 状态，必要时重新上传。
+
+## 实时消息与历史渲染
+
+持久用户消息的实时帧新增可选 `event.files`：
+
+```json
+{
+  "kind": "event", "sessionId": "s1", "seq": 42, "time": 1000,
+  "event": {
+    "type": "user/message", "text": "帮我分析这个报告", "source": "user",
+    "files": [{ "attachmentId": "opaque-file-id", "name": "分析报告.pdf", "bytes": 7 }]
+  }
+}
+```
+
+`history` 与 `session-snapshot` 保留原生 `{type,seq,time,data}` 结构，文件位于 `user/message.data.content[]` 的 `{type:"file",attachment:{attachmentId,name,bytes}}`。App reducer 必须识别 file 块，不能因未知类型丢掉整条纯文件消息；实时和历史按网关、会话、格式版本及 seq 合并，得到相同的附件卡片。
+
+推荐保存附件名称、字节数和持久引用，不在消息表内存储大段 Base64。发送设备可继续使用其私有草稿副本进行本地预览；在确认消息已入历史、无需重试后，再按缓存策略释放副本。
+
+本次不增加按 file attachmentId 下载附件的接口。已有 `attachment` 是图片读取接口，`file-download-*` 只读取会话工作目录中的文件，不能把 attachmentId 当路径传给它们。Host 附件存储可以在工作区之外；其他设备即使看见附件卡片，也不能据此假定已有远程预览链路。已有 `deliverables/presented` 文件卡片和本地文件链接仍按原下载协议处理。
+
+## 失败处理与资源生命周期
+
+错误帧为 `kind:"error"`，带 `requestType/requestId/code/message`，并在请求提供时带 sessionId 或 uploadId。错误文案用于显示，分支判断使用 code。
+
+| code | 处理方式 |
+|---|---|
+| `authentication-required` / `wrong-channel` | 检查设备配对和通道；即使调试关闭普通鉴权，也不能匿名上传或发送文件凭证 |
+| `file-upload-disabled` / `file-upload-unavailable` | 关闭当前上传入口或提示管理员检查配置；不可退回上传任意路径 |
+| `bad-request` / `session-not-found` / `subagent/attachment-invalid` | 修正文件名、请求字段或会话目标，子会话不提供此入口 |
+| `file-too-large` | 在选择阶段或 open 失败后提示大小上限，不自动反复上传 |
+| `file-upload-limit` / `file-upload-busy` | 降低并发，等待前一请求完成；不要同时发多个 chunk 或 finish |
+| `file-upload-offset` / `file-upload-invalid-data` / `file-upload-size` | 修正偏移、Base64 和长度；chunk 不是幂等请求，回执状态不明时取消并从头重传 |
+| `file-upload-incomplete` | 补齐剩余块后再 finish；当前已接收字节仍保留 |
+| `file-upload-checksum` | 当前传输已销毁，从固定本地副本重新计算后完整重传 |
+| `file-upload-not-found` / `file-upload-cancelled` | 传输属于其他连接、已取消、已过期或已结束；重新 open，不能从旧偏移续传 |
+| `file-upload-timeout` / `file-upload-failed` / `file-upload-invalid-response` / 文件系统错误码 | 当前操作可能失败；finish 的失败会清理传输，保留本地副本，提示重试；磁盘问题应先处理空间或权限 |
+| `session/attachment-invalid` | Host 不支持文件存储或凭证不属于该 Session、已失效；检查 Host 错误消息并视情况重新上传 |
+
+传输只在当前进程和 socket 内有效，不支持断线、重启后断点续传。socket 关闭或网关停止时中止活动上传并删除网关暂存；空闲传输由定时扫描回收，实际回收可晚于 idleTimeoutMs 一个扫描周期。提交阶段有独立超时，且同一传输的取消、写入和清理串行协调。
+
+finish 失败或取消时，官方附件存储可能已接收部分或全部内容；网关只保证清理自身暂存，不操作 Host 附件 GC。进程被强制杀死时，系统临时目录可能残留 `dsh-mobile-upload-*`，它们不是可恢复传输。
+
+## 网关配置
+
+| 配置 | 默认值 | 作用 |
+|---|---|---|
+| `fileUploadsEnabled` | `true` | 关闭后不公布上传能力，拒绝上传和含文件消息 |
+| `fileUploadMaxBytes` | 512 MiB | 单文件解码后大小上限 |
+| `fileUploadChunkBytes` | 256 KiB | 单块解码后字节上限，实际值还受 maxPayloadBytes 约束 |
+| `fileUploadMaxTransfers` | 4 | 全网关活动上传上限，包含尚未完成的 open 与 Host 提交 |
+| `fileUploadIdleMs` | 120000 | 空闲传输和完成结果缓存的保留时间 |
+| `fileUploadCommitTimeoutMs` | 180000 | 会话查询和 Host 附件提交的单次超时 |
+
+上传开关与 `fileDownloadsEnabled` 独立。手机只需现有 `/ws/mobile` 可达，Cloudflare Quick、命名 Tunnel 和 LAN 入口无需新增 HTTP 路由。网关为每个活动上传使用私有暂存目录，磁盘预算需考虑并发数乘单文件上限，以及官方存储提交时可能同时存在的副本。
+
+## App 实施顺序与验收
+
+KMM 共享层新增上传 DTO、按 requestId 分发的请求协调器、草稿附件 reducer 和有界队列；平台层负责系统文件选择、私有副本、后台摘要计算和文件流读取，UI 订阅共享状态。不要在主线程做文件复制、SHA-256 或 Base64 编码，也不要把每块数据长期存进状态流。
+
+Android 可使用系统文档选择器和 ContentResolver 流，iOS 可使用文档选择器并在授权访问期间复制到私有目录；两端都应保留原始显示文件名、真实字节长度，以及可重新读取的草稿副本。UI 展示“上传中、处理中、可发送、失败重试、取消”，移除附件时主动取消活动上传。
+
+客户端验收应包含：
+
+- PDF、Word、ZIP、音频及含 NUL 的二进制数据上传后与原始 SHA-256 一致；零字节文件可完成。
+- 超限文件、目录路径文件名、错误摘要、错误偏移和非法 Base64 得到可处理错误。
+- 纯文件、文件加文字、图片加文件加文字均能发送；历史恢复与实时消息展示一致。
+- 切 Session、切网关、断线和取消时旧任务不能污染新草稿；另一个 socket 不能操作原 uploadId。
+- 跨 Session 凭证被 Host 拒绝；同一次消息重试沿用 requestId，不重复进入队列。
+- finish 回执丢失时可在原连接缓存有效期内重试；其余未知进度情况从头重传。
+- 最多并发上传数、空闲回收、磁盘写入失败和 Host 取消不会留下仍占用的传输名额。
+- 上传成功不会自动发送给 Agent；App 必须等用户执行发送。
+
+自动验证入口：`npm test` 包含上传单元测试和真实 WebSocket 的鉴权、通道分流、上传到消息与实时文件引用测试。可选官方契约测试使用实际 DSH 流式路由、附件存储、凭证解析及 prompt 准入，所有数据位于测试临时目录：
+
+```bash
+DSH_INSTALL_ROOT=/absolute/path/to/@deepseek-ai/dsh node test/file-upload-official.test.mjs
+```
+
+代码入口：[上传管理器](../lib/file-upload.mjs)、[Host Adapter](../lib/dsh-host-adapter.mjs)、[消息与 WebSocket 接入](../lib/index.mjs)。这次不修改 App 页面，也不发布 npm；客户端完成后还需在设备上验证文件选择、后台编码、进度、取消和卡片展示。

package/lib/dsh-host-adapter.mjs

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto'
 import os from 'node:os'
+import { Readable } from 'node:stream'
 import { sessionAddress } from './session-target.mjs'
 
 function requireRecord(value, endpoint) {
@@ -79,7 +80,7 @@ function sessionListArgs(request) {
  * descriptors. Its public methods intentionally match mobile-gateway domain
  * operations, not the upstream transport envelope.
  */
-export function createDshHostAdapter(typertGateway, peer) {
+export function createDshHostAdapter(typertGateway, peer, connection) {
   if (!typertGateway || typeof typertGateway.invoke !== 'function' || typeof typertGateway.stream !== 'function') {
     throw new Error('mobile-gateway requires the DSH Remote Gateway host service')
   }
@@ -97,6 +98,11 @@ export function createDshHostAdapter(typertGateway, peer) {
   const stream = (namespace, method, args, signal) => typertGateway.stream({
     namespace, method, args, peer, signal,
   })
+  // Dispatch in-process through the official authenticated route; no loopback
+  // HTTP listener, browser cookie, or public /api exposure is required.
+  const uploadHandler = connection?.createSharedFetchHandler?.('/api')
+  const uploadUrl = new URL('http://localhost/api/session/uploadFileBinary')
+  const uploadsAvailable = () => uploadHandler?.requestBodyMode({ method: 'POST', url: uploadUrl }) === 'streaming'
 
   const sessionSnapshot = async (request, signal) => {
     const frame = requireRecord(await firstStreamFrame(
@@ -207,6 +213,33 @@ export function createDshHostAdapter(typertGateway, peer) {
   }
 
   return {
+    files: {
+      available: uploadsAvailable,
+      async upload({ sessionId, name, data }, signal) {
+        if (!uploadsAvailable()) throw Object.assign(new Error('The official file upload service is unavailable'), { code: 'file-upload-unavailable' })
+        const url = new URL(uploadUrl)
+        url.searchParams.set('sessionId', sessionId)
+        url.searchParams.set('name', name)
+        const uploadSignal = signal ? AbortSignal.any([signal, peer.signal]) : peer.signal
+        uploadSignal.throwIfAborted()
+        const source = Readable.from(data, { objectMode: false })
+        try {
+          const response = await uploadHandler.fetch(new Request(url, {
+            method: 'POST', headers: { 'content-type': 'application/octet-stream' },
+            body: Readable.toWeb(source), duplex: 'half',
+            signal: uploadSignal,
+          }), peer)
+          if (!response.ok) throw Object.assign(new Error(`Official file upload returned HTTP ${response.status}`), { code: 'file-upload-unavailable' })
+          const result = await response.json()
+          if (result.ok !== true) throw Object.assign(new Error(result.error?.message || 'Official file upload failed'),
+            { code: result.error?.code || 'file-upload-failed' })
+          return requireRecord(result.value, 'file upload')
+        } catch (error) {
+          uploadSignal.throwIfAborted()
+          throw error
+        } finally { source.destroy() }
+      },
+    },
     speech: {
       catalog: (signal) => invoke('speech', 'catalog', {}, signal),
       follow: (signal) => stream('speech', 'follow', {}, signal),

package/lib/file-upload.mjs

@@ -0,0 +1,205 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+export const FILE_UPLOAD_REQUEST_TYPES = new Set([
+  'file-upload-open', 'file-upload-chunk', 'file-upload-finish', 'file-upload-cancel',
+])
+export const FILE_UPLOAD_DEFAULTS = Object.freeze({
+  fileUploadsEnabled: true,
+  fileUploadMaxBytes: 512 * 1024 * 1024,
+  fileUploadChunkBytes: 256 * 1024,
+  fileUploadMaxTransfers: 4,
+  fileUploadIdleMs: 2 * 60 * 1000,
+  fileUploadCommitTimeoutMs: 180_000,
+})
+
+function failure(code, message) { return Object.assign(new Error(message), { code }) }
+function check(condition, code, message) { if (!condition) throw failure(code, message) }
+function validName(name) {
+  return typeof name === 'string' && name.trim().length > 0 && name.length <= 255
+    && name !== '.' && name !== '..' && !/[\x00-\x1f\x7f/\\]/.test(name)
+}
+
+// Receive bounded chunks in a private spool, verify exact bytes, then use DSH's
+// streaming attachment admission. Never interpret client names as host paths.
+export function createFileUploadManager(api, configuration = {}) {
+  const options = { ...FILE_UPLOAD_DEFAULTS, ...configuration }
+  const payloadLimit = Math.max(0, Math.floor(((options.maxPayloadBytes ?? 144 * 1024 * 1024) - 4096) / 4) * 3)
+  const chunkBytes = Math.min(options.fileUploadChunkBytes, payloadLimit)
+  const transfers = new Map()
+  const completed = new Map()
+  const closedClients = new WeakSet()
+  let disposed = false
+
+  const cleanup = async transfer => {
+    if (transfer.handle) {
+      await transfer.handle.close().catch(() => {})
+      transfer.handle = undefined
+    }
+    if (transfer.directory) await fsp.rm(transfer.directory, { recursive: true, force: true })
+  }
+  const release = async transfer => {
+    try { await cleanup(transfer) } finally { transfers.delete(transfer.id) }
+  }
+  const stop = async transfer => {
+    transfer.abort.abort(failure('file-upload-cancelled', 'File upload cancelled'))
+    // Keep the slot reserved until its writes/Host commit have actually stopped.
+    await transfer.operation?.catch(() => {})
+    await release(transfer)
+  }
+  const assertActive = transfer => {
+    transfer.abort.signal.throwIfAborted()
+    check(!disposed && !closedClients.has(transfer.client), 'file-upload-cancelled', 'Upload connection closed')
+  }
+  const run = (transfer, task) => {
+    check(!transfer.operation, 'file-upload-busy', 'An upload operation is already in progress')
+    const operation = task()
+    transfer.operation = operation
+    return operation.finally(() => { if (transfer.operation === operation) transfer.operation = undefined })
+  }
+
+  const open = async (client, msg) => {
+    check(!disposed && !closedClients.has(client), 'file-upload-cancelled', 'Upload connection closed')
+    check(api.files?.available(), 'file-upload-unavailable', 'The official file upload service is unavailable')
+    check(typeof msg.sessionId === 'string' && msg.sessionId.trim(), 'bad-request', 'An existing sessionId is required')
+    check(msg.parentSessionId === undefined && msg.subagentMode === undefined, 'subagent/attachment-invalid', 'Subagent file uploads are unsupported')
+    check(validName(msg.name), 'bad-request', 'name must be a leaf filename of 1..255 characters without control characters')
+    check(Number.isSafeInteger(msg.size) && msg.size >= 0, 'bad-request', 'size must be a nonnegative safe integer')
+    check(msg.size <= options.fileUploadMaxBytes, 'file-too-large', 'File exceeds the configured upload limit')
+    check(typeof msg.sha256 === 'string' && /^[a-fA-F0-9]{64}$/.test(msg.sha256), 'bad-request', 'sha256 must contain 64 hexadecimal digits')
+    check(transfers.size < options.fileUploadMaxTransfers, 'file-upload-limit', 'Too many active uploads')
+    const transfer = {
+      id: crypto.randomUUID(), client, sessionId: msg.sessionId.trim(), name: msg.name,
+      size: msg.size, sha256: msg.sha256.toLowerCase(), offset: 0, hash: crypto.createHash('sha256'),
+      abort: new AbortController(), lastActiveAt: Date.now(),
+    }
+    transfers.set(transfer.id, transfer)
+    try {
+      return await run(transfer, async () => {
+        const sessions = await api.sessions.list({}, AbortSignal.any([
+          transfer.abort.signal, AbortSignal.timeout(options.fileUploadCommitTimeoutMs),
+        ]))
+        check(sessions.items?.some(item => item.sessionId === transfer.sessionId && item.origin !== 'subagent'),
+          'session-not-found', 'No visible ordinary session exists with this ID')
+        assertActive(transfer)
+        transfer.directory = await fsp.mkdtemp(path.join(os.tmpdir(), 'dsh-mobile-upload-'))
+        transfer.path = path.join(transfer.directory, 'payload')
+        transfer.handle = await fsp.open(transfer.path, 'wx', 0o600)
+        assertActive(transfer)
+        return { kind: 'file-upload-opened', uploadId: transfer.id, sessionId: transfer.sessionId,
+          name: transfer.name, size: transfer.size, chunkBytes, maxBytes: options.fileUploadMaxBytes,
+          idleTimeoutMs: options.fileUploadIdleMs }
+      })
+    } catch (error) {
+      await release(transfer)
+      throw error
+    }
+  }
+
+  const receive = async (client, msg) => {
+    if (msg.type === 'file-upload-open') return open(client, msg)
+    check(typeof msg.uploadId === 'string' && msg.uploadId.length > 0, 'bad-request', 'uploadId is required')
+    const done = completed.get(msg.uploadId)
+    if (done?.client === client && msg.type === 'file-upload-finish') return done.frame
+    const transfer = transfers.get(msg.uploadId)
+    check(transfer?.client === client, 'file-upload-not-found', 'Upload is unknown or belongs to another connection')
+    if (msg.type === 'file-upload-cancel') {
+      await stop(transfer)
+      return { kind: 'file-upload-cancelled', uploadId: msg.uploadId, sessionId: transfer.sessionId }
+    }
+    assertActive(transfer)
+    return run(transfer, async () => {
+      transfer.lastActiveAt = Date.now()
+      if (msg.type === 'file-upload-chunk') {
+        check(Number.isSafeInteger(msg.offset) && msg.offset === transfer.offset,
+          'file-upload-offset', 'offset must equal the next expected byte')
+        check(typeof msg.data === 'string' && msg.data.length > 0 && msg.data.length <= Math.ceil(chunkBytes / 3) * 4,
+          'file-upload-invalid-data', 'Chunk must be nonempty canonical base64 within chunkBytes')
+        const bytes = Buffer.from(msg.data, 'base64')
+        check(bytes.length > 0 && bytes.length <= chunkBytes && bytes.toString('base64') === msg.data,
+          'file-upload-invalid-data', 'Chunk must be nonempty canonical base64 within chunkBytes')
+        check(transfer.offset + bytes.length <= transfer.size, 'file-upload-size', 'Chunk exceeds declared size')
+        try {
+          let written = 0
+          while (written < bytes.length) {
+            assertActive(transfer)
+            const result = await transfer.handle.write(bytes, written, bytes.length - written, transfer.offset + written)
+            check(result.bytesWritten > 0, 'file-upload-write-failed', 'Upload write made no progress')
+            written += result.bytesWritten
+          }
+        } catch (error) {
+          transfer.abort.abort(error)
+          await release(transfer)
+          throw error
+        }
+        assertActive(transfer)
+        transfer.hash.update(bytes)
+        transfer.offset += bytes.length
+        return { kind: 'file-upload-chunk-accepted', uploadId: transfer.id, sessionId: transfer.sessionId, nextOffset: transfer.offset }
+      }
+      check(transfer.offset === transfer.size, 'file-upload-incomplete', 'Not all declared bytes have arrived')
+      try {
+        check(transfer.hash.digest('hex') === transfer.sha256, 'file-upload-checksum', 'SHA-256 does not match the uploaded bytes')
+        await transfer.handle.close()
+        transfer.handle = undefined
+        const signal = AbortSignal.any([transfer.abort.signal, AbortSignal.timeout(options.fileUploadCommitTimeoutMs)])
+        const result = await api.files.upload({ sessionId: transfer.sessionId, name: transfer.name,
+          data: fs.createReadStream(transfer.path, { highWaterMark: chunkBytes }) }, signal)
+        signal.throwIfAborted()
+        assertActive(transfer)
+        check(typeof result.receiptId === 'string' && result.receiptId.length > 0
+          && typeof result.file?.attachmentId === 'string' && result.file.attachmentId.length > 0
+          && typeof result.file.name === 'string' && result.file.bytes === transfer.size,
+        'file-upload-invalid-response', 'Official upload result does not match the declared file')
+        const frame = { kind: 'file-upload-completed', uploadId: transfer.id, sessionId: transfer.sessionId,
+          receiptId: result.receiptId, file: { attachmentId: result.file.attachmentId, name: result.file.name, bytes: result.file.bytes },
+          sha256: transfer.sha256 }
+        completed.set(transfer.id, { client, frame, lastActiveAt: Date.now() })
+        if (completed.size > 128) completed.delete(completed.keys().next().value)
+        return frame
+      } finally {
+        await release(transfer)
+      }
+    })
+  }
+
+  return {
+    async handle(client, msg) {
+      const correlation = {
+        ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}),
+        ...(typeof msg.sessionId === 'string' ? { sessionId: msg.sessionId } : {}),
+        ...(typeof msg.uploadId === 'string' ? { uploadId: msg.uploadId } : {}),
+      }
+      try {
+        check(options.fileUploadsEnabled, 'file-upload-disabled', 'File uploads are disabled')
+        check(typeof msg.requestId === 'string' && msg.requestId.trim().length > 0 && msg.requestId.length <= 128,
+          'bad-request', 'requestId must contain 1..128 characters')
+        const frame = await receive(client, msg)
+        return { ...frame, requestId: msg.requestId }
+      } catch (error) {
+        return { kind: 'error', requestType: msg.type, ...correlation,
+          code: error.name === 'TimeoutError' ? 'file-upload-timeout'
+            : typeof error.code === 'string' ? error.code : 'file-upload-failed',
+          message: error.message || 'File upload failed' }
+      }
+    },
+    async closeClient(client) {
+      closedClients.add(client)
+      await Promise.all([...transfers.values()].filter(transfer => transfer.client === client).map(stop))
+      for (const [id, done] of completed) if (done.client === client) completed.delete(id)
+    },
+    async expire() {
+      const cutoff = Date.now() - options.fileUploadIdleMs
+      await Promise.all([...transfers.values()].filter(transfer => !transfer.operation && transfer.lastActiveAt < cutoff).map(stop))
+      for (const [id, done] of completed) if (done.lastActiveAt < cutoff) completed.delete(id)
+    },
+    async dispose() {
+      disposed = true
+      await Promise.all([...transfers.values()].map(stop))
+      completed.clear()
+    },
+  }
+}

package/lib/index.mjs

@@ -21,7 +21,7 @@ import { assistantFinish, failureDetails, toolResultDetails, turnReasonDetails }
 //                     { "type": "subscribe", "sessionId": "..." }  (optional filter)
 //                     { "type": "unsubscribe" }
 //                     { "type": "message", "sessionId"?, "text"?, "images"?:
-//                       [{ "mediaType", "data", "name"? }], "mode"?: "queue"|"steer",
+//                       [{ "mediaType", "data", "name"? }], "files"?: [{ "receiptId" }], "mode"?: "queue"|"steer",
 //                       "workspaceId"?, "cwd"?, "clientTimeZone"? }
 //                        sessionId omitted -> a new session is created first; the
 //                        new session can be placed in a workspace via workspaceId
@@ -100,6 +100,10 @@ import { assistantFinish, failureDetails, toolResultDetails, turnReasonDetails }
 //                       "path", "name", "mediaType", "size", "chunkBytes" }
 //                     { "kind": "file-download-chunk", "transferId", "offset", "data", "eof", "sha256"? }
 //                     { "kind": "file-download-cancelled", "transferId" }
+//                     { "kind": "file-upload-opened", "requestId", "uploadId", "sessionId", "name", "size", "chunkBytes", "maxBytes", "idleTimeoutMs" }
+//                     { "kind": "file-upload-chunk-accepted", "requestId", "uploadId", "sessionId", "nextOffset" }
+//                     { "kind": "file-upload-completed", "requestId", "uploadId", "sessionId", "receiptId", "file", "sha256" }
+//                     { "kind": "file-upload-cancelled", "requestId", "uploadId", "sessionId" }
 //                     { "kind": "session-cancelled", "sessionId", "accepted": true }
 //                     { "kind": "queue-item-updated", "sessionId", "itemId", "action", "accepted": true }
 //                     { "kind": "session-queues", "queues": { "<sessionId>": [...] } }
@@ -137,6 +141,7 @@ import { WebSocketServer } from 'ws'
 import devicesModule from './devices.js'
 import { createDshHostAdapter, DSH_VERSION, SESSION_FORMAT_VERSION } from './dsh-host-adapter.mjs'
 import { createSpeechInputManager, SPEECH_REQUEST_TYPES } from './speech-input.mjs'
+import { createFileUploadManager, FILE_UPLOAD_REQUEST_TYPES, FILE_UPLOAD_DEFAULTS } from './file-upload.mjs'
 import { handlePluginQuery, PLUGIN_REQUEST_TYPES } from './plugin-management.mjs'
 import { createSessionFollower } from './session-follower.mjs'
 import { parseSessionTarget, TEAM_PROJECTION_KINDS } from './session-target.mjs'
@@ -227,6 +232,12 @@ const Config = Schema.object({
   fileDownloadChunkBytes: Schema.natural().min(64 * 1024).max(1024 * 1024).default(DEFAULT_FILE_DOWNLOAD_CHUNK_BYTES),
   fileDownloadIdleMs: Schema.natural().min(10_000).max(30 * 60 * 1000).default(DEFAULT_FILE_DOWNLOAD_IDLE_MS),
   fileDownloadMaxTransfers: Schema.natural().min(1).max(16).default(DEFAULT_FILE_DOWNLOAD_MAX_TRANSFERS),
+  fileUploadsEnabled: Schema.boolean().default(FILE_UPLOAD_DEFAULTS.fileUploadsEnabled),
+  fileUploadMaxBytes: Schema.natural().min(1024 * 1024).max(2 * 1024 * 1024 * 1024).default(FILE_UPLOAD_DEFAULTS.fileUploadMaxBytes),
+  fileUploadChunkBytes: Schema.natural().min(64 * 1024).max(1024 * 1024).default(FILE_UPLOAD_DEFAULTS.fileUploadChunkBytes),
+  fileUploadMaxTransfers: Schema.natural().min(1).max(16).default(FILE_UPLOAD_DEFAULTS.fileUploadMaxTransfers),
+  fileUploadIdleMs: Schema.natural().min(10_000).max(30 * 60 * 1000).default(FILE_UPLOAD_DEFAULTS.fileUploadIdleMs),
+  fileUploadCommitTimeoutMs: Schema.natural().min(10_000).max(30 * 60 * 1000).default(FILE_UPLOAD_DEFAULTS.fileUploadCommitTimeoutMs),
   adminLoopbackOnly: Schema.boolean().default(true),
   publicUrl: Schema.string().default(''),
   deviceFile: Schema.string().default(''),
@@ -278,6 +289,12 @@ function imagesOf(blocks) {
   return images
 }
 
+function filesOf(blocks) {
+  return blocks.filter(block => block?.type === 'file' && block.attachment).map(({ attachment }) => ({
+    attachmentId: attachment.attachmentId, name: attachment.name, bytes: attachment.bytes,
+  }))
+}
+
 // Build the small, owned JSON wire record for one session event. Reads only
 // leaf fields of the live SessionEvent — never serializes live objects.
 function buildWireEvent(session, event) {
@@ -289,6 +306,7 @@ function buildWireEvent(session, event) {
   switch (event.type) {
     case 'user/message': {
       const images = imagesOf(d.content || [])
+      const files = filesOf(d.content || [])
       return Object.assign(base, {
         event: {
           type: 'user/message',
@@ -296,6 +314,7 @@ function buildWireEvent(session, event) {
           source: d.source && d.source.kind,
           ...(typeof d.id === 'string' && d.id ? { raw: { id: d.id } } : {}),
           ...(images.length ? { images } : {}),
+          ...(files.length ? { files } : {}),
         },
       })
     }
@@ -554,8 +573,21 @@ async function admitMessage(api, msg) {
   const parsedImages = parseWireImages(msg.images, 'message')
   if (parsedImages.error) return rejectMessage(parsedImages.error)
   const imageParts = parsedImages.value
-  if (!text && imageParts.length === 0) {
-    return rejectMessage({ kind: 'error', code: 'bad-request', message: 'message requires non-empty text or at least one image' })
+  const files = msg.files === undefined ? [] : msg.files
+  if (!Array.isArray(files) || files.length > 20 || files.some(file => !file || typeof file.receiptId !== 'string'
+    || !file.receiptId.trim() || file.receiptId.length > 256)
+    || new Set(files.map(file => file.receiptId)).size !== files.length) {
+    return rejectMessage({ kind: 'error', code: 'bad-request', message: 'files must contain at most 20 distinct receiptId entries' })
+  }
+  if (files.length && (target.value.parentSessionId !== undefined || typeof msg.sessionId !== 'string' || !msg.sessionId.trim())) {
+    return rejectMessage({ kind: 'error', code: target.value.parentSessionId ? 'subagent/attachment-invalid' : 'bad-request',
+      message: 'file receipts require an existing ordinary session' })
+  }
+  if (files.length && (typeof msg.requestId !== 'string' || !msg.requestId.trim() || msg.requestId.length > 128)) {
+    return rejectMessage({ kind: 'error', code: 'bad-request', message: 'file messages require a requestId of 1..128 characters' })
+  }
+  if (!text && imageParts.length === 0 && files.length === 0) {
+    return rejectMessage({ kind: 'error', code: 'bad-request', message: 'message requires text, images or uploaded file receipts' })
   }
   const mode = msg.mode === 'steer' ? 'steer' : 'queue'
 
@@ -582,9 +614,10 @@ async function admitMessage(api, msg) {
       ...target.value,
       sessionId,
       mode,
-      ...(target.value.parentSessionId === undefined ? {} : requestIdentity),
+      ...(target.value.parentSessionId === undefined && files.length === 0 ? {} : requestIdentity),
       // Match the official WebUI ordering: images first, optional text last.
-      content: [...imageParts, ...(text ? [{ type: 'text', text }] : [])],
+      content: [...imageParts, ...files.map(file => ({ type: 'file', receiptId: file.receiptId })),
+        ...(text ? [{ type: 'text', text }] : [])],
       ...(typeof msg.clientTimeZone === 'string' && msg.clientTimeZone.trim() ? { clientTimeZone: msg.clientTimeZone.trim() } : {}),
     })
     log(`mobile message accepted: session=${sessionId} mode=${mode} images=${imageParts.length} text="${text.slice(0, 60)}"`)
@@ -2257,7 +2290,7 @@ const plugin = {
     // 已配对设备沿用本机用户权限；身份只由 Host 创建，不能由移动端参数指定。
     // 问答与审批仍由本插件的 Host 监听器处理，无需另开 Remote 交互流。
     const peer = ctx.connection.createPeer({ principal: { kind: 'owner' }, interactions: 'none' })
-    const api = createDshHostAdapter(ctx.typertGateway, peer)
+    const api = createDshHostAdapter(ctx.typertGateway, peer, ctx.connection)
     const host = api
     const agentDefaultModel = ctx.agentDefaultModel
     const options = {
@@ -2274,6 +2307,7 @@ const plugin = {
       fileDownloadChunkBytes: DEFAULT_FILE_DOWNLOAD_CHUNK_BYTES,
       fileDownloadIdleMs: DEFAULT_FILE_DOWNLOAD_IDLE_MS,
       fileDownloadMaxTransfers: DEFAULT_FILE_DOWNLOAD_MAX_TRANSFERS,
+      ...FILE_UPLOAD_DEFAULTS,
       adminLoopbackOnly: true,
       publicUrl: '',
       deviceFile: '',
@@ -2331,12 +2365,14 @@ const plugin = {
     const pendingQuestions = new Map()
     const pendingApprovals = new Map()
     const fileTransfers = createFileTransferManager(api, options)
+    const fileUploads = createFileUploadManager(api, options)
     const speechInput = createSpeechInputManager(api, options)
     const fileTransferExpiryTimer = setInterval(() => {
       fileTransfers.expire().catch((error) => {
         log(`file download expiry failed: ${error && error.message ? error.message : String(error)}`)
       })
-    }, Math.min(options.fileDownloadIdleMs, 30_000))
+      fileUploads.expire().catch(error => log(`file upload expiry failed: ${error.message}`))
+    }, Math.min(options.fileDownloadIdleMs, options.fileUploadIdleMs, 30_000))
     const backgroundStreamAbort = new AbortController()
     let archivedSessionIds = null
     let sessionQueues = null
@@ -3021,12 +3057,20 @@ const plugin = {
             const conversationRequest = ['message', 'history', 'subscribe', 'unsubscribe'].includes(msg.type)
             if ((ws.mobileChannel === 'control' && conversationRequest) ||
                 (ws.mobileChannel === 'conversation' && !conversationRequest && msg.type !== 'ping')) {
-              ws.send(stringifyWireFrame({ kind: 'error', code: 'wrong-channel', requestType: msg.type, message: 'Request belongs to the other mobile channel' }))
+              ws.send(stringifyWireFrame({ kind: 'error', code: 'wrong-channel', requestType: msg.type,
+                ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}), message: 'Request belongs to the other mobile channel' }))
               return
             }
 
             if (msg.type === 'ping') {
               ws.send(stringifyWireFrame({ kind: 'pong', at: Date.now() }))
+            } else if (FILE_UPLOAD_REQUEST_TYPES.has(msg.type)) {
+              if (!ws.deviceId) {
+                sendFrame({ kind: 'error', code: 'authentication-required', requestType: msg.type,
+                  ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}), message: 'File uploads require a paired device' })
+                return
+              }
+              void fileUploads.handle(ws, msg).then(sendFrame)
             } else if (SPEECH_REQUEST_TYPES.has(msg.type)) {
               if (!ws.deviceId) {
                 sendFrame({ kind: 'error', code: 'authentication-required', requestType: msg.type,
@@ -3078,6 +3122,12 @@ const plugin = {
                 if (frame && ws.readyState === 1) ws.send(stringifyWireFrame(frame))
               })
             } else if (msg.type === 'message') {
+              if (Array.isArray(msg.files) && msg.files.length > 0 && (!ws.deviceId || !options.fileUploadsEnabled)) {
+                sendFrame({ kind: 'error', code: !ws.deviceId ? 'authentication-required' : 'file-upload-disabled',
+                  requestType: 'message', ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}),
+                  message: 'File attachments require paired-device file upload access' })
+                return
+              }
               admitMessage(api, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(stringifyWireFrame(frame))
               })
@@ -3128,6 +3178,7 @@ const plugin = {
             fileTransfers.closeClient(ws).catch((error) => {
               log(`file download cleanup failed: ${error && error.message ? error.message : String(error)}`)
             })
+            fileUploads.closeClient(ws).catch(error => log(`file upload cleanup failed: ${error.message}`))
             log(`client disconnected (id=${id}, remaining=${clients.size})`)
           })
 
@@ -3163,6 +3214,7 @@ const plugin = {
               'schedule-management',
               'plugin-management-v1',
               ...(device ? ['speech-input-v1'] : []),
+              ...(device && options.fileUploadsEnabled ? ['file-upload-v1'] : []),
               'session-cancel',
               'queue-control',
               'session-archive',
@@ -3569,6 +3621,7 @@ const plugin = {
       fileTransfers.dispose().catch((error) => {
         log(`file download disposal failed: ${error && error.message ? error.message : String(error)}`)
       })
+      fileUploads.dispose().catch(error => log(`file upload disposal failed: ${error.message}`))
       disposeUpgrade()
       disposeMgmt()
       disposeEvents()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.11.0",
-  "description": "DeepSeek Harness 移动网关，支持安全设备配对、实时会话同步、插件管理、官方语音输入、文件卡片与安全预览、局域网及 Cloudflare Tunnel。0.11.0 新增智能体团队与子会话协议，支持团队成员、共享任务看板、多层子智能体目录和运行状态实时同步，以及子智能体独立历史、视图切换、继续对话、图片输入与停止执行；提供完整 APP 接入文档，客户端需按能力发现接入。",
+  "version": "0.11.1",
+  "description": "DeepSeek Harness 移动网关，支持安全设备配对、实时会话同步、智能体团队与子会话、插件管理、官方语音输入，以及局域网和 Cloudflare Tunnel。0.11.1 新增普通文件分块上传，支持 SHA-256 校验、进度确认、取消与断线清理，复用 DSH 官方附件存储和会话专属凭证，支持文件随消息发送及实时和历史文件引用；提供详细 App 对接指南。",
   "main": "lib/index.mjs",
   "files": [
     "bin",
@@ -26,7 +26,7 @@
   },
   "bin": "bin/setup-ip.mjs",
   "scripts": {
-    "test": "node test/wire-json.test.mjs && node test/setup-ip.test.mjs && node test/host-adapter.test.mjs && node test/speech-input.test.mjs && node test/plugin-management.test.mjs && node test/session-preset.test.mjs && node test/session-follower.test.mjs && node --test test/agent-team.test.mjs && node test/session-event-details.test.mjs && node test/gateway.test.mjs && node --test test/approval-replay.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs && node test/cloudflared-binary.test.mjs && node test/cloudflare-tunnel.test.mjs && node --test test/public-endpoint-check.test.mjs && node test/gateway-tools.test.mjs && node test/multi-gateway.test.mjs"
+    "test": "node test/wire-json.test.mjs && node test/setup-ip.test.mjs && node test/host-adapter.test.mjs && node --test test/file-upload.test.mjs && node test/speech-input.test.mjs && node test/plugin-management.test.mjs && node test/session-preset.test.mjs && node test/session-follower.test.mjs && node --test test/agent-team.test.mjs && node test/session-event-details.test.mjs && node test/gateway.test.mjs && node --test test/approval-replay.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs && node test/cloudflared-binary.test.mjs && node test/cloudflare-tunnel.test.mjs && node --test test/public-endpoint-check.test.mjs && node test/gateway-tools.test.mjs && node test/multi-gateway.test.mjs"
   },
   "exports": {
     ".": "./lib/index.mjs",