@rooode/dsh-plugin-preview 0.1.7 → 0.1.9

package/README.md

@@ -12,103 +12,159 @@
 ## 🌟 核心特性 (Features)
 
 1. **📁 工作空间目录树浏览器 (Workspace Tree Explorer)**：
-   - 树状层级展开/折叠项目所有目录与文件，支持文件大小与修改时间展示。
-   - 文件名即时过滤搜索，自动展开命中路径并折叠无关项。
-   - 快捷折叠全部目录、一键刷新磁盘目录结构。
+   - 树状层级展开/折叠项目所有目录与文件，支持文件大小与修改时间展示；
+   - 文件名即时过滤搜索，自动展开命中路径并折叠无关项；
+   - 快捷折叠全部目录、一键刷新磁盘目录结构；
    - 目录树宽度支持鼠标自由拖拽调节。
-
 2. **💡 对话区智能交互与自动收起**：
-   - 当预览抽屉处于打开状态时，点击左侧会话列表或对话输入框，抽屉自动平滑收起/隐藏，保证专注对话输入。
+   - 当预览抽屉处于打开状态时，点击左侧会话列表或对话输入框，抽屉自动平滑收起/隐藏，保证专注对话输入；
    - 收起后右下角保留胶囊浮窗，一键随时恢复展开。
-
 3. **🌳 交互式 JSON 结构树检查器 (JSON Tree Inspector)**：
-   - `.json` 文件默认以交互结构树呈现，支持 `Object{N}` 与 `Array[N]` 多层级折叠展开。
-   - 属性名与属性值即时过滤搜索。
-   - 单击快捷复制指定字段路径（如 `scripts.build`）或字段值。
+   - `.json` 文件默认以交互结构树呈现，支持 `Object{N}` 与 `Array[N]` 多层级折叠展开；
+   - 属性名与属性值即时过滤搜索；
+   - 单击快捷复制指定字段路径（如 `scripts.build`）或字段值；
    - 提供 `⚡ 格式化 (2空格对齐)` 与 `🗜️ 压缩 (单行)` 快捷操作，并支持随时切换至高亮代码模式。
-
 4. **🌐 多语言语法高亮与符号大纲 (Polyglot Highlighting & Symbol TOC)**：
-   - 采用单趟扫描分词器（Single-Pass Tokenizer），杜绝 HTML 嵌套污染。
+   - 采用单趟扫描分词器（Single-Pass Tokenizer），杜绝 HTML 嵌套污染；
    - **全面支持主流语言**：
-     - ☕ **Java**：注解（`@Service`, `@Autowired`, `@Override`）、泛型、集合类、文本块、Package/Class/Method 符号大纲。
-     - ⚙️ **C / C++**：预处理指令（`#include <...>`）、命名空间、模板、标准库类型、智能指针、Namespace/Class/Struct/Function 符号大纲。
-     - 🐍 **Python**：装饰器（`@dataclass`, `@property`）、多行 Docstrings、异步协程（`async def`）、类型标注、Class/Def 符号大纲。
-     - ⚡ **JavaScript / TypeScript**：ES 模块、JSX 标签、接口/枚举、模板字符串、箭头函数、Class/Fn/Type/Export 符号大纲。
-     - 🦀 **Rust** / 🌐 **Go** / ⌨️ **Shell** / 🗄️ **SQL** / ⚙️ **YAML** / 📝 **Markdown** 等。
-   - **大纲点击平滑跳转**：点击大纲侧栏任一项，代码区域自动平滑滚动定位至目标代码行，并在行号及对应行触发高亮闪烁反馈。
+     - ☕ **Java**：注解（`@Service`, `@Autowired`, `@Override`）、泛型、集合类、文本块、Package/Class/Method 符号大纲；
+     - ⚙️ **C / C++**：预处理指令（`#include <...>`）、命名空间、模板、标准库类型、智能指针、Namespace/Class/Struct/Function 符号大纲；
+     - 🐍 **Python**：装饰器（`@dataclass`, `@property`）、多行 Docstrings、异步协程（`async def`）、类型标注、Class/Def 符号大纲；
+     - ⚡ **JavaScript / TypeScript**：ES 模块、JSX 标签、接口/枚举、模板字符串、箭头函数、Class/Fn/Type/Export 符号大纲；
+     - 🦀 **Rust** / 🌐 **Go** / ⌨️ **Shell** / 🗄️ **SQL** / ⚙️ **YAML** / 📝 **Markdown** 等；
+   - **大纲点击平滑跳转**：点击大纲侧栏任一项，代码区域自动平滑滚动定位至目标代码行，并在行号及对应行触发高亮闪烁反馈；
    - **代码排版优化**：默认水平滚动，点击 `↩️ 换行` 可在单行与自动折行（`overflow-wrap: break-word`）间无缝切换，杜绝单词被撕裂打碎。
