dsh-workbuddy-files 0.1.0

package/lib/index.js

@@ -0,0 +1,348 @@
+import { homedir } from "node:os";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, normalize, resolve, sep } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/host/index.ts
+/**
+* dsh-workbuddy-files · Host 半侧
+*
+* 职责：
+*  1. 文件落地缓存 `~/.dsh-drops/`（保留拖入目录树结构），通过 webServer 路由
+*     `/workbuddy-drops` 接收浏览器 fetch 的二进制 POST（无需 base64，支持大文件）；
+*  2. 注册 `read_document` 模型工具：解析 `@"path"` / `@path` 引用并返回内容。
+*
+* 真实插件包的 Host 半侧运行在 DSH 的 Node 进程里（非沙箱），可以直接使用
+* node:fs —— 这也是 dsh-pet 等第三方插件的标准写法（参考其 src/host/index.ts）。
+*/
+/** 插件行 id（与 cordis.patch.yml 的 id 一致） */
+const name = "workbuddy-files";
+/** 硬依赖：Web 服务器路由注册表 */
+const inject = ["webServer"];
+function resolveConfig(config = {}) {
+	return {
+		dropsDir: config.dropsDir ?? "~/.dsh-drops",
+		maxFileBytes: config.maxFileBytes ?? 268435456
+	};
+}
+function expandHome(dir) {
+	if (dir === "~" || dir.startsWith("~/")) return join(homedir(), dir.slice(1));
+	return dir;
+}
+/** 规范化相对路径：拒绝 `..`、绝对路径与控制字符（防目录穿越） */
+function normRel(rel) {
+	const parts = String(rel).replace(/\\/g, "/").split("/");
+	const out = [];
+	for (const p of parts) {
+		if (p === "" || p === ".") continue;
+		if (p === "..") return null;
+		if (/[\u0000-\u001f"\r\n]/.test(p)) return null;
+		out.push(p);
+	}
+	return out.join("/");
+}
+/** 校验最终路径仍位于 drops 根目录内（第二道防线） */
+function resolveDrops(root, rel) {
+	const candidate = normalize(join(root, rel));
+	const rootWithSep = root.endsWith(sep) ? root : root + sep;
+	if (candidate !== root && !candidate.startsWith(rootWithSep)) return void 0;
+	return candidate;
+}
+function sendJson(res, status, obj) {
+	const body = JSON.stringify(obj);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": Buffer.byteLength(body)
+	});
+	res.end(body);
+}
+/** 收集请求体原始字节（流式，不设上限；上限检查在写盘前按 maxFileBytes 执行） */
+function readBody(req) {
+	return new Promise((resolve2, reject) => {
+		const chunks = [];
+		let total = 0;
+		req.on("data", (c) => {
+			chunks.push(c);
+			total += c.length;
+		});
+		req.on("end", () => resolve2(Buffer.concat(chunks, total)));
+		req.on("error", reject);
+	});
+}
+/** UTF-8 可解码性 / 二进制探测（NUL 字节即二进制） */
+function looksBinary(buf) {
+	if (buf.includes(0)) return true;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(buf);
+		return false;
+	} catch {
+		return true;
+	}
+}
+function apply(ctx, config = {}) {
+	const resolved = resolveConfig(config);
+	const dropsDir = resolve(expandHome(resolved.dropsDir));
+	const webServer = ctx.webServer;
+	ctx.effect(() => webServer.register({
+		kind: "prefix",
+		path: "/workbuddy-drops",
+		handler: async (req, res) => {
+			const url = new URL(req.url ?? "/", "http://localhost");
+			const action = url.pathname.slice(16).replace(/^\/+/, "");
+			try {
+				if (action === "home") {
+					sendJson(res, 200, {
+						ok: true,
+						root: dropsDir
+					});
+					return;
+				}
+				if (action === "stat") {
+					const path = url.searchParams.get("path") ?? "";
+					if (path === "") {
+						sendJson(res, 200, {
+							ok: true,
+							exists: false,
+							path
+						});
+						return;
+					}
+					const info = await stat(path);
+					sendJson(res, 200, {
+						ok: true,
+						exists: true,
+						path,
+						type: info.isDirectory() ? "directory" : info.isFile() ? "file" : "other",
+						size: info.isFile() ? info.size : null
+					});
+					return;
+				}
+				if (action === "list") {
+					const q = (url.searchParams.get("query") ?? "").toLowerCase();
+					const items = [];
+					const add = (p, name, type, size) => {
+						if (items.length >= 200) return;
+						if (q === "" || p.toLowerCase().includes(q) || name.toLowerCase().includes(q)) items.push({
+							name,
+							path: p,
+							type,
+							size: size ?? null
+						});
+					};
+					if (await stat(dropsDir).catch(() => null) === null) {
+						sendJson(res, 200, {
+							ok: true,
+							items: []
+						});
+						return;
+					}
+					const batches = await readdir(dropsDir, { withFileTypes: true });
+					for (const b of batches) {
+						if (items.length >= 200) break;
+						if (b.name === ".tmp" || b.name.charAt(0) === ".") continue;
+						const bp = join(dropsDir, b.name);
+						if (b.isFile()) {
+							const s = await stat(bp).catch(() => null);
+							add(bp, b.name, "file", s?.size);
+							continue;
+						}
+						if (!b.isDirectory()) continue;
+						const children = await readdir(bp, { withFileTypes: true }).catch(() => []);
+						for (const c of children) {
+							if (items.length >= 200) break;
+							const cp = join(bp, c.name);
+							const isDir = c.isDirectory();
+							const s = isDir ? null : await stat(cp).catch(() => null);
+							add(cp, c.name, isDir ? "directory" : "file", s?.size ?? void 0);
+							if (isDir) {
+								const sub = await readdir(cp, { withFileTypes: true }).catch(() => []);
+								for (const s2 of sub) {
+									if (items.length >= 200) break;
+									const s2p = join(cp, s2.name);
+									const s2dir = s2.isDirectory();
+									const st2 = s2dir ? null : await stat(s2p).catch(() => null);
+									add(s2p, s2.name, s2dir ? "directory" : "file", st2?.size ?? void 0);
+								}
+							}
+						}
+					}
+					sendJson(res, 200, {
+						ok: true,
+						items
+					});
+					return;
+				}
+				if (action === "save" && req.method === "POST") {
+					const rel = normRel(url.searchParams.get("rel") ?? "");
+					const batch = normRel(url.searchParams.get("batch") ?? "") || "misc";
+					if (rel === null || rel === "") {
+						sendJson(res, 400, {
+							ok: false,
+							error: "目标路径非法"
+						});
+						return;
+					}
+					const dst = resolveDrops(dropsDir, batch + "/" + rel);
+					if (dst === void 0) {
+						sendJson(res, 400, {
+							ok: false,
+							error: "目标路径越界"
+						});
+						return;
+					}
+					const body = await readBody(req);
+					if (resolved.maxFileBytes > 0 && body.length > resolved.maxFileBytes) {
+						sendJson(res, 413, {
+							ok: false,
+							error: "文件超过大小上限 " + Math.floor(resolved.maxFileBytes / 1048576) + "MB"
+						});
+						return;
+					}
+					await mkdir(dirname(dst), { recursive: true });
+					await writeFile(dst, body);
+					sendJson(res, 200, {
+						ok: true,
+						path: dst,
+						rel: batch + "/" + rel,
+						root: dropsDir
+					});
+					return;
+				}
+				sendJson(res, 404, {
+					ok: false,
+					error: "unknown action: " + action
+				});
+			} catch (err) {
+				sendJson(res, 500, {
+					ok: false,
+					error: String(err?.message ?? err)
+				});
+			}
+		}
+	}), "workbuddy: /workbuddy-drops route");
+	const readDocumentTool = defineTool({
+		name: "read_document",
+		description: "解析并读取用户消息中拖拽/粘贴/@ 产生的文件引用（支持 @\"C:\\path\\file.pdf\"、@path 或裸绝对路径）。文本类文件（代码、文档、数据）直接返回内容；文件夹引用返回目录树；图片、二进制与超大文件返回元数据与读取建议。",
+		parameters: {
+			reference: {
+				type: "string",
+				required: true,
+				description: "文件引用：消息中的 @\"...\" 或 @... 令牌，或直接给出绝对路径"
+			},
+			max_chars: {
+				type: "number",
+				description: "文本内容返回上限（默认 60000 字符）"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		execute: async (args, _exec) => {
+			const maxChars = typeof args.max_chars === "number" && args.max_chars > 0 ? Math.floor(args.max_chars) : 6e4;
+			const raw = String(args.reference ?? "").trim();
+			if (raw === "") return {
+				ok: false,
+				error: "reference 为空"
+			};
+			if (raw.startsWith("dsh-drop://")) return {
+				ok: false,
+				error: "该引用是浏览器端零上传直引（FS Access API 句柄），发送消息时已物化到本地缓存。请用消息中的真实路径重新读取。"
+			};
+			let path = raw;
+			if (path.charAt(0) === "@") path = path.slice(1).trim();
+			if (path.length >= 2 && path.charAt(0) === "\"" && path.charAt(path.length - 1) === "\"") path = path.slice(1, -1);
+			path = path.replace(/\/+$/, "");
+			try {
+				const info = await stat(path);
+				const base = path.split(/[\\/]/).pop();
+				if (info.isDirectory()) {
+					const entries = await readdir(path, { withFileTypes: true });
+					const tree = entries.slice(0, 300).map(async (e) => {
+						const st = e.isFile() ? await stat(join(path, e.name)).catch(() => null) : null;
+						return {
+							name: e.name,
+							type: e.isDirectory() ? "directory" : "file",
+							size: st?.size ?? null
+						};
+					});
+					return {
+						ok: true,
+						path,
+						name: base,
+						kind: "directory",
+						entries: await Promise.all(tree),
+						truncated: entries.length > 300
+					};
+				}
+				if (!info.isFile()) return {
+					ok: false,
+					error: "目标不是普通文件: " + path
+				};
+				const size = info.size;
+				if (/\.(png|jpe?g|gif|webp|bmp|svg|ico)$/i.test(base ?? "")) return {
+					ok: true,
+					path,
+					name: base,
+					kind: "image",
+					size,
+					hint: "图片文件：请使用 read_image 工具以该路径直接查看。"
+				};
+				if (size > 15e5) return {
+					ok: true,
+					path,
+					name: base,
+					kind: "large",
+					size,
+					hint: "文件过大，未内联内容；可请用户拆分，或用支持分块读取的工具处理。"
+				};
+				const buf = await readFile(path);
+				if (looksBinary(buf)) return {
+					ok: true,
+					path,
+					name: base,
+					kind: "binary",
+					size,
+					hint: "二进制文件。若为常见格式，可询问用户或用宿主工具转换后读取。"
+				};
+				let content = buf.toString("utf8");
+				const truncated = content.length > maxChars;
+				if (truncated) content = content.slice(0, maxChars);
+				return {
+					ok: true,
+					path,
+					name: base,
+					kind: "text",
+					size,
+					content,
+					truncated
+				};
+			} catch (err) {
+				if (err?.code === "ENOENT") return {
+					ok: false,
+					error: "路径不存在: " + path
+				};
+				return {
+					ok: false,
+					error: String(err?.message ?? err)
+				};
+			}
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: "读取引用文件",
+			kind: "read",
+			rawInput: String(args.reference ?? "")
+		})
+	});
+	const tools = ctx.get("tools");
+	ctx.effect(() => tools !== void 0 ? tools.register(readDocumentTool) : (() => {}), "workbuddy: read_document tool");
+	console.log("[workbuddy-files] host 就绪：drops 缓存 " + dropsDir + "（/workbuddy-drops 路由）+ read_document 工具");
+}
+//#endregion
+export { apply, inject, name };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "dsh-workbuddy-files",
+  "version": "0.1.0",
+  "description": "WorkBuddy 风格的 DeepSeek Harness Web 插件：拖拽/粘贴文件与文件夹生成输入框引用气泡（附绝对路径）、@ 菜单检索缓存文件、对话区文件卡片、read_document 工具。",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "workbuddy",
+    "drag-drop",
+    "file-reference",
+    "file-pill",
+    "web-ui",
+    "cordis"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/miaoxintechnology/dsh-workbuddy-files#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miaoxintechnology/dsh-workbuddy-files.git"
+  },
+  "bugs": {
+    "url": "https://github.com/miaoxintechnology/dsh-workbuddy-files/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run bundle"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "_comment": [
+    "main (lib/index.js) 是 Host 半侧入口（Cordis 插件 apply/inject）",
+    "exports['./client'] 是浏览器半侧入口，DSH 模块系统据此提供 /plugins/dsh-workbuddy-files/client.js",
+    "dsh.bundle.patch 声明本包是 bundle：dsh plugin add 后自动加入 profile 的 bundles 层栈并挂载 host 半侧",
+    "dsh.client 声明浏览器半侧的注入依赖与平台（web）",
+    "peerDependencies 是宿主（DSH）提供的模块，本包不打包它们"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-fs": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/react": "^18.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.5.0"
+  }
+}

