前言¶
平时在 DeepSeek Harness（DSH）里处理压缩包，常见做法是先解压到某个目录，再在 Files 里翻找，改完文本还要手动打回。dsh-archive-sidebar 把这个流程收进了右侧边栏：不解压就打开子文件，改完原地写回压缩包。它是客户端类插件，维护者 gejx-gejingxuan，定位是 DSH Web UI 右侧边栏里的压缩包管理器。
下面介绍它提供的能力、安装方式、典型流程和已知限制。
这是什么¶
一句话：在 DSH Web UI 的右侧边栏新增一个「压缩包」标签页，像原生解压软件一样浏览 zip / rar / 7z / tar / gz / bz2 / xz，预览并直接编辑其中的文本文件，把未解压的子文件开成侧边栏标签页，也可以交给系统默认程序打开。需要时再让当前会话的 AI 通过插件自带的 archive_* 工具代为修改。
插件是一个 DSH bundle（Host 插件 + Web 客户端插件），无需构建：client.js 是手写的 __ModuleLoader__ bundle，Host 侧是纯 Node ESM。代码使用 MIT License，当前版本 1.0.0。
核心功能¶
- 侧边栏内解析：新增「压缩包」标签页；可以从侧边栏向导打开，也可以在 Files 标签里直接点一个
.zip/.rar/.7z等文件，由插件接管解析。 - 浏览：列出全部条目（目录优先，可展开/折叠），显示名称与解压后大小，顶部可按名称筛选。
- 原生解压软件的用法：双击条目 = 解出到系统临时目录并用默认程序打开（Word / PDF 阅读器 / 看图工具等）；单击 = 在侧边栏标签页里预览该子文件。工具栏提供「用默认程序打开」「解压此条目」「在文件夹中显示」。
- 子文件直开：点任意条目会在右侧边栏新开一个标签页显示这个未解压的子文件。文本带行号预览/编辑，图片直接预览；doc/docx/xls/xlsx/ppt/pptx/pdf 等文档类型给出一键「用默认程序打开」，不在侧边栏里模拟 Office。
- 原地编辑：子文件标签里可切换预览/编辑；编辑器带同步行号、等宽字体、Tab 缩进、
Ctrl+S保存、换行开关、脏标记与还原，保存即原地写回压缩包。 - 直接修改：文本条目保存回原压缩包（原地更新，不另存副本）；也支持新增条目、重命名条目、删除条目、从磁盘添加文件。
- AI 辅助修改：收在面板底部的折叠入口「请求 AI 修改…」里，写一句需求发送给当前会话，AI 通过本插件的
archive_*工具完成修改。日常操作用面板本身即可，不需要 AI。 - 解压 / 新建：整个压缩包或某个子条目解压到指定目录；把目录打包成 zip / 7z / tar / gz / bz2 / xz。
面板按 Harness 原生右侧边栏组件绘制，使用主题 token，自动跟随明暗主题。
安装与启用¶
插件不需要 dsh plugin add 这类命令，通过 Plugins 页或 plugin_manager 安装 bundle。
- Plugins 页添加（推荐）：打开 Harness 设置 → Plugins → 添加插件，选择本仓库目录（本地 clone）或填入 git 地址：
https://github.com/gejx-gejingxuan/dsh-archive-sidebar
- 让 Agent 安装：让 Agent 调用
plugin_manager工具的install_bundle，target填 clone 后的绝对目录或上面的 git 地址（需要 full-access 权限或审批）。
plugin_manager install_bundle --target https://github.com/gejx-gejingxuan/dsh-archive-sidebar
- 安装后如页面未自动更新，刷新一次页面；卸载在 Plugins 页删除该 bundle。
运行要求：Node.js ≥ 20。Windows 上想要 rar 读写请安装 WinRAR（默认路径 C:\Program Files\WinRAR\）。
打开压缩包¶
三种入口：
- 侧边栏顶部的「+」→ 向导里的压缩包卡片。
- 右侧边栏 Files 标签中点击任意压缩包文件。
- 在「压缩包」标签页里直接输入压缩包的绝对路径，例如：
D:\data\site.zip
支持的格式¶
| 格式 | 浏览 / 读取 | 原地修改 | 引擎 |
|---|---|---|---|
| zip / zipx | ✅ | ✅ | 随包 7-Zip (bin/7za.exe) |
| 7z | ✅ | ✅ | 随包 7-Zip |
| tar / gz / tgz / bz2 / xz / cab / iso / lzh / zst | ✅（读取/解压） | ❌ | 随包 7-Zip |
| rar / rar5 | ✅（读取/解压） | ✅（写入需 WinRAR 的 Rar.exe） |
本机 WinRAR (UnRAR.exe / Rar.exe) |
RAR 解包与写入依赖本机 WinRAR。未安装时 RAR 仍可能用 7-Zip 读取（7-Zip 支持 RAR 解包），但写入会提示不可用。
Agent 工具¶
插件注册为全局工具，任何会话都可直接使用：
| 工具 | 作用 |
|---|---|
archive_list |
列出压缩包条目 |
archive_read |
读取一个文本条目 |
archive_write |
覆盖/新增文本条目（mode: replace \| add） |
archive_add_file |
把磁盘上的一个文件加入压缩包（保留原字节） |
archive_rename |
重命名压缩包内的一个条目 |
archive_delete |
删除条目 |
archive_extract |
解压全部或部分条目到目录 |
archive_create |
把目录打包成新压缩包 |
路径一律使用绝对路径，条目名一律使用 POSIX 风格，例如 dir/file.txt。
配置¶
一般不需要改。可以在 profile 的 cordis.patch.yml 中覆盖工具位置，例如 7-Zip 或 WinRAR 不在默认位置时：
- id: archive-sidebar
config:
sevenZip: 'D:\tools\7-Zip\7za.exe'
rar: 'D:\tools\WinRAR\Rar.exe'
unrar: 'D:\tools\WinRAR\UnRAR.exe'
典型流程¶
打开一个 zip 后，在侧边栏里单击 site/config.yaml，右侧边栏新开标签页显示未解压的这份文本。切到编辑模式，改一行，按 Ctrl+S，插件把改动原地写回压缩包，不落临时文件、不另存副本。
遇到 docx、pdf 这类不在侧边栏模拟的文档，点「用默认程序打开」，插件把该条目解到 %TEMP%\dsh-archive-open\… 再交给系统默认程序，压缩包本身不变。
如果一批条目要做同样的文本替换，可以不逐个手改：在面板底部打开「请求 AI 修改…」，写一句需求，由当前会话调用 archive_list、archive_read、archive_write 完成。
安全与限制¶
- 面板请求走
/api/dsh-archive/rpc，只接受已认证的浏览器连接，与 Harness 其它/api路由同一套校验。 - 只能操作本机文件系统上已存在的压缩包；写入只允许 zip / zipx / 7z / rar 原地更新，并校验条目名（拒绝
..、绝对路径、盘符）。 - 单次读取上限：文本 4 MiB、二进制 8 MiB，超出标记
truncated。 - 修改是原地的，不保留自动备份；重要压缩包请先自行备份。
- 加密压缩包（密码）当前不支持。
- 插件卸载后，已注册工具与路由会随 Cordis effect 一起移除。
适用场景与注意¶
适合在 DSH Web UI 里频繁查看、小改压缩包内容的开发者：不想为了看一个文本文件先解压，也不想为改一行反复解压、重压。rar 写入依赖本机 WinRAR，其余格式走随包的 7-Zip 控制台二进制。
需要注意两点：插件以当前 DSH 进程的权限运行，安装前建议先看一遍源码和许可证（MIT，第三方二进制见 THIRD-PARTY-NOTICES.md）；原地修改不做自动备份，动手前先备份重要压缩包。
目录页：https://www.skillhub.cn/plugins/gejx-gejingxuan/dsh-archive-sidebar
GitHub：https://github.com/gejx-gejingxuan/dsh-archive-sidebar
