前言¶

用 DeepSeek Harness（DSH）做智能体开发时，Web 侧栏里的工作区通常要在界面里手动登记，或改 workspace.json。如果你已经在 Windows 资源管理器里定位到项目目录，再切回浏览器登记，步骤会重复且容易打断节奏。社区插件 dsh-folder-launcher（维护者 snnnnke）面向「外部来源传入文件夹路径、在运行中的 DSH Web 里打开为工作区」这一需求：右键文件夹即可登记，且不必手改配置文件。下面介绍它的组成、安装方式与使用注意。

这是什么¶

dsh-folder-launcher 是 DSH 的客户端类插件：接收来自外部的文件夹路径，通过 DSH 自带的 workspaceRegistry 注册，使路径出现在 正在运行 的 DSH Web 侧栏中。仓库说明为：A dsh plugin that receives folder paths from external sources and opens them as workspaces。

实现上分为两部分：

• 主机插件：随 dsh web 加载，在本地提供受保护的 HTTP 路由。
• 按用户的 Explorer 集成（Windows）或 Node CLI（Linux/macOS 及脚本）：把路径 POST 给主机插件。

无需管理员权限、无需重启已运行的 DSH 进程、无需编辑 workspace.json。DSH 主机本身要求 Node 22；Explorer 脚本兼容 Windows 7/8/10/11（PowerShell 2.0 语法），但 DSH 未必能在 Windows 7 上运行。

核心功能¶

工作区注册方式¶

插件调用 ctx.workspaceRegistry.create(path)，与 DSH Web 侧栏的正常工作区展示一致，而不是绕过注册表直接改文件。

本地 loopback 接口¶

外部启动器不依赖浏览器 Cookie：通过仅监听 loopback 的路由，并用本地 bearer token 鉴权。发现文件默认位于 $DSH_HOME（Windows 上一般为 %USERPROFILE%\.dsh）：

$DSH_HOME/folder-launcher/state.ini   # pid / port / origin / startedAt
$DSH_HOME/folder-launcher/token       # 32-byte random hex token

Windows 资源管理器右键¶

流程概览：

Explorer 右键
   │  wscript.exe（无控制台闪窗）
   ▼
explorer/dsh-folder-launcher.ps1
   │  读取 state.ini + token
   │  POST /dsh-folder-launcher/add  { "path": "..." }
   ▼
dsh-folder-launcher 主机插件
   │  bearer token + 仅 loopback + 拒绝 Origin
   │  workspaceRegistry.create(path)
   ▼
侧栏出现新工作区

菜单项文案为 Add to DSH Web，可对文件夹、文件夹空白处或驱动器使用。若 DSH Web 未运行，启动器会直接启动 dsh web（无确认），并在后台等待插件就绪后再执行添加；重 profile 下 DSH 可能需要一两分钟，Explorer 操作不会阻塞。可通过 %LOCALAPPDATA%\dsh-folder-launcher\config.ps1 中的 StartWebIfMissing 开关该行为。

Windows 11 上经典注册表动词在 Show more options 下；按 Shift+F10 可直接打开经典菜单。

跨平台 CLI¶

仓库提供 Node CLI，便于在 Linux/macOS 文件管理器自定义动作或脚本中调用：

node .\bin\dsh-folder-launcher.mjs add "D:\Code\my project"
node .\bin\dsh-folder-launcher.mjs health
node .\bin\dsh-folder-launcher.mjs state

Linux/macOS 示例：

node /path/to/dsh-folder-launcher/bin/dsh-folder-launcher.mjs add %f

安全边界（本地路由）¶

本地路由在 DSH 浏览器 /api 防护之外，自行校验：

1. 仅 loopback 来源（127.0.0.0/8、::1 或 IPv4-mapped loopback）。
2. Bearer token（持久化于 $DSH_HOME/folder-launcher/token）。
3. 带 Origin 头的请求返回 403。
4. 请求体上限 16 KiB，仅 application/json。
5. 路径须为存在且绝对的目录；注册经 workspaceRegistry（realpath 规范化）。