package/src/client/app.ts

@@ -0,0 +1,130 @@
+/**
+ * Client 半侧实现（factory 模式）。
+ *
+ * DSH 客户端模块加载器要求 client 产物是「普通副作用脚本」：加载时调用
+ * window.__ModuleLoader__.load({ id, factory })，factory 签名 (require) => module，
+ * 返回 { apply, inject, name }。react 通过 factory 的 require('react') 取得
+ * （参考 dsh-pet 的 src/client/app.ts 与 index.ts）。
+ *
+ * 纯逻辑模块（lib/*、at-source、definitions）不依赖 react，可安全地
+ * 被 tsdown 内联到 bundle 顶层；组件在 factory 内以注入的 React 构造。
+ */
+import { createAtSource } from './at-source'
+import { createFileCardsComponent } from './components/file-cards'
+import { createOverlayComponent, ReactLike } from './components/overlay'
+import { createPickButtonComponent } from './components/pick-button'
+import { CSS } from './css'
+import { boundaryDef, fileRefsDef, selectTurnFileRefs } from './definitions'
+import { createDropBus } from './lib/bus'
+import { createDropHandlers } from './lib/drop'
+import { createInsertPipeline } from './lib/insert'
+import { dropsHome, runUploadJobs } from './lib/transfer'
+import type { UploadJob } from './types'
+
+/** 工厂返回的 Cordis 客户端插件 */
+export interface ClientPlugin {
+  apply(ctx: Record<string, unknown>): void
+  inject?: string[]
+  name?: string
+}
+
+export function makeFactory() {
+  return function workbuddyClientFactory(require: (m: string) => unknown): ClientPlugin {
+    const React = require('react') as ReactLike
+
+    return {
+      name: 'workbuddy-files',
+      apply(ctx) {
+        const get = (name: string) => (ctx.get as (n: string) => unknown)(name)
+
+        // ---- 能力探测（缺失则优雅退出）----
+        const sessions = get('sessions') as never
+        const slots = get('slots') as {
+          inject(key: string, callback: () => unknown): () => void
+          register(options: Record<string, unknown>, component: unknown): unknown
+        } | undefined
+        const conversation = get('conversation') as never
+        const inputTriggers = get('inputTriggers') as {
+          registerSource(source: unknown): () => void
+        } | undefined
+        const conversationEvents = get('conversationEvents') as {
+          register(definition: unknown): (() => void) | undefined
+        } | undefined
+        const styles = get('styles') as { insert(css: string): () => void } | undefined
+        if (slots === undefined) return
+
+        // ---- 包内样式 ----
+        const insertStyles = () => (styles !== undefined ? styles.insert(CSS) : () => {})
+        const effect = (ctx.effect as (fn: () => (() => void) | undefined, label?: string) => void).bind(ctx)
+        effect(insertStyles, 'workbuddy: styles')
+
+        // ---- 共享实例 ----
+        const bus = createDropBus()
+
+        // ---- 缓存根目录（启动预取；拖入时兜底拉取）----
+        let rootCache: string | null = null
+        void dropsHome().then((r) => { rootCache = r })
+        const ensureRoot = async (): Promise<string | null> => {
+          if (rootCache !== null) return rootCache
+          const r = await dropsHome()
+          rootCache = r
+          return r
+        }
+
+        // ---- 后台上传队列（完成/失败 toast）----
+        const enqueueUpload = (jobs: UploadJob[], batch: string): void => {
+          void runUploadJobs(jobs, batch).then(({ ok, failed }) => {
+            if (failed.length > 0) {
+              bus.toast('缓存失败 ' + failed.length + ' 项：' + failed.slice(0, 2).join('；') + (failed.length > 2 ? '…' : ''), 'error')
+            } else if (ok > 0) {
+              bus.toast('后台缓存完成：' + ok + ' 个文件已就绪')
+            }
+          }).catch((err) => {
+            bus.toast('后台缓存失败：' + String((err as Error)?.message ?? err), 'error')
+          })
+        }
+
+        // ---- 气泡注入管线 ----
+        const insert = createInsertPipeline({ sessions, conversation, toast: bus.toast })
+
+        // ---- 拖拽 / 粘贴处理 + 窗口级监听 ----
+        const handlers = createDropHandlers({ bus, insert, ensureRoot, enqueueUpload })
+        effect(() => handlers.installListeners(), 'workbuddy: window listeners')
+
+        // ---- @ 触发源（文件缓存分组）----
+        if (inputTriggers !== undefined) {
+          const source = createAtSource()
+          effect(() => inputTriggers.registerSource(source), 'workbuddy: @ source')
+        }
+
+        // ---- 会话事件定义 ----
+        if (conversationEvents !== undefined) {
+          effect(() => {
+            const d1 = conversationEvents.register(boundaryDef)
+            const d2 = conversationEvents.register(fileRefsDef)
+            return () => {
+              if (typeof d1 === 'function') d1()
+              if (typeof d2 === 'function') d2()
+            }
+          }, 'workbuddy: conversation definitions')
+        }
+
+        // ---- Slot 注册 ----
+        slots.inject('shell.overlay', () => slots.register(
+          { name: 'shell.overlay', id: 'workbuddy-drop', order: 300, label: 'WorkBuddy 拖拽遮罩' },
+          createOverlayComponent(React, bus),
+        ))
+        slots.inject('conversation.input.left', () => slots.register(
+          { name: 'conversation.input.left', id: 'workbuddy-pick', order: 0, label: '引用文件/文件夹' },
+          createPickButtonComponent(React, bus, handlers),
+        ))
+        slots.inject('conversation.chat.turnTail', () => slots.register(
+          { name: 'conversation.chat.turnTail', select: selectTurnFileRefs },
+          createFileCardsComponent(React),
+        ))
+
+        console.log('[workbuddy-files] client 就绪：拖入即插气泡 + 后台缓存 / 统一遮罩 / 文件卡片')
+      },
+    }
+  }
+}

