前言¶
在 DSH 里做插件兼容性排查时，若依赖上游的 dsh-compat-check 工具，每次检查都要把完整工具 schema 随请求发给模型，一次检查往往要 4–8 轮往返，每轮输入 token 在 40–100K 量级，而实际计算都在本机完成。对日常开发或 CI 门禁来说，这既慢又贵。下面介绍社区插件 dsh-compat-optimize（维护者 dongchiluo，分类：客户端）：在保持与原有判定逻辑一致的前提下，用磁盘缓存预热、单次返回报告，并提供不经过模型的离线 CLI。
这是什么¶
dsh-compat-optimize 是 DSH 插件，同时附带可独立运行的 Node CLI。仓库说明为：Fast path for DSH plugin compatibility checks: cache warm-up, one-shot reports, zero-token CLI。无需构建步骤，也无额外 npm 依赖。载入 DSH 后注册工具 compat_optimize（插件 id：tool-compat-optimize）。可选依赖同目录下的 dsh-compat-check 加载上游检查逻辑；未安装时使用内置 fallback。
与 dsh-compat-check 的差异¶
| 阶段 | 使用 dsh-compat-check（LLM 工具） | 使用本插件 |
|---|---|---|
| 工具 schema | 每次请求重传（约 1,198 字符描述） | compat_optimize 描述压缩至约 104 字符 |
| 单次检查 | 4–8 轮往返 | action=run 一次返回摘要、报告路径与报告正文 |
| 本地计算 | 反复解析约 4.76 MB 的 app.asar 头（冷路径约 183 ms） |
头信息解析一次并落盘，跨进程复用（暖缓存约 85 ms） |
| 离线 / CI | 只能经模型调用 | bin/compat-check-cli.mjs，0 token |
资料中说明：deferLoading 不能省 token，宿主仍会在每次请求中投影工具定义；缩短 description 才是省 token 的手段。
核心功能¶
DSH 工具动作¶
通过 compat_optimize 的 action 参数调用（action 必填）：
action |
作用 | 是否联网 |
|---|---|---|
status |
缓存状态、上次运行摘要 | 否 |
warm |
解析 app.asar 头并持久化 |
否（除非 withNetwork: true） |
run |
执行检查，返回紧凑摘要与报告 | 否 |
bench |
重复 N 次并报告中位数/最小/最大耗时 | 否 |
notes |
与上游 GitHub release、npm 对照 | 缓存未命中时需联网 |
还可传 installDir、pluginsDir、outDir、cacheDir、iterations、refresh、withNetwork、source 等参数。
离线 CLI¶
node bin/compat-check-cli.mjs [command] [options]
命令：check（默认）、status、warm、notes、bench。
退出码：0 无损坏插件；1 发现不兼容插件；2 运行时错误。
默认不访问网络，除非指定 --notes、--refresh 或 --network。
磁盘缓存¶
默认目录 <baseDir>/.cache/compat-check/，与 dsh-compat-check 字节级兼容，包含 asar-header、asar-entry、upstream、last-run.json 等。条目用内容指纹（首 64 KB 的 sha1）校验，避免 Electron 下 app.asar 合成 stat 导致缓存失效。
安装与启用¶
将仓库放入 DSH 插件目录（默认 <baseDir>/plugins），无需 npm install：
git clone https://github.com/dongchiluo/dsh-compat-optimize.git <baseDir>/plugins/dsh-compat-optimize
<baseDir> 解析顺序：$DSH_COMPAT_BASE_DIR → $DSH_HOME → 用户主目录。CLI 可单独指定根目录，例如：
DSH_COMPAT_BASE_DIR=/opt/dsh node bin/compat-check-cli.mjs check
配置默认值在 cordis.patch.yml，可在个人 profile 中按插件 id 覆盖（整段替换，不合并；省略字段则回退 schema 默认）。常用字段包括：
| 字段 | 默认 | 含义 |
|---|---|---|
baseDir |
空则见上 | 插件、报告、缓存根目录 |
pluginsDir |
空则 baseDir/plugins |
待检查插件目录 |
installDir |
空则自动检测 | DSH 安装目录（可指向 resources/app.asar） |
outDir |
空则 baseDir/out/compat |
报告输出目录 |
cacheDir |
空则 baseDir/.cache/compat-check |
缓存目录 |
warmOnStart |
false |
插件启动时是否预热缓存 |
mainPluginDir |
空则同级 dsh-compat-check |
上游检查逻辑路径 |
典型用法¶
在插件目录下，零 token 做一次检查（退出码即结论）：
node bin/compat-check-cli.mjs check
CI 门禁与 JSON 输出：
node bin/compat-check-cli.mjs check --json
先预热再检查：
node bin/compat-check-cli.mjs warm && node bin/compat-check-cli.mjs check
性能采样：
node bin/compat-check-cli.mjs bench --bench 10
自测（约 60 条断言，无 DSH 安装也可跑大部分用例）：
node _selftest.mjs
适用场景与注意¶
- 适合：需要在对话外批量或自动化做 DSH 插件兼容性检查、希望减少
compat_check多轮 token 消耗、或在 cron/CI 里用退出码做门禁的开发者。 - 环境：Node.js ≥ 20；作为 DSH 插件时需 DSH
>=0.2.1-rc.5 <0.3.0（package.json 版本 0.1.0，MIT 许可证）。 - 安全与权限：插件在当前 DSH 进程权限下运行，会读取安装目录、插件目录并写入缓存与报告。安装前请自行审阅仓库源码与许可证，社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-compat-optimize 把兼容性检查从「多轮 LLM 工具调用」收成「本地缓存 + 一次 run 或一条 CLI」，判定与上游逻辑对齐，并给 CI 提供了明确的退出码。进一步了解可访问目录页与仓库：
- 目录页：https://www.skillhub.cn/plugins/dongchiluo/dsh-compat-optimize
- GitHub：https://github.com/dongchiluo/dsh-compat-optimize
