fish-dock-plugin-filemgr 0.0.0-stage → 1.0.5

package/README.md

@@ -1,3 +1,62 @@
-# 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.
+# 文件管理
+
+把 FISH Dock 变成随手可用的文件工作台：左边逛目录、右边看内容，中间还能把常用文件先「暂存」起来，随时拖进别的程序。
+
+## 功能
+
+### 目录浏览 + 预览
+
+- **目录浏览**：从磁盘根目录、用户目录、桌面 / 文档 / 下载逐层进入；支持把文件 / 文件夹直接拖进面板。
+- **预览**：Markdown 渲染、图片（PNG / JPEG / GIF / WebP / BMP / AVIF / ICO / SVG）、Office 文本抽取（docx 段落与标题、xlsx 多工作表、pptx 每页文字，原生解析 OOXML，不需要装 Office）、代码高亮行号、纯文本与二进制兜底。
+- **上下并列**：上半是文件夹浏览器（面包屑 + 列表 + 上一级 / 刷新 / 常用文件夹 / 固定），下半是预览；中间分隔条可拖动调高，高度会被记住。
+- **框选与拖入暂存**：在列表里拖出选框可批量选中（Ctrl / Shift 点选切换），选中项直接拖到左侧暂存区即批量加入；拖到一半拖出列表会自动从「框选」切到「搬运」。
+- **常用文件夹**：记住打开过的目录，浮层里快速跳转；可把目录「固定」到最上面。
+
+### 选择文件夹
+
+「打开文件夹」默认调用 **Windows 原生文件夹选择框**（`pick-folder.ps1` + IFileOpenDialog），选完直接进入该目录。
+
+宿主原本会在系统对话框抢走焦点时自动收起设置面板。插件只在**弹出对话框的那一刻**调用 `bridge.js` 的 `hold(true)`，选完（或取消/报错）立刻在 `finally` 里 `hold(false)` 放开——平时浏览、拖放都不锁，点面板外面照常能关。
+
+宿主没有 `fish:hold` 能力（官方发行版 ≤ v1.2.3）时，插件自动回落到**内置自绘选择器**（用后端 `preview.tree` 逐层浏览），功能完整，只是不锁面板：
+
+| 宿主 | 「打开文件夹」 | 面板锁定 |
+|---|---|---|
+| 自行编译、带 `fish:hold` 的宿主 | Windows 原生对话框 | 仅对话框期间临时锁定 |
+| 官方发行版（≤ v1.2.3） | 内置选择器 | 不锁定 |
+
+宿主侧要支持这条路，需要三处改动（都已在 `FISH-Dock` 上游以补丁形式验证过）：
+
+1. `sdk/browser/bridge.js` 暴露 `hold(on)` → `parent.postMessage({type:'fish:hold', ticket, on}, '*')`
+2. `Wakuwaku/src/pet/extension-page.js` 收 `fish:hold` 写入 `record.hold`，并新增 `onHold(record, on)` 回调；`park()` / `enter()` / `retire()` 各自同步
+3. `Wakuwaku/src/pet/settings.js` 维护 `pluginHold` 标志，`onBlur` 判定里加 `!pluginHold`
+
+只改插件包、不重编译宿主时，插件自动走内置选择器，功能完整不缺。
+
+### 文件暂存（中转站）
+
+- 拖入文件或文件夹即加入暂存区，也可以右键 / 按钮添加。
+- **分组**：暂存区支持多个分组标签，点击切换，标签可折叠；删除分组只走标签右侧的 ×。
+- **拖出**：把暂存项直接拖到桌面、资源管理器、微信等外部程序。
+- 复制路径、复制为文件、多选批量、去重、清空，偏好持久化。
+
+## 说明
+
+- 只读取路径白名单内的文件，路径解析后必须落在允许的根目录之下；UNC 路径一律拒绝。
+- 「打开文件夹」在支持 `fish:hold` 的宿主上会短暂启动系统 PowerShell 调起 Windows 原生文件夹对话框（`pick-folder.ps1`），用于拿到用户亲手选择的路径；不加 `fish:hold` 的宿主上不会启动子进程，走内置选择器。除此之外不启动任何子进程。
+- 页面运行在宿主沙箱里（`default-src 'none'`），PDF 与音视频不做内联播放，会提示用系统程序打开。
+- 不发起网络请求。
+
+## 存储
+
+偏好（布局、最近打开、额外根目录、暂存分组）保存在插件命名空间的 `config/prefs.json`。
+
+## 开发
+
+```bash
+# 本地暂存（模拟官方 tools/stage-development.mjs 的产出）
+node _stage_filemgr.mjs
+# 产物
+#   dist/filemgr.fish-plugin
+#   _stage/filemgr/   ← 可直接用 FISH Dock 的「从文件安装」装上验证
+```

