dsh-popout-sidebar

一句话定位

给 DeepSeek Harness Web UI 增加一个可弹出为独立浏览器标签页的侧边栏，实时列出代理创建或修改的文件以及工作区目录树，并按文件类型（代码、Markdown、图片、PDF、HTML）预览内容。

核心能力

• 追踪代理通过 write/edit 工具写入或修改的文件，自动加入产物列表（同时记录编辑前后的差异片段）。
• 对 bash/pwsh 这类不透明执行器做工作区快照对比，把脚本间接生成的文件（如 python make_chart.py 输出的 PNG）并入产物列表。
• 一键把侧边栏弹出为独立浏览器标签页（/popout-sidebar），可拖到另一块显示器上更大更清晰地查看。
• 按文件类型自动选择预览方式：代码走语法高亮 + 行号、Markdown 渲染成 HTML、图片直接显示、PDF 用内置 pdf.js 渲染（独立标签页则走浏览器原生查看器）、HTML 在沙箱 iframe 里渲染。
• 内置文件树，可懒加载展开工作区目录并直接预览文件；切换会话时文件树会自动重新指向新工作区。
• 一键复制文件路径，或把 @路径 引用写入当前会话的输入框（失败则降级为剪贴板复制）。

技术实现

• 语言: JavaScript（ESM，无 TypeScript；build 产物为 Node 端 host.js 与浏览器端 client.js）
• 关键依赖: cordis（插件加载与 schema 注入，关键词中声明）/ React（客户端组件运行时，client/body.js:25 通过 require('react') 注入）/ 打包内置的 pdf.js（Mozilla PDFium 渲染器，src/vendor/ 目录）/ DSH 自带的 @deepseek-ai/dsh-client-ui-primitives（可选，用于走原生 CodeBlock 高亮）
• 架构模式: 双半插件（Host + Client）。Host 在 Node 进程内监听 tools/result 与 tools/execute 事件追踪产物、注册 /popout-sidebar/* HTTP 路由、注册 slots.inject('settings.section')；Client 通过 shell.overlay 槽位注册常驻按钮 + 浮动面板，二者通过 HTTP 路由通信。构建脚本 scripts/build.js 把 src/shared/、src/host/、src/client/ 用 @@占位符@@ 拼成单文件 bundle。
• 入口文件: host 静态入口 src/index.js（动态加载 src/host.js）、client 单文件 bundle src/client.js、manifest 补丁 cordis.patch.yml、DSH 元数据 package.json#dsh

适用场景

当代理在长时间会话里频繁写文件、改代码、跑脚本生成图片/PDF，而你希望把工作区和文件变更摆在 DSH 对话旁一眼可见时使用；尤其适合需要在大屏（外接显示器）上独立查看产物的工作流，以及对文件结构和差异比对有强需求的开发场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:e2mcc/dsh-popout-sidebar

配置项

配置保存在浏览器 localStorage 键 dsh-popout-sidebar:settings，可在 DSH 设置 → Popout Sidebar 选项卡中调整。

常见问题

Q: 安装后需要在浏览器做什么操作？

A: 装完先重启 dsh web 让 host 端重新加载，然后在浏览器做 Cmd/Ctrl+Shift+R 硬刷新；右上角会出现常驻的「产物」图标按钮（即使没有当前会话也可见），点击即可展开侧边栏。

Q: 这个侧边栏和其他 sidebar 插件冲突吗？

A: 不冲突。它把面板固定在右侧，当其他 sidebar 插件打开时本面板会自动让位到其左侧，二者可同时显示；面板宽度通过读取宿主 --dsh-sidebar-width 变量做位移偏移。

Q: 「清除」按钮会删除磁盘上的文件吗？

A: 不会。清除只会从内存里的产物列表移除条目（host 端的 removeFile 仅 splice 数组），磁盘文件保持不变；面板顶部还有提示文案「仅清除内存记录，不删除磁盘文件」。

Q: 它怎么追踪 shell 命令产生的文件（比如 python 脚本生成的 PNG）？

A: 对 bash 和 pwsh 这两个执行器，插件在工具执行前后对工作区做指纹快照（递归遍历目录，用文件 version token 做指纹，跳过 node_modules、.git 等大目录，深度 16、5000 文件上限），比对差异后把新增或改写的文件并入产物列表；其他不透明执行器暂不追踪。

Q: 设置保存在哪里？跨设备同步吗？

A: 保存在当前浏览器 localStorage 键 dsh-popout-sidebar:settings，不跨设备同步；如需在新设备上获得同样设置，建议截图后手动调整，或直接复用同一浏览器 profile。

Q: 独立标签页里的 PDF 预览为什么能离线用？

A: pdf.js 的 lib 与 worker 被打包进了 src/vendor/，由构建脚本内联进 src/host.js，host 通过 /popout-sidebar/pdfjs/pdf.min.js 与 pdf.worker.min.js 路由以一年强缓存吐给浏览器；侧边栏内嵌自定义 pdf.js 渲染，独立标签页走浏览器原生 PDF 查看器。

上手难度

入门 — 安装一条命令即可使用，零配置即可看到产物追踪与预览；要体验全部功能（设置调优、清除模式、独立标签页、文件树）只需在 DSH 设置里开关几次。

已知问题与限制

• 文本预览单文件最多截取 200,000 字符，超过会显示 (truncated preview) 提示（src/host/core.js:198）。
• 编辑差异片段会被裁剪到 8,000 字符 / 段，超长替换区域只会展示首部（src/host/core.js:153）。
• 产物列表最多保留 1,000 条记录，超出会按插入顺序丢弃最早条目（src/host/core.js:52）。
• 工作区快照递归深度上限 16、单次最多扫描 5,000 个文件，并固定跳过 node_modules、.venv、.git、dist、build 等目录（src/host/core.js:22-29）；无法自定义跳过目录。
• 仅对 bash 和 pwsh 两个执行器做快照对比追踪，其他「不透明」执行器产生的文件不会被自动收录（src/host/core.js:19）。
• 媒体路由单次读取上限 25 MB，体积更大的二进制预览可能失败（src/host/routes.js:64）。
• 独立标签页默认强制浅色主题（在另一显示器上更稳定），如需深色需在 URL 后手动加 ?scheme=dark（src/host/page.js:8-12）。

可弹出式侧边栏：侧边栏展示产物与文件树，支持多种文件预览形式；并可弹出为独立浏览器标签页（可拖至另一显示器上更大更清晰的观看）；兼容其他 sidebar 插件，可以同时显示。

Popout Sidebar: a sidebar that lists the agent's artifacts and a file tree, with multiple preview formats, and pops out into a separate browser tab (drag it to another monitor for a larger, clearer view) — coexisting with other sidebar plugins at the same time.

给 DeepSeek Harness Web UI 增加一个展示产物（artifacts）与文件树的侧边栏，并可一键弹出为独立浏览器标签页。

已上线 / Now available

本插件已收录进 DeepSeek Harness 插件生态：

一键安装（推荐）

先装市场：

dsh plugin --profile web add dshmarket

重启 dsh web 后，打开 设置 → Plugin Market，搜索 popout 或 sidebar，点「安装」。

或直接按注册表命令安装：

dsh plugin --profile web add github:e2mcc/dsh-popout-sidebar

装完重启 dsh web 并硬刷新浏览器（Cmd/Ctrl+Shift+R），界面右上角出现常驻「产物」图标按钮（无会话时也可见）。

特性 / Features

• ↗️ 弹出为独立标签页：一键把侧边栏弹出为独立网页标签页（/popout-sidebar），每 1.5s 自动刷新，可拖到另一块显示器上更大、更清晰地观看。
• 🗂 产物侧边栏：实时列出代理通过 write / edit 创建或修改的文件，以及 bash / pwsh 命令在工作区里产生的文件（如脚本生成的图片）；列表与预览区之间的分界线可拖动调整。
• 🌳 文件树：侧边栏与独立标签页内都有「文件树」，可浏览当前工作区目录（懒加载展开，点击文件即预览），并实时跟随工作区切换。
• 👀 多类型预览：按文件类型预览——代码 / 纯文本（语法高亮 + 行号）、Markdown 渲染、图片、PDF（浏览器原生查看器）、HTML（沙箱 iframe），超长内容自动截断。
• 📝 编辑差异：edit 修改过的文件在预览里展示「删除 / 新增」改动片段对比。
• 🔗 复制 / 引用：一键复制文件路径，或把 @path 引用写入会话输入框（悬浮在列表行）。
• 🧭 与其他 sidebar 兼容：其他「侧边卡片」打开时，本侧边栏自动让位到其左侧，两者同时可见。
• ⚙️ 设置面板：DSH 设置里新增「Popout Sidebar」选项卡，可开关默认展开、自动刷新、文件树，设置最短面板宽度（存于 localStorage）；面板更宽可通过拖动左边缘调整。
• 🗑 清除模式：右上角进入清除模式后，点击产物将其标红，再点红色 × 移除列表条目（仅移除条目，不动磁盘文件）。
• ✖️ 关闭：点击右上角「产物」图标按钮收起面板。

工作原理 / How it works

• Host（Node 进程）
  • 监听 tools/result 事件，追踪 write / edit 的成功调用并提取 file_path（edit 额外记录 old_string/new_string 改动片段，并按扩展名标注预览类型）。
  • 监听 tools/execute 事件，对 bash / pwsh 这类「不透明」执行器做工作区前后快照对比（fs.listDir 递归 + 版本 token 指纹，跳过 node_modules/.git 等大目录），把命令间接新增/改写的文件并入产物列表。
  • 通过 harness.handle 暴露 RPC：artifacts.list、artifacts.read、artifacts.remove、artifacts.listDir。
  • 通过 webServer.register 提供路由：/popout-sidebar（页面）、/popout-sidebar/data（JSON）、/popout-sidebar/content（文本预览）、/popout-sidebar/media（二进制图片 / PDF）、/popout-sidebar/remove（移除条目）、/popout-sidebar/listdir（目录列表）。
• Client（浏览器）
  • 在 shell.overlay（root 作用域）注册一个固定于右上角的常驻「产物」图标按钮，无会话时依然可见。
  • 在 shell.overlay 渲染浮动侧边栏面板。
  • 订阅 session store、并通过跨标签页 localStorage 同步当前会话，让侧边栏与独立标签页的文件树实时跟随工作区切换（行为一致）。

目录结构 / Layout

.
├── README.md
├── LICENSE
├── package.json          # 静态 bundle 元数据（main / exports ./client / dsh.bundle / dsh.client）
├── cordis.patch.yml      # bundle 挂载补丁（dsh plugin add 自动识别）
├── scripts
│   ├── build.js          # 组装脚本：把 src/{shared,host,client} 拼成下面的两个单文件 bundle
│   └── precommit.sh      # 提交前守护：自动重建 bundle，产物过期则拦截提交
└── src
    ├── index.js          # 静态 Host 入口（ESM）：求值 host.js 主体并导出给 loader
    ├── host.js           # ⚙️ 生成产物：Host 单文件（由 scripts/build.js 生成，勿手改）
    ├── client.js         # ⚙️ 生成产物：Client 单文件 bundle（由 scripts/build.js 生成，勿手改）
    ├── shared/           # 两端共享的可复用纯函数（可移植 JS，无模板字符串）
    │   ├── ext.js        #   扩展名 → 预览类型（extType / fileExt）
    │   ├── markdown.js   #   极简 Markdown → HTML（含代码块高亮）
    │   └── highlight.js  #   零依赖语法高亮器（tok-* token）
    ├── host/             # Host 半模块（Node 进程）
    │   ├── body.js       #   骨架：inject / apply + 占位符
    │   ├── core.js       #   常量 + 产物追踪 + 文件操作 + RPC
    │   ├── page.js       #   独立标签页 HTML（内联 script 引用 shared）
    │   └── routes.js     #   /popout-sidebar/* HTTP 路由
    └── client/           # Client 半模块（浏览器）
        ├── body.js       #   骨架：__ModuleLoader__ 工厂 + 占位符
        ├── core.js       #   store / settings / 会话辅助
        ├── styles.js     #   注入的 CSS
        ├── icons.js      #   内联 SVG 图标
        ├── preview.js    #   renderPreview / CodeView / diff
        └── components.js #   FileTree / ArtifactsPanel / 设置面板

修改 src/shared/、src/host/、src/client/ 里的源码后，运行 npm run build（或 node scripts/build.js）重新生成 src/host.js 与 src/client.js，再提交。运行时 DSH 只加载这两个生成产物。

建议安装提交前守护（一次即可）：ln -sf ../../scripts/precommit.sh .git/hooks/pre-commit。之后每次 git commit 会自动重建 bundle，若产物与源码不同步会直接拦截提交，杜绝「源码新、产物旧」。

使用 / Usage

本插件同时支持静态安装（推荐，持久生效）与动态加载（临时）。

静态安装（推荐）

前置：DSH 已装好（dsh web 能正常运行）。

# 通过注册表（GitHub 源码）
dsh plugin --profile web add github:e2mcc/dsh-popout-sidebar

# 或通过 dsh-market 市场：装好市场后在 设置 → Plugin Market 里一键安装

装完重启 DSH 服务（host 半加载）并硬刷新浏览器（Cmd/Ctrl+Shift+R），界面右上角即出现常驻「产物」图标按钮。

• 包内 cordis.patch.yml（dsh.bundle.patch）让 CLI 自动把它挂进 dsh.profile.bundles；
• client 半由 package.json 的 dsh.client.platform: "web" + exports["./client"] 自动发现并加载；
• 本地开发用 dsh plugin --profile web add /绝对路径/dsh-popout-sidebar 会安装为符号链接，改 src/ 后重启服务 / 硬刷新即可生效。

动态加载（临时，进程级）

src/host.js 与 src/client.js 的 return { ... } 主体仍可直接传给 cordis_define：

1. 在 Harness 会话中调用 cordis_define：code.host 填 src/host.js 的 return { ... } 主体；code.client 填 src/client.js 的 return { ... } 主体。
2. 调用 cordis_run 激活返回的 pluginId / packageId。
3. 点击「产物」按钮；点面板右上角 ↗ 打开独立标签页。

两种模式下 host 与 client 都通过 /popout-sidebar/* HTTP 路由通信（动态模式另保留 harness.handle RPC 兼容），因此行为一致。

设置 / Settings

在 DSH 设置面板（左下角 ⚙️）里会多出一个「Popout Sidebar」选项卡：

右上角的「产物」图标按钮、独立标签页按钮（↗）、以及「自动让位到其他侧边栏左侧」均为常驻行为，无需开关。

设置保存在浏览器 localStorage（键 dsh-popout-sidebar:settings），刷新后仍然生效。

主题 / Theming

• 侧边栏面板跟随主界面浅色 / 深色主题（使用 --dsw-alias-* 主题变量）。
• 独立标签页刻意固定为浅色配色（保证在另一显示器上内容清晰稳定）；如需深色，可在地址后手动加 ?scheme=dark。

更新 / Updates

• 本插件从 GitHub 源码安装（未发布 npm），更新按 commit 比对：dsh-market 的「更新」会自动比对本地锁定的 commit 与仓库当前 HEAD，检测到新提交即提示「更新可用」，点一下即可升级。
• 命令行更新：dsh plugin --profile web update dsh-popout-sidebar（或重新 add），随后重启 dsh web 并硬刷新浏览器。

License

MIT