@jaxzhou/dsh-file-explorer 0.1.4 → 0.1.6

package/README.md

@@ -10,8 +10,9 @@ English | [中文](README.zh.md)
 
 A **Files** tab for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness),
 beside **Chat** and **Trajectory**: the session workspace as a tree, and a preview
-that adapts to what the file is — rendered Markdown, a JSON tree, highlighted
-source, an image, or plain text. Read-only, no configuration, nothing stored.
+that adapts to what the file is — rendered Markdown with its diagrams, a page of
+HTML, a JSON tree, highlighted source, an image, a PDF, or an unpacked Word, Excel
+or PowerPoint document. Read-only, no configuration, nothing stored.
 
 ```sh
 dsh plugin --profile web add @jaxzhou/dsh-file-explorer
@@ -21,13 +22,17 @@ dsh --profile web
 ## Demo
 
 [![The Files tab beside Chat and Trajectory: a workspace tree on the left, and a
-rendered Markdown document on the right whose toolbar carries Copy, Source and
-Export PDF](media/demo.gif)](media/demo.mp4)
+rendered Markdown document on the right](media/demo.gif)](media/demo.mp4)
 
 *15 seconds — click for the full-quality MP4.* A primary-school maths workspace: a
 lesson document rendered with its tables, the **Source** toggle showing the
-Markdown behind it, a second document open beside it in its own tab, and **Export
-PDF**, which hands the page to the browser's print dialog.
+Markdown behind it, a second document open beside it in its own tab, and an export
+of it to PDF.
+
+**The recording is an older build than the list below.** It predates Mermaid
+diagrams, the PDF and Office previews and the pane's **Download** control, and it
+still shows an export handing the page to the browser's print dialog — which no
+export does now.
 
 ## What you get
 
@@ -44,20 +49,41 @@ The right pane picks each tab's body from the file:
 
 | Category | Preview |
 |---|---|
-| **Markdown** | Rendered GFM — headings, tables, task lists, quotes, math, footnotes, images referenced beside the file, highlighted code fences — with a **Source** toggle, and **Export PDF** |
-| **HTML** | Drawn as a page in a sandboxed frame: the file's own CSS applies, and its scripts run in an opaque origin that cannot reach this application. With a **Source** toggle, and **Export PDF** |
+| **Markdown** | Rendered GFM — headings, tables, task lists, quotes, math, footnotes, images referenced beside the file, highlighted code fences, and **Mermaid diagrams** — with a **Source** toggle and an **Export** menu |
+| **HTML** | Drawn as a page in a sandboxed frame: the file's own CSS applies, and its scripts run in an opaque origin that cannot reach this application. With a **Source** toggle and an **Export** menu |
 | **JSON** | A collapsible tree with per-value copy, and the same toggle |
 | **Source code** | Syntax highlighting, line numbers, and a copy button for 24 grammars: TypeScript/JavaScript, shell, Python, Ruby, Go, Rust, Java, C, C++, C#, Kotlin, Swift, PHP, YAML, TOML, INI, HTML, CSS, SCSS, Less, SQL, XML, Lua, MDX |
 | **Images** | PNG, JPEG, GIF, WebP, AVIF, BMP, ICO and SVG, drawn to the pane. An SVG goes through `<img>`, so its scripts never run |
-| **Anything else** | Numbered plain text — an unmapped suffix (`.vue`, `.proto`, `.txt`) stays plain rather than guessing a wrong grammar |
+| **PDF** | Drawn by the browser's own PDF reader, from the file's bytes — so its text is real text |
+| **Word, Excel, PowerPoint** | `.docx`, `.xlsx` and `.pptx` unpacked in the page: a document's headings, lists, tables, pictures and code; a workbook's sheets as a grid, with the dates it stores as numbers shown as dates; a deck's slides as an outline of their text and pictures |
+| **Anything else** | Numbered plain text — an unmapped suffix (`.vue`, `.proto`, `.txt`) stays plain rather than guessing a wrong grammar. The legacy binary Office formats (`.doc`, `.xls`, `.ppt`) are not previewed: the pane says so and offers the download |
+
+A **Mermaid** code fence (` ```mermaid `) is a diagram, not source, so the pane
+draws it: flowcharts, sequence diagrams, state, class, ER, gantt, pie and the
+rest of what Mermaid 11 understands. The drawing is a picture everywhere it
+appears — the preview, the PDF page, and the Word document all carry the same
+image — so what you see is what exports. A diagram Mermaid cannot parse keeps its
+source, with the failure named above it.
 
 Text previews wrap at their spaces and keep every word whole; an image reads its
