dsh-aionui-panel/packages/dsh-aionui-panel

一句话定位

在 DSH Web GUI 聊天区右侧加上一套 IDE 风格面板：可拖拽宽度的文件树、多 tab 多格式预览（代码/Markdown/Office/图片）、Git 变更面板和终端命令台，全部直连真实文件系统与真实 Git 仓库；安装 dsh-easyssh 后同一面板自动跟随 SSH 模式切换到远程。

核心能力

• 双栏文件面板：聊天区右侧出现「Preview 多 tab 预览」+「Explorer 文件 / 变更」两栏，宽度可拖拽钳位（Explorer 220500px，Preview 3401200px），双击把手复位默认；Explorer 顶部按文件名 150ms 防抖搜索定位，跳过 .git 与 node_modules
• 13 类文件预览：Markdown、HTML、PDF、CSV、图片、Office（docx/xlsx/pptx、odt/ods/odp、rtf）、代码（70+ 后缀自动 highlight）、diff/patch、纯文本、外链 URL 都直接打开
• 框内富文本编辑：code/Markdown/HTML/Office 全部可改可保存，docx/xlsx/pptx 编辑保存时由编辑后 HTML 在浏览器端 ZIP 重组后二进制回写
• 真实 Git 变更面板：「变更」tab 读取 porcelain v1 -z 真实状态，支持批量 stage / unstage / discard（tracked 走 restore，untracked 走删除，带批量确认）
• 按项目隔离的偏好与记忆：每条 localStorage 以项目根为 scope 记忆展开态、tab 列表、宽度、折叠态、布局（LRU 12 个 scope，超出淘汰最旧）
• 集成终端面板：独立开终端或从代码文件一键运行，本地模式走宿主 subprocess，SSH 模式自动改为远程执行；超时兜底 UTF-8，避免 Windows cmd GBK 截断 emoji

技术实现

