dsh-remote-bridge 2.6.0 → 2.7.0

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.6.0-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.7.0-087f8c">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DeepSeek_Harness-plugin-1f2328">
   <img alt="Platforms" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-586069">
   <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-2da44e">
@@ -102,10 +102,10 @@ dsh plugin --profile web add dsh-remote-bridge
 dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com
 
 # 2. tarball from the GitHub release
-dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
 
 # 3. tarball from the Gitee release (faster from mainland China)
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -122,7 +122,7 @@ Restart DSH after installation, then open settings — The section is titled **
 To install a downloaded release archive:
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.6.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.7.0.tgz
 ```
 
 ## First connection
@@ -219,10 +219,28 @@ The following controls remain active over both HTTP and HTTPS:
 - revocable scopes and per-root grants;
 - separate rate limits for pairing, authentication failures, and normal requests;
 - audit records that omit tokens, file bodies, and chat bodies;
-- no automatic access to roots added after a device was paired.
+- no automatic access to roots added after a device was paired;
+- provider `baseURL` changes are limited to public http(s) destinations, and moving a
+  provider that already stores a credential to a new host also requires a fresh API key
+  (the kernel sends that key to the address, so this is a credential boundary, not just SSRF).
 
 Only a loopback client may add roots, change device grants, create pairing codes, configure the listener, or permanently purge trash.
 
+### Local LLM endpoints (ollama / LM Studio)
+
+Private, loopback, link-local and CGNAT provider addresses are **rejected by default**.
+To use a local model server, list it explicitly in the plugin config:
+
+```yaml
+allowPrivateProviderHosts:
+  - 127.0.0.1:11434     # recommended: pin the port
+  - 192.168.1.5         # bare host: allows every port on that host
+```
+
+Exact `host` or `host:port` only — CIDR is not supported. Prefer the `host:port` form:
+allowing `192.168.1.5` allows every service on it, while ollama only listens on 11434.
+See `docs/project/SECURITY.md` for the reasoning and the audit trail fields.
+
 ## Path boundary
 
 External requests use `rootId + relativePath`, never an absolute server path.
@@ -297,6 +315,16 @@ A device also needs an explicit grant for every `rootId`. Local administrators m
 
 **New scopes are picked before pairing, in Remote access**: whatever you tick is what the generated pairing code carries, and those scopes take effect once the app enters the code. For a device that is already paired, open **Devices** and use its **Permissions** button.
 
+The default selection is five scopes — `chat.read`, `chat.write`, `files.read`, `files.write`, `settings.read` — and **deliberately excludes** `files.delete` and `settings.write`. You can still tick them; the default just no longer hands out destructive permissions on its own.
+
+### Device names and models
+
+At pairing time the bridge has no idea who will use the token, so a new device starts with a **platform-neutral** placeholder name (`Mobile device`). The first time the device connects, the bridge works out its platform and model from the request and replaces the name with `platform · model` (for example `HarmonyOS · ICL-AL10`).
+
+Platform detection prefers the client-declared `X-Dsh-Device: <platform>/<model>` header and falls back to the `User-Agent`. **The model is only taken from what the client reports**: neither okhttp nor ArkWeb puts a model in its default UA, and the bridge will not guess — a wrong model is worse than no model.
+
+Open **Devices** and use **Permissions** to rename a device. **A name you set yourself is never overwritten**; an automatically generated name still updates when the device reports a new identity. Device names are for display and troubleshooting only and take no part in authorization.
+
 **Revoking a device deletes it from the database** rather than leaving a marker row behind. Its grants go with it, while the audit trail (who revoked which device, and when) is kept.
 
 ## Upgrade and uninstall
@@ -352,21 +380,49 @@ pnpm check
 pnpm pack
 ```
 
-`pnpm check` covers type-checking, documentation consistency, and tests. It currently passes **67 test files / 557 cases**, plus **8 browser-layer cases** (Playwright measuring real computed styles, including the 375px narrow-viewport contract).
+`pnpm check` covers type-checking, documentation consistency, and tests. It currently passes **76 test files / 698 cases**, plus **8 browser-layer cases** (Playwright measuring real computed styles, including the 375px narrow-viewport contract).
 
