@dshfly/remote-connector 0.2.1

package/index.js

@@ -0,0 +1,173 @@
+// packages/remote-connector/index.js
+// @dshfly/remote-connector —— DeepSeek Harness (DSH) cordis 插件入口（host 侧）。
+//
+// 把原独立 connector 进程（services/connector）搬进 dsh web 进程：
+//   出站连中继（纯出站 WSS）+ E2EE 终点 + loopback 反代 dsh web(/api + events.mux/.host)
+//   + /dshfly 控制路由（loopback-only）
+//   + ctx.mobileBridge 服务承载（M4.x-c 整合决策 1b：bridge 是纯库，本插件是服务所有者——
+//     装本插件一个命令即带出移动端插件能力，无独立安装/时序问题）。
+//
+// cordis 插件契约：name / inject / Config / apply。
+// 参考实现：@orbisapp/remote-dsh（orbis），方案见 docs/connector-plugin.md。
+
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { ConnectorCore } from './core/connector-core.js';
+import { createDshflyHttpRoute, installRecommendedPlugin, uninstallPlugin, resolveDshVersion, resolveDshNodeModules } from './http-api.js';
+import { resolveConfig, validateConfig, Config } from './config.js';
+import { MobileBridgeCore, createMobileBridgeService, resolveProfileDir } from './mobile-bridge/index.js';
+import { createDshAdapter } from './core/dsh-web.js';
+
+const require = createRequire(import.meta.url);
+/** 本插件版本（设置页显示 + 升级检查；发布时 pnpm 替换为实际版本号）。 */
+const selfVersion = require('./package.json').version;
+
+export const name = 'dshfly-remote-connector';
+// 最小依赖：只有 /dshfly 路由需要 webServer；隧道是纯出站，不需要 DSH 业务服务。
+export const inject = ['webServer'];
+export { Config };
+
+/** 默认密钥路径：<dshHome>/dshfly/keys.json（决策：从新路径全新开始，不迁移旧 ~/.dshfly）。 */
+async function defaultKeysPath() {
+  try {
+    const { resolveDshHome } = await import('@deepseek-ai/dsh-home-paths');
+    return path.join(resolveDshHome(), 'dshfly', 'keys.json');
+  } catch {
+    // 非 DSH 宿主环境（单测/开发）：用独立临时目录，避免污染真实密钥
+    return path.join(os.tmpdir(), 'dshfly-plugin', 'keys.json');
+  }
+}
+
+export async function apply(ctx, config = {}) {
+  const cfg = resolveConfig(config);
+
+  // 硬约束（决策 8，已定案）：配对控制路由含一次性密钥，必须 loopback-only。
+  if (!ctx.webServer || ctx.webServer.host !== '127.0.0.1') {
+    throw new Error(
+      'dshfly-remote-connector requires dsh web to bind 127.0.0.1 (loopback-only pairing controls)',
+    );
+  }
+
+  // 业务配置校验：默认值即可用（relayUrl 内建；D1 无账号层），
+  // 仅当显式覆盖成非法值时 warn + 跳过启动（不抛错——DSH 是 fail-loud 启动，
+  // apply 抛错会拖垮整个 dsh web；跳过则插件空转，配置后重启生效）。
+  const errors = validateConfig(cfg);
+  if (errors.length) {
+    console.warn(
+      `[dshfly-remote-connector] 配置无效，跳过启动: ${errors.join('; ')}` +
+      '（默认 relayUrl=https://relay.dshfly.com，一般无需配置）',
+    );
+    return;
+  }
+
+  // M4.x-c（整合决策 1b）：本插件承载 ctx.mobileBridge 服务。
+  // 先 provide（插件只要在本插件之后 apply 即可注册），枚举后台化不阻塞启动。
+  // 文件树（docs/file-tree-plan.md）：注入 loopback 根白名单解析器（工作区 ∪ 主机 cwd），
+  // 每次 files.* 调用实时取，工作区增删即时生效；loopback 失败 fail-closed（空白名单）。
+  const dshAdapter = createDshAdapter({
+    // 惰性函数：typertGateway 依赖 connection，激活可能晚于只依赖 webServer 的 connector；
+    // 请求时再取，确保拿到最新服务实例。
+    gateway: () => ctx?.get?.('typertGateway') ?? null,
+    ctx,
+    // host.describe（DSH 版本/主机工作目录/host.commectorVersion）：合成时填 DSH 包版本
+    // （无 host 命名空间可查）；connectorVersion = 本连接器插件（@dshfly/remote-connector）自身
+    // 版本（运行中已安装包），供手机端配对设备详情页展示。
+    dshVersion: resolveDshVersion(cfg.dshBin || ''),
+    connectorVersion: selfVersion,
+  });
+  // 2026-09：附件树根白名单经进程内 DSH 适配层取工作区（loopback HTTP 旧路径已 401/端点删除）。
+  const resolveRoots = async () => {
+    try {
+      const r = await dshAdapter.workspaceList();
+      return (r?.ok ? r.value?.items || [] : []).map((i) => i?.path).filter((p) => typeof p === 'string' && p);
+    } catch {
+      return [];
+    }
+  };
+  const bridgeCore = new MobileBridgeCore({
+    profileDir: resolveProfileDir(cfg),
+    resolveRoots,
+    // 2026-09：dsh.profile.bundles 里混有 DSH 内置运行时 bundle（@deepseek-ai/dsh-base 等），
+    // 它们在 DSH 应用 node_modules、不在 profile node_modules → 传入 DSH 应用 node_modules 作为
+    // 额外解析根，避免把 DSH 内置包误报为"bundle 目录解析失败"。
+    bundleResolveRoots: [resolveDshNodeModules()].filter(Boolean),
+  });
+  // App 插件页空状态"一键安装"：注入推荐插件安装器（与设置页 /dshfly/plugins/install 同一实现）
+  bridgeCore.setPluginInstaller((id) =>
+    installRecommendedPlugin({
+      id,
+      recommendedPlugins: cfg.recommendedPlugins || [],
+      bridgeCore,
+      loader: ctx.get('loader') ?? null,
+      dshBin: cfg.dshBin || '',
+      profileName: cfg.profileName,
+    }),
+  );
+  // App 插件详情页"卸载"：注入卸载器（与设置页 /dshfly/plugins/uninstall 同一实现）
+  bridgeCore.setPluginUninstaller((id) =>
+    uninstallPlugin({
+      id,
+      recommendedPlugins: cfg.recommendedPlugins || [],
+      bridgeCore,
+      loader: ctx.get('loader') ?? null,
+      dshBin: cfg.dshBin || '',
+      profileName: cfg.profileName,
+    }),
+  );
+  ctx.provide('mobileBridge', createMobileBridgeService(bridgeCore));
+  // 枚举后台化不阻塞启动（决策 10）；幂等——listPlugins 会复用同一 promise 等它完成，
+  // 消除"插件动态 register 先到、枚举未完成"导致 staticSource 缺失（插件 ID 回退短 id）的竞态。
+  bridgeCore.ensureEnumerated();
+
+  const core = new ConnectorCore({
+    relayUrl: cfg.relayUrl,
+    deviceName: cfg.deviceName || os.hostname(),
+    keysFile: cfg.keysPath || (await defaultKeysPath()),
+    target: cfg.target || 'http://127.0.0.1:3080',
+    // 2026-09：DSH 0.1.2 起 /api 需 browser-session cookie 且协议结构性改动。同进程内直接调
+    // DSH typertGateway（免 HTTP 认证 + 免 remote.mux 线协议）；gateway 不可用时 adapter
+    // 返回业务错误（不拖垮 dsh web）。
+    dshAdapter,
+  });
+  // 接线：mobile.* RPC 本地处理 + 插件事件注入隧道（connector-core 的 setMobileBridge）
+  core.setMobileBridge(createMobileBridgeService(bridgeCore));
+
+  // 启动时序（决策 10）：cordis 保证 inject 的服务（webServer）先于插件 apply 激活，
+  // webServer 的 [Service.init] 即 socket bind（"Activation listens immediately"），
+  // 因此 apply 时目标（127.0.0.1:3080 自环）已可连；tunnel.js 的事件 WS 首连仍有
+  // 指数退避重试兜底（路由注册顺序导致的瞬态失败会在 1s 后自愈）。
+  //
+  // 启动容错：登记/连中继失败（如网络不可达）时 warn + 跳过，不拖垮 dsh web；
+  // 恢复后重启 dsh web（或未来 M4 加自动重试）即可。
+  try {
+    await core.start();
+  } catch (e) {
+    console.warn(`[dshfly-remote-connector] 启动失败，跳过（重启 dsh web 可重试）: ${e.message}`);
+    return;
+  }
+  await bridgeCore.ensureEnumerated(); // 复用第 96 行触发的同一枚举 promise（幂等），等待静态枚举完成
+  if (bridgeCore.entries.size === 0 && bridgeCore.health.length === 0) {
+    console.log('[dshfly-remote-connector] profile 无移动端插件（或 profile 不存在）——插件 Tab 将显示空状态');
+  } else if (bridgeCore.health.length) {
+    console.warn(`[dshfly-remote-connector] 移动端插件健康报告: ${JSON.stringify(bridgeCore.health)}`);
+  }
+
+  ctx.effect(async () => {
+    const disposeRoute = ctx.webServer.register(
+      createDshflyHttpRoute(core, {
+        autoConfirm: cfg.autoConfirm,
+        bridgeCore,
+        loader: ctx.get('loader') ?? null, // 一键安装热加载（沙箱 ctx 已验证可获取）
+        recommendedPlugins: cfg.recommendedPlugins || [],
+        dshBin: cfg.dshBin || '',
+        profileName: cfg.profileName,
+        version: selfVersion, // 本插件本地版本（设置页显示 + 升级检查）
+      }),
+    );
+    return async () => {
+      disposeRoute();
+      core.stop();
+    };
+  }, 'dshfly-remote-connector: lifecycle');
+}

