dsh-vscode-mode 0.7.0 → 0.9.0

package/src/lsp/server.ts

@@ -11,11 +11,18 @@ import { deriveDefinitionFromLocations } from './derive.js'
 import type { LspProviderSpec } from './providers.js'
 import { LSP_SEMANTIC_TOKEN_MODIFIERS, LSP_SEMANTIC_TOKEN_TYPES } from '../shared/lsp.js'
 import type {
+  LspCompletionItem,
+  LspCompletionList,
+  LspCompletionTextEdit,
   LspLocation,
+  LspParameterInformation,
+  LspRange,
   LspSemanticTokens,
   LspServerCapabilities,
   LspServerPhase,
   LspServerStatus,
+  LspSignatureHelp,
+  LspSignatureInformation,
   LspSymbol,
 } from '../shared/lsp.js'
 
@@ -34,6 +41,9 @@ export interface LspServer {
   documentSymbol(path: string): Promise<LspSymbol[]>
   workspaceSymbol(query: string): Promise<LspSymbol[]>
   hover(path: string, line: number, character: number): Promise<{ contents: string[] } | null>
+  completion(path: string, line: number, character: number, context?: unknown): Promise<LspCompletionList | null>
+  resolveCompletion(path: string, item: LspCompletionItem): Promise<LspCompletionItem | null>
+  signatureHelp(path: string, line: number, character: number): Promise<LspSignatureHelp | null>
   semanticTokens(path: string): Promise<LspSemanticTokens | null>
   dispose(): Promise<void>
 }
@@ -86,6 +96,9 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
     workspaceSymbol: false,
     hover: false,
     semanticTokens: false,
+    completion: false,
+    completionResolve: false,
+    signatureHelp: false,
     semanticTokenTypes: [...LSP_SEMANTIC_TOKEN_TYPES],
     semanticTokenModifiers: [...LSP_SEMANTIC_TOKEN_MODIFIERS],
   }
@@ -346,6 +359,69 @@ export function createLspServer(spec: LspProviderSpec, root: string, languageId:
       return { contents: stringifyHoverContents(result.contents) }
     },
 
