dsh-explorer-open 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-explorer-open contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-explorer-open
+
+在 Windows 资源管理器的右键菜单里加一条 **「通过 dsh 打开」**：点一下就在 [DeepSeek Harness](https://github.com/deepseek-ai) 里打开这个文件夹（没有工作区就新建），并开一个新会话。
+
+Win11 的**新式简洁菜单**和**旧式完整菜单**里都有这一条，都带图标。
+
+- 仓库：<https://github.com/ame-code/dsh-explorer-open>
+- npm：`dsh-explorer-open`
+
+## 功能
+
+| 在哪儿右键 | 打开的文件夹 | 放进新会话的草稿 |
+| --- | --- | --- |
+| 文件夹空白处 | 当前文件夹 | 无 |
+| 文件夹图标上 | 这个文件夹 | 无 |
+| 任意文件上 | 文件所在的文件夹 | `@文件名` 引用（工作区之外的路径不引用） |
+
+- 每次都**新建会话**并切过去；工作区按完整路径复用，不会重复创建。
+- dsh 没开时会先把它拉起来，请求排队等页面连上再执行。
+- 插件停用/卸载时会**自己拆掉菜单**（旧式注册表键 + Win11 新式 MSIX 包），不留垃圾。
+
+## 状态
+
+当前 **0.1.x**：功能可用，但接口（`/api/plugins/...` 路径、`~/.dsh/dsh-explorer-open/` 状态目录、`DSH_EXPLORER_OPEN_*` 环境变量）和安装方式都还可能变，破坏性改动不保证向后兼容。
+
+原生组件（`win11/`）有独立的版本号，见 `native/version.txt`；JS 侧版本见 `package.json`。
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+在 dsh 的插件设置里安装 `dsh-explorer-open`，或让 agent 执行安装（bundle 安装入口接受 npm 包名）。
+
+首次启用时会自动装 Win11 新式菜单所需的 MSIX 包。因为是自签证书，包里没有受信的根，Windows 会拒绝安装并给出：
+
+```
+Deployment failed with HRESULT: 0x800B0109
+```
+
+这时以管理员身份运行一次插件目录下的 `native/trust-cert.bat`（把自签证书 `dsh-open-with.cer` 导入 `LocalMachine\TrustedPeople`），然后重启 dsh 即可。只需要做一次。
+
+> 只想要旧式菜单、不想动证书：设环境变量 `DSH_EXPLORER_OPEN_NO_MSIX=1` 再启动 dsh，插件就不会去装 MSIX 包。
+
+### 从源码/本地目录安装
+
+```powershell
+# 仓库本身就是插件包（package.json 在根目录）
+plugin_manager install_bundle E:\work\tools\dsh-open-with
+```
+
+改过代码后要重启 dsh 才会重新加载宿主侧插件；客户端 bundle 需要刷新页面。
+
+## 工作原理
+
+```
+资源管理器右键
+   ├─ 旧式菜单：HKCU\Software\Classes\{Directory\Background, Directory, *}\shell\OpenWithDsh
+   │     └─ powershell -File launch.ps1 "%V"   （无窗口，写入待办后退出）
+   └─ 新式菜单：MSIX 包身份 + 原生 IExplorerCommand
+         └─ 同一个 launch.ps1
+                ↓
+   %USERPROFILE%\.dsh\dsh-explorer-open\pending.json   {folder, file?, token, at}
+                ↓  宿主侧插件每 300ms 扫描
+   GET /api/plugins/dsh-explorer-open/request          （带 x-dsh-explorer-open 头）
+                ↓  页面侧插件每 1s 轮询
+   workspaces.create → sessions.create → uiWorkspace.openSession
+                ↓  文件右键时
+   conversation.input.requestDraftInitialization(binding, { prompt: '@文件', clearPreviousDraft: true })
+```
+
+- 启动器用 PowerShell 5.1 写 UTF-8（**无 BOM**）、先写临时文件再改名，页面不会读到半个 JSON。
+- `/api/...` 路由要求自定义请求头，跨站页面带不上它（会先触发预检），因此别的网页没法领走排队中的请求。
+- dsh 可执行文件位置由插件写进 `config.json`，启动器按 config → `DSH_EXPLORER_OPEN_EXE` → 常见安装路径的顺序查找。
+
+## win11/ 原生组件
+
+Win11 新式菜单不接受「注册表 + exe」的旧式扩展，必须是一个**有包身份、已签名、且 DLL 内嵌了 msix 身份清单**的 COM 组件。`win11/` 就是这个组件：
+
+```
+win11/
+├─ src/dsh_open_with.cpp   IExplorerCommand 实现（GetTitle/GetIcon/GetState/Invoke）
+├─ src/stub.cpp           满足清单的占位 exe（Windows.FullTrustApplication 入口，永不被启动）
+├─ src/test-host.cpp      不经过资源管理器的自测宿主
+├─ src/msix.manifest      DLL 内嵌的 msix 身份（publisher/packageName/applicationId）
+├─ src/msix.rc            把上面那份清单编进 PE 资源
+├─ assets/dsh.ico         菜单图标
+├─ package/AppxManifest.xml  MSIX 清单：comServer + fileExplorerContextMenus
+├─ build.sh               构建 → 签名 → 打包 → 同步到 ../native/
+├─ install-msix.ps1 / uninstall-msix.ps1
+└─ trust-cert.ps1 / trust-cert.bat   把自签证书导入受信存储
+```
+
+重新构建（需要 MinGW-w64、`windres`、Windows SDK BuildTools 的 `makeappx`/`signtool`，以及 `Cert:\CurrentUser\My` 里的 `CN=DshOpenWith` 证书）：
+
+```bash
+cd win11
+bash build.sh
+```
+
+`build.sh` 会把签名好的 `DshOpenWith.msix`、`dsh-open-with.cer` 和 `version.txt` 复制到 `../native/`，插件启用时按 `version.txt` 决定要不要重装。
+
+### 踩过的坑（都已在代码里修掉）
+
+1. **清单里的 GUID 不能带花括号**，否则 `Add-AppxPackage` 报 `0x80080204 / 0xC00CE169`。
+2. **DLL 必须内嵌 msix 身份清单**，否则资源管理器根本不会加载这个 COM 类（表现为"装好了但菜单里没有"）。
+3. DLL 必须 `-static` 链接：包目录里没有 `libwinpthread-1.dll`。
+4. `GetState` 不要依赖选中项解析结果：新式菜单取「文件夹空白处」时 `IShellItemArray` 是空的，返回 `ECS_HIDDEN` 会把菜单项藏起来。恒返回 `ECS_ENABLED`，路径解析放到 `Invoke`。
+5. AppX 代理进程里 `GetModuleFileNameW(NULL)` 返回的是代理进程的路径，图标要按 `DllMain` 保存的 `hinst` 取自身目录。
+6. 自签证书必须进 `LocalMachine\TrustedPeople`；`CurrentUser\Root` / `CurrentUser\TrustedPeople` 都不够。
+
+## 开发
+
+```bash
+# 宿主侧：注册表、待办扫描、HTTP 路由、启用/停用清理
+# USERPROFILE 指向一个空目录（要用 Windows 路径写法），DSH_EXPLORER_OPEN_TEST_HOME=1 是防误跑的开关
+USERPROFILE='E:\tmp\dsh-explorer-open-home' DSH_EXPLORER_OPEN_TEST_HOME=1 \
+DSH_EXPLORER_OPEN_REG_BASE='HKCU\Software\Classes\__dsh_explorer_open_test' \
+DSH_EXPLORER_OPEN_NO_MSIX=1 node test/host-test.mjs
+
+# 页面侧：调用顺序、参数、@引用拼装、失败回退
+node test/client-test.mjs
+```
+
+两个脚本都用假的 ctx / fetch，不会碰真实的菜单和 MSIX 包。
+
+- `HANDOFF.md`：开发笔记（决策记录、踩坑、待办），中文。
+- `win11/build/` 与 `.probe/` 是构建产物和本地临时目录，不纳入版本库。
+
+## 已知限制
+
+- 只在 Windows 上工作（注册表 + MSIX + 资源管理器）。
+- `*` 键会让这一条出现在**所有**文件类型上，包括没有关联程序的。
+- 以管理员权限运行的资源管理器不会显示用户级（HKCU）菜单项。
+- 新式菜单需要证书受信；分发第三方时应该用正式代码签名证书，而不是自签。
+
+## License
+
+MIT

package/client.js

@@ -0,0 +1,143 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-explorer-open',
+  factory(require) {
+    const REQUEST_URL = '/api/plugins/dsh-explorer-open/request'
+    // 自定义请求头：跨站页面无法在不触发预检的情况下带上它，
+    // 可以挡住别的网页偷偷 GET 掉排队中的请求。
+    const REQUEST_HEADER = 'x-dsh-explorer-open'
+    const POLL_MS = 1000
+
+    return {
+      inject: ['uiWorkspace', 'sessions', 'workspaces'],
+      apply(ctx) {
+        const log = (message, error) => {
+          if (error === undefined) console.info(`[dsh-explorer-open] ${message}`)
+          else console.warn(`[dsh-explorer-open] ${message}`, error)
+        }
+
+        /** 打开工作区（已存在则复用），在其中新建一个会话，再切过去。 */
+        async function handle(folder, file) {
+          // create 对同一路径是幂等的：有就返回已有的，没有才新建
+          const workspace = await ctx.workspaces.create({ path: folder })
+          const workspaceId = workspace.workspaceId
+
+          let sessionId
+          try {
+            // 不关心有没有旧会话：每次都新建一个
+            sessionId = await ctx.sessions.create({ workspaceId, cwd: workspace.path })
+          } catch (error) {
+            log(`新建会话失败，改为打开工作区: ${folder}`, error)
+            await ctx.uiWorkspace.openWorkspace(workspaceId)
+            return
+          }
+
+          try {
+            ctx.uiWorkspace.openSession(sessionId)
+          } catch (error) {
+            log(`切换到新会话失败，改为打开工作区: ${folder}`, error)
+            await ctx.uiWorkspace.openWorkspace(workspaceId)
+            return
+          }
+          log(`已打开: ${folder} → 会话 ${sessionId}`)
+
+          if (file !== undefined) await seedFileReference(workspace.path, sessionId, file)
+        }
+
+        /**
+         * 把被点中的文件写成草稿里的 @引用。
+         * 引用按会话 cwd 解析，所以只接受位于工作区之内的文件；含空格的路径用 @"..." 形式。
+         */
+        function relativeMention(cwd, file) {
+          const trim = (path) => path.replace(/[\\/]+$/u, '')
+          const base = trim(cwd)
+          const target = trim(file)
+          const lower = (path) => path.toLowerCase()
+          if (lower(target) === lower(base)) return undefined
+          const prefix = lower(target).startsWith(`${lower(base)}\\`) || lower(target).startsWith(`${lower(base)}/`)
+          if (!prefix) return undefined
+          const relative = target.slice(base.length + 1)
+          return `${/\s/u.test(relative) ? `@"${relative}"` : `@${relative}`} `
+        }
+
+        /** 新会话刚建好时，binding 可能还没就绪，短暂重试几次再写草稿。 */
+        async function seedFileReference(cwd, sessionId, file) {
+          const mention = relativeMention(cwd, file)
+          if (mention === undefined) {
+            log(`文件不在工作区内，跳过引用: ${file}`)
+            return
+          }
+
+          let input
+          try {
+            input = ctx.get('conversation')?.input
+          } catch {
+            input = undefined
+          }
+          if (input?.requestDraftInitialization === undefined) {
+            log(`当前界面不支持预置草稿，跳过引用: ${file}`)
+            return
+          }
+
+          for (let attempt = 0; attempt < 20; attempt += 1) {
+            const binding = ctx.sessions.binding?.(sessionId)
+            if (binding !== undefined) {
+              try {
+                const result = input.requestDraftInitialization(binding, {
+                  prompt: mention,
+                  clearPreviousDraft: true,
+                })
+                if (result !== 'blocked') {
+                  log(`已在草稿中引用: ${mention.trim()}`)
+                  return
+                }
+              } catch (error) {
+                log(`写入草稿失败: ${file}`, error)
+                return
+              }
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100))
+          }
+          log(`草稿未就绪，跳过引用: ${file}`)
+        }
+
+        async function poll() {
+          let data
+          try {
+            const res = await fetch(REQUEST_URL, { cache: 'no-store', headers: { [REQUEST_HEADER]: '1' } })
+            if (!res.ok) return
+            data = await res.json()
+          } catch {
+            return
+          }
+          if (data?.status !== 'open' || !Array.isArray(data.requests)) return
+          for (const request of data.requests) {
+            if (request === null || typeof request.folder !== 'string') continue
+            const file = typeof request.file === 'string' ? request.file : undefined
+            try {
+              await handle(request.folder, file)
+            } catch (error) {
+              log(`打开失败: ${request.folder}`, error)
+            }
+          }
+        }
+
+        let busy = false
+        async function tick() {
+          if (busy) return
+          busy = true
+          try {
+            await poll()
+          } finally {
+            busy = false
+          }
+        }
+
+        ctx.effect(() => {
+          void tick()
+          const timer = setInterval(() => void tick(), POLL_MS)
+          return () => clearInterval(timer)
+        })
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: dsh-explorer-open
+      name: 'dsh-explorer-open'
+      config: {}

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="4" y="10" width="56" height="44" rx="8" fill="#2f6bff"/>
+  <path d="M14 26l10 6-10 6z" fill="#fff"/>
+  <rect x="30" y="36" width="18" height="4" rx="2" fill="#fff"/>
+</svg>

package/index.js

@@ -0,0 +1,4 @@
+import { apply } from './lib/index.js'
+
+export { apply }
+export const inject = []

package/lib/index.js

@@ -0,0 +1,220 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { installLegacy, isLegacyInstalled, refreshExplorer, removeLegacy } from './registry.js'
+import { installPackage, removePackage } from './win11.js'
+
+/** 启动器写、本插件读的待办文件。 */
+const PENDING_DIR = join(homedir(), '.dsh', 'dsh-explorer-open')
+const PENDING_FILE = join(PENDING_DIR, 'pending.json')
+
+/** 页面询问「有没有新的右键请求」的接口。 */
+export const REQUEST_PATH = '/api/plugins/dsh-explorer-open/request'
+
+/** 页面轮询时必须带上的请求头，见 client.js。 */
+const REQUEST_HEADER = 'x-dsh-explorer-open'
+
+/** 超过这个时间的请求视为过期，不再执行。 */
+const REQUEST_TTL_MS = 120_000
+
+/** 同一路径连续请求（右键双击、菜单被重复触发）的合并窗口。 */
+const DUPLICATE_WINDOW_MS = 1_500
+
+/** 扫描待办文件的间隔。 */
+const SCAN_MS = 300
+
+/** 插件自带的启动器与图标；安装时复制到 PENDING_DIR，菜单指向那两份副本。 */
+const PLUGIN_DIR = join(dirname(fileURLToPath(import.meta.url)), '..')
+const LAUNCHER_SOURCE = join(PLUGIN_DIR, 'lib', 'launch.ps1')
+const LAUNCHER_PATH = join(PENDING_DIR, 'launch.ps1')
+const ICON_SOURCE = join(PLUGIN_DIR, 'assets', 'dsh.ico')
+const ICON_PATH = join(PENDING_DIR, 'dsh.ico')
+const CONFIG_FILE = join(PENDING_DIR, 'config.json')
+
+/**
+ * 把启动器和图标复制到固定位置，并写下 dsh 可执行文件的位置。
+ * 菜单里写死的是这个固定位置的路径，这样插件目录被移动/删除后菜单仍然可用，
+ * 也让注册表里不会出现一个指向开发目录的路径。
+ * config.json 让启动器知道该唤起哪个 exe，不必猜安装目录。
+ */
+function ensureRuntime() {
+  mkdirSync(PENDING_DIR, { recursive: true })
+  for (const [source, target] of [
+    [LAUNCHER_SOURCE, LAUNCHER_PATH],
+    [ICON_SOURCE, ICON_PATH],
+  ]) {
+    const bytes = readFileSync(source)
+    const current = existsSync(target) ? readFileSync(target) : undefined
+    if (current === undefined || !current.equals(bytes)) writeFileSync(target, bytes)
+  }
+  const config = `${JSON.stringify({ exe: process.execPath }, null, 2)}\n`
+  if (!existsSync(CONFIG_FILE) || readFileSync(CONFIG_FILE, 'utf8') !== config) {
+    writeFileSync(CONFIG_FILE, config)
+  }
+  return { launcher: LAUNCHER_PATH, icon: ICON_PATH }
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+function removePending() {
+  try {
+    rmSync(PENDING_FILE, { force: true })
+  } catch {
+    // 下次扫描会再试
+  }
+}
+
+function readPending() {
+  if (!existsSync(PENDING_FILE)) return undefined
+  try {
+    const payload = JSON.parse(readFileSync(PENDING_FILE, 'utf8'))
+    if (typeof payload?.folder !== 'string' || typeof payload?.at !== 'number') {
+      removePending()
+      return undefined
+    }
+    if (payload.file !== undefined && typeof payload.file !== 'string') {
+      removePending()
+      return undefined
+    }
+    return payload
+  } catch {
+    // 可能正好写了一半，留着下次再读
+    return undefined
+  }
+}
+
+export function apply(ctx) {
+  /** 待页面取走的请求；同一时刻只保留最新的一条。 */
+  let queue = []
+
+  // 0. Win11 新式精简菜单：装上带包身份的原生扩展（旧式菜单见下一段）
+  //    设 DSH_EXPLORER_OPEN_NO_MSIX=1 可跳过（离线自测时用，免得卸载真实安装的包）
+  ctx.effect(() => {
+    if (process.env.DSH_EXPLORER_OPEN_NO_MSIX === '1') return
+    let disposed = false
+    void (async () => {
+      try {
+        const result = installPackage()
+        if (result.status === 'untrusted') {
+          ctx.logger?.warn?.(
+            `[dsh-explorer-open] 新式菜单未启用：签名证书尚未被信任，请以管理员身份运行 ${result.detail}`,
+          )
+          return
+        }
+        if (result.status === 'missing-msix' || result.status === 'failed') {
+          ctx.logger?.warn?.(`[dsh-explorer-open] 新式菜单未启用: ${result.detail}`)
+          return
+        }
+        ctx.logger?.info?.(`[dsh-explorer-open] 新式菜单已就绪 ${result.status} ${result.detail}`)
+        if (result.status === 'installed') await refreshExplorer()
+      } catch (error) {
+        if (!disposed) ctx.logger?.warn?.(`[dsh-explorer-open] 安装新式菜单失败: ${error}`)
+      }
+    })()
+
+    return () => {
+      disposed = true
+      try {
+        removePackage()
+      } catch (error) {
+        ctx.logger?.warn?.(`[dsh-explorer-open] 卸载新式菜单失败: ${error}`)
+      }
+    }
+  })
+
+  // 1. 注入右键菜单；插件停用时移除
+  ctx.effect(() => {
+    let disposed = false
+    void (async () => {
+      try {
+        const { launcher, icon } = ensureRuntime()
+        await installLegacy(launcher, icon)
+        const ok = await isLegacyInstalled()
+        ctx.logger?.info?.(`[dsh-explorer-open] 右键菜单已写入=${ok} (${launcher})`)
+        await refreshExplorer()
+      } catch (error) {
+        if (!disposed) ctx.logger?.warn?.(`[dsh-explorer-open] 写入右键菜单失败: ${error}`)
+      }
+    })()
+
+    return () => {
+      disposed = true
+      void removeLegacy()
+        .then(() => refreshExplorer())
+        .catch((error) => ctx.logger?.warn?.(`[dsh-explorer-open] 移除右键菜单失败: ${error}`))
+    }
+  })
+
+  // 2. 扫描启动器留下的待办文件，转成内存里的请求
+  ctx.effect(() => {
+    let lastKey
+    let lastAt = 0
+
+    const tick = () => {
+      const payload = readPending()
+      if (payload === undefined) return
+      removePending()
+
+      if (Date.now() - payload.at > REQUEST_TTL_MS) return
+      if (!isDirectory(payload.folder)) return
+      // 文件右键：文件必须还在，否则只打开它所在的文件夹
+      const file = payload.file !== undefined && isFile(payload.file) ? payload.file : undefined
+      const key = `${payload.folder}\u0000${file ?? ''}`
+      // 1.5 秒内对同一目标的重复请求只算一次
+      if (key === lastKey && Date.now() - lastAt < DUPLICATE_WINDOW_MS) return
+
+      lastKey = key
+      lastAt = Date.now()
+      // 只保留最新一条；页面每秒来取一次
+      const request = { folder: payload.folder, token: payload.token ?? '', at: payload.at }
+      if (file !== undefined) request.file = file
+      queue = [request]
+      ctx.logger?.info?.(`[dsh-explorer-open] 收到请求: ${file ?? payload.folder}`)
+    }
+
+    const timer = setInterval(tick, SCAN_MS)
+    return () => clearInterval(timer)
+  })
+
+  // 3. 页面轮询这个接口领取请求
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(() =>
+      webCtx.webServer.register({
+        kind: 'exact',
+        path: REQUEST_PATH,
+        resource: async (request) => {
+          // 只认页面自己发的请求：跨站页面带不上这个头（会先触发预检）
+          if (request?.headers?.get?.(REQUEST_HEADER) !== '1') {
+            return new Response(JSON.stringify({ error: 'forbidden' }), {
+              status: 403,
+              headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+            })
+          }
+          const now = Date.now()
+          const taken = queue.filter((item) => now - item.at <= REQUEST_TTL_MS)
+          queue = []
+          const reply = { status: taken.length === 0 ? 'idle' : 'open', requests: taken }
+          return new Response(JSON.stringify(reply), {
+            status: 200,
+            headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+          })
+        },
+      }),
+    )
+  })
+}

package/lib/launch.ps1

@@ -0,0 +1,68 @@
+# Explorer context menu entry point.
+# Kept pure ASCII on purpose: Windows PowerShell 5.1 decodes BOM-less .ps1
+# files with the ANSI code page, so non-ASCII text would be mojibake.
+param([Parameter(Position = 0)][string]$Target)
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+# Normalise "%V": the shell may hand over a quoted path or a trailing separator.
+$path = $Target
+if ($null -ne $path) { $path = $path.Trim().Trim('"') }
+if ($null -ne $path) { $path = $path.TrimEnd('\', '/') }
+
+# A folder opens itself; a file opens the folder that contains it and is also
+# handed to the page so the new session can start with a reference to it.
+$folder = $null
+$file = $null
+
+if ($path) {
+    if ([System.IO.Directory]::Exists($path)) {
+        $folder = $path
+    }
+    elseif ([System.IO.File]::Exists($path)) {
+        $file = $path
+        $folder = [System.IO.Path]::GetDirectoryName($path)
+    }
+}
+
+if (-not $folder) { exit 0 }
+
+$root = Join-Path $env:USERPROFILE '.dsh\dsh-explorer-open'
+if (-not [System.IO.Directory]::Exists($root)) { [void][System.IO.Directory]::CreateDirectory($root) }
+
+$token = [guid]::NewGuid().ToString('N')
+$payload = [ordered]@{
+    folder = $folder
+    token  = $token
+    at     = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds()
+}
+if ($file) { $payload.file = $file }
+
+# Write to a unique temp file and rename, so the page never reads half a JSON.
+$json = $payload | ConvertTo-Json -Compress
+$temp = Join-Path $root ("pending.$token.tmp")
+$final = Join-Path $root 'pending.json'
+[System.IO.File]::WriteAllText($temp, $json, [System.Text.UTF8Encoding]::new($false))
+Move-Item -LiteralPath $temp -Destination $final -Force
+
+# Find the DeepSeek Harness executable: the plugin writes config.json with the
+# real path, then an environment variable, then a few well-known install spots.
+$exe = $null
+$config = Join-Path $root 'config.json'
+if ([System.IO.File]::Exists($config)) {
+    try { $exe = (Get-Content -LiteralPath $config -Raw | ConvertFrom-Json).exe } catch { $exe = $null }
+}
+if (-not $exe -and $env:DSH_EXPLORER_OPEN_EXE) { $exe = $env:DSH_EXPLORER_OPEN_EXE }
+
+if (-not ($exe -and [System.IO.File]::Exists($exe))) {
+    $candidates = @(
+        (Join-Path $env:LOCALAPPDATA 'Programs\DeepSeek Harness\DeepSeek Harness.exe'),
+        (Join-Path $env:ProgramFiles 'DeepSeek Harness\DeepSeek Harness.exe'),
+        'D:\DeepSeek Harness\DeepSeek Harness.exe'
+    )
+    foreach ($candidate in $candidates) {
+        if ($candidate -and [System.IO.File]::Exists($candidate)) { $exe = $candidate; break }
+    }
+}
+
+if ($exe -and [System.IO.File]::Exists($exe)) { Start-Process -FilePath $exe }

package/lib/registry.js

@@ -0,0 +1,120 @@
+import { execFile } from 'node:child_process'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+const run = promisify(execFile)
+
+/** 右键菜单显示文本，用户要求严格保持这个措辞。 */
+export const MENU_TEXT = '通过 dsh 打开'
+
+/**
+ * 旧式（扩展）右键菜单的挂载点：
+ * Directory\Background —— 在文件夹空白处右键（%V 是当前文件夹）；
+ * Directory            —— 在文件夹图标上右键（%V 是被点中的文件夹）；
+ * *                    —— 在任意文件上右键（%V 是该文件的完整路径，由启动器取所在目录）。
+ * Win11 的简洁菜单也是从这里读的，所以这几处同时覆盖新菜单和旧菜单。
+ */
+/** 自测时可用环境变量指到一次性的假位置，避免动到真实菜单；默认就是真实的用户级 Classes。 */
+const REG_BASE = process.env.DSH_EXPLORER_OPEN_REG_BASE || 'HKCU\\Software\\Classes'
+
+const LEGACY_SHELL_KEYS = [
+  `${REG_BASE}\\Directory\\Background\\shell\\OpenWithDsh`,
+  `${REG_BASE}\\Directory\\shell\\OpenWithDsh`,
+  `${REG_BASE}\\*\\shell\\OpenWithDsh`,
+]
+
+/** 旧式菜单里显示的图标。默认用插件自带的那份（安装时复制到固定位置）。 */
+const FALLBACK_ICON_PATH = ''
+
+const POWERSHELL = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
+
+async function reg(args) {
+  const { stdout } = await run('reg.exe', args, { windowsHide: true })
+  return stdout
+}
+
+async function keyExists(key) {
+  try {
+    await reg(['query', key])
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 生成 shell 命令。
+ * 菜单项经 cmd.exe 转发到 PowerShell：-NoProfile 保证不受用户配置文件影响，
+ * -ExecutionPolicy Bypass 保证脚本不会被组策略拦住。
+ */
+export function menuCommand(scriptPath) {
+  return `"${POWERSHELL}" -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "${scriptPath}" "%V"`
+}
+
+/**
+ * 写入旧式右键菜单项。
+ * %V 在 Background 键下是当前文件夹路径，在 Directory 键下是被点中的文件夹路径，
+ * 在 * 键下是被点中的文件路径（启动器会取它所在的文件夹并一并记下这个文件）。
+ * iconPath 为空时只写文字，不写图标。
+ */
+export async function installLegacy(launcherPath, iconPath = FALLBACK_ICON_PATH) {
+  const command = menuCommand(launcherPath)
+  for (const key of LEGACY_SHELL_KEYS) {
+    await reg(['add', key, '/ve', '/d', MENU_TEXT, '/f'])
+    if (iconPath) await reg(['add', key, '/v', 'Icon', '/d', iconPath, '/f'])
+    await reg(['add', `${key}\\command`, '/ve', '/d', command, '/f'])
+  }
+}
+
+/** 精确删除本插件写入的注册表键，不影响其他软件。 */
+export async function removeLegacy() {
+  for (const key of LEGACY_SHELL_KEYS) {
+    try {
+      await reg(['delete', key, '/f'])
+    } catch {
+      // 键本来就不存在，视为已清理干净
+    }
+  }
+}
+
+/** 用于确认启用/关闭是否真的生效。 */
+export async function isLegacyInstalled() {
+  const results = await Promise.all(LEGACY_SHELL_KEYS.map(keyExists))
+  return results.every(Boolean)
+}
+
+/** 更新资源管理器，让右键菜单的改动立刻可见（失败不影响功能，只是可能要等一会）。 */
+export async function refreshExplorer() {
+  const script = [
+    'Add-Type -Namespace GoW -Name Native -MemberDefinition \'[DllImport("shell32.dll")] public static extern void SHChangeNotify(int e, uint f, IntPtr i1, IntPtr i2);\';',
+    '[GoW.Native]::SHChangeNotify(0x8000000, 0x1000, [IntPtr]::Zero, [IntPtr]::Zero)',
+  ].join(' ')
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-explorer-open-'))
+  const file = join(dir, 'refresh.ps1')
+  try {
+    await writeFile(file, script, 'utf8')
+    await run(POWERSHELL, ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden', '-File', file], {
+      windowsHide: true,
+      timeout: 10_000,
+    })
+  } catch {
+    // 忽略：菜单项本身已经写好，资源管理器迟早会刷新
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/**
+ * Windows 11 的新式简洁右键菜单没有公开的注册接口，系统固定从扩展菜单读取。
+ * 该键存在 = 用户手动关掉了新菜单、退回旧菜单。
+ */
+export async function isWin11NewMenu() {
+  try {
+    await reg(['query', 'HKCU\\Software\\Classes\\CLSID\\{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}\\InprocServer32'])
+    return false
+  } catch {
+    return true
+  }
+}

package/lib/win11.js

@@ -0,0 +1,76 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Windows 11 新式右键菜单只接受「带包身份（packaged identity）」的扩展。
+ * 我们用稀疏 MSIX 包把原生 COM 组件（IExplorerCommand 实现）注册进那个菜单。
+ * 包名与 native/AppxManifest.xml 里的 Identity/@Name 必须一致。
+ */
+export const PACKAGE_NAME = 'DshOpenWith.Local'
+
+const POWERSHELL = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
+const NATIVE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'native')
+const MSIX_PATH = join(NATIVE_DIR, 'DshOpenWith.msix')
+const VERSION_FILE = join(NATIVE_DIR, 'version.txt')
+
+/** 证书不受信时 Add-AppxPackage 的报错码。 */
+const UNTRUSTED_HRESULT = '0x800B0109'
+
+function runPowerShell(script) {
+  const result = spawnSync(
+    POWERSHELL,
+    ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script],
+    { encoding: 'utf8', windowsHide: true, timeout: 60_000 },
+  )
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()
+  return { ok: result.status === 0, output }
+}
+
+/** 打包时写进 native/version.txt 的期望版本。 */
+export function expectedVersion() {
+  try {
+    return readFileSync(VERSION_FILE, 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+/** 当前用户已安装的包版本；没装返回空串。 */
+export function installedVersion() {
+  const { output } = runPowerShell(
+    `(Get-AppxPackage -Name '${PACKAGE_NAME}' | Select-Object -First 1).Version`,
+  )
+  return output.trim()
+}
+
+/**
+ * 安装/升级新式菜单用的 MSIX 包。
+ * 返回 { status, detail }，status 取值：missing-msix / current / installed / untrusted / failed。
+ */
+export function installPackage() {
+  if (!existsSync(MSIX_PATH)) return { status: 'missing-msix', detail: MSIX_PATH }
+
+  const wanted = expectedVersion()
+  const installed = installedVersion()
+  if (installed !== '' && (wanted === '' || installed === wanted)) {
+    return { status: 'current', detail: installed }
+  }
+
+  const { output } = runPowerShell(`Add-AppxPackage -Path '${MSIX_PATH}'`)
+  if (output.includes(UNTRUSTED_HRESULT)) {
+    return { status: 'untrusted', detail: join(NATIVE_DIR, 'trust-cert.bat') }
+  }
+
+  const now = installedVersion()
+  if (now !== '' && (wanted === '' || now === wanted)) return { status: 'installed', detail: now }
+  return { status: 'failed', detail: output || `status=${now || 'none'}` }
+}
+
+/** 卸载新式菜单用的 MSIX 包；返回是否已确认移除。 */
+export function removePackage() {
+  if (installedVersion() === '') return true
+  runPowerShell(`Get-AppxPackage -Name '${PACKAGE_NAME}' | Remove-AppxPackage`)
+  return installedVersion() === ''
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Open with dsh",
+    "description": "Adds an \"Open with dsh\" entry to the Windows Explorer context menu that opens the folder in dsh and starts a new session."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "通过 dsh 打开",
+    "description": "在 Windows 资源管理器的右键菜单里加入“通过 dsh 打开”，一点就在 dsh 中打开对应文件夹并新建会话。"
+  }
+}

package/native/trust-cert.bat

@@ -0,0 +1,3 @@
+@echo off
+rem Ask UAC to run trust-cert.ps1 elevated.
+powershell -NoProfile -ExecutionPolicy Bypass -Command "Start-Process -FilePath powershell.exe -Verb RunAs -ArgumentList '-NoProfile -ExecutionPolicy Bypass -NoExit -File \"%~dp0trust-cert.ps1\"'"

package/native/trust-cert.ps1

@@ -0,0 +1,23 @@
+# Trust the self-signed code-signing certificate that signed DshOpenWith.msix.
+# Must run elevated. Keep this file pure ASCII: PowerShell 5.1 decodes a BOM-less
+# .ps1 with the ANSI code page, so non-ASCII text would be mangled.
+$ErrorActionPreference = 'Stop'
+
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = New-Object Security.Principal.WindowsPrincipal($identity)
+if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+  Write-Host 'ERROR: this script must run as Administrator.'
+  exit 1
+}
+
+$cer = Join-Path $PSScriptRoot 'dsh-open-with.cer'
+if (-not (Test-Path -LiteralPath $cer)) {
+  Write-Host ('ERROR: certificate not found: ' + $cer)
+  exit 1
+}
+
+Import-Certificate -FilePath $cer -CertStoreLocation 'Cert:\LocalMachine\TrustedPeople' | Out-Null
+
+$thumb = (Get-PfxCertificate -FilePath $cer).Thumbprint
+Write-Host ('OK: certificate trusted (LocalMachine\TrustedPeople): ' + $thumb)
+Write-Host 'Windows 11 modern context menu items can now load this package.'

package/native/version.txt

@@ -0,0 +1 @@
+1.0.0.7

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "dsh-explorer-open",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Windows 资源管理器右键菜单里的「通过 dsh 打开」：在文件夹空白处、文件夹或文件上右键，直接在 dsh 中打开该文件夹并新建会话。",
+  "author": "ame-code",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ame-code/dsh-explorer-open.git"
+  },
+  "homepage": "https://github.com/ame-code/dsh-explorer-open#readme",
+  "bugs": {
+    "url": "https://github.com/ame-code/dsh-explorer-open/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "windows",
+    "explorer",
+    "context-menu",
+    "iexplorercommand",
+    "msix"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "scripts": {
+    "test": "node test/client-test.mjs && node test/host-test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib",
+    "native",
+    "assets",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  }
+}