package/src/client/at-source.ts

@@ -0,0 +1,57 @@
+import type { InputTriggerSource, InputTriggerCandidate } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
+import { iconFor } from './lib/icons'
+import { dropsList, mentionFor } from './lib/transfer'
+
+/**
+ * @ 触发源「workbuddy」：输入 @ 时在菜单中追加「文件缓存」分组 ——
+ * ~/.dsh-drops 中拖拽/粘贴/选择落地的文件与目录树，支持搜索。
+ * 选中后由输入管线的 onPick → { insert } 在触发词位置铸造原生气泡。
+ *
+ * 工作区文件/文件夹的 @ 检索由 DSH 官方 ui-reference 源提供（文件与文件夹 +
+ * Session 分组），本插件与之共存，无需重复实现。
+ *
+ * 所有引用在拖入时已完成落地（真实绝对路径），因此 codec 序列化是恒等函数，
+ * 发送消息不可能因文件未落地而失败。
+ */
+export function createAtSource(): InputTriggerSource {
+  return {
+    trigger: '@',
+    name: 'workbuddy',
+    order: 5,
+    showGroupTitle: true,
+    async candidates(_session, req) {
+      const q = (req && req.query) || ''
+      const items = await dropsList(q)
+      const out: InputTriggerCandidate[] = []
+      for (const it of items) {
+        const isDir = it.type === 'directory'
+        out.push({
+          name: (isDir ? '📁 ' : iconFor(it.name) + ' ') + it.name + (isDir ? '/' : ''),
+          description: it.path,
+          section: '文件缓存 · ~/.dsh-drops',
+          value: JSON.stringify({ kind: isDir ? 'folder' : 'file', name: it.name, path: it.path }),
+        })
+      }
+      return out.slice(0, 60)
+    },
+    onPick(pick) {
+      let v: { kind?: string; name?: string; path?: string } | null = null
+      try { v = JSON.parse(pick.candidate.value || 'null') } catch { return undefined }
+      if (v === null || typeof v !== 'object' || typeof v.path !== 'string') return undefined
+      const mention = mentionFor(v.path, v.kind === 'folder')
+      return {
+        insert: {
+          source: 'workbuddy',
+          ref: mention,
+          label: v.name ?? '',
+          appearance: v.kind === 'folder' ? 'folder' : 'file',
+          clipboardText: mention,
+        },
+      }
+    },
+    codec: {
+      clipboardText: (ref) => ref,
+      serialize: (ref) => Promise.resolve(ref),
+    },
+  }
+}

