dsh-vscode-mode 0.11.0 → 0.13.0

package/src/client/useOpenReceipt.ts

@@ -0,0 +1,128 @@
+/** Correlated editor readiness for external file opens. @author ddj 2026年09月28号 */
+import React from 'react'
+import { finishOpen, hasOpen, peekOpen } from './openReceipt.js'
+import type { EditorRequest } from './openReceipt.js'
+
+export interface ReceiptHost {
+  sessionId: string
+  open(request: EditorRequest): void | Promise<void>
+  ready(request: EditorRequest): boolean
+  error(request: EditorRequest): string | null
+}
+
+/** One mounted editor owns at most one claimed external request. */
+export class OpenMonitor {
+  private pending: EditorRequest | undefined
+  private frame: number | undefined
+  private stopped = false
+  private opening = false
+  /** @private @author ddj 2026年09月28号 Claim a request arriving after mount. */
+  private listener = (): void => { this.claim() }
+
+  /** @author ddj 2026年09月28号 @param read Read current component state without a stale closure. */
+  constructor(private readonly read: () => ReceiptHost) {}
+
+  /** @public @author ddj 2026年09月28号 Attach the listener and claim a pre-mount request. */
+  start(): void {
+    window.addEventListener('edrv:open-request', this.listener)
+    this.claim()
+  }
+
+  /** @public @author ddj 2026年09月28号 Fail claimed work and cancel the frame on unmount. */
+  stop(): void {
+    this.stopped = true
+    window.removeEventListener('edrv:open-request', this.listener)
+    if (this.frame !== undefined) cancelAnimationFrame(this.frame)
+    this.frame = undefined
+    if (this.pending) finishOpen(this.pending.requestId, false, '编辑器已关闭')
+    this.pending = undefined
+  }
+
+  /** @private @author ddj 2026年09月28号 Schedule at most one readiness/queue check. */
+  private arm(): void {
+    if (!this.stopped && this.frame === undefined) this.frame = requestAnimationFrame(this.check)
+  }
+
+  /**
+   * Settle only the request this instance still owns; queued work runs next frame.
+   * @private @author ddj 2026年09月28号
+   * @param request Claimed request, captured before asynchronous work.
+   * @param success Whether actual readiness was confirmed.
+   * @param error Failure description.
+   */
+  private finish(request: EditorRequest, success: boolean, error?: string): void {
+    if (this.stopped || this.pending !== request) return
+    this.pending = undefined
+    this.opening = false
+    if (hasOpen(request.requestId)) finishOpen(request.requestId, success, error)
+    this.arm()
+  }
+
+  /**
+   * Observe startup without letting a late completion affect a new claim.
+   * @private @author ddj 2026年09月28号
+   * @param request Startup's request identity.
+   * @param operation Optional asynchronous editor startup.
+   */
+  private watchOpen(request: EditorRequest, operation: void | Promise<void>): void {
+    if (!operation) return
+    this.opening = true
+    /** @author ddj 2026年09月28号 Release readiness only for this live claim. */
+    const ready = (): void => {
+      if (!this.stopped && this.pending === request) this.opening = false
+    }
+    /** @author ddj 2026年09月28号 @param error Correlated startup rejection. */
+    const fail = (error: unknown): void => this.finish(request, false, String(error))
+    void Promise.resolve(operation).then(ready, fail)
+  }
+
+  /** @private @author ddj 2026年09月28号 Claim this session; exceptions fail the exact request. */
+  private claim(): void {
+    if (this.stopped || (this.pending && hasOpen(this.pending.requestId))) return
+    this.pending = undefined
+    this.opening = false
+    try {
+      const host = this.read()
+      const request = peekOpen(host.sessionId)
+      if (!request) return
+      this.pending = request
+      this.watchOpen(request, host.open(request))
+      this.arm()
+    } catch (error) {
+      if (this.pending) this.finish(this.pending, false, String(error))
+    }
+  }
+
+  /** @private @author ddj 2026年09月28号 Check readiness; expired claims and exceptions cannot ACK later work. */
+  private check = (): void => {
+    this.frame = undefined
+    if (this.stopped) return
+    const request = this.pending
+    if (!request || !hasOpen(request.requestId)) { this.pending = undefined; this.claim(); return }
+    try {
+      const host = this.read()
+      if (request.sessionId !== host.sessionId) { this.finish(request, false, '会话已切换'); return }
+      if (this.opening) { this.arm(); return }
+      const error = host.error(request)
+      if (error || host.ready(request)) { this.finish(request, !error, error ?? undefined); return }
+      this.arm()
+    } catch (error) { this.finish(request, false, String(error)) }
+  }
+}
+
+/**
+ * Bind a component while reading its latest model state.
+ * @author ddj 2026年09月28号
+ * @param host Mounted editor actions and readiness checks.
+ */
+export function useOpenReceipt(host: ReceiptHost): void {
+  const latest = React.useRef(host)
+  latest.current = host
+  /** @author ddj 2026年09月28号 @returns Listener and animation-frame cleanup. */
+  function mount(): () => void {
+    const monitor = new OpenMonitor(() => latest.current)
+    monitor.start()
+    return () => monitor.stop()
+  }
+  React.useEffect(mount, [host.sessionId])
+}

