dsh-vscode-mode 0.1.52 → 0.1.53

package/src/rpc.ts

@@ -32,6 +32,10 @@ import { rulesList, rulesRead, rulesRemove, rulesSave, rulesToggle } from './rul
 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 { INTEGRATION_BASE_DEFAULT } from './shared/integration.js'
+import { shellMenuRegister, shellMenuRemove, shellMenuStatus } from './integrate.js'
+import { unityAdd, unityInstall, unityList, unityRemove } from './unityBridge.js'
+import { handoffOpen, pendingState, pollPending } from './externalHandoff.js'
 import { buildReport } from './compat.js'
 import { findProfileDir, readDevForm, setDevForm } from './devForm.js'
 import { normalizeRel } from './tree.js'
@@ -216,6 +220,15 @@ async function latestPatchBackup(patchPath: string): Promise<string | undefined>
   return names.filter((n) => n.startsWith(base + '.bak-')).sort().reverse()[0]
 }
 
+/** 读取设置中的深链基址（缺省/非法回退默认 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 raw = typeof value?.integrationBaseUrl === 'string' ? value.integrationBaseUrl.trim() : ''
+  return raw || INTEGRATION_BASE_DEFAULT
+}
+
 /** 各方法 handler 表（类型由 shared/rpc 的 RpcHandlerMap 约束）。 */
 export function buildHandlers(
   ctx: Ctx,
@@ -524,16 +537,18 @@ export function buildHandlers(
       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), revision: descriptor?.revision }
+      return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? FILE_OPEN_DEFAULT), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: descriptor?.revision }
     },
     'vscode.fileOpenSettingsUpdate': async (args) => {
       const settings = ctx.get('settings')
       if (!settings?.update) return { ok: false, error: '设置服务不可用' }
       try {
-        await settings.update(FILE_OPEN_SETTINGS_NS, { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) }, args.expectedRevision)
+        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), revision: descriptor?.revision }
+        return { ok: true, fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool), integrationBaseUrl: await integrationBaseUrlOf(ctx), revision: descriptor?.revision }
       } catch (error) { return { ok: false, error: String(error) }
       }
     },
@@ -548,6 +563,78 @@ export function buildHandlers(
         return { ok: false, error: String(error) }
       }
     },
