前言¶
在 DeepSeek Harness（DSH）裏排查 Electron 應用或本地打包產物時，經常要打開 app.asar 或 .zip 看裏面的 README、配置或源碼片段。常見做法是臨時寫一段解析腳本：自己算 asar 頭部偏移、控制別把上萬條條目全塞進對話，還要避免誤寫磁盤。dsh-plugin-archive-reader 把「列條目、讀單條、按正則搜內容」收成三次模型側工具調用，且聲明爲零依賴、只讀、不聯網。
下面介紹它是什麼、怎麼裝、三個工具怎麼用，以及支持範圍與配置上限。
這是什麼¶
dsh-plugin-archive-reader 是維護者 XHXnb123 提供的 DSH Host 插件（GitHub 倉庫：XHXnb123/dsh-plugin-archive-reader）。在社區目錄 skillhub.cn 中歸類爲「聯網工具」；插件本體在 README 中明確爲不聯網、只讀，全部在本地用 Node 內置模塊解析歸檔。
插件向會話註冊三個工具：archive_list、archive_read、archive_grep。當前 package.json 版本爲 0.1.0，許可證 MIT，運行時要求 Node >= 20，並聲明 peerDependencies: { "@deepseek-ai/dsh": ">=0.2.0-rc.1" }。
核心功能¶
三個只讀工具¶
| 工具 | 用途 | 關鍵參數 |
|---|---|---|
archive_list |
列條目，支持按正則/子串過濾 | path、pattern?、limit?、format? |
archive_read |
讀單個條目的文本內容 | path、entry、maxBytes?、format? |
archive_grep |
在所有文本條目裏按正則搜內容 | path、pattern、maxMatches?、maxEntryBytes?、format? |
共性行爲（來自 README）：
- 只打開歸檔讀數據，不寫盤、不修改任何 profile 狀態。
pattern先按不區分大小寫的正則解釋；解析失敗（例如x(1）自動退回子串匹配，返回值裏的matcherKind標明用了哪種方式。archive_read若檢測到二進制（開頭有 NUL 字節），只報告大小並設binary: true，不返回內容。entry須精確匹配（也接受忽略大小寫的完全一致）；找不到時會列出相近候選。
典型調用示例¶
README 給出的動機示例：在 app.asar 裏搜文檔標題，而不手寫偏移腳本：
archive_grep { path: "...\\app.asar", pattern: "版本兼容性與豁免" }
→ dsh/node_modules/@deepseek-ai/dsh-plugin-manager/README.zh.md:61: ### 版本兼容性與豁免
安裝與啓用¶
官方安裝方式如下（npm 名與本地路徑二選一；npm 尚未發佈時用本地路徑）：
dsh plugin --profile web add dsh-plugin-archive-reader # npm 安裝（尚未發佈時用下面的本地路徑）
dsh plugin --profile web add D:\path\to\dsh-plugin-archive-reader
裝完後完全重啓 dsh（不是僅刷新頁面），三個工具纔會出現在會話裏。
若本機 dsh 版本與 peerDependencies 不一致，Harness 兼容性檢查可能拒絕加載；可用 dsh plugin allow-version 寫精確版本豁免（README 說明插件本身不 import Harness 包，不依賴 dsh 安裝樹裏的包解析）。
支持範圍與限制¶
- 支持：
.asar（Electron 打包格式）與.zip（store / deflate）。 - 不支持：ZIP64、加密條目、tar/gz/7z/rar——遇到會明確報錯，不做靜默降級。
- zip 條目名未聲明 UTF-8 時（歷史 CP437）按 UTF-8 盡力解碼，可能有亂碼。
- 截斷按字節切，可能切在多字節字符中間，解碼後會出現替換字符。
archive_grep逐條解壓掃描，受總掃描預算約束（默認 64 MB，觸頂時在stoppedEarly裏說明）；大歸檔會有可感知的 CPU 佔用。- asar 中
unpacked條目從<歸檔名>.unpacked/目錄讀取。
配置（cordis.patch.yml）¶
cordis.patch.yml 裏該插件行的 config 支持下列字段（均有常量硬上限）：
| 字段 | 默認 | 含義 |
|---|---|---|
maxEntries |
200 | archive_list 默認返回條目數 |
hardMaxEntries |
5000 | 單次調用可請求的條目上限 |
maxReadBytes |
65536 | archive_read 默認返回字節數 |
hardMaxReadBytes |
1048576 | 單次可請求的字節上限 |
maxMatches |
50 | archive_grep 默認命中行數 |
hardMaxMatches |
500 | 單次可請求的命中上限 |
maxEntryBytes |
4 MB | archive_grep 跳過的單條目大小 |
maxScanBytes |
64 MB | archive_grep 的總掃描預算 |
maxLineChars |
400 | 單行匹配文本的最大長度 |
timeoutMs |
30000 | 三個工具的工具級超時 |
依賴與安全¶
- 零運行時依賴：僅使用
node:fs、node:zlib；無安裝腳本、無postinstall、無第三方包。 - 不聯網：全部本地解析。
- 只讀：README 稱代碼中無寫文件調用（
fs.open(..., 'r')與fs.readFile）。
插件以當前 dsh 進程權限運行；安裝前建議自行查看倉庫源碼與 MIT 許可證，確認路徑與歸檔來源可信。DSH 社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
不想讀源碼時，倉庫提供 PLAIN.zh.md 一頁紙說明；Windows 可雙擊 verify.bat，或運行 node scripts/verify.mjs 做自測彙總。
適用場景¶
- 在 Harness 會話裏快速列出 Electron
app.asar或 zip 包內路徑，再定點讀 README / 配置。 - 用
archive_grep在大歸檔裏按關鍵詞或正則定位行，避免把整包條目導入對話。 - 本地插件或打包產物排查：配合只讀策略，減少臨時腳本與誤寫風險。
不適合：需要 ZIP64、加密 zip、tar/gz/7z/rar，或必須在插件內聯網拉取歸檔的場景——本插件會直接報錯或不提供能力。
結尾¶
dsh-plugin-archive-reader 把 asar/zip 的列目錄、讀單文件、正則檢索收成三個 DSH 工具，零依賴、只讀、不聯網，並給出條目與掃描字節上限及超時配置。目錄頁：skillhub.cn/plugins/XHXnb123/dsh-plugin-archive-reader；源碼與詳細說明：github.com/XHXnb123/dsh-plugin-archive-reader。
