dsh-archive-preview 0.0.0-stage → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.3
+
+- 配置不再写死可信域名：默认读取 dsh web 启动参数里的 `--trusted-host`。
+
+## 0.1.2
+
+- 更新 README。
+
+## 0.1.1
+
+- 修复 TAR 条目读取的二次复杂度：16MB 条目从约 2.5 秒降到约 0.3 秒。
+
+## 0.1.0
+
+- 首个版本：右侧栏文档预览查看 zip/7z/rar/tar 等压缩包。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jackylong
+
+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,99 @@
-# Temporary Holding Version
+# dsh-archive-preview
 
-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 右侧栏「文档预览」里查看压缩包：目录树、文本、图片、单文件下载。
+
+注册在核心文档预览注册表（`documentPreviews`）。走核心右侧栏打开的文件都会命中：工作区文件树、聊天里的文件引用，以及其它插件通过 `openResource` 打开的路径。不依赖其它插件。
+
+## 功能
+
+- **目录浏览**：逐层进入文件夹，面包屑返回，按名称筛选；显示每个文件的大小与修改时间；加密条目单独标注。
+- **在线预览**：文本（txt/md/json/csv/代码等，支持 UTF-8 与 GBK）与图片（png/jpg/gif/webp/bmp/ico/avif）；其余类型只提供下载。
+- **单文件下载**：文件名按 RFC 5987 编码。
+- **只在内存解压**：条目不写入磁盘。
+
+## 支持的格式
+
+| 格式 | 读取方式 | 说明 |
+|---|---|---|
+| `.zip` | 本插件纯 JS（零依赖） | 只读中央目录，按需解压 |
+| `.tar` | 本插件纯 JS 流式解析 | 支持 GNU 长名与 PAX 头 |
+| `.tar.gz` / `.tgz` | Node `zlib` + 纯 JS TAR | |
+| `.tar.bz2` / `.tbz2` / `.tbz` | 系统 `bzip2` 解压流 + 纯 JS TAR | |
+| `.tar.xz` / `.txz` | 系统 `xz` 解压流 + 纯 JS TAR | |
+| `.tar.zst` / `.tar.zstd` / `.tzst` | 系统 `zstd` 解压流 + 纯 JS TAR | |
+| `.7z` / `.rar` | 系统 `7z`（RAR 无 7z 时退 `unrar`） | 需要 7z / unrar |
+| `.gz` / `.bz2` / `.xz` / `.zst`（单文件） | 系统 `7z` | 条目名取自文件名 |
+
+不支持的格式、加密条目、超出上限的条目会返回具体原因，并提供下载入口。
+
+## 安全与上限
+
+- 仅服务 loopback 与 `trustedHosts` 中的域名；跨站请求返回 403。
+- 仅接受常见压缩包扩展名；`realpath` 后必须位于 `allowedRoots` 内，软链越界返回 403。
+- 上限：条目解压 32MB、文本预览 1.5MB、图片 24MB；超过上限返回「请下载」。
+- 列表最多 20000 条，超出截断。
+- 外部工具按参数数组调用，不经过 shell。
+- 内联 SVG 以图片 MIME 返回，并附 `sandbox` CSP。
+
+## 安装
+
+在 DSH 的插件管理里安装 `dsh-archive-preview`，装完重启 dsh web。
+
+需要 7z / rar 时，主机要有 `7z`（RAR 没有 7z 时用 `unrar`）；zip、tar、tar.gz 不需要额外工具。
+
+## 配置（`cordis.patch.yml`）
+
+```yaml
+- insert:
+    - id: dsh-archive-preview
+      name: dsh-archive-preview
+      config:
+        # 可选；不写就跟 dsh web 的 --trusted-host 一致
+        trustedHosts: ['<your-domain>']
+        allowedRoots: !!js "[dshHomePath('..')]"
+```
+
+- `trustedHosts`：额外放行的反代域名；不写默认读 dsh web 启动参数里的 `--trusted-host`（loopback 始终放行）。
+- `allowedRoots`：允许读取压缩包的根目录；不写默认 `$DSH_HOME` 的父目录（通常是用户家目录）。
+
+## 接口
+
+- `GET /api/dsh-archive-preview/list?path=…[&cwd=…]` → 条目列表 JSON
+- `GET /api/dsh-archive-preview/entry?path=…&name=…[&cwd=…][&download=1]` → 文本/图片原样返回，其余下载
+
+两个路由都要求可信 Host/Origin；`path` 可为绝对路径，或相对 `cwd` / 工作区根的路径。
+
+## 已知限制
+
+- 加密压缩包不解密，只列出并标注。
+- 嵌套压缩包（zip 里套 zip）不递归展开。
+- TAR 每次取条目都会重扫整包（压缩流没有随机访问），大包连续点多个文件会重复解压。
+- 单流格式（`.gz`/`.bz2`/`.xz`/`.zst`）的条目名取自文件名；`.gz` 头里带原始名时用原始名。
+- RAR 依赖 `7z`/`unrar`，开发环境没有 RAR 样本，未做真机用例。
+- 大包的目录列表一次性读完再渲染；条目数超过 2 万会截断。
+
+## 开发
+
+```sh
+node --test test/*.test.mjs
+```
+
+改 `client/client.js` 刷新页面即可；改 `lib/` 需要重启 dsh web。
+
+测试自带最小 ZIP/TAR 写入器（不引第三方包），覆盖 store/deflate、GBK 文件名、加密标记、TAR 长名/PAX、路径白名单与信任门；有 `7z` 时会真跑一遍 7z 与单流格式。
+
+## 目录结构
+
+```
+lib/zip.js         ZIP 中央目录 + 条目解压（零依赖）
+lib/tar.js         TAR 流式解析 + gzip/xz/bz2/zstd 解压流
+lib/sevenzip.js    7z / unrar 调用与输出解析
+lib/archive.js     类型识别与统一读取入口
+lib/encoding.js    UTF-8 → GBK → latin1 容错解码
+lib/index.js       两个 HTTP 路由、信任门、路径白名单、上限
+client/client.js   React 预览正文（目录树/搜索/文本/图片/下载）
+```
+
+## License
+
+MIT

