dsh-deps-audit

DeepSeek Harness 的依赖审计工具箱：parse_lock 解析 npm / pnpm lockfile 为结构化包清单，find_duplicates 检测同一包名多个共存版本，unused_deps 找出声明了却未被源码引用的依赖。只读、零运行时依赖，帮助你把依赖健康和体积管理起来。

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-deps-audit
• npm：https://www.npmjs.com/package/dsh-deps-audit

功能说明

项目越写越大，依赖越装越乱：同一个包悄悄装了好几个版本、某依赖声明了却根本没人用、lockfile 里到底有多少包谁也说不清。本插件用三档工具帮你把依赖状况摸清楚：

• 解析 lockfile（parse_lock）：解析 npm（package-lock.json / npm-shrinkwrap.json）与 pnpm（pnpm-lock.yaml）lockfile，输出 lock 类型、包总数、直接依赖与包清单。
• 多版本冲突（find_duplicates）：在 lockfile 里检测同一包名存在多个共存版本的情况。这类冲突通常来自传递依赖的版本范围不一致，会造成重复安装与体积膨胀。
• 未使用依赖（unused_deps）：对比 package.json 声明的依赖与源码里的 import / require，找出声明了却未被任何源码引用的依赖，辅助清理。

解析是启发式的：npm 按 JSON 解析，pnpm 用轻量 YAML 子集解析（不引入 YAML 依赖），包名提取对嵌套路径做归一（node_modules/legacy/lodash → lodash）；未使用依赖只匹配 import / require / 动态 import 的裸包名。

安装

npm install dsh-deps-audit

安装后在 cordis.patch.yml 中加入：

- insert:
    - id: deps-audit
      name: "dsh-deps-audit"

使用说明

parse_lock

解析 lockfile 为结构化包清单。path 传 lockfile 路径或所在目录；lock_type 传 auto（自动检测）/ npm / pnpm；show_direct 控制列出多少条直接依赖。

lockfile：E:\project\package-lock.json
格式：npm；解析到包 4 个，直接依赖 3 个
直接依赖（前 3）：
1. lodash@^4.17.21
2. chalk@^2.4.2
3. typescript@^5.0.0
包清单（前 4 / 共 4）：
1. [email protected]
2. [email protected]
3. [email protected]
4. @types/[email protected]
说明：pnpm lock 用轻量 YAML 子集解析（非完整 YAML 语义），个别条目可能遗漏；npm lock 按 JSON 解析。

参数：path（必填）；lock_type（默认 auto）；max_size；show_direct（默认 10）；max_chars。

用户：这个项目 lockfile 里总共有多少依赖

助手：调用 parse_lock，path=package-lock.json，输出包总数与直接依赖

用户：pnpm 项目装了几个包

助手：调用 parse_lock，path=.（自动定位 pnpm-lock.yaml），lock_type=pnpm

find_duplicates

检测同一包名多个共存版本。path 传 lockfile 或所在目录；top 控制列出多少包。

lockfile：E:\project\package-lock.json；格式 npm；包 120 个
多版本共存的包 3 个（前 3 / 共 3）：
1. lodash → 4.17.21, 4.17.19（2 个版本）
2. chalk → 2.4.2, 2.4.1（2 个版本）
3. react → 18.2.0, 17.0.2（2 个版本）
提示：多版本通常来自传递依赖的版本范围不一致；可通过 pnpm overrides / npm resolutions 收敛，或升级上层依赖。

参数：path（必填）；lock_type（默认 auto）；max_size；top（默认 5）；max_chars。

用户：有没有一个包装了两个版本

助手：调用 find_duplicates，path=package-lock.json，列出多版本共存

unused_deps

找出声明了但未被源码引用的依赖。path 传项目根（含 package.json 与源码）；src 指定源码目录（缺省为 path）；top 控制列出多少。

项目：E:\project；声明依赖 12 个；扫描源码 40 个
声明但未在源码中引用（共 2）：
1. moment（声明 ^2.29.0）
2. axios（声明 ^1.0.0）
说明：启发式匹配 import/require 的裸包名；动态路径 import、脚本引用、peer 供宿主用等情况可能误报，请结合业务判断。

参数：path（必填）；src（可选）；max_files；max_size；top（默认 5）；max_chars。

用户：package.json 里有哪些依赖其实没用到

助手：调用 unused_deps，path=.、src=src，列出未使用的依赖

典型场景

