@dsh-sparrow/dsh-file-manage 0.1.0 → 0.1.2-rc.1.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 English | [简体中文](CHANGELOG.zh-CN.md)
 
+## 0.1.2-rc.1.1 (2026-09-09)
+
+- If dsh is upgraded to a version this plugin does not support yet, the plugin now disables itself instead of running against an unknown contract (dsh and other plugins are unaffected).
+
+## 0.1.2-rc.1 (2026-09-05)
+
+- Version-line alignment with official dsh 0.1.2-rc.1 (stability line).
+- Pagination and delete race fixes: after quickly reopening the panel or hitting Retry, stale pages no longer merge into the fresh list, "Load more" no longer sticks disabled, and a late delete callback no longer dismisses a newly opened confirmation dialog.
+- Requests that outlive the panel now stop by themselves instead of hanging (15s cap for list/delete, 60s for the count pass), and the count pass stops paging as soon as the client connection drops, so an abandoned count no longer keeps burning API quota.
+- The sidebar "Cloud Files" button now aligns its width with Settings (same as the Archive entry).
+- "Load more" now lives at the end of the file list and the list auto-scrolls to the bottom after each page loads (the button no longer sits in a fixed panel footer).
+- A subtle 🐦 dsh-sparrow brand line closes the panel.
+
 ## 0.1.0 (2026-09-02)
 
 - Promoted 0.1.0 (identical to 0.1.0-alpha.3).

package/CHANGELOG.zh-CN.md

@@ -2,6 +2,19 @@
 
 简体中文 | [English](CHANGELOG.md)
 
+## 0.1.2-rc.1.1（2026-09-09）
+
+- dsh 升级到本插件尚不支持的版本时，插件会自动停用（dsh 与其它插件不受影响），不再带病运行。
+
+## 0.1.2-rc.1（2026-09-05）
+
+- 版本对齐官方 dsh 0.1.2-rc.1（稳定线）。
+- 翻页与删除的并发修复：快速关开面板或点击重试后，陈旧页不再混入新列表、「加载更多」不再卡死，迟到的删除回调不再误关新弹出的确认框。
+- 请求超时后自行停止不再无限挂起（列表/删除 15s、计数 60s 上限），计数翻页在客户端连接断开（超时/导航）时立即停下，被放弃的计数不再持续消耗 API 配额。
+- 侧边栏「云端文件」按钮与 Settings 同宽对齐（与归档入口一致）。
+- 「加载更多」移到文件列表末尾，每页加载后自动滚到列表底部（按钮不再固定在面板底部）。
+- 面板底部新增 🐦 dsh-sparrow 品牌行。
+
 ## 0.1.0 (2026-09-02)
 
 - 转正 0.1.0（与 0.1.0-alpha.3 一致）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 peiyucn
+
+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

@@ -12,14 +12,14 @@ Large images pasted into DSH are auto-uploaded to the DeepSeek Files API, but th
 dsh plugin --profile web add @dsh-sparrow/dsh-file-manage
 ```
 
-Requires dsh ≥ 0.1.2-alpha.4 and a working `pnpm` (`dsh plugin` forwards installation to pnpm).
+Requires dsh 0.1.2-rc.1 — the exact official version line this release is built and verified against (newer lines, pre-releases in particular, are not covered) — and a working `pnpm` (`dsh plugin` forwards installation to pnpm).
 
 > Do **not** run `npm install @dsh-sparrow/dsh-file-manage` directly: that only downloads the package into some `node_modules` and does not register it with the DSH web profile. Use the `dsh plugin` command above, then restart DSH.
 
 ## Usage
 
 * **Entry**: the "Cloud Files" button at the sidebar footer
-* **List**: 20 files per page with "Load more" pagination (official after cursor, newest first); each row shows filename / size / upload time / expiry time (when present)
+* **List**: newest first with "Load more" at the bottom (100 more files per click, official after cursor); each row shows filename / size / upload time / expiry time (when present)
 * **Quota**: the panel header shows the total count and a netdisk-style quota bar (used storage / the official 25 GiB limit)
 * **Delete**: per-row delete with confirmation; "DSH auto-uploaded" files (`dsh-` prefix) get an extra note — sessions referencing them will transparently re-upload on next use (may be slower)
 * **Copy file_id**: one-click copy per row
@@ -40,3 +40,5 @@ Requires dsh ≥ 0.1.2-alpha.4 and a working `pnpm` (`dsh plugin` forwards insta
 ## Uninstall & leftovers
 
 * The plugin keeps no local state; uninstalling leaves the cloud files untouched and DSH behavior unchanged
+
+**Changelog**: [CHANGELOG.md](https://github.com/peiyucn/dsh-sparrow/blob/main/plugins/dsh-file-manage/CHANGELOG.md)

package/README.zh-CN.md

@@ -12,14 +12,14 @@ DSH 贴图的大图会自动上传到 DeepSeek Files API（云端文件库），
 dsh plugin --profile web add @dsh-sparrow/dsh-file-manage
 ```
 