package/bridge.js

@@ -0,0 +1,53 @@
+// 插件浏览器 SDK：只连接父页面，所有业务调用由票据锁定当前插件。
+;(function () {
+  const ticket = location.pathname.split('/')[1]
+  let sequence = 0
+  const pending = new Map()
+  window.addEventListener('message', event => {
+    const row = event.data
+    if (event.source !== parent || !row || row.ticket !== ticket) return
+    if (row.type === 'fish:theme') {
+      const palette = row.colors || {}
+      for (const [name, value] of Object.entries(palette)) if (/^--dock-[a-z-]+$/.test(name) && typeof value === 'string' && /^(#[a-f\d]{3,8}|rgba?\([\d.,%\s]+\))$/i.test(value)) document.documentElement.style.setProperty(name, value)
+      document.documentElement.dataset.dockTheme = row.mode === 'light' ? 'light' : 'dark'
+      const title = document.getElementById('title')
+      if (title && typeof row.title === 'string') title.textContent = row.title
+      return
+    }
+    if (row.type !== 'fish:result') return
+    const waiter = pending.get(row.id)
+    if (!waiter) return
+    pending.delete(row.id); clearTimeout(waiter.timer)
+    if (row.error) waiter.reject(new Error(row.error)); else waiter.resolve(row.result)
+  })
+  function call(method, params = {}) {
+    if (pending.size >= 32) return Promise.reject(new Error('插件页面请求过多，请稍后重试'))
+    const id = ++sequence
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); reject(new Error('插件页面请求超时')) }, 20000)
+      pending.set(id, { resolve, reject, timer })
+      parent.postMessage({ type: 'fish:call', ticket, id, method, params }, '*')
+    })
+  }
+  let layout = 'single'
+  function reportLayout() {
+    const main = document.querySelector('main') || document.body
+    if (!main) return
+    const height = Math.ceil(main.getBoundingClientRect().height)
+    if (height > 0) parent.postMessage({ type:'fish:layout', ticket, height, layout }, '*')
+  }
+  function setLayout(value) {
+    if (!['single','double'].includes(value)) return
+    layout = value
+    requestAnimationFrame(reportLayout)
+  }
+  function observeLayout() {
+    parent.postMessage({ type: 'fish:ready', ticket }, '*')
+    const main = document.querySelector('main') || document.body
+    if (!main || typeof ResizeObserver === 'undefined') return
+    new ResizeObserver(reportLayout).observe(main)
+  }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', observeLayout, { once: true }); else observeLayout()
+  parent.postMessage({ type: 'fish:ready', ticket }, '*')
+  Object.defineProperty(window, 'FishDock', { value: Object.freeze({ call, setLayout }), writable: false, configurable: false })
+})()

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "fish-dock-plugin-filemgr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.5",
+  "description": "FISH Dock 文件管理插件：目录浏览 + 文件预览（Markdown / 图片 / Office / 代码）+ 文件暂存中转站，兼容 FISH Dock v1.2.3 及更早官方发行版。",
+  "type": "module",
+  "files": [
+    "plugin.json",
+    "README.md",
+    "bridge.js",
+    "plugins"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "fish-dock",
+    "fishdock",
+    "plugin",
+    "file-manager",
+    "file-preview",
+    "markdown",
+    "stash",
+    "windows"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jassdingk/fish-dock-plugin-filemgr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jassdingk/fish-dock-plugin-filemgr/issues"
+  },
+  "homepage": "https://github.com/jassdingk/fish-dock-plugin-filemgr#readme",
+  "author": "jassdingk",
+  "license": "MIT",
+  "os": [
+    "win32"
+  ]
+}

package/plugin.json