package/src/client/components/file-cards.tsx

@@ -0,0 +1,47 @@
+import { formatSize, iconFor } from '../lib/icons'
+import { dropsStat } from '../lib/transfer'
+import type { ReactLike } from './overlay'
+
+/**
+ * 对话区文件卡片（挂在 conversation.chat.turnTail 链式槽）：
+ * 用户消息发送后，该轮次消息中引用的文件以「类型图标 + 文件名 + 大小/文件夹」卡片
+ * 渲染在轮次尾部；点击卡片经 owner 的 openFile 打开文件。
+ * selector 只匹配含文件引用的轮次（见 definitions.ts），不抢占其他链条目。
+ */
+export function createFileCardsComponent(React: ReactLike) {
+  function FileCard(props: { path: string; openFile?: (path: string) => void }) {
+    const { path, openFile } = props
+    const [meta, setMeta] = React.useState<Awaited<ReturnType<typeof dropsStat>> | null>(null)
+    React.useEffect(() => {
+      let live = true
+      dropsStat(path).then((r) => { if (live) setMeta(r) }, () => { if (live) setMeta({ ok: false, path }) })
+      return () => { live = false }
+    }, [path])
+
+    const name = String(path).split(/[\\/]/).pop() || path
+    const good = meta !== null && meta !== undefined && meta.ok === true && meta.exists === true
+    const isDir = good && meta.type === 'directory'
+    const icon = isDir ? '📁' : iconFor(name)
+    const sub = meta === null ? '…' : (!good ? '不可用' : (isDir ? '文件夹' : formatSize(meta.size)))
+
+    return React.createElement('button', {
+      type: 'button',
+      className: 'wbd-card',
+      title: path,
+      onClick: () => { if (typeof openFile === 'function') { try { openFile(path) } catch { /* ignore */ } } },
+    },
+      React.createElement('span', { className: 'wbd-card-icon' }, icon),
+      React.createElement('span', { className: 'wbd-card-name' }, name),
+      React.createElement('span', { className: 'wbd-card-sub' }, sub),
+    )
+  }
+
+  return function FileCards(props: { matched: { refs: string[] }; openFile?: (path: string) => void }) {
+    const matched = props.matched
+    if (matched === null || matched === undefined || !Array.isArray(matched.refs) || matched.refs.length === 0) return null
+    return React.createElement('div', { className: 'wbd-cards' },
+      React.createElement('span', { className: 'wbd-cards-label' }, '📎 消息引用的文件'),
+      matched.refs.map((path, i) => React.createElement(FileCard, { key: String(path) + ':' + i, path, openFile: props.openFile })),
+    )
+  }
+}