package/src/compat.ts

@@ -132,8 +132,10 @@ export function detectGuards(ctx: Ctx): CompatAdapter[] {
   ]
 }
 
-/** 已实测覆盖的最高 DSH 版本（适配矩阵上界，超过则提示，见 buildReport）。 */
-const TESTED_DSH_MAX = '0.1.7-alpha.2'
+/** 已实测覆盖的最高 DSH 版本（适配矩阵上界，超过则提示，见 buildReport）。
+ * 0.1.7-rc.2 已在官方已签名打包 Desktop 上实机装配（认证路由、同源 RPC、项目 MCP
+ * 与私有打开队列均生效）；更高版本仍按能力探测运行并提示。 */
+const TESTED_DSH_MAX = '0.1.7-rc.2'
 
 /** Config volatile 标记起效的版本线（此前设置走 section 安装，与 volatile 无关）。 */
 const CONFIG_VOLATILE_MIN = '0.1.7-alpha.1'
@@ -210,7 +212,7 @@ export async function buildReport(
     guards,
     adapters,
     warnings,
-    devForm: readDevForm(),
+    devForm: readDevForm(ctx),
     dshVersion,
   }
 }

package/src/dap/manager.ts

@@ -18,6 +18,8 @@
  * 作者 ddj 2026年09月29号 / 2026年09月21号
  */
 import { spawn, type ChildProcess } from 'node:child_process'
+import { childEnv } from '../childEnv.js'
+import { stopTree } from '../processTree.js'
 import { join } from 'node:path'
 import { createFrameParser, encodeMessage } from '../lsp/jsonrpc.js'
 import { sourceBaseOf, sourceKeyOf, sourcePathOf, normalizeSourcePath } from './sourcePath.js'
