DeepSeek Harness - 多功能文档与工作空间代码预览插件 (@rooode/dsh-plugin-preview)

本插件为 DeepSeek Harness (DSH) 与 WorkBuddy 对话界面提供了参考 WorkBuddy FileTabs 设计的右侧多标签 Markdown、代码与工作空间文件树浏览器。

在 DSH 中，大模型经常会生成、改写或读取 .md 文档与各类代码文件。默认情况下，点击生成的文档链接会直接调用 Windows 系统的本地记事本 (Notepad) 打开，打断了用户在 Web 会话中的阅读与操作体验。通过安装本插件，点击任何文档或代码将直接在右侧滑出多标签预览抽屉，提供工作空间目录树浏览、多语言代码高亮与符号大纲、JSON 交互结构树、GFM 富文本渲染、一键复制、实时刷新以及按需本地打开等全套能力。

---

🌟 核心特性 (Features)

1. 📁 工作空间目录树与文件操作 (Workspace Tree, Creation & Move)：
   • 树状层级展开/折叠项目所有目录与文件，支持文件大小与修改时间展示；
   • 文件夹与文件新建：支持头部快捷按钮、右键上下文菜单在任意子目录行内新建（VS Code 交互风格，按回车确认，Esc 取消），新建文件后自动打开预览；
   • 流畅的拖拽移动 (Drag & Drop)：支持在目录树中自由拖动文件或文件夹到目标目录，带放置目标高亮悬停提示与防循环嵌套移动保护；
   • 剪切与粘贴移动 (Cut & Paste)：右键菜单支持快速“剪切”并在目标目录“粘贴”，便捷管理项目结构；
   • FileTabs 状态自动联动：移动或重命名文件时，自动无缝同步更新已打开标签页的文件路径与标题；
   • 重命名、删除与文件管理器定位：支持右键菜单一键重命名、删除（带确认保护）与在系统文件管理器中定位；
   • 文件名即时过滤搜索，自动展开命中路径并折叠无关项；
   • 快捷折叠全部目录、一键刷新磁盘目录结构；
   • 目录树宽度支持鼠标自由拖拽调节。
2. 💡 对话区智能交互与自动收起：
   • 当预览抽屉处于打开状态时，点击左侧会话列表或对话输入框，抽屉自动平滑收起/隐藏，保证专注对话输入；
   • 收起后右下角保留胶囊浮窗，一键随时恢复展开。
3. 🌳 交互式 JSON 结构树检查器 (JSON Tree Inspector)：
   • .json 文件默认以交互结构树呈现，支持 Object{N} 与 Array[N] 多层级折叠展开；
   • 属性名与属性值即时过滤搜索；
   • 单击快捷复制指定字段路径（如 scripts.build）或字段值；
   • 提供 ⚡ 格式化 (2空格对齐) 与 🗜️ 压缩 (单行) 快捷操作，并支持随时切换至高亮代码模式。
4. 🌐 多语言语法高亮与符号大纲 (Polyglot Highlighting & Symbol TOC)：
   • 采用单趟扫描分词器（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 等；
   • 大纲点击平滑跳转：点击大纲侧栏任一项，代码区域自动平滑滚动定位至目标代码行，并在行号及对应行触发高亮闪烁反馈；
   • 代码排版优化：默认水平滚动，点击 ↩️ 换行 可在单行与自动折行（overflow-wrap: break-word）间无缝切换，杜绝单词被撕裂打碎。
5. 📖 全功能 GFM Markdown 渲染引擎：
   • 三模视图切换：📖 渲染预览 (Preview) / 📝 源码模式 (Source) / 🌓 分栏对比 (Split)；
   • GitHub Alerts 提示框：完整支持 > [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION] 彩色卡片渲染；
   • LaTeX 数学公式：支持 $inline$ 与 $$block$$ 数学公式排版；
   • 数据表格与任务清单：斑马纹表格自适应排版、交互式勾选框列表；
   • 目录大纲导航 (TOC)：自动提取 H1~H6 标题生成侧栏目录，点击平滑滚动跳转。
6. 📑 右侧多标签页 (FileTabs)：
   • 支持同时打开多个文档与代码文件，标签栏展示对应语言彩色图标、文件名与独立关闭按钮；
   • 支持快速切换激活标签、一键全部关闭；
   • 左侧边框支持鼠标自由拖拽调节宽度（支持 380px 至 90vw 自由调整）。

---

📦 快速安装 (Installation)

在终端中执行以下命令，将插件一键安装到 DSH 的 web profile 中：

方式 1：标准 npx 安装（推荐，无需全局安装）

# 1. 一键从 npm 下载并安装插件
npx @deepseek-ai/dsh plugin --profile web add @rooode/dsh-plugin-preview

# 2. 启动 DSH Web 界面
npx @deepseek-ai/dsh web

方式 2：全局 dsh CLI 安装

如果您已全局安装了 npm install -g @deepseek-ai/dsh：

# 1. 安装插件
dsh plugin --profile web add @rooode/dsh-plugin-preview

# 2. 启动
dsh web

方式 3：离线 Tarball 安装（适合内网/断网环境）

# 下载或拷贝 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 中自定义配置以下参数：

- 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)

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)

在本项目根目录下执行：

# 1. 编译并将最新产物同步至本地 DSH 运行环境
npm run build

# 2. 监听文件修改并自动重新编译分发
npm run dev

# 3. 执行 TypeScript 类型检查
npm run typecheck

# 4. 生成离线分发 tarball 压缩包
npm run package

---

📄 开源许可证 (License)

MIT License © 2026 rooode