-`npm pack` produces roughly a **0.61 MB** archive (v2.5.2 measured 635,325 bytes, SHA-256 `18d36904…c8095`): 2.2.0 dropped the standalone page and its editor dependencies and turned source maps off, down from 1.72 MB; it has since grown slightly with projection passthrough, the permission BFF, and the five-dimension hardening.
+`npm pack` produces roughly a **0.64 MB** archive (v2.6.1 measured 669,434 bytes, SHA-256 `9bf0189b…2cd35`): 2.2.0 dropped the standalone page and its editor dependencies and turned source maps off, down from 1.72 MB; it has since grown slightly with projection passthrough, the permission BFF, and the five-dimension hardening.
 
 v2.5.0 was verified on DSH **0.2.1-rc.2** on real hardware: all 14/14 host services injected, the three jobs endpoints exercised, and the permission catalog returned the kernel's real three presets. The development baseline is upstream `dsh-v0.2.1-rc.2` (commit `687f282e8625c6b8d11ff58211a90524be2e4317`); see `engines.dsh` above for the supported range. CI covers Windows, Ubuntu, and macOS.
 
-**v2.6.0 verification status**: 70 test files / 593 cases green, plus 8 Playwright browser cases
+**v2.7.0 verification status**: 76 test files / 698 cases green, plus 8 Playwright browser cases
 (including the 375px narrow-viewport contract); `typecheck`, `docs:check`, and the build all pass.
-All three rounds of real-hardware tunnel regressions were reproduced and verified on a
-React18 + Playwright click harness (one-click token issuance, the stop-tunnel escape hatch, and the
-locked state when re-entering settings), then confirmed by manual testing on the user's machine.
+All four capabilities were exercised on an isolated DSH **0.2.1-rc.3** instance rather than inferred:
+the plugin inventory returned `loaded: 14 / 16 / problems: 2`, the model catalog reported
+`ctx=1048576` for `free:mimo-v2.6-flash-free`, the four `reuseBlank` semantics were each verified,
+and the client bundle contains `dsh-remote-bridge-plugins` and `sidebarRightTabs`. Screenshots live
+in `dsh-021cmp/shots/`. The compatibility review was itself measured: 305 packages compared by
+sha256, 285 with zero code changes and 20 substantively changed, all ten hard-dependency providers
+inside the zero-change set, and 4 slots retained with 0 removed.
 
 ## Project
 
-- Version: `v2.6.0`
+- Version: `v2.7.0`
+- **v2.7.0 aligns with DSH 0.2.1-rc.3 and lifts four capabilities**: (1) the model catalog now carries
+  `contextWindow` / `maxTokens` — the kernel's `ModelCatalogModel` only has id/name/description, so the
+  bridge resolves capacity through `llm.resolveModelInfo`, caching per `provider + model` for ten
+  minutes, never caching a failure, and never overwriting a value the kernel already supplied;
+  (2) the plugin inventory gains a right-sidebar form (the bridge becomes a `SidebarRightTabDefinition`
+  provider, so from DSH 0.2.1-rc.3 the card can be pinned; on rc.2 it still renders but has no pin or
+  More menu, which is the expected degradation); (3) `POST /chat/sessions` accepts an optional
+  `reuseBlank`, matching the 0.2.1 desktop behaviour where New Session returns to the workspace's
+  existing blank session, skipping blanks whose preset contradicts the request; (4) the settings page
+  gains a Plugins card (inventory / enable / disable / check for updates) and an "open plugin list"
+  button (rc.2 has no `pluginNavigation.openList`, so the bridge feature-detects instead of checking
+  versions).
+- **v2.6.1 is the security-fix + device-identity release**: it closes a **high-severity** hole —
+  the three provider `baseURL` entry points (create / update / model discovery) performed no
+  validation at all, so a device holding `settings.write` could point the baseURL at its own server
+  and the kernel would request `/models` there with **that provider's real API key**, leaking the
+  credential outright; the persistent variant was worse, since after changing the baseURL every
+  subsequent chat would send the key there. There are now three gates (protocol allow-list,
+  private networks denied by default with an explicit `allowPrivateProviderHosts` opt-in, and a
+  new key required when repointing a provider that already holds a credential), and the pairing
+  default was narrowed from seven scopes to five (no more `settings.write` / `files.delete` by default).
+  It also fixes "the device name is always 'Android device'": the bridge now derives the platform and
+  model from the `X-Dsh-Device` header (User-Agent as fallback), renames the placeholder to
+  "platform · model", and offers a rename channel (a manually set name is never overwritten).
 - **v2.6.0 is the plugin-settings + IM-entry release**: it adds the per-plugin settings namespaces (`GET /api/v1/settings/namespaces`, `PATCH .../{ns}`) so the app can build the form from the kernel schema, and two entry points for "I am out and the desktop is still locked" — the host command `/tunnel` and the tool `open_tunnel_config`; plus one-tap pruning of unused devices, the audit page removed, and a guard so a failing optional registration cannot tear down the whole plugin context.
 - **v2.5.2 is a comprehensive hardening release**: it lands the five-dimension audit
   (security, features, performance, UI, button feedback) — including the unauthenticated

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.6.0-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.7.0-087f8c">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DeepSeek_Harness-plugin-1f2328">
   <img alt="Platforms" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-586069">
   <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-2da44e">