-
 5. **📖 全功能 GFM Markdown 渲染引擎**：
-   - **三模视图切换**：📖 渲染预览 (Preview) / 📝 源码模式 (Source) / 🌓 分栏对比 (Split)。
-   - **GitHub Alerts 提示框**：完整支持 `> [!NOTE]`、`> [!TIP]`、`> [!IMPORTANT]`、`> [!WARNING]`、`> [!CAUTION]` 彩色卡片渲染。
-   - **LaTeX 数学公式**：支持 `$inline$` 与 `$$block$$` 数学公式排版。
-   - **数据表格与任务清单**：斑马纹表格自适应排版、交互式勾选框列表。
+   - **三模视图切换**：📖 渲染预览 (Preview) / 📝 源码模式 (Source) / 🌓 分栏对比 (Split)；
+   - **GitHub Alerts 提示框**：完整支持 `> [!NOTE]`、`> [!TIP]`、`> [!IMPORTANT]`、`> [!WARNING]`、`> [!CAUTION]` 彩色卡片渲染；
+   - **LaTeX 数学公式**：支持 `$inline$` 与 `$$block$$` 数学公式排版；
+   - **数据表格与任务清单**：斑马纹表格自适应排版、交互式勾选框列表；
    - **目录大纲导航 (TOC)**：自动提取 H1~H6 标题生成侧栏目录，点击平滑滚动跳转。
-
 6. **📑 右侧多标签页 (FileTabs)**：
-   - 支持同时打开多个文档与代码文件，标签栏展示对应语言彩色图标、文件名与独立关闭按钮。
-   - 支持快速切换激活标签、一键全部关闭。
+   - 支持同时打开多个文档与代码文件，标签栏展示对应语言彩色图标、文件名与独立关闭按钮；
+   - 支持快速切换激活标签、一键全部关闭；
    - 左侧边框支持鼠标自由拖拽调节宽度（支持 380px 至 90vw 自由调整）。
 
 ---
 
 ## 📦 快速安装 (Installation)
 
-### 方式 1：通过 `dsh plugin` 命令安装
+在终端中执行以下命令，将插件一键安装到 DSH 的 `web` profile 中：
+
+### 方式 1：标准 `npx` 安装（推荐，无需全局安装）
 ```bash
-# 1. 安装插件到 web profile
+# 1. 一键从 npm 下载并安装插件
 npx @deepseek-ai/dsh plugin --profile web add @rooode/dsh-plugin-preview
 
-# 2. 启动 DSH Web
+# 2. 启动 DSH Web 界面
 npx @deepseek-ai/dsh web
 ```
 
-### 方式 2：本地源码一键构建与分发部署
-在本项目根目录下执行：
+### 方式 2：全局 `dsh` CLI 安装
+如果您已全局安装了 `npm install -g @deepseek-ai/dsh`：
 ```bash
-# 编译并自动分发到所有本地 DSH 环境与 npx 缓存
-npm run build
+# 1. 安装插件
+dsh plugin --profile web add @rooode/dsh-plugin-preview
 
-# 启动 Web UI 体验
-npx @deepseek-ai/dsh web
+# 2. 启动
+dsh web
+```
+
+### 方式 3：离线 Tarball 安装（适合内网/断网环境）
+```bash
+# 下载或拷贝 rooode-dsh-plugin-preview-*.tgz 后执行：
+npx @deepseek-ai/dsh plugin --profile web add ./rooode-dsh-plugin-preview-0.1.7.tgz
 ```
 
 ---
 
 ## ⚙️ 配置项说明 (Configuration)
 
