dsh-folder-path 0.0.0-stage → 0.2.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,161 @@
-# 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   # tsc: src/index.ts -> lib/index.js，client/index.ts -> .client-build/index.js；再包成 lib/client.js
+npm test        # 先 build，再跑宿主路由 / 浏览器半契约 / 清单契约测试（node --test，无需 DSH 服务器）
+```
+
+宿主半边源码在 `src/index.ts`（TypeScript，`lib/index.js` 与 `lib/types/` 是 tsc 产物，随仓库提交）；
+浏览器半边是 `client/index.ts`（`.client-build/index.js` 是 tsc 产物），由构建脚本包成 `lib/client.js`。
+
+浏览器侧调试钩子（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.ts -> .client-build/index.js -> lib/client.js (wraps the browser half as a __ModuleLoader__ bundle)
+npm test        # builds both halves, then 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/globals.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ambient declarations for the browser half.
+ *
+ * `client/index.ts` is a classic script (it has no imports or exports), so the
+ * bundle wrapper in `scripts/build-client.mts` can embed it inside a
+ * `window.__ModuleLoader__.load({ id, factory })` factory unchanged. The DOM
+ * types come from the `DOM` lib in `tsconfig.client.json`; only the two
+ * page globals this plugin defines or consumes are declared here.
+ */
+
+/** The troubleshooting hook the browser half installs on `window`. */
+interface FolderPathDebugHook {
+  /** The host route the plugin calls. */
+  route: string
+  /** Ask the host for the full paths behind these folder names. */
+  probe(names: string[]): Promise<{ paths: string[]; reason: string | null }>
+  /** Insert text through DSH's own paste path. */
+  insert(root: HTMLElement, text: string): void
+  /** Split a paste payload into directories and files. */
+  classify(dataTransfer: DataTransfer): { directories: string[]; files: File[] }
+}
+
+interface Window {
+  /** The DSH client module system; the bundle wrapper registers through it. */
+  __ModuleLoader__: {
+    load(registration: { id: string; factory: (require: (id: string) => unknown) => unknown }): void
+  }
+  /** Installed by `apply` so the devtools console can drive the plugin. */
+  __dshFolderPath?: FolderPathDebugHook
+}