+    'edrv.integration.status': async () => {
+      try {
+        return { ok: true, ...(await shellMenuStatus(ctx, await integrationBaseUrlOf(ctx))) }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.integration.register': async () => {
+      try {
+        return { ok: true, ...(await shellMenuRegister(ctx, await integrationBaseUrlOf(ctx))) }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.integration.unregister': async () => {
+      try {
+        return { ok: true, ...(await shellMenuRemove(ctx, await integrationBaseUrlOf(ctx))) }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.unity.list': async () => {
+      try {
+        return { ok: true, ...(await unityList()) }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.unity.add': async (args) => {
+      try {
+        return { ok: true, project: await unityAdd(args.path) }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.unity.remove': async (args) => {
+      try {
+        await unityRemove(args.path)
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.unity.install': async (args) => {
+      try {
+        return { ok: true, project: await unityInstall(args.path) }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.externalStat': async (args) => {
+      // 深链判型（无会话依赖）：绝对路径直过 resolve；缺失/其他类型归入 missing
+      const fs = ctx.get('fs')
+      if (!fs) return { ok: false, error: '缺少 fs' }
+      try {
+        const target = await fs.resolve(args.path)
+        const info = await fs.stat(target)
+        if (!info || info.type === 'other') return { ok: true, kind: 'missing' }
+        return { ok: true, kind: info.type === 'directory' ? 'directory' : 'file' }
+      } catch (error) {
+        return { ok: false, error: String(error) }
+      }
+    },
+    'edrv.external.handoff': async (args) => ({
+      ok: true,
+      ...handoffOpen({ paths: args.paths, line: args.line, column: args.column }),
+    }),
+    'edrv.external.pending': async () => ({ ok: true, open: pollPending() }),
+    'edrv.external.pendingState': async (args) => ({
+      ok: true,
+      delivered: pendingState(args.token, args.take === true).delivered,
+    }),
     'edrv.perf.inventory': async () => {
       try {
         const home = dshHome()

package/src/shared/externalOpen.ts

@@ -0,0 +1,62 @@
+/**
+ * dsh-vscode-mode shared — 外部深链 URL 契约（Windows launcher / Unity 包 / client 共用）。
+ * 形态：?<FLAG>=1&<PATHS_KEY>=<enc1>[,<enc2>…] [&<LINE_KEY>=N] [&<COLUMN_KEY>=M]
+ * 每个路径独立 percent-encode（encodeURIComponent / Uri.EscapeDataString）后以 `,` 连接：
+ * 编码结果不含裸逗号（Windows 路径本身不允许逗号，编码兜底其余字符），URLSearchParams
+ * 取值做一次标准解码即得 `enc1,enc2`，按 `,` split 即路径，无需二次 decode。
+ * Purity rule: no node/react imports（URLSearchParams 为标准全局）。
+ * 作者 ddj 2026-09-07
+ */
+
+/** 深链开关参数名（值恒为 '1'）。 */
+export const EDRV_OPEN_FLAG = 'edrvOpen'
+/** 路径列表参数名（逗号分隔的已编码路径）。 */
+export const EDRV_PATHS_KEY = 'edrvPaths'
+/** 目标行参数名（1-based，可选，作用于首个路径）。 */
+export const EDRV_LINE_KEY = 'edrvLine'
+/** 目标列参数名（1-based，可选，作用于首个路径）。 */
+export const EDRV_COLUMN_KEY = 'edrvColumn'
+/** 深链参数键全集（URL 清理用）。 */
+export const EDRV_PARAM_KEYS = [EDRV_OPEN_FLAG, EDRV_PATHS_KEY, EDRV_LINE_KEY, EDRV_COLUMN_KEY]
+/** 路径分隔符（编码后路径不含裸逗号，分隔安全）。 */
+export const PATHS_SEPARATOR = ','
+
+/** 一次外部深链请求（解析结果）。 */
+export interface OpenParams {
+  /** 待打开路径（已解码，首个路径可携带行列）。 */
+  paths: string[]
+  /** 目标行（1-based，可空）。 */
+  line?: number
+  /** 目标列（1-based，可空）。 */
+  column?: number
+}
+
+/**
+ * 解析深链查询串：非深链/路径为空 → null；行列仅接受正整数，非法忽略。
+ * @author ddj 2026年09月07号
+ * @param search location.search（含或不含前导 ? 均可）
+ * @returns 深链参数或 null
+ */
+export function parseOpenParams(search: string): OpenParams | null {
+  const params = new URLSearchParams(search ?? '')
+  if (params.get(EDRV_OPEN_FLAG) !== '1') return null
+  const paths = (params.get(EDRV_PATHS_KEY) ?? '')
+    .split(PATHS_SEPARATOR)
+    .map((item) => item.trim())
+    .filter(Boolean)
+  if (!paths.length) return null
+  const line = positiveIntOf(params.get(EDRV_LINE_KEY))
+  const column = positiveIntOf(params.get(EDRV_COLUMN_KEY))
+  return { paths, line, column }
+}
+
+/**
+ * 正整数解析（非法/非正 → undefined）。
+ * @author ddj 2026年09月07号
+ * @param raw 参数原文（可空）
+ * @returns 正整数或 undefined
+ */
+function positiveIntOf(raw: string | null): number | undefined {
+  const value = Number(raw)
+  return Number.isInteger(value) && value > 0 ? value : undefined
+}

package/src/shared/integration.ts

@@ -0,0 +1,73 @@
+/**
+ * dsh-vscode-mode shared — 系统集成载荷契约（Windows 右键菜单 + Unity 一键安装/更新）。
+ * Purity rule: no node/react imports（platform 用 string 表示）。
+ * 作者 ddj 2026-09-07
+ */
+
+/** Unity 内嵌包名（UPM 包名，同时是项目 Packages/ 下的目录名）。 */
+export const UNITY_PACKAGE_NAME = 'com.dsh.editor'
+/** 注册表菜单键叶子名（HKCU\Software\Classes\*\shell\<leaf>）。 */
+export const SHELL_MENU_LEAF = 'DSHEditor'
+/** 深链基址默认值（DSH Web GUI 默认端口，dsh-web.cmd 实证）。 */
+export const INTEGRATION_BASE_DEFAULT = 'http://127.0.0.1:3080'
+
+/** launcher 安装态。 */
+export interface ShellLauncherState {
+  /** launcher 文件是否已安装（编译 exe 或降级 ps1）。 */
+  present: boolean
+  /** 是否为已编译 exe（false = 降级 ps1）。 */
+  compiled: boolean
+  /** launcher 文件绝对路径（未安装时为期望路径）。 */
+  path: string
+}
+
+/** 一条右键菜单注册条目（跨平台：Windows 三键 / Linux 两项 / macOS 快速操作）。 */
+export interface ShellMenuEntry {
+  /** 条目 id（files/dir/dirBackground/nautilus/dolphin/finder）。 */
+  id: string
+  /** 展示名。 */
+  label: string
+  /** 是否已注册。 */
+  registered: boolean
+  /** 是否需手动创建（macOS Automator 配方）。 */
+  manual?: boolean
+}
+
+/** 系统集成状态（edrv.integration.status/register/unregister 载荷）。 */
+export interface ShellIntegrationStatus {
+  /** 宿主平台（'win32'/'linux'/'darwin'）。 */
+  platform: string
+  launcher: ShellLauncherState
+  /** 菜单注册条目（按平台）。 */
+  entries: ShellMenuEntry[]
+  /** 深链基址（设置 integrationBaseUrl）。 */
+  baseUrl: string
+  /** Unity 包源目录（随插件分发的 unity/com.dsh.editor 绝对路径）。 */
+  unityPackagePath: string
+}
+
+/** 一个已登记 Unity 项目的安装状态（edrv.unity.* 载荷）。 */
+export interface UnityProjectEntry {
+  /** 项目根（归一化绝对路径）。 */
+  path: string
+  /** 目录名（展示标题）。 */
+  title: string
+  /** 已安装版本（未安装 → null）。 */
+  installedVersion: string | null
+  /** 已安装且版本等于包源版本。 */
+  upToDate: boolean
+  /** 项目目录不存在。 */
+  missingDir: boolean
+  /** 非法原因（非 Unity 项目根等）。 */
+  error?: string
+}
+
+/** edrv.unity.list 载荷。 */
+export interface UnityListPayload {
+  /** 包源版本（unity/com.dsh.editor/package.json 的 version）。 */
+  sourceVersion: string | null
+  /** 包源目录绝对路径。 */
+  sourcePath: string
+  /** 已登记项目及安装状态。 */
+  projects: UnityProjectEntry[]
+}

package/src/shared/rpc.ts

@@ -14,6 +14,7 @@ import type {
 } from './types.js'
 import type { MpcConfig, MpcProject, MpcProjectSaveInput, MpcServer } from './mcp.js'
 import type { CompatReport, DevFormInfo } from './compat.js'
+import type { ShellIntegrationStatus, UnityListPayload, UnityProjectEntry } from './integration.js'
 import type { RuleInfo, RuleProject, RuleRefInput, RuleSaveInput } from './rules.js'
 import type { LspEnvInstallState, LspExtInfo, LspExtUpdate, LspHover, LspLocation, LspMarketItem, LspPosition, LspSemanticTokens, LspServerStatus, LspSymbol } from './lsp.js'
 
@@ -132,7 +133,18 @@ export interface RpcRequestMap {
   'mcp.projectToggle': { workspacePath: string; serverName: string; enabled: boolean }
   'mcp.projectRefresh': { workspacePath: string; serverName: string }
   'vscode.fileOpenSettingsGet': {}
-  'vscode.fileOpenSettingsUpdate': { fileOpenTool: string; expectedRevision?: number }
+  'vscode.fileOpenSettingsUpdate': { fileOpenTool: string; integrationBaseUrl?: string; expectedRevision?: number }
+  'edrv.integration.status': {}
+  'edrv.integration.register': {}
+  'edrv.integration.unregister': {}
+  'edrv.unity.list': {}
+  'edrv.unity.add': { path: string }
+  'edrv.unity.remove': { path: string }
+  'edrv.unity.install': { path: string }
+  'edrv.externalStat': { path: string }
+  'edrv.external.handoff': { paths: string[]; line?: number; column?: number }
+  'edrv.external.pending': {}
+  'edrv.external.pendingState': { token: string; take?: boolean }
   'vscode.devFormGet': {}
   'vscode.devFormSet': { enabled: boolean; path?: string }
   'compat': {}
@@ -203,8 +215,19 @@ export interface RpcOkMap {
   'mcp.projectRemove': { project: MpcProject }
   'mcp.projectToggle': { project: MpcProject }
   'mcp.projectRefresh': { project: MpcProject }
-  'vscode.fileOpenSettingsGet': { fileOpenTool: string; revision?: number }
-  'vscode.fileOpenSettingsUpdate': { fileOpenTool: string; revision?: number }
+  'vscode.fileOpenSettingsGet': { fileOpenTool: string; integrationBaseUrl: string; revision?: number }
+  'vscode.fileOpenSettingsUpdate': { fileOpenTool: string; integrationBaseUrl: string; revision?: number }
+  'edrv.integration.status': ShellIntegrationStatus
+  'edrv.integration.register': ShellIntegrationStatus
+  'edrv.integration.unregister': ShellIntegrationStatus
+  'edrv.unity.list': UnityListPayload
+  'edrv.unity.add': { project: UnityProjectEntry }
+  'edrv.unity.remove': object
+  'edrv.unity.install': { project: UnityProjectEntry }
+  'edrv.externalStat': { kind: 'file' | 'directory' | 'missing' }
+  'edrv.external.handoff': { clients: number; token: string }
+  'edrv.external.pending': { open: { paths: string[]; line?: number; column?: number } | null }
+  'edrv.external.pendingState': { delivered: boolean }
   'vscode.devFormGet': { devForm: DevFormInfo }
   'vscode.devFormSet': { devForm: DevFormInfo; restart: boolean }
   'compat': { report: CompatReport }

package/src/unityBridge.ts

@@ -0,0 +1,234 @@
+/**
+ * dsh-vscode-mode host — Unity 内嵌包一键安装/更新。
+ * 机制：把包源目录 unity/com.dsh.editor 复制为 <Unity项目根>/Packages/com.dsh.editor
+ * （Unity 内嵌包自动发现，无需改 manifest.json）；安装/更新同入口（整目录替换）；
+ * 卸载 = 删除目标目录。登记清单存 ~/.dsh/dsh-vscode-mode/unity-projects.json。
+ * 安全：只触碰固定目标目录；项目根须含 Assets + ProjectSettings；目标已存在且
+ * package.json name 不是本包 → 拒绝覆盖。纯路径构造与项目特征判定可单测。
+ * 作者 ddj 2026-09-07
+ */
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dshHome, PLUGIN_ID } from './paths.js'
+import { UNITY_PACKAGE_NAME } from './shared/integration.js'
+import type { UnityListPayload, UnityProjectEntry } from './shared/integration.js'
+
+/** Unity 项目特征目录。 */
+const UNITY_MARKERS = ['Assets', 'ProjectSettings']
+/** 登记清单文件名。 */
+const PROJECTS_FILE = 'unity-projects.json'
+/** 包源目录相对插件包根的位置。 */
+const UNITY_DIR_NAME = 'unity'
+
+/**
+ * 包源目录（随插件包分发的 unity/com.dsh.editor 绝对路径）。
+ * @author ddj 2026年09月07号
+ * @param moduleUrl 模块 URL（缺省 import.meta.url；测试注入）
+ * @returns 包源目录绝对路径
+ */
+export function unitySourceDir(moduleUrl: string = import.meta.url): string {
+  return join(dirname(fileURLToPath(moduleUrl)), '..', UNITY_DIR_NAME, UNITY_PACKAGE_NAME)
+}
+
+/**
+ * 项目登记清单文件（~/.dsh/dsh-vscode-mode/unity-projects.json）。
+ * @author ddj 2026年09月07号
+ * @param home DSH home（测试可注入）
+ * @returns 清单文件绝对路径
+ */
+export function unityProjectsFile(home = dshHome()): string {
+  return join(home, PLUGIN_ID, PROJECTS_FILE)
+}
+
+/**
+ * 归一化用户输入的项目根：去首尾空白/引号/尾部分隔符。
+ * @author ddj 2026年09月07号
+ * @param raw 原始输入
+ * @returns 归一化绝对路径
+ */
+export function normalizeUnityRoot(raw: string): string {
+  return String(raw ?? '').trim().replace(/^["']|["']$/g, '').replace(/[\\/]+$/, '')
+}
+
+/**
+ * 目录名清单是否满足 Unity 项目特征（Assets + ProjectSettings 同时存在）。
+ * @author ddj 2026年09月07号
+ * @param entries 项目根下的目录名清单
+ * @returns 是否 Unity 项目根
+ */
+export function isUnityProject(entries: string[]): boolean {
+  return UNITY_MARKERS.every((marker) => entries.includes(marker))
+}
+
+/**
+ * 内嵌包目标目录（固定：<root>/Packages/com.dsh.editor）。
+ * @author ddj 2026年09月07号
+ * @param root Unity 项目根
+ * @returns 目标目录绝对路径
+ */
+export function unityTargetOf(root: string): string {
+  return join(root, 'Packages', UNITY_PACKAGE_NAME)
+}
+
+/**
+ * 读 package.json 的 version（缺失/非法 → null）。
+ * @author ddj 2026年09月07号
+ * @param pkgFile package.json 绝对路径
+ * @returns 版本号或 null
+ */
+export async function readPackageVersion(pkgFile: string): Promise<string | null> {
+  try {
+    const data = JSON.parse(await readFile(pkgFile, 'utf8')) as { version?: unknown }
+    return typeof data?.version === 'string' && data.version ? data.version : null
+  } catch {
+    return null
+  }
+}
+
+/** 登记清单单条记录。 */
+interface ProjectRecord { path: string; addedAt: string }
+
+/** 读登记清单（缺失/非法 → 空数组）。 */
+async function readProjects(home = dshHome()): Promise<ProjectRecord[]> {
+  try {
+    const data: unknown = JSON.parse(await readFile(unityProjectsFile(home), 'utf8'))
+    if (!Array.isArray(data)) return []
+    return (data as unknown[])
+      .filter((item): item is ProjectRecord => !!item && typeof (item as ProjectRecord).path === 'string')
+      .map((item) => ({ path: String(item.path), addedAt: String(item.addedAt ?? '') }))
+  } catch {
+    return []
+  }
+}
+
+/** 写登记清单（父目录按需创建）。 */
+async function writeProjects(records: ProjectRecord[], home = dshHome()): Promise<void> {
+  const file = unityProjectsFile(home)
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, JSON.stringify(records, null, 2) + '\n', 'utf8')
+}
+
+/**
+ * 单个项目的安装状态视图（版本对比 + 合法性）。
+ * @author ddj 2026年09月07号
+ * @param rawPath 项目路径（原始输入）
+ * @param moduleUrl 模块 URL（测试注入）
+ * @returns 项目状态
+ */
+export async function unityEntryOf(rawPath: string, moduleUrl: string = import.meta.url): Promise<UnityProjectEntry> {
+  const root = normalizeUnityRoot(rawPath)
+  const entry: UnityProjectEntry = { path: root, title: basename(root) || root, installedVersion: null, upToDate: false, missingDir: false }
+  let names: string[] = []
+  try {
+    names = await readdir(root)
+  } catch {
+    entry.missingDir = true
+    return entry
+  }
+  if (!isUnityProject(names)) {
+    entry.error = '不是 Unity 项目根（缺少 Assets 或 ProjectSettings 目录）'
+    return entry
+  }
+  const installed = await readPackageVersion(join(unityTargetOf(root), 'package.json'))
+  entry.installedVersion = installed
+  const sourceVersion = await readPackageVersion(join(unitySourceDir(moduleUrl), 'package.json'))
+  entry.upToDate = installed !== null && installed === sourceVersion
+  return entry
+}
+
+/**
+ * 列出登记项目与包源版本。
+ * @author ddj 2026年09月07号
+ * @param moduleUrl 模块 URL（测试注入）
+ * @param home DSH home（测试注入）
+ * @returns 列表载荷
+ */
+export async function unityList(moduleUrl: string = import.meta.url, home = dshHome()): Promise<UnityListPayload> {
+  const source = unitySourceDir(moduleUrl)
+  const records = await readProjects(home)
+  const projects: UnityProjectEntry[] = []
+  for (const record of records) projects.push(await unityEntryOf(record.path, moduleUrl))
+  return { sourceVersion: await readPackageVersion(join(source, 'package.json')), sourcePath: source, projects }
+}
+
+/**
+ * 登记一个 Unity 项目（校验通过才入清单，重复登记幂等）。
+ * @author ddj 2026年09月07号
+ * @param rawPath 项目路径（原始输入）
+ * @param moduleUrl 模块 URL（测试注入）
+ * @param home DSH home（测试注入）
+ * @returns 项目状态
+ */
+export async function unityAdd(rawPath: string, moduleUrl: string = import.meta.url, home = dshHome()): Promise<UnityProjectEntry> {
+  const root = normalizeUnityRoot(rawPath)
+  const entry = await unityEntryOf(root, moduleUrl)
+  if (entry.missingDir) throw new Error('目录不存在：' + root)
+  if (entry.error) throw new Error(entry.error)
+  const records = await readProjects(home)
+  if (!records.some((record) => normalizeUnityRoot(record.path) === root)) {
+    records.push({ path: root, addedAt: new Date().toISOString() })
+    await writeProjects(records, home)
+  }
+  return entry
+}
+
+/**
+ * 移除一个项目的登记（不删除已安装的包目录）。
+ * @author ddj 2026年09月07号
+ * @param rawPath 项目路径（原始输入）
+ * @param home DSH home（测试注入）
+ */
+export async function unityRemove(rawPath: string, home = dshHome()): Promise<void> {
+  const root = normalizeUnityRoot(rawPath)
+  const records = await readProjects(home)
+  await writeProjects(records.filter((record) => normalizeUnityRoot(record.path) !== root), home)
+}
+
+/**
+ * 一键安装/更新：整目录替换 <root>/Packages/com.dsh.editor 为包源内容。
+ * @author ddj 2026年09月07号
+ * @param rawPath 项目路径（原始输入）
+ * @param moduleUrl 模块 URL（测试注入）
+ * @returns 安装后项目状态
+ */
+export async function unityInstall(rawPath: string, moduleUrl: string = import.meta.url): Promise<UnityProjectEntry> {
+  const root = normalizeUnityRoot(rawPath)
+  const source = unitySourceDir(moduleUrl)
+  const target = unityTargetOf(root)
+  await validateInstallTarget(root, source, target)
+  await rm(target, { recursive: true, force: true })
+  await mkdir(join(target, '..'), { recursive: true })
+  await cp(source, target, { recursive: true })
+  return unityEntryOf(root, moduleUrl)
+}
+
+/**
+ * 安装前校验：Unity 项目根 + 目标不与包源重叠 + 已存在目标必须是本包。
+ * @author ddj 2026年09月07号
+ * @param root 项目根
+ * @param source 包源目录
+ * @param target 目标目录
+ */
+async function validateInstallTarget(root: string, source: string, target: string): Promise<void> {
+  let names: string[] = []
+  try {
+    names = await readdir(root)
+  } catch {
+    throw new Error('目录不存在：' + root)
+  }
+  if (!isUnityProject(names)) throw new Error('不是 Unity 项目根（缺少 Assets 或 ProjectSettings 目录）')
+  if (target === source || target.startsWith(source + sep) || source.startsWith(target + sep)) {
+    throw new Error('目标目录与包源重叠，拒绝安装')
+  }
+  const text = await readFile(join(target, 'package.json'), 'utf8').catch((error: NodeJS.ErrnoException) => {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  })
+  if (text === null) return
+  let name: unknown = null
+  try {
+    name = (JSON.parse(text) as { name?: unknown }).name
+  } catch { /* 解析失败按未知包处理 */ }
+  if (name !== UNITY_PACKAGE_NAME) throw new Error('目标目录已存在且不是 DSH 包，拒绝覆盖：' + target)
+}