-complete bytes. Every text body carries a **Copy** control in the pane's toolbar,
-which copies the file's own text — a rendered Markdown document copies its
-Markdown source. A rendered Markdown or HTML file also carries **Export PDF**,
-which hands the page to the browser's print dialog: every browser offers "Save as
-PDF" there, and its own layout engine keeps the text as text rather than
-rasterising the page the way a canvas-based PDF library would.
+complete bytes.
+
+Every preview carries **Download** in the pane's toolbar, which saves the file
+itself — not a conversion of it, which is why it is the one control that works for
+every kind of file, including the ones this pane will not draw. Every text body
+carries **Copy**, which copies the file's own text — a rendered Markdown document
+copies its Markdown source.
+
+A rendered Markdown or HTML document also carries **Export**, which **downloads a
+file directly** — no print dialog — in either of two formats:
+
+| Format | What it is |
+|---|---|
+| **PDF** | A picture of the page, laid out as A4 and sliced to fit. The text in it is not selectable. That is deliberate: a text-mode PDF of a Chinese document would need a CJK font embedded in the plugin, which is megabytes for a preview tool |
+| **Word** (`.docx`) | A real Word document: headings, lists, tables, code and images, with the text still text — editable, searchable, and rendered with Word's own fonts. Chinese included |
+
+A document's own local assets come with it: the images a Markdown file references
+beside it, and the images and stylesheets an HTML file links to.
 
 ## Requirements
 
@@ -119,6 +145,11 @@ restart the profile.
   state lives in memory and is discarded with the session.
 - **Inert Host half.** The package's Node side registers no service, tool, prompt
   section, or event.
+- **Diagrams are drawn in the page.** Mermaid is bundled into the plugin and runs
+  locally; drawing a diagram fetches nothing from anywhere.
+- **Office documents are unpacked in the page.** A `.docx`, `.xlsx` or `.pptx` is
+  read here, by this plugin's own reader; nothing about it leaves the browser. A
+  PDF is handed to the browser's reader as a local blob URL.
 - **HTML runs sandboxed.** A previewed page's scripts execute in an opaque origin,
   which cannot read this application's DOM, storage, or session; an exported page
   is printed with its scripts removed. An SVG draws through `<img>`, so its scripts
@@ -147,8 +178,32 @@ restart the profile.
   the second loads directly, and the third is not fetched.
 - **HTML previews do not resolve relative assets.** A page drawn from a Blob
   document has no base to resolve its own `style.css` or images against, so only
-  absolute URLs load there too. An export prints the page as it renders without
-  its scripts, which a static PDF has no use for anyway.
+  absolute URLs load there. **An export does resolve them** — the file it writes is
+  read from a copy that has been made to stand alone — so a document can export
+  with pictures it does not show in the preview.
+- **An exported PDF's text is a picture.** Nothing in it can be selected or
+  searched — a *previewed* PDF is the browser's own reader, where it can. Export
+  Word instead when the text has to stay text.
+- **A Mermaid diagram is a picture too.** It is drawn once, to a PNG, for the
+  preview and for both exports — so its labels are not selectable, and it is
+  always drawn on white, because a PDF page and a Word document are white and a
+  diagram drawn for a dark pane would be invisible on them. Drawing supports the
+  diagram types Mermaid 11 carries; a malformed one keeps its source and names
+  the failure above it.
+- **An Office preview is content, not layout.** A `.docx` shows its headings,
+  text, lists, tables and pictures; a `.xlsx` shows its cells' values; a `.pptx`
+  shows each slide's text and pictures. What is *not* there is everything that
+  needs a layout engine and the fonts the file names: colours and themes, column
+  widths, page breaks, headers and footers, charts, SmartArt, and animations.
+  Formulas show the value the file cached, not a recalculation.
+- **Only the OOXML formats are read.** `.doc`, `.xls` and `.ppt` are the older
+  binary container, which this pane does not parse — it says so and offers the
+  download instead.
+- **Preview and download are bounded by one complete-file read**, 32 MiB by
+  default in the shipped Web composition. A file above it reports the refusal
+  rather than arriving cut.
+- **Long documents are cut at 60 PDF pages**, and an image past 8 MiB is left out;
+  both are stated here because a silent cut reads as a complete export.
 
 ## Contributing
 

package/README.zh.md

@@ -10,8 +10,9 @@
 
 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 增加一个
 **文件** 标签，与 **对话**、**轨迹** 并列：左侧是会话工作区的目录树，右侧的预览