• 多版本清理：find_duplicates 找出同包多版本，用 overrides / resolutions 或升级上层依赖收敛，减小体积。
• 依赖清理：unused_deps 定位「声明未用」，确认后从 package.json 移除。
• lockfile 审计：parse_lock 快速掌握项目依赖全貌（多少包、哪些直接依赖）。
• 提交前自查：合并前对 lockfile 跑 find_duplicates，避免把多版本带进主线。
• CI 门禁：核心项目对 package.json 跑 unused_deps，出现未使用依赖即告警，防止越堆越乱。
• 迁移评估：从 npm 迁 pnpm 前先 parse_lock 摸清依赖规模，find_duplicates 评估收敛成本。

安全边界

• 只读：三个工具都不写入、不修改、不删除文件；只读取 lockfile / package.json / 源码做文本扫描。
• 不访问网络：解析全部在本地完成，无任何外部请求，也不外发任何内容。
• 不执行代码：只做文本解析与字符串剥离，不 eval、不加载、不运行被测代码。
• 启发式结论，非权威：pnpm 用轻量 YAML 子集解析，个别条目可能遗漏；未使用依赖的判定是启发式的，动态 import、脚本引用、peer 依赖供宿主用等场景可能误报。
• 限制规模：max_size 跳过超大文件，max_files 限流源码扫描，二进制文件不解析。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-import-graph | unused_deps 判「声明未用」，import-graph 看本地模块依赖结构与孤立文件，互补治理 | | dsh-code-check | 清理未使用依赖后跑 code-check 验证改动 | | dsh-deps-audit（本插件） | parse_lock 管 lockfile，与 import-graph 管本地依赖形成「内外双层依赖治理」 | | dsh-template-render | 把依赖清单 / 冲突列表渲染成 Markdown 报告 | | dsh-chart-ascii | 把各包版本数 / 体积画成条形图，直观对比 | | dsh-test-report | 收敛依赖 / 清理无用依赖后跑测试确认无回归 |

版本说明

• 0.1.0（2026-10-09）：初始版本。
  • parse_lock：自动定位与识别 npm / pnpm lockfile，输出直接依赖与包清单；npm 按 JSON 解析，pnpm 用轻量 YAML 子集解析（零 YAML 依赖）
  • find_duplicates：按包名聚合 lock 内版本，检测多版本共存，按版本数降序输出
  • unused_deps：扫描源码 import / require / 动态 import 裸包名，对比 package.json 声明，列出未引用依赖
  • 包名归一：嵌套路径（node_modules/legacy/lodash）取最后一段，scoped 包（@scope/name）保留两段
  • 只读、跳过二进制/超大文件、多层上限

RoadMap

v0.2（计划）

• 增加 dependency_tree：输出某直接依赖的完整传递依赖子树
• 支持解析 yarn.lock 与 bun.lockb 的说明符格式
• 增加 peer_check：校验 peerDependencies 与实际安装版本的匹配情况

v0.3（展望）

• 输出可选 format=json，便于脚本消费依赖审计结果
• 增加体积估算：结合每个包的 resolved tarball 大小字段粗估安装体积
• 支持 monorepo（pnpm workspace / npm workspaces）：对每个 workspace 包分别审计

FAQ

Q：pnpm-lock.yaml 怎么解析的？ 用轻量 YAML 子集：按缩进容错提取 packages: 段的 /name@version: 键，以及 importers: 段各 workspace 的直接依赖。不引入 YAML 依赖、零运行时开销，但个别复杂 YAML 结构（锚点、别名、多行折叠）可能遗漏，属预期内。

Q：嵌套路径的包名怎么归一？ npm 的 node_modules/legacy/lodash 表示 legacy 包依赖了 lodash，包名取最后一段 → lodash。scoped 包 node_modules/@scope/pkg 保留两段 → @scope/pkg。这样多版本检测能把嵌套与顶层同包正确聚合。

Q：unused_deps 为什么可能误报？ 它只匹配 import / require / 动态 import 里的裸包名。如果依赖通过 require(\${name}`)` 动态路径、脚本文件、或作为 peer 依赖供宿主使用，源码里可能没有静态 import，就会误报为未使用。需结合业务判断，勿盲删。

Q：find_duplicates 的多版本怎么来的？ 通常来自传递依赖的版本范围不一致：A 依赖 lodash@^4.17，B 依赖 lodash@^4.16，若解析器无法收敛到同一版本就会并存。可通过 overrides / resolutions 或升级上层依赖解决。

Q：会执行我的依赖代码吗？ 不会。只读文本解析，不 eval、不加载、不运行 lockfile 或任何被测代码。

Q：lockfile 很大会不会卡？ max_size（默认 20480 KB）跳过超大文件，max_files（默认 300）限流源码扫描，二进制文件不解析。

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-deps-audit
• npm：https://www.npmjs.com/package/dsh-deps-audit

许可证

MIT