@@ -288,9 +290,18 @@ export class DapSession {
 
   // ---------------------------------------------------------------- 内部实现
 
-  /** spawn 适配器进程并接好帧解析。 */
+  /**
+   * 启动独立适配器进程组并接入协议，清理隐式宿主凭据。
+   * @private
+   * @author ddj 2026年09月28号
+   * @param spec 适配器规格
+   * @throws spawn 同步失败
+   */
   private spawnAdapter(spec: DapAdapterSpec): void {
-    const child = spawn(spec.command, spec.args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+    const child = spawn(spec.command, spec.args, {
+      stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
+      detached: process.platform !== 'win32', env: this.adapterEnv(),
+    })
     this.child = child
     const parser = createFrameParser()
     child.stdout?.on('data', (chunk: Buffer) => {
@@ -300,11 +311,16 @@ export class DapSession {
       log.debug('[dap-adapter] ' + chunk.toString('utf8').trim())
       this.stderrTail = (this.stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL_CAP)
     })
-    child.on('error', (error) => this.fail('适配器进程错误：' + String(error)))
+    child.on('error', (error) => {
+      if (this.child === child) this.fail('适配器进程错误：' + String(error))
+    })
+    child.stdin?.on('error', (error) => {
+      if (this.child === child) this.fail('适配器 stdin 错误：' + String(error))
+    })
     child.on('exit', (code) => {
-      if (this.child === child && this.phase !== 'idle' && this.phase !== 'terminated') {
-        this.fail('适配器退出（code=' + code + '）' + this.stderrSuffix())
-      }
+      if (this.child !== child) return
+      if (this.phase === 'idle' || this.phase === 'terminated') this.killChild()
+      else this.fail('适配器退出（code=' + code + '）' + this.stderrSuffix())
     })
   }
 
@@ -529,18 +545,35 @@ export class DapSession {
     this.setPhase('terminated')
   }
 
-  /** 杀适配器进程树（Windows taskkill /T /F，同 LSP transport 口径）。 */
+  /**
+   * 清理父环境后合并 launch 配置显式 env，null 表示移除该项。
+   * @private
+   * @author ddj 2026年09月28号
+   * @returns 适配器的环境副本
+   */
+  private adapterEnv(): NodeJS.ProcessEnv {
+    const explicit: NodeJS.ProcessEnv = {}
+    const raw = this.config?.raw?.env
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === 'string' || value === null) explicit[key] = value ?? undefined
+      }
+    }
+    return childEnv(explicit)
+  }
+
+  /**
+   * 解除会话拥有权并终止适配器进程树；不先杀根进程。
+   * @private
+   * @author ddj 2026年09月28号
+   * @description 同时清理所有待处理请求与计时器。
+   */
   private killChild(): void {
     const child = this.child
     this.child = null
     for (const entry of this.pending.values()) { clearTimeout(entry.timer); entry.resolve(null) }
     this.pending.clear()
-    if (!child) return
-    try { child.kill() } catch { /* 忽略 */ }
-    if (process.platform === 'win32' && child.pid) {
-      try { spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }) } catch { /* 忽略 */ }
-    }
-    setTimeout(() => { try { child.kill('SIGKILL') } catch { /* 忽略 */ } }, 1500).unref?.()
+    if (child) stopTree(child, (line) => log.warn('[dap] ' + line))
   }
 
   /** 相位切换（running→running 等幂等跳过）。 */

package/src/devForm.ts