-适配 dsh ≥ 0.1.2-alpha.4，并需要可用的 `pnpm`（`dsh plugin` 会把安装操作转发给 pnpm）。
+适配 dsh 0.1.2-rc.1（本版构建与验证所对齐的确切官方版本线；更新的版本线、尤其是预发布版本不在承诺范围内），并需要可用的 `pnpm`（`dsh plugin` 会把安装操作转发给 pnpm）。
 
 > **不要**直接执行 `npm install @dsh-sparrow/dsh-file-manage`：那只会把包下载到某个 `node_modules`，不会注册进 DSH 的 web profile。请使用上面的 `dsh plugin` 命令安装，并在安装后重启 DSH。
 
 ## 使用
 
 * **入口**：侧边栏底部「云端文件」按钮
-* **列表**：每页 20 条，底部「加载更多」翻页（官方 after 游标，最新在前）；行内展示文件名 / 大小 / 上传时间 / 到期时间（有则显）
+* **列表**：最新在前，底部「加载更多」每次多显示 100 条（官方 after 游标翻页）；行内展示文件名 / 大小 / 上传时间 / 到期时间（有则显）
 * **配额**：列表顶部显示总数与网盘式配额进度条（已用存储 / 25 GiB 官方上限）
 * **删除**：行内删除按钮二次确认；「DSH 自动上传」角标（`dsh-` 前缀）的文件有额外提示——删除后旧会话再次引用时官方会自动重新上传（可能稍慢）
 * **复制 file_id**：行内按钮一键复制
@@ -40,3 +40,5 @@ dsh plugin --profile web add @dsh-sparrow/dsh-file-manage
 ## 卸载与残留
 
 * 插件无任何本地持久化状态；卸载后云端文件原样保留，DSH 行为不受影响