@@ -93,10 +93,10 @@ dsh plugin --profile web add dsh-remote-bridge
 dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com
 
 # ② GitHub Release 的 tarball
-dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.7.0/dsh-remote-bridge-v2.7.0.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -112,7 +112,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.6.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.7.0.tgz
 ```
 
 ## 第一次使用
@@ -251,9 +251,27 @@ DSH1:eyJ2IjoxLCJlbmRwb2ludHMiOlt7ImxhYmVsIjoi…
 - 配对、认证和普通请求分别限流。
 - 审计记录操作类型和对象，但不记录令牌、文件正文或聊天正文。
 - 新增根目录不会自动授权给已经配对的设备。
+- 供应商 `baseURL` 只能指向公网 http(s) 地址；把「已经存有凭据」的供应商换到新 host
+  还必须同时提供新的 API key —— 因为内核会带着那把 key 去请求这个地址，这是凭据边界，
+  不只是 SSRF。
 
 只有来自回环地址的管理界面可以添加根目录、调整设备权限、生成配对码、修改监听设置和永久清理回收站。
 
+### 自建 LLM（ollama / LM Studio）
+
+私网、回环、链路本地与 CGNAT 的供应商地址**默认拒绝**。要用本机模型服务，在插件配置里
+显式放行：
+
+```yaml
+allowPrivateProviderHosts:
+  - 127.0.0.1:11434     # 推荐：钉住端口
+  - 192.168.1.5         # 裸 host：放行该主机的全部端口
+```
+
+只接受精确 `host` 或 `host:port`，**不支持 CIDR**。推荐带端口写法：放行 `192.168.1.5`
+等于放行它上面所有服务，而 ollama 只在 11434。理由与审计字段见
+[docs/project/SECURITY.md](docs/project/SECURITY.md#供应商-baseurl-的地址策略261-起sec-h11)。
+
 ## 文件边界
 
 外部接口只接受 `rootId + relativePath`，不会接收服务器绝对路径。路径还会经过以下检查：
@@ -328,6 +346,16 @@ Authorization: Bearer DEVICE_TOKEN
 
 **新增的权限是配对前在「远程访问」里勾选的**：勾什么，生成的配对码就带什么；APP 输入配对码后这些权限随设备一起生效。已在用的设备则到「设备」里点它的「权限」修改。
 
+默认勾选是五档 —— `chat.read`、`chat.write`、`files.read`、`files.write`、`settings.read`，**刻意不含** `files.delete` 与 `settings.write`。你仍然可以自己勾上；默认值只是不再替你做这个决定。
+
+### 设备名与型号
+
+配对那一刻桥并不知道将来是谁来用这个令牌，所以新设备先得到一个**平台无关**的占位名（`Mobile device`）。设备第一次连上来时，桥会从请求里识别平台与型号，把名字自动换成「平台 · 型号」（比如 `HarmonyOS · ICL-AL10`）。
+
+平台判定优先看客户端上报的 `X-Dsh-Device: <platform>/<model>` 头，没有就从 `User-Agent` 兜底。**型号只认客户端上报**：OkHttp 与 ArkWeb 的默认 UA 里都没有机型，桥不会去猜 —— 猜错的型号比没有型号更糟。
+
+在「设备」页点「权限」可以直接改名。**你手动改过的名字不会再被自动覆盖**；自动生成的名字在设备上报了新身份时仍会更新。设备名只用于显示与排查，不参与任何授权判断。
+
 **撤销一台设备会直接把它从数据库里删除**，不是打个标记留着；它的授权随之清除，但审计记录（谁在什么时候撤了谁）会保留。
 
 ## 升级与卸载
@@ -383,22 +411,42 @@ pnpm check
 pnpm pack
 ```
 