@@ -1,133 +1,293 @@
-/**
- * dsh-vscode-mode host — 开发形态管理（安装形态切换）。
- * 开发形态 = profile 中以 link: 依赖 + junction 指向工作区的安装（用于插件开发）；
- * 关闭 = 改回版本依赖 + 删 junction + pnpm install 装配正式版。
- * 切换后需重启 DSH 生效（运行中的代码仍是旧形态）。
- * 与 compat.ts 存在模块环（devForm 用 pluginVersionOf、compat 用 readDevForm），
- * 双方仅在函数体内交叉使用，模块求值期无依赖，ESM 安全。
- * 作者 ddj 2026-08-24
- */
-import { existsSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { homedir } from 'node:os'
+/** 当前运行 profile 的开发形态切换；失败恢复 manifest、lockfile 与原安装入口。 */
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 import { PLUGIN_NAME, pluginVersionOf } from './compat.js'
+import { dshHome } from './paths.js'
+import { childEnv } from './childEnv.js'
 import type { DevFormInfo } from './shared/compat.js'
 import type { Ctx } from './store.js'
 
-/** 扫描 $DSH_HOME/profiles 找到依赖本插件的 profile 目录（无 env 依赖，多 profile 安全）。 */
-export function findProfileDir(): string | undefined {
-  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+/** 官方 dsh profile-boot 提供的当前运行事实；不从 inventory 猜测。 */
+interface ProfileContext {
+  dir: string
+  packageManager?: { command: string; args?: string[]; env?: NodeJS.ProcessEnv }
+}
+type SwitchResult = { ok: boolean; error?: string; restart: boolean }
+interface ProfileBackup {
+  dir: string
+  link: string
+  savedLink: string
+  hadLink: boolean
+  files: { path: string; text: Buffer | undefined }[]
+}
+const switching = new Set<string>()
+
+// --region 运行上下文
+/**
+ * 获取官方 profileContext 服务；服务存在但无有效目录时拒绝猜测。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param ctx 可选运行上下文
+ * @returns 官方服务对象或缺失
+ * @throws 服务对象目录无效
+ */
+function profileOf(ctx?: Ctx): ProfileContext | undefined {
+  const profile = ctx?.get?.('profileContext')
+  if (profile === undefined || profile === null) return undefined
+  if (typeof profile.dir !== 'string' || !isAbsolute(profile.dir)) throw new Error('当前 profileContext.dir 无效')
+  return profile as ProfileContext
+}
+
+/**
+ * 检查 manifest 是否明确依赖本插件；坏 manifest 不作候选。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir profile 目录
+ * @returns 是否包含插件依赖
+ */
+function ownsPlugin(dir: string): boolean {
   try {
-    for (const name of readdirSync(join(home, 'profiles'))) {
-      const pkgFile = join(home, 'profiles', name, 'package.json')
-      if (!existsSync(pkgFile)) continue
-      try {
-        const pkg = JSON.parse(readFileSync(pkgFile, 'utf8')) as { dependencies?: Record<string, unknown> } | undefined
-        if (pkg?.dependencies?.[PLUGIN_NAME]) return dirname(pkgFile)
-      } catch {
-        /* 坏 manifest 跳过该 profile */
-      }
-    }
-  } catch {
-    /* profiles 目录不存在时放弃 */
-  }
-  return undefined
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, ''))
+    return typeof pkg?.dependencies?.[PLUGIN_NAME] === 'string'
+  } catch { return false }
 }
 
 /**
- * 读取当前开发形态（manifest link: 判定）。
- * @author ddj 2026年08月24号
- * @returns 开发形态状态
+ * 优先使用真实运行 profile；旧宿主仅允许唯一候选回退，多候选拒绝。
+ * @public
+ * @author ddj 2026年09月28号
+ * @param ctx DSH host 上下文（可选，旧宿主兼容）
+ * @returns 当前 profile 目录；无有效或唯一候选时 undefined
  */
-export function readDevForm(): DevFormInfo {
-  const profileDir = findProfileDir()
-  if (!profileDir) return { enabled: false }
+export function findProfileDir(ctx?: Ctx): string | undefined {
   try {
-    const text = readFileSync(join(profileDir, 'package.json'), 'utf8').replace(/^\uFEFF/, '')
-    const pkg = JSON.parse(text) as { dependencies?: Record<string, unknown> } | undefined
+    const profile = profileOf(ctx)
+    if (profile) return ownsPlugin(profile.dir) ? profile.dir : undefined
+    const homePath = ctx?.get?.('dshHomePath')
+    const root = join(typeof homePath === 'function' ? homePath() : dshHome(), 'profiles')
+    const candidates = readdirSync(root).map((name) => join(root, name)).filter(ownsPlugin)
+    return candidates.length === 1 ? candidates[0] : undefined
+  } catch { return undefined }
+}
+
+/**
+ * 读取选中 profile 的 link 依赖状态。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir 已选定目录
+ * @returns 开发形态；无法读取时未开启
+ */
+function readProfileForm(dir: string): DevFormInfo {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, ''))
     const spec = pkg?.dependencies?.[PLUGIN_NAME]