-会按文件本身决定形态 —— 渲染后的 Markdown、JSON 树、语法高亮源码、图片，或纯
-文本。只读、无需配置、不落任何数据。
+会按文件本身决定形态 —— 渲染后的 Markdown（含图表）、HTML 页面、JSON 树、语法
+高亮源码、图片、PDF，以及解包后的 Word / Excel / PowerPoint 文档。只读、无需配置、
+不落任何数据。
 
 ```sh
 dsh plugin --profile web add @jaxzhou/dsh-file-explorer
@@ -20,12 +21,14 @@ dsh --profile web
 
 ## 演示
 
-[![文件标签与对话、轨迹并列：左侧是工作区目录树，右侧是渲染后的 Markdown 文档，
-工具栏上带复制、源码与导出 PDF](media/demo.gif)](media/demo.mp4)
+[![文件标签与对话、轨迹并列：左侧是工作区目录树，右侧是渲染后的 Markdown 文档](media/demo.gif)](media/demo.mp4)
 
 *15 秒录屏 —— 点击可打开完整画质的 MP4。* 一个小数学工作区：渲染后的讲义文档
 （含表格）、切到 **源码** 看它背后的 Markdown、在旁边用另一个标签打开第二份文档，
-最后用 **导出 PDF** 把页面交给浏览器的打印对话框。
+最后把它导出为 PDF。
+
+**录屏来自比下面更早的版本。** 它早于 Mermaid 图表、PDF 与 Office 预览以及工具栏
+上的 **下载**，其中那次导出仍然把页面交给浏览器的打印对话框 —— 现在的导出都不会。
 
 ## 能做什么
 
@@ -39,18 +42,37 @@ dsh --profile web
 
 | 类别 | 预览 |
 |---|---|
-| **Markdown** | 直接渲染为 GFM —— 标题、表格、任务列表、引用、公式、脚注、引用文件旁的图片、高亮的代码围栏 —— 并带 **源码** 切换与 **导出 PDF** |
-| **HTML** | 在沙箱 iframe 中当作页面绘制：文件自己的 CSS 生效，其脚本运行在不透明源（opaque origin）里，无法触达本应用。带 **源码** 切换与 **导出 PDF** |
+| **Markdown** | 直接渲染为 GFM —— 标题、表格、任务列表、引用、公式、脚注、引用文件旁的图片、高亮的代码围栏、**Mermaid 图表** —— 并带 **源码** 切换与 **导出** 菜单 |
+| **HTML** | 在沙箱 iframe 中当作页面绘制：文件自己的 CSS 生效，其脚本运行在不透明源（opaque origin）里，无法触达本应用。带 **源码** 切换与 **导出** 菜单 |
 | **JSON** | 可折叠树，每个值可单独复制，同样带 **源码** 切换 |
 | **源码** | 24 种语法的语法高亮、行号与复制按钮：TypeScript/JavaScript、shell、Python、Ruby、Go、Rust、Java、C、C++、C#、Kotlin、Swift、PHP、YAML、TOML、INI、HTML、CSS、SCSS、Less、SQL、XML、Lua、MDX |
 | **图片** | PNG、JPEG、GIF、WebP、AVIF、BMP、ICO、SVG，自动适配窗格。SVG 经 `<img>` 绘制，其中的脚本不会执行 |
-| **其它** | 带行号的纯文本 —— 未映射的后缀（`.vue`、`.proto`、`.txt`）保持纯文本，而不是猜测一个错误的高亮 |
+| **PDF** | 交由浏览器自带的 PDF 阅读器绘制，用的是文件自身的字节 —— 因此其中的文字是真文字 |
+| **Word / Excel / PowerPoint** | `.docx`、`.xlsx`、`.pptx` 在页面内解包：文档的标题、列表、表格、图片与代码；工作簿按工作表显示为网格，并以日期显示它按数字存储的日期；演示文稿按幻灯片显示其文字与图片的提纲 |
+| **其它** | 带行号的纯文本 —— 未映射的后缀（`.vue`、`.proto`、`.txt`）保持纯文本，而不是猜测一个错误的高亮。旧版二进制 Office 格式（`.doc`、`.xls`、`.ppt`）不做预览：窗格会说明原因并提供下载 |
+
+**Mermaid** 代码围栏（` ```mermaid `）是图表而不是源码，窗格会把它画出来：
+流程图、时序图、状态图、类图、ER 图、甘特图、饼图，以及 Mermaid 11 支持的其它
+类型。它在出现的每一处都是图像 —— 预览、PDF 页面、Word 文档携带的是同一张图 ——
+所见即所得。Mermaid 无法解析的图表会保留源码，并在其上方说明失败原因。
+
+文本预览在空格处折行、保持单词完整；图片读取完整字节。
+
+每一种预览的窗格工具栏里都有 **下载**，保存的是文件本身而不是它的某种转换 ——
+因此这是唯一对**所有**文件类型都可用的控件，包括本窗格不绘制的那些。每一种文本预览
+还有 **复制**，复制的是文件自身的文本——渲染态的 Markdown 复制的是它的 Markdown
+源码。
+
+渲染态的 Markdown 与 HTML 还带 **导出** 菜单，**直接下载文件**（不走打印对话框），
+两种格式：
+
+| 格式 | 说明 |
+|---|---|
+| **PDF** | 页面的图像：按 A4 排版并分页切分。其中的文字**不可选中**。这是刻意的：中文文档若用文本模式生成 PDF，就必须在插件里内嵌 CJK 字体——对一个预览工具来说是好几 MB |
+| **Word**（`.docx`） | 真正的 Word 文档：标题、列表、表格、代码与图片都在，文字仍是文字——可编辑、可搜索，中文交给 Word 自己的字体渲染 |
 