-`pnpm check` 覆盖类型检查、文档一致性与测试；当前 **67 个测试文件 / 557 个用例**，外加 **8 个浏览器层用例**（Playwright 实测量出的计算样式，含 375px 窄屏契约），全部通过。
+`pnpm check` 覆盖类型检查、文档一致性与测试；当前 **76 个测试文件 / 698 个用例**，外加 **8 个浏览器层用例**（Playwright 实测量出的计算样式，含 375px 窄屏契约），全部通过。
 
-`npm pack` 的产物约 **0.61 MB**（v2.5.2 实测 635,325 字节，SHA-256 `18d36904…c8095`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传、权限 BFF 与五维加固小幅增长。
+`npm pack` 的产物约 **0.64 MB**（v2.6.1 实测 669,434 字节，SHA-256 `9bf0189b…2cd35`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传、权限 BFF 与五维加固小幅增长。
 
 v2.5.0 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部可注入、三个 jobs 端点实测通过、
 权限档位目录返回内核真实三档。开发基线为上游 `dsh-v0.2.1-rc.2`（commit `687f282e8625c6b8d11ff58211a90524be2e4317`），
 兼容范围见上文 `engines.dsh`。CI 覆盖 Windows、Ubuntu 和 macOS。
 
-**v2.6.0 的验证状态**：70 个测试文件 / 593 个用例全绿、8 个 Playwright 浏览器用例
-（含 375px 窄屏契约）、`typecheck`/`docs:check`/构建通过；隧道管理面三轮真机回归均用
-React18 + Playwright 真点击台复现并验证（一键出令牌、停止出口、重进设置页锁定态），
-用户真机手工复测通过。
+**v2.7.0 的验证状态**：76 个测试文件 / 698 个用例全绿、8 个 Playwright 浏览器用例
+（含 375px 窄屏契约）、`typecheck`/`docs:check`/构建通过。这一版的四项能力都在
+DSH **0.2.1-rc.3** 隔离实例上**实跑验过**，不是静态推断：插件清单返回
+`loaded: 14 / 16 / problems: 2`、模型目录里 `free:mimo-v2.6-flash-free` 带出
+`ctx=1048576`、`reuseBlank` 的四种语义逐一验过、客户端 bundle 里能找到
+`dsh-remote-bridge-plugins` 与 `sidebarRightTabs`。截图存于 `dsh-021cmp/shots/`。
+兼容性核对本身也是实测：305 个包逐个 sha256 比对，285 个代码零改动、20 个有实质改动，
+10 个硬依赖服务的提供方**全部**落在零改动名单，4 个 slot 全保留、删除 0。
 
 ## 项目信息
 