+
+**更新日志**：[CHANGELOG.zh-CN.md](https://github.com/peiyucn/dsh-sparrow/blob/main/plugins/dsh-file-manage/CHANGELOG.zh-CN.md)

package/lib/client.js

@@ -32,19 +32,56 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/client/paging.ts
+var RENDER_PAGE_SIZE = 100;
+var FILE_PAGE_SIZE = 200;
+function renderedRowCount(totalRows, renderLimit) {
+  const total = Math.max(0, Math.trunc(totalRows));
+  const limit = Math.max(0, Math.trunc(renderLimit));
+  return Math.min(total, limit);
+}
+function hasLoadMore(totalRows, renderLimit, dataHasMore) {
+  return renderedRowCount(totalRows, renderLimit) < totalRows || dataHasMore;
+}
+
 // src/client/api.ts
+var COUNT_CACHE_TTL_MS = 3e4;
+var countCache = null;
+function readCountCache(entry, nowMs) {
+  return entry !== null && nowMs < entry.expiresAt ? entry.value : null;
+}
+function invalidateCountCache() {
+  countCache = null;
+}
 var REQUEST_TIMEOUT_MS = 15e3;
 var COUNT_TIMEOUT_MS = 6e4;
+async function fetchWithTimeout(path, init, timeoutMs) {
+  try {
+    return await fetch(path, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (error) {
+    if (error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
+      throw new Error(`\u8BF7\u6C42\u8D85\u65F6\uFF08${Math.round(timeoutMs / 1e3)}s\uFF09\uFF0C\u8BF7\u91CD\u8BD5`);
+    }
+    throw error;
+  }
+}
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return {};
+  }
+}
+async function readErrorMessage(response) {
+  const payload = await readJson(response);
+  return payload.error?.message ?? `\u8BF7\u6C42\u5931\u8D25\uFF08HTTP ${response.status}\uFF09`;
+}
 async function listApi(after) {
-  const params = new URLSearchParams();
+  const params = new URLSearchParams({ limit: String(FILE_PAGE_SIZE) });
   if (after !== void 0) params.set("after", after);
-  const response = await fetch(`/api/file-manage/list?${params.toString()}`, {
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-  });
-  const payload = await response.json();
-  if (!response.ok) {
-    throw new Error(payload.error?.message ?? `\u8BF7\u6C42\u5931\u8D25\uFF08HTTP ${response.status}\uFF09`);
-  }
+  const response = await fetchWithTimeout(`/api/file-manage/list?${params.toString()}`, {}, REQUEST_TIMEOUT_MS);
+  if (!response.ok) throw new Error(await readErrorMessage(response));
+  const payload = await readJson(response);
   return {
     rows: payload.items ?? [],
     hasMore: payload.hasMore ?? false,
@@ -52,12 +89,12 @@ async function listApi(after) {
   };
 }
 async function countApi() {
-  const response = await fetch("/api/file-manage/count", { signal: AbortSignal.timeout(COUNT_TIMEOUT_MS) });
-  const payload = await response.json();
-  if (!response.ok) {
-    throw new Error(payload.error?.message ?? `\u8BF7\u6C42\u5931\u8D25\uFF08HTTP ${response.status}\uFF09`);
-  }
-  return {
+  const cached = readCountCache(countCache, Date.now());
+  if (cached !== null) return cached;
+  const response = await fetchWithTimeout("/api/file-manage/count", {}, COUNT_TIMEOUT_MS);
+  if (!response.ok) throw new Error(await readErrorMessage(response));
+  const payload = await readJson(response);
+  const summary = {
     count: payload.count ?? 0,
     totalBytes: payload.totalBytes ?? 0,
     totalBytesLabel: payload.totalBytesLabel ?? "0 B",
@@ -65,17 +102,14 @@ async function countApi() {
     quotaBytesLabel: payload.quotaBytesLabel ?? "0 B",
     quotaCount: payload.quotaCount ?? 0
   };
+  countCache = { value: summary, expiresAt: Date.now() + COUNT_CACHE_TTL_MS };
+  return summary;
 }
 async function deleteApi(id) {
   const params = new URLSearchParams({ id });
-  const response = await fetch(`/api/file-manage/files?${params.toString()}`, {
-    method: "DELETE",
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-  });
-  const payload = await response.json();
-  if (!response.ok) {
-    throw new Error(payload.error?.message ?? `\u8BF7\u6C42\u5931\u8D25\uFF08HTTP ${response.status}\uFF09`);
-  }
+  const response = await fetchWithTimeout(`/api/file-manage/files?${params.toString()}`, { method: "DELETE" }, REQUEST_TIMEOUT_MS);
+  if (!response.ok) throw new Error(await readErrorMessage(response));
+  invalidateCountCache();
 }
 
 // src/client/FileManageDock.tsx
@@ -411,17 +445,22 @@ var styles = {
     fontSize: 12,
     lineHeight: "18px"
   },
-  footerBar: {
+  /** 合集品牌 footer：固定面板底部（滚动区之外），顶部分割线与内容区隔开；紧凑规格。 */
+  footer: {
     flex: "none",
-    display: "flex",
-    justifyContent: "center",
-    // 列表已包区块卡，不再加顶部分隔线（避免与卡片叠加显乱）。
-    padding: "10px 24px 14px"
+    boxSizing: "border-box",
+    padding: "6px 24px 8px",
+    borderTop: "1px solid var(--dsw-alias-border-l1, #e2e5ea)",
+    textAlign: "center",
+    fontSize: 11,
+    lineHeight: "16px",
+    color: "var(--dsw-alias-label-tertiary, #8a919f)"
   }
 };
 
 // src/client/FileManageDock.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
+var COPIED_RESET_MS = 2e3;
 function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
   const [open, setOpen] = (0, import_react.useState)(false);
   const [rows, setRows] = (0, import_react.useState)([]);
@@ -437,13 +476,20 @@ function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
   const [summaryPending, setSummaryPending] = (0, import_react.useState)(false);
   const closeButtonRef = (0, import_react.useRef)(null);
   const refreshSeqRef = (0, import_react.useRef)(0);
+  const bodyRef = (0, import_react.useRef)(null);
+  const scrollPendingRef = (0, import_react.useRef)(false);
   const copiedTimerRef = (0, import_react.useRef)(null);
+  const [renderLimit, setRenderLimit] = (0, import_react.useState)(RENDER_PAGE_SIZE);
   const reload = (0, import_react.useCallback)(() => {
     const seq = ++refreshSeqRef.current;
     setLoading(true);
     setSummaryPending(true);
     setSummary(null);
     setError(null);
+    setLoadingMore(false);
+    setBusyDelete(false);
+    scrollPendingRef.current = false;
+    setRenderLimit(RENDER_PAGE_SIZE);
     listFiles().then((page) => {
       if (seq !== refreshSeqRef.current) return;
       setRows(page.rows);
@@ -486,18 +532,29 @@ function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
     if (copiedTimerRef.current !== null) window.clearTimeout(copiedTimerRef.current);
   }, []);
   const loadMore = (0, import_react.useCallback)(() => {
-    if (lastId === void 0 || loadingMore) return;
+    if (loadingMore) return;
+    if (renderLimit < rows.length) {
+      setRenderLimit((limit) => limit + RENDER_PAGE_SIZE);
+      scrollPendingRef.current = true;
+      return;
+    }
+    if (lastId === void 0) return;
+    const seq = refreshSeqRef.current;
     setLoadingMore(true);
+    scrollPendingRef.current = true;
     listFiles(lastId).then((page) => {
+      if (seq !== refreshSeqRef.current) return;
       setRows((current) => [...current, ...page.rows]);
       setHasMore(page.hasMore);
       setLastId(page.lastId);
+      setRenderLimit((limit) => limit + RENDER_PAGE_SIZE);
     }).catch((reason) => {
+      if (seq !== refreshSeqRef.current) return;
       setError(reason instanceof Error ? reason.message : String(reason));
     }).finally(() => {
-      setLoadingMore(false);
+      if (seq === refreshSeqRef.current) setLoadingMore(false);
     });
-  }, [lastId, loadingMore, listFiles]);
+  }, [renderLimit, rows.length, lastId, loadingMore, listFiles]);
   const copyId = (0, import_react.useCallback)(async (row) => {
     try {
       await navigator.clipboard.writeText(row.id);
@@ -505,27 +562,39 @@ function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
       if (copiedTimerRef.current !== null) window.clearTimeout(copiedTimerRef.current);
       copiedTimerRef.current = window.setTimeout(() => {
         setCopied(null);
-      }, 2e3);
+      }, COPIED_RESET_MS);
     } catch {
       setCopied(null);
       setError(t("copyFailed"));
     }
   }, [t]);
+  (0, import_react.useEffect)(() => {
+    if (!scrollPendingRef.current) return;
+    scrollPendingRef.current = false;
+    const el = bodyRef.current;
+    if (el !== null) el.scrollTop = el.scrollHeight;
+  }, [rows, renderLimit]);
   const initialLoading = loading || summaryPending;
   const quotaRatio = summary === null ? 0 : storageUsageRatio(summary.totalBytes, summary.quotaBytes);
+  const visibleCount = renderedRowCount(rows.length, renderLimit);
   const submitDelete = (0, import_react.useCallback)(() => {
     if (confirming === null || busyDelete) return;
+    const seq = refreshSeqRef.current;
+    const deleteId = confirming.id;
     setBusyDelete(true);
-    deleteFile(confirming.id).then(() => {
-      setRows((current) => current.filter((row) => row.id !== confirming.id));
-      setConfirming(null);
-      void countFiles().then(setSummary).catch(() => {
+    deleteFile(deleteId).then(() => {
+      setRows((current) => current.filter((row) => row.id !== deleteId));
+      setConfirming((current) => current !== null && current.id === deleteId ? null : current);
+      void countFiles().then((next) => {
+        if (seq === refreshSeqRef.current) setSummary(next);
+      }).catch(() => {
       });
     }).catch((reason) => {
+      if (seq !== refreshSeqRef.current) return;
       setError(reason instanceof Error ? reason.message : String(reason));
-      setConfirming(null);
+      setConfirming((current) => current !== null && current.id === deleteId ? null : current);
     }).finally(() => {
-      setBusyDelete(false);
+      if (seq === refreshSeqRef.current) setBusyDelete(false);
     });
   }, [busyDelete, confirming, deleteFile, countFiles]);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
@@ -560,9 +629,9 @@ function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "dsh-file-manage-quota-text", children: `${summary.totalBytesLabel} / ${summary.quotaBytesLabel} \xB7 ${t("quota.used", { percent: formatUsagePercent(quotaRatio) })}` }),
           quotaRatio > 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dsh-file-manage-quota-fill", style: { width: `${Math.round(quotaRatio * 100)}%` } }) : null
         ] }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dsh-file-manage-count", children: rows.length < summary.count ? t("summary.loaded", { loaded: rows.length, count: summary.count }) : t("summary.count", { count: summary.count }) })
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "dsh-file-manage-count", children: visibleCount < summary.count ? t("summary.loaded", { loaded: visibleCount, count: summary.count }) : t("summary.count", { count: summary.count }) })
       ] }) : null,
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { ...styles.body, padding: summary !== null ? "0 24px 24px" : "12px 24px 24px" }, className: "dsh-file-manage-body", children: initialLoading ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dsh-file-manage-loading", role: "status", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: bodyRef, style: { ...styles.body, padding: summary !== null ? "0 24px 24px" : "12px 24px 24px" }, className: "dsh-file-manage-body", children: initialLoading ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "dsh-file-manage-loading", role: "status", children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "dsh-file-manage-spinner", "aria-hidden": true }),
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: t("loading") })
       ] }) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
