@zhangfengshun/dsh-remote-ssh 2.4.5 → 2.4.7

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.4.7] — `@` 文件引用补全支持远程工作区（issue #10）
+### 新增
+- **远程工作区会话里 `@` 补全现在列远端文件**（感谢 @Linhaojing 的通道分析与挂载点核实）：`@` 补全由宿主 `ctx.fileReferences` 服务提供（官方 provider `@deepseek-ai/dsh-file-reference-local`），它只遍历**本地磁盘**——远程工作区会话的 cwd 是本地镜像目录，于是候选只有镜像里那几个文件（通常只有本插件写入的 `README.md`）。该链路不经过任何 HTTP 路由（客户端经 remote gateway 调 `ctx.fileReferences.list`），因此采用**服务层包装**：
+  - 在 `ctx.inject(["fileReferences"])` 里包装已注册的服务实例，**远程工作区自己算候选**，其余一律委托回原实现——本地会话的索引与模糊排序**零改动**，不替换 composition row，也不新增 `@deepseek-ai/*` 运行时依赖；
+  - 桥接侧动态解析服务（`dsh-api-session-controller` 的 `this.ctx.fileReferences.list(...)`），实例包装对其立即生效（已核实）；
+  - 服务缺失或不可包装时打印一条 warn 并保持原行为；卸载时自动还原原方法。
+- **查询语义与官方 provider 逐条对齐**：空查询/含 `/` 走目录列举、纯片段走模糊查询；隐藏文件仅在小片段以 `.` 开头时可见；评分常量（同名 1000 / 前缀 900 / 名称子串 700 / 路径子串 500 / 子序列 300+间隔惩罚）、目录 +25、排序 tiebreak（目录优先 → 路径短 → 字典序）、排除目录表（与上游 `DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES` 的 15 条一致）全部照搬。
+- **索引来源按远端实际测量取舍**：git 仓库用 `git ls-files --cached --others --exclude-standard`（真实超算实测 **0.117s / 137 条**，尊重 `.gitignore`、含未跟踪文件），非 git 回退有界 `find`（`maxdepth 5` + 剪枝，实测 **1.57s / 3121 条**）——作为对照，深遍历 `find` 在同一仓库要 **18.6s**。
+- **性能与降级**：索引按 workspace 缓存 60s 并挂到既有 `cacheEpoch`（写/exec 后自动失效）；单次查询只等 **900ms**，超时用陈旧索引或空结果作答、重建继续在后台（与本地 provider 的"陈旧索引照常回答"一致）；`AbortSignal` 已取消时直接返回空；任何异常一律降级到本地实现，绝不把光标卡在 SSH 上。
+
+### 测试
+- 新增 `tests/file-references.test.mjs`（**62 条断言**）：查询拆分、索引解析（git/find 两种帧、父路径合成目录、排除目录剪枝、符号链接跳过、CRLF、条目上限）、评分与排序（含逐条对照上游常量）、隐藏文件可见性、索引命令生成（两条分支 + 15 条排除目录）、服务包装（远程走远端 / 本地委托 / 异常降级 / 恢复函数 / 非法服务安全返回）、以及**真实 HPC 输出样例**喂给解析器。
+
+## [2.4.6] — 「文件」页签树根显示远程目录名（issue #9）
+### 修复
+- **树根标签不再显示本地镜像目录 ID**（感谢 @Linhaojing 的链路定位）：better-sidebar「文件」页签的树根标签取自会话 cwd（= 本地镜像路径）的 basename，于是显示成 `wmu3sxe24jpvg` 之类的镜像目录名。这条链路**不经过任何 `fs.*` 路由**，且 Host 侧 `session.cwd` 虽已返回 `root` 字段但客户端只消费 `cwd`（`api.sessionCwd(...).then(r => setFetchedCwd(r.cwd))`，另有 `useSessionCwd` 直接读客户端会话列表的 `cwd`），因此只能在渲染层替换文本。现由客户端取 `listWorkspaces` 的 `mirrorPath`/`remotePath` 建立「镜像 basename → 远程 basename」映射，把树根那一行换成**远程目录名**（如 `IB_Robot`），并给该行加 `title` 显示完整远程路径（如 `~/lhj/IB_Robot`）。
+  - **定位不依赖构建期哈希类名**：根行是树里唯一带内联 `padding-left:6px` 的行，仅当该行内纯文本节点恰好等于某远程工作区的镜像 basename 时才替换——同名子条目、本地工作区、无根行标志（上游改版）时一律保守不动；
+  - **同步替换 + 幂等自愈**：与设置导航图标同样在 MutationObserver 回调（微任务、绘制前）内完成，不会先闪一下镜像 ID；React 重渲染还原文本时由 1s 复检与 30s 工作区轮询恢复。
+
+### 测试
+- 新增 `tests/tree-root-label.test.mjs`：从 `lib/client.js` 提取**真实**实现配极简 DOM 桩执行，覆盖 7 组场景共 17 条断言（替换、假阳性防护、幂等、React 还原自愈、本地工作区、同名边界、样式容错、接线检查）。
+
 ## [2.4.5] — 集成终端落在工作区远程目录（issue #7）+ 密码认证回退提示
 ### 修复
 - **「终端」页签现在落在工作区对应的远程目录**（感谢 @Linhaojing 的完整定位与验证矩阵）：此前生成的 `dsh-remote-shell.js` 只拼 host/user/port/keyPath/proxyJump，`ssh -tt` 不带远程命令，交互式 shell 落在远程 `$HOME`；同一会话里出现「文件树在工作区目录、终端在 $HOME」的割裂。现在 wrapper 读取标记文件里**已有的** `remotePath` 并追加远程命令：