威胁模型侧重浏览器/CSRF，不防同用户权限下的本地恶意程序。若 DSH 用 --host 绑定非 loopback 地址，勿经 LAN IP 调用该路由（会被拒绝）；默认 dsh web 绑定 127.0.0.1 为支持配置。

说明：DSH 核心没有官方交互式终端 TUI；本仓库已移除仅打开终端、不启动 DSH 的旧菜单项，避免误导。

安装与启用¶

插件版本在 package.json 中为 0.1.0，DSH 引擎要求 >=0.2.1-rc.3 <0.3.0-0。安装分三步：DSH 插件、重启 Web、Explorer 菜单（仅 Windows 需要菜单脚本）。

1. 安装 DSH 插件¶

在 PowerShell 中执行（带版本标签）：

dsh plugin --profile web add github:snnnnke/dsh-folder-launcher#v0.1.0

尚无 tag 时使用默认分支：

dsh plugin --profile web add github:snnnnke/dsh-folder-launcher

本地开发时可指向目录：

dsh plugin --profile web add file:D:\path\to\dsh-folder-launcher

dsh plugin add github:... 只安装插件，不会安装资源管理器菜单。

2. 重启 dsh web¶

停止当前进程（Ctrl+C）后重新启动：

dsh web

确认插件已发布状态：

Get-Content "$env:USERPROFILE\.dsh\folder-launcher\state.ini"

3. 安装 Explorer 右键菜单（Windows）¶

菜单安装脚本在仓库根目录的 install-context-menu.ps1（调用 explorer\install.ps1）。需要先取得完整仓库（克隆或 GitHub Code → Download ZIP 解压），在普通 PowerShell（不要提升为管理员）中执行，例如：

git clone https://github.com/snnnnke/dsh-folder-launcher.git
cd dsh-folder-launcher
powershell -ExecutionPolicy Bypass -File .\install-context-menu.ps1

或使用解压后的完整路径：

powershell -ExecutionPolicy Bypass -File "C:\your-clone\dsh-folder-launcher\install-context-menu.ps1"

安装器仅写入当前用户 HKCU 下的 shell 项，并将脚本复制到 %LOCALAPPDATA%\dsh-folder-launcher\；克隆目录之后可删除。ZIP 用户解压后于根目录运行同一脚本即可。

典型用法¶

1. 完成插件安装并重启 dsh web；Windows 用户再完成菜单安装。
2. 在资源管理器中右键目标文件夹、空白处或驱动器，选择 Add to DSH Web。
3. 在 DSH Web 侧栏查看新出现的工作区；若此前未运行 Web，等待后台启动与注册完成即可。

卸载菜单（在持有仓库脚本的路径下）：

powershell -ExecutionPolicy Bypass -File .\explorer\uninstall.ps1
powershell -ExecutionPolicy Bypass -File .\explorer\uninstall.ps1 -RemoveData

移除插件：

dsh plugin --profile web remove dsh-folder-launcher

之后需再次重启 dsh web。

适用场景与注意¶

适合：经常在 Windows 资源管理器中切换项目目录、希望一键把目录挂到已运行的 DSH Web 工作区列表的开发者；或在 Linux/macOS 上通过文件管理器自定义动作调用 CLI 的用户。

注意：

• 插件在当前 dsh web 进程的权限与环境中执行；安装前请阅读源码与 MIT 许可证，自行评估是否满足环境要求。
• 社区插件目录 skillhub.cn 与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文仅介绍社区维护的客户端集成方式。
• 保管好 $DSH_HOME 与 folder-launcher/token，避免 token 泄露导致本机 loopback 接口被滥用。

结尾¶

dsh-folder-launcher 把「选文件夹 → 登记 DSH Web 工作区」收成资源管理器右键或一条 CLI，并在 Web 未运行时可选自动拉起 dsh web，减少手改配置与重复切窗。

• 目录页：https://www.skillhub.cn/plugins/snnnnke/dsh-folder-launcher
• 源码与完整说明：https://github.com/snnnnke/dsh-folder-launcher