dsh-remote-bridge 2.4.3 → 2.5.0

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.3-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.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">
@@ -36,9 +36,17 @@ The interface is bilingual and defaults to Chinese. Prebuilt packages run on Win
 > `engines.dsh` is recognized by the 0.2.1 kernel (`prepareProfileEntries` in
 > `dsh-app-boot/lib/index.js`) — an unmet range only sets that entry to `disabled` and prints to
 > stderr; **the host process does not exit**. So no code change is needed to run on `0.2.1-rc.2`.
-> The only point still needing on-device confirmation is the injection surface of
-> `permissionPresets` (never injectable on 0.2.0 either, where the plugin already falls back to a
-> built-in catalog).
+>
+> **Functional differences between the two versions (important)**: the `inject` list holds **only
+> services that exist in both versions** — cordis treats `inject` as a **hard dependency**, and a
+> single missing service leaves the whole plugin inactive (proven by CI on the 0.2.0-rc.2 baseline:
+> writing a 0.2.1-only service into `inject` once made the plugin fail to activate on 0.2.0).
+> The services that only 0.2.1 provides (**background jobs** `jobController`, the **permission
+> catalog** `permissionPresets`, file upload `fileUploads`, attachment storage `attachments`) are
+> therefore read at runtime through `ctx.reflect.get(name, false)`: **all of them work on
+> 0.2.1-rc.2 and degrade automatically on 0.2.0-rc.2** (the jobs endpoints answer 404 there, the
+> permission catalog falls back to its built-in one) — the plugin itself runs on both kernels.
+> `GET /api/v1/debug/host-services` reports which optional capabilities the current machine has.
 
 ## What it looks like
 