@@ -574,7 +643,7 @@ function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
           }, children: t("retry") })
         ] }) : null,
         error === null && rows.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.secondarySmall, children: t("empty") }) : null,
-        rows.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dsh-file-manage-card", children: rows.map((row) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.row, children: [
+        rows.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dsh-file-manage-card", children: rows.slice(0, renderLimit).map((row) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.row, children: [
           /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { minWidth: 0 }, children: [
             /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { display: "flex", alignItems: "center", gap: 6, minWidth: 0 }, children: [
               /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: styles.title, title: row.filename, children: row.filename }),
@@ -611,20 +680,21 @@ function FileManageDock({ wide, listFiles, deleteFile, countFiles, t }) {
               }
             )
           ] })
-        ] }, row.id)) }) : null
+        ] }, row.id)) }) : null,
+        hasLoadMore(rows.length, renderLimit, hasMore) && !initialLoading ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { display: "flex", justifyContent: "center", paddingTop: 12 }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "button",
+          {
+            type: "button",
+            className: "dsh-file-manage-btn",
+            disabled: loadingMore,
+            onClick: () => {
+              void loadMore();
+            },
+            children: loadingMore ? t("loading") : t("loadMore")
+          }
+        ) }) : null
       ] }) }),
-      hasMore && !initialLoading ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.footerBar, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-        "button",
-        {
-          type: "button",
-          className: "dsh-file-manage-btn",
-          disabled: loadingMore,
-          onClick: () => {
-            void loadMore();
-          },
-          children: loadingMore ? t("loading") : t("loadMore")
-        }
-      ) }) : null
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: styles.footer, children: "\u{1F426} dsh-sparrow" })
     ] }) }) : null,
     confirming !== null ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "dsh-file-manage-confirm-overlay", role: "presentation", onMouseDown: (event) => {
       if (event.target === event.currentTarget && !busyDelete) setConfirming(null);

package/lib/compat.js

@@ -0,0 +1,34 @@
+/**
+ * 宿主兼容自检（根 AGENTS《插件与宿主兼容》）——纯能力版。
+ *
+ * 本插件不读 dsh 会话数据，因此没有会话格式门；守卫点是**宿主能力面**
+ * （依赖的服务/方法/导出是否存在，以及运行环境特性）。不满足即抛错自停用，
+ * 绝不带病运行。判定与文案是纯逻辑，供单测。
+ */
+/**
+ * 缺失的能力名（纯逻辑，供单测）。
+ * @param capabilities - 本插件声明的能力。
+ * @returns 未满足的能力名，按声明顺序。
+ */
+export function missingCapabilities(capabilities) {
+    return capabilities.filter(capability => !capability.ok).map(capability => capability.name);
+}
+/**
+ * 能力门：任一必需能力缺失即抛错（自停用）。
+ *
+ * cordis 逐插件捕获 `apply` 异常并把该插件标为 inactive，dsh 与其余插件不受影响
+ * （已查证 cordis `lib/index.js:1350-1362`）。抛错前先记一条面向用户的告警，
+ * 说明「为什么停用、怎么恢复」。
+ * @param ctx - 插件上下文（只用到 logger）。
+ * @param pluginName - 插件名（日志与错误前缀）。
+ * @param capabilities - 本插件声明的能力。
+ */
+export function assertCapabilities(ctx, pluginName, capabilities) {
+    const missing = missingCapabilities(capabilities);
+    if (missing.length === 0)
+        return;
+    const reason = `缺少本插件依赖的 ${missing.join('、')}`;
+    ctx.logger.warn(`${pluginName}: ${reason}；已停用插件以免影响 dsh（升级本插件或运行环境后自动恢复）`);
+    throw new Error(`${pluginName}: ${reason}`);
+}
+//# sourceMappingURL=compat.js.map

package/lib/host.js

@@ -1,6 +1,6 @@
 /** dsh-file-manage host half：DeepSeek Files API 云端文件清单 REST 路由（复用官方 DeepSeekFilesClient）。 */
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
-import { DeepSeekFileId, DeepSeekFilesClient, MAX_STORED_FILE_BYTES, MAX_STORED_FILE_COUNT } from '@deepseek-ai/dsh-llm-deepseek';
+import { assertCapabilities } from './compat.js';
 import { classifyUpstreamError, COUNT_PAGE_LIMIT, COUNT_PAGE_TIMEOUT_MS, decodeFileIdParam, formatBytes, MAX_COUNT_PAGES, normalizePageQuery, toFileRow } from './files.js';
 export const name = 'dsh-file-manage';
 export const inject = ['webServer', 'credentials', 'settings'];
@@ -9,6 +9,11 @@ const PREFIX = '/api/file-manage';
 const DEFAULT_BASE_URL = 'https://api.deepseek.com';
 const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY';
 const LLM_DEEPSEEK_NS = 'llm-deepseek';
+/**
+ * 单页 list / 单条 delete 的上游超时：官方 client 的 fetch 本身无默认超时，客户端断开
+ * （关面板 / 15s 超时）后残留的上游请求必须自限，否则会无限挂起并占用官方 API 配额。
+ */
+const UPSTREAM_TIMEOUT_MS = 15_000;
 /** 插件自身错误（面板可读的 code / message + HTTP 状态）。 */
 class FileManageError extends Error {
     code;
@@ -68,11 +73,31 @@ function sendUpstreamError(res, error) {
     const info = classifyUpstreamError(error);
     sendJson(res, info.status, { error: { code: info.code, message: info.message } });
 }
+let officialSurface;
+/** 读取（并缓存）官方导出面；缺任何一项即抛可读错误（启动期抛错 = 自停用）。 */
+async function deepSeekSurface() {
+    if (officialSurface !== undefined)
+        return officialSurface;
+    const module = await import('@deepseek-ai/dsh-llm-deepseek');
+    const missing = ['DeepSeekFileId', 'DeepSeekFilesClient', 'MAX_STORED_FILE_BYTES', 'MAX_STORED_FILE_COUNT']
+        .filter(key => module[key] === undefined);
+    if (missing.length > 0) {
+        throw new FileManageError('UNSUPPORTED_HOST', `当前 dsh 的 dsh-llm-deepseek 不再导出 ${missing.join('、')}；本插件已停用（升级本插件后自动恢复）`, 501);
+    }
+    officialSurface = module;
+    return officialSurface;
+}
 /**
  * host half 入口：注册 prefix 路由（list / 单条删除），全部副作用挂在 apply 的 effect 上。
  * @param ctx - DSH 插件上下文。
  */
-export function apply(ctx) {
+export async function apply(ctx) {
+    // 宿主兼容自检（根 AGENTS《插件与宿主兼容》，先于一切注册）：能力面或官方面缺失即自停用。
+    assertCapabilities(ctx, name, [
+        { name: 'webServer.register', ok: typeof ctx.webServer?.register === 'function' },
+        { name: 'credentials.resolve', ok: typeof ctx.credentials?.resolve === 'function' },
+    ]);
+    await deepSeekSurface();
     ctx.effect(() => ctx.webServer.register({
         kind: 'prefix',
         path: PREFIX,
@@ -80,6 +105,7 @@ export function apply(ctx) {
             const url = new URL(req.url ?? '/', 'http://localhost');
             const pathname = url.pathname;
             try {
+                const surface = await deepSeekSurface();
                 if (req.method === 'GET' && pathname === `${PREFIX}/list`) {
                     const query = normalizePageQuery({
                         after: url.searchParams.get('after') ?? undefined,
@@ -87,11 +113,12 @@ export function apply(ctx) {
                         order: url.searchParams.get('order') ?? undefined,
                     });
                     const connection = await resolveConnection(ctx);
-                    const client = new DeepSeekFilesClient({ baseURL: connection.baseURL, apiKey: connection.apiKey });
+                    const client = new surface.DeepSeekFilesClient({ baseURL: connection.baseURL, apiKey: connection.apiKey });
                     const page = await client.list({
-                        ...query.after === undefined ? {} : { after: DeepSeekFileId(query.after) },
+                        ...query.after === undefined ? {} : { after: surface.DeepSeekFileId(query.after) },
                         limit: query.limit,
                         order: query.order,
+                        signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
                     });
                     sendJson(res, 200, {
                         items: page.data.map(toFileRow),
@@ -103,11 +130,14 @@ export function apply(ctx) {
                 if (req.method === 'GET' && pathname === `${PREFIX}/count`) {
                     // 官方 list 无总数字段：翻到底累计（每页 1000，配额内最多 10 页，MAX_COUNT_PAGES 兜底）。
                     const connection = await resolveConnection(ctx);
-                    const client = new DeepSeekFilesClient({ baseURL: connection.baseURL, apiKey: connection.apiKey });
+                    const client = new surface.DeepSeekFilesClient({ baseURL: connection.baseURL, apiKey: connection.apiKey });
                     let count = 0;
                     let totalBytes = 0;
                     let after;
                     for (let page = 0; page < MAX_COUNT_PAGES; page++) {
+                        // 客户端已断开（超时 / 关面板）时停止翻页：剩余页数没有接收方，白烧官方 API 配额。
+                        if (res.destroyed)
+                            break;
                         const result = await client.list({
                             ...after === undefined ? {} : { after },
                             limit: COUNT_PAGE_LIMIT,
@@ -125,9 +155,9 @@ export function apply(ctx) {
                         count,
                         totalBytes,
                         totalBytesLabel: formatBytes(totalBytes),
-                        quotaBytes: MAX_STORED_FILE_BYTES,
-                        quotaBytesLabel: formatBytes(MAX_STORED_FILE_BYTES),
-                        quotaCount: MAX_STORED_FILE_COUNT,
+                        quotaBytes: surface.MAX_STORED_FILE_BYTES,
+                        quotaBytesLabel: formatBytes(surface.MAX_STORED_FILE_BYTES),
+                        quotaCount: surface.MAX_STORED_FILE_COUNT,
                     });
                     return;
                 }
@@ -138,8 +168,8 @@ export function apply(ctx) {
                         return;
                     }
                     const connection = await resolveConnection(ctx);
-                    const client = new DeepSeekFilesClient({ baseURL: connection.baseURL, apiKey: connection.apiKey });
-                    await client.delete(DeepSeekFileId(id));
+                    const client = new surface.DeepSeekFilesClient({ baseURL: connection.baseURL, apiKey: connection.apiKey });
+                    await client.delete(surface.DeepSeekFileId(id), AbortSignal.timeout(UPSTREAM_TIMEOUT_MS));
                     sendJson(res, 200, { deleted: true, id });
                     return;
                 }

package/lib/types/client/api.d.ts

@@ -9,6 +9,17 @@ export interface FileCountSummary {
     quotaBytesLabel: string;
     quotaCount: number;
 }
+/** 总数统计 TTL 缓存时长：面板快速重开/重试不重复 count 全量翻页（count 要翻到底，配额内最多 10 页）。 */
+export declare const COUNT_CACHE_TTL_MS = 30000;
+/** TTL 缓存条目（api.ts 模块级单例：面板单实例，随 client bundle 生命周期，有界一条）。 */
+export interface CountCacheEntry {
+    readonly value: FileCountSummary;
+    readonly expiresAt: number;
+}
+/** TTL 读缓存（时钟注入的纯逻辑，供单测）：未过期返回快照，过期或缺条返回 null。 */
+export declare function readCountCache(entry: CountCacheEntry | null, nowMs: number): FileCountSummary | null;
+/** 删除成功后失效计数缓存：下一次 count 拉取重新翻页，包含删除结果。 */
+export declare function invalidateCountCache(): void;
 export declare function listApi(after?: string): Promise<{
     rows: FileRow[];
     hasMore: boolean;

package/lib/types/client/paging.d.ts

@@ -0,0 +1,13 @@
+/** 文件面板渲染窗口纯逻辑（对齐 archive-manage spec 09）：数据分页与 DOM 渲染窗口分离。 @module dsh-file-manage/client/paging */
+/** 渲染窗口大小：每次渲染的行数上限，「加载更多」按此递增（archive 同款 100）。 */
+export declare const RENDER_PAGE_SIZE = 100;
+/**
+ * 数据分页大小：每次 list 拉取的行数。必须大于渲染窗口（200 > 100），
+ * 窗口才会真正裁剪 DOM——否则窗口永远跑在数据前面，退化回全量渲染。
+ */
+export declare const FILE_PAGE_SIZE = 200;
+/** 窗口内可见行数：min(已加载行数, 窗口上限)；负数/小数钳到安全值（不抛）。 */
+export declare function renderedRowCount(totalRows: number, renderLimit: number): number;
+/** 「加载更多」是否可见：窗口未盖满已加载行（纯延伸窗口），或服务端还有更多数据（延伸窗口 + 拉页）。 */
+export declare function hasLoadMore(totalRows: number, renderLimit: number, dataHasMore: boolean): boolean;
+//# sourceMappingURL=paging.d.ts.map

package/lib/types/client/styles.d.ts

@@ -56,11 +56,16 @@ export declare const styles: {
         fontSize: number;
         lineHeight: string;
     };
-    readonly footerBar: {
+    /** 合集品牌 footer：固定面板底部（滚动区之外），顶部分割线与内容区隔开；紧凑规格。 */
+    readonly footer: {
         flex: string;
-        display: "flex";
-        justifyContent: "center";
+        boxSizing: "border-box";
         padding: string;
+        borderTop: string;
+        textAlign: "center";
+        fontSize: number;
+        lineHeight: string;
+        color: "var(--dsw-alias-label-tertiary, #8a919f)";
     };
 };
 //# sourceMappingURL=styles.d.ts.map

package/lib/types/compat.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 宿主兼容自检（根 AGENTS《插件与宿主兼容》）——纯能力版。
+ *
+ * 本插件不读 dsh 会话数据，因此没有会话格式门；守卫点是**宿主能力面**
+ * （依赖的服务/方法/导出是否存在，以及运行环境特性）。不满足即抛错自停用，
+ * 绝不带病运行。判定与文案是纯逻辑，供单测。
+ */
+/** 一项能力：`name` 进日志，`ok` 由调用方探测（服务/方法/导出/浏览器特性是否存在）。 */
+export interface HostCapability {
+    readonly name: string;
+    readonly ok: boolean;
+}
+/**
+ * 缺失的能力名（纯逻辑，供单测）。
+ * @param capabilities - 本插件声明的能力。
+ * @returns 未满足的能力名，按声明顺序。
+ */
+export declare function missingCapabilities(capabilities: readonly HostCapability[]): string[];
+/**
+ * 能力门：任一必需能力缺失即抛错（自停用）。
+ *
+ * cordis 逐插件捕获 `apply` 异常并把该插件标为 inactive，dsh 与其余插件不受影响
+ * （已查证 cordis `lib/index.js:1350-1362`）。抛错前先记一条面向用户的告警，
+ * 说明「为什么停用、怎么恢复」。
+ * @param ctx - 插件上下文（只用到 logger）。
+ * @param pluginName - 插件名（日志与错误前缀）。
+ * @param capabilities - 本插件声明的能力。
+ */
+export declare function assertCapabilities(ctx: {
+    logger: {
+        warn(message: string): void;
+    };
+}, pluginName: string, capabilities: readonly HostCapability[]): void;
+//# sourceMappingURL=compat.d.ts.map

package/lib/types/host.d.ts

@@ -6,5 +6,5 @@ export declare const inject: string[];
  * host half 入口：注册 prefix 路由（list / 单条删除），全部副作用挂在 apply 的 effect 上。
  * @param ctx - DSH 插件上下文。
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context): Promise<void>;
 //# sourceMappingURL=host.d.ts.map