package/client/client.js

@@ -0,0 +1,464 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-archive-preview',
+  factory: (require) => {
+    const module = { exports: {} }
+    const exports = module.exports
+    const React = require('react')
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    // ===== dsh-archive-preview: 压缩包文档预览 =====
+    // 只做一件事：把常见压缩包（zip/7z/rar/tar/tar.gz…）注册进核心的文档预览注册表，
+    // 并用**同一个 id** 提供 React 正文。
+    //   · 元数据契约：ctx.documentPreviews.register({ id, extensions, binaryExtensions, priority, title, loading, wrap })
+    //   · 正文契约：同 id 注册 keyed / Session 作用域子 slot `sidebar.right.tab.document`；
+    //     `loading:'renderer'` ⇒ 正文自己取内容，并拿到 `content: { kind:'renderer', revision, loaded, failed, reload }`。
+    //   · `priority:'extension'` 才排在核心的纯文本兜底之前（否则 .zip 会被核心当"二进制容器"显示不支持）。
+    //   · 数据全走本插件自己的两个 JSON 路由（见 lib/index.js），不碰核心、不改别的插件。
+    //
+    // 覆盖的四个入口（都经核心 `sidebarRight.openResource` 到同一个注册表）：
+    //   会话产物卡片 / 会话文件面板 / 文件管理页签 / 原生工作区文件树。
+
+    const PREVIEW_ID = 'dsh-archive-preview/preview'
+    const LIST_ROUTE = '/api/dsh-archive-preview/list'
+    const ENTRY_ROUTE = '/api/dsh-archive-preview/entry'
+
+    const EXTENSIONS = [
+      '.zip', '.7z', '.rar',
+      '.tar', '.tar.gz', '.tgz', '.tar.bz2', '.tbz2', '.tbz', '.tar.xz', '.txz', '.tar.zst', '.tar.zstd', '.tzst',
+      '.gz', '.bz2', '.xz', '.zst', '.zstd',
+    ]
+    const BINARY_EXTENSIONS = [
+      'zip', '7z', 'rar', 'tar', 'tar.gz', 'tgz', 'tar.bz2', 'tbz2', 'tbz', 'tar.xz', 'txz', 'tar.zst', 'tar.zstd', 'tzst',
+      'gz', 'bz2', 'xz', 'zst', 'zstd',
+    ]
+
+    const TEXT_EXTENSIONS = /\.(txt|text|md|markdown|log|json|jsonl|ndjson|csv|tsv|xml|html?|css|scss|less|js|mjs|cjs|jsx|ts|tsx|yml|yaml|toml|ini|conf|cfg|properties|env|sh|bash|zsh|fish|ps1|bat|cmd|py|rb|go|rs|java|kt|swift|c|h|cc|cpp|hpp|cs|php|lua|pl|r|sql|vue|svelte|astro|svg|patch|diff)$/i
+    const IMAGE_EXTENSIONS = /\.(png|jpe?g|gif|webp|bmp|ico|avif)$/i
+
+    /** 只在"确实像编码"时才解：逐段 decodeURIComponent，解不开就原样。 */
+    const pathMaybeDecoded = (value) => {
+      let text = typeof value === 'string' ? value : ''
+      if (text === '' || text.indexOf('%') === -1) return text
+      for (let i = 0; i < 3; i += 1) {
+        try {
+          const decoded = text.split('/').map((segment) => decodeURIComponent(segment)).join('/')
+          if (decoded === text) break
+          text = decoded
+        } catch { break }
+      }
+      return text
+    }
+
+    /** 从核心资源地址里抠出文件路径（纯函数）；认不出返回 `''`（服务端按 cwd / 工作区根兜底）。 */
+    const pathFromResourceAddress = (address) => {
+      try {
+        const PREFIX = 'dsh-resource://file/'
+        const raw = String(address || '')
+        if (raw.indexOf(PREFIX) !== 0) return ''
+        const cut = raw.search(/[?#]/)
+        const parts = (cut === -1 ? raw.slice(PREFIX.length) : raw.slice(PREFIX.length, cut)).split('/')
+        const scope = parts.shift()
+        if (scope === 'session') {
+          if (parts.length < 2 || parts[0] === '') return ''
+          return parts.slice(1).map(decodeURIComponent).join('/')
+        }
+        if (scope === 'absolute') {
+          const rest = parts.filter((segment) => segment !== '')
+          return rest.length === 0 ? '' : '/' + rest.map(decodeURIComponent).join('/')
+        }
+        return ''
+      } catch { return '' }
+    }
+
+    /** 会话当前工作目录（核心挂在 window 上的约定值）。 */
+    const currentCwd = () => {
+      try { return String(window.__dshCurrentCwd || '') } catch { return '' }
+    }
+
+    const formatSize = (bytes) => {
+      const value = Number(bytes) || 0
+      if (value < 1024) return value + ' B'
+      if (value < 1048576) return (value / 1024).toFixed(1) + ' KiB'
+      if (value < 1073741824) return (value / 1048576).toFixed(1) + ' MiB'
+      return (value / 1073741824).toFixed(2) + ' GiB'
+    }
+
+    const formatTime = (ms) => {
+      const value = Number(ms) || 0
+      if (value <= 0) return ''
+      try {
+        const date = new Date(value)
+        const pad = (n) => String(n).padStart(2, '0')
+        return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`
+      } catch { return '' }
+    }
+
+    const baseNameOf = (name) => String(name || '').replace(/\/+$/, '').split('/').pop() || String(name || '')
+
+    const extensionOf = (name) => {
+      const match = /\.([A-Za-z0-9]+)$/.exec(String(name || ''))
+      return match ? match[1].toLowerCase() : ''
+    }
+
+    const iconOf = (name) => {
+      const extension = extensionOf(name)
+      if (IMAGE_EXTENSIONS.test(name)) return '🖼️'
+      if (TEXT_EXTENSIONS.test(name)) return '📝'
+      if (extension === 'pdf') return '📕'
+      if (extension === 'docx' || extension === 'doc') return '📄'
+      if (extension === 'xlsx' || extension === 'xls' || extension === 'csv') return '📊'
+      if (extension === 'pptx' || extension === 'ppt') return '📽️'
+      if (/^(zip|7z|rar|tar|gz|bz2|xz|zst|tgz|tbz2|txz)$/.test(extension)) return '🗜️'
+      return '📄'
+    }
+
+    /** 把条目列表建成目录树（纯函数；目录条目与隐式父目录都算）。 */
+    const buildTree = (entries) => {
+      const root = { name: '', dirs: new Map(), files: [] }
+      const ensure = (parts) => {
+        let node = root
+        for (const part of parts) {
+          if (!node.dirs.has(part)) node.dirs.set(part, { name: part, dirs: new Map(), files: [] })
+          node = node.dirs.get(part)
+        }
+        return node
+      }
+      for (const entry of entries || []) {
+        const raw = String(entry.name || '').replace(/\\/g, '/').replace(/\/+$/, '')
+        if (raw === '') continue
+        const parts = raw.split('/').filter((part) => part !== '' && part !== '.')
+        if (parts.length === 0) continue
+        if (entry.dir === true) { ensure(parts); continue }
+        const parent = ensure(parts.slice(0, -1))
+        parent.files.push({ ...entry, name: raw, base: parts[parts.length - 1] })
+      }
+      return root
+    }
+
+    const nodeAt = (tree, dirPath) => {
+      let node = tree
+      for (const part of String(dirPath || '').split('/').filter(Boolean)) {
+        if (!node.dirs.has(part)) return node
+        node = node.dirs.get(part)
+      }
+      return node
+    }
+
+    const countFiles = (node) => {
+      let total = node.files.length
+      for (const child of node.dirs.values()) total += countFiles(child)
+      return total
+    }
+
+    /** 全部文件（搜索时用平铺列表）。 */
+    const flattenFiles = (node, prefix, out) => {
+      for (const file of node.files) out.push({ ...file, displayPath: prefix === '' ? file.base : prefix + '/' + file.base })
+      for (const [name, child] of node.dirs) flattenFiles(child, prefix === '' ? name : prefix + '/' + name, out)
+      return out
+    }
+
+    const CSS = `
+.dsh-archive{position:absolute;inset:0;display:flex;flex-direction:column;background:var(--dsw-alias-bg-document-preview,#fff);color:var(--dsw-alias-label-primary);font:12px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;overflow:hidden}
+.dsh-archive-toolbar{flex:none;display:flex;align-items:center;gap:8px;padding:8px 12px;border-bottom:.5px solid var(--dsw-alias-border-l2);flex-wrap:wrap}
+.dsh-archive-kind{flex:none;font-size:10px;line-height:16px;padding:1px 6px;border-radius:5px;border:.5px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);white-space:nowrap}
+.dsh-archive-crumbs{flex:1 1 auto;min-width:0;display:flex;align-items:center;gap:2px;overflow:hidden}
+.dsh-archive-crumb{border:0;background:transparent;color:var(--dsw-alias-state-business-primary);font:inherit;font-size:12px;padding:1px 4px;border-radius:5px;cursor:pointer;white-space:nowrap}
+.dsh-archive-crumb:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-archive-crumb-current{color:var(--dsw-alias-label-primary);cursor:default}
+.dsh-archive-crumb-current:hover{background:transparent}
+.dsh-archive-search{flex:0 1 150px;min-width:96px;box-sizing:border-box;padding:3px 8px;border:.5px solid var(--dsw-alias-border-l2);border-radius:7px;background:transparent;color:inherit;font:inherit;font-size:12px}
+.dsh-archive-scroll{flex:1 1 auto;min-height:0;overflow:auto;padding:6px 8px 12px}
+.dsh-archive-meta{flex:none;color:var(--dsw-alias-label-tertiary);font-size:11px;padding:2px 2px 6px}
+.dsh-archive-banner{flex:none;margin:0 0 8px;padding:6px 10px;border-radius:8px;border:.5px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);font-size:11px;background:var(--dsw-alias-bg-layer-2)}
+.dsh-archive-row{display:flex;align-items:center;gap:8px;width:100%;box-sizing:border-box;padding:6px 10px;border:0;border-radius:7px;background:transparent;color:inherit;font:inherit;font-size:12px;text-align:left;cursor:pointer}
+.dsh-archive-row:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-archive-ico{flex:none;width:18px;text-align:center}
+.dsh-archive-name{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dsh-archive-size,.dsh-archive-time{flex:none;color:var(--dsw-alias-label-tertiary);font-size:11px;white-space:nowrap}
+.dsh-archive-size{width:78px;text-align:right}
+.dsh-archive-time{width:112px;text-align:right}
+.dsh-archive-lock{flex:none;font-size:11px;color:var(--dsw-alias-label-tertiary)}
+.dsh-archive-state{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:10px;height:100%;min-height:160px;padding:24px;text-align:center;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1.8}
+.dsh-archive-state strong{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:600}
+.dsh-archive-state button{border:.5px solid var(--dsw-alias-border-l2);background:transparent;color:inherit;font:inherit;padding:4px 14px;border-radius:7px;cursor:pointer}
+.dsh-archive-state button:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-archive-detail{display:flex;flex-direction:column;height:100%;min-height:0}
+.dsh-archive-detail-head{flex:none;display:flex;align-items:center;gap:8px;padding:2px 2px 8px}
+.dsh-archive-back{flex:none;border:.5px solid var(--dsw-alias-border-l2);background:transparent;color:inherit;font:inherit;font-size:12px;padding:3px 10px;border-radius:7px;cursor:pointer}
+.dsh-archive-back:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-archive-detail-name{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:12px;font-weight:600}
+.dsh-archive-detail-size{flex:none;color:var(--dsw-alias-label-tertiary);font-size:11px}
+.dsh-archive-download{flex:none;border:.5px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-state-business-primary);font:inherit;font-size:12px;padding:3px 10px;border-radius:7px;text-decoration:none;cursor:pointer}
+.dsh-archive-download:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.dsh-archive-detail-body{flex:1 1 auto;min-height:0;overflow:auto}
+.dsh-archive-text{margin:0;padding:10px 12px;white-space:pre-wrap;word-break:break-word;font:12px/1.7 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;color:var(--dsw-alias-label-primary)}
+.dsh-archive-image{display:block;max-width:100%;height:auto;margin:8px auto;border-radius:8px}
+@media (max-width:560px){.dsh-archive-time{display:none}.dsh-archive-size{width:auto}}
+`
+
+    /** 正文：目录浏览（树 + 搜索）＋ 条目预览（文本/图片/下载）。 */
+    const ArchivePreviewBody = (props) => {
+      const content = props ? props.content : undefined
+      const resourceAddress = String((props && props.resourceAddress) || '')
+      const resource = props && typeof props.useResource === 'function' ? props.useResource(resourceAddress) : undefined
+      const value = resource && resource.value ? resource.value : undefined
+      const absolutePath = pathMaybeDecoded(value && typeof value.absolutePath === 'string' ? value.absolutePath : '')
+      const version = value ? value.version : undefined
+      const revision = content && content.kind === 'renderer' ? content.revision : 0
+      const filePath = absolutePath !== '' ? absolutePath : pathFromResourceAddress(resourceAddress)
+      const cwd = absolutePath !== '' ? '' : currentCwd()
+
+      const [listing, setListing] = React.useState({ status: 'loading' })
+      const [dirPath, setDirPath] = React.useState('')
+      const [query, setQuery] = React.useState('')
+      const [selected, setSelected] = React.useState(null)
+      const [detail, setDetail] = React.useState({ status: 'idle' })
+      const reportedRef = React.useRef('')
+
+      React.useEffect(() => {
+        let alive = true
+        setListing({ status: 'loading' })
+        setSelected(null)
+        setDetail({ status: 'idle' })
+        setDirPath('')
+        setQuery('')
+        if (filePath === '') {
+          setListing({ status: 'error', error: '拿不到文件路径（这个入口没有给出可预览的本地路径）' })
+          return undefined
+        }
+        let url = LIST_ROUTE + '?path=' + encodeURIComponent(filePath)
+        if (cwd !== '') url += '&cwd=' + encodeURIComponent(cwd)
+        fetch(url, { cache: 'no-store', credentials: 'same-origin' })
+          .then(async (response) => {
+            const body = await response.json().catch(() => ({}))
+            if (!response.ok || body.ok !== true) throw new Error(body.error || ('HTTP ' + response.status))
+            return body
+          })
+          .then((data) => {
+            if (!alive) return
+            setListing({ status: 'ready', data })
+            if (version !== undefined && content && content.kind === 'renderer') {
+              const key = String(revision) + ':' + String(version)
+              if (reportedRef.current !== key) {
+                reportedRef.current = key
+                try { content.loaded(version) } catch { /* 忽略 */ }
+              }
+            }
+          })
+          .catch((error) => {
+            if (!alive) return
+            setListing({ status: 'error', error: String((error && error.message) || error) })
+            try { if (content && content.kind === 'renderer') content.failed() } catch { /* 忽略 */ }
+          })
+        return () => { alive = false }
+      }, [filePath, cwd, revision])
+
+      // 条目预览：文本拉回来、图片直接交给 <img>、其余类型只给下载。
+      React.useEffect(() => {
+        if (selected === null) { setDetail({ status: 'idle' }); return undefined }
+        if (selected.encrypted === true) { setDetail({ status: 'encrypted' }); return undefined }
+        if (IMAGE_EXTENSIONS.test(selected.name)) { setDetail({ status: 'image' }); return undefined }
+        if (!TEXT_EXTENSIONS.test(selected.name)) { setDetail({ status: 'binary' }); return undefined }
+        let alive = true
+        const controller = typeof AbortController === 'function' ? new AbortController() : null
+        setDetail({ status: 'loading' })
+        let url = ENTRY_ROUTE + '?path=' + encodeURIComponent(filePath) + '&name=' + encodeURIComponent(selected.name)
+        if (cwd !== '') url += '&cwd=' + encodeURIComponent(cwd)
+        fetch(url, { cache: 'no-store', credentials: 'same-origin', signal: controller ? controller.signal : undefined })
+          .then(async (response) => {
+            if (!response.ok) {
+              const body = await response.json().catch(() => ({}))
+              throw new Error(body.error || ('HTTP ' + response.status))
+            }
+            return response.text()
+          })
+          .then((text) => { if (alive) setDetail({ status: 'text', text }) })
+          .catch((error) => {
+            if (!alive) return
+            if (error && error.name === 'AbortError') return
+            setDetail({ status: 'error', error: String((error && error.message) || error) })
+          })
+        return () => { alive = false; try { if (controller) controller.abort() } catch { /* 忽略 */ } }
+      }, [selected, filePath, cwd])
+
+      const reload = () => { try { if (content && content.kind === 'renderer') content.reload() } catch { /* 忽略 */ } }
+
+      const rootStyle = { position: 'absolute', inset: '0' }
+      const styleElement = React.createElement('style', { key: 'css' }, CSS)
+
+      if (listing.status === 'loading') {
+        return React.createElement('div', { className: 'dsh-archive', style: rootStyle }, styleElement,
+          React.createElement('div', { className: 'dsh-archive-state' },
+            React.createElement('strong', null, '正在读取压缩包…'),
+            React.createElement('span', null, absolutePath !== '' ? absolutePath : filePath)))
+      }
+      if (listing.status === 'error') {
+        return React.createElement('div', { className: 'dsh-archive', style: rootStyle }, styleElement,
+          React.createElement('div', { className: 'dsh-archive-state' },
+            React.createElement('strong', null, '打不开这个压缩包'),
+            React.createElement('span', null, listing.error),
+            React.createElement('button', { type: 'button', onClick: reload }, '重试')))
+      }
+
+      const data = listing.data
+      const tree = buildTree(data.entries)
+      const baseUrl = (name, download) => {
+        let url = ENTRY_ROUTE + '?path=' + encodeURIComponent(filePath) + '&name=' + encodeURIComponent(name)
+        if (cwd !== '') url += '&cwd=' + encodeURIComponent(cwd)
+        if (download === true) url += '&download=1'
+        return url
+      }
+
+      const openEntry = (file) => { setSelected(file); }
+      const goDir = (next) => { setDirPath(next); setQuery(''); setSelected(null) }
+      const back = () => { setSelected(null); setDetail({ status: 'idle' }) }
+
+      const toolbar = React.createElement('div', { className: 'dsh-archive-toolbar', key: 'toolbar' }, [
+        React.createElement('span', { className: 'dsh-archive-kind', key: 'kind', title: data.note || '' }, data.label || '压缩包'),
+        React.createElement('div', { className: 'dsh-archive-crumbs', key: 'crumbs' }, (() => {
+          const items = [React.createElement('button', {
+            key: 'root', type: 'button', className: 'dsh-archive-crumb' + (dirPath === '' && query === '' ? ' dsh-archive-crumb-current' : ''),
+            onClick: () => goDir(''),
+          }, data.name)]
+          const segments = dirPath === '' ? [] : dirPath.split('/')
+          segments.forEach((segment, index) => {
+            const target = segments.slice(0, index + 1).join('/')
+            const isLast = index === segments.length - 1
+            items.push(React.createElement('span', { key: 'sep' + index, className: 'dsh-archive-crumb-current' }, '/'))
+            items.push(React.createElement('button', {
+              key: 'seg' + index, type: 'button',
+              className: 'dsh-archive-crumb' + (isLast ? ' dsh-archive-crumb-current' : ''),
+              onClick: () => goDir(target),
+            }, segment))
+          })
+          return items
+        })()),
+        React.createElement('input', {
+          key: 'search', className: 'dsh-archive-search', type: 'search',
+          placeholder: '筛选条目…', value: query, spellCheck: false,
+          onChange: (event) => { setQuery(event.target.value); setSelected(null) },
+        }),
+      ])
+
+      const meta = React.createElement('div', { className: 'dsh-archive-meta', key: 'meta' },
+        `${data.total} 个条目 · 共 ${formatSize(data.bytes)}` + (data.truncated === true ? ' · 条目太多，只显示前一部分' : ''))
+
+      let body
+      if (selected !== null) {
+        const detailHead = React.createElement('div', { className: 'dsh-archive-detail-head', key: 'head' }, [
+          React.createElement('button', { className: 'dsh-archive-back', key: 'back', type: 'button', onClick: back }, '← 返回'),
+          React.createElement('span', { className: 'dsh-archive-detail-name', key: 'name', title: selected.name }, baseNameOf(selected.name)),
+          React.createElement('span', { className: 'dsh-archive-detail-size', key: 'size' }, formatSize(selected.size)),
+          React.createElement('a', {
+            className: 'dsh-archive-download', key: 'dl', href: baseUrl(selected.name, true),
+            download: baseNameOf(selected.name),
+          }, '下载'),
+        ])
+
+        let detailBody
+        if (detail.status === 'loading') detailBody = React.createElement('div', { className: 'dsh-archive-state' }, '正在读取…')
+        else if (detail.status === 'text') detailBody = React.createElement('pre', { className: 'dsh-archive-text' }, detail.text)
+        else if (detail.status === 'image') detailBody = React.createElement('img', {
+          className: 'dsh-archive-image', src: baseUrl(selected.name, false), alt: baseNameOf(selected.name),
+          onError: () => setDetail({ status: 'error', error: '图片加载失败（可能不是有效图片或体积过大）' }),
+        })
+        else if (detail.status === 'encrypted') detailBody = React.createElement('div', { className: 'dsh-archive-state' }, '这个条目已加密，无法在线预览。可下载后用对应工具解密查看。')
+        else if (detail.status === 'binary') detailBody = React.createElement('div', { className: 'dsh-archive-state' }, '这种类型不能在线预览，点右上角「下载」查看。')
+        else if (detail.status === 'error') detailBody = React.createElement('div', { className: 'dsh-archive-state' }, detail.error)
+        else detailBody = React.createElement('div', { className: 'dsh-archive-state' }, '正在准备…')
+
+        body = React.createElement('div', { className: 'dsh-archive-detail', key: 'detail' },
+          detailHead,
+          React.createElement('div', { className: 'dsh-archive-detail-body' }, detailBody))
+      } else {
+        const children = [meta]
+        if (query.trim() !== '') {
+          const keyword = query.trim().toLowerCase()
+          const hits = flattenFiles(tree, '', []).filter((file) => file.displayPath.toLowerCase().indexOf(keyword) !== -1)
+          if (hits.length === 0) children.push(React.createElement('div', { className: 'dsh-archive-state' }, '没有匹配的条目'))
+          for (const file of hits) children.push(React.createElement('button', {
+            key: 'f' + file.name, type: 'button', className: 'dsh-archive-row',
+            onClick: () => openEntry(file), title: file.displayPath,
+          }, [
+            React.createElement('span', { className: 'dsh-archive-ico', key: 'i' }, iconOf(file.base)),
+            React.createElement('span', { className: 'dsh-archive-name', key: 'n' }, file.displayPath),
+            file.encrypted === true ? React.createElement('span', { className: 'dsh-archive-lock', key: 'l' }, '🔒') : null,
+            React.createElement('span', { className: 'dsh-archive-size', key: 's' }, formatSize(file.size)),
+          ]))
+        } else {
+          const node = nodeAt(tree, dirPath)
+          const dirs = Array.from(node.dirs.keys()).sort((a, b) => a.localeCompare(b, 'zh'))
+          if (dirs.length === 0 && node.files.length === 0) {
+            children.push(React.createElement('div', { className: 'dsh-archive-state' }, dirPath === '' && data.total === 0 ? '这个压缩包是空的' : '这个目录是空的'))
+          }
+          for (const name of dirs) {
+            const child = node.dirs.get(name)
+            const next = dirPath === '' ? name : dirPath + '/' + name
+            children.push(React.createElement('button', {
+              key: 'd' + next, type: 'button', className: 'dsh-archive-row',
+              onClick: () => goDir(next),
+            }, [
+              React.createElement('span', { className: 'dsh-archive-ico', key: 'i' }, '📁'),
+              React.createElement('span', { className: 'dsh-archive-name', key: 'n' }, name),
+              React.createElement('span', { className: 'dsh-archive-size', key: 's' }, `${countFiles(child)} 项`),
+            ]))
+          }
+          const files = node.files.slice().sort((a, b) => a.base.localeCompare(b.base, 'zh'))
+          for (const file of files) {
+            children.push(React.createElement('button', {
+              key: 'f' + file.name, type: 'button', className: 'dsh-archive-row',
+              onClick: () => openEntry(file), title: file.name,
+            }, [
+              React.createElement('span', { className: 'dsh-archive-ico', key: 'i' }, iconOf(file.base)),
+              React.createElement('span', { className: 'dsh-archive-name', key: 'n' }, file.base),
+              file.encrypted === true ? React.createElement('span', { className: 'dsh-archive-lock', key: 'l' }, '🔒') : null,
+              React.createElement('span', { className: 'dsh-archive-size', key: 's' }, formatSize(file.size)),
+              React.createElement('span', { className: 'dsh-archive-time', key: 't' }, formatTime(file.mtime)),
+            ]))
+          }
+        }
+        body = React.createElement('div', { className: 'dsh-archive-scroll', key: 'scroll', ref: props ? props.scrollportRef : undefined }, children)
+      }
+
+      return React.createElement('div', { className: 'dsh-archive', style: rootStyle }, [styleElement, toolbar, body])
+    }
+    // <<< dsh-archive-preview: preview body <<<
+
+    /** @param ctx - 客户端插件上下文（用到 `documentPreviews` 与 `slots` 两个服务）。 */
+    function apply(ctx) {
+      // 注册与样式各自独立兜底：样式失败绝不能连累注册（否则界面只表现"没反应"，极难定位）。
+      try {
+        ctx.inject(['documentPreviews'], (scope) => {
+          scope.effect(() => scope.documentPreviews.register({
+            id: PREVIEW_ID,
+            extensions: EXTENSIONS,
+            binaryExtensions: BINARY_EXTENSIONS,
+            priority: 'extension',
+            title: () => '压缩包预览',
+            loading: 'renderer',
+            wrap: false,
+          }), 'dsh-archive-preview: preview metadata')
+          scope.effect(() => scope.slots.inject('sidebar.right.tab.document', () => scope.slots.register({
+            name: 'sidebar.right.tab.document',
+            key: PREVIEW_ID,
+          }, ArchivePreviewBody)), 'dsh-archive-preview: preview body')
+        })
+      } catch (error) {
+        warn('preview registration failed:', error)
+      }
+    }
+
+    const warn = (...args) => {
+      try { console.warn('[dsh-archive-preview]', ...args) } catch { /* 忽略 */ }
+    }
+
+    // ⚠️ 插件级 inject 必须声明 `slots`：正文要注册到 keyed slot `sidebar.right.tab.document`，
+    //    而 `scope.slots` 只在插件级声明过该服务时才在注入作用域里可见。漏了它 ⇒ 静默无变化。
+    const inject = ['slots']
+    exports.apply = apply
+    exports.inject = inject
+    // 离线用例的纯函数钩子（宿主不会用到）。
+    exports.__test__ = { buildTree, nodeAt, pathFromResourceAddress, formatSize, formatTime, baseNameOf, iconOf, PREVIEW_ID, EXTENSIONS }
+    return module.exports
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-archive-preview 的 bundle patch：把插件插进 profile 的层栈。
+# 只声明本插件自己（入口、ID、它自己的配置）；不替核心或别的插件写配置。
+#
+# trustedHosts 复用宿主 Web 运行时那份可信域名/来源（与 dsh-long-plugins / dsh-long-cad 同一口径）：
+# 路由只服务 loopback 与这些反代域名，别的 Host/Origin 一律 403。
+- insert:
+    - id: dsh-archive-preview
+      name: dsh-archive-preview
+      config:
+        # 可信域名默认跟 dsh web 启动参数里的 --trusted-host 走（loopback 始终放行）；
+        # 需要额外放行时在这里加 trustedHosts: ['<your-domain>']。
+        # 允许读取压缩包的路径根。不写＝代码默认（$DSH_HOME 的父目录 = 用户家目录）。
+        # 换机/换盘符：删掉或改成那台机器的路径即可。
+        allowedRoots: !!js "[dshHomePath('..')]"

package/dsh.plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "dsh-archive-preview",
+  "description": "在右侧栏「文档预览」里直接看压缩包：列出 zip/7z/rar/tar/tar.gz/tar.bz2/tar.xz/gz 等常见格式的条目，预览文本与图片，下载单个文件。不落盘、不整包读入内存，条目解压有上限。 | Preview common archives in the DSH sidebar document preview — zip, 7z, rar, tar, tar.gz, tar.bz2, tar.xz, gz: browse entries, preview text and images, download individual files.",
+  "version": "0.1.3",
+  "entry": {
+    "name": "dsh-archive-preview"
+  },
+  "client": {
+    "platform": "web"
+  }
+}

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" role="img" aria-label="压缩包">
+  <path d="M4.2 8h15.6v11.2a1.6 1.6 0 0 1-1.6 1.6H5.8a1.6 1.6 0 0 1-1.6-1.6z"/>
+  <path d="M3 4.6h18v3.4H3z"/>
+  <path d="M11.2 4.6v3.4M12.8 8v3.2M11.2 11.2v3.2M12.8 14.4v2.6"/>
+  <circle cx="12" cy="18.6" r="1.1"/>
+</svg>