dsh-vscode-mode 0.7.0 → 0.8.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/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/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))

package/src/rpc.ts

@@ -34,7 +34,7 @@ import { rulesList, rulesRead, rulesRemove, rulesSave, rulesToggle } from './rul
 import { isSnippetFilePath, snippetsEntries, snippetsList, snippetsRead, snippetsRemove, snippetsSave } from './snippets.js'
 import { listMcp, refreshMcp, removeMcp, saveMcp, toggleMcp } from './mcp.js'
 import { listProjects, projectRefresh, projectRemove, projectSave, projectToggle } from './mcpProject.js'
-import { normalizeFileOpenTool, FILE_OPEN_DEFAULT, FILE_OPEN_SETTINGS_NS } from './fileOpenSettings.js'
+import { normalizeFileOpenTool, FILE_OPEN_DEFAULT, FILE_OPEN_SETTINGS_NS, sectionOf, updateSection } from './fileOpenSettings.js'
 import { INTEGRATION_BASE_DEFAULT } from './shared/integration.js'
 import { shellMenuRegister, shellMenuRemove, shellMenuStatus } from './integrate.js'
 import { unityAdd, unityInstall, unityList, unityRemove } from './unityBridge.js'
@@ -47,7 +47,7 @@ import { invalidateIndex, listDirCached } from './treeIndex.js'
 import { revealInExplorer } from './reveal.js'
 import { dshHome, debugLogFile, pluginLogRoot } from './paths.js'
 import { clearDebugLog, debugRecord, isDebugLogName, listDebugLogs, readDebugLog } from './debugLog.js'
-import { markActiveSessions, moveOutSessions, planMoveOut, purgeArchive, restoreSession, scanSessionInventory, sessionsArchiveRoot, sessionSizeOf, sidecarSummaryOf } from './perf.js'
+import { markActiveSessions, markOfficialFlags, moveOutSessions, planMoveOut, purgeArchive, restoreSession, scanSessionInventory, sessionsArchiveRoot, sessionSizeOf, sidecarSummaryOf, unarchiveOfficial } from './perf.js'
 import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfConfigBlock } from './perfPatch.js'
 import type { FileVersions } from './fileVersions.js'
 
@@ -107,6 +107,57 @@ function snippetTargetOf(path: string): string | null {
   return isSnippetFilePath(path) ? path.replace(/\\/g, '/') : null
 }
 
+/** readTargetOf 成功形态：解析后的目标路径、stat 信息与 fs 服务句柄。 */
+interface ReadTargetOk {
+  target: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  fs: any
+  info: { version?: unknown; size?: number }
+}
+
+/**
+ * 二进制/文本读取共用前置（edrv.read 与 edrv.readBinary）：解析路径 + debugRecord +
+ * stat + 文件类型校验 + 32MB 二进制上限，保证两条读通道的错误口径完全一致。
+ * @author ddj 2026年09月22号
+ * @param ctx DSH 上下文
+ * @param sc requireSession 成功结果（session + cwd）
+ * @param path 客户端请求路径
+ * @returns 成功返回解析目标与 stat；失败返回错误文案（文件不存在时附 resolvedPath）
+ */
+async function readTargetOf(
+  ctx: Ctx,
+  sc: { session: Session; cwd: string },
+  path: string,
+): Promise<ReadTargetOk | { err: string; resolvedPath?: string }> {
+  const fs = ctx.get('fs')
+  if (!fs) return { err: '缺少 fs' }
+  try {
+    const target = await resolveTarget(ctx, sc.session, path)
+    debugRecord(ctx, sc.cwd, '[DEBUG path.resolve] input=' + String(path ?? '') + ' resolved=' + fs.processPath(target), 'debug')
+    const info = await fs.stat(target)
+    if (!info || info.type !== 'file') {
+      // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
+      return { err: '文件不存在', resolvedPath: fs.processPath(target) }
+    }
+    if ((info.size ?? 0) > BINARY_READ_CAP) return { err: '文件过大（>32MB），不支持整文件预览' }
+    return { target, fs, info }
+  } catch (error) {
+    return { err: '读取失败：' + String(error) }
+  }
+}
+
+/**
+ * readTargetOf 失败结果 → RPC 错误载荷（文件不存在时保留 resolvedPath 供诊断）。
+ * @author ddj 2026年09月22号
+ * @param prep readTargetOf 的失败分支
+ * @returns { ok:false } 形态载荷
+ */
+function targetErrOf(prep: { err: string; resolvedPath?: string }): { ok: false; error: string; resolvedPath?: string } {
+  return prep.resolvedPath !== undefined
+    ? { ok: false, error: prep.err, resolvedPath: prep.resolvedPath }
+    : { ok: false, error: prep.err }
+}
+
 /**
  * 本地文件系统版本令牌（mtime+size）：与 ctx.fs 的不透明版本串用途相同，
  * 仅供全局片段文件（走 node:fs 直读、不经 ctx.fs）在 edrv.read 时回带。
@@ -241,8 +292,7 @@ async function latestPatchBackup(patchPath: string): Promise<string | undefined>
 /** 读取设置中的深链基址（缺省/非法回退默认 3080）。 */
 async function integrationBaseUrlOf(ctx: Ctx): Promise<string> {
   const settings = ctx.get('settings')
-  const descriptor = settings?.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === FILE_OPEN_SETTINGS_NS)
-  const value = descriptor?.value as { integrationBaseUrl?: unknown } | undefined
+  const value = sectionOf(settings, FILE_OPEN_SETTINGS_NS)?.value as { integrationBaseUrl?: unknown } | undefined
   const raw = typeof value?.integrationBaseUrl === 'string' ? value.integrationBaseUrl.trim() : ''
   return raw || INTEGRATION_BASE_DEFAULT
 }