package/mobile-bridge/README.md

@@ -0,0 +1,33 @@
+# @dshfly/mobile-bridge
+
+DSH 移动端插件规范的**实现库**（M4.x-c）。**注意（2026-08-17 整合决策 1b）：本包已不是独立 cordis 插件**——`ctx.mobileBridge` 服务由 [`@dshfly/remote-connector`](../remote-connector/) 承载（它拥有传输层，是服务的天然所有者）。本包是 connector 的运行时依赖，随 connector 一起安装，**不能也不应单独安装**。
+
+规范正文见 [`docs/mobile-plugin-spec.md`](../../docs/mobile-plugin-spec.md)。
+
+## 提供什么
+
+```
+MobileBridgeCore（core/bridge-core.js）  # 枚举/注册表/RPC/事件（纯 Node，可单测）
+createMobileBridgeService(core)          # 把 core 包装成服务对象（connector ctx.provide 用）
+readProfileBundles / resolveBundleDir    # 枚举 dsh.profile.bundles → 包目录
+resolveProfileDir                        # <dshHome>/profiles/<profileName> 解析
+```
+
+## 服务契约（消费方不变）
+
+- **功能插件**：`ctx.mobileBridge.register({manifest, handler})` / `unregister` / `emit`——与整合前完全一致；
+- **传输层**（当前只有 connector）：`handleRpc(method, payload)` + `onEvent(sink)`。
+
+## 为什么整合
+
+桥单独安装没有传输层，等于无用（手机无法触达）；整合后：
+- 装 `@dshfly/remote-connector` 一个命令即带出全部能力；
+- bridge 非 bundle，无法被单独误装（"装了没用"的状态空间消失）；
+- 无插件加载时序问题（服务随 connector 同步提供）；
+- 规范实现与通道实现仍在不同包：未来 DSH 上游若吸收移动端规范，本库可直接上贡。
+
+## 测试
+
+```bash
+pnpm --filter @dshfly/mobile-bridge test
+```

