@dshfly/remote-connector 0.2.1

package/mobile-bridge/core/files.js

@@ -0,0 +1,431 @@
+// core/files.js —— 文件服务（mobile.files.*）。
+//
+// 纯 Node、零依赖、可单测。职责：
+//   - files.list：列一层目录（目录优先 + localeCompare 稳定序，200 条/页，hidden 标记）
+//   - files.read：UTF-8 文本分页读取（64KB/页，页尾对齐字符边界，单文件预览上限 5MB）
+//   - files.mkdir：创建目录（递归，已存在幂等）——"添加工作区"用：手机输入 PC 上
+//     不存在（或已存在）的目录绝对路径，先建目录再 workspace.create（2026-08 新增）
+//
+// 安全：
+//   - list/read 锚定（§5，服务端强制）：root 必须命中注入的 resolveRoots() 白名单；
+//     path 经 realpath 规范化后必须位于 root 之内（符号链接逃逸被拒）
+//   - mkdir 是"新目录"写入，目标不在既有工作区白名单内是常态，因此不套用白名单——
+//     信任级与"配对手机可 prompt agent 在 PC 上执行命令"一致（file-tree-plan §5 论证）；
+//     仅接受绝对路径，错误消息不携带绝对路径
+//   - 仅 UTF-8 文本（fatal 解码，二进制拒绝）；错误消息不携带绝对路径
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const fsp = fs.promises;
+
+export class FilesError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export const FILES_DEFAULTS = {
+  pageSize: 200,          // list 每页条目数
+  pageBytes: 64 * 1024,   // read 每页字节数
+  maxPreviewBytes: 5 * 1024 * 1024, // 单文件预览上限（文本）
+  maxDownloadBytes: 200 * 1024 * 1024, // 单文件下载上限（方案 file-image-download-plan.md §5.4；超出 files-too-large）
+  defaultChunkBytes: 512 * 1024, // download 缺省分块大小（客户端可传 length 覆盖）
+};
+
+/** 隐藏文件 = POSIX 点前缀（跨平台统一约定；Windows 无此语义，v1 不做平台差异）。 */
+function isHidden(name) {
+  return name.startsWith('.') && name !== '.' && name !== '..';
+}
+
+/** name 排序：目录优先，同级 localeCompare（稳定序，分页不重不漏）。 */
+function compareEntries(a, b) {
+  if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+  return a.name.localeCompare(b.name);
+}
+
+/** 扩展名 → MIME（非图片回退分发用；图片由魔数权威判定，不在此表）。 */
+const EXT_MIME = {
+  '.txt': 'text/plain', '.md': 'text/markdown', '.log': 'text/plain',
+  '.json': 'application/json', '.xml': 'application/xml', '.yaml': 'text/yaml', '.yml': 'text/yaml', '.toml': 'text/x-toml',
+  '.csv': 'text/csv', '.html': 'text/html', '.css': 'text/css',
+  '.js': 'text/javascript', '.jsx': 'text/javascript', '.ts': 'text/typescript', '.tsx': 'text/typescript',
+  '.py': 'text/x-python', '.sh': 'text/x-shellscript', '.bash': 'text/x-shellscript', '.go': 'text/x-go',
+  '.rs': 'text/x-rust', '.java': 'text/x-java', '.c': 'text/x-c', '.h': 'text/x-c',
+  '.cpp': 'text/x-c++', '.hpp': 'text/x-c++', '.rb': 'text/x-ruby', '.php': 'text/x-php',
+  '.swift': 'text/x-swift', '.sql': 'text/x-sql', '.gradle': 'text/x-groovy', '.env': 'text/plain',
+  '.pdf': 'application/pdf', '.zip': 'application/zip', '.gz': 'application/gzip',
+  '.tar': 'application/x-tar', '.tgz': 'application/gzip', '.rar': 'application/vnd.rar',
+  '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel', '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+
+export class FilesService {
+  /**
+   * @param {{resolveRoots?: () => Promise<string[]>, pageSize?: number, pageBytes?: number, maxPreviewBytes?: number}} opts
+   *   resolveRoots：每次调用实时返回允许的根（canonical 绝对路径）集合；未注入时 files.* 停用。
+   */
+  constructor({ resolveRoots = null, pageSize = FILES_DEFAULTS.pageSize, pageBytes = FILES_DEFAULTS.pageBytes, maxPreviewBytes = FILES_DEFAULTS.maxPreviewBytes, maxDownloadBytes = FILES_DEFAULTS.maxDownloadBytes, defaultChunkBytes = FILES_DEFAULTS.defaultChunkBytes } = {}) {
+    this.resolveRoots = resolveRoots;
+    this.pageSize = pageSize;
+    this.pageBytes = pageBytes;
+    this.maxPreviewBytes = maxPreviewBytes;
+    this.maxDownloadBytes = maxDownloadBytes;
+    this.defaultChunkBytes = defaultChunkBytes;
+    this._decoder = new TextDecoder('utf-8', { fatal: true });
+  }
+
+  /** 校验 root 命中白名单，返回 {rootReal}（canonical）。 */
+  async _assertRoot(root) {
+    if (typeof root !== 'string' || !root) {
+      throw new FilesError('files-root-forbidden', 'root 必须是非空路径');
+    }
+    if (typeof this.resolveRoots !== 'function') {
+      throw new FilesError('files-root-forbidden', '文件服务未启用');
+    }
+    let roots;
+    try {
+      roots = await this.resolveRoots();
+    } catch {
+      roots = [];
+    }
+    if (!Array.isArray(roots)) roots = [];
+    const canon = new Set();
+    for (const r of roots) {
+      if (typeof r !== 'string' || !r) continue;
+      try {
+        canon.add(await fsp.realpath(r));
+      } catch {
+        // 白名单里不可达的根（如已删除的工作区）直接忽略
+      }
+    }
+    let rootReal;
+    try {
+      rootReal = await fsp.realpath(root);
+    } catch {
+      throw new FilesError('files-root-forbidden', 'root 不可达或未授权');
+    }
+    if (!canon.has(rootReal)) {
+      throw new FilesError('files-root-forbidden', 'root 未授权');
+    }
+    return { rootReal };
+  }
+
+  /** 把 path 规范化到 root 之内（realpath；越界/符号链接逃逸拒绝）。返回 canonical 绝对路径。 */
+  async _resolveInside(rootReal, p) {
+    if (typeof p !== 'string' || !p) {
+      throw new FilesError('files-not-found', '路径必填');
+    }
+    const abs = path.isAbsolute(p) ? p : path.join(rootReal, p);
+    let real;
+    try {
+      real = await fsp.realpath(abs);
+    } catch {
+      throw new FilesError('files-not-found', '路径不存在');
+    }
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) {
+      throw new FilesError('files-outside-root', '路径越出工作区');
+    }
+    return real;
+  }
+
+  /**
+   * 一层目录列表。
+   * 响应 entries[] 每项携带绝对 path（对齐 host.listDirectory 契约："the client
+   * never joins path segments itself"）；分页游标 offset 按排序后索引。
+   */
+  async list({ root, path: p, offset = 0 } = {}) {
+    const { rootReal } = await this._assertRoot(root);
+    // 缺省列 root；空字符串视为非法（files-not-found），防止客户端误传
+    const target = p === undefined || p === null ? rootReal : await this._resolveInside(rootReal, p);
+    // parent 语义：相对工作区根（root 本身无上级 → null）
+    return this._readDir(target, offset, (t) => t === rootReal);
+  }
+
+  /**
+   * 浏览任意目录（mobile.files.browse，2026-08：添加工作区选目录用）。
+   * 与 list 的区别：**不做 resolveRoots 白名单锚定**——"添加工作区"的语义就是浏览并
+   * 采纳 PC 上任意目录（含新建），锚定既有工作区会锁死该场景；信任级与"配对手机可
+   * prompt agent 在 PC 上执行 bash 命令"一致（file-tree-plan §5 论证），仅暴露目录
+   * 条目元信息（名称/类型/大小/时间），不读文件内容。
+   * 约束：path 必须是绝对路径（缺省 = connector 进程 cwd，通常即 dsh web 主目录）；
+   * realpath 规范化；目标必须是目录；错误消息不携带绝对路径。
+   */
+  async browse({ path: p, offset = 0 } = {}) {
+    let target;
+    if (p === undefined || p === null || p === '') {
+      target = process.cwd();
+    } else if (typeof p === 'string' && path.isAbsolute(p)) {
+      target = path.normalize(p);
+    } else {
+      throw new FilesError('files-not-found', '路径必须是绝对路径');
+    }
+    let real;
+    try {
+      real = await fsp.realpath(target);
+    } catch {
+      throw new FilesError('files-not-found', '路径不存在');
+    }
+    let st;
+    try {
+      st = await fsp.stat(real);
+    } catch {
+      throw new FilesError('files-not-found', '路径不存在');
+    }
+    if (!st.isDirectory()) {
+      throw new FilesError('files-not-directory', '目标不是目录');
+    }
+    // parent 语义：相对文件系统根（文件系统根本身无上级 → null）
+    return this._readDir(real, offset, (t) => t === path.parse(t).root);
+  }
+
+  /** 列一层目录（list/browse 共用）：stat → 目录校验 → readdir → 逐项 stat → 排序 → 分页。
+   *  parentRoot(t)：返回 true 表示 t 是"无上级"的根（list=工作区根，browse=文件系统根）。 */
+  async _readDir(target, offset, parentRoot) {
+    let st;
+    try {
+      st = await fsp.stat(target);
+    } catch {
+      throw new FilesError('files-not-found', '路径不存在');
+    }
+    if (!st.isDirectory()) {
+      throw new FilesError('files-not-directory', '目标不是目录');
+    }
+    let dirents;
+    try {
+      dirents = await fsp.readdir(target, { withFileTypes: true });
+    } catch {
+      throw new FilesError('files-io', '目录读取失败');
+    }
+
+    // 逐项 stat（跟随符号链接）：目录/文件分类 + 大小 + 时间；坏链/特殊文件跳过
+    const rows = [];
+    for (const d of dirents) {
+      let cst;
+      try {
+        cst = await fsp.stat(path.join(target, d.name));
+      } catch {
+        continue; // 坏链或瞬时 IO：跳过（不破坏整层）
+      }
+      const type = cst.isDirectory() ? 'dir' : cst.isFile() ? 'file' : null;
+      if (!type) continue;
+      rows.push({
+        name: d.name,
+        // 绝对路径（client 端不自行拼接路径段——对齐 host.listDirectory 契约先例）
+        path: path.join(target, d.name),
+        type,
+        size: type === 'file' ? cst.size : 0,
+        mtime: cst.mtimeMs,
+        hidden: isHidden(d.name),
+      });
+    }
+    rows.sort(compareEntries);
+
+    const start = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+    const page = rows.slice(start, start + this.pageSize);
+    const truncated = start + page.length < rows.length;
+    return {
+      root: target,
+      path: target,
+      parent: parentRoot(target) ? null : path.dirname(target),
+      entries: page,
+      truncated,
+      nextOffset: truncated ? start + page.length : null,
+    };
+  }
+
+  /** UTF-8 文本分页读取（64KB/页，页尾对齐字符边界，预览上限 maxPreviewBytes）。 */
+  async read({ root, path: p, offset = 0 } = {}) {
+    const { rootReal } = await this._assertRoot(root);
+    const target = await this._resolveInside(rootReal, p);
+
+    let st;
+    try {
+      st = await fsp.stat(target);
+    } catch {
+      throw new FilesError('files-not-found', '路径不存在');
+    }
+    if (!st.isFile()) {
+      throw new FilesError('files-not-regular', '目标不是普通文件');
+    }
+
+    const start = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+    const end = Math.min(st.size, this.maxPreviewBytes);
+    if (start >= end) {
+      return {
+        root: rootReal, path: target, name: path.basename(target),
+        size: st.size, offset: start, content: '', totalRead: end,
+        nextOffset: null, truncated: st.size > this.maxPreviewBytes,
+      };
+    }
+
+    // 只读 want 字节；页尾若切在多字节字符中间，从尾部逐字节回退（最多 3 字节）
+    // 找到合法 UTF-8 边界。绝不把下一页的字节带进本页结果。
+    const want = Math.min(this.pageBytes, end - start);
+    const buf = Buffer.alloc(want);
+    let bytesRead = 0;
+    try {
+      const fh = await fsp.open(target, 'r');
+      try {
+        ({ bytesRead } = await fh.read(buf, 0, want, start));
+      } finally {
+        await fh.close();
+      }
+    } catch {
+      throw new FilesError('files-io', '文件读取失败');
+    }
+
+    let content = null;
+    let used = bytesRead;
+    for (let trim = 0; trim <= 3 && trim <= bytesRead; trim++) {
+      try {
+        content = this._decoder.decode(buf.subarray(0, bytesRead - trim));
+        used = bytesRead - trim;
+        break;
+      } catch {
+        // 尾部字符不完整，继续回退
+      }
+    }
+    if (content === null) {
+      throw new FilesError('files-not-text', '不是可预览的 UTF-8 文本');
+    }
+
+    const totalRead = start + used;
+    const truncated = st.size > this.maxPreviewBytes;
+    return {
+      root: rootReal, path: target, name: path.basename(target),
+      size: st.size, offset: start, content, totalRead,
+      nextOffset: totalRead < end ? totalRead : null,
+      truncated,
+    };
+  }
+
+  /** 校验 target 是普通文件，返回其 stat（files-not-found / files-not-regular）。 */
+  async _statRegular(target) {
+    let st;
+    try {
+      st = await fsp.stat(target);
+    } catch {
+      throw new FilesError('files-not-found', '路径不存在');
+    }
+    if (!st.isFile()) {
+      throw new FilesError('files-not-regular', '目标不是普通文件');
+    }
+    return st;
+  }
+
+  /**
+   * 文件元信息（方案 file-image-download-plan.md §4.1）：下载/预览前获取
+   * 文件名（含扩展名）、总字节、MIME（魔数嗅探判定，非扩展名）、mtime。
+   * - mediaType 供客户端决定「文本预览 / 图片查看 / 下载并打开」三路分发（§5.1）。
+   * - 锚定同 read（root ∈ 白名单，path ∈ root）。仅 stat + 最多读文件头 12B，开销极小。
+   */
+  async info({ root, path: p } = {}) {
+    const { rootReal } = await this._assertRoot(root);
+    const target = await this._resolveInside(rootReal, p);
+    const st = await this._statRegular(target);
+    const mediaType = await this._sniffMediaType(target);
+    return {
+      name: path.basename(target),
+      size: st.size,
+      mediaType: mediaType || 'application/octet-stream',
+      mtime: st.mtimeMs,
+    };
+  }
+
+  /**
+   * 二进制分块读取（方案 file-image-download-plan.md §4.2）：返回 [offset, offset+length)
+   * 的**原始字节**（Uint8Array）。客户端据 info.size 与已收字节判断是否下载完。
+   * - 无 base64、无分块内元数据（信文明文就是文件字节，避业务层 base64，见 §3）。
+   * - length 缺省 defaultChunkBytes（512KB）；服务端钳到 size-offset。
+   * - 单文件超过 maxDownloadBytes → files-too-large（服务端护栏，客户端另行确认）。
+   * - 锚定同 read；目标必须是普通文件。
+   */
+  async download({ root, path: p, offset = 0, length } = {}) {
+    const { rootReal } = await this._assertRoot(root);
+    const target = await this._resolveInside(rootReal, p);
+    const st = await this._statRegular(target);
+    if (st.size > this.maxDownloadBytes) {
+      throw new FilesError('files-too-large', '文件超过单次下载上限');
+    }
+    const start = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+    if (start >= st.size) return new Uint8Array(0); // 越界 → 空块（客户端据 size 已收满即停）
+    const want = Number.isFinite(length) && length > 0 ? Math.floor(length) : this.defaultChunkBytes;
+    const n = Math.min(want, st.size - start);
+    const buf = Buffer.alloc(n);
+    let bytesRead = 0;
+    try {
+      const fh = await fsp.open(target, 'r');
+      try {
+        ({ bytesRead } = await fh.read(buf, 0, n, start));
+      } finally {
+        await fh.close();
+      }
+    } catch {
+      throw new FilesError('files-io', '文件读取失败');
+    }
+    // Buffer 本身就是 Uint8Array 子类；切出实际读到的那段（避免把未写满的尾字节带出去）
+    return new Uint8Array(buf.subarray(0, bytesRead));
+  }
+
+  /** 魔数嗅探媒体类型：优先图片（权威，不信任扩展名）；无魔数则按扩展名回退（文本/常见类型）。
+   *  仅读前 12 字节。图片类型判定用于客户端 → 图片查看器；文本/常见类型用于 → 文本预览/下载。 */
+  async _sniffMediaType(file) {
+    let head;
+    try {
+      const fh = await fsp.open(file, 'r');
+      try {
+        const b = Buffer.alloc(12);
+        await fh.read(b, 0, 12, 0);
+        head = b;
+      } finally {
+        await fh.close();
+      }
+    } catch {
+      return null;
+    }
+    const eq = (sig) => sig.every((v, i) => head[i] === v);
+    // 图片（魔数）
+    if (eq([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png';
+    if (eq([0xff, 0xd8, 0xff])) return 'image/jpeg';
+    if (eq([0x47, 0x49, 0x46, 0x38, 0x37, 0x61]) || eq([0x47, 0x49, 0x46, 0x38, 0x39, 0x61])) return 'image/gif';
+    if (eq([0x42, 0x4d])) return 'image/bmp';
+    if (String.fromCharCode(...head.subarray(0, 4)) === 'RIFF' && String.fromCharCode(...head.subarray(8, 12)) === 'WEBP') return 'image/webp';
+    if (String.fromCharCode(...head.subarray(4, 8)) === 'ftyp') {
+      const brand = String.fromCharCode(...head.subarray(8, 12));
+      if (['heic', 'heix', 'hevc', 'mif1', 'avif', 'heif'].includes(brand)) return 'image/heic';
+    }
+    // 非图片：按扩展名回退（用于文本/常见类型分发）
+    const ext = path.extname(file).toLowerCase();
+    return EXT_MIME[ext] || null;
+  }
+
+  /**
+   * 创建目录（递归，已存在幂等）。"添加工作区"流程：手机输入 PC 目录绝对路径 →
+   * mkdir（不存在则连同父目录一并创建）→ workspace.create 采纳。
+   * 不套用 resolveRoots 白名单（目标通常是"新"目录）；仅绝对路径 + 错误不携带路径。
+   */
+  async mkdir({ path: p } = {}) {
+    if (typeof p !== 'string' || !p.trim()) {
+      throw new FilesError('files-mkdir-failed', '路径必填');
+    }
+    if (!path.isAbsolute(p.trim())) {
+      throw new FilesError('files-mkdir-failed', '路径必须是绝对路径');
+    }
+    const target = path.normalize(p.trim());
+    try {
+      await fsp.mkdir(target, { recursive: true });
+    } catch (e) {
+      throw new FilesError('files-mkdir-failed', e?.code === 'EACCES' ? '没有权限创建目录' : '创建目录失败');
+    }
+    let real;
+    try {
+      real = await fsp.realpath(target);
+    } catch {
+      real = target;
+    }
+    return { path: real };
+  }
+}

package/mobile-bridge/core/roots.js

@@ -0,0 +1,50 @@
+// core/roots.js —— 文件树根白名单解析器（方案 docs/file-tree-plan.md §3/§5 + 审计 P1-1/D4）。
+//
+// 宿主（remote-connector 插件）注入给 MobileBridgeCore 的 resolveRoots 实现：
+// 每次调用经本机 loopback /api（与手机同一 client-request 信封协议，对齐
+// plugin-myassistant 的自环先例）实时取：
+//   - workspace.list → 已登记工作区 canonical path
+// 工作区增删 / 换 PC 即时生效，不做缓存。
+//
+// ⚠️ D4（审计 P1-1）：host.describe 的 cwd 不再并入允许根——dsh web 常从用户家目录启动
+// （cwd=home 会让"受限"手机（fullDisk=false）经 files.list/read
+// 读取 ~/.ssh、~/.aws 等整个家目录，使"不允许完整磁盘"开关名存实亡。受限手机可见范围
+// = **仅已登记工作区**（cwd 若本身就是已登记工作区则天然在根内）。
+// 任何失败（loopback 不可达、网关报错）→ 返回空数组 → 所有 files.* 请求
+// 以 files-root-forbidden 拒绝（fail-closed）。
+
+/** 构造 loopback 根解析器。fetchImpl 可注入（单测）。 */
+export function createLoopbackRootsResolver({
+  baseUrl = 'http://127.0.0.1:3080',
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 3000,
+} = {}) {
+  const base = baseUrl.replace(/\/$/, '');
+  let counter = 0;
+
+  async function rpc(method) {
+    const rpcId = `fs-roots-${Date.now()}-${++counter}`;
+    const res = await fetchImpl(`${base}/api/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ type: 'client-request', rpcId, method, payload: {} }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) throw new Error(`loopback ${method} -> HTTP ${res.status}`);
+    const full = await res.json();
+    if (!full || full.rpcId !== rpcId || !full.result?.ok) {
+      throw new Error(`loopback ${method} -> ${full?.result?.error?.code ?? 'bad envelope'}`);
+    }
+    return full.result.value;
+  }
+
+  /** resolveRoots：Promise<string[]>（fail-closed，永不抛）。仅已登记工作区（D4）。 */
+  return async function resolveRoots() {
+    try {
+      const ws = await rpc('workspace.list');
+      return (ws?.items ?? []).map((i) => i?.path).filter((p) => typeof p === 'string' && p);
+    } catch {
+      return [];
+    }
+  };
+}

package/mobile-bridge/index.js

@@ -0,0 +1,59 @@
+// packages/remote-connector/mobile-bridge/index.js
+// DSH 移动端插件规范实现（M4.x-c，2026-08-17 整合为纯库；现已并入 @dshfly/remote-connector）。
+// 原 @dshfly/mobile-bridge 已不再作为独立 publish 包——由 remote-connector 承载。
+import os from 'node:os';
+//
+// 整合决策（方案 1b）：本包不再是独立 cordis 插件——`ctx.mobileBridge` 服务由
+// `@dshfly/remote-connector` 承载（它拥有传输层，是服务的天然所有者）。本包只提供：
+//   - MobileBridgeCore（枚举/注册表/RPC/事件，纯 Node 可单测）
+//   - createMobileBridgeService（把 core 包装成服务对象，connector 负责 ctx.provide）
+//   - resolveProfileDir（profile 目录解析）
+// 收益：bridge 无法被单独安装（非 bundle，"装了没用"的状态空间消失）；装 connector
+// 一个命令即带出；无插件加载时序问题。插件侧契约不变：ctx.mobileBridge.register。
+// 规范实现的独立边界保留：未来 DSH 上游若吸收移动端规范，本库可直接上贡。
+
+export { MobileBridgeCore, MobileBridgeError } from './core/bridge-core.js';
+export { readProfileBundles, resolveBundleDir } from './core/enumerate.js';
+export { FilesService, FilesError } from './core/files.js';
+export { createLoopbackRootsResolver } from './core/roots.js';
+
+/** 把 core 包装成服务对象（connector apply 里 ctx.provide('mobileBridge', ...) 用；也便于测试）。 */
+export function createMobileBridgeService(core) {
+  return {
+    listPlugins: () => core.listPlugins(),
+    getHome: (pluginId, params) => core.getHome(pluginId, params),
+    invoke: (pluginId, actionId, params) => core.invoke(pluginId, actionId, params),
+    subscribe: (pluginId) => core.subscribe(pluginId),
+    openChat: (pluginId, sessionId) => core.openChat(pluginId, sessionId),
+    register: (opts) => core.register(opts || {}),
+    unregister: (pluginId) => core.unregister(pluginId),
+    emit: (pluginId, name, payload) => core.emit(pluginId, name, payload),
+    onEvent: (sink) => core.onEvent(sink),
+    handleRpc: (method, payload) => core.handleRpc(method, payload),
+    // 方案 A：pending 审批/提问缓存数据源注入（connector 隧道持有）
+    setPendingApprovalProvider: (fn) => core.setPendingApprovalProvider(fn),
+    // 2026-08：中继用量/配额数据源注入（connector 持 deviceToken 查 relay /api/v1/usage）
+    setRelayUsageProvider: (fn) => core.setRelayUsageProvider(fn),
+    health: () => core.health,
+  };
+}
+
+/** 解析 profile 目录（默认 <dshHome>/profiles/<profileName>，profileName 默认 'web'）。
+ *  2026-08 修复：pnpm 符号链接布局下，源码包动态 import('@deepseek-ai/dsh-home-paths') 从
+ *  仓库真实路径解析不到该依赖（它只装在 profile 安装目录，未提升到仓库根）→ 原 catch 返回 null，
+ *  导致 enumerate 跳过、插件 staticSource 缺失（App 插件 ID 回退短 id）。DSH 默认 home = ~/.dsh
+ *  （resolveDshHome 同值），追加 os.homedir() 兜底，免依赖该 import。 */
+export function resolveProfileDir({ profileDir = '', profileName = 'web' } = {}) {
+  if (profileDir) return profileDir;
+  try {
+    const { resolveDshHome } = awaitImportDshHome();
+    return `${resolveDshHome()}/profiles/${profileName}`;
+  } catch {
+    return `${os.homedir()}/.dsh/profiles/${profileName}`;
+  }
+}
+
+// 延迟 import（单测等非宿主环境不强制解析 dsh-home-paths；connector 运行时正常解析）
+async function awaitImportDshHome() {
+  return import('@deepseek-ai/dsh-home-paths');
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@dshfly/remote-connector",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "DSH Fly remote connector as a DeepSeek Harness (DSH) cordis plugin — outbound relay tunnel + E2EE endpoint + loopback proxy into dsh web",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dshfly",
+    "remote",
+    "e2ee",
+    "cordis"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./client": "./dist/client.js",
+    "./core": "./core/connector-core.js",
+    "./keys": "./core/keys.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "config.js",
+    "http-api.js",
+    "core",
+    "dist",
+    "mobile-bridge",
+    "!mobile-bridge/test",
+    "cordis.patch.yml"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "qrcode": "^1.5.4",
+    "ws": "^8.21.3",
+    "@dshfly/tunnel-protocol": "0.1.0",
+    "@dshfly/mobile-plugin-schema": "0.1.0",
+    "@dshfly/crypto": "0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.0-rc.6",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "@dshfly/plugin-notifications": "0.1.0",
+    "@dshfly/plugin-myassistant": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build:client": "node scripts/build-client.mjs",
+    "test": "node --test test/*.test.js test/mobile-bridge/test/*.test.js",
+    "build": "node scripts/build-client.mjs"
+  }
+}