@@ -0,0 +1,47 @@
+{
+  "schema": 1,
+  "id": "jassdingk.filemgr",
+  "name": "文件管理",
+  "version": "1.0.5",
+  "hostApi": 1,
+  "platforms": [
+    "windows-x86_64"
+  ],
+  "storage": {
+    "directory": ".plugin.jassdingk.filemgr",
+    "dataSchema": 1
+  },
+  "backend": {
+    "runtime": "node",
+    "entry": "plugins/filemgr/backend.mjs"
+  },
+  "capabilities": [
+    "storage"
+  ],
+  "pages": [
+    {
+      "id": "main",
+      "title": "文件管理",
+      "entry": "plugins/filemgr/page.html"
+    }
+  ],
+  "files": {
+    "bridge.js": "f38f93994e3cb2b71f2ff1810b3f68fb42f4261550f8ab01b0bfa3eecd5f94ee",
+    "package.json": "7e9124508cc113f5039ce514573a5f8f280faf9392e4677d30bb144c55351e5c",
+    "plugins/filemgr/backend.mjs": "b448aa688ff11f2abc4c5281b4714646ed6c384473d873cfe431a8e64b066d26",
+    "plugins/filemgr/clip.ps1": "b0a32fca35cf2d25133338f46e20a0db20d78c5bb6b5c2aab899998bfbd6c6ab",
+    "plugins/filemgr/dock.css": "e795214dd39de3b473ac0b1a7b79f6922a88c761fca4d3ea4da8fd9b60188bcf",
+    "plugins/filemgr/filemgr.css": "16c621471133d29c6942781bedf86e0a4de806865ff004b666bcad8b1929434e",
+    "plugins/filemgr/FolderPicker.ps1": "4b7f86c543e06fd8f93fa5d8002997d944c8189cb0ae031bedf864ea89196427",
+    "plugins/filemgr/page.css": "0801a05b5148cd091a68957beac21cc982a7818ef4707cd06fd11b20adbc7765",
+    "plugins/filemgr/page.html": "3cfda31be29cd23b1e0f7f6004b6c03522c3526b78f9df4711e320962a660831",
+    "plugins/filemgr/page.js": "282f11d803ddc8bb87a0a99d8af68315f4ff7304672072da838a07a47c5cdc62",
+    "plugins/filemgr/pick-files.ps1": "88bff92d9a2e5b69e9411bb372441ff0b86899b7f5b31f5ed8d154c4f6fc2f37",
+    "plugins/filemgr/pick-folder.ps1": "ff031c14df32149c1c80c7ab6a21710c1a68e823e96e3068c458a60902ae3b6f",
+    "plugins/filemgr/preview.mjs": "a5596e77180fe7928443244a0148b6d3ea8381a1f886ee01f9a08be038c7ee80",
+    "plugins/filemgr/sdk.mjs": "76b052b8d99ff6b6b0b149aee7479d1129bb248a959625642282184978065f38",
+    "plugins/filemgr/stash.css": "fce2aaa13a86dbd7675b685c533f0bb916c7e610fc612a3ade660c67069f5662",
+    "plugins/filemgr/stash.mjs": "c33cea6b845a3847950d26a10b9aba1ef68d39b1f9fc423b23055dead7638866",
+    "README.md": "e9fb4ca9831b778a1d530b67518fcaf2b42cf02494b9d68deaad16bf2b947687"
+  }
+}

package/plugins/filemgr/FolderPicker.ps1

