dsh-folder-path 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cooper Zhuang
+
+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,158 @@
-# Temporary Holding Version
+# dsh-folder-path
 
-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（DeepSeek Harness）Web 插件：在输入框里**粘贴一个刚从资源管理器 / Finder 复制来的文件夹**时，
+不再尝试把它当成附件上传（原版会显示「上传失败，点击重试」），而是把它的**完整路径**作为文本插进输入框。
+
+- 复制一个文件夹 → `Ctrl+V`（macOS `Cmd+V`）→ 输入框出现 `D:\项目\数据\2026Q1` / `/Users/me/项目/数据`
+- 复制多个文件夹 → 每行一条
+- 普通文本、图片、真实文件的粘贴**完全不受影响**（插件只在粘贴载荷里出现目录时才接管）
+
+## 它解决的是什么问题
+
+浏览器是沙盒：网页 JavaScript 拿不到本地文件的磁盘路径。把一个文件夹粘进网页时，
+浏览器交出的是一个 `size: 0`、`type: ''` 的 `File`——字节不可读，因此 DSH 原版的上传链路必然失败；
+而路径也根本不在粘贴载荷里（`File.name` 只有文件夹名）。
+
+但剪贴板是**进程级**的：运行宿主的那台机器上，剪贴板里此刻装的正是你刚复制的那份文件列表。
+所以本插件由**宿主半边**去读系统剪贴板的文件列表——Windows 走 CF_HDROP，macOS 走 NSPasteboard 的文件 URL——
+再把真实全路径交回浏览器半边。
+
+## 平台要求
+
+Windows（剪贴板经 PowerShell 5.1 的 `System.Windows.Forms` 读取）或 macOS（系统自带 `osascript`）。
+其他平台宿主返回 `unsupported-platform`，粘贴行为退回原版。
+
+## 安装
+
+```sh
+dsh plugin --profile <profile> add dsh-folder-path
+```
+
+把 `<profile>` 换成目标 profile（例如桌面版 `desktop`、`dsh web` 用 `web`）。
+
+也可以从源码目录安装：
+
+```sh
+git clone https://github.com/CooperZhuang/dsh-plugins-cooper-custom.git
+dsh plugin --profile <profile> add ./dsh-plugins-cooper-custom/packages/dsh-folder-path
+```
+
+安装后刷新页面即可。Desktop Beta 2.0.18-beta.1（内核 0.2.1-rc.2）起新增的 bundle 行通常能热挂载，
+宿主不必重启；**更早的版本必须重启 `dsh web`**，不确定时重启一次总是安全的。
+
+验证是否挂上：`dsh --profile <profile> --dump-config` 里应出现 `# == dsh-folder-path` 层。
+
+### 卸载
+
+```sh
+dsh plugin --profile <profile> remove dsh-folder-path
+```
+
+删除后重启宿主一次。
+
+## 兼容性
+
+本包声明的兼容区间是 `engines.dsh: ^0.2.1-rc.2 || ^0.2.2-alpha.2`（Node.js `>=24`）。
+已在 **DSH 0.2.1-rc.2**（npm `@deepseek-ai/dsh` 0.2.1-rc.2）上逐项核对过安装、组合、宿主路由与浏览器半边；
+内核接口一旦变化，最坏结果是插件不再接管粘贴、行为退回原版，而不会破坏原有的粘贴/上传链路。
+本插件只用到内核的这几处：
+
+| 内核接口 | 用途 |
+|---|---|
+| `webServer` 服务：`ctx.inject(['webServer'])` + `ctx.webServer.register({ kind: 'exact', … })` | 宿主半注册那条精确路由 |
+| `ctx.effect` / `ctx.logger` | 路由的挂载与清理、剪贴板探测失败时的告警 |
+| 插件入口的 `name` / `apply(ctx, config)` 形状 | 宿主半的加载方式 |
+| `package.json` 的 `dsh.bundle.patch` 与 `dsh.client.platform` | bundle 补丁层与浏览器半的模块登记 |
+| `exports['./client']` + `window.__ModuleLoader__.load({ id, factory })` | 浏览器半的加载方式 |
+
+插件**不涉及子代理**，所以内核 0.2.1-rc.2 的子代理约定（`startActivation({provider, request})`、Agent Preset）
+不改变它的任何行为。`test/manifest.test.js` 与 `test/client.test.js` 把上面这份清单钉在测试里。
+
+## 使用
+
+1. 在资源管理器（Windows）或 Finder（macOS）里选中一个或多个文件夹，`Ctrl+C`（macOS `Cmd+C`）
+2. 回到 DSH Web 输入框，`Ctrl+V`（macOS `Cmd+V`）
+3. 路径作为文本出现在草稿里；解析失败时右下角出现一条提示，草稿不动
+
+## 工作原理
+
+| 半边 | 位置 | 职责 |
+|---|---|---|
+| Host 半 `lib/index.js` | 宿主进程（`webServer` 服务） | 精确路由 `POST /dsh-folder-path/api/v1/clipboard-paths`：读系统剪贴板的文件列表（Windows CF_HDROP / macOS NSPasteboard）、按浏览器报来的文件夹名匹配、返回真实全路径 |
+| Client 半 `lib/client.js` | 浏览器（`__ModuleLoader__` bundle） | document 捕获阶段拦截 `paste`，只有载荷里含**目录**时才接管；向宿主取路径，再把文本按 DSH 自己的粘贴通路插进 composer |
+
+插入不是直接改 DOM：客户端补发一个只带 `text/plain` 的合成 `paste` 事件，
+走的是 DSH 编辑器**原生的文本粘贴命令**（草稿状态、命令菜单、撤销历史、已有 chip 都不受影响）；
+引擎不允许构造带数据的 `ClipboardEvent` 时，退化为 `document.execCommand('insertText')`。
+
+宿主按平台读剪贴板：Windows 用 PowerShell（`System.Windows.Forms.Clipboard`，输出 **base64(UTF-8 JSON)**，
+中文/空格路径不会被重定向进程的代码页破坏）；macOS 用 `osascript -l JavaScript` 读 NSPasteboard 的
+`public.file-url` 条目，并合并 Finder 的旧格式 `NSFilenamesPboardType` 列表，避免多选文件夹被折叠成一条。
+目录还是文件由宿主进程自己 `stat` 判断。同一时刻的多次粘贴会合并成一次探测。
+
+## 配置
+
+插件的配置写在 profile 的补丁层里（`~/.dsh/profiles/web/cordis.patch.yml` 或本包自带的
+`cordis.patch.yml` 会被 `dsh plugin add` 接入），全部可选：
+
+```yaml
+- insert:
+    - id: folder-path
+      name: dsh-folder-path
+      config:
+        enabled: true          # false = 宿主半边空转（客户端因此不再接管，行为退回原版）
+        timeoutMs: 5000        # 单次剪贴板探测预算
+        powershell: powershell.exe   # 也可用环境变量 DSH_FOLDER_PATH_POWERSHELL 覆盖
+        osascript: /usr/bin/osascript # 也可用环境变量 DSH_FOLDER_PATH_OSASCRIPT 覆盖
+        allowNonLoopback: false      # true = 允许远程浏览器读取宿主机剪贴板（见下）
+```
+
+## 安全边界
+
+- **只读**：路由只读剪贴板，从不打开、复制或上传文件
+- **只接受环回**：默认拒绝非环回对端（`remote-not-supported`）——否则远程浏览器会被喂**宿主机**的路径
+- **同源**：带 `Origin` 的请求必须与 `Host` 一致，否则 403
+- **不猜路径**：宿主报回的文件夹名必须与剪贴板条目对上；对不上就明确失败，绝不返回一个"看起来像"的路径
+- **不缓存**：响应 `cache-control: no-store`
+
+## 已知限制
+
+- **只支持 Windows 与 macOS**。其它平台宿主返回 `unsupported-platform`，客户端给出提示，行为退回原版。
+- **只处理粘贴，不处理拖放**。浏览器拖放载荷里同样没有磁盘路径，本插件不猜；把文件夹拖进窗口仍是原版行为。
+- **远程访问时读不到你的剪贴板**。通过局域网 IP、端口转发或跳板机访问 `dsh web` 时，剪贴板属于**运行宿主的那台机器**。
+  默认直接拒绝；`allowNonLoopback: true` 会读宿主机的剪贴板（只有"浏览器和宿主在同一台机器、但用局域网 IP 打开"时才该打开它）。
+- Windows 依赖 PowerShell 5.1 的 `System.Windows.Forms`；被安全策略挡住时返回 `clipboard-error` 并提示。
+- macOS 依赖系统自带的 `osascript`（读粘贴板不需要 TCC 授权，也不会弹「允许访问剪贴板」）；
+  只认标准文件复制格式（`public.file-url` / `NSFilenamesPboardType`），自造私有剪贴板格式的 App 读不到。
+
+## 开发
+
+```sh
+npm run build   # client/index.js -> lib/client.js（把浏览器半边包成 __ModuleLoader__ bundle）
+npm test        # 语法检查 + 宿主路由 / 浏览器半契约 / 清单契约测试（node --test，无需 DSH 服务器）
+```
+
+浏览器侧调试钩子（devtools 控制台）：
+
+```js
+await __dshFolderPath.probe(['文件夹名'])   // 直接问宿主要路径
+__dshFolderPath.insert(document.querySelector('[contenteditable]'), '文本')   // 直接试插入
+```
+
+改**浏览器半边**后：`npm run build`，然后刷新页面即可，**不必重启宿主**——
+`dsh-client-hmr` 每 500 ms 轮询各客户端产物，重建后重算 revision 并推给页面。
+只有**新增**客户端模块才需要重启宿主（启动时的扫描决定「有哪些客户端模块」）。
+
+改**宿主半边**后：必须**重启宿主进程**（宿主走 Node 的 ESM 缓存，运行中的那份代码不会跟着变）。
+Desktop 版要把应用**完全退出**再打开——关窗口不算退出。
+
+## 致谢
+
+架构参考了同类的 macOS 插件 [jhuanxx44/dsh-paste-path](https://github.com/jhuanxx44/dsh-paste-path)
+（Finder 复制 → 宿主读粘贴板 → Ctrl+V 插路径）：环回/同源校验、宿主侧读取系统剪贴板、
+"宿主属于运行 dsh 的那台机器"这条边界都沿用它的判断；本插件把同一思路落到 Windows 剪贴板，
+并把触发方式改为**粘贴事件驱动的目录识别**（Windows 上无粘贴板变更计数可供廉价轮询）。
+
+## License
+
+MIT

package/README_EN.md

@@ -0,0 +1,179 @@
+# dsh-folder-path
+
+A DeepSeek Harness (DSH) Web plugin: paste a **folder** you just copied in Windows Explorer or macOS
+Finder into the composer (`Ctrl+V` / `Cmd+V`) and get its **absolute path as text**, instead of the
+stock "upload failed" dead end.
+
+- Copy one folder → `Ctrl+V` (`Cmd+V` on macOS) → the draft gets `D:\work\data\2026Q1` or `/Users/me/work/data`
+- Copy several folders → one path per line
+- Ordinary text, images and real files paste exactly as before (the plugin only takes over when the
+  paste payload actually contains a directory)
+
+## The problem it solves
+
+The browser is a sandbox: page JavaScript never sees a local file's disk path. Pasting a folder hands
+the page a `File` with `size: 0` and `type: ''` — its bytes cannot be read, so DSH's upload path must
+fail — and the path itself is not in the payload at all (`File.name` is just the basename).
+
+The clipboard, however, is process-wide: on the machine running the host, it holds exactly the file
+list you just copied. So the **host half** reads the platform clipboard's file list — CF_HDROP on
+Windows, NSPasteboard file URLs on macOS — and hands the real absolute paths back to the browser half.
+
+## Requirements
+
+Windows (the clipboard is read through PowerShell 5.1 `System.Windows.Forms`) or macOS (system
+`osascript`). Other platforms answer `unsupported-platform` and stock paste behaviour applies.
+
+## Install
+
+```sh
+dsh plugin --profile <profile> add dsh-folder-path
+```
+
+Replace `<profile>` with the target profile name (for example `desktop` for the desktop app, `web` for `dsh web`).
+
+From a source checkout:
+
+```sh
+git clone https://github.com/CooperZhuang/dsh-plugins-cooper-custom.git
+dsh plugin --profile <profile> add ./dsh-plugins-cooper-custom/packages/dsh-folder-path
+```
+
+Then refresh the page. Since Desktop Beta 2.0.18-beta.1 (core 0.2.1-rc.2) a newly added bundle row
+is usually hot-mounted, so the host needs no restart; **earlier versions require restarting
+`dsh web`**. Restarting once is always safe when in doubt.
+
+Check it mounted: `dsh --profile <profile> --dump-config` should show a `# == dsh-folder-path` layer.
+
+### Uninstall
+
+```sh
+dsh plugin --profile <profile> remove dsh-folder-path
+```
+
+Restart the host once afterwards.
+
+## Compatibility
+
+This package declares `engines.dsh: ^0.2.1-rc.2 || ^0.2.2-alpha.2` and Node.js `>=24`. It was checked
+item by item against **DSH 0.2.1-rc.2** (npm `@deepseek-ai/dsh` 0.2.1-rc.2): installing, composing,
+the host route and the browser half all work as before. If a kernel interface changes, the worst case is
+that the plugin stops taking over folder pastes and behaviour falls back to stock — the original
+paste/upload path is never broken. The plugin touches exactly this much of the kernel:
+
+| Kernel interface | Used for |
+|---|---|
+| the `webServer` service: `ctx.inject(['webServer'])` + `ctx.webServer.register({ kind: 'exact', … })` | the host half registers its exact route |
+| `ctx.effect` / `ctx.logger` | mounting and cleaning up the route, warning on a failed clipboard probe |
+| the plugin entry's `name` / `apply(ctx, config)` shape | how the host half is loaded |
+| `package.json`'s `dsh.bundle.patch` and `dsh.client.platform` | the bundle patch layer and the browser half's module registration |
+| `exports['./client']` + `window.__ModuleLoader__.load({ id, factory })` | how the browser half is loaded |
+
+The plugin involves **no subagents**, so the kernel 0.2.1-rc.2 subagent convention
+(`startActivation({provider, request})`, Agent Presets) changes nothing for it. `test/manifest.test.js`
+and `test/client.test.js` pin the list above in the test suite.
+
+## Use
+
+1. Select one or more folders in Explorer / Finder and press `Ctrl+C` (`Cmd+C` on macOS)
+2. Return to the DSH Web composer and press `Ctrl+V` (`Cmd+V` on macOS)
+3. The paths appear in the draft; when the host cannot resolve them, a notice appears and the draft is
+   left untouched
+
+## How it works
+
+| Half | Where | Job |
+|---|---|---|
+| Host `lib/index.js` | host process (`webServer`) | exact route `POST /dsh-folder-path/api/v1/clipboard-paths`: read the platform clipboard's file list (CF_HDROP on Windows, NSPasteboard on macOS), match the folder names the browser reported, answer with the real absolute paths |
+| Client `lib/client.js` | browser (`__ModuleLoader__` bundle) | capture-phase `paste` interception, only when the payload contains a directory; asks the host, then inserts the text through DSH's own paste path |
+
+Insertion does not poke the DOM: the client re-dispatches a synthetic `paste` carrying only
+`text/plain`, which reaches the editor's **native text-paste command** (draft state, command menu,
+undo history and existing chips all stay intact). Engines that refuse to construct a `ClipboardEvent`
+with clipboard data fall back to `document.execCommand('insertText')`.
+
+The host reads the clipboard per platform. Windows uses PowerShell
+(`System.Windows.Forms.Clipboard`) and emits **base64(UTF-8 JSON)**, so paths with Chinese characters
+or spaces survive the redirected process's code page. macOS uses `osascript -l JavaScript` to read the
+NSPasteboard's `public.file-url` entries and merges Finder's legacy `NSFilenamesPboardType` list, so a
+multi-selection cannot collapse into one item; directory versus file is decided by the host with
+`stat`. Concurrent pastes share one probe.
+
+## Configuration
+
+Every knob is optional and lives in the profile patch layer (`~/.dsh/profiles/web/cordis.patch.yml`,
+or this package's own `cordis.patch.yml`, which `dsh plugin add` wires in):
+
+```yaml
+- insert:
+    - id: folder-path
+      name: dsh-folder-path
+      config:
+        enabled: true          # false mounts the host half inert (the client then stops taking over)
+        timeoutMs: 5000        # per-probe budget
+        powershell: powershell.exe   # also settable via DSH_FOLDER_PATH_POWERSHELL
+        osascript: /usr/bin/osascript # also settable via DSH_FOLDER_PATH_OSASCRIPT
+        allowNonLoopback: false      # true = let a remote browser read this host's clipboard
+```
+
+## Security boundary
+
+- **Read-only**: the route only reads the clipboard; files are never opened, copied or uploaded
+- **Loopback only** by default (`remote-not-supported`), so a remote browser is never handed the
+  *host machine's* paths
+- **Same-origin**: a request carrying `Origin` must match `Host`, else 403
+- **No guessing**: the reported folder name must match a clipboard entry; otherwise the request fails
+  loudly instead of returning a plausible-looking wrong path
+- **No caching**: `cache-control: no-store`
+
+## Known limitations
+
+- **Windows and macOS only.** Other platforms answer `unsupported-platform` and the client shows a notice.
+- **Paste only, not drag-and-drop.** A drop payload carries no disk path either; this plugin does not
+  guess, so dropping a folder keeps the stock behaviour.
+- **Remote access cannot reach your clipboard.** Over a LAN address, port forward or jump host the
+  clipboard belongs to the machine running the host. That is rejected by default;
+  `allowNonLoopback: true` reads the host's clipboard instead (only sensible when the browser and the
+  host are the same machine reached through a LAN IP).
+- Windows requires PowerShell 5.1 with `System.Windows.Forms`; if policy blocks it the route answers
+  `clipboard-error` and the client explains.
+- macOS uses the system `osascript`; reading the pasteboard needs no TCC grant and raises no
+  "allow clipboard access" prompt. Only the standard copy flavours (`public.file-url`,
+  `NSFilenamesPboardType`) are recognised — an app that puts files on the pasteboard in a private
+  format will not be read.
+
+## Development
+
+```sh
+npm run build   # client/index.js -> lib/client.js (wraps the browser half as a __ModuleLoader__ bundle)
+npm test        # syntax checks + host route / browser-half contract / manifest contract tests
+                # (node --test, no DSH server needed)
+```
+
+Browser-side debugging hooks (devtools console):
+
+```js
+await __dshFolderPath.probe(['folder-name'])   // ask the host directly
+__dshFolderPath.insert(document.querySelector('[contenteditable]'), 'text')
+```
+
+After changing the **browser half**: `npm run build`, then refresh the page — **no host restart
+needed**. `dsh-client-hmr` polls every client bundle every 500 ms, recomputes the revision after a
+rebuild and pushes it to the page. Only **adding** a client module needs a restart (the startup scan
+decides which client modules exist).
+
+After changing the **host half**: you must **restart the host process** (the host goes through Node's
+ESM cache, so the running copy of the code does not change with it). In the Desktop app, quit the app
+completely and reopen it — closing the window is not quitting.
+
+## Credits
+
+The architecture follows the macOS plugin [jhuanxx44/dsh-paste-path](https://github.com/jhuanxx44/dsh-paste-path)
+(copy in Finder → host reads the pasteboard → Ctrl+V inserts the path): its loopback/same-origin
+checks, host-side system-clipboard reads and the "the clipboard belongs to the machine running dsh"
+boundary all carry over. This plugin brings the same idea to the Windows clipboard and triggers on
+the **paste event's directory payload** (Windows offers no cheap pasteboard change counter to poll).
+
+## License
+
+MIT

package/client/index.js

@@ -0,0 +1,306 @@
+/**
+ * `dsh-folder-path` browser half.
+ *
+ * Shipped as the package's `./client` bundle: the DSH client module system
+ * loads it as a `window.__ModuleLoader__.load({ id, factory })` script, calls
+ * `factory(require)`, and mounts the exported plugin (`apply`) into the browser
+ * Cordis tree.
+ *
+ * What it does — one thing, in the capture phase, before the conversation
+ * plugin's Lexical paste command can turn the folder into a doomed upload:
+ *
+ *   * a paste is inspected for entries that are *directories*
+ *     (`webkitGetAsEntry().isDirectory`; the paste payload is a `File` of size 0
+ *     with no bytes to upload, which is why 上传失败 appears today);
+ *   * the pasted folder names go to the host half, which reads the host
+ *     machine's clipboard (Windows file-drop list, macOS NSPasteboard file
+ *     URLs) and answers with the real full paths;
+ *   * those paths are inserted into the composer as plain text by re-dispatching
+ *     a synthetic text/plain paste, so the insertion goes through DSH's own
+ *     composer path (command menu, draft state, undo history) instead of
+ *     poking at the DOM.
+ *
+ * Ordinary pastes — text, images, real files — are never touched: the handler
+ * returns before `preventDefault()` unless a directory is present.
+ */
+
+/** The host route; hand-mirrored from `lib/index.js` (ROUTE_PATH). */
+var ROUTE_PATH = '/dsh-folder-path/api/v1/clipboard-paths'
+
+/** Marks the synthetic events this plugin dispatches, so they are not re-read. */
+var SYNTHETIC = '__dshFolderPathSynthetic'
+
+/** The composer's editable root, as Lexical renders it. */
+var EDITABLE_SELECTOR = '[contenteditable=""],[contenteditable="true"]'
+
+/** How long a failure notice stays on screen. */
+var TOAST_MS = 5000
+
+/**
+ * Split a paste payload into directories and files.
+ *
+ * `webkitGetAsEntry()` is the only reliable directory signal. The
+ * `size === 0 && type === ''` arm is a fallback for engines without the entry
+ * API; it is deliberately not applied when an entry exists, so a genuinely
+ * empty file is never mistaken for a folder.
+ *
+ * @param dataTransfer - the event's clipboard or drag data.
+ * @returns directory basenames and the non-directory files.
+ */
+function classifyPayload(dataTransfer) {
+  var directories = []
+  var files = []
+  var items = dataTransfer.items ? Array.prototype.slice.call(dataTransfer.items) : []
+
+  for (var index = 0; index < items.length; index += 1) {
+    var item = items[index]
+    if (item.kind !== 'file') continue
+
+    var entry = null
+    try {
+      entry = typeof item.webkitGetAsEntry === 'function' ? item.webkitGetAsEntry() : null
+    } catch (error) {
+      entry = null
+    }
+
+    if (entry !== null) {
+      // The entry API answers both questions. Reading the file of a directory is
+      // deliberately skipped: the browser hands over a zero-byte `File` whose
+      // bytes cannot be read, which is the upload failure this plugin exists to
+      // avoid, so there is nothing to forward for it.
+      if (entry.isDirectory === true) {
+        if (entry.name) directories.push(entry.name)
+        continue
+      }
+      var entryFile = null
+      try {
+        entryFile = item.getAsFile()
+      } catch (error) {
+        entryFile = null
+      }
+      if (entryFile !== null) files.push(entryFile)
+      continue
+    }
+
+    var file = null
+    try {
+      file = item.getAsFile()
+    } catch (error) {
+      file = null
+    }
+    if (file === null) continue
+    if (file.size === 0 && file.type === '') {
+      // No entry API (a non-Chromium engine): a zero-byte, type-less item is
+      // the only directory-shaped signal left to go on.
+      if (file.name) directories.push(file.name)
+      continue
+    }
+    files.push(file)
+  }
+
+  return { directories: directories, files: files }
+}
+
+/**
+ * Find the composer root a paste belongs to.
+ *
+ * A paste into anything that is not an editable surface is left alone: the
+ * plugin swallows events it handles, and swallowing a paste it cannot insert
+ * into would silently eat user data.
+ *
+ * @param target - the event target.
+ * @returns the editable root element, or null.
+ */
+function editableRootOf(target) {
+  var candidates = [target, document.activeElement]
+  for (var index = 0; index < candidates.length; index += 1) {
+    var candidate = candidates[index]
+    if (candidate && typeof candidate.closest === 'function') {
+      var root = candidate.closest(EDITABLE_SELECTOR)
+      if (root !== null) return root
+    }
+  }
+  return null
+}
+
+/**
+ * Ask the host half for the full paths behind the pasted folder names.
+ * @param names - directory basenames the browser saw.
+ * @returns the resolved paths (empty when the host could not answer).
+ */
+async function requestPaths(names) {
+  var response = await fetch(ROUTE_PATH, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ names: names }),
+  })
+  if (!response.ok) return { paths: [], reason: 'http-' + String(response.status) }
+  var payload = await response.json()
+  if (payload && payload.ok === true && Array.isArray(payload.paths)) {
+    return { paths: payload.paths, reason: null }
+  }
+  return { paths: [], reason: (payload && payload.reason) || 'unknown' }
+}
+
+/**
+ * Insert plain text through DSH's own paste path.
+ *
+ * A synthetic `paste` carrying only `text/plain` reaches the same Lexical
+ * command a real text paste does, so the draft, command menu and undo history
+ * stay consistent. `execCommand` is the fallback for engines that refuse to
+ * construct a `ClipboardEvent` with clipboard data.
+ *
+ * @param root - the composer's editable root.
+ * @param text - the text to insert.
+ */
+function insertText(root, text) {
+  root.focus({ preventScroll: true })
+  try {
+    var dataTransfer = new DataTransfer()
+    dataTransfer.setData('text/plain', text)
+    var event = new ClipboardEvent('paste', { clipboardData: dataTransfer, bubbles: true, cancelable: true })
+    event[SYNTHETIC] = true
+    root.dispatchEvent(event)
+    if (event.defaultPrevented) return
+  } catch (error) {
+    /* fall through to the DOM insertion below */
+  }
+  document.execCommand('insertText', false, text)
+}
+
+/**
+ * Hand non-directory files back to the composer.
+ *
+ * Copying a folder and files together is legal; the files still belong to the
+ * attachment flow, so they are forwarded as one synthetic file paste after the
+ * paths are in.
+ *
+ * @param root - the composer's editable root.
+ * @param files - the files taken out of the original paste.
+ */
+function forwardFiles(root, files) {
+  if (files.length === 0) return
+  try {
+    var dataTransfer = new DataTransfer()
+    for (var index = 0; index < files.length; index += 1) dataTransfer.items.add(files[index])
+    var event = new ClipboardEvent('paste', { clipboardData: dataTransfer, bubbles: true, cancelable: true })
+    event[SYNTHETIC] = true
+    root.dispatchEvent(event)
+  } catch (error) {
+    /* the paths are the point; a failed forward must not undo them */
+  }
+}
+
+/**
+ * Failure copy for a host answer.
+ * @param reason - the host's reason code.
+ * @returns the message to show.
+ */
+function failureText(reason) {
+  if (reason === 'unsupported-platform') return '当前宿主系统不支持读取剪贴板里的文件夹路径（仅支持 Windows / macOS）'
+  if (reason === 'remote-not-supported') return '当前页面不在运行 dsh web 的这台机器上，读不到这台机器的剪贴板'
+  if (reason === 'clipboard-error') return '读取剪贴板失败，没能解析文件夹的完整路径'
+  if (reason === 'no-match') return '剪贴板里的内容与粘贴的文件夹不一致，没能解析完整路径'
+  return '没能解析文件夹的完整路径（宿主未响应）'
+}
+
+/**
+ * Show a short-lived notice above the composer.
+ * @param message - the text to show.
+ */
+function toast(message) {
+  try {
+    var element = document.createElement('div')
+    element.textContent = message
+    element.setAttribute('data-dsh-folder-path-toast', '')
+    element.style.cssText =
+      'position:fixed;left:50%;bottom:96px;transform:translateX(-50%);z-index:2147483000;' +
+      'max-width:70vw;padding:8px 14px;border-radius:10px;background:rgba(28,28,30,0.92);color:#fff;' +
+      'font-size:13px;line-height:1.45;box-shadow:0 6px 24px rgba(0,0,0,0.28);pointer-events:none;'
+    document.body.appendChild(element)
+    setTimeout(function () {
+      element.remove()
+    }, TOAST_MS)
+  } catch (error) {
+    /* a missing notice must never break the paste */
+  }
+}
+
+/**
+ * Build the browser-half plugin from the bundle's `require`.
+ * @param require - the module system's synchronous require.
+ * @returns the plugin's `apply`.
+ */
+function createPlugin(require) {
+  /**
+   * Resolve the pasted folders and put their paths in the composer.
+   * @param root - the composer's editable root.
+   * @param directories - the pasted directory basenames.
+   * @param files - the non-directory files from the same paste.
+   */
+  async function resolveAndInsert(root, directories, files) {
+    var result
+    try {
+      result = await requestPaths(directories)
+    } catch (error) {
+      result = { paths: [], reason: 'host-unreachable' }
+    }
+    if (result.paths.length === 0) {
+      toast(failureText(result.reason))
+      forwardFiles(root, files)
+      return
+    }
+    if (!root.isConnected) {
+      toast('输入框已经关闭，路径没有插入：' + result.paths.join('、'))
+      return
+    }
+    insertText(root, result.paths.join('\n'))
+    forwardFiles(root, files)
+  }
+
+  /**
+   * Capture-phase paste handler: intercepts directory pastes only.
+   * @param event - the paste event.
+   */
+  function onPaste(event) {
+    if (event[SYNTHETIC] === true) return
+    if (!event.clipboardData) return
+
+    var payload = classifyPayload(event.clipboardData)
+    if (payload.directories.length === 0) return
+
+    var root = editableRootOf(event.target)
+    if (root === null) return
+
+    event.preventDefault()
+    event.stopPropagation()
+    void resolveAndInsert(root, payload.directories, payload.files)
+  }
+
+  /**
+   * Mount the listener; the returned plugin is applied by the client runner.
+   * @param ctx - browser Cordis context.
+   */
+  function apply(ctx) {
+    document.addEventListener('paste', onPaste, true)
+    ctx.effect(
+      function () {
+        return function () {
+          document.removeEventListener('paste', onPaste, true)
+        }
+      },
+      'dsh-folder-path: paste listener',
+    )
+
+    // Troubleshooting hook: the same resolution the paste path uses, callable
+    // from the devtools console (`await __dshFolderPath.probe(['name'])`).
+    window.__dshFolderPath = {
+      route: ROUTE_PATH,
+      probe: requestPaths,
+      insert: insertText,
+      classify: classifyPayload,
+    }
+  }
+
+  return { apply: apply }
+}