@@ -433,26 +483,36 @@ export function buildHandlers(
       }
       const sc = await requireSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false, error: sc.err }
-      const fs = ctx.get('fs')
-      if (!fs) return { ok: false, error: '缺少 fs' }
+      const prep = await readTargetOf(ctx, sc, args.path)
+      if ('err' in prep) return targetErrOf(prep)
       try {
-        const target = await resolveTarget(ctx, sc.session, args.path)
-         debugRecord(ctx, sc.cwd, '[DEBUG path.resolve] input=' + String(args.path ?? '') + ' resolved=' + fs.processPath(target), 'debug')
-        const info = await fs.stat(target)
-        if (!info || info.type !== 'file') {
-          // 带上解析后的真实路径：跳转失败时可直接看出是路径解析错还是目标本身不存在
-          return { ok: false, error: '文件不存在', resolvedPath: fs.processPath(target) }
-        }
-        if ((info.size ?? 0) > BINARY_READ_CAP) return { ok: false, error: '文件过大（>32MB），不支持整文件预览' }
         if (args.encoding === 'base64') {
-          // 图片/PDF 等二进制预览：readBytes 无解码、无二进制拒绝；超上限已由上方 stat 拦截
-          const bytes = await fs.readBytes(target, undefined, BINARY_READ_CAP)
+          // 图片/PDF 等二进制预览：readBytes 无解码、无二进制拒绝；超上限已由 readTargetOf 拦截
+          const bytes = await prep.fs.readBytes(prep.target, undefined, BINARY_READ_CAP)
           const content = Buffer.from(bytes).toString('base64')
-          return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(info.version ?? '') }
+          return { ok: true, content, size: bytes.byteLength, encoding: 'base64', mime: binaryMimeOf(args.path), version: String(prep.info.version ?? '') }
+        }
+        if ((prep.info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
+        const content = await prep.fs.readText(prep.target)
+        return { ok: true, content, size: content.length, version: String(prep.info.version ?? '') }
+      } catch (error) {
+        return { ok: false, error: '读取失败：' + String(error) }
+      }
+    },
+    'edrv.readBinary': async (args) => {
+      // 二进制直读通道（图片/PDF 预览）：与 edrv.read base64 分支共用 readTargetOf 前置，
+      // 返回 Uint8Array 信封；routes 接线后以 octet-stream + x-edrv-* 头直出，
+      // 未接线时信封被 JSON 化，由 client 探测到后自动回退 base64 路径（见 shared/rpc readBinaryPreview）。
+      const sc = await requireSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false, error: sc.err }
+      const prep = await readTargetOf(ctx, sc, args.path)
+      if ('err' in prep) return targetErrOf(prep)
+      try {
+        const bytes = await prep.fs.readBytes(prep.target, undefined, BINARY_READ_CAP)
+        return {
+          ok: true,
+          binary: { bytes, mime: binaryMimeOf(args.path), size: bytes.byteLength, version: String(prep.info.version ?? '') },
         }
-        if ((info.size ?? 0) > READ_CAP) return { ok: false, error: '文件过大（>8MB），不支持整文件预览' }
-        const content = await fs.readText(target)
-        return { ok: true, content, size: content.length, version: String(info.version ?? '') }
       } catch (error) {
         return { ok: false, error: '读取失败：' + String(error) }
       }