@@ -0,0 +1,260 @@
+# Windows 原生文件夹/文件选择对话框的 C# 实现（IFileOpenDialog）。
+# 由 pick-folder.ps1 / pick-files.ps1 通过 Add-Type -TypeDefinition 编译，避免依赖 .cs 文件。
+$FolderPickerSource = @'
+// Windows 原生"选择文件夹"对话框（IFileOpenDialog + FOS_PICKFOLDERS）。
+// 与 FISH Dock 宿主 paper.rs:588 用的是同一个 COM 接口，所以外观和系统资源管理器
+// 的"选择文件夹"完全一致，而不是 WinForms 那棵 1995 年的老树。
+using System;
+using System.Runtime.InteropServices;
+
+namespace FishDockPick
+{
+    [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"),
+     InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    internal interface IFileDialog
+    {
+        [PreserveSig] int Show(IntPtr parent);
+        void SetFileTypes(uint c, IntPtr rg);
+        void SetFileTypeIndex(uint i);
+        void GetFileTypeIndex(out uint i);
+        void Advise(IntPtr e, out uint c);
+        void Unadvise(uint c);
+        void SetOptions(uint o);
+        void GetOptions(out uint o);
+        void SetDefaultFolder(IShellItem si);
+        void SetFolder(IShellItem si);
+        void GetFolder(out IShellItem si);
+        void GetCurrentSelection(out IShellItem si);
+        void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string name);
+        void GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string name);
+        void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string title);
+        void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string text);
+        void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string label);
+        void GetResult(out IShellItem si);
+        void AddPlace(IShellItem si, int fdap);
+        void SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string ext);
+        void Close(int hr);
+        void SetClientGuid(ref Guid guid);
+        void ClearClientData();
+        void SetFilter(IntPtr filter);
+    }
+
+    [ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"),
+     InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    internal interface IShellItem
+    {
+        void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+        void GetParent(out IShellItem parent);
+        void GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string name);
+        void GetAttributes(uint sfgaoMask, out uint sfgaoAttribs);
+        void Compare(IShellItem psi, uint hint, out int order);
+    }
+
+    [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")]
+    internal class FileOpenDialog { }
+
+    // IFileOpenDialog — 多选文件需要这个接口（继承 IFileDialog，多了 GetResults）。
+    [ComImport, Guid("d57c7288-d4ad-4768-be02-9d969532d960"),
+     InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    internal interface IFileOpenDialog
+    {
+        [PreserveSig] int Show(IntPtr parent);
+        void SetFileTypes(uint c, IntPtr rg);
+        void SetFileTypeIndex(uint i);
+        void GetFileTypeIndex(out uint i);
+        void Advise(IntPtr e, out uint c);
+        void Unadvise(uint c);
+        void SetOptions(uint o);
+        void GetOptions(out uint o);
+        void SetDefaultFolder(IShellItem si);
+        void SetFolder(IShellItem si);
+        void GetFolder(out IShellItem si);
+        void GetCurrentSelection(out IShellItem si);
+        void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string name);
+        void GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string name);
+        void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string title);
+        void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string text);
+        void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string label);
+        void GetResult(out IShellItem si);
+        void AddPlace(IShellItem si, int fdap);
+        void SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string ext);
+        void Close(int hr);
+        void SetClientGuid(ref Guid guid);
+        void ClearClientData();
+        void SetFilter(IntPtr filter);
+        void GetResults(out IShellItemArray ppenum);
+        void GetSelectedItems(out IShellItemArray ppsai);
+    }
+
+    [ComImport, Guid("b63ea76d-1f85-456f-a19c-48159efa858b"),
+     InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    internal interface IShellItemArray
+    {
+        void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+        void GetPropertyStore(int flags, ref Guid riid, out IntPtr ppv);
+        void GetPropertyDescriptionList(IntPtr keyType, ref Guid riid, out IntPtr ppv);
+        void GetAttributes(uint AttribFlags, uint sfgaoMask, out uint psfgaoAttribs);
+        void GetCount(out uint pdwNumItems);
+        void GetItemAt(uint dwIndex, out IShellItem ppsi);
+        void EnumItems(out IntPtr ppenumShellItems);
+    }
+
+    public static class FolderPicker
+    {
+        private const uint FOS_PICKFOLDERS = 0x20;
+        private const uint FOS_FORCEFILESYSTEM = 0x40;
+        private const uint FOS_PATHMUSTEXIST = 0x800;
+        private const uint FOS_ALLOWMULTISELECT = 0x200;
+        private const uint SIGDN_FILESYSPATH = 0x80058000;
+        private const int ERROR_CANCELLED = unchecked((int)0x800704C7);
+
+        [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+        private static extern void SHCreateItemFromParsingName(
+            [MarshalAs(UnmanagedType.LPWStr)] string pszPath,
+            IntPtr pbc,
+            ref Guid riid,
+            [MarshalAs(UnmanagedType.Interface)] out IShellItem ppv);
+
+        [DllImport("ole32.dll")]
+        private static extern int CoInitializeEx(IntPtr pvReserved, uint dwCoInit);
+
+        [DllImport("ole32.dll")]
+        private static extern void CoUninitialize();
+
+        [DllImport("user32.dll")]
+        private static extern IntPtr GetForegroundWindow();
+
+        [DllImport("user32.dll")]
+        private static extern bool SetForegroundWindow(IntPtr hWnd);
+
+        [DllImport("user32.dll")]
+        private static extern bool AllowSetForegroundWindow(int dwProcessId);
+
+        // 只初始化 COM 和创建对话框对象，不弹窗——供自检用。
+        public static string Selftest()
+        {
+            int hr = CoInitializeEx(IntPtr.Zero, 2 /* APARTMENTTHREADED */);
+            try
+            {
+                IFileDialog dlg = (IFileDialog)new FileOpenDialog();
+                uint opts;
+                dlg.GetOptions(out opts);
+                dlg.SetOptions(opts | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_PATHMUSTEXIST);
+                dlg.SetTitle("选择文件夹");
+                return "COM_OK hr=0x" + hr.ToString("X8");
+            }
+            finally
+            {
+                if (hr >= 0) CoUninitialize();
+            }
+        }
+
+        public static string Pick(string initial, string title)
+        {
+            int hr = CoInitializeEx(IntPtr.Zero, 2 /* APARTMENTTHREADED */);
+            try
+            {
+                IFileDialog dlg = (IFileDialog)new FileOpenDialog();
+                uint opts;
+                dlg.GetOptions(out opts);
+                dlg.SetOptions(opts | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_PATHMUSTEXIST);
+
+                if (!string.IsNullOrEmpty(title)) dlg.SetTitle(title);
+
+                if (!string.IsNullOrEmpty(initial))
+                {
+                    try
+                    {
+                        Guid iid = new Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe");
+                        IShellItem folder;
+                        SHCreateItemFromParsingName(initial, IntPtr.Zero, ref iid, out folder);
+                        if (folder != null) dlg.SetFolder(folder);
+                    }
+                    catch { /* 起始目录不存在就退回系统默认 */ }
+                }
+
+                // 关键：本进程是被宿主当子进程拉起来的、且宿主页面还是隐藏窗口，
+                // 系统默认会把对话框排在后面，用户看到的是"点了没反应"。
+                // 先让操作系统允许本进程抢前台，再 Show 时把父窗口设为 NULL，
+                // 弹出来之后主动 SetForegroundWindow，保证一定浮在最上面。
+                AllowSetForegroundWindow(-1 /* ASFW_ANY */);
+
+                int show = dlg.Show(IntPtr.Zero);
+                if (show == ERROR_CANCELLED || show != 0) return null;
+
+                IShellItem item;
+                dlg.GetResult(out item);
+                if (item == null) return null;
+
+                string path;
+                item.GetDisplayName(SIGDN_FILESYSPATH, out path);
+                return path;
+            }
+            finally
+            {
+                if (hr >= 0) CoUninitialize();
+            }
+        }
+
+        /// <summary>
+        /// 弹出多选文件对话框（无 FOS_PICKFOLDERS，加 FOS_ALLOWMULTISELECT）。
+        /// 返回选中的路径数组，取消返回空数组。
+        /// </summary>
+        public static string[] PickFiles(string initial, string title)
+        {
+            int hr = CoInitializeEx(IntPtr.Zero, 2 /* APARTMENTTHREADED */);
+            try
+            {
+                var dlg = (IFileOpenDialog)new FileOpenDialog();
+                uint opts;
+                dlg.GetOptions(out opts);
+                dlg.SetOptions(opts | FOS_FORCEFILESYSTEM | FOS_PATHMUSTEXIST | FOS_ALLOWMULTISELECT);
+
+                if (!string.IsNullOrEmpty(title)) dlg.SetTitle(title);
+
+                if (!string.IsNullOrEmpty(initial))
+                {
+                    try
+                    {
+                        Guid iid = new Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe");
+                        IShellItem folder;
+                        SHCreateItemFromParsingName(initial, IntPtr.Zero, ref iid, out folder);
+                        if (folder != null) ((IFileDialog)dlg).SetFolder(folder);
+                    }
+                    catch { /* 起始目录不存在就退回系统默认 */ }
+                }
+
+                AllowSetForegroundWindow(-1 /* ASFW_ANY */);
+
+                int show = ((IFileDialog)dlg).Show(IntPtr.Zero);
+                if (show == ERROR_CANCELLED || show != 0) return new string[0];
+
+                IShellItemArray results;
+                dlg.GetResults(out results);
+                if (results == null) return new string[0];
+
+                uint count;
+                results.GetCount(out count);
+                var paths = new string[count];
+                for (uint i = 0; i < count; i++)
+                {
+                    IShellItem item;
+                    results.GetItemAt(i, out item);
+                    if (item != null)
+                    {
+                        string path;
+                        item.GetDisplayName(SIGDN_FILESYSPATH, out path);
+                        paths[i] = path;
+                    }
+                }
+                return paths;
+            }
+            finally
+            {
+                if (hr >= 0) CoUninitialize();
+            }
+        }
+    }
+}
+
+'@