-- 当前版本：`v2.6.0`
+- 当前版本：`v2.7.0`
+- **v2.7.0 是对齐 DSH 0.2.1-rc.3 的能力提升版**：四项 —— ①模型目录补上 `contextWindow` / `maxTokens`
+  （内核的 `ModelCatalogModel` 只有 id/name/description，容量得另走 `llm.resolveModelInfo`，桥按
+  `provider + model` 缓存 10 分钟、失败不缓存、内核自己给了就不覆盖）；②插件清单多了右侧栏形态
+  （成为 `SidebarRightTabDefinition` 提供方，DSH 0.2.1-rc.3 起该卡片可被 pin；rc.2 上正常显示但
+  没有 pin 与 More 菜单，属预期降级）；③`POST /chat/sessions` 新增可选 `reuseBlank`，对齐 0.2.1
+  桌面端「新会话回到那个工作区已有的空白会话」的语义，并跳过 preset 与请求不符的空白；
+  ④设置页新增「插件」卡片（清单 / 启停 / 检查更新）与「打开插件列表」按钮（rc.2 无
+  `pluginNavigation.openList`，故做特性检测而非版本判断）。
+- **v2.6.1 是安全修复 + 设备身份版**：修掉一个**高危**问题 —— 供应商 `baseURL` 的三个入口
+  （新建 / 修改 / 探测模型）此前不做任何校验，持有 `settings.write` 的设备可以把 baseURL
+  指向自己的服务器，内核会带着**该供应商的真实 API key** 去请求 `/models`，等于凭据直接外泄；
+  持久化变体更糟：改完 baseURL 之后正常聊天都会把 key 发过去。现在三道闸门（协议白名单、
+  私网默认拒绝 + `allowPrivateProviderHosts` 显式放行、换 host 且已有凭据时必须同时给新 key），
+  配对默认权限也从七档收到五档（不再默认给 `settings.write` 与 `files.delete`）。
+  另修「设备名永远是『Android 设备』」：桥现在从 `X-Dsh-Device` 头（UA 兜底）识别平台与型号，
+  自动把占位名换成「平台 · 型号」，并新增改名通道（手动改过的名字永不被自动覆盖）。
 - **v2.6.0 是通用设置面 + IM 入口版**：新增「按插件划分的设置命名空间」两个端点（手机端照 schema 自建表单，新装插件无需改 App），以及「人已出门、电脑还锁着」时用 IM 一句话开隧道并收回配对配置的双入口（宿主命令 `/tunnel` + 工具 `open_tunnel_config`）；另加一键清理 N 天未使用设备、移除审计页，并把「激活期降级保护」补上（apply 尾部抛错不再拆掉整条插件上下文）。
 - **v2.5.2 是全量完善版**：落地五维审计（安全/功能/性能/界面/按钮反馈）——含高危的
   `debug/host-services` 免鉴权信息泄露修复、限流双桶、广播背压、弱 ETag、审计保留策略等，

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.6.0
+  version: 2.7.0
   description: |
     Live file and authorized DSH chat events. Reconnect clients must refresh
     REST state; unbounded replay is not provided.

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.6.0
+  version: 2.7.0
   description: Versioned file and chat BFF for mobile and third-party DSH clients. HTTP and HTTPS are both supported.
 servers:
   - url: http://127.0.0.1:3090/api/v1
@@ -24,7 +24,7 @@ paths:
                 properties:
                   ok: { type: boolean, const: true }
                   version: { type: string, const: v1 }
-                  pluginVersion: { type: string, const: 2.6.0 }
+                  pluginVersion: { type: string, const: 2.7.0 }
   /debug/host-services:
     get:
       operationId: hostServices
@@ -506,7 +506,16 @@ paths:
         '403': { $ref: '#/components/responses/Error' }
     post:
       operationId: createCustomProvider
-      description: Creates a fully custom llm-pi-ai provider using the protocols reported by ProviderSettings.customProvider.
+      description: |
+        Creates a fully custom llm-pi-ai provider using the protocols reported by
+        ProviderSettings.customProvider.
+
+        `baseURL` must be an absolute http(s) URL. Private, loopback, link-local and
+        CGNAT destinations are rejected with `403 PROVIDER_BASE_URL_FORBIDDEN` unless the
+        deployment lists the host in `allowPrivateProviderHosts` (exact `host` or
+        `host:port`, no CIDR). The kernel sends the provider's stored API key to this
+        address, so the check is what keeps a paired device from redirecting credentials.
+        See SECURITY.md ("供应商 baseURL 的地址策略").
       requestBody:
         required: true
         content:
@@ -519,6 +528,7 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ProviderSettings' }
         '400': { $ref: '#/components/responses/Error' }
+        '403': { $ref: '#/components/responses/Error' }
         '409': { $ref: '#/components/responses/Error' }
   /settings/plugins:
     get:
@@ -649,7 +659,15 @@ paths:
         schema: { type: string }
     patch:
       operationId: updateProvider
-      description: Updates provider settings and optionally writes an API key to the DSH credential store.
+      description: |
+        Updates provider settings and optionally writes an API key to the DSH credential store.
+
+        `baseURL` goes through the same address policy as creation. In addition, moving a
+        provider that already holds a credential to a different host requires supplying a
+        new `apiKey` in the same patch (`403 PROVIDER_BASE_URL_REPOINT_FORBIDDEN`) —
+        otherwise a paired device could point a live key at its own public domain, which
+        the private-address rule cannot catch. Changing models, the display name, or the
+        path within the same host is unaffected.
       requestBody:
         required: true
         content:
@@ -675,6 +693,11 @@ paths:
   /settings/providers/{providerId}/discover:
     post:
       operationId: discoverProviderModels
+      description: |
+        Fetches `GET {baseURL}/models` through the kernel, carrying the provider's stored
+        credential. `baseURL` here is a temporary override that is NOT persisted, so a
+        rejected address never reaches the config — but it does reach the network unless
+        the address policy allows it. Same rules as creation.
       parameters:
         - name: providerId
           in: path
