dsh-vscode-mode 0.4.2 → 0.4.4

package/src/client/ui/useFileWatch.ts

@@ -0,0 +1,214 @@
+/**
+ * dsh-vscode-mode client — 已打开文件的外部改动轮询。
+ *
+ * 背景：RPC 只有客户端拉取通道（无服务端推送），编辑区因此无法感知外部写盘。
+ * 本 hook 以轻量接口补上感知：每 POLL_MS 一次把「全部已打开页签路径」批量交给
+ * host edrv.versions（单请求多条 stat），逐条与本地基线比对后按 watchDecision 的
+ * 判定表把动作回调给 EditorView 执行（IO 与 UI 都在那里）。
+ *
+ * 为何「版本变了还要读内容」：host 版本令牌含 ctime，同字节重写（格式化工具/同步盘/
+ * 编辑器保存策略）也会让它变化，只看版本会把无实质变化的文件反复重载（打断光标与
+ * 滚动）。故版本变化时读一次磁盘内容与缓冲比对，相同则只推进基线；读取结果按版本
+ * 记入 readVersions，同一版本只读一次（陈旧缓冲长期不处理也不会反复拉大文件）。
+ *
+ * 取舍：不使用 fs.watch（句柄/网络盘/长路径兼容性差），纯 stat+按需读轮询跨平台稳定
+ * 且可单测；1.5s 周期对「外部改文件 → 编辑区可见」足够及时，标签页隐藏时整轮跳过。
+ *
+ * 上报规则（避免每轮都弹提示）：
+ * - 首次观测某路径（无标记）：报 conflict/deleted，并落标记；
+ * - 已有标记且仍异常：不再重复回调（提示已在屏上），版本恢复一致时自动清标记；
+ * - 站点不可达（老 host 无此方法/离线）：整轮静默放弃，不清标记、不放大重试。
+ *
+ * 作者 ddj 2026-09-15
+ */
+import * as React from 'react'
+import { rpc } from '../rpc.js'
+import type { FileVersionItem } from '../../shared/rpc.js'
+import {
+  baselineOf,
+  clearReadVersion,
+  clearSync,
+  markReadVersion,
+  markSync,
+  readSync,
+  readVersionOf,
+  recordBaseline,
+  syncDecision,
+  versionOf,
+} from '../watchDecision.js'
+
+/** 轮询周期：外部改动可见延迟上限（标签页隐藏时跳过整轮）。 */
+export const POLL_MS = 1500
+
+/** 同步判定结果（hook 只说「发生了什么」，怎么处理由调用方决定）。 */
+export interface DiskChange {
+  path: string
+  kind: 'modified' | 'conflict' | 'deleted'
+}
+
+/** 读盘结果（供内容比对）。 */
+export interface DiskContent {
+  /** 磁盘内容是否与调用方缓冲内容相同。 */
+  equal: boolean
+}
+
+/** 一轮判定的上下文（ref 与回调打包，避免 evaluate 参数过长；导出供测试构造）。 */
+export interface PollContext {
+  sessionId: string
+  scope: string
+  dirtyRef: React.MutableRefObject<Record<string, boolean>>
+  onReadDisk?: (path: string) => Promise<DiskContent | null>
+  onChange: (change: DiskChange) => void
+}
+
+/** hook 选项（ref 传入最新值，避免把轮询循环写进 React 依赖数组）。 */
+export interface FileWatchOptions {
+  /** 会话 id（缺失时不轮询）。 */
+  sessionId?: string | null
+  /** 工作区作用域键（基线/台账按它隔离）。 */
+  scope: string
+  /** 当前全部页签路径（读 ref 取最新值）。 */
+  tabsRef: React.MutableRefObject<string[]>
+  /** 脏标记表（path → 是否待保存）。 */
+  dirtyRef: React.MutableRefObject<Record<string, boolean>>
+  /**
+   * 版本变化时读磁盘内容（与调用方缓冲内容比对用）；
+   * 未实现/失败返回 null → 干净缓冲按「需要重载」处理，脏缓冲按冲突处理。
+   */
+  onReadDisk?: (path: string) => Promise<DiskContent | null>
+  /** 同步动作回调（EditorView 负责重载、提示、刷新差异标记）。 */
+  onDiskChange: (change: DiskChange) => void
+}
+
+/**
+ * 装配外部改动轮询（挂载即开始，卸载/换会话即停）。
+ * @author ddj 2026年09月15号
+ * @param options 会话/作用域/ref 与回调
+ */
+export function useFileWatch(options: FileWatchOptions): void {
+  const { sessionId, scope, tabsRef, dirtyRef, onReadDisk, onDiskChange } = options
+  const cbRef = React.useRef(onDiskChange)
+  cbRef.current = onDiskChange
+  const readRef = React.useRef(onReadDisk)
+  readRef.current = onReadDisk
+  /** 在途守卫：上一轮未返回（host 卡住）时跳过本轮，避免请求堆积。 */
+  const busyRef = React.useRef(false)
+
+  React.useEffect(() => {
+    if (!sessionId) return
+    const context: PollContext = {
+      sessionId,
+      scope,
+      dirtyRef,
+      onReadDisk: (path) => (readRef.current ? readRef.current(path) : Promise.resolve(null)),
+      onChange: (change) => cbRef.current(change),
+    }
+    /**
+     * 一轮观测：批量取版本 → 逐条判定 → 回调。
+     * @author ddj 2026年09月15号
+     */
+    const poll = async (): Promise<void> => {
+      if (busyRef.current) return
+      if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return
+      const paths = (tabsRef.current ?? []).filter((p) => typeof p === 'string' && p)
+      if (!paths.length) return
+      busyRef.current = true
+      try {
+        const res = await rpc('edrv.versions', { sessionId, paths })
+        if (!res || !res.ok || !Array.isArray(res.items)) return
+        for (const item of res.items) {
+          if (!item || !item.path) continue
+          await evaluate(item, context)
+        }
+      } catch (error) {
+        // 老 host 无此方法 / 离线：静默停摆这一轮，不清任何标记
+      } finally {
+        busyRef.current = false
+      }
+    }
+    const timer = window.setInterval(() => { void poll() }, POLL_MS)
+    void poll()
+    return () => window.clearInterval(timer)
+  }, [sessionId, scope])
+}
+
+/**
+ * 单条判定：按 watchDecision 的判定表决定动作，必要时清/落台账标记。
+ * 版本变化时先读磁盘内容（同版本只读一次）再定分支：内容相同只推进基线，
+ * 内容不同且缓冲脏才升级为冲突提示。
+ *
+ * 导出原因：这是「观测 → 动作派发」的关键落点（三条分支各自的副作用不轻），
+ * 用假 fetch + 假 context 可直接驱动它做端到端断言，无需渲染 React 树。
+ * 仅供测试与同模块内 poll 调用，不属于对外 API。
+ * @author ddj 2026年09月15号
+ * @param item host 版本条目
+ * @param context 轮询上下文（作用域/脏标记/读盘/回调）
+ */
+export async function evaluate(item: FileVersionItem, context: PollContext): Promise<void> {
+  const path = item.path
+  const scope = context.scope
+  const baseline = baselineOf(scope, path)
+  const version = versionOf(item)
+  const missing = item.type === 'missing'
+  const dirty = context.dirtyRef.current?.[path] === true
+  // 无基线但拿到版本：补记基线（首次观测不报变化，避免开页即弹提示）
+  if (!baseline) {
+    recordBaseline(scope, path, version)
+    return
+  }
+  const versionChanged = version !== baseline
+  if (!versionChanged && !missing) {
+    clearSync(scope, path) // 版本恢复一致：清掉历史标记（含误报自愈）
+    return
+  }
+  // 版本变了但内容一致（同字节重写：格式化工具/同步盘/编辑器保存策略）：
+  // 只推进基线，绝不通知调用方重载——那会白刷一次并打断光标与滚动。
+  const mode = await inspect(path, version, context)
+  if (mode.known && mode.equal) {
+    recordBaseline(scope, path, version)
+    markReadVersion(scope, path, version, true)
+    clearSync(scope, path)
+    return
+  }
+  const action = syncDecision({ hasBaseline: true, versionChanged, missing, clean: !dirty, contentEqual: mode.equal })
+  if (action === 'sync-silent') {
+    clearSync(scope, path)
+    if (mode.known) {
+      recordBaseline(scope, path, version) // 内容不同：先推进基线，随后由调用方重载
+      markReadVersion(scope, path, version, false)
+    } else {
+      clearReadVersion(scope, path) // 读失败：交重载重新读盘（并重试比对）
+    }
+    context.onChange({ path, kind: 'modified' })
+    return
+  }
+  if (action === 'none') return
+  const kind = action === 'deleted' ? 'deleted' : 'conflict'
+  const flagged = readSync(scope, path)
+  if (flagged && flagged.kind === kind) return
+  markSync(scope, path, kind)
+  context.onChange({ path, kind })
+}
+
+/**
+ * 读盘并与调用方缓冲比对（脏缓冲也需要：内容相同就不该报冲突）。
+ * 同版本只读一次：已读过该版本的路径直接回放当时的比对结果（不重复拉取大文件）。
+ * @author ddj 2026年09月15号
+ * @param path 文件路径
+ * @param version 当前磁盘版本（可为 null）
+ * @param context 轮询上下文
+ * @returns { known: 是否拿到磁盘内容, equal: 内容是否与缓冲一致 }
+ */
+async function inspect(
+  path: string,
+  version: string | null,
+  context: PollContext,
+): Promise<{ known: boolean; equal: boolean }> {
+  if (!version) return { known: false, equal: false }
+  const cached = readVersionOf(context.scope, path, version)
+  if (cached) return { known: true, equal: cached.equal }
+  const disk = await context.onReadDisk?.(path).catch(() => null)
+  if (!disk) return { known: false, equal: false }
+  markReadVersion(context.scope, path, version, disk.equal)
+  return { known: true, equal: disk.equal }
+}

