前言¶
平時在 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