package/README.md

@@ -15,6 +15,7 @@
 | 💻 远程终端 | 内置「终端」页签自动检测远程工作区，SSH 交互式终端，**落在工作区对应的远程目录**（与 VSCode Remote-SSH 一致） |
 | 🌐 远程工作区 | 选择远程目录创建原生工作区，一键进入远程环境 |
 | 🤖 模型工具 | 13 个 `remote_ssh_*` 工具，会话感知免填连接参数；命令级超时 + `remote_ssh_kill` 兜底恢复 |
+| 🗂️ `@` 引用补全 | 远程工作区会话里 `@` 补全列**远端**文件（git 仓库走 `git ls-files`，实测 0.1s；非 git 用有界 `find`；索引缓存 + 900ms 查询预算，超时降级不卡输入框） |
 | ⚡ 打开提速 | 单往返合并读 + raw 文本快路径 + 结果缓存（LRU + 5s TTL）：首开 ≈**1.31×**，TTL 内重复打开 **0 往返**，过期复验 **≈5×**（真实超算实测）；`remote_ssh_exec` 连接复用 **≈15×** |
 
 ## 截图
@@ -45,7 +46,7 @@
 **一条命令安装**（无需 token、API Key 或额外配置）：
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.5
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.7
 ```
 
 安装后**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
@@ -155,6 +156,15 @@ dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 
 远程工作区会话中调用工具可免填 `profileId` 等连接参数；全部文件/命令类工具走持久 SSH 会话池 + 结果缓存，`remote_ssh_exec` 单命令实测 ≈15× 提速。
 
+## `@` 文件引用补全
+
+远程工作区会话里输入 `@`，候选来自**远端**（与「文件」页签的树一致），而不是本地镜像目录：
+
+- **索引来源**：git 仓库用 `git ls-files --cached --others --exclude-standard`（尊重 `.gitignore`、含未跟踪文件；真实超算实测 0.117s / 137 条），非 git 目录回退有界 `find`（`maxdepth 5` + 剪枝，实测 1.57s / 3121 条）；
+- **查询语义与官方 provider 逐条对齐**：`@` 与 `@src/` 走远端目录列举；`@read` 走索引模糊匹配（同名 > 前缀 > 名称子串 > 路径子串 > 子序列，目录加权 +25）；
+- **不卡输入框**：索引按工作区缓存 60 秒（写文件/执行命令后自动失效），单次补全只等 900ms——超时先用旧索引作答、重建在后台进行；连接异常时自动回退到本地行为；
+- **本地工作区不受影响**：非远程会话直接委托宿主原实现，索引与排序完全没有改动。
+
 ## 命令超时与恢复
 
 所有 SSH 命令默认 **120 秒**超时（issue #5）：一条挂起的远端命令（网络卡顿、远端进程僵死、等待 stdin 的 `cat`）不会再永久占用会话、拖死后续命令。
@@ -187,6 +197,8 @@ dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 | 侧边栏文件页签显示「这类内容还没有可用的查看方式。」 | `dsh-better-sidebar` 主机半边未加载：0.18.1 / 0.19.0 / 0.19.1 在 DSH Desktop 上会因 `SessionLogOffset` 运行时导入失败——降到 0.18.0 或使用修复版（上游 PR [#641](https://github.com/omdsh-dev/DSH-better-sidebar/pull/641)） |
 | 内置「终端」页签连不上 | 终端为 `ssh -tt` 交互式通道，**仅支持密钥认证**；密码认证的连接会回退为本地 shell 并打印一行提示（避免把本地 shell 误认为已连上远程），密码认证请改用「文件」页签与模型工具 |
 | 终端落在远程 `$HOME` 而不是工作区目录 | 2.4.5 起已修复（wrapper 会 `cd` 到工作区 `remotePath`，目录不存在时回退 `$HOME`）；若仍停在 `$HOME`，确认 2.4.5 已装入并重启 DSH |
+| 「文件」页签树根显示镜像目录 ID（如 `wmu3sxe24jpvg`） | 2.4.6 起已修复：树根改为显示**远程目录名**（如 `IB_Robot`），悬停可见完整远程路径；该标签不经过 `fs.*` 路由，由客户端渲染层替换 |
+| `@` 补全只搜到镜像里那几个文件 | 2.4.7 起已修复：远程工作区会话的 `@` 补全改列远端文件（索引缓存 60s + 900ms 查询预算）；若仍只有镜像文件，确认 2.4.7 已装入并重启 DSH |
 | 安装时提示 `minimumReleaseAge` 或「No matching version」（刚发布） | npm 供应链新鲜度策略，等 1–5 分钟后重试即可 |
 | 命令卡住不返回 | 默认 120s 超时后自动丢弃会话；长时任务用 `timeoutMs: 0`，随时可用 `remote_ssh_kill` 强杀 |
 | 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB（更大自动回落一次性连接）；用 `remote_ssh_exec` + `head`/`tail` 分段处理 |

package/README_EN.md

@@ -15,6 +15,7 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 | 💻 Remote Terminal | Built-in **Terminal** tab auto-detects remote workspaces, opens an SSH interactive shell **in the workspace's remote directory** (like VSCode Remote-SSH) |
 | 🌐 Remote Workspace | Select a remote directory to create a native workspace, one-click enter |
 | 🤖 Model Tools | 13 `remote_ssh_*` tools, session-aware with auto-filled connection params; command-level timeout + `remote_ssh_kill` recovery |
+| 🗂️ `@` Completion | In a remote-workspace session, `@` completion lists **remote** files (git repos via `git ls-files`, measured 0.1s; bounded `find` otherwise; cached index + 900ms query budget so the caret never stalls) |
 | ⚡ Faster Opens | Single-roundtrip merged reads + raw text fast path + result cache (LRU + 5s TTL): first open ≈**1.31×**, repeat opens within TTL **0 round-trips**, expired revalidation **≈5×** (measured on a real HPC); `remote_ssh_exec` connection reuse **≈15×** |
 
 ## Screenshots
@@ -45,7 +46,7 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 **One command** (no token, API key or extra configuration needed):
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.5
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.7
 ```
 
 **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
