pkgdiet

🥗 PkgDiet

面向 AI 辅助 JavaScript 和 TypeScript 开发的依赖策略。
给你的 node_modules 减减负。

问题： AI 编码 Agent（Claude Code、Codex、Cursor、Windsurf、Cline）会推荐不存在、已弃用、存在漏洞或名称仿冒的包。没有内置机制可以阻止它们执行安装操作。

解决方案： PkgDiet 使用原生 Agent 钩子 API，拦截 AI Agent 生成的每条 npm install / pnpm add / yarn add 命令，并在执行前阻止未经批准的安装。

---

🔒 实测演示

运行以下命令，查看 PkgDiet 如何在终端中拦截真实且有风险的 AI 生成依赖：

npx [email protected] demo

输出示例：

🔒 PkgDiet — Live AI Dependency Enforcement Demo
   Simulating what happens when an AI agent tries to install these packages.

🟡  WARNING — moment
   Context:   AI suggested this for date formatting
   Score:     100/100
   Reason:    Efficiency Flag: Better alternatives exist for moment.
   Use this:  dayjs, date-fns

🔴  BLOCKED — request
   Context:   AI suggested this for HTTP requests
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  undici, native fetch
   CVEs:      GHSA-p8p7-x288-28g6

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🔴  BLOCKED — node-uuid
   Context:   AI suggested this for UUID generation
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  crypto.randomUUID(), uuid

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🟡  WARNING — lodash
   Context:   AI suggested this for array utilities
   Score:     80/100
   Reason:    Efficiency Flag: Better alternatives exist for lodash.
   Use this:  lodash-es, native JS

📊 Demo Summary: 2 blocked, 2 warned
   These checks run automatically before every npm install in your AI agent.
   Setup: npx [email protected] init

查看机器可读的 CI 证明：

npx [email protected] demo --json

---

🚀 一条命令完成设置

npx [email protected] init

这条命令会创建以下文件：

文件	用途
.pkgdietrc.json	仓库依赖策略
.github/workflows/pkgdiet.yml	GitHub Actions CI 门禁
.cursor/mcp.json	Cursor MCP 服务
.cursor/rules/pkgdiet.mdc	Cursor 始终应用的强制执行规则
.cursorrules	Cursor 提示性规则（旧版）
.windsurfrules	Windsurf 提示性规则
cline_mcp_settings.json	Cline MCP 服务
.github/mcp.json	GitHub Copilot MCP
CLAUDE.md	Claude Code 提示性规则
.claude/settings.json	Claude Code PreToolUse 钩子注册
.claude/hooks/pkgdiet-install-guard.sh	Claude Code bash 安装防护
.codex/hooks.json	Codex PreToolUse 钩子注册
.codex/hooks/pkgdiet-install-guard.mjs	Codex Node.js 安装防护

---

🛡️ Agent 强制执行

PkgDiet 使用各 Agent 的原生钩子 API来阻止安装，而不只是提供建议规则：

Agent	强制执行机制	阻止的操作
Claude Code	PreToolUse bash hook (.claude/hooks/)	执行前阻止 npm/pnpm/yarn install
Codex (OpenAI)	PreToolUse Node.js hook (.codex/hooks/)	执行前阻止 npm/pnpm/yarn install
Cursor	MDC alwaysApply 规则 + MCP check_dependency	阻止 AI 编写安装命令
Windsurf	.windsurfrules + MCP check_dependency	阻止 AI 编写安装命令
Cline	MCP check_dependency	通过工具调用在安装前阻止
GitHub Copilot	MCP check_dependency	通过工具调用在安装前阻止
CI (GitHub Actions)	pkgdiet ci 门禁	如果任何新增软件包违反策略，则阻止合并 PR

PreToolUse 钩子的工作原理： 当 Claude Code 或 Codex 生成包含 npm install 的 Bash 工具调用时，注册的钩子脚本会先运行。如果 PkgDiet 返回非零退出代码，Agent 会看到拒绝原因并中止安装——该命令不会运行。

---

🔄 3 阶段策略循环

PkgDiet 使用共享核心引擎（@pkgdiet/core），确保所有接口都应用相同的评估逻辑。

1. 仓库策略： 单个 .pkgdietrc.json 文件决定项目中允许、警告或阻止哪些操作。
2. Agent 钩子（强制执行）： Claude Code 和 Codex 的原生 PreToolUse 钩子会在安装命令执行前拦截命令。MCP check_dependency 会在其他 Agent 编写命令前向其发出指示。
3. CI 门禁（回退机制）： npx pkgdiet ci 在 GitHub Actions 中运行，将 package.json 与基准提交进行比较；如果任何新增软件包违反策略，就会使 PR 检查失败。

---

🛠️ CLI 命令

Commands:
  audit           Audit existing dependencies for policy, health, size, and unused-package signals
  check           Evaluate npm packages against this repository's dependency policy
  demo            Show live proof that PkgDiet blocks risky AI-generated dependencies before install
  mcp             Start the MCP JSON-RPC server over stdio for MCP-compatible AI coding agents
  ci              Enforce policy for dependency changes introduced by this branch
  init            Set up PkgDiet — creates policy, CI workflow, and all AI agent configs
  agent-setup     Configure PkgDiet for AI coding agents (codex, cursor, claude-code, ...)
  alternatives    Browse the PkgDiet alternatives dataset
  drift           Scan project for dependency health drift over time
  policy-check    Validate the repository's .pkgdietrc.json policy

---

⚙️ 配置（.pkgdietrc.json）

{
  "minHealthScore": 70,
  "warnHealthScore": 80,
  "blockDeprecated": true,
  "blockKnownVulnerabilities": true,
  "blockTyposquats": false,
  "requirePinnedVersions": true,
  "maxPackageSizeBytes": 15728640,
  "failOn": "BLOCK",
  "securityMode": "fail-open",
  "blockedPackages": ["moment", "request"],
  "internalNamePrefixes": [],
  "environments": {
    "ci": { "minHealthScore": 80, "failOn": "BLOCK", "securityMode": "fail-closed" },
    "dev": { "minHealthScore": 60, "failOn": "BLOCK", "securityMode": "fail-open" }
  }
}

---

🤖 MCP 集成

PkgDiet 可作为本地模型上下文协议（MCP）服务运行。

AI 编码 Agent 连接到 PkgDiet 后，即可使用以下功能：

• check_dependency：根据本地 .pkgdietrc.json 策略评估 npm 软件包，并返回包含证据的结构化 ALLOW、WARN 或 BLOCK 判定。
• suggest_alternative：查询 PkgDiet 精选的数据集，为被阻止的软件包寻找现代、更轻量且仍在维护的替代方案。

包含的智能功能（全部免费，无需付费服务）：

• OSV 漏洞数据库——检查软件包版本是否存在已知 CVE
• npm 注册表来源验证——验证已签名的 npm 证明
• Typosquat 检测——与 15 个以上热门软件包名称进行编辑距离比对
• Lockfile 固定版本验证——要求 CI 中使用精确的版本固定
• 依赖混淆检测——阻止在公共注册表中发现的内部前缀软件包

---

🔗 文档与支持

• GitHub 仓库： om-tajne/pkgdiet
• 报告问题： Issue Tracker
• 许可证： MIT