+    /**
+     * 查询补全列表（textDocument/completion）。
+     *
+     * 列表阶段**剥离 documentation**：EmmyLua 把文档挂在 resolve 阶段（我方 initialize 已声明
+     * resolveSupport），但并非所有服务器都遵守；每条都带长文档会让单次 RPC 载荷暴涨。
+     * `data` 原样透传，resolve 时由服务器回认该条目。
+     * @author ddj 2026年09月22号
+     * @param path 工作区相对路径
+     * @param line 0-based 行
+     * @param character 0-based 列
+     * @param context LSP CompletionContext（触发字符/触发类型）
+     * @returns 归一化补全列表；不支持或文档未打开时 null
+     */
+    async completion(path: string, line: number, character: number, context?: unknown): Promise<LspCompletionList | null> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait) || !capabilities.completion) return null
+      const params: Record<string, unknown> = {
+        textDocument: { uri: doc.uri },
+        position: { line, character },
+      }
+      if (context) params.context = context
+      const result = await ensureClient().request<unknown>('textDocument/completion', params)
+      return normCompletion(result)
+    },
+
+    /**
+     * 补全项惰性补全（completionItem/resolve）：按 `data` 取回 documentation/detail/additionalTextEdits。
+     *
+     * 必须回传**完整条目**（服务器按 data + label 精确匹配），只发 label/data 可能被服务器忽略。
+     * @author ddj 2026年09月22号
+     * @param path 工作区相对路径
+     * @param item 列表阶段返回的补全项
+     * @returns 补全后的条目；服务器不支持时原样返回
+     */
+    async resolveCompletion(path: string, item: LspCompletionItem): Promise<LspCompletionItem | null> {
+      if (!item || typeof item.label !== 'string') return null
+      if (!(await readyWait) || !capabilities.completionResolve) return item
+      const result = await ensureClient().request<unknown>('completionItem/resolve', toLspCompItem(item))
+      const resolved = normCompItem(result)
+      return resolved ?? item
+    },
+
+    /**
+     * 查询签名帮助（textDocument/signatureHelp）。
+     *
+     * activeSignature/activeParameter 做边界裁剪：服务器可能给越界值（多签名时按实参推进出错），
+     * Monaco 拿到越界索引会取不到签名而不渲染 —— 裁剪后至少显示首个签名。
+     * @author ddj 2026年09月22号
+     * @param path 工作区相对路径
+     * @param line 0-based 行
+     * @param character 0-based 列
+     * @returns 归一化签名帮助；无签名/不支持时 null
+     */
+    async signatureHelp(path: string, line: number, character: number): Promise<LspSignatureHelp | null> {
+      const doc = docs.get(path)
+      if (!doc || !(await readyWait) || !capabilities.signatureHelp) return null
+      const result = await ensureClient().request<unknown>(
+        'textDocument/signatureHelp',
+        { textDocument: { uri: doc.uri }, position: { line, character } },
+      )
+      return toSignatureHelp(result)
+    },
+
     /** 查询全文 semantic tokens，并将服务器 legend 归一到插件固定 legend。 */
     async semanticTokens(path: string): Promise<LspSemanticTokens | null> {
       const doc = docs.get(path)
@@ -440,8 +516,202 @@ function normalizeSymbol(item: unknown): LspSymbol | null {
   return symbol
 }
 
-/** hover contents → 文本行（MarkupContent | MarkedString | MarkedString[]）。 */
-function stringifyHoverContents(contents: unknown): string[] {
+/** hover/markdown 内容 → 纯文本（string | MarkupContent | MarkedString[] | MarkedString）。 */
+function plainText(value: unknown): string | undefined {
+  if (typeof value === 'string') return value || undefined
+  if (Array.isArray(value)) {
+    const parts = value.map(plainText).filter((part): part is string => Boolean(part))
+    return parts.length ? parts.join('\n\n') : undefined
+  }
+  if (value && typeof value === 'object') {
+    // MarkedString 对象形态：{ language, value }；MarkupContent 形态：{ kind, value }
+    const text = (value as { value?: unknown }).value
+    if (typeof text === 'string') return text || undefined
+  }
+  return undefined
+}
+
+/**
+ * 归一化补全文本编辑范围（单 range 与 insert/replace 双 range 两种形态）。
+ *
+ * 两种形态必须都认：只认一种会让采用另一种形态的服务器补全落点错位（替换范围算错，
+ * 已输入的前缀被重复插入）。双 range 时 insert 用于「保留前缀插入」，replace 用于覆盖。
+ * @author ddj 2026年09月22号
+ * @param raw 原始 textEdit
+ * @returns 归一化文本编辑；无有效范围或文本时 null
+ */
+function normalizeTextEdit(raw: unknown): LspCompletionTextEdit | null {
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as { range?: unknown; insert?: unknown; replace?: unknown; newText?: unknown }
+  const newText = typeof obj.newText === 'string' ? obj.newText : ''
+  if (!newText) return null
+  const single = normalizeRange(obj.range)
+  if (single) return { range: single, newText }
+  const insert = normalizeRange(obj.insert)
+  const replace = normalizeRange(obj.replace)
+  if (!insert && !replace) return null
+  return { insert: insert ?? replace!, replace: replace ?? insert!, newText }
+}
+
+/** 归一化 LSP Range（缺字段返回 null，避免产出畸形范围）。 */
+function normalizeRange(raw: unknown): LspRange | null {
+  if (!raw || typeof raw !== 'object') return null
+  const r = raw as { start?: { line?: unknown; character?: unknown }; end?: { line?: unknown; character?: unknown } }
+  if (!r.start || !r.end) return null
+  return {
+    start: { line: toInt(r.start.line), character: toInt(r.start.character) },
+    end: { line: toInt(r.end.line), character: toInt(r.end.character) },
+  }
+}
+
+/**
+ * 归一化单个补全项。
+ * @author ddj 2026年09月22号
+ * @param raw 原始条目
+ * @returns 归一化条目；缺 label 时 null
+ */
+export function normCompItem(raw: unknown): LspCompletionItem | null {
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as Record<string, unknown>
+  const label = typeof obj.label === 'string' ? obj.label : ''
+  if (!label) return null
+  const item: LspCompletionItem = { label }
+  if (typeof obj.kind === 'number') item.kind = toInt(obj.kind)
+  if (typeof obj.detail === 'string' && obj.detail) item.detail = obj.detail
+  const documentation = plainText(obj.documentation)
+  if (documentation) item.documentation = documentation
+  if (typeof obj.insertText === 'string') item.insertText = obj.insertText
+  if (typeof obj.insertTextFormat === 'number') item.insertTextFormat = toInt(obj.insertTextFormat)
+  const textEdit = normalizeTextEdit(obj.textEdit)
+  if (textEdit) item.textEdit = textEdit
+  if (obj.data !== undefined) item.data = obj.data
+  if (typeof obj.sortText === 'string') item.sortText = obj.sortText
+  if (typeof obj.filterText === 'string') item.filterText = obj.filterText
+  if (obj.preselect === true) item.preselect = true
+  if (Array.isArray(obj.commitCharacters)) {
+    const chars = obj.commitCharacters.filter((c): c is string => typeof c === 'string')
+    if (chars.length) item.commitCharacters = chars
+  }
+  // 弃用标记两处来源：顶层 deprecated（旧草案）与 tags 含 1（CompletionItemTag.Deprecated）
+  const tags = Array.isArray(obj.tags) ? obj.tags : []
+  if (obj.deprecated === true || tags.some((tag) => toInt(tag) === 1)) item.deprecated = true
+  if (Array.isArray(obj.additionalTextEdits)) {
+    const edits = obj.additionalTextEdits
+      .map((edit) => {
+        const range = normalizeRange((edit as { range?: unknown } | null)?.range)
+        const text = (edit as { newText?: unknown } | null)?.newText
+        if (!range || typeof text !== 'string') return null
+        return { range, newText: text }
+      })
+      .filter((edit): edit is { range: LspRange; newText: string } => edit !== null)
+    if (edits.length) item.additionalTextEdits = edits
+  }
+  return item
+}
+
+/**
+ * 归一化补全结果（CompletionList | CompletionItem[]）。
+ *
+ * 两种顶层形态都要认：`{ isIncomplete, items }` 与裸数组。裸数组是最常见形态，
+ * 只认 CompletionList 会让「补全列表恒为空」且无报错。
+ * @author ddj 2026年09月22号
+ * @param result 原始响应
+ * @returns 归一化列表；无效时 null
+ */
+export function normCompletion(result: unknown): LspCompletionList | null {
+  if (result == null) return null
+  const list = Array.isArray(result)
+    ? { items: result, isIncomplete: false }
+    : (result as { items?: unknown; isIncomplete?: unknown })
+  if (!Array.isArray(list.items)) return null
+  const items = list.items
+    .map(normCompItem)
+    .filter((item): item is LspCompletionItem => item !== null)
+  // 截断由 RPC 层按统一上限处理（与 definition/references 同口径），此处不下刀
+  return { items, incomplete: list.isIncomplete === true }
+}
+
+/**
+ * 补全项 → LSP 载荷（resolve 回传用）。
+ * 只回传协议字段，剔除 client 侧衍生字段；`data` 必须原样带上，服务器靠它认条目。
+ * @author ddj 2026年09月22号
+ * @param item 归一化条目
+ * @returns LSP CompletionItem 载荷
+ */
+export function toLspCompItem(item: LspCompletionItem): Record<string, unknown> {
+  const out: Record<string, unknown> = { label: item.label }
+  if (item.kind !== undefined) out.kind = item.kind
+  if (item.detail !== undefined) out.detail = item.detail
+  if (item.documentation !== undefined) out.documentation = item.documentation
+  if (item.insertText !== undefined) out.insertText = item.insertText
+  if (item.insertTextFormat !== undefined) out.insertTextFormat = item.insertTextFormat
+  if (item.data !== undefined) out.data = item.data
+  if (item.sortText !== undefined) out.sortText = item.sortText
+  if (item.filterText !== undefined) out.filterText = item.filterText
+  if (item.textEdit) out.textEdit = item.textEdit.range ? { range: item.textEdit.range, newText: item.textEdit.newText } : item.textEdit
+  if (item.additionalTextEdits) out.additionalTextEdits = item.additionalTextEdits
+  if (item.commitCharacters) out.commitCharacters = item.commitCharacters
+  return out
+}
+
+/** 归一化单个签名参数（label 支持字符串与 [start, end] 元组，两者原样透传）。 */
+function toSignatureParam(raw: unknown): LspParameterInformation | null {
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as { label?: unknown; documentation?: unknown }
+  const tuple = Array.isArray(obj.label) && obj.label.length >= 2
+    ? [toInt(obj.label[0]), toInt(obj.label[1])] as [number, number]
+    : null
+  if (typeof obj.label !== 'string' && !tuple) return null
+  const param: LspParameterInformation = { label: typeof obj.label === 'string' ? obj.label : tuple! }
+  const documentation = plainText(obj.documentation)
+  if (documentation) param.documentation = documentation
+  return param
+}
+
+/** 归一化单个签名。 */
+function toSignature(raw: unknown): LspSignatureInformation | null {
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as { label?: unknown; documentation?: unknown; parameters?: unknown; activeParameter?: unknown }
+  if (typeof obj.label !== 'string') return null
+  const signature: LspSignatureInformation = { label: obj.label, parameters: [] }
+  const documentation = plainText(obj.documentation)
+  if (documentation) signature.documentation = documentation
+  if (Array.isArray(obj.parameters)) {
+    signature.parameters = obj.parameters
+      .map(toSignatureParam)
+      .filter((param): param is LspParameterInformation => param !== null)
+  }
+  if (typeof obj.activeParameter === 'number') signature.activeParameter = toInt(obj.activeParameter)
+  return signature
+}
+
+/**
+ * 归一化签名帮助，并裁剪越界的 activeSignature / activeParameter。
+ *
+ * 为什么必须裁：Monaco 用这两个索引直接取签名与参数，越界时取不到签名就整个浮窗不渲染；
+ * 服务器在「实参刚敲下逗号」等边界时刻常给超前一位的索引。裁剪后至少显示首个签名/末个参数，
+ * 观感是「高亮没跟上」，而不是「参数提示整个不见」。
+ * @author ddj 2026年09月22号
+ * @param result 原始响应
+ * @returns 归一化结果；无有效签名时 null
+ */
+export function toSignatureHelp(result: unknown): LspSignatureHelp | null {
+  if (!result || typeof result !== 'object') return null
+  const obj = result as { signatures?: unknown; activeSignature?: unknown; activeParameter?: unknown }
+  if (!Array.isArray(obj.signatures)) return null
+  const signatures = obj.signatures
+    .map(toSignature)
+    .filter((signature): signature is LspSignatureInformation => signature !== null)
+  if (!signatures.length) return null
+  const activeSignature = Math.min(Math.max(0, toInt(obj.activeSignature)), signatures.length - 1)
+  const current = signatures[activeSignature]!
+  const rawActive = typeof obj.activeParameter === 'number' ? toInt(obj.activeParameter) : (current.activeParameter ?? 0)
+  const count = current.parameters.length
+  const activeParameter = count > 0 ? Math.min(Math.max(0, rawActive), count - 1) : 0
+  return { signatures, activeSignature, activeParameter }
+}
+
+/** hover contents → 文本行（MarkupContent | MarkedString | MarkedString[]）。 */function stringifyHoverContents(contents: unknown): string[] {
   if (typeof contents === 'string') return [contents]
   if (Array.isArray(contents)) return contents.map(stringifyHoverContents).flat().filter(Boolean)
   if (contents && typeof contents === 'object') {

package/src/model.ts

@@ -32,7 +32,8 @@ export function normalizeRecord(raw: unknown): DiffRecord | null {
       }
     })
     : []
-  const toolName: DiffRecord['toolName'] = r.toolName === 'write' ? 'write' : 'edit'
+  // 白名单保留已知工具名，未知/缺失回退 'edit'（旧 sidecar 语义不变）
+  const toolName: DiffRecord['toolName'] = r.toolName === 'write' || r.toolName === 'remote_ssh_write' ? r.toolName : 'edit'
   const rawDecisions = r.decisions && typeof r.decisions === 'object' ? r.decisions as Record<string, unknown> : {}
   const call = rawDecisions.call === 'accepted' || rawDecisions.call === 'rejected' ? rawDecisions.call : 'pending'
   const rawPerHunk = Array.isArray(rawDecisions.perHunk) ? rawDecisions.perHunk : []

package/src/perf.ts

@@ -12,6 +12,7 @@ import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/p
 import { dirname, join, resolve, sep } from 'node:path'
 import { parseSidecar } from './store.js'
 import { recSummary } from './model.js'
+import { log } from './log.js'
 import { SIDECAR, SIDECAR_ARCHIVE, dshHome, sessionIdSegment, sessionWorkspaceKey, sessionsRoot } from './paths.js'
 import type { PerfMoveFailure, PerfMoveItem, PerfSession, PerfTotals, PerfWorkspace, SidecarPerfSummary } from './shared/rpc.js'
 import type { Ctx } from './store.js'
@@ -112,13 +113,76 @@ export async function scanSessionInventory(home = dshHome(), archive = sessionsA
   return { workspaces, sessions, totals: { workspaces: workspaces.length, sessions: totalCount, totalBytes } }
 }
 
-/** 标记活跃会话（live id 与目录段名双向匹配，兼容编码差异）。 */
-export function markActiveSessions(sessions: PerfSession[], activeIds: Iterable<string>): void {
-  const raw = new Set(activeIds)
+/** id 双向匹配器：原始 id 与编码段名任一命中（兼容编码差异）。 */
+function idMatcher(ids: Iterable<string>): (id: string) => boolean {
+  const raw = new Set(ids)
   const encoded = new Set<string>()
   for (const id of raw) encoded.add(sessionIdSegment(id))
+  return (id) => raw.has(id) || encoded.has(id)
+}
+
+/** 标记活跃会话（live id 与目录段名双向匹配，兼容编码差异）。 */
+export function markActiveSessions(sessions: PerfSession[], activeIds: Iterable<string>): void {
+  const match = idMatcher(activeIds)
   for (const s of sessions) {
-    if (raw.has(s.sessionId) || encoded.has(s.sessionId)) s.active = true
+    if (match(s.sessionId)) s.active = true
+  }
+}
+
+/** 官方归档/置顶标志 id 集合（registry 缺服务/缺字段时为空集）。 */
+interface OfficialFlagIds {
+  archived: Set<string>
+  pinned: Set<string>
+}
+
+/** 空标志集合（服务/字段缺失的统一降级返回值）。 */
+function emptyFlagIds(): OfficialFlagIds {
+  return { archived: new Set(), pinned: new Set() }
+}
+
+/** 任意值 → id 字符串集合（非数组或非字符串元素一律丢弃）。 */
+function toIdSet(ids: unknown): Set<string> {
+  if (!Array.isArray(ids)) return new Set()
+  return new Set(ids.filter((id): id is string => typeof id === 'string'))
+}
+
+/**
+ * 一次读取 workspaceRegistry 的官方归档/置顶 id 集合（摊到盘点各行使用）。
+ * 服务缺失、字段缺失或非数组（DSH 0.1.6 及更旧没有）一律视为空集，绝不抛错。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @returns archived/pinned 两组 id 集合（缺失即空集）
+ */
+export function registryFlags(ctx: Ctx): OfficialFlagIds {
+  try {
+    const registry = ctx.get('workspaceRegistry')
+    if (!registry) return emptyFlagIds()
+    return { archived: toIdSet(registry.archivedSessionIds), pinned: toIdSet(registry.pinnedSessionIds) }
+  } catch (error) {
+    log.debug('registryFlags 跳过（服务缺失或读取失败）：' + String(error))
+    return emptyFlagIds()
+  }
+}
+
+/**
+ * 给盘点行附官方归档/置顶标志（best-effort：仅命中附 true，缺失/未命中不附字段），
+ * 让 PerfSettings 会话行能看到官方侧栏的归档/置顶状态。id 匹配复用 markActiveSessions
+ * 的双向（原始 id / 编码段名）口径；服务/字段缺失不附字段、绝不抛错（旧 host 兼容降级）。
+ * @author ddj 2026年09月22号
+ * @param sessions 盘点会话行（就地附加 archived/pinned）
+ * @param ctx DSH 上下文
+ */
+export function markOfficialFlags(sessions: PerfSession[], ctx: Ctx): void {
+  try {
+    const flags = registryFlags(ctx)
+    const archived = idMatcher(flags.archived)
+    const pinned = idMatcher(flags.pinned)
+    for (const s of sessions) {
+      if (archived(s.sessionId)) s.archived = true
+      if (pinned(s.sessionId)) s.pinned = true
+    }
+  } catch (error) {
+    log.debug('markOfficialFlags 跳过（读取失败，保持无标志）：' + String(error))
   }
 }
 
@@ -239,6 +303,28 @@ export async function restoreSession(home: string, archive: string, workspaceKey
   }
 }
 
+/**
+ * 恢复后对齐官方归档标志（best-effort）：官方 archive 是 workspaceRegistry 的
+ * archivedSessionIds 持久标志（只藏 UI/拦模型步骤，不搬目录；dsh-workspace 源码注明
+ * unarchiveSession 对未归档与未知 id 均为无写入 no-op、对失踪会话也容忍）。
+ * 插件把目录搬回后若该会话曾被官方归档，官方侧栏会继续隐藏它、0.1.7 的
+ * archived-session-gate 会继续拦它的模型步骤——这里探测 host 的 workspaceRegistry
+ * 服务做一次幂等清除；服务缺失、id 编码差异未命中或调用抛错一律静默跳过
+ * （保持现状，不加猜的行为）。有效期：仅恢复成功后触发一次，不轮询不重试。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @param sessionId 恢复的会话 id（目录段名与原始 id 同形时可命中官方标志）
+ */
+export async function unarchiveOfficial(ctx: Ctx, sessionId: string): Promise<void> {
+  try {
+    const registry = ctx.get('workspaceRegistry')
+    if (!registry || typeof registry.unarchiveSession !== 'function') return
+    await registry.unarchiveSession(sessionId)
+  } catch (error) {
+    log.debug('unarchiveOfficial 跳过（服务缺失或调用失败，保持现状）：' + String(error))
+  }
+}
+
 /** 清除归档区早于 N 天的会话（破坏性，仅限归档区）。 */
 export async function purgeArchive(archive: string, olderThanDays: number): Promise<{ removed: number; reclaimedBytes: number }> {
   const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000

package/src/remoteWorkspace.ts

@@ -0,0 +1,177 @@
+/**
+ * dsh-vscode-mode host — dsh-remote-ssh 远程工作区探测与镜像↔远端路径映射。
+ * 背景（issue #7）：dsh-remote-ssh 的「原生远程工作区」cwd 指向本机镜像目录
+ * （如 ~/.dsh/remote-workspaces/<id>，根下含 .remote-ssh.json {profileId, host,
+ * user, remotePath}），agent 的 remote_ssh_write 直写远端；差异审查需要把
+ * 远端参数路径映射回镜像（捕获/读/决策复用本地链路），并把展示路径翻译成远端形态。
+ * 判据与上游 dsh-remote-ssh 的 findMirrorRoot 对齐（host/user/remotePath 必填、
+ * 向上 ≤8 层有界）；纯函数为主，node:fs 仅用于标记读取（带 60s TTL 缓存）。
+ * 作者 ddj 2026年09月23号
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+// --region 常量与类型
+/** dsh-remote-ssh 工作区标记文件名。 */
+const MARKER = '.remote-ssh.json'
+/** 向上探测的最大层数（含 cwd 自身；与上游 findMirrorRoot 的 8 层有界一致）。 */
+const MAX_DEPTH = 8
+/** 探测结果 TTL（edrv.list 为 5s 轮询，避免每轮都做文件 IO）。 */
+const TTL_MS = 60_000
+
+/** 远程工作区（镜像根 + 标记内容）。 */
+export interface RemoteWs {
+  /** 镜像根（含标记文件的目录，平台绝对路径）。 */
+  root: string
+  host: string
+  user: string
+  /** 远端工作区目录（`~/proj` 或绝对路径，原样保留）。 */
+  remotePath: string
+  profileId?: string
+}
+// --endregion
+
+// --region 探测
+/** cwd → { at, ws } 探测缓存（含阴性结果）。 */
+const cache = new Map<string, { at: number; ws: RemoteWs | null }>()
+
+/**
+ * 标记内容 → 远程工作区（host/user/remotePath 缺任一字段判非法，与上游一致）。
+ * @author ddj 2026年09月23号
+ * @param root 标记所在目录
+ * @param raw 标记文件文本
+ * @returns 合法返回 RemoteWs；非法返回 null
+ */
+function markerWsOf(root: string, raw: string): RemoteWs | null {
+  try {
+    const info = JSON.parse(raw) as Record<string, unknown>
+    if (typeof info.host !== 'string' || !info.host) return null
+    if (typeof info.user !== 'string' || !info.user) return null
+    if (typeof info.remotePath !== 'string' || !info.remotePath) return null
+    const ws: RemoteWs = { root, host: info.host, user: info.user, remotePath: info.remotePath }
+    if (typeof info.profileId === 'string' && info.profileId) ws.profileId = info.profileId
+    return ws
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 从 cwd 起向上有界探测标记（不走缓存）。
+ * @author ddj 2026年09月23号
+ * @param cwd 会话工作区根
+ * @returns 命中合法标记返回 RemoteWs；否则 null
+ */
+function walkRemoteWs(cwd: string): RemoteWs | null {
+  let dir = cwd
+  for (let i = 0; i < MAX_DEPTH; i++) {
+    try {
+      const ws = markerWsOf(dir, readFileSync(join(dir, MARKER), 'utf8'))
+      if (ws) return ws
+    } catch {
+      // 无标记或不可读/JSON 损坏：继续向上（与上游 findMirrorRoot 行为一致）
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * 探测工作区是否为 dsh-remote-ssh 远程工作区（cwd 或向上 ≤8 层找 .remote-ssh.json）。
+ * 结果按 cwd 缓存 60s（含阴性）；标记变更后可用 clearWsCache 立即重置。
+ * @author ddj 2026年09月23号
+ * @param cwd 会话工作区根（可空）
+ * @returns 远程工作区信息；非远程或标记非法返回 null
+ */
+export function findRemoteWs(cwd: string | null | undefined): RemoteWs | null {
+  if (!cwd) return null
+  const now = Date.now()
+  const hit = cache.get(cwd)
+  if (hit && now - hit.at < TTL_MS) return hit.ws
+  const ws = walkRemoteWs(cwd)
+  cache.set(cwd, { at: now, ws })
+  return ws
+}
+
+/**
+ * 清空探测缓存（测试与标记变更后重置用）。
+ * @author ddj 2026年09月23号
+ */
+export function clearWsCache(): void {
+  cache.clear()
+}
+// --endregion
+
+// --region 路径映射
+/**
+ * 前缀剥离：path 必须严格位于 root 之下；等于 root 或不匹配返回 null。
+ * @author ddj 2026年09月23号
+ * @param path 待剥离路径（posix 形态）
+ * @param root 前缀（posix 形态、无尾斜杠）
+ * @returns 相对段；不匹配返回 null
+ */
+function prefixRel(path: string, root: string): string | null {
+  if (path === root || !path.startsWith(root + '/')) return null
+  return path.slice(root.length + 1)
+}
+
+/**
+ * 远端参数路径 → 相对远端工作区目录的相对段。
+ * 支持：相对路径（工具语义即基于远端工作区目录）、绝对路径且 remotePath 为绝对
+ * 形态并为其前缀、`~` 形态且 remotePath 同为 `~` 前缀；Windows 盘符形态按
+ * 非远端语义拒绝。含 `..` 逃逸或空相对段返回 null。
+ * @author ddj 2026年09月23号
+ * @param argPath remote_ssh_write 的 path 参数
+ * @param ws 远程工作区
+ * @returns posix 相对段；不可映射返回 null
+ */
+function remoteRelOf(argPath: string, ws: RemoteWs): string | null {
+  const path = argPath.replace(/\\/g, '/').replace(/^\.\//, '')
+  if (!path) return null
+  const root = ws.remotePath.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (!root) return null
+  let rel: string | null
+  if (path.startsWith('/')) {
+    rel = root.startsWith('/') ? prefixRel(path, root) : null
+  } else if (path === '~' || path.startsWith('~/')) {
+    rel = root.startsWith('~/') ? prefixRel(path, root) : null
+  } else if (/^[A-Za-z]:\//.test(path)) {
+    rel = null
+  } else {
+    rel = path
+  }
+  if (rel === null || rel.split('/').some((seg) => seg === '..')) return null
+  return rel
+}
+
+/**
+ * 远端工具参数路径 → 本机镜像绝对路径。
+ * @author ddj 2026年09月23号
+ * @param argPath remote_ssh_write 的 path 参数
+ * @param ws 远程工作区
+ * @returns 镜像内绝对路径；镜像外/前缀形态不一致/逃逸返回 null
+ */
+export function mirrorTargetOf(argPath: string, ws: RemoteWs): string | null {
+  const rel = remoteRelOf(argPath, ws)
+  return rel === null ? null : join(ws.root, rel)
+}
+
+/**
+ * 镜像内绝对路径 → 远端展示路径（remotePath + 相对段，posix 拼接）。
+ * @author ddj 2026年09月23号
+ * @param mirrorAbs 镜像内绝对路径（通常是记录 path）
+ * @param ws 远程工作区
+ * @returns 远端路径；不在镜像根下返回 null（调用方回落原 path）
+ */
+export function remoteDisplayOf(mirrorAbs: string, ws: RemoteWs): string | null {
+  const path = mirrorAbs.replace(/\\/g, '/')
+  const root = ws.root.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (!root) return null
+  const rel = prefixRel(path, root)
+  if (rel === null || rel.split('/').some((seg) => seg === '..')) return null
+  const remoteRoot = ws.remotePath.replace(/\/+$/, '')
+  return remoteRoot + '/' + rel
+}
+// --endregion

package/src/routes.ts

@@ -80,7 +80,7 @@ export function registerRoutes(
   ctx.effect(() => guarded({
     kind: 'exact',
     path: RPC_PATH,
-    handler: async (req: unknown, res: { statusCode?: number; setHeader: (k: string, v: string) => void; end: (b?: string) => void }) => {
+    handler: async (req: unknown, res: { statusCode?: number; setHeader: (k: string, v: string) => void; end: (b?: string | Uint8Array) => void }) => {
       try {
         const chunks: Uint8Array[] = []
         for await (const chunk of req as AsyncIterable<Uint8Array>) chunks.push(chunk)
@@ -92,6 +92,18 @@ export function registerRoutes(
         }
         const method = (typeof input.method === 'string' ? input.method : '') as RpcMethod
         const result = await handleRpc(method, (input.args ?? {}) as never)
+        // 二进制预览信封（edrv.readBinary）：octet-stream + 元数据头直出原始字节，
+        // 省 base64 ~33% 体积；错误与其余方法仍走下方 JSON 分支（client 侧据此识别并回退）
+        const bin = (result as { ok?: boolean; binary?: { bytes?: Uint8Array; mime?: string; size?: number; version?: string } } | null)?.binary
+        if (result && (result as { ok?: boolean }).ok === true && bin?.bytes instanceof Uint8Array) {
+          res.statusCode = 200
+          res.setHeader('content-type', 'application/octet-stream')
+          res.setHeader('x-edrv-mime', String(bin.mime ?? ''))
+          res.setHeader('x-edrv-version', String(bin.version ?? ''))
+          res.setHeader('x-edrv-size', String(bin.size ?? bin.bytes.byteLength))
+          res.end(Buffer.from(bin.bytes))
+          return
+        }
         res.statusCode = 200
         res.setHeader('content-type', 'application/json')
         res.end(JSON.stringify(result))