依赖供应链审计zoahdev/dsh-dep-audit

dsh-dep-audit

npm

CI
License: MIT
dsh-plugin

针对 DeepSeek Harness（dsh）项目与配置文件的依赖供应链卫生审计。

它回答的问题是：“我能信任这个 dsh 插件 / 配置文件的依赖图吗？” —— 解析不到任何版本的 peer 范围、与声明的范围相矛盾的 dist-tag、陈旧或无许可证的依赖、非 registry 来源，以及已安装版本与 package.json 声明内容之间悄然发生的漂移。

与 zoahdev 安全套件的其余部分互补：

| 工具 | 关注点 |
|---|---|
| dsh-poison-guard | 插件代码的恶意软件 / 混淆扫描 |
| dsh-plugin-doctor | 发布就绪性：manifest/patch/build/pack/install |
| dsh-dep-audit | 依赖图卫生：可解析性、dist-tag、陈旧度、来源、许可证、漂移 |

安装

dsh plugin add dsh-dep-audit

或者不安装到 dsh 中，直接独立运行：

npx dsh-dep-audit .

检查项

| 检查项 | 验证内容 | 触发时的状态 |
|---|---|---|
| manifest | package.json 存在、可解析、声明了 name / version | fail |
| peer-resolvable | 每个 peerDependencies 范围至少匹配 registry 上一个已发布的版本 | fail |
| dist-tag | dist-tags.latest 不与声明的范围相矛盾（损坏的 latest / ERESOLVE 类问题，例如 discussion #2763） | warn |
| source | 被审计的依赖使用 registry 说明符，而非 git: / file: / link: / workspace: | warn |
| license | registry 依赖在其最新发布的元数据中声明了许可证 | warn |
| freshness | registry 依赖在过去 365 天内有发布（可配置） | warn |
| drift | node_modules 中已安装的版本满足声明的范围（ERESOLVE / 宿主遮蔽类问题） | fail |
| outdated | 已安装的版本未落后于 registry 的 latest | warn |

仅当所有检查都通过（没有 fail 项）时，ok 才为 true。警告是真实的信号，但不是阻断项。

CLI

dsh-dep-audit [dir] [options]

--json               打印机器可读的报告
--offline            跳过 registry 网络调用
--all                包含 devDependencies
--registry      npm registry 基础 URL（默认：NPM_CONFIG_REGISTRY 或 registry.npmjs.org）
--stale-days      当最新发布早于 n 天时发出警告（默认 365）
--help               显示帮助
退出码：0 全部通过，1 至少一项失败，2 用法/IO 错误。

npx dsh-dep-audit . --json
npx dsh-dep-audit ~/.dsh/profiles/web --offline

在 harness 内使用（可由 agent 调用）

安装后，向你的 dsh agent 提问：

审计一下当前插件的依赖健康：dep_audit，目录指向项目根目录。
Run a dependency audit on this plugin: dep_audit with dir set to the project root.

agent 会调用 dep_audit 工具（dir，可选 options），返回一份 dsh-dep-audit/v1 报告：

{
"schema": "dsh-dep-audit/v1",
"target": ".",
"offline": false,
"ok": true,
"summary": { "total": 8, "pass": 8, "warn": 0, "fail": 0 },
"checks": [ ... ]
}

示例

在没有网络访问的情况下审计一个 profile：

npx dsh-dep-audit ~/.dsh/profiles/web --offline

在 CI 中以依赖卫生作为门禁：

- run: npx dsh-dep-audit .

为什么需要它

- pnpm 可能会悄悄把一个较旧的 RC 链接进插件的 peer 槽位；“能正常加载” ≠ “符合声明的 peer 范围”。drift 把这一前提变成经过检查的事实。
- npm 的 latest dist-tag 可能指向一个陈旧、损坏的构建，而 next 才是真正的发布版本——此时 dsh plugin add  会为所有人解析出意料之外的东西。dist-tag 会在它造成伤害之前标记出这一矛盾（讨论 #2763 中的那类失败）。
- 一个最新发布已是数年前的依赖，或者缺少许可证的依赖，在一个每周新增数千个插件的供应链中是一个危险信号。
- 无许可证或陈旧的依赖不是恶意软件——那是 poison-guard 的职责。本插件是供应链故事中“健康饮食”的那一半。

报告信封

每项检查都携带 { id, status, title, detail, items }；items 是 { name, issue, level }，其中 level: warn | fail。schema 版本（dsh-dep-audit/v1）稳定且机器可读，适用于 CI。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI 会运行 dsh-plugin-doctor 预检、单元测试、一个打包产物的集成测试（安装真实 tarball 并调用真实的 dep_audit 处理器），以及在 Windows 上对全新 profile 进行 dsh web 启动冒烟测试。