@@ -94,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.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.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.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.0.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -114,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.4.3.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.0.tgz
 ```
 
 ## First connection
@@ -346,13 +354,13 @@ pnpm pack
 
 `pnpm check` covers type-checking, documentation consistency, and tests. It currently passes **30 test files / 226 cases**, plus **4 browser-layer cases** (Playwright measuring real computed styles).
 
-`npm pack` produces roughly a **0.55 MB** archive (v2.4.3 measured 572,951 bytes, SHA-256 `38f25c10…299c93`): 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 and the permission BFF.
+`npm pack` produces roughly a **0.55 MB** archive (v2.5.0 measured 572,951 bytes, SHA-256 `38f25c10…299c93`): 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 and the permission BFF.
 
-v2.4.3 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 `master@47f943859bef60e4160492346772ded9b24f765a` (kernel 0.2.0-rc.2); see `engines.dsh` above for the supported range. CI covers Windows, Ubuntu, and macOS.
+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.
 
 ## Project
 
-- Version: `v2.4.3`
+- Version: `v2.5.0`
 - Author: upstream [Hakunm](https://github.com/Hakunm); this fork maintained by [westanke](https://github.com/westanke)
 - Repository: [GitHub](https://github.com/westanke/dsh-remote-bridge) · [Gitee](https://gitee.com/westanke/dsh-remote-bridge)
 - npm: [`dsh-remote-bridge`](https://www.npmjs.com/package/dsh-remote-bridge) ([mainland-China mirror](https://registry.npmmirror.com/dsh-remote-bridge))

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.3-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.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">
@@ -26,13 +26,21 @@
 > 0.2.x 上无法启动（表现为「添加根目录返回 405」）。兼容层的完整说明——基于什么、为什么、改了什么、
 > 测了什么——见 [DSH 0.2.x 兼容性适配说明](./docs/project/DSH-0.2-COMPAT.md)。
 >
-> **对 DSH 0.2.1-rc.2 的适配结论**（2026-10-20 复核，依据 `/media/wangke/OFFICE/workspace/dsh-remote-bridge/docs/project/DSH-0.2.1-ADAPTATION.md`）：
+> **对 DSH 0.2.1-rc.2 的适配结论**（2026-10-20 复核，依据 `docs/project/DSH-0.2.1-ADAPTATION.md`）：
 > 本插件**刻意不 import 任何 `@deepseek-ai/*` 包**，全部宿主服务经结构类型 + Host 注入消费
 > （见 `src/host/dsh-0.2-bridge.ts` 头注释）。逐一到 `0.2.1-rc.2` 实装包核对：`cordis.patch.yml`
 > 的 10 项 `inject` 服务名**全部仍存在且签名未变**，`engines.dsh` 在 0.2.1 被内核识别
 > （`dsh-app-boot/lib/index.js` 的 `prepareProfileEntries`），不满足时只把该 entry 置
 > `disabled` 并打 stderr，**宿主进程不退出**。故本插件无需改码即可运行于 `0.2.1-rc.2`。
-> 唯一需真机定论的是 `permissionPresets` 的注入面（0.2.0 上即注不进，已降级到内置目录）。
+>
+> **两版的功能差异（重要）**：`inject` 里只放**两个版本都存在**的服务 —— cordis 的 inject 是
+> **硬依赖**，任何一个服务缺失就整个插件不激活（CI 在 0.2.0-rc.2 基线上实锤过：
+> 一度因为把 0.2.1 才有的服务写进 inject 而让插件在 0.2.0 上整体不激活）。
+> 因此 0.2.1 才提供的服务（**后台任务** `jobController`、**权限档位目录**
+> `permissionPresets`、文件上传 `fileUploads`、附件存储 `attachments`）改为运行时经
+> `ctx.reflect.get(name, false)` 读取：**0.2.1-rc.2 上这些功能全部可用，0.2.0-rc.2 上
+> 自动降级**（如后台任务端点返回 404、权限档位走内置目录），插件本体两种内核都能跑。
+> 用 `GET /api/v1/debug/host-services` 可以查这台机器上哪些可选能力可用。
 
 ## 实际效果
 
@@ -85,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.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.0.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.0.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -104,7 +112,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.0.tgz
 ```
 
 ## 第一次使用
@@ -332,15 +340,15 @@ pnpm pack
 
 `pnpm check` 覆盖类型检查、文档一致性与测试；当前 **30 个测试文件 / 226 个用例**，外加 **4 个浏览器层用例**（Playwright 实测量出的计算样式），全部通过。
 
-`npm pack` 的产物约 **0.55 MB**（v2.4.3 实测 572,951 字节，SHA-256 `38f25c10…299c93`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传与权限 BFF 小幅增长。
+`npm pack` 的产物约 **0.55 MB**（v2.5.0 实测 572,951 字节，SHA-256 `38f25c10…299c93`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传与权限 BFF 小幅增长。
 
-v2.4.3 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部可注入、三个 jobs 端点实测通过、
-权限档位目录返回内核真实三档。开发基线为 `master@47f943859bef60e4160492346772ded9b24f765a`（内核 0.2.0-rc.2），
+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.4.3`
+- 当前版本：`v2.5.0`
 - 作者：上游 [Hakunm](https://github.com/Hakunm)，本 fork 维护 [westanke](https://github.com/westanke)
 - 仓库：[GitHub](https://github.com/westanke/dsh-remote-bridge) · [Gitee](https://gitee.com/westanke/dsh-remote-bridge)
 - npm：[`dsh-remote-bridge`](https://www.npmjs.com/package/dsh-remote-bridge)（[国内镜像](https://registry.npmmirror.com/dsh-remote-bridge)）

package/cordis.patch.yml

@@ -16,6 +16,20 @@
       # 这一条曾长期掩盖真相：`permissionPresets` 一直以为「web profile 注不进、
       # 只能走内置兜底目录」，实际是这里没声明它。`jobController` 加进来之后
       # 同样注不进，才顺着 `_refresh()` 的 INACTIVE 逻辑反查到这条覆盖规则。
+      # ⚠️ 这份列表**只能放「两个支持版本上都存在的服务」**。
+      # cordis 的 inject 是**硬依赖**：任何一个服务缺失 → 整个 entry 永久 INACTIVE。
+      # 2026-10-20 CI 实锤：把 jobController / fileUploads / attachments /
+      # permissionPresets 加进来后，插件在 **0.2.0-rc.2**（smoke-profile-install
+      # 检出的上游基线）上整体不激活，报
+      # "waiting for services: ..., jobController, fileUploads" ——
+      # 那一版内核的 web profile 没挂这些服务。
+      #
+      # 可选服务（permissionPresets / jobController / fileUploads / attachments /
+      # workingDirectory）**不在这里声明**，由插件在运行时经
+      # `ctx.reflect.get(name, false)` 读取（cordis 给「不带 inject 要求」读服务
+      # 准备的正路，见 dsh-0.2-bridge.ts 的 optionalService 注释）：
+      # 0.2.1-rc.2 上读到就走全功能，0.2.0-rc.2 上读不到就按能力位降级。
+      # 探针（GET /debug/host-services）继续报告这 5 个名字的真实可用性。
       inject: [
         sessionController,
         workspaceController,
@@ -23,20 +37,10 @@
         settingsController,
         credentialsController,
         agentPresets,
-        # 权限档位目录（`ctx.permissionPresets`）：内核把它做成独立的 Typert
-        # 远程服务，会话投影那条 wire 视图只给 currentValue、不带候选项。
-        permissionPresets,
         llm,
         webServer,
         agents,
         commands,
-        # 后台任务（`ctx.jobController`）：远程场景下任务跑飞了要能停掉。
-        jobController,
-        # 文件上传服务（`ctx.fileUploads`）：用它而不是内核那条只绑 loopback 的
-        # /api/session/uploadFileBinary HTTP 路由。
-        fileUploads,
-        # 附件存储（`ctx.attachments`）：会话历史里的图片以 attachmentId 引用存在。
-        attachments,
       ]
       config:
         # 状态目录**不改名**：已装的机器上有既有数据库与回收站，换目录等于让用户

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.4.3
+  version: 2.5.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.4.3
+  version: 2.5.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
@@ -1408,8 +1408,26 @@ components:
         configurable: { type: boolean }
         configured: { type: boolean }
         removable: { type: boolean }
+        defaultBaseURL: { type: string, description: '目录供应商的适配器默认 API 地址（未配置时使用）。' }
+        baseURLEnv:
+          type: array
+          items: { type: string }
+          description: '可能覆盖默认地址的环境变量，按优先级排序。'
+        nativeAuth: { $ref: '#/components/schemas/NativeAuthHint' }
+        settingsNs:
+          type: string
+          description: 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。
         credential: { $ref: '#/components/schemas/CredentialState' }
         config: { $ref: '#/components/schemas/ProviderConfig' }
+    NativeAuthHint:
+      type: object
+      required: [env, oauth]
+      properties:
+        env:
+          type: array
+          items: { type: string }
+          description: '适配器原生认证依赖的环境变量。'
+        oauth: { type: boolean, description: '是否支持 OAuth 登录。' }
     ProviderSettings:
       type: object
       required: [writable, revisionByNamespace, customProvider, providers]
@@ -1433,7 +1451,8 @@ components:
         thinking: { type: [string, 'null'] }
         reasoningEffort: { type: [string, 'null'] }
         models:
-          type: array
+          type: [array, 'null']
+          description: '数组=整体替换模型目录（空数组=自定义空目录）；`null`=恢复适配器默认目录（unset）。'
           items: { $ref: '#/components/schemas/ProviderModel' }
         expectedRevision: { type: integer, minimum: 0 }
     CustomProviderCapability:

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

@@ -206,6 +206,12 @@ data class CredentialState(
     val writable: Boolean,
 )
 
+@Serializable
+data class NativeAuthHint(
+    val env: List<String> = emptyList(),
+    val oauth: Boolean = false,
+)
+
 @Serializable
 data class ProviderView(
     val id: String,
@@ -215,6 +221,11 @@ data class ProviderView(
     val configurable: Boolean,
     val configured: Boolean,
     val removable: Boolean,
+    val defaultBaseURL: String? = null,
+    val baseURLEnv: List<String>? = null,
+    val nativeAuth: NativeAuthHint? = null,
+    /** 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。 */
+    val settingsNs: String? = null,
     val credential: CredentialState,
     val config: ProviderConfig,
 )