@@ -847,22 +907,20 @@ export function buildHandlers(
     },
     'vscode.fileOpenSettingsGet': async () => {
       const settings = ctx.get('settings')
-      const descriptor = settings?.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === FILE_OPEN_SETTINGS_NS)
-      const value = descriptor?.value as { fileOpenTool?: unknown } | undefined
-      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? FILE_OPEN_DEFAULT), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: descriptor?.revision }
+      const section = sectionOf(settings, FILE_OPEN_SETTINGS_NS)
+      const value = section?.value as { fileOpenTool?: unknown } | undefined
+      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? FILE_OPEN_DEFAULT), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: section?.revision }
     },
     'vscode.fileOpenSettingsUpdate': async (args) => {
       const settings = ctx.get('settings')
-      if (!settings?.update) return { ok: false, error: '设置服务不可用' }
-      try {
-        const patch: Record<string, unknown> = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) }
-        if (typeof args.integrationBaseUrl === 'string' && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim()
-        await settings.update(FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision)
-        const descriptor = settings.describe?.({ redactSecrets: true })?.find((item: { ns?: string }) => item.ns === FILE_OPEN_SETTINGS_NS)
-        const value = descriptor?.value as { fileOpenTool?: unknown } | undefined
-        return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: descriptor?.revision }
-      } catch (error) { return { ok: false, error: String(error) }
-      }
+      const patch: Record<string, unknown> = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) }
+      if (typeof args.integrationBaseUrl === 'string' && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim()
+      // 冲突自愈（0.1.7 SettingsConflictError 重读重试一次）与形状校验读取统一走 fileOpenSettings 工具
+      const result = await updateSection(settings, FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision)
+      if (!result.ok) return { ok: false, error: result.error ?? '设置服务不可用' }
+      const section = sectionOf(settings, FILE_OPEN_SETTINGS_NS)
+      const value = section?.value as { fileOpenTool?: unknown } | undefined
+      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: section?.revision }
     },
     'compat': async () => ({ ok: true, report: await buildReport(ctx) }),
     'vscode.devFormGet': async () => ({ ok: true, devForm: readDevForm() }),
@@ -953,6 +1011,7 @@ export function buildHandlers(
         const inventory = await scanSessionInventory(home, sessionsArchiveRoot(home))
         const active = activeSessionIds(ctx)
         markActiveSessions(inventory.sessions, active)
+        markOfficialFlags(inventory.sessions, ctx)
         return { ok: true, ...inventory, activeIds: [...active] }
       } catch (error) {
         return { ok: false, error: '盘点失败：' + String(error) }
@@ -990,7 +1049,10 @@ export function buildHandlers(
     'edrv.perf.restore': async (args) => {
       try {
         const result = await restoreSession(dshHome(), sessionsArchiveRoot(dshHome()), args.workspaceKey, args.sessionId)
-        return result.ok ? { ok: true, restored: true } : { ok: false, error: result.error ?? '恢复失败' }
+        if (!result.ok) return { ok: false, error: result.error ?? '恢复失败' }
+        // 目录搬回后对齐官方归档标志（best-effort：服务缺失/调用失败不影响恢复结果，见 perf.unarchiveOfficial）
+        await unarchiveOfficial(ctx, args.sessionId)
+        return { ok: true, restored: true }
       } catch (error) {
         return { ok: false, error: '恢复失败：' + String(error) }
       }