package/mobile-bridge/core/bridge-core.js

@@ -0,0 +1,367 @@
+// core/bridge-core.js —— MobileBridgeCore：规范实现的核心（纯 Node，无 cordis 依赖，可单测）。
+//
+// 职责（spec §4/§5）：
+//   枚举    profile bundles → package.json 的 dshfly.mobile → 两级校验 → 静态注册表
+//   注册    动态 register（同 id 覆盖静态，v0.1 定稿决策）/ unregister
+//   RPC     listPlugins / getHome / invoke / subscribe（错误码对齐 spec §5.3）
+//   事件    emit → 扇出给传输层 sink（frame: {type:'mobile/event', pluginId, event:{name,payload}}）
+//
+// 规则：
+//   - listPlugins 只列"可交互"（已注册 handler）的插件；仅静态声明（未注册）的插件
+//     留在内部注册表 + health，供 PC 设置页健康报告。
+//   - handler 由插件自己注册（cordis 场景：插件 inject mobileBridge 服务后调 register）；
+//     handler = { getHome?(params), invoke?(actionId, params), getBadge?() }。
+//   - 事件扇出 v1 为广播（所有已连接设备都收到 mobile/event，App 端按 pluginId 过滤）；
+//     per-device 订阅优化留给传输层/App 端（spec §5.1 subscribe 语义）。
+
+import { validateMobileManifest, readMobileManifest } from '@dshfly/mobile-plugin-schema';
+import { readProfileBundles, resolveBundleDir } from './enumerate.js';
+import { FilesService } from './files.js';
+
+export class MobileBridgeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** 默认语言（旧 App 不发 lang 时兜底）。 */
+const DEFAULT_LANG = 'zh';
+
+/** 解析 manifest 文本字段：string → 原样；{zh,en} → 按请求语言取（缺省/未知回退 zh，再回退 en/任意键）。 */
+function resolvePluginString(value, lang) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') {
+    if (typeof value[lang] === 'string' && value[lang]) return value[lang];
+    if (typeof value.zh === 'string' && value.zh) return value.zh;
+    if (typeof value.en === 'string' && value.en) return value.en;
+    for (const k of Object.keys(value)) if (typeof value[k] === 'string' && value[k]) return value[k];
+  }
+  return '';
+}
+
+export class MobileBridgeCore {
+  /** @param {{profileDir?: string|null, resolveRoots?: () => Promise<string[]>, bundleResolveRoots?: string[]}} opts
+   *   profileDir=null 时只支持动态注册（单测/无 DSH 宿主场景）。
+   *   resolveRoots：文件树服务（mobile.files.*，方案 docs/file-tree-plan.md）的根白名单提供者，
+   *   由宿主（remote-connector）注入；未注入时 files.* RPC 返回 INTERNAL。
+   *   bundleResolveRoots：额外 bundle 解析根（如 DSH 应用自身的 node_modules）。DSH 的
+   *   dsh.profile.bundles 里混有"DSH 内置运行时 bundle"（@deepseek-ai/dsh-base 等，在 DSH 应用
+   *   node_modules，不在 profile node_modules）——枚举时先查 profile node_modules，找不到再查这些
+   *   附加根，避免把 DSH 内置包误报为"bundle 目录解析失败"。 */
+  constructor({ profileDir = null, resolveRoots = null, bundleResolveRoots = [] } = {}) {
+    this.profileDir = profileDir;
+    /** 额外 bundle 解析根（DSH 应用 node_modules 等）。 */
+    this.bundleResolveRoots = Array.isArray(bundleResolveRoots) ? bundleResolveRoots.filter((d) => typeof d === 'string' && d) : [];
+    /** 文件树只读服务（mobile.files.list/read）。 */
+    this.files = resolveRoots ? new FilesService({ resolveRoots }) : null;
+    /** @type {Map<string, {manifest: object, staticSource: string|null, handler: object|null, registeredAt: number|null}>} */
+    this.entries = new Map();
+    /** @type {Array<{pluginId?: string, message: string}>} PC 设置页健康报告。 */
+    this.health = [];
+    /** @type {Set<(frame: object) => void>} 传输层事件 sink。 */
+    this.sinks = new Set();
+    /** @type {(() => {frames: object[]}) | null} 方案 A：pending 审批/提问缓存提供者
+     *  （connector 在 dsh 事件流上镜像；手机连接恢复时经 mobile.approvals.list 拉取，
+     *   补齐手机离线期间被 relay 丢弃的审批事件）。 */
+    this._pendingApprovalProvider = null;
+    /** 静态枚举的幂等 promise（2026-08 修竞态）：listPlugins 等它完成，避免
+     *  "插件动态 register 先到、enumerate 后台未完成"时 staticSource 缺失（详情页
+     *  插件 ID 回退成短 id 而非 npm 全局标识）。 */
+    this._enumeratePromise = null;
+  }
+
+  /** 静态枚举（幂等）：返回同一 promise，确保只跑一次；listPlugins 等待其完成以拿到
+   *  staticSource（npm 包名）。profileDir 缺失/枚举失败 → resolve（失败静默，仅动态注册）。 */
+  ensureEnumerated() {
+    if (this._enumeratePromise) return this._enumeratePromise;
+    if (!this.profileDir) { this._enumeratePromise = Promise.resolve(); return this._enumeratePromise; }
+    this._enumeratePromise = this.enumerate().catch((e) => {
+      console.warn(`[mobile-bridge] 枚举移动端插件失败，仅支持动态注册: ${e.message}`);
+    });
+    return this._enumeratePromise;
+  }
+
+  /** 静态枚举：profile bundles → dshfly.mobile 声明 → 两级校验 → 注册表 upsert。 */
+  async enumerate() {
+    this.health = [];
+    if (!this.profileDir) return;
+    for (const name of readProfileBundles(this.profileDir)) {
+      const dir = resolveBundleDir(this.profileDir, name, this.bundleResolveRoots);
+      if (!dir) {
+        this.health.push({ pluginId: name, message: 'bundle 目录解析失败（node_modules 中不存在）' });
+        continue;
+      }
+      const read = readMobileManifest(dir);
+      if (!read.found) continue; // 不是移动端插件，正常跳过
+      const v = validateMobileManifest(read.manifest);
+      if (!v.ok) {
+        this.health.push({
+          pluginId: name,
+          message: `manifest 结构无效: ${v.errors.map((e) => `${e.path} ${e.message}`).join('; ')}`,
+        });
+        continue;
+      }
+      const m = read.manifest;
+      const existing = this.entries.get(m.id);
+      if (existing) {
+        existing.staticSource = name; // 动态注册先到（如热重载）：只补静态来源
+      } else {
+        this.entries.set(m.id, { manifest: m, staticSource: name, handler: null, registeredAt: null });
+      }
+    }
+  }
+
+  /** 动态注册（spec §4.1 ③）。handler 必带；同 id 覆盖静态 manifest（定稿决策）。 */
+  register({ manifest, handler } = {}) {
+    const v = validateMobileManifest(manifest);
+    if (!v.ok) return { ok: false, errors: v.errors, warnings: v.warnings };
+    const id = manifest.id;
+    const existing = this.entries.get(id);
+    this.entries.set(id, {
+      manifest,
+      staticSource: existing?.staticSource ?? null,
+      handler: handler ?? null,
+      registeredAt: Date.now(),
+    });
+    return { ok: true, errors: [], warnings: v.warnings, pluginId: id };
+  }
+
+  /** 注销 handler：有静态声明的退回"仅声明"态，否则整体删除。 */
+  unregister(pluginId) {
+    const e = this.entries.get(pluginId);
+    if (!e) return;
+    if (e.staticSource) {
+      e.handler = null;
+      e.registeredAt = null;
+    } else {
+      this.entries.delete(pluginId);
+    }
+  }
+
+  /** 卸载后彻底移除条目（静态+动态）：插件从 listPlugins 立即消失。
+   *  enumerate() 只 upsert 静态声明、不清动态 register 条目——卸载必须显式调用本方法，
+   *  否则运行中实例的动态条目残留，列表不消失（2026-08 实测）。 */
+  removeEntry(pluginId) {
+    return this.entries.delete(pluginId);
+  }
+
+  _active(pluginId) {
+    const e = this.entries.get(pluginId);
+    if (!e || !e.handler) throw new MobileBridgeError('PLUGIN_NOT_FOUND', `plugin not found: ${pluginId}`);
+    return e;
+  }
+
+  _requireCapability(e, cap) {
+    if (!e.manifest.capabilities?.includes(cap)) {
+      throw new MobileBridgeError('CAPABILITY_NOT_DECLARED', `capability "${cap}" not declared by ${e.manifest.id}`);
+    }
+  }
+
+  /** 插件列表（仅可交互项）+ 每插件 badge（handler.getBadge，失败记 0）。
+   *  params.lang（可选，'zh'|'en'）：把 manifest 的 name/description 按请求语言解析为字符串下发
+   *  （manifest 本体仍保留原始 {zh,en}，App 端始终拿到字符串——旧 App 不发 lang 时兜底 zh）。 */
+  async listPlugins(params = {}) {
+    await this.ensureEnumerated(); // 静态来源就绪后再列（防 register 先到/enumerate 未完成的竞态）
+    const rawLang = params?.lang; // 手机端实际传的 lang（undefined = 未传/旧客户端）
+    const lang = (rawLang === 'en' || rawLang === 'zh') ? rawLang : DEFAULT_LANG;
+    const out = [];
+    for (const [id, e] of this.entries) {
+      if (!e.handler) continue;
+      let badge = 0;
+      try {
+        const b = await e.handler.getBadge?.();
+        if (typeof b === 'number' && b > 0) badge = b;
+      } catch {}
+      out.push({
+        manifest: {
+          ...e.manifest,
+          name: resolvePluginString(e.manifest.name, lang),
+          description: resolvePluginString(e.manifest.description, lang),
+        },
+        badge,
+        pkgName: e.staticSource || null,
+      });
+    }
+    return out;
+  }
+
+  /** 插件首页组件树（spec §6：根必须为 screen 节点，结构性 sanity）。 */
+  async getHome(pluginId, params = {}) {
+    const e = this._active(pluginId);
+    this._requireCapability(e, 'home');
+    if (typeof e.handler.getHome !== 'function') {
+      throw new MobileBridgeError('INTERNAL', `plugin ${pluginId} declares home but implements no getHome()`);
+    }
+    const tree = await e.handler.getHome(params);
+    if (!tree || typeof tree !== 'object' || tree.type !== 'screen') {
+      throw new MobileBridgeError('INTERNAL', `plugin ${pluginId} getHome() 返回非法组件树（根必须为 screen）`);
+    }
+    return tree;
+  }
+
+  /** 触发动作（spec §5.1 invoke；actionId 未知由插件抛 ACTION_NOT_FOUND，透传）。 */
+  async invoke(pluginId, actionId, params = {}) {
+    const e = this._active(pluginId);
+    this._requireCapability(e, 'actions');
+    if (typeof actionId !== 'string' || !actionId) {
+      throw new MobileBridgeError('INTERNAL', 'invoke: actionId 必填');
+    }
+    if (typeof e.handler.invoke !== 'function') {
+      throw new MobileBridgeError('INTERNAL', `plugin ${pluginId} declares actions but implements no invoke()`);
+    }
+    return e.handler.invoke(actionId, params);
+  }
+
+  /** 订阅插件事件。v1：校验插件存在后即 ack；扇出为广播（App 端按 pluginId 过滤）。 */
+  subscribe(pluginId) {
+    this._active(pluginId);
+    return { ok: true, note: 'v1 broadcast fan-out' };
+  }
+
+  /** 打开插件聊天（spec §5.1）：sessionId 缺省时由 handler.getChatSession?.() 提供（如秘书的持久会话）。 */
+  async openChat(pluginId, sessionId) {
+    const e = this._active(pluginId);
+    this._requireCapability(e, 'chat');
+    let sid = sessionId;
+    if (!sid) {
+      if (typeof e.handler.getChatSession !== 'function') {
+        throw new MobileBridgeError('INTERNAL', `plugin ${pluginId} declares chat but implements no getChatSession()`);
+      }
+      sid = await e.handler.getChatSession();
+    }
+    if (typeof sid !== 'string' || !sid) {
+      throw new MobileBridgeError('INTERNAL', `plugin ${pluginId} 未提供可打开的会话`);
+    }
+    return { sessionId: sid };
+  }
+
+  /** 插件主动发事件：{type:'mobile/event', pluginId, event:{name, payload}} 扇出给所有 sink。 */
+  emit(pluginId, name, payload = null) {
+    const frame = { type: 'mobile/event', pluginId, event: { name, payload } };
+    let delivered = 0;
+    for (const sink of this.sinks) {
+      try {
+        sink(frame);
+        delivered++;
+      } catch {}
+    }
+    return { delivered };
+  }
+
+  /** 传输层注册事件 sink，返回注销函数。 */
+  onEvent(sink) {
+    this.sinks.add(sink);
+    return () => this.sinks.delete(sink);
+  }
+
+  /** 方案 A：注入 pending 审批/提问缓存提供者（connector 隧道持有；未注入时 RPC 返回 INTERNAL）。
+   *  返回 { frames: [server-request 帧, ...] }——与实时 mux 帧同形，手机端走与实时帧相同的分发路径。 */
+  setPendingApprovalProvider(fn) {
+    this._pendingApprovalProvider = typeof fn === 'function' ? fn : null;
+  }
+
+  /** 注入中继用量/配额提供者（2026-08，quota-ux.md §5 定稿链路）：connector 持 deviceToken
+   *  查 relay GET /api/v1/usage（非计费只读）；未注入时 RPC 返回 INTERNAL——与 files/approvals 同模式。
+   *  fn() → Promise<{ plan, quota, used, resetAt, quotaDisabled }>（quota=null 表示不限量）。 */
+  setRelayUsageProvider(fn) {
+    this._relayUsageProvider = typeof fn === 'function' ? fn : null;
+  }
+
+  /** 注入一键安装推荐插件提供者（remote-connector 提供 dsh plugin add 实现；
+   *  未注入时 RPC 返回 INTERNAL——与 files/approvals 同模式）。fn(id) → Promise<{ok, already?, rebootNeeded?}> */
+  setPluginInstaller(fn) {
+    this._pluginInstaller = typeof fn === 'function' ? fn : null;
+  }
+
+  /** 注入一键卸载插件提供者（remote-connector 提供 dsh plugin remove 实现；对称 plugins.install）。
+   *  fn(id) → Promise<{ok, pkgName?, loaded?, rebootNeeded?}> */
+  setPluginUninstaller(fn) {
+    this._pluginUninstaller = typeof fn === 'function' ? fn : null;
+  }
+
+  /** mobile.approvals.list：拉取 pending 审批/提问（补手机离线窗口的缺失）。 */
+  _approvalsList() {
+    if (!this._pendingApprovalProvider) {
+      throw new MobileBridgeError('INTERNAL', '审批缓存未启用（宿主未注入 pending 提供者）');
+    }
+    return this._pendingApprovalProvider();
+  }
+
+  /** mobile.getRelayUsage：当前 PC 的中继用量/配额（2026-08，quota-ux.md §5）。 */
+  _relayUsage() {
+    if (!this._relayUsageProvider) {
+      throw new MobileBridgeError('INTERNAL', '用量查询未启用（宿主未注入提供者）');
+    }
+    return this._relayUsageProvider();
+  }
+
+  /** 统一 RPC 入口（spec §5.1 信封语义）：method = 'mobile.xxx'。 */
+  async handleRpc(method, payload = {}) {
+    const name = method.startsWith('mobile.') ? method.slice('mobile.'.length) : method;
+    switch (name) {
+      case 'listPlugins': return this.listPlugins(payload?.params);
+      case 'getHome': return this.getHome(payload?.pluginId, payload?.params);
+      case 'invoke': return this.invoke(payload?.pluginId, payload?.actionId, payload?.params);
+      case 'subscribe': return this.subscribe(payload?.pluginId);
+      case 'openChat': return this.openChat(payload?.pluginId, payload?.sessionId);
+      case 'refresh': await this.enumerate(); return { ok: true };
+      // 文件树（只读，方案 docs/file-tree-plan.md）：宿主注入 resolveRoots 后启用
+      case 'files.list': return this._files('list', payload);
+      case 'files.read': return this._files('read', payload);
+      // 文件元信息（方案 file-image-download-plan.md §4.1）：下载/预览前取 size + mediaType
+      case 'files.info': return this._files('info', payload);
+      // 二进制分块下载（§4.2）：返回 {__raw: Uint8Array}，connector 以原始字节作信文明文
+      case 'files.download': return this._files('download', payload);
+      // 浏览任意目录（2026-08：添加工作区选目录用；无白名单锚定）
+      case 'files.browse': return this._files('browse', payload);
+      // 创建目录（2026-08：添加工作区用——手机输入 PC 目录路径，先建后采纳）
+      case 'files.mkdir': return this._files('mkdir', payload);
+      // 方案 A：pending 审批/提问补拉（手机离线期间被丢弃的审批事件）
+      case 'approvals.list': return this._approvalsList();
+      // 中继用量/配额（2026-08，quota-ux.md §5）：当前 PC 的今日用量与额度（非计费）
+      case 'getRelayUsage': return this._relayUsage();
+      // 一键安装推荐插件（App 插件页空状态入口）：宿主注入 installer 后启用
+      case 'plugins.install': return this._pluginInstall(payload?.id);
+      // 一键卸载插件（App 插件详情页入口）：宿主注入 uninstaller 后启用
+      case 'plugins.uninstall': return this._pluginUninstall(payload?.id);
+      default:
+        throw new MobileBridgeError('INTERNAL', `未知方法: ${method}`);
+    }
+  }
+
+  /** 插件安装门禁：未注入 installer 时停用（错误码 INTERNAL，细节只进 PC 日志）。 */
+  _pluginInstall(id) {
+    if (!this._pluginInstaller) {
+      throw new MobileBridgeError('INTERNAL', '插件安装未启用（宿主未注入 installer）');
+    }
+    if (typeof id !== 'string' || !id) {
+      throw new MobileBridgeError('INTERNAL', 'plugins.install: id 必填');
+    }
+    return this._pluginInstaller(id);
+  }
+
+  /** 插件卸载门禁：未注入 uninstaller 时停用（错误码 INTERNAL，细节只进 PC 日志）。 */
+  _pluginUninstall(id) {
+    if (!this._pluginUninstaller) {
+      throw new MobileBridgeError('INTERNAL', '插件卸载未启用（宿主未注入 uninstaller）');
+    }
+    if (typeof id !== 'string' || !id) {
+      throw new MobileBridgeError('INTERNAL', 'plugins.uninstall: id 必填');
+    }
+    return this._pluginUninstaller(id);
+  }
+
+  /** 文件树 RPC 门禁：未注入 resolveRoots 时停用（错误码 INTERNAL，细节只进 PC 日志）。
+   *  download 返回原始字节，包成 {__raw} 标记，交由 tunnel 检测后以原始字节作信封明文（§4.2）。 */
+  _files(op, payload) {
+    if (!this.files) {
+      throw new MobileBridgeError('INTERNAL', '文件服务未启用（宿主未注入 resolveRoots）');
+    }
+    const res = this.files[op](payload || {});
+    if (op === 'download') {
+      return Promise.resolve(res).then((bytes) => ({ __raw: bytes }));
+    }
+    return res;
+  }
+}