许可证

MIT © 2026 zoahdev

dsh-dep-audit（中文）

DeepSeek Harness（dsh）项目与 profile 的依赖供应链卫生审计。

回答一个具体问题：“这个 dsh 插件 / profile 的依赖图能信吗？” —— peer 范围在注册表上解析不到、dist-tag 与声明的范围互相矛盾、依赖长期不更新或没有许可证、用了 git/file/workspace 来源，以及安装版本与 package.json 声明悄悄漂移。

与 zoahdev 安全套件的分工：

| 工具 | 定位 |
|---|---|
| dsh-poison-guard | 插件代码的恶意/混淆扫描 |
| dsh-plugin-doctor | 发布就绪：manifest/patch/build/pack/install |
| dsh-dep-audit | 依赖图卫生：可解析性、dist-tag、过期、来源、许可证、漂移 |

安装

dsh plugin add dsh-dep-audit

不装进 dsh 也能单独用：

npx dsh-dep-audit .

检查项

| 检查 | 验证内容 | 触发级别 |
|---|---|---|
| manifest | package.json 存在、可解析、有 name / version | fail |
| peer-resolvable | 每个 peerDependencies 范围在注册表上至少有一个已发布版本 | fail |
| dist-tag | dist-tags.latest 不与声明范围矛盾（坏 latest / ERESOLVE 一类，见 讨论 #2763） | warn |
| source | 依赖使用注册表来源，而非 git: / file: / link: / workspace: | warn |
| license | 注册表依赖的最新元数据声明了许可证 | warn |
| freshness | 注册表依赖在 365 天内有新发布（可配置） | warn |
| drift | node_modules 里的实际版本满足声明范围（ERESOLVE / 宿主遮蔽类） | fail |
| outdated | 已安装版本不落后于注册表 latest | warn |

只有所有检查都没有 fail 项时 ok 才为 true。warn 是真实信号，但不是硬阻塞。

CLI

dsh-dep-audit [dir] [options]

--json               输出机器可读报告
--offline            跳过注册表网络请求
--all                把 devDependencies 也纳入审计
--registry      npm 注册表地址（默认 NPM_CONFIG_REGISTRY 或 registry.npmjs.org）
--stale-days      超过 n 天未发布即告警（默认 365）
--help               帮助

退出码：0 全过，1 有 fail，2 用法/IO 错误。

npx dsh-dep-audit . --json
npx dsh-dep-audit ~/.dsh/profiles/web --offline

在 harness 内使用（agent 可调用）

装好后对 agent 说：

审计一下当前插件的依赖健康：dep_audit，目录指向项目根目录。

agent 会调用 dep_audit 工具（dir，可选 options），返回 dsh-dep-audit/v1 报告：

{
"schema": "dsh-dep-audit/v1",
"target": ".",
"offline": false,
"ok": true,
"summary": { "total": 8, "pass": 8, "warn": 0, "fail": 0 },
"checks": [ ... ]
}

为什么需要它

- pnpm 可能把旧 RC 静默链进插件的 peer 槽；“能加载”≠“符合声明的 peer 范围”。drift 把这条前置条件变成可核验的事实。
- npm 的 latest dist-tag 可能指向旧坏包，而 next 才是真版本——dsh plugin add  会让所有人解析到意外结果。dist-tag 在踩坑前先标出矛盾（讨论 #2763 的失败类别）。
- 最新版本几年没动、或没有许可证的依赖，在以每周千计增长的插件供应链里都是红旗。
- 没许可证、长期不更新不等于恶意——那是 poison-guard 的事。本插件负责供应链“健康饮食”这一半。

报告结构

每个检查带 { id, status, title, detail, items }；items 是 { name, issue, level }，level 为 warn | fail。schema 版本 dsh-dep-audit/v1 稳定、可给 CI 解析。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI 跑 dsh-plugin-doctor 预检、单元测试、打包集成（真实安装 tarball 并调用真实 dep_audit handler）、以及 Windows 上全新 profile 的 dsh web 启动冒烟。

许可证

MIT © 2026 zoahdev
相关生态工具

- dsh-dep-audit - 依赖供应链卫生
- dsh-quality-score - 插件质量评分卡 + 全注册表排行榜
- dsh-ecosystem - 健康扫描、影响、趋势、实时仪表盘
- dsh-tutorials - 双语插件流水线教程
常见问题

- 如何安装？ dsh plugin add dsh-dep-audit，或直接运行 CLI（见 README）。
- 需要 API 密钥吗？ 不需要。
- 是只读的吗？ 默认是；任何写入/应用都是显式标志。