@@ -242,6 +253,7 @@ data class ProviderPatch(
     val apiKey: String? = null,
     val thinking: String? = null,
     val reasoningEffort: String? = null,
+    /** 数组=整体替换（空数组=自定义空目录）；恢复默认目录用 [DshWorkspaceClient.resetProviderModels]（wire `models: null`）。 */
     val models: List<ProviderModel>? = null,
     val expectedRevision: Int? = null,
 )
@@ -426,6 +438,27 @@ class DshWorkspaceClient(
         return executeJson("settings/providers/$providerId", "PATCH", body, ProviderSettings.serializer())
     }
 
+    /**
+     * 恢复供应商的适配器默认模型目录（wire `models: null`）。data class 无法把
+     * null 默认值与「字段缺席」区分开，所以这里手工拼 body。
+     */
+    fun resetProviderModels(providerId: String, expectedRevision: Int? = null): ProviderSettings {
+        val body = buildString {
+            append("{\"models\":null")
+            if (expectedRevision != null) append(",\"expectedRevision\":").append(expectedRevision)
+            append('}')
+        }
+        return executeJson("settings/providers/$providerId", "PATCH", body, ProviderSettings.serializer())
+    }
+
+    fun deleteProvider(providerId: String, expectedRevision: Int? = null) {
+        val relative = buildString {
+            append("settings/providers/").append(providerId)
+            if (expectedRevision != null) append("?expectedRevision=").append(expectedRevision)
+        }
+        executeUnit(relative, "DELETE", null)
+    }
+
     fun createCustomProvider(provider: CustomProviderCreate): ProviderSettings {
         val body = json.encodeToString(CustomProviderCreate.serializer(), provider)
         return executeJson("settings/providers", "POST", body, ProviderSettings.serializer())

package/lib/index.d.ts

@@ -78,7 +78,9 @@ declare class WorkspaceDatabase {
   readonly dataDir: string;
   readonly trashDir: string;
   private readonly db;
+  private closed;
   constructor(dataDir: string);
+  /** 关闭数据库。**幂等** —— 重复调用不抛错。 */
   close(): void;
   /**
    * 导出 `roots` 的建表语句（只读，诊断与迁移测试用）。
@@ -218,6 +220,12 @@ interface ConfigurableProvider {
   settingsPath: string[];
   active: boolean;
   declared?: boolean;
+  defaultBaseURL?: string;
+  baseURLEnv?: string[];
+  nativeAuth?: {
+    env?: string[];
+    oauth?: boolean;
+  };
 }
 interface SettingsApiProxy extends DshApiProxy {
   settings: {
@@ -326,6 +334,14 @@ interface ProviderView {
   configurable: boolean;
   configured: boolean;
   removable: boolean;
+  defaultBaseURL?: string;
+  baseURLEnv?: string[];
+  nativeAuth?: {
+    env?: string[];
+    oauth?: boolean;
+  };
+  /** 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。 */
+  settingsNs?: string;
   credential: {
     ref: string;
     configured: boolean;
@@ -341,7 +357,8 @@ interface ProviderPatch {
   apiKey?: string | null;
   thinking?: string | null;
   reasoningEffort?: string | null;
-  models?: ProviderModelView[];
+  /** `null` 恢复适配器默认模型目录（unset），`[]` 写入自定义空目录。 */
+  models?: ProviderModelView[] | null;
   expectedRevision?: number;
 }
 interface CustomProviderCreate {
@@ -738,6 +755,14 @@ interface LlmLike {
     settingsNs: string;
     settingsPath: readonly string[];
     declared?: boolean;
+    defaultBaseURL?: string;
+    /** Environment variables that may override the default base URL, in priority order. */
+    baseURLEnv?: readonly string[];
+    /** Native authentication the adapter can fall back to when no key is stored. */
+    nativeAuth?: {
+      env?: readonly string[];
+      oauth?: boolean;
+    };
     error?: string;
   }[];
   discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
@@ -761,7 +786,14 @@ interface Dsh02HostServices {
   settingsController: SettingsControllerLike;
   credentialsController: CredentialsControllerLike;
   agentPresets: AgentPresetsLike;
-  permissionPresets: PermissionPresetsLike;
+  /**
+   * 权限档位目录（`ctx.permissionPresets`）——**可选**。
+   *
+   * 0.2.1 的 web profile 上有；0.2.0-rc.2 上没有。inject 是硬依赖，
+   * 所以它不能进 inject，只能声明成可选，由 `optionalService` 运行时读；
+   * 读不到时权限档位走 `FALLBACK_PERMISSION_CATALOG` + BFF。
+   */
+  permissionPresets?: PermissionPresetsLike;
   /**
    * 后台任务控制器（`ctx.jobController`，`@deepseek-ai/dsh-api-job-controller`）。
    *
@@ -771,7 +803,14 @@ interface Dsh02HostServices {
    * 与 `sessionController` 不同，这个是 `TypertRemoteService`（不是 `@Remote`
    * 控制器集合），但结构类型消费方式完全一样：只声明用到的成员，缺了就明确报错。
    */
-  jobController: JobControllerLike;
+  /**
+   * 后台任务控制器（`ctx.jobController`）——**可选**。
+   *
+   * 只有 DSH 0.2.1 的 web profile 挂了这个服务；0.2.0-rc.2 上没有，
+   * 而 inject 是硬依赖（缺一个整个插件不激活），所以它**不能**出现在 inject 里，
+   * 只能在这里声明成可选，由 `optionalService` 运行时读。
+   */
+  jobController?: JobControllerLike;
   llm: LlmLike;
   /**
    * 内核附件存储（`ctx.attachments`）；会话历史里的图片要经它取字节。
@@ -782,14 +821,23 @@ interface Dsh02HostServices {
    * `cannot get property "attachments" without inject` —— 请求链路本身没问题，
    * 挂在服务端、而且只在真的去取图时才炸，所以很难在本地测出来。
    */
-  attachments: AttachmentStoreLike;
   /**
-   * Kernel file-upload service (`ctx.fileUploads`).
+   * 内核附件存储（`ctx.attachments`）——**可选**。
+   *
+   * 0.2.0-rc.2 的 web profile 上没有这个服务（诊断日志实测 MISSING），
+   * 而 inject 是硬依赖，所以它只能声明成可选，由 `optionalService` 运行时读；
+   * 读不到时附件读取走内核 `sessionController.attachment()`。
+   */
+  attachments?: AttachmentStoreLike;
+  /**
+   * Kernel file-upload service (`ctx.fileUploads`)——**可选**。
    *
    * 为什么用它而不是内核那条 `/api/session/uploadFileBinary` HTTP 路由：那条路由
    * 只绑 loopback（手机根本到不了），而这个 cordis 服务就在同一个进程里，插件可直接调。
+   *
+   * 可选的原因同 [attachments]：0.2.0-rc.2 的 web profile 上没有它。
    */
-  fileUploads: FileUploadsLike;
+  fileUploads?: FileUploadsLike;
   /**
    * Cordis event bus of the host context. Used for the two facts the old
    * `apiProxy` event streams carried that no controller returns: session

package/lib/index.js

@@ -1,4 +1,4 @@
-import path, { join } from "node:path";
+import path, { join, sep } from "node:path";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { execFile, spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
@@ -134,10 +134,22 @@ function isLoopbackOrigin(origin) {
 }
 //#endregion
 //#region src/host/cloudflared.ts
-/** 平台/架构 -> cloudflared 归档后缀。 */
-function archSuffix(platform = process.platform) {
+/**
+* 平台/架构 -> cloudflared 归档后缀。
+*
+* **架构必须能单独传**，不能读 `process.arch`：
+* 2026-10-20 CI 实锤 —— 旧实现里 platform 是参数、arch 却写死 `process.arch`，
+* 于是 `archSuffix('linux')` 在 macOS runner（arm64）上返回 `linux-arm64`，
+* 而调用方要的是「linux 平台该用哪个官方归档」。同一函数里 platform 可控、
+* arch 不可控，是**自相矛盾的设计**；测试在 macOS 上红、Linux 上绿，全平台矩阵
+* （ubuntu/windows/macos × 两个 Node 版本）里只有 Linux 那两格能过。
+*
+* 两个参数都带默认值时保持旧行为（本机平台 + 本机架构）；显式传入时，
+* 结果只由入参决定 —— 这才让「算一个别的平台的后缀」成为可能。
+*/
+function archSuffix(platform = process.platform, arch = process.arch) {
 	if (platform !== "linux") throw new Error(`cloudflared 尚不支持 ${platform} 平台。`);
-	switch (process.arch) {
+	switch (arch) {
 		case "x64": return "linux-amd64";
 		case "arm64": return "linux-arm64";
 		default: throw new Error(`cloudflared 尚不支持 ${process.arch} 架构。`);
@@ -197,8 +209,20 @@ function isDebSource() {
 	return mirrorBase().startsWith("deb+");
 }
 /** 返回要下载的源 URL：deb 源返回完整 .deb 地址；裸镜像基址拼架构后缀；否则官方 GitHub。 */
-function downloadUrlFor() {
-	const suffix = archSuffix();
+/**
+* cloudflared 官方归档的下载地址。
+*
+* **platform/arch 都能显式传入**（2026-10-20 CI 实锤后加）：旧实现里
+* `downloadUrlFor()` 走 `archSuffix()` 的默认参数 —— 也就是**本机** platform/arch。
+* 于是这个函数在 macOS runner 上直接抛「尚不支持 darwin 平台」，
+* 而它要回答的问题其实是「linux 的 cloudflared 该从哪下」。
+*
+* 默认值保持本机（生产调用点 `ensureCloudflared` 就在 linux 上跑，行为不变），
+* 但显式传入后结果只由入参决定 —— 这才让「算别的平台的 URL」成为可能，
+* 也让测试不依赖跑在什么机器上。
+*/
+function downloadUrlFor(platform = process.platform, arch = process.arch) {
+	const suffix = archSuffix(platform, arch);
 	const mirror = mirrorBase();
 	if (mirror === "") return `${OFFICIAL_BASE}${suffix}`;
 	if (mirror.startsWith("deb+")) return mirror.slice(4);
@@ -796,7 +820,33 @@ function parentWirePath(relativePath) {
 * 调用方必须自己给出可读的错误（见 readAttachment），而不是让用户看到一个
 * 语焉不详的 500。
 */
+/**
+* 读一个**可选**宿主服务：存在就返回，不存在返回 null。
+*
+* ## 为什么必须走 `ctx.reflect.get(name, false)`，不能直接读属性
+*
+* cordis 的 `inject` 是**硬依赖**（`registry.d.ts` 的 `Inject` 类型只有数组与映射两种
+* 形式，注释原文是 "required services"）：inject 里任何一个服务缺失，`_refresh()`
+* 就把 epoch 置为 INACTIVE，**整个插件不激活**。
+*
+* 所以「可选服务」**不能**写进 inject —— 写了就变成「哪个内核版本缺它、插件在哪一版
+* 整个死掉」。而直接读属性（`host[name]`）也不行：不在 inject 里的属性会抛
+* `cannot get property "x" without inject`，与「服务不存在」**报同一个错**，
+* 于是这个函数会永远返回 null（这正是它此前的实际行为，
+* `attachments` / `fileUploads` 一直在走降级路径）。
+*
+* `ctx.reflect.get(name, false)` 是 cordis 给这件事准备的正路
+* （`cordis/lib/index.js` 的 ReflectService.get，注释原文：
+* "Read a service from the store **without the inject requirement**"）：
+* 不要求 inject 声明，服务不存在时返回 `undefined` 而不是抛错。
+*/
 function optionalService(host, name) {
+	const reflect = host.reflect;
+	if (reflect !== void 0 && typeof reflect.get === "function") try {
+		const value = reflect.get(name, false);
+		if (value === void 0 || value === null) return null;
+		return value;
+	} catch {}
 	try {
 		return host[name];
 	} catch {
@@ -1413,7 +1463,7 @@ function writeHandoffFile(dir, workspace, mediaType, data) {
 	if (!existsSync(absolute)) writeFileSync(absolute, bytes, { mode: 384 });
 	return {
 		absolute,
-		relative: workspace !== void 0 && absolute.startsWith(workspace + "/") ? absolute.slice(workspace.length + 1) : fileName
+		relative: workspace !== void 0 && absolute.startsWith(workspace + sep) ? absolute.slice(workspace.length + 1).split(sep).join("/") : fileName
 	};
 }
 /** 交接文件名只允许「内容哈希 + 图片扩展名」：挡住一切路径穿越。 */
@@ -2013,7 +2063,13 @@ function createDsh02ApiProxy(host, options = {}) {
 					settingsNs: entry.settingsNs,
 					settingsPath: [...entry.settingsPath],
 					active: live.has(entry.provider),
-					...entry.declared === void 0 ? {} : { declared: entry.declared }
+					...entry.declared === void 0 ? {} : { declared: entry.declared },
+					...entry.defaultBaseURL === void 0 ? {} : { defaultBaseURL: entry.defaultBaseURL },
+					...entry.baseURLEnv === void 0 ? {} : { baseURLEnv: [...entry.baseURLEnv] },
+					...entry.nativeAuth === void 0 ? {} : { nativeAuth: {
+						...entry.nativeAuth,
+						...entry.nativeAuth.env === void 0 ? {} : { env: [...entry.nativeAuth.env] }
+					} }
 				})) };
 			}),
 			models: () => call(async () => {
@@ -2036,7 +2092,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.4.3";
+const PLUGIN_VERSION = "2.5.0";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -3235,10 +3291,51 @@ function redactApprovalText(value, maxLength = 1200) {
 }
 //#endregion
 //#region src/host/database.ts
+/**
+* 本进程内打开的库（弱引用集合）。
+*
+* ## 为什么需要它
+*
+* `WorkspaceDatabase` 用 `PRAGMA journal_mode=WAL` 打开 sqlite，会留下
+* `workspace.sqlite` / `-wal` / `-shm` 三个文件，**且句柄不关就删不掉**。
+* Linux/macOS 上删一个仍被打开的文件是允许的（unlink 只是断链），所以问题
+* 在那里看不出来；**Windows 上直接 EBUSY**：
+*
+* ```
+* EBUSY: resource busy or locked, unlink 'C:\...\Temp\daw-xxx\state\workspace.sqlite'
+* ```
+*
+* 2026-10-20 CI 在 windows-latest 上实锤（macOS/Linux 全绿、Windows 全红）。
+*
+* ## 它的作用
+*
+* 进程退出时统一关闭所有还开着的库 —— 无论调用方记不记得 `close()`。
+* 这不是「代替 close」，而是**兜底**：正常路径仍应显式 close（早关早释放），
+* 但漏掉的那一个不会在 Windows 上变成 EBUSY 式的删除失败。
+*
+* 弱引用：不阻止 GC，也不阻止正常 close 后的移除（close 时会从集合里摘掉）。
+*/
+const openDatabases = /* @__PURE__ */ new Set();
+/** 进程退出时尽力关闭所有还开着的库。 */
+function closeAllOpenDatabases() {
+	for (const ref of [...openDatabases]) {
+		const db = ref.deref();
+		if (db === void 0) {
+			openDatabases.delete(ref);
+			continue;
+		}
+		try {
+			db.close();
+		} catch {}
+	}
+	openDatabases.clear();
+}
+process.once("exit", closeAllOpenDatabases);
 var WorkspaceDatabase = class {
 	dataDir;
 	trashDir;
 	db;
+	closed = false;
 	constructor(dataDir) {
 		this.dataDir = path.resolve(dataDir);
 		this.trashDir = path.join(this.dataDir, "trash");
@@ -3246,8 +3343,13 @@ var WorkspaceDatabase = class {
 		this.db = new DatabaseSync(path.join(this.dataDir, "workspace.sqlite"));
 		this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
 		this.migrate();
+		openDatabases.add(new WeakRef(this));
 	}
+	/** 关闭数据库。**幂等** —— 重复调用不抛错。 */
 	close() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const ref of [...openDatabases]) if (ref.deref() === this) openDatabases.delete(ref);
 		this.db.close();
 	}
 	/**
@@ -4064,7 +4166,14 @@ function trashView(record) {
 * 使用方式：`GET /dsh-workspace-api/api/v1/debug/host-services`
 * （需要设备 token 或 loopback admin，与其它 REST 端点同一套鉴权）。
 */
-/** 插件 `src/index.ts` 里 inject 声明的全部服务名。 */
+/**
+* 插件 `cordis.patch.yml` 与 `src/index.ts` 里 inject 声明的全部服务名
+* （**两份清单必须一致**，docs:check 有对齐门禁）。
+*
+* ⚠️ 只能放「两个支持版本（0.2.0-rc.2 与 0.2.1-rc.2）上都存在的服务」——
+* cordis 的 inject 是硬依赖，缺一个整个插件不激活（2026-10-20 在 0.2.0-rc.2 的
+* smoke-profile-install 上实锤过）。可选服务一律走 OPTIONAL_SERVICE_NAMES。
+*/
 const INJECTED_SERVICE_NAMES = [
 	"sessionController",
 	"workspaceController",
@@ -4072,17 +4181,26 @@ const INJECTED_SERVICE_NAMES = [
 	"settingsController",
 	"credentialsController",
 	"agentPresets",
-	"permissionPresets",
 	"llm",
 	"webServer",
 	"agents",
-	"commands",
+	"commands"
+];
+/**
+* **可选服务**：不写进 inject（inject 是硬依赖），由插件经
+* `ctx.reflect.get(name, false)` 运行时读取 —— 读到就走该能力，读不到按能力位降级。
+*
+* 探针用同一条 `reflect.get` 读取它们：这样报告的是「内核**真的**提供了什么」，
+* 而不是「我们 inject 了什么」。两者的差就是「可选能力在这台内核上可用与否」。
+*/
+const OPTIONAL_SERVICE_NAMES = [
+	"permissionPresets",
 	"jobController",
 	"fileUploads",
-	"attachments"
+	"attachments",
+	"workingDirectory",
+	"workspaceFiles"
 ];
-/** 0.2.1 新增、插件尚未 inject 但已确认存在于 web profile 的服务。 */
-const OBSERVED_ONLY_SERVICE_NAMES = ["workingDirectory", "workspaceFiles"];
 /**
 * 在注入属性**仍可读**的时机（即 `apply` 执行期间）逐个试读服务。
 *
@@ -4096,6 +4214,32 @@ const OBSERVED_ONLY_SERVICE_NAMES = ["workingDirectory", "workspaceFiles"];
 * @returns 每个服务的可解析性报告。
 */
 function probeHostServices(host, pluginVersion) {
+	const reflect = host.reflect;
+	const probeOptional = (name) => {
+		if (reflect === void 0 || typeof reflect.get !== "function") return {
+			name,
+			available: false,
+			resolvable: false,
+			error: "ctx.reflect.get unavailable on this cordis"
+		};
+		try {
+			const value = reflect.get(name, false);
+			const resolvable = value !== null && value !== void 0;
+			return {
+				name,
+				available: true,
+				resolvable,
+				...resolvable ? {} : { error: "not provided by this kernel/profile" }
+			};
+		} catch (caught) {
+			return {
+				name,
+				available: false,
+				resolvable: false,
+				error: caught instanceof Error ? caught.message : String(caught)
+			};
+		}
+	};
 	const probeOne = (name) => {
 		let available = false;
 		let resolvable = false;
@@ -4116,7 +4260,7 @@ function probeHostServices(host, pluginVersion) {
 		};
 	};
 	const injected = INJECTED_SERVICE_NAMES.map(probeOne);
-	const observed = OBSERVED_ONLY_SERVICE_NAMES.map(probeOne);
+	const observed = OPTIONAL_SERVICE_NAMES.map(probeOptional);
 	return {
 		pluginVersion,
 		injected,
@@ -4125,7 +4269,7 @@ function probeHostServices(host, pluginVersion) {
 			injectedTotal: injected.length,
 			injectedAvailable: injected.filter((service) => service.available).length,
 			injectedMissing: injected.filter((service) => !service.available).map((service) => service.name),
-			observedAvailable: observed.filter((service) => service.available).map((service) => service.name)
+			observedAvailable: observed.filter((service) => service.resolvable).map((service) => service.name)
 		}
 	};
 }
@@ -4787,20 +4931,36 @@ function timestamp() {
 //#endregion
 //#region src/host/root-resolver.ts
 /**
-* 在授权根集合里找出包含该绝对路径的那一个（**纯字符串匹配，不触碰文件系统**）。
+* 与 [matchAuthorizedRoot] 相同，但**两侧都做 realpath 归一**再比较。
+*
+* ## 为什么需要它
 *
-* 多个根相互嵌套时取**最长**的那个 —— 否则外层根会把内层根下的文件解析成更长的相对路径，
-* 虽然仍能读到同一文件，但会绕过内层根更严格的授权语义。
+* 授权根在入库时走了 `canonicalRoot()`（`database.ts` 的 addRoot），存的是**解析过
+* 符号链接**的路径；而客户端请求里的路径通常**没解析**。两者字面不同就匹配不上，
+* 结果是「明明在授权根内」却报 404 `PATH_OUTSIDE_ROOTS`。
 *
-* 注意这只是粗筛：字符串前缀相等不代表真实落在根内（根内可能存在指向外部的符号链接）。
-* 真正的安全校验由 [inspectResolvedPath] 经 `resolveAuthorizedPath` 完成。
+* 最常见的触发场景就是 **macOS 的临时目录**：`os.tmpdir()` 给的是
+* `/var/folders/...`，而它是指向 `/private/var/folders/...` 的**符号链接**。
+* 于是测试里 `mkdtemp(os.tmpdir())` 造出的根与请求路径字面不一致 → 404。
+* 2026-10-20 CI 在 macOS runner 上实锤（Linux 上 tmpdir 不带 symlink，所以只在 macOS 炸）。
+*
+* 这不只是测试问题：用户给一个经 symlink 的路径加授权根、或客户端用 symlink 别名
+* 请求，都会踩到。**归一后两侧是同一条真实路径**，语义也就正确了。
+*
+* ## 安全边界不变
+*
+* 归一只解决「同一个目录的两种写法」，**不放宽**任何权限：
+* 真正的越权校验仍由 [inspectResolvedPath] → `resolveAuthorizedPath` 逐段做
+* （它会拒绝指向根外的符号链接）。这里只是把「找哪个根」这一步做准。
 */
-function matchAuthorizedRoot(absolutePath, roots) {
+async function matchAuthorizedRootResolved(absolutePath, roots) {
+	const candidate = await canonicalOrSelf(absolutePath);
 	let best;
 	for (const root of roots) {
-		const relative = wireRelative(root.realPath, absolutePath);
+		const canonicalRoot = await canonicalOrSelf(root.realPath);
+		const relative = wireRelative(canonicalRoot, candidate);
 		if (relative === void 0) continue;
-		if (best === void 0 || root.realPath.length > best.root.realPath.length) best = {
+		if (best === void 0 || canonicalRoot.length > best.root.realPath.length) best = {
 			root,
 			relative
 		};
@@ -4810,6 +4970,14 @@ function matchAuthorizedRoot(absolutePath, roots) {
 		path: best.relative
 	};
 }
+/** 取路径的真实形式；取不到（路径不存在、无权限等）就原样返回。 */
+async function canonicalOrSelf(target) {
+	try {
+		return await realpath(target);
+	} catch {
+		return target;
+	}
+}
 const CONTENT_TYPES = {
 	".md": "text/markdown",
 	".txt": "text/plain",
@@ -5071,7 +5239,7 @@ var ApiRouter = class {
 			const requested = url.searchParams.get("path")?.trim() ?? "";
 			if (requested === "") throw new ApiError(400, "BODY_INVALID", "path is required.");
 			if (!path.isAbsolute(requested)) throw new ApiError(400, "PATH_NOT_ABSOLUTE", "path must be an absolute path.");
-			const match = matchAuthorizedRoot(path.resolve(requested), this.authorizedRoots(principal));
+			const match = await matchAuthorizedRootResolved(path.resolve(requested), this.authorizedRoots(principal));
 			if (match === void 0) throw new ApiError(404, "PATH_OUTSIDE_ROOTS", "The path is not inside any root this device may access.");
 			sendJson(res, 200, await inspectResolvedPath(this.requireRoot(principal, match.rootId), match.path));
 			return;
@@ -6424,6 +6592,10 @@ var DshSettingsAdapter = class {
 					configurable: entry.settingsNs !== "",
 					configured,
 					removable,
+					...entry.defaultBaseURL === void 0 ? {} : { defaultBaseURL: entry.defaultBaseURL },
+					...entry.baseURLEnv === void 0 ? {} : { baseURLEnv: entry.baseURLEnv },
+					...entry.nativeAuth === void 0 ? {} : { nativeAuth: entry.nativeAuth },
+					...entry.settingsNs === "" ? {} : { settingsNs: entry.settingsNs },
 					credential: {
 						ref,
 						...credential
@@ -6463,12 +6635,18 @@ var DshSettingsAdapter = class {
 			});
 		}
 		if (patch.models !== void 0) {
-			validateModels(patch.models);
-			ops.push({
-				op: "set",
-				path: [...context.entry.settingsPath, "models"],
-				value: patch.models
+			if (patch.models === null) ops.push({
+				op: "unset",
+				path: [...context.entry.settingsPath, "models"]
 			});
+			else {
+				validateModels(patch.models);
+				ops.push({
+					op: "set",
+					path: [...context.entry.settingsPath, "models"],
+					value: patch.models
+				});
+			}
 		}
 		const ref = text(context.profile?.apiKeyEnv) ?? keyRef(providerId);
 		if (context.entry.settingsPath.length > 0 && context.profile === void 0) ops.unshift({
@@ -6718,14 +6896,10 @@ const inject = [
 	"settingsController",
 	"credentialsController",
 	"agentPresets",
-	"permissionPresets",
 	"llm",
 	"webServer",
 	"agents",
-	"commands",
-	"jobController",
-	"fileUploads",
-	"attachments"
+	"commands"
 ];
 async function apply(ctx, config = {}) {
 	const dataDir = path.resolve(config.dataDir ?? path.join(process.cwd(), ".dsh-workspace"));
@@ -6770,13 +6944,9 @@ async function apply(ctx, config = {}) {
 		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: host service probe failed: ${String(error)}`));
 	}
 	let router;
-	let jobControllerAvailable = false;
-	try {
-		ctx.jobController;
-		jobControllerAvailable = true;
-	} catch {
-		ctx.logger.warn(/* @__PURE__ */ new Error("dsh-remote-bridge: ctx.jobController unavailable, background-job endpoints disabled"));
-	}
+	const reflect = ctx.reflect;
+	const jobControllerAvailable = reflect?.get !== void 0 && reflect.get("jobController", false) !== void 0;
+	if (!jobControllerAvailable) ctx.logger.warn(/* @__PURE__ */ new Error("dsh-remote-bridge: jobController not provided by this kernel, background-job endpoints disabled"));
 	const remote = new RemoteApiServer({
 		port,
 		remoteHost,
@@ -6798,7 +6968,7 @@ async function apply(ctx, config = {}) {
 		maxUploadBytes,
 		imageFallbackDir: imageHandoffDir,
 		...hostServiceReport === void 0 ? {} : { hostServiceReport },
-		...jobControllerAvailable ? { jobs: new JobAdapter({ jobController: ctx.jobController }) } : {}
+		...jobControllerAvailable && reflect?.get ? { jobs: new JobAdapter({ jobController: reflect.get("jobController", false) }) } : {}
 	});
 	try {
 		await remote.start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-bridge",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "Versioned REST bridge for DeepSeek Harness: remote access for trusted clients (chat, files, devices) plus a Phone-settings panel inside the DSH WebUI.",
   "type": "module",
   "packageManager": "pnpm@11.19.0",