package/src/client/watchDecision.ts

@@ -0,0 +1,274 @@
+/**
+ * dsh-vscode-mode client — 外部磁盘改动的同步决策（纯逻辑，可单测）。
+ *
+ * 存在意义：编辑区内容只在打开/手动刷新时从磁盘读取，外部（其他编辑器、Unity、
+ * 脚本、agent 工具）改了文件后缓冲与文件树长期陈旧，且陈旧缓冲的防抖自动保存会
+ * 直接覆盖外部改动。本模块只承载判定与基线台账，IO 与 UI 由 useFileWatch /
+ * EditorView 承担：
+ * - 基线（baseline）：每个已打开路径记录「最后一次从磁盘读到的版本令牌」，
+ *   版本令牌来自 host fs.stat（不透明串），客户端只做相等比较。
+ * - 台账（syncState）：判定为需要用户介入（冲突/消失）的路径，供状态栏提示
+ *   与「抑制自动保存」读取；冲突被处理或自愈后清除。
+ *
+ * 判定表（syncDecision）：
+ *   无基线              → none（首次打开或未带版本，由调用方补记基线）
+ *   文件缺失 + 缓冲干净  → deleted
+ *   文件缺失 + 缓冲脏    → none（保留未保存编辑，交由保存失败路径提示）
+ *   版本未变            → none
+ *   版本变 + 缓冲干净    → sync-silent（先比内容：相同只补基线，不同才重载）
+ *   版本变 + 缓冲脏 + 内容相同 → sync-silent（仅补记基线，不打断编辑）
+ *   版本变 + 缓冲脏 + 内容不同 → conflict（绝不覆盖）
+ *
+ * 重要事实（实测，勿改回「只看版本」）：host 版本令牌 = host fs 的 stat 身份串，
+ * 本地后端实现为 `dev:ino:size:mtimeNs:ctimeNs`，其中 ctime 在「同字节重写」时
+ * 也会变（格式化工具/同步盘/编辑器保存策略常见）。因此版本变化只代表「动过」，
+ * 是否真的需要重载必须由磁盘内容与缓冲内容的比对决定；读取结果按版本号缓存
+ * （readVersion），同一版本只读一次，避免陈旧缓冲长期不处理时反复拉取大文件。
+ *
+ * 作者 ddj 2026-09-15
+ */
+import type { FileVersionItem } from '../shared/rpc.js'
+
+// --region 类型
+
+/** 一次同步判定的输入（全部为已观测事实，不含 IO）。 */
+export interface SyncInput {
+  /** 是否已有磁盘版本基线。 */
+  hasBaseline: boolean
+  /** 磁盘版本令牌是否与基线不同（无基线时为 false）。 */
+  versionChanged: boolean
+  /** 磁盘上是否已不存在该路径。 */
+  missing: boolean
+  /** 缓冲是否已置脏（有待保存的编辑）。 */
+  clean: boolean
+  /** 缓冲内容是否与磁盘内容相同（仅冲突分支需要，未取到磁盘内容时传 false）。 */
+  contentEqual: boolean
+}
+
+/** 同步判定结果。 */
+export type SyncAction = 'sync-silent' | 'conflict' | 'deleted' | 'none'
+
+/** 需要用户介入的台账项（状态栏提示与自动保存抑制共用）。 */
+export interface SyncFlag {
+  path: string
+  kind: 'conflict' | 'deleted'
+  at: number
+}
+
+// --endregion
+
+// --region 常量与状态
+
+/** 台账上限：超出按写入序逐出最旧（防长时间运行无界增长）。 */
+export const SYNC_STATE_CAP = 64
+/** 单作用域基线上限：超出按写入序逐出最旧（已关闭页签的基线可丢）。 */
+export const BASELINE_CAP = 128
+
+/** 作用域键 → 路径 → 磁盘版本令牌。 */
+const baselines = new Map<string, Map<string, string>>()
+/** 作用域键 → 路径 → 已读取过内容的磁盘版本（同版本不重复读盘；含当时的比对结果）。 */
+const readVersions = new Map<string, Map<string, { version: string; equal: boolean }>>()
+/** 作用域键 → 路径 → 待处理同步标记。 */
+const syncState = new Map<string, Map<string, SyncFlag>>()
+
+// --endregion
+
+// --region 纯函数
+
+/**
+ * 台账键：作用域 + 归一化路径（`/` 分隔，大小写敏感语义与 host 一致）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径（工作区相对或绝对）
+ * @returns 台账键
+ */
+export function syncKey(scope: string, path: string): string {
+  return String(scope ?? '') + '\u0000' + String(path ?? '').replace(/\\/g, '/')
+}
+
+/**
+ * 判定一次观测的同步动作（纯函数，判定表见模块头注释）。
+ * @author ddj 2026年09月15号
+ * @param input 观测输入（基线有无/版本是否变化/是否缺失/缓冲是否脏/内容是否相同）
+ * @returns 同步动作
+ */
+export function syncDecision(input: SyncInput): SyncAction {
+  if (!input.hasBaseline) return 'none'
+  if (input.missing) return input.clean ? 'deleted' : 'none'
+  if (!input.versionChanged) return 'none'
+  if (input.clean) return 'sync-silent'
+  return input.contentEqual ? 'sync-silent' : 'conflict'
+}
+
+/**
+ * 从 host 版本条目取可比较的版本令牌（缺失/空串 → null，表示该后端不提供版本）。
+ * @author ddj 2026年09月15号
+ * @param item 版本条目（可为 undefined）
+ * @returns 版本令牌或 null
+ */
+export function versionOf(item: FileVersionItem | undefined | null): string | null {
+  const version = item?.version
+  return typeof version === 'string' && version ? version : null
+}
+
+// --endregion
+
+// --region 基线台账
+
+/**
+ * 记入（或更新）某路径的磁盘版本基线；版本为空串时不记（后端不支持版本）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ * @param version 磁盘版本令牌
+ */
+export function recordBaseline(scope: string, path: string, version: string | undefined | null): void {
+  if (!path || typeof version !== 'string' || !version) return
+  let map = baselines.get(scope)
+  if (!map) {
+    map = new Map()
+    baselines.set(scope, map)
+  }
+  const key = String(path).replace(/\\/g, '/')
+  map.delete(key)
+  map.set(key, version)
+  while (map.size > BASELINE_CAP) {
+    const oldest = map.keys().next().value
+    if (oldest === undefined) break
+    map.delete(oldest)
+  }
+}
+
+/**
+ * 读取某路径的磁盘版本基线。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ * @returns 版本令牌；无基线 → null
+ */
+export function baselineOf(scope: string, path: string): string | null {
+  return baselines.get(scope)?.get(String(path).replace(/\\/g, '/')) ?? null
+}
+
+/**
+ * 清除某路径的基线（页签关闭、会话销毁时调用）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ */
+export function clearBaseline(scope: string, path: string): void {
+  baselines.get(scope)?.delete(String(path).replace(/\\/g, '/'))
+}
+
+/**
+ * 记入「已读取过内容的磁盘版本」与比结果（同版本不再重复读盘）。
+ * 读盘成功、保存成功、覆盖成功、保留本地推进基线时都要记，避免下一轮白读一次。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ * @param version 版本令牌（空值忽略）
+ * @param equal 读到的磁盘内容是否与当时的缓冲内容相同
+ */
+export function markReadVersion(scope: string, path: string, version: string | undefined | null, equal = false): void {
+  if (!path || typeof version !== 'string' || !version) return
+  let map = readVersions.get(scope)
+  if (!map) {
+    map = new Map()
+    readVersions.set(scope, map)
+  }
+  const key = String(path).replace(/\\/g, '/')
+  map.delete(key)
+  map.set(key, { version, equal: equal === true })
+  while (map.size > BASELINE_CAP) {
+    const oldest = map.keys().next().value
+    if (oldest === undefined) break
+    map.delete(oldest)
+  }
+}
+
+/**
+ * 该磁盘版本是否已读过内容；是则同时给出当时的比对结果（轮询跳过读盘）。
+ * 必须按版本号严格匹配：缓存里可能是更早版本的结果，版本不同一律视为未读。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ * @param version 当前磁盘版本令牌
+ * @returns 未读过该版本 → null；读过 → { equal: 内容是否与缓冲一致 }
+ */
+export function readVersionOf(scope: string, path: string, version: string | null): { equal: boolean } | null {
+  if (!version) return null
+  const memo = readVersions.get(scope)?.get(String(path).replace(/\\/g, '/'))
+  if (!memo || memo.version !== version) return null
+  return { equal: memo.equal }
+}
+
+/**
+ * 清除某路径的已读版本（重载后必须清：下一轮需按新版本重新读盘比对）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ */
+export function clearReadVersion(scope: string, path: string): void {
+  readVersions.get(scope)?.delete(String(path).replace(/\\/g, '/'))
+}
+
+/**
+ * 清空某作用域的全部基线（作用域切换时调用，防旧工作区基线串到新工作区）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ */
+export function clearScope(scope: string): void {
+  baselines.delete(scope)
+  readVersions.delete(scope)
+  syncState.delete(scope)
+}
+
+// --endregion
+
+// --region 同步标记
+
+/**
+ * 标记某路径需要用户介入（冲突/文件消失）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ * @param kind 标记类型
+ */
+export function markSync(scope: string, path: string, kind: SyncFlag['kind']): void {
+  let map = syncState.get(scope)
+  if (!map) {
+    map = new Map()
+    syncState.set(scope, map)
+  }
+  const key = String(path).replace(/\\/g, '/')
+  map.delete(key)
+  map.set(key, { path, kind, at: Date.now() })
+  while (map.size > SYNC_STATE_CAP) {
+    const oldest = map.keys().next().value
+    if (oldest === undefined) break
+    map.delete(oldest)
+  }
+}
+
+/**
+ * 读取某路径的待处理同步标记。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ * @returns 标记；无 → null
+ */
+export function readSync(scope: string, path: string): SyncFlag | null {
+  return syncState.get(scope)?.get(String(path).replace(/\\/g, '/')) ?? null
+}
+
+/**
+ * 清除某路径的同步标记（重新加载/保留本地/保存成功后调用）。
+ * @author ddj 2026年09月15号
+ * @param scope 工作区作用域键
+ * @param path 文件路径
+ */
+export function clearSync(scope: string, path: string): void {
+  syncState.get(scope)?.delete(String(path).replace(/\\/g, '/'))
+}
+
+// --endregion