-    if (typeof spec === 'string' && spec.startsWith('link:')) {
-      return { enabled: true, path: spec.slice('link:'.length) }
-    }
-  } catch {
-    /* manifest 不可读视为非开发形态 */
-  }
+    if (typeof spec === 'string' && spec.startsWith('link:')) return { enabled: true, path: spec.slice(5) }
+  } catch { /* 只读探测失败 */ }
   return { enabled: false }
 }
 
 /**
- * 规划切换后的 manifest 文本（纯函数，可单测；非法 JSON 抛错）。
- * @author ddj 2026年08月24号
+ * 读取当前运行 profile 的开发形态。
+ * @public
+ * @author ddj 2026年09月28号
+ * @param ctx DSH host 上下文
+ * @returns 开发形态状态
+ */
+export function readDevForm(ctx?: Ctx): DevFormInfo {
+  const dir = findProfileDir(ctx)
+  return dir ? readProfileForm(dir) : { enabled: false }
+}
+// --endregion
+
+/**
+ * 规划切换后的 manifest，保留其它字段。
+ * @public
+ * @author ddj 2026年09月28号
  * @param text 原 manifest 文本
- * @param enabled 目标形态（true=link:，false=版本）
- * @param path 工作区路径（开启时必填）
- * @param version 版本号（关闭时使用，写入 ^<version>）
- * @returns 新 manifest 文本（无 BOM，2 空格缩进）
+ * @param enabled true 为开发链接
+ * @param path 开发目录
+ * @param version 正式版本号
+ * @returns 新 manifest 文本
+ * @throws JSON 或 dependencies 无效
  */
 export function planManifest(text: string, enabled: boolean, path: string, version: string): string {
   const data = JSON.parse(text.replace(/^\uFEFF/, '')) as { dependencies?: Record<string, unknown> }
-  if (!data.dependencies || typeof data.dependencies !== 'object') {
+  if (!data.dependencies || typeof data.dependencies !== 'object' || Array.isArray(data.dependencies)) {
     throw new Error('profile package.json 缺少 dependencies 字段')
   }
   data.dependencies[PLUGIN_NAME] = enabled ? 'link:' + path.replace(/\\/g, '/') : '^' + version
   return JSON.stringify(data, null, 2) + '\n'
 }
 
-/** 建立或移除 node_modules 下的开发 junction（目标不存在时开启失败）。 */
-function applyJunction(profileDir: string, enabled: boolean, target: string): void {
-  const linkDir = join(profileDir, 'node_modules', PLUGIN_NAME)
-  if (existsSync(linkDir)) rmSync(linkDir, { recursive: true, force: true })
-  if (!enabled) return
-  if (!existsSync(target)) throw new Error('工作区路径不存在：' + target)
-  symlinkSync(target, linkDir, 'junction')
+// --region 切换事务
+/**
+ * 检查开发目录属于本插件且不位于会被替换的 node_modules 内。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir profile 目录
+ * @param target 用户目标路径
+ * @returns 真实绝对目录
+ * @throws 目录、包身份或位置不安全
+ */
+function checkTarget(dir: string, target: string): string {
+  if (!target || !isAbsolute(target)) throw new Error('开启开发形态需要提供工作区绝对路径')
+  const full = realpathSync(target)
+  if (!statSync(full).isDirectory()) throw new Error('工作区路径不是目录：' + target)
+  const pkg = JSON.parse(readFileSync(join(full, 'package.json'), 'utf8').replace(/^\uFEFF/, ''))
+  if (pkg?.name !== PLUGIN_NAME) throw new Error('工作区 package.json.name 必须是 ' + PLUGIN_NAME)
+  const modules = join(dir, 'node_modules')
+  const moduleRoot = existsSync(modules) ? realpathSync(modules) : resolve(realpathSync(dir), 'node_modules')
+  const inside = relative(moduleRoot, full)
+  if (!inside || (!inside.startsWith('..' + (process.platform === 'win32' ? '\\' : '/')) && !isAbsolute(inside))) {
+    throw new Error('开发源码不能位于当前 profile 的 node_modules 内')
+  }
+  return full
+}
+
+/**
+ * 删除安装入口；链接仅 unlink，绝不递归其源码目标。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param path 安装入口或备份入口
+ * @throws 删除失败
+ */
+function removeEntry(path: string): void {
+  const info = lstatSync(path, { throwIfNoEntry: false })
+  if (!info) return
+  if (info.isSymbolicLink()) unlinkSync(path)
+  else rmSync(path, { recursive: true, force: true })
+}
+
+/**
+ * 在首次写入前保存 manifest/lockfile 原字节，并移动原安装入口保留链接身份。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir profile 目录
+ * @returns 可回滚的备份
+ * @throws 备份失败；尚未修改 manifest
+ */
+function backupProfile(dir: string): ProfileBackup {
+  const files = ['package.json', 'pnpm-lock.yaml'].map((name) => {
+    const path = join(dir, name)
+    return { path, text: existsSync(path) ? readFileSync(path) : undefined }
+  })
+  const backupDir = mkdtempSync(join(dir, '.vscode-mode-backup-'))
+  const link = join(dir, 'node_modules', PLUGIN_NAME)
+  const savedLink = join(backupDir, 'module')
+  const hadLink = !!lstatSync(link, { throwIfNoEntry: false })
+  try {
+    for (const file of files) {
+      if (file.text !== undefined) writeFileSync(join(backupDir, relative(dir, file.path)), file.text)
+    }
+    if (hadLink) renameSync(link, savedLink)
+    return { dir: backupDir, link, savedLink, hadLink, files }
+  } catch (error) {
+    rmSync(backupDir, { recursive: true, force: true })
+    throw error
+  }
 }
 
 /**
- * 切换开发形态：改 manifest → 建/删 junction → pnpm install（subprocess）。
- * @author ddj 2026年08月24号
- * @param ctx DSH host 上下文（subprocess 服务）
+ * 恢复原安装入口和配置文件；恢复失败时保留备份供恢复。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param saved 原状态备份
+ * @throws 回滚失败，错误包含备份位置
+ */
+function restoreProfile(saved: ProfileBackup): void {
+  const failures: string[] = []
+  try {
+    removeEntry(saved.link)
+    if (saved.hadLink) renameSync(saved.savedLink, saved.link)
+  } catch (error) { failures.push(String(error)) }
+  for (const file of saved.files) {
+    try {
+      if (file.text === undefined) rmSync(file.path, { force: true })
+      else writeFileSync(file.path, file.text)
+    } catch (error) { failures.push(String(error)) }
+  }
+  if (failures.length) throw new Error('回滚失败，备份保留于 ' + saved.dir + '：' + failures.join('; '))
+  rmSync(saved.dir, { recursive: true, force: true })
+}
+
+/**
+ * 执行已预检的切换；安装失败时恢复原入口及 manifest/lockfile。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param ctx host 上下文
+ * @param dir 已确定的 profile
  * @param enabled 目标形态
- * @param path 工作区绝对路径（开启时必填）
- * @returns 切换结果（restart=true 表示需重启 DSH 生效）
+ * @param target 已预检目标
+ * @returns 事务结果；成功需重启
  */
-export async function setDevForm(ctx: Ctx, enabled: boolean, path?: string): Promise<{ ok: boolean; error?: string; restart: boolean }> {
-  const profileDir = findProfileDir()
-  if (!profileDir) return { ok: false, error: '未找到依赖本插件的 profile（检查 DSH_HOME/profiles）', restart: false }
-  const current = readDevForm()
-  const target = (path ?? current.path ?? '').replace(/\\/g, '/')
-  if (enabled && !target) return { ok: false, error: '开启开发形态需要提供工作区路径（path 参数）', restart: false }
-  if (enabled === current.enabled && (!enabled || target === current.path)) {
-    return { ok: true, restart: false }
+async function switchProfile(ctx: Ctx, dir: string, enabled: boolean, target: string): Promise<SwitchResult> {
+  const version = pluginVersionOf()
+  if (!version) throw new Error('读取插件版本失败，无法写入版本依赖')
+  const next = planManifest(readFileSync(join(dir, 'package.json'), 'utf8'), enabled, target, version)
+  const saved = backupProfile(dir)
+  try {
+    writeFileSync(join(dir, 'package.json'), next, 'utf8')
+    mkdirSync(join(dir, 'node_modules'), { recursive: true })
+    if (enabled) symlinkSync(target, saved.link, 'junction')
+    await runPnpmInstall(ctx, dir)
+  } catch (error) {
+    restoreProfile(saved)
+    throw error
   }
   try {
-    const pkgFile = join(profileDir, 'package.json')
-    const version = pluginVersionOf()
-    if (!version) return { ok: false, error: '读取插件版本失败，无法写入版本依赖', restart: false }
-    const next = planManifest(readFileSync(pkgFile, 'utf8').replace(/^\uFEFF/, ''), enabled, target, version)
-    writeFileSync(pkgFile, next, 'utf8')
-    applyJunction(profileDir, enabled, target)
-    const installError = await runPnpmInstall(ctx, profileDir)
-    return { ok: !installError, error: installError, restart: true }
+    removeEntry(saved.savedLink)
+    rmSync(saved.dir, { recursive: true, force: true })
   } catch (error) {
-    return { ok: false, error: String(error), restart: false }
+    return { ok: true, error: '切换成功，旧安装备份清理失败：' + saved.dir + '：' + String(error), restart: true }
   }
+  return { ok: true, restart: true }
 }
 
-/** 在 profile 目录执行 pnpm install（subprocess 契约：spawn({argv,cwd,stdio,graceMs})）。 */
-async function runPnpmInstall(ctx: Ctx, profileDir: string): Promise<string | undefined> {
-  const sub = ctx.get('subprocess')
-  if (!sub || typeof sub.spawn !== 'function') return 'manifest/junction 已更新，但缺少 subprocess：请手动在 profile 目录运行 pnpm install'
-  const handle = sub.spawn({
-    argv: ['pnpm', 'install'],
+/**
+ * 预检运行 profile、目标与安装服务，再串行执行可回滚切换。
+ * @public
+ * @author ddj 2026年09月28号
+ * @param ctx DSH host 上下文
+ * @param enabled 目标形态
+ * @param path 开发工作区绝对路径
+ * @returns 结果与是否需重启；失败不提交切换
+ */
+export async function setDevForm(ctx: Ctx, enabled: boolean, path?: string): Promise<SwitchResult> {
+  const dir = findProfileDir(ctx)
+  if (!dir) return { ok: false, error: '无法唯一定位当前 profile；请检查 profileContext 或 DSH_HOME/profiles', restart: false }
+  const key = process.platform === 'win32' ? resolve(dir).toLowerCase() : resolve(dir)
+  if (switching.has(key)) return { ok: false, error: '该 profile 正在切换开发形态', restart: false }
+  switching.add(key)
+  try {
+    const current = readProfileForm(dir)
+    const raw = path ?? current.path ?? ''
+    const target = enabled ? checkTarget(dir, raw) : ''
+    if (enabled === current.enabled && (!enabled || resolve(dir, current.path ?? '') === target)) return { ok: true, restart: false }
+    if (typeof ctx?.get?.('subprocess')?.spawn !== 'function') throw new Error('缺少 subprocess 服务，未修改 profile')
+    return await switchProfile(ctx, dir, enabled, target)
+  } catch (error) {
+    return { ok: false, error: String(error), restart: false }
+  } finally { switching.delete(key) }
+}
+
+/**
+ * 使用官方 profileContext.packageManager 运行 Desktop 内置 pnpm；旧宿主使用 PATH。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param ctx host 上下文
+ * @param profileDir profile 工作目录
+ * @throws 启动失败或非零退出；只需退出码，stdio 使用 inherit
+ */
+async function runPnpmInstall(ctx: Ctx, profileDir: string): Promise<void> {
+  const runner = profileOf(ctx)?.packageManager
+  const handle = ctx.get('subprocess').spawn({
+    argv: [runner?.command ?? 'pnpm', ...runner?.args ?? [], 'install'],
     cwd: profileDir,
-    stdio: { stdout: { maxBytes: 1 << 16 }, stderr: { maxBytes: 1 << 16 }, stdin: 'ignore' },
+    env: childEnv(runner?.env),
+    stdio: { stdout: 'inherit', stderr: 'inherit', stdin: 'ignore' },
     graceMs: 120000,
   })
   const outcome = await handle.done
-  const code = outcome?.exitCode ?? outcome?.code
-  if (code !== 0) {
-    const stderr = handle.collected?.stderr?.readFrom(0).text ?? ''
-    return 'pnpm install 失败（exit ' + code + '）：' + stderr.slice(0, 500)
-  }
-  return undefined
+  if (outcome?.exitCode !== 0) throw new Error('pnpm install 失败（exit ' + String(outcome?.exitCode) + '）')
 }
+// --endregion