package/mobile-bridge/core/enumerate.js

@@ -0,0 +1,44 @@
+// core/enumerate.js —— 枚举 DSH profile 中已安装的插件（spec §4.1 ① ②）。
+//
+// 发现路径（已核实，@deepseek-ai/dsh@0.1.0-rc.6 源码）：
+//   dsh 插件管理 = profile 目录 pnpm + profile manifest 的 dsh.profile.bundles 清单。
+//   每个 bundle 条目是包名，包本体在 <profileDir>/node_modules/<name>（pnpm 符号链接，
+//   path.join 直解即可；scoped 包为 node_modules/@scope/name）。
+//   本模块只做文件系统枚举，不依赖 cordis 内部 API——对未加载的插件也能枚举。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 读 profile manifest 的 dsh.profile.bundles（string[]）；manifest 缺失/损坏返回 []。 */
+export function readProfileBundles(profileDir) {
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(profileDir, 'package.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  const bundles = pkg?.dsh?.profile?.bundles;
+  return Array.isArray(bundles) ? bundles.filter((b) => typeof b === 'string') : [];
+}
+
+/**
+ * 把 bundle 包名解析为包目录：
+ *   - 先在 profile 根下找 `<profileDir>/node_modules/<name>`（用户/profile 装的插件）；
+ *   - 再在附加 node_modules 根（extraNodeModulesRoots，本就是 node_modules 目录，如 DSH 应用自身的
+ *     node_modules——DSH 内置运行时 bundle @deepseek-ai/dsh-* 在那里）下找 `<root>/<name>`。
+ * 全失败返回 null。
+ */
+export function resolveBundleDir(profileDir, name, extraNodeModulesRoots = []) {
+  try {
+    const dir = path.join(profileDir, 'node_modules', ...name.split('/'));
+    if (fs.statSync(dir).isDirectory()) return dir;
+  } catch {}
+  for (const root of (extraNodeModulesRoots || [])) {
+    if (!root) continue;
+    const dir = path.join(root, ...name.split('/'));
+    try {
+      if (fs.statSync(dir).isDirectory()) return dir;
+    } catch {}
+  }
+  return null;
+}