@@ -702,6 +725,8 @@ paths:
                   models:
                     type: array
                     items: { $ref: '#/components/schemas/ProviderModel' }
+        '400': { $ref: '#/components/responses/Error' }
+        '403': { $ref: '#/components/responses/Error' }
   /chat/sessions:
     get:
       operationId: listChatSessions
@@ -747,6 +772,16 @@ paths:
                 path: { $ref: '#/components/schemas/WirePath' }
                 sessionId: { type: string }
                 agentPreset: { type: string }
+                reuseBlank:
+                  type: boolean
+                  default: true
+                  description: |
+                    Only consulted when `sessionId` is absent. When true (the default) the
+                    bridge first looks for an existing **blank** session at the requested
+                    location and reuses it, mirroring the DSH 0.2.1 desktop "New Session"
+                    behaviour; when false it always mints a fresh session. A blank whose
+                    recorded `agentPreset` contradicts a requested one is skipped rather
+                    than reused. Clients that omit this field get the desktop semantics.
                 clientRequestId: { type: string, maxLength: 200 }
       responses:
         '201': { description: DSH session created or idempotently returned. }
@@ -1412,6 +1447,28 @@ components:
         rootIds:
           type: array
           items: { type: string }
+        platform:
+          type: string
+          description: >-
+            Platform the device reported, or the one inferred from its
+            User-Agent when it reported nothing. Absent for devices that never
+            connected since the bridge started collecting it. Informational
+            only — it is client-declared and never takes part in authorization.
+          enum: [android, harmonyos, ios, ipados, web, windows, macos, linux]
+        model:
+          type: string
+          description: >-
+            Model the device reported. Often absent: neither okhttp nor ArkWeb
+            puts a model in its default User-Agent, and the bridge deliberately
+            does not guess — a wrong model is worse than no model.
+        nameSource:
+          type: string
+          description: >-
+            Where `name` came from. `default` (pairing placeholder) and
+            `detected` (auto-generated from the reported identity) may still be
+            replaced when the device reports a different identity; `declared`
+            means a human set it and it is never overwritten automatically.
+          enum: [default, detected, declared]
     FileEntry:
       type: object
       required: [name, path, kind, size, modifiedAt, writable]

package/kotlin-sdk/src/main/kotlin/ai/deepseek/dsh/workspace/DshWorkspaceClient.kt

@@ -46,6 +46,12 @@ data class DeviceView(
     val name: String,
     val scopes: List<String>,
     val rootIds: List<String>,
+    /** 平台：`android` / `harmonyos` / `ios` / …。老桥与从未连过的设备没有这个字段。 */
+    val platform: String? = null,
+    /** 型号。桥刻意不猜（okhttp/ArkWeb 默认 UA 里没有机型），所以多数时候是 null。 */
+    val model: String? = null,
+    /** `name` 的来源：`default` / `detected` / `declared`。null 等价于 `declared`。 */
+    val nameSource: String? = null,
 )
 
 @Serializable
@@ -482,14 +488,21 @@ class DshWorkspaceClient(
         ).models
     }
 
+    /**
+     * 在工作区里新建会话。
+     *
+     * [reuseBlank] 省略时由桥按桌面语义处理（复用该位置已有的空白会话）；传 `false`
+     * 可强制新建一个全新会话。老客户端不传这个参数，行为与之前一致。
+     */
     fun createSessionInWorkspace(
         workspaceId: String,
         clientRequestId: String,
         agentPreset: String? = null,
+        reuseBlank: Boolean? = null,
     ): JsonElement {
         val body = json.encodeToString(
             WorkspaceSessionRequest.serializer(),
-            WorkspaceSessionRequest(workspaceId, agentPreset, clientRequestId),
+            WorkspaceSessionRequest(workspaceId, agentPreset, clientRequestId, reuseBlank),
         )
         return executeJsonElement("chat/sessions", "POST", body)
     }
@@ -800,6 +813,7 @@ class EventSubscription internal constructor(
     val workspaceId: String,
     val agentPreset: String? = null,
     val clientRequestId: String,
+    val reuseBlank: Boolean? = null,
 )
 @Serializable private data class SendMessageRequest(val text: String, val mode: String, val clientRequestId: String)
 @Serializable private data class ErrorEnvelope(val error: ApiErrorBody)