package/src/compat.ts

@@ -133,7 +133,7 @@ export function detectGuards(ctx: Ctx): CompatAdapter[] {
 }
 
 /** 已实测覆盖的最高 DSH 版本（适配矩阵上界，超过则提示，见 buildReport）。 */
-const TESTED_DSH_MAX = '0.1.3-alpha.2'
+const TESTED_DSH_MAX = '0.1.6-alpha.1'
 
 /** 版本适配机制状态行：DSH 版本探测 + 设置 section 安装策略。 */
 export function versionAdapters(dshVersion: string): CompatAdapter[] {

package/src/dshVersion.ts

@@ -86,6 +86,8 @@ export function inDshRange(version: DshVersion | null | undefined, range: DshRan
 export function familyLabel(input: string): string {
   const version = parseDshVersion(input)
   if (!version) return '未知'
+  if (inDshRange(version, { from: '0.1.6-alpha.1' })) return '0.1.6-alpha 及更新（MCP SDK v2 + Web 侧边栏终端 + 文件链接默认侧栏预览）'
+  if (inDshRange(version, { from: '0.1.5-alpha.1' })) return '0.1.5-alpha 及更新（官方右侧 Sidebar 编辑区 + sidebar.panellist）'
   if (inDshRange(version, { from: '0.1.3-alpha.1' })) return '0.1.3-alpha 及更新（对话文件链接=remote.session.openWorkspacePath）'
   if (inDshRange(version, { from: '0.1.2-alpha.1' })) return '0.1.2-alpha 及更新（设置 API=settings.installSection）'
   return '0.1.0/0.1.1 rc 线（设置 API=installSettingsSection）'
@@ -101,21 +103,51 @@ const VERSION_CANDIDATES = [
 
 let detectedVersion: string | undefined
 
+/**
+ * 宿主入口 require 锚点：process.argv[1] 指向运行中 DSH 的启动脚本
+ * （安装树 node_modules/@deepseek-ai/dsh/... 或 profile 树），从其所在目录
+ * 向上解析能命中宿主的 @deepseek-ai 包——避开本插件自身 node_modules 里的
+ * dev 依赖副本（dev-link 安装下 import.meta.url 锚点会先命中 rc 线副本，
+ * 曾致版本探测与 deps 加载错位到 0.1.0-rc.8，见 fileOpenSettings 的 hostImport）。
+ * @author ddj 2026年09月15号
+ * @returns 宿主锚点 require；argv[1] 缺失或不可用时 undefined
+ */
+function hostRequire(): NodeRequire | undefined {
+  const entry = process.argv[1]
+  if (!entry) return undefined
+  try {
+    return createRequire(entry)
+  } catch {
+    return undefined
+  }
+}
+
+/** 用指定 resolver 解析一个候选包版本（解析/读取失败返回 null）。 */
+function resolveVersionOf(specifier: string, resolver: NodeRequire): string | null {
+  try {
+    const file = resolver.resolve(specifier)
+    const pkg = JSON.parse(readFileSync(file, 'utf8')) as { version?: unknown }
+    if (typeof pkg.version === 'string' && parseDshVersion(pkg.version) !== null) return pkg.version
+  } catch {
+    /* exports 未放行或包缺失：尝试下一个候选 */
+  }
+  return null
+}
+
 /** 探测运行中 DSH 核心版本（模块级缓存；失败空串，不抛错）。 */
 export function detectDshVersion(): string {
   if (detectedVersion !== undefined) return detectedVersion
   detectedVersion = ''
-  const require = createRequire(import.meta.url)
-  for (const specifier of VERSION_CANDIDATES) {
-    try {
-      const file = require.resolve(specifier)
-      const pkg = JSON.parse(readFileSync(file, 'utf8')) as { version?: unknown }
-      if (typeof pkg.version === 'string' && parseDshVersion(pkg.version) !== null) {
-        detectedVersion = pkg.version
-        break
+  // 宿主锚点优先（运行中 DSH 的 @deepseek-ai 树），失败回退本插件位置（测试/独立运行）。
+  const resolvers: Array<NodeRequire | undefined> = [hostRequire(), createRequire(import.meta.url)]
+  for (const resolver of resolvers) {
+    if (!resolver) continue
+    for (const specifier of VERSION_CANDIDATES) {
+      const version = resolveVersionOf(specifier, resolver)
+      if (version !== null) {
+        detectedVersion = version
+        return detectedVersion
       }
-    } catch {
-      /* exports 未放行或包缺失：尝试下一个候选 */
     }
   }
   return detectedVersion

package/src/fileOpenSettings.ts

@@ -7,6 +7,8 @@
  * 全程 try/catch，不产生未捕获 rejection。
  * 作者 ddj 2026年08月24号 / 2026年08月26号 / 2026年09月02号
  */
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
 import type { Ctx } from './store.js'
 import { KEYBINDING_DEFAULTS } from './shared/keybindings.js'
 import { INTEGRATION_BASE_DEFAULT } from './shared/integration.js'
@@ -47,16 +49,38 @@ export type SettingsDepsLoader = () => Promise<SettingsDeps | null>
 
 let depsPromise: Promise<SettingsDeps | null> | undefined
 
+/**
+ * 宿主锚点动态导入：先经 process.argv[1]（DSH 启动脚本所在树）解析并加载目标包，
+ * 避开本插件自身 node_modules 的 dev 依赖副本（dev-link 下 import() 相对插件位置
+ * 解析，会命中 rc 线旧包 dsh-settings@0.1.0-rc.8）；argv[1] 缺失或解析失败回退
+ * 普通 specifier import。
+ * @author ddj 2026年09月15号
+ * @param specifier 包名
+ * @returns 加载的模块命名空间
+ */
+async function hostImport(specifier: string): Promise<unknown> {
+  const entry = process.argv[1]
+  if (entry) {
+    try {
+      const resolved = createRequire(entry).resolve(specifier)
+      return await import(pathToFileURL(resolved).href)
+    } catch {
+      /* 锚点不可用：回退普通 import */
+    }
+  }
+  return import(specifier)
+}
+
 /**
  * 动态加载设置依赖（模块级缓存；任一缺失/失败返回 null 而非抛错）。
  * installSettingsSection 仅在 rc 线 dsh-settings 中存在时提供（alpha 起移除，
  * 属性探测得到 undefined，不抛错）。
- * @author ddj 2026年08月24号
+ * @author ddj 2026年08月24号 / 2026年09月15号
  * @returns 设置依赖或 null
  */
 export function loadSettingsDeps(): Promise<SettingsDeps | null> {
   if (!depsPromise) {
-    depsPromise = Promise.all([import('@deepseek-ai/dsh-settings'), import('schemastery')])
+    depsPromise = Promise.all([hostImport('@deepseek-ai/dsh-settings'), hostImport('schemastery')])
       .then(([dshSettings, schemastery]) => ({
         // dsh-settings 类型声明随版本变化（rc.8 有 d.ts、alpha 已移除导出），统一经 unknown 松绑
         installSettingsSection: (dshSettings as unknown as { installSettingsSection?: SettingsDeps['installSettingsSection'] }).installSettingsSection,