@@ -155,6 +156,15 @@ Returns `{ ok, exitCode, stdout, stderr, error, truncated, isTimeout }` — e.g.
 
 In a remote-workspace session, `profileId` and other connection params can be omitted. All file/command tools run over the persistent SSH session pool + result cache; `remote_ssh_exec` measures ≈15× faster per command.
 
+## `@` File Reference Completion
+
+In a remote-workspace session, typing `@` offers **remote** candidates (matching the Files tab tree) instead of the local mirror directory:
+
+- **Index source**: git repos use `git ls-files --cached --others --exclude-standard` (respects `.gitignore`, includes untracked files; measured 0.117s / 137 entries on a real HPC), non-git directories fall back to a bounded `find` (`maxdepth 5` + pruning, measured 1.57s / 3121 entries);
+- **Query semantics mirror the official provider**: `@` and `@src/` list a remote directory; `@read` runs the fuzzy index (exact name > prefix > name substring > path substring > subsequence, directories +25);
+- **The caret never stalls**: the index is cached per workspace for 60s (invalidated after writes/commands) and a single completion waits at most 900ms — on timeout the stale index answers and the rebuild continues in the background; connection failures fall back to local behaviour;
+- **Local workspaces are untouched**: non-remote sessions delegate straight to the host implementation.
+
 ## Command Timeout & Recovery
 
 All SSH commands default to a **120-second** timeout (issue #5): a hung remote command (network stall, stuck remote process, `cat` waiting on stdin) can no longer occupy the session forever and block every later command.
@@ -187,6 +197,8 @@ The plugin never patches DSH sources or injects into the profile dependency tree
 | Sidebar Files tab says "Nothing here can view this kind of content yet." | `dsh-better-sidebar` host half failed to load: 0.18.1 / 0.19.0 / 0.19.1 hit the `SessionLogOffset` runtime import on DSH Desktop — downgrade to 0.18.0 or use a fixed build (upstream PR [#641](https://github.com/omdsh-dev/DSH-better-sidebar/pull/641)) |
 | Built-in Terminal tab cannot connect | The terminal is an `ssh -tt` interactive channel and supports **key auth only**; password-auth profiles fall back to a local shell and now print a one-line notice (so a local shell is not mistaken for a remote one) — use the Files tab and the model tools for password auth |
 | Terminal opens in the remote `$HOME` instead of the workspace directory | Fixed in 2.4.5 (the wrapper `cd`s into the workspace `remotePath`, falling back to `$HOME` when it no longer exists); if it still starts in `$HOME`, make sure 2.4.5 is installed and DSH restarted |
+| Files tab tree root shows the mirror directory id (e.g. `wmu3sxe24jpvg`) | Fixed in 2.4.6: the root row now shows the **remote directory name** (e.g. `IB_Robot`) with the full remote path on hover; that label never passes through the `fs.*` routes, so the client renders the replacement |
+| `@` completion only finds the few files in the mirror | Fixed in 2.4.7: in a remote-workspace session `@` now lists remote files (60s index cache + 900ms query budget); if only mirror files show up, make sure 2.4.7 is installed and DSH restarted |
 | Install fails with `minimumReleaseAge` or "No matching version" right after a release | npm supply-chain freshness policy — retry after 1–5 minutes |
 | A command hangs forever | The 120s timeout discards the pooled session automatically; use `timeoutMs: 0` for long jobs and `remote_ssh_kill` at any time |
 | Large files are truncated | 4MB per read, ≈6.29MB on the pooled download path (larger files fall back to a one-shot connection); use `remote_ssh_exec` with `head`/`tail` to page through |

package/lib/client.js

@@ -1167,6 +1167,8 @@ window.__ModuleLoader__.load({
         // 追加地球经纬线组 —— 文件夹本体保持壳层默认原语几何，零改写零对账风险。
         var remoteTitles = new Set();
         var watchedTitles = []; // 已匹配的标题元素：定时幂等复检，抵消 React 重渲染对图标的还原
+        /** 镜像目录 basename → { label: 远程目录 basename, remotePath }（issue #9）。 */
+        var rootLabels = {};
         function refreshRemoteTitles() {
           api("listWorkspaces").then(function (r) {
             if (!(r && r.ok && Array.isArray(r.workspaces))) return;
@@ -1176,7 +1178,9 @@ window.__ModuleLoader__.load({
               if (t) { next.add(t); next.add("🌐 " + t); } // 兼容自愈前的旧前缀标题
             }
             remoteTitles = next;
+            refreshRootLabels(r.workspaces);
             swapWorkspaceIconsIn(document.body); // 标题集就绪后补一次全量替换
+            applyRootLabelsIn(document.body);    // 树根标签同样补一次全量替换
           }).catch(function () {});
         }
         /** 地球经纬线组（右下角、无圆盘底色）：线为白色、其余全透明；文件夹本体完全
@@ -1247,12 +1251,83 @@ window.__ModuleLoader__.load({
             }
           } catch (e) {}
         }
+
+        // ---- 文件树根标签：显示远程目录名，而不是本地镜像目录 ID（issue #9）----
+        // better-sidebar「文件」页签的树根标签取自会话 cwd（= 本地镜像路径）的 basename，
+        // 于是显示成镜像目录 ID（如 wmu3sxe24jpvg）。这条链路不经过任何 fs.* 路由，
+        // 而 Host 侧 session.cwd 虽然已返回 root 字段，客户端只消费 cwd
+        // （client-registry 的 api.sessionCwd(...).then(r => setFetchedCwd(r.cwd))，
+        // 另有 useSessionCwd 直接读客户端会话列表的 cwd），因此只能在渲染层替换文本。
+        // 定位不依赖构建期哈希类名：根行是树里唯一带内联 padding-left:6px 的行，
+        // 仅当该行内的纯文本节点 === 某远程工作区的镜像 basename 时才替换（幂等、可自愈）。
+        var watchedRootLabels = []; // 已替换的标签元素：1s 幂等复检，抵消 React 重渲染
+        function refreshRootLabels(workspaces) {
+          var next = {};
+          for (var i = 0; i < (workspaces || []).length; i++) {
+            var w = workspaces[i] || {};
+            var mirror = String(w.mirrorPath || "").replace(/[\\/]+$/, "");
+            var remote = String(w.remotePath || "").replace(/[\\/]+$/, "");
+            if (!mirror || !remote) continue;
+            var mb = mirror.split(/[\\/]/).pop();
+            var rb = remote.split(/[\\/]/).pop();
+            if (mb && rb && mb !== rb) next[mb] = { label: rb, remotePath: remote };
+          }
+          rootLabels = next;
+        }
+        /** 根行判据：自身或 ≤3 层祖先带内联 padding-left:6px（better-sidebar 根行样式）。 */
+        function isRootRow(el) {
+          var node = el;
+          for (var hop = 0; hop < 3 && node; hop++) {
+            var style = node.getAttribute ? node.getAttribute("style") : null;
+            if (style && /padding-left:\s*6px/i.test(String(style))) return true;
+            node = node.parentElement;
+          }
+          return false;
+        }
+        /** 单个标签替换：纯文本 + 命中镜像 basename + 位于根行 → 换成远程目录名。 */
+        function fixRootLabel(el) {
+          var text = (el.textContent || "").trim();
+          if (!text) return false;
+          var hit = rootLabels[text];
+          if (hit === undefined) {
+            // 文本已是远程目录名（上一轮替换过）→ 幂等成功；否则与本插件无关
+            return el.getAttribute && el.getAttribute("data-rssh-root-label") === "1";
+          }
+          if (el.childElementCount > 0) return false; // 只改纯文本节点
+          if (!isRootRow(el)) return false;           // 非根行（例如同名子条目）不动
+          el.textContent = hit.label;
+          if (el.setAttribute) {
+            el.setAttribute("data-rssh-root-label", "1");
+            el.setAttribute("title", hit.remotePath); // 悬停可见完整远程路径
+          }
+          watchRootLabel(el);
+          return true;
+        }
+        function watchRootLabel(el) {
+          for (var i = 0; i < watchedRootLabels.length; i++) { if (watchedRootLabels[i] === el) return; }
+          watchedRootLabels.push(el);
+        }
+        function recheckRootLabels() {
+          for (var i = watchedRootLabels.length - 1; i >= 0; i--) {
+            var el = watchedRootLabels[i];
+            if (!el || !el.isConnected) { watchedRootLabels.splice(i, 1); continue; }
+            fixRootLabel(el);
+          }
+        }
+        function applyRootLabelsIn(root) {
+          if (!root || !root.querySelectorAll) return;
+          try {
+            var nodes = root.querySelectorAll("span,div");
+            for (var i = 0; i < nodes.length; i++) fixRootLabel(nodes[i]);
+            if (root.nodeType === 1) fixRootLabel(root);
+          } catch (e) {}
+        }
         ctx.effect(function () {
           if (typeof document === "undefined") return;
           applyRemoteNavIcon();
           refreshRemoteTitles();
           var titleTimer = setInterval(refreshRemoteTitles, 30000);
-          var recheckTimer = setInterval(recheckWatched, 1000); // 抵消 React 属性还原
+          var recheckTimer = setInterval(function () { recheckWatched(); recheckRootLabels(); }, 1000); // 抵消 React 属性还原
           var timer = null;
           var pendingRoots = null;
           var schedule = function (root) {
@@ -1265,13 +1340,14 @@ window.__ModuleLoader__.load({
               if (document.hidden) return; // 后台页签零开销
               if (roots && roots.length) {
                 // 只扫新增子树：流式聊天期间不做全文档扫描（稳态成本≈0）
-                // （设置导航图标已在 MutationObserver 回调里同步替换，这里只补工作区角标）
+                // （设置导航图标与树根标签已在 MutationObserver 回调里同步替换，这里只补工作区角标）
                 for (var i = 0; i < roots.length; i++) {
                   if (roots[i].isConnected) swapWorkspaceIconsIn(roots[i]);
                 }
               } else {
                 applyRemoteNavIcon(); // 语言切换等无根场景全量扫一次
                 swapWorkspaceIconsIn(document.body);
+                applyRootLabelsIn(document.body);
               }
             }, 500);
           };
@@ -1283,7 +1359,11 @@ window.__ModuleLoader__.load({
                 // 设置导航图标：同步原位替换。MutationObserver 回调是微任务，
                 // 在浏览器绘制前执行 —— 齿轮刚插入 DOM 就被换成显示器图标，
                 // 用户看到的第一帧就是最终图标（2.4.2 修复齿轮闪现）。
-                if (node && node.nodeType === 1 && node.isConnected) checkCellIn(node);
+                if (node && node.nodeType === 1 && node.isConnected) {
+                  checkCellIn(node);
+                  // 树根标签同样同步替换：微任务内、绘制前完成，避免先闪一下镜像目录 ID
+                  applyRootLabelsIn(node);
+                }
                 // 工作区地球角标依赖异步 remoteTitles，仍走防抖批量路径
                 schedule(node);
               }
@@ -1298,7 +1378,7 @@ window.__ModuleLoader__.load({
             clearInterval(titleTimer);
             clearInterval(recheckTimer);
           };
-        }, "dsh-remote-ssh: settings nav monitor icon + remote workspace folder-globe icon");
+        }, "dsh-remote-ssh: settings nav monitor icon + tree root label + remote workspace folder-globe icon");
       }
 
       // better-sidebar 0.15+ 的文件上传 UI 把原始字节流 POST 到 /sidebar/upload。

package/lib/index.js

@@ -1109,6 +1109,154 @@ function remoteWorkspaceReadme(profileName, remotePath) {
   ].join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// @ 文件引用补全的远端支持（issue #10）
+//
+// 「@」补全由宿主 ctx.fileReferences 服务提供（官方 provider：@deepseek-ai/dsh-file-reference-local），
+// 它只遍历**本地磁盘**——远程工作区会话里，会话 cwd 是本地镜像目录，于是候选只有镜像里那几个文件
+// （镜像通常只有本插件写入的 README.md 与 .remote-ssh.json）。这条链路不经过任何 HTTP 路由
+// （客户端经 remote gateway 调 ctx.fileReferences.list），所以只能用服务层方案：
+// 包装已注册的服务实例，远程工作区自己算候选，其余一律委托回原实现（本地索引/模糊排序零改动）。
+//
+// 查询语义与本地 provider 完全对齐（对照 dsh-file-reference-local 的 WorkspaceFileSearch）：
+//   - 空查询或含 "/"：目录列举（隐藏文件仅在小片段以 . 开头时可见；排除目录剪枝）
+//   - 纯片段：全量模糊搜索（子序列评分 + 目录加权 + 长度/字典序 tiebreak）
+// 索引来源对远端做了取舍：git 仓库用 `git ls-files --cached --others --exclude-standard`
+// （实测 0.1s / 尊重 .gitignore / 含未跟踪），非 git 退化为有界 find（maxdepth 5），
+// 结果按 workspace 缓存并挂到既有 cacheEpoch 上，写/exec 后自动失效。
+// ---------------------------------------------------------------------------
+
+/** 与本地 provider 的 maxResults 默认值一致。 */
+const REF_MAX_RESULTS = 20;
+/** 索引条目上限（本地默认 5 万；远端按传输与内存预算收紧）。 */
+const REF_MAX_ENTRIES = 20000;
+/** 索引缓存 TTL：过期后仍先用旧索引作答，重建在后台进行（与本地 provider 的陈旧索引策略一致）。 */
+const REF_INDEX_TTL_MS = 60000;
+/** 单次查询等待索引的预算：超过就返回旧索引/空，绝不把光标卡在 SSH 上。 */
+const REF_QUERY_BUDGET_MS = 900;
+/** 后台建索引的预算。 */
+const REF_INDEX_BUILD_TIMEOUT_MS = 20000;
+/** 非 git 仓库的 find 深度上限。 */
+const REF_FIND_MAXDEPTH = 5;
+/** 排除目录：与 @deepseek-ai/dsh-file-reference-local 的 DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES 逐条一致。 */
+const REF_EXCLUDED_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", "out", "coverage", "target",
+  ".next", ".nuxt", ".turbo", ".venv", "__pycache__", ".pytest_cache",
+  ".mypy_cache", ".gradle"
+]);
+const refIndexCache = new Map();  // key = profileKey|root -> { at, epoch, entries }
+const refIndexBuilds = new Map(); // key -> Promise<entries>（同一 workspace 只建一次）
+
+/** 拆分 @ 查询：返回 { directory, fragment, isDirectoryQuery }（与本地 list() 的分支判据一致）。 */
+function refSplitQuery(rawQuery) {
+  const query = String(rawQuery == null ? "" : rawQuery).replace(/\\/g, "/");
+  const slash = query.lastIndexOf("/");
+  if (query === "" || slash >= 0) {
+    return {
+      directory: slash < 0 ? "" : query.slice(0, slash + 1),
+      fragment: slash < 0 ? "" : query.slice(slash + 1),
+      isDirectoryQuery: true
+    };
+  }
+  return { directory: "", fragment: query, isDirectoryQuery: false };
+}
+
+/** 子序列评分（对照本地 subsequenceScore：按命中字符的间隔惩罚）。 */
+function refSubsequenceScore(target, query) {
+  let targetIndex = 0;
+  let gap = 0;
+  for (const character of query) {
+    const found = target.indexOf(character, targetIndex);
+    if (found < 0) return undefined;
+    gap += found - targetIndex;
+    targetIndex = found + 1;
+  }
+  return Math.max(0, 100 - gap);
+}
+
+/** 候选评分（逐字对照本地 scoreCandidate 的常量：1000/900/700/500/300 + 目录 25）。 */
+function refScoreCandidate(candidate, query) {
+  if (query === "") return 0;
+  const path = String(candidate.path).toLowerCase();
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  const needle = String(query).toLowerCase();
+  const directoryBonus = candidate.kind === "directory" ? 25 : 0;
+  if (name === needle) return 1000 + directoryBonus;
+  if (name.startsWith(needle)) return 900 + directoryBonus;
+  if (name.includes(needle)) return 700 + directoryBonus;
+  if (path.includes(needle)) return 500 + directoryBonus;
+  const subsequence = refSubsequenceScore(path, needle);
+  return subsequence === undefined ? undefined : 300 + subsequence + directoryBonus;
+}
+
+/** 排序（逐字对照本地 rankCandidates：评分降序 → 目录优先 → 路径短优先 → 字典序）。 */
+function refRankCandidates(candidates, query, limit) {
+  const ranked = [];
+  for (const candidate of candidates) {
+    const score = refScoreCandidate(candidate, query);
+    if (score !== undefined) ranked.push({ candidate, score });
+  }
+  const kindRank = (kind) => (kind === "directory" ? 0 : 1);
+  const compareText = (l, r) => (l < r ? -1 : l > r ? 1 : 0);
+  ranked.sort((left, right) =>
+    right.score - left.score ||
+    kindRank(left.candidate.kind) - kindRank(right.candidate.kind) ||
+    (query === "" ? 0 : left.candidate.path.length - right.candidate.path.length) ||
+    compareText(left.candidate.path, right.candidate.path));
+  return ranked.slice(0, limit).map((entry) => entry.candidate);
+}
+
+/** 隐藏文件可见性（对照本地 visibleForGlobalQuery）。 */
+function refVisibleForGlobalQuery(path, query) {
+  if (query.startsWith(".") || query.includes("/.")) return true;
+  return !String(path).split("/").some((segment) => segment.startsWith("."));
+}
+
+/** 解析索引输出（`<type>\t<path>` 逐行；git 分支只有 f，目录由父路径合成）。 */
+function refParseIndexOutput(text) {
+  const files = new Set();
+  const dirs = new Set();
+  const excludedSegment = (p) => p.split("/").some((seg) => REF_EXCLUDED_DIRS.has(seg));
+  for (const line of String(text || "").split("\n")) {
+    if (!line) continue;
+    const tab = line.indexOf("\t");
+    if (tab < 0) continue;
+    const type = line.slice(0, tab);
+    const path = line.slice(tab + 1).replace(/\r$/, "");
+    if (!path || excludedSegment(path)) continue;
+    if (type === "d") dirs.add(path);
+    else if (type === "f") files.add(path);
+    // 其它类型（符号链接等）跳过：与本地 provider 只收 isFile/isDirectory 一致
+  }
+  for (const path of Array.from(files)) {
+    let i = path.indexOf("/");
+    while (i > 0) {
+      const dir = path.slice(0, i);
+      if (excludedSegment(dir)) break;
+      dirs.add(dir);
+      i = path.indexOf("/", i + 1);
+    }
+  }
+  const out = [];
+  for (const d of Array.from(dirs).sort()) out.push({ path: d, kind: "directory" });
+  for (const f of Array.from(files).sort()) out.push({ path: f, kind: "file" });
+  return out.length > REF_MAX_ENTRIES ? out.slice(0, REF_MAX_ENTRIES) : out;
+}
+
+/** 远端建索引命令：git 仓库走 git ls-files（快且尊重 .gitignore），否则有界 find。 */
+function refIndexCommand(root) {
+  const target = shellQuotePath(root || "~");
+  const prune = Array.from(REF_EXCLUDED_DIRS).map((n) => "-name " + shellQuote(n)).join(" -o ");
+  return [
+    "cd " + target + " 2>/dev/null || exit 3",
+    "if [ -d .git ] && command -v git >/dev/null 2>&1; then",
+    "git ls-files --cached --others --exclude-standard 2>/dev/null | head -n " + (REF_MAX_ENTRIES + 1) + " | sed 's/^/f\t/'",
+    "else",
+    "find . -mindepth 1 -maxdepth " + REF_FIND_MAXDEPTH + " \\( " + prune + " \\) -prune -o -printf '%y\t%P\\n' 2>/dev/null | head -n " + (REF_MAX_ENTRIES + 1),
+    "fi"
+  ].join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // apply
 // ---------------------------------------------------------------------------
@@ -2815,8 +2963,124 @@ function apply(ctx, config) {
     handler: function (req, res) { return handleSidebarFile(req, res); }
   }), "dsh-remote-ssh: intercept /sidebar/file");
 
+  // ---- @ 文件引用补全：远程工作区走 SSH（issue #10）----
+  // 包装宿主 ctx.fileReferences 服务实例：远程工作区自己算候选，其余委托回原实现。
+  // 不替换 composition row（file-reference-local）也不需要新的 @deepseek-ai 运行时依赖：
+  // 本地会话的索引/模糊排序保持原样，零回归风险。
+  /** 远端目录列举（复用 remoteListDir 的 LRU 缓存），语义对齐本地 listDirectory。 */
+  async function remoteRefListDirectory(profile, root, displayDirectory, fragment) {
+    const dirRel = String(displayDirectory || "").replace(/\/+$/, "");
+    if (dirRel.split("/").some((seg) => seg && REF_EXCLUDED_DIRS.has(seg))) return [];
+    const base = String(root || "~").replace(/\/+$/, "") || "~";
+    const remoteDir = dirRel ? base + "/" + dirRel : base;
+    const r = await remoteListDir(runPooled, profile, remoteDir);
+    if (!r.ok) return [];
+    const out = [];
+    for (const e of r.entries || []) {
+      const name = String(e && e.name ? e.name : "");
+      if (!name) continue;
+      const isDir = e.type === "directory";
+      if (name.startsWith(".") && !String(fragment || "").startsWith(".")) continue;
+      if (isDir && REF_EXCLUDED_DIRS.has(name)) continue;
+      out.push({ path: String(displayDirectory || "") + name, kind: isDir ? "directory" : "file" });
+    }
+    return refRankCandidates(out, String(fragment || ""), REF_MAX_RESULTS);
+  }
+
+  /** 远端 workspace 索引：缓存 + 后台重建；单次查询只等 REF_QUERY_BUDGET_MS。 */
+  async function refIndexFor(profile, root) {
+    const pk = profileKey(profile);
+    const key = pk + "|" + String(root || "~");
+    const epoch = cacheEpoch(pk);
+    const hit = refIndexCache.get(key);
+    if (hit && hit.epoch === epoch && Date.now() - hit.at <= REF_INDEX_TTL_MS) return hit.entries;
+    let build = refIndexBuilds.get(key);
+    if (!build) {
+      build = (async () => {
+        try {
+          const r = await runPooled(profile, refIndexCommand(root), undefined, MAX_BYTES, false, REF_INDEX_BUILD_TIMEOUT_MS);
+          const entries = refParseIndexOutput(r && r.stdout ? r.stdout : "");
+          // 只有成功（或确实拿到了输出）才写缓存：cd 失败/断连时不能把空索引缓存 60 秒
+          if (r && (r.ok || (r.stdout && String(r.stdout).length > 0))) {
+            refIndexCache.set(key, { at: Date.now(), epoch, entries });
+          }
+          return entries;
+        } catch (e) {
+          return (hit && hit.entries) || [];
+        } finally {
+          refIndexBuilds.delete(key);
+        }
+      })();
+      refIndexBuilds.set(key, build);
+    }
+    try {
+      return await withTimeout(build, REF_QUERY_BUDGET_MS, "文件引用索引", null);
+    } catch (e) {
+      // 超时：先用陈旧索引作答（与本地 provider 的「陈旧索引照常回答、重建在后台」一致）
+      return (hit && hit.entries) || [];
+    }
+  }
+
+  /** 远程 @ 补全：查询语义与本地一致（目录查询 vs 模糊查询）。 */
+  async function remoteRefList(profile, root, query, signal) {
+    if (signal && signal.aborted) return [];
+    const split = refSplitQuery(query);
+    if (split.isDirectoryQuery) {
+      return await remoteRefListDirectory(profile, root, split.directory, split.fragment);
+    }
+    const entries = await refIndexFor(profile, root);
+    if (!entries.length) return [];
+    const visible = entries.filter((e) => refVisibleForGlobalQuery(e.path, split.fragment));
+    return refRankCandidates(visible, split.fragment, REF_MAX_RESULTS);
+  }
+
+  /** 该 agent 是远程工作区会话则返回远端候选，否则返回 null（调用方委托原实现）。 */
+  async function remoteRefListForAgent(agent, query, signal) {
+    const session = agent && agent.session;
+    const cwd = session && session.header && session.header.cwd;
+    if (!cwd) return null;
+    const info = readRemoteInfoSync(cwd);
+    if (!info || !info.host || !info.user || !info.keyPath) return null;
+    const profile = getProfile(info.profileId);
+    if (!profile) return null;
+    return await remoteRefList(profile, info.remotePath || "~", query, signal);
+  }
+
+  /** 包装服务实例；返回恢复函数（失败返回 null）。 */
+  function installFileReferenceBridge(sctx) {
+    const svc = sctx && typeof sctx.get === "function" ? sctx.get("fileReferences") : sctx && sctx.fileReferences;
+    if (!svc || typeof svc.list !== "function") return null;
+    const original = svc.list.bind(svc);
+    const patched = async function (agent, query, signal) {
+      try {
+        const remote = await remoteRefListForAgent(agent, query, signal);
+        if (remote !== null) return remote;
+      } catch (e) {
+        // 任何异常都降级到本地实现：补全不该因为远端问题而不可用
+      }
+      return original(agent, query, signal);
+    };
+    try {
+      svc.list = patched;
+    } catch (e) {
+      return null;
+    }
+    return function restoreFileReferenceList() {
+      try { if (svc.list === patched) svc.list = original; } catch (e) {}
+    };
+  }
+
+  let restoreFileReferences = null;
+  ctx.inject(["fileReferences"], (sctx) => {
+    restoreFileReferences = installFileReferenceBridge(sctx);
+    if (!restoreFileReferences) {
+      try { ctx.logger?.warn("[dsh-remote-ssh] fileReferences 服务不可包装，@ 补全在远程工作区仍只覆盖本地镜像"); } catch (e) {}
+    }
+  });
+
   // ---- 清理 ----
   ctx.effect(() => () => {
+    if (restoreFileReferences) { try { restoreFileReferences(); } catch (e) {} restoreFileReferences = null; }
     clearInterval(idleTimer);
     sessions.forEach(function (s) { try { s.close(); } catch (e) {} });
     sessions.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.4.5",
+  "version": "2.4.7",
   "description": "DSH web plugin: VSCode Remote-SSH-like remote development (SSH to supercomputers/servers, remote workspace, file explorer, integrated terminal), integrated with dsh-better-sidebar and DSH settings.",
   "keywords": [
     "dsh",