-文本预览在空格处折行、保持单词完整；图片读取完整字节。每一种文本预览在窗格工具栏
-里都有 **复制** 按钮，复制的是文件自身的文本——渲染态的 Markdown 复制的是它的
-Markdown 源码。渲染态的 Markdown 与 HTML 还带 **导出 PDF**：它把页面交给浏览器的
-打印对话框，那里每个浏览器都提供「另存为 PDF」，而排版由浏览器自己的引擎完成
-——文字仍是文字，不像基于 canvas 的 PDF 库那样把整页栅格化。
+文档自带的本地资源会一起带上：Markdown 文件旁边引用的图片，以及 HTML 文件链接的
+图片与样式表。
 
 ## 环境要求
 
@@ -106,6 +128,10 @@ profile。
   Host 的文件系统决定。插件自身不持有文件权限、不做路径解析、不接触凭据。
 - **不落数据**：不写磁盘、不写会话日志；视图状态保存在内存中，随会话一起释放。
 - **Host 半边是空实现**：包的 Node 侧不注册任何服务、工具、提示词片段或事件。
+- **图表在页面内绘制**：Mermaid 打包在插件里、在本地运行；绘制图表不会向任何地方
+  发起请求。
+- **Office 文档在页面内解包**：`.docx`、`.xlsx`、`.pptx` 由本插件自己的读取器在本地
+  解析，内容不会离开浏览器。PDF 则以本地 blob URL 交给浏览器自带的阅读器。
 - **HTML 在沙箱中运行**：预览页面的脚本执行于不透明源，无法读取本应用的 DOM、
   存储或会话；导出时会先剥除脚本再打印。SVG 经 `<img>` 绘制，脚本完全不执行。
 
@@ -129,8 +155,25 @@ profile。
   URL、绝对路径则交给渲染器自己的规则：第一个保持原样，第二个直接加载，第三个
   不会去读。
 - **HTML 预览不解析相对资源**：由 Blob 文档绘制出的页面没有可用来解析自身
-  `style.css` 或图片的 base，所以同样只有绝对 URL 能加载。导出时按渲染结果打印，
-  且不带脚本——静态 PDF 本来也用不上脚本。
+  `style.css` 或图片的 base，所以预览里只有绝对 URL 能加载。**导出时会解析**——
+  写出的文件来自一份被补齐成自包含的副本——所以可能有「预览里看不到图，导出里
+  有图」的情况。
+- **导出的 PDF 里文字是图像**，无法选中或搜索（**预览** PDF 用的是浏览器自带的
+  阅读器，文字可选）。需要文字可编辑时请导出 Word。
+- **Mermaid 图表同样是图像**：它只绘制一次（PNG），供预览与两种导出共用 —— 因此
+  其中的标签不可选中，且始终以白底绘制：PDF 页面与 Word 文档都是白底，为深色窗格
+  绘制的图在它们上面会看不见。绘制范围是 Mermaid 11 支持的图表类型；语法错误的
+  图表会保留源码，并在上方说明失败原因。
+- **Office 预览是内容，不是排版**：`.docx` 显示标题、正文、列表、表格与图片；
+  `.xlsx` 显示单元格的值；`.pptx` 显示每页的文字与图片。**没有**的是所有需要排版
+  引擎和文件所指定字体的东西：颜色与主题、列宽、分页、页眉页脚、图表、SmartArt、
+  动画。公式显示文件缓存的值，不做重算。
+- **只读取 OOXML 格式**：`.doc`、`.xls`、`.ppt` 是更早的二进制容器，本窗格不解析
+  —— 会说明这一点并提供下载。
+- **预览与下载都受同一次「完整读取」上限约束**：官方 Web 组合默认 32 MiB。超过上限
+  的文件会报告被拒绝，而不是被截断后送来。
+- **超长文档会在 60 页 PDF 处截断**，单张超过 8 MiB 的图片会被跳过；写在这里是因为
+  静默截断会被误认为完整导出。
 
 ## 参与开发