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