前言¶

DSH 側邊欄插件，把每個工作區文件夾行變成一鍵直達入口。懸停即現 訪達 / Zed / Ghostty 三個圖標，點一下就在本機對應應用中打開該目錄。

核心能力¶

• 行內懸停按鈕：每個 workspace:<id> 側邊欄行右側自動追加三個 16px 圖標按鈕，與原生 ··· 菜單並排，不遮擋原有操作。
• 可用性感知：啓動時請求 /status，只渲染本機真實存在且配置允許的應用按鈕（沒裝 Zed 就不顯示 Zed 按鈕）。
• 中英雙語：跟隨 DSH locale，中文顯示「在訪達中打開」，英文顯示 “Open in Finder”（含 title + aria-label 無障礙標籤）。
• 操作反饋：成功/失敗均有右下角 toast 提示（已在 Finder 中打開 / 打開失敗：…），按鈕在請求期間置灰並脈衝動畫，防止重複點擊。
• 服務端解析路徑：瀏覽器只發送 workspaceId + app，真實目錄由服務端 workspaceRegistry 解析，客戶端無法僞造路徑打開任意目錄。
• 無 shell、無 PATH 查找：統一 execFile('open', [...固定參數])，不存在命令注入面。

安裝與配置¶

安裝¶

dsh plugin --profile web add "github:johnsonspirit/open-with-finder-ide"

安裝後重啓 DSH（dsh web）即生效。

配置¶

插件配置（Config["~standard"] 標準 schema，可缺省，全缺省即三項全開）：

示例——只保留訪達和 Zed：

config:
  finder: true
  zed: true
  ghostty: false

使用方法¶

1. 啓動 DSH，打開任意帶工作區文件夾的側邊欄視圖。
2. 把鼠標懸停到某一工作區行（例如 open-folder ~/src/Misc/open-folder）。
3. 行右側出現三個圖標：笑臉（訪達）/ 方塊 Z（Zed）/ 小幽靈（Ghostty），懸停有中文 tooltip。
4. 單擊圖標 → 對應應用打開該目錄 → 右下角 toast 確認。
5. 若某應用未安裝，對應圖標自動隱藏，無需任何配置。

API 調用¶

基址：/api/dsh-folder-open。全部接口僅限 loopback（127.0.0.1 / ::1 / localhost）。

查詢能力¶

curl http://127.0.0.1:PORT/api/dsh-folder-open/status

返回示例：

{
  "ok": true,
  "mac": true,
  "apps": { "finder": true, "zed": true, "ghostty": true },
  "enabled": { "finder": true, "zed": true, "ghostty": true }
}

打開目錄¶

curl -X POST http://127.0.0.1:PORT/api/dsh-folder-open/open \
  -H 'content-type: application/json' \
  -d '{"workspaceId":"abc123","app":"finder"}'

運行要求與安全¶

運行要求¶

安全設計¶

1. 路徑永不信任客戶端 — workspaceId → path 只走服務端 workspaceRegistry.get()，POST body 里根本沒有 path 字段可供僞造。
2. Loopback 強校驗 — remoteAddress + Host + Origin + Sec-Fetch-Site 四重檢查，局域網其他機器與跨站頁面無法調用。
3. 固定 argv — 所有喚起走 execFile('open', [...])，目錄作爲單個 argv 元素傳遞，不經過 shell。
4. 輸入上限 — body 16 KiB 封頂，workspaceId 限長 80 字符。
5. 能力探測不走 PATH — 只檢查 /Applications 與 ~/Applications 下的固定 *.app，避免 PATH 劫持誤報。

結尾¶

該插件通過服務端解析路徑與 Loopback 校驗，確保了本地喚起的安全性。適合需要在 DeepSeek Harness 中頻繁切換工作區目錄的開發者。更多細節可參考 項目主頁 或 GitHub 倉庫。