• 语言: TypeScript（Node 端 host + Browser 端 client 两半区 + React + JSZip）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver、@deepseek-ai/dsh-subprocess、jszip（docx/xlsx/pptx 浏览器端 ZIP 解析）
• 架构模式: 双端 Cordis 插件 + profile bundle 注入。src/index.ts 是 host 半区入口（注册 /aionui-panel/* HTTP 路由与 systemPrompt 公告），src/client/index.ts 是 browser 半区（通过 dsh.client.inject 注入 web GUI 网格、向 settings 面板注册「右边栏工作区」栏目）
• 入口文件: packages/dsh-aionui-panel/src/index.ts:51（host apply）；packages/dsh-aionui-panel/src/client/index.ts:50（client apply）

适用场景

在 DSH Web GUI 里同时打开多个本地项目时，希望在 AI 对话旁直接浏览、预览、编辑文件并查看 Git 变更，不必切回 VS Code 或 Finder；装上 dsh-easyssh 后同样的入口也能对远程服务器做这些操作——给「模型代理写代码、用户盯文件改动」的场景一个一体化窗口。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:chenw2759-wq/dsh-IDE/packages/dsh-aionui-panel

配置项

本插件在宿主侧不暴露任何 Cordis Schema 配置项；所有可调行为都通过 GUI 内的「设置 → 右边栏工作区」开关面板（即时生效、持久化在 localStorage 键 aionui-workspace-settings）。这套开关由 8 项功能 + 9 项编辑工具组成（src/client/settings.ts:10-79）：

另外还有三类用户态数据用 localStorage 自动持久化，源码未声明具体清理接口，按本地浏览器容量管理：

常见问题

Q: 安装后需要重启 DSH 吗？

A: 需要。cordis.patch.yml 通过 dsh.bundle.patch 注入到 web profile 的插件列表（cordis.patch.yml:11-13），必须重启一次 dsh web 才会注册新的插件行；之后通过设置面板调开关不需要再重启。

Q: 不装 dsh-easyssh 也能用吗？

A: 能。所有 fs/git 操作默认走宿主进程的本地文件系统与本地 git 子进程（src/host/fs-service.ts / src/host/git-service.ts），不依赖 SSH。SSH 切换是可选增强——不装 dsh-easyssh 时面板始终展示本地会话 cwd。

Q: 改了设置面板里的开关要刷新页面吗？

A: 不需要。「右边栏工作区」的开关通过单个共享 store（src/client/settings.ts:138-143）即时热应用，关掉监视圆点或语法高亮立刻生效，不会留陈旧状态。

Q: 文件保存会不会覆盖外部的改动？

A: 不会。text 写入走 /aionui-panel/write，docx/xlsx/pptx 走 /aionui-panel/write-binary，服务端会用浏览器随写入提交的上一次 mtime 与磁盘实时 mtime 对比，冲突返回 write-conflict，不会静默覆盖（src/host/routes.ts:218-247）。

Q: 能预览哪些文件？

A: 自动识别 markdown/html/code/diff/csv/pdf/word(excel/ppt)/image/text/url 共 13 类（src/client/fileType.ts:10-82）；不支持的扩展名显示「此格式暂不支持预览」占位。

Q: 怎么卸载？

A: 从 cordis.patch.yml 删除 ui-dsh-aionui-panel 行（cordis.patch.yml:12），重启 dsh web；浏览器侧的 aionui-workspace-settings 等 localStorage 可以保留也可以手动清除。

Q: 和 dsh 自带的 fs-sandbox / subprocess 冲突吗？

A: 不冲突。本插件只声明 webServer / subprocess / workspaceRegistry / systemPrompt 四个 inject（src/index.ts:34），不会替换宿主服务；如果同时安装 dsh-easyssh 由它做接缝切换，本插件通过 sshWorkspaceMode / sshWorkspaceCore 这两个跨插件服务自动跟随远程模式。

Q: docx 为什么有时候图表不显示？

A: 已知限制。docx 解析覆盖段落、表格、段落底纹、页眉页脚、内联图片（src/client/preview/office.tsx:1-17 与 README.md:36）；word/charts/ 图表与嵌入的 Excel 对象暂不渲染（CHANGELOG v0.2.0 已知技术风险），不会单独报错。

上手难度

进阶 — 装机即用，但要让 SSH / 终端 / Office 编辑这三类能力都转起来需要分别了解 DSH profile、SSH 凭据管理与 docx 渲染边界。

已知问题与限制

• docx 中的图表（word/charts/chart1.xml）和嵌入的 Excel 对象在预览与编辑保存重建时均不渲染（src/client/preview/office.tsx:1-17 / README.md:36）
• PPT 预览不保留动画与切换效果（dsh-IDE 根 CHANGELOG v0.2.0 已知技术风险）
• SSH 模式下 /aionui-panel/git-* 系列接口全部返回 git-unavailable（src/host/routes.ts:319-333），SCM 变面板在远程会话下隐藏相关操作
• docx HTML 重建保真度有限：编辑保存后页眉页脚、合并单元格等复杂排版不会被保留（dsh-IDE 根 CHANGELOG v0.2.0 已知技术风险）
• 文件名搜索结果有上限：命中 200 条 / 扫描 20,000 个条目（src/host/fs-service.ts:46-47），超出标 truncated: true
• 本地模式终端走宿主 subprocess，最长 grace 10 秒、单条命令 60 秒超时（src/index.ts:98 / src/index.ts:76-77），超长命令会返回错误
• 浏览器侧持久化 LRU 最多 12 个项目根的 Preview 记忆（src/client/persist.ts:93-94），跨项目更多时最久未用的 scope 会被淘汰

中文 | English

把 DeepSeek Harness（DSH）Web GUI 升级为一体化开发环境，四大核心能力：

• 🖥️ 右侧边栏：可停靠的右栏抽屉——文件树 + 预览/编辑同框；拖 tab 拖出成浮窗，拖回右缘自动停靠（下框 / 右栏 / 浮动 / 三栏 IDE 四态切换）
• 📄 预览：Markdown / HTML / 图片 / CSV / Office（docx / xlsx / pptx）/ 日志等多格式直接预览
• ✏️ 编辑：代码即时编辑（语法高亮 + 行号 + 斑马纹）+ Markdown/HTML Word 式可视化编辑 + Office 框内富文本编辑
• 🧩 IDE：文件树、命令行终端、Trae 风格红绿 diff、类型颜色标签、Git 角标、监视路径——开箱即用的 JupyterLab 式工作区

同时内置 SSH 远程工作区模式：右上角（session log 左侧）配置 SSH 主机（密码 / 密钥，复用 ~/.dsh/dsh-ssh.json），进入后右侧面板自动切换为远程文件树，模型本机的 read / write / edit / glob / grep 与 bash / 终端在 SSH 模式下透明地在远程服务器执行，LLM 与 Agent 循环仍在本机——「本地大脑、远程手脚」。

功能总览

⚙️ 右边栏工作区设置（系统设置内）

「设置」→「右边栏工作区」栏目集中管理右栏工作区的功能开关（8 项：自动 diff / 监视圆点 / Git 角标 / 语法高亮 / 缩放预览 / 三栏 IDE / 终端停靠 / 会话隔离）与编辑工具栏工具（9 项，供富文本编辑选用），圆角卡片 + 开关，改动即时生效并持久化。

🖼️ Markdown 预览（三种布局）

Markdown 文件在面板中直接渲染预览（青色标签），并支持三种布局随意切换：

• 下框展示（⇊）：预览显示在下栏
• 右侧弹出（⇉）：预览显示在右侧代码栏
• 浮动覆盖（⇱）：浮动覆盖在对话框上方，宽度更大

🌳 左侧文件树

左侧文件树：懒加载、按文件名搜索定位、Git 状态角标（A/M/D/R/U/C）、右键菜单（新建文件 / 新建文件夹 / 下载 / 行内重命名 / 复制 / 粘贴 / 删除进回收站），本地目录与 SSH 远程目录自动切换；已打开的文件绝不重复开 tab，磁盘变化时在原 tab 上自动刷新内容。

🔍 监视路径（自动弹出范围）：默认只监视一级目录（根目录及其直接子目录下的文件）。 点击目录行右侧圆点逐级切换：浅黄 = 监视此目录下一级路径，绿色 = 监视此目录下所有层级（n级），再点恢复默认；监视标记按会话记忆。顶栏（文件 / 变更 / >_ 右侧）有规则说明框。构建产物、临时文件、锁文件等过程文件无论标记都不弹出。

📊 状态栏

底部状态栏展示工作区状态。

✏️ 支持代码即时编辑

代码区即时编辑：五颜六色的语法高亮（Trae 风格配色，跟随浅色/深色主题自动切换）+ 行号 + 斑马底纹，可读写编辑、Ctrl+S 保存、保存带 mtime 冲突检测；工具栏提供分屏（编辑器 | 预览）、刷新等操作。

🔴🟢 红绿标注（Trae 风格编辑 diff）

任何外部编辑（Agent 工具写文件、其他进程改动）都会自动弹出「Update(路径)」卡片到下栏—— Added/removed 统计 + 删除行红底、新增行绿底；每个文件的每次编辑都会弹（基线自动推进，不重复不遗漏）； 保存后同样弹出：

• 全新文件（无历史基线）自动弹出全绿卡片（整份文件视为新增）
• 文件被删除自动弹出全红卡片（整份文件视为移除）
• diff 卡带固定双列行号（旧 / 新各一列，增删行号对齐）、未变更行斑马底纹
• 点「编辑最新版本」→ 编辑器覆盖整个显示框，可直接修改最新代码并保存（保存后红绿自动更新）； 点「刷新」红绿不丢失

🎨 颜色标记（类型颜色标签）

每个打开的标签带类型色块——橙 = 图片、绿 = CSV、蓝 = Python、黄 = JS/TS、紫 = JSON、 青 = Markdown、红 = diff、灰 = 日志——标签再多也能一眼分辨；新打开的文件与 diff 自动滚到 可见位置，标签条横向滚动 + 标题截断，绝不拥挤。

⌨️ 命令行展示（终端与运行）

内置命令行终端：代码工具栏「▶ 运行」直接执行当前文件（python / node / bash 等），「>_ 终端」打开 命令行面板随时输入命令（SSH 模式下均在远程执行）；文件栏 tab 条也有独立终端入口。终端以 真实终端风格停靠在聊天栏底部五分之一处（黑体、macOS 圆点标题、❯ 提示符、绿光标，不与对话重叠）。

📜 日志预览

日志文件（灰色标签）在面板中直接预览。

🖼️ 图片预览 / 📋 CSV 预览 / 🌐 HTML 预览

• 图片（橙色标签）与 HTML（紫色标签）预览支持放大/缩小：工具栏 − / % / + / 1:1 / 适应宽度，或 Ctrl+滚轮缩放
• CSV 数据表渲染为表格（绿色标签）

🖥️ 右侧边栏（可停靠抽屉 · 拖拽停靠 / 脱离）

• 右栏抽屉（默认）：预览停靠在右侧栏（文件树 + 预览同框的 drawer）；四态切换——下框（⇊）/ 右栏（⇉） / 浮动（⇱）/ 三栏 IDE（⿻，对话 | 文件树 | 预览三栏并排）
• 拖 tab 拖出成浮窗：任意布局下按住预览 tab 条 / 工具栏空白处拖动，即把预览拖出成浮动窗，位置 1:1 跟随指针、动画流畅不卡
• 拖回右缘自动停靠：把浮窗拖到屏幕右缘松手，自动停靠回右侧抽屉；拖到「盖住文件树（树自动折叠为圆形按钮）/ 树下方 / 聊天区下方」附近则吸附到对应预设位，拖出吸附区即回到自由浮动
• 浮窗自由缩放：右下角斜纹把手拖拽改宽高（尺寸记忆，吸附时保留）
• 聚焦模式：预览打开时点文件栏折叠箭头，文件树收为约 30px 右栏 rail（仅留小圆角展开按钮），点击即展开，专注预览与编辑；折叠后预览框保持原宽度

🧬 R 语言支持

.R / .r 脚本以 Rscript 运行（▶ 运行），R 标签用 R 官方蓝；.Rmd（R Markdown）识别为 Markdown 可预览渲染；代码高亮原生支持 R。

📄 Office 呈现（docx / xlsx / pptx 直接预览）

• docx：段落 / 表格 / 加粗 / 斜体 / 下划线 / 文字颜色 / 字号 / 高亮 / 对齐 / 字体（含中文字体 w:eastAsia）/ 段落与文本底纹 / 内联图片与形状照片（w:drawing/a:blip，含 mc:AlternateContent 形状）/ 内容控件（w:sdt）/ 页眉页脚（header1.xml 等 part 的 logo/信头）直接渲染
• xlsx：首个工作表渲染为表格（共享字符串解析）
• pptx：逐页卡片式呈现
• 浏览器端 ZIP 解析，无需宿主依赖、无需重启 dsh

✏️ 框内富文本编辑（Office）

预览工具栏「编辑」进入框内编辑：工具栏按设置面板勾选显示（字体 / 字号 / 加粗斜体 / 对齐 / 下划线 / 文字颜色 / 高亮 / 段间距行间距 / 页边距）；保存时由编辑后 HTML 重建 docx/xlsx/pptx 并以二进制写回（mtime 冲突保护，粗体/斜体/下划线/颜色/字号/字体/高亮等 run 格式编辑保存后不丢）。 已知限制：图表（word/charts/*）与嵌入对象（嵌入 Excel）等复杂结构暂不解析，编辑保存也不保留。

🎨 HTML / Markdown 可视化编辑（Word 式原地编辑）

预览工具栏「可视化编辑」：渲染结果本身就是可编辑文档（不再是浮动文本框）——像 Word 一样在渲染页上直接改。Markdown 在可编辑区里改编译后的 HTML，保存时转回 markdown 源（标题含中划线不会乱码、代码围栏保留语言）；颜色 / 字号 / 字体 / 下划线 / 高亮以严格白名单的内联 HTML 持久化，改字色不再误刷底色、粗斜体字号保存后不丢。HTML 在完整文档 iframe 里编辑（PPT 式富文本修改：颜色/字号/粗斜体/对齐/下划线/高亮），原 <style> 与画布背景照常渲染，保存回写整个文档（不再丢成单列覆盖的 body 碎片）。工具栏提供加粗/斜体/下划线/文字颜色/高亮/字体/字号/对齐/撤销/重做。文字颜色 / 底色为 Word 式按钮：点一下「A」就把当前记住的颜色套到选区（下方色条显示当前颜色），小「▾」弹出调色板选色即记住并生效——选色不再要点好几下，且可与粗体/斜体对同一段同时生效。工具栏会高亮当前选区已有的格式（加粗/斜体/下划线/对齐/颜色/底色按钮呈现阴影），像 Word 一样一眼看出选中文字带了什么格式。

🚀 SSH 远程开发（本地大脑、远程手脚）

• 接缝切换：通过 profile 补丁把 ctx.fs / ctx.subprocess 切换为模式路由门面——本地模式委托 给部署自带的沙箱化实现，SSH 模式委托给 SFTP/SSH 远程实现（原子写、版本校验、CRLF 处理、流式输出、 PTY 终端）。模型工具零改动地远程执行。
• 远程文件系统：完整 @deepseek-ai/dsh-fs 实现，路径 / 版本 / 原子写 / CRLF / 规范路径传输。
• 远程子进程：完整 @deepseek-ai/dsh-subprocess 实现，exec + PTY 终端，输出溢出转储到本地。
• 多主机：GUI 配置多台主机（含 ProxyJump 跳板链、密钥 passphrase），一键切换；设置页主机管理 专区（增删改 / 测试连接 / 进入退出），配置持久化在 ~/.dsh/dsh-ssh.json。
• 圆角胶囊按钮 + 多机选择栏：会话头部 SSH 按钮圆角化（远程态品牌色高亮）；连接对话框顶部列出 已保存主机，点击即进入（多机一键切换）。
• 会话级 SSH 状态隔离：每个会话记住自己的设备与模式，切换会话自动恢复（不同会话可分别处于 不同主机或本地）。限制：宿主侧 fs/subprocess 接缝按全局模式路由，隔离作用于面板与显式 remote_* 工具。
• 符号链接跟随：远程文件树正确识别符号链接目录（如 AutoDL 的 /root/autodl-tmp）。
• 显式远程工具：remote_status / remote_ls / remote_read / remote_write / remote_mkdir / remote_rm / remote_rename / remote_glob / remote_grep，以及 ssh_exec / ssh_upload / ssh_download。

SSH 主机配置：别名 / 主机 / 端口 / 用户名 / 密码或密钥 / 远程根目录，保存并测试连接后一键进入 SSH 模式。

进入 SSH 模式后，右侧面板自动切换为远程文件树，read / write / edit / glob / grep 与终端透明地在远程服务器执行。

操作速览

• 布局切换：预览 tab 条右侧「⇊ / ⇉ / ⇱」循环切换——下框展示 / 右侧抽屉（默认）/ 浮动覆盖（更宽）。
• 拖拽停靠：按住 tab 条 / 工具栏空白处拖出成浮窗；拖到屏幕右缘松手停靠回右栏抽屉；拖到预设位吸附。
• 编辑文件：打开 .py / .md / .js 等文件 → 直接输入 → Ctrl+S 保存（mtime 冲突检测）。
• 运行代码：打开 .py / .js / .sh 等文件 → 工具栏「▶ 运行」，SSH 模式下在远程主机执行。
• 打开终端：预览工具栏「>_ 终端」，或文件栏 tab 条「>_」按钮（不打开代码也能开命令行）。
• 查看 diff：外部编辑 / 保存后自动弹卡；点「编辑最新版本」直接改，点「刷新」保留红绿。
• 文件右键：文件树节点右键 → 下载 / 重命名 / 复制 / 粘贴 / 删除（本地与远程一致）。

仓库结构

dsh-IDE/
├── packages/
│   ├── dsh-aionui-panel/ # 右侧面板系统：文件树/预览/终端/编辑 diff/类型色标签（IDE 工作区本体）
│   ├── dsh-ssh/          # SSH 引擎：ssh2 连接池、exec/PTY/SFTP/隧道/集群（SSH 远程模式依赖）
│   └── dsh-easyssh/      # SSH 远程工作区：模式状态机、接缝门面、远程实现、Web GUI 前端
└── README.md

右侧文件面板（文件树 / 预览 / 终端 / 右键菜单 / 编辑 diff）由 dsh-aionui-panel（DSH Web GUI 右侧 面板系统）提供，本仓库内与 dsh-IDE 配套维护；dsh-easyssh 通过 sshWorkspaceMode 跨插件服务驱动它 跟随 SSH 模式。SSH 远程开发只是 dsh-IDE 的能力之一——本地目录同样享受完整的 IDE 工作区。

安装

前置要求：Node.js ≥ 22、pnpm、已安装 dsh（npx @deepseek-ai/dsh）。

# 1) 克隆并构建
git clone https://github.com/chenw2759-wq/dsh-IDE.git
cd dsh-IDE
pnpm install
pnpm --filter "./packages/dsh-aionui-panel" build
pnpm --filter "./packages/dsh-ssh" build
pnpm --filter "./packages/dsh-easyssh" build

# 2) 把三个包安装到 web profile（注意用你自己的绝对路径）
dsh plugin --profile web add file:C:/你的路径/dsh-IDE/packages/dsh-aionui-panel
dsh plugin --profile web add file:C:/你的路径/dsh-IDE/packages/dsh-ssh
dsh plugin --profile web add file:C:/你的路径/dsh-IDE/packages/dsh-easyssh

仓库品牌为 dsh-IDE；核心插件包名沿用 dsh-easyssh（安装标识，不随品牌改名）。

💡 pnpm 构建放行（一行）：dsh-ssh 依赖的原生库（ssh2 / cpu-features）需要构建。pnpm 10+ 默认阻止依赖构建脚本，dsh plugin add 会报 ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: [email protected], [email protected]，并在 <profile>/pnpm-workspace.yaml 里自动写入占位：

allowBuilds:
  cpu-features: set this to true or false
  ssh2: set this to true or false

把两个 set this to true or false 改成 true，然后重新执行第 2 步的 dsh plugin add （重复执行是幂等的）。这是 pnpm 的标准流程，任何带原生依赖的插件都一样。

第 3 步：接缝切换（自动，无需手动）

安装 dsh-easyssh 时，其自带的 cordis.patch.yml（经 dsh.bundle.patch 声明）会作为 profile bundle 层自动应用：禁用部署自带的 fs-sandbox / subprocess，挂载模式路由门面 easyssh-fs / easyssh-subprocess（SSH 模式下模型工具透明地远程执行；本地模式委托回同一套 沙箱实现）。不需要手动编辑 <profile>/cordis.patch.yml。

⚠️ 升级用户必读：手动写入接缝补丁只属于 0.1.0 之前的旧版本。若你按旧文档在 <profile>/cordis.patch.yml（Windows 默认 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml） 里写过手写补丁，升级后必须把它删除（恢复为 []）——否则自动补丁 + 手写补丁各插入一次 相同的 ssh-workspace-fs / ssh-workspace-subprocess 行，启动会报 duplicate loader entry id 错误。删除后重启即可（自动补丁内容与旧手写补丁一致，行 id 相同）。

第 4 步：重启

# 重启 dsh
npx @deepseek-ai/dsh web

打开 http://127.0.0.1:3080 → Ctrl+F5 硬刷新（浏览器缓存旧 client 包时必做）→ 右上角 SSH 按钮配置主机 → 进入 SSH 模式。

回滚 = 把 cordis.patch.yml 恢复为 [] 再重启。

使用

1. 会话右上角（session log 左侧）点击 SSH → 填主机（别名/主机/端口/用户名/密码或密钥/远程根） → 保存并测试 → 进入 SSH 模式。
2. 右侧面板自动切换到远程文件树；直接对 Agent 说「读/改远程文件」「在服务器上执行命令」——普通工具即远程执行。
3. 路径规则：远程绝对路径直接用；相对路径以远程根 remoteRoot（默认 ~）为基准；不要用 Windows 本机路径。
4. 右上角切换按钮随时回到本机模式。

安全

• 路由仅 loopback（同源校验）；认证材料存 ~/.dsh/dsh-ssh.json（0600）。
• 远程操作消耗真实远程资源，先确认再执行；SSH 模式下本机沙箱不对远程执行生效。
• 远程 grep/glob/realpath 依赖 GNU find/grep/coreutils。

致谢

远程 ctx.fs / ctx.subprocess 实现移植并改编自 UynajGI/dsh-ssh （MIT，详见各文件头与 NOTICE），在其基础上补全了 Web GUI 前端与运行时模式切换。

License

BSD-3-Clause。远程实现的 MIT 版权归 UynajGI/dsh-ssh 原作者（见 NOTICE）。