-可以在 `cordis.patch.yml` 或配置文件中自定义以下参数：
+可在 `cordis.patch.yml` 中自定义配置以下参数：
 
 ```yaml
-- id: ui-preview
-  name: '@rooode/dsh-plugin-preview'
-  config:
-    # 自动拦截并右侧预览的文件后缀列表
-    autoPreviewExtensions:
-      - .md
-      - .markdown
-      - .txt
-      - .json
-      - .yaml
-      - .yml
-      - .js
-      - .ts
-      - .java
-      - .cpp
-      - .c
-      - .h
-      - .hpp
-      - .py
-      - .go
-      - .rs
-      - .sh
-      - .sql
-    # 最大允许读取的文件大小 (MB)
-    maxFileSizeMb: 10
-    # 默认打开视图: 'preview' (预览) | 'source' (源码) | 'split' (分栏) | 'json-tree' (树) | 'code' (代码)
-    defaultViewMode: preview
-    # 右侧预览面板默认宽度 (px)
-    defaultPanelWidth: 760
+- insert:
+    - id: ui-preview
+      name: '@rooode/dsh-plugin-preview'
+      config:
+        # 自动拦截并在右侧预览的文件后缀列表
+        autoPreviewExtensions:
+          - .md
+          - .markdown
+          - .txt
+          - .json
+          - .yaml
+          - .yml
+          - .js
+          - .ts
+          - .java
+          - .cpp
+          - .c
+          - .h
+          - .hpp
+          - .py
+          - .go
+          - .rs
+          - .sh
+          - .sql
+        # 最大允许读取的文件大小 (MB)
+        maxFileSizeMb: 10
+        # 默认打开视图: 'preview' (预览) | 'source' (源码) | 'split' (分栏)
+        defaultViewMode: 'preview'
+        # 右侧预览面板默认初始宽度 (px)
+        defaultPanelWidth: 560
+```
+
+### 配置参数列表
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `autoPreviewExtensions` | `string[]` | `['.md', '.markdown', '.txt', ...]` | 点击文档链接时自动在右侧面板滑出预览的文件扩展名白名单列表 |
+| `maxFileSizeMb` | `number` | `10` | 最大允许读取和预览的文件体积上限（MB） |
+| `defaultViewMode` | `'preview' \| 'source' \| 'split'` | `'preview'` | 默认打开视图模式（渲染预览 / 源码模式 / 双栏分栏对比） |
+| `defaultPanelWidth` | `number` | `560` | 右侧预览面板默认初始化宽度（px） |
+
+---
+
+## 📁 项目结构 (Directory Structure)
+
+```text
+dsh-plugin-preview/
+├── package.json              # 插件元信息、dsh.bundle/client 声明与 npm scripts
+├── cordis.patch.yml          # DSH 组合包 patch 描述文件
+├── tsconfig.json             # TypeScript 严格编译与类型输出配置
+├── README.md                 # 插件技术说明与安装文档
+├── src/
+│   ├── types.ts              # 文件节点、目录树、视图模式与配置类型定义
+│   ├── service.ts            # Cordis 服务 PreviewService (Node 端文件扫描与读取 REST API)
+│   ├── index.ts              # Node 端入口：服务初始化、WebServer 注入与 Schema 校验
+│   └── client.js             # 前端 React 多标签抽屉、目录树、GFM 渲染与多语言高亮引擎
+├── lib/
+│   ├── index.js              # Node 端 ESM 产物
+│   ├── index.d.ts            # 类型定义声明
+│   └── client.js             # 前端独立分发 Bundle
+└── scripts/
+    └── build.js              # 编译与 Profile 自动分发同步脚本
+```
+
+---
+
+## 🛠️ 本地开发与二次构建 (Development)
+
+在本项目根目录下执行：
+
+```bash
+# 1. 编译并将最新产物同步至本地 DSH 运行环境
+npm run build
+
+# 2. 监听文件修改并自动重新编译分发
+npm run dev
+
+# 3. 执行 TypeScript 类型检查
+npm run typecheck
+
+# 4. 生成离线分发 tarball 压缩包
+npm run package
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rooode/dsh-plugin-preview",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "DeepSeek Harness Markdown 文档与工作空间文件浏览器右侧预览插件 (支持工作区文件树、JSON 交互结构树/格式化、Java/C++/Python/JS/TS/YAML/Go/Rust 多语言语法高亮与符号大纲、自动换行与多标签 FileTabs)",
   "type": "module",
   "main": "lib/index.js",
@@ -18,11 +18,12 @@
     "dev": "node scripts/build.js --watch",
     "typecheck": "tsc --noEmit",
     "package": "node scripts/build.js && npm pack",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "node scripts/build.js"
   },
   "keywords": [
     "deepseek-harness",
     "dsh",
+    "dsh-plugin",
     "cordis-plugin",
     "preview",
     "markdown-preview",