peerconflict

peerconflict

安装刚刚因 peer 依赖错误而失败，输出中满是嵌套的依赖要求。peerconflict 获取解析后的依赖树——每个已安装软件包的名称和版本，以及每个软件包声明的 peer 要求——并将问题整理成易于阅读的图：

• 边 — 每项 peer 要求对应一条记录，并标记为已满足或未满足。只有 peer 确实已安装，且其已安装版本符合要求的范围时，边才算已满足。
• 冲突 — 未满足的边；如果 peer 根本没有安装，则标记为 missing；如果已安装但版本不在范围内，则标记为 version，并附上一行详情，例如 app requires peer react (^18.0.0) but 17.0.2 is installed。
• 解决方案 — 每个冲突 peer 对应一条记录：引发冲突的要求、满足每个范围的最低版本，以及改动最少的建议——如果 peer 不存在，则安装它；如果已存在，则更改其版本。建议始终针对列出的每个范围表述，确保一次修复能满足该 peer 的所有依赖方。

版本格式为 MAJOR.MINOR.PATCH，且不能包含其他内容。范围必须符合此工具定义的语法：* 接受任何版本，精确版本仅接受该版本，^x.y.z 接受基准版本至下一个不兼容版本界限之前的版本——遵循通常的 0.x 收紧规则，因此 ^0.2.3 不接受 0.3.0 及以上版本，而 ^0.0.3 仅接受 0.0.3——~x.y.z 接受同一小版本内的补丁版本变更，>=x.y.z 接受基准版本及任何更高版本。不符合该语法的内容均会导致验证错误；软件包名称缺失或重复、版本格式错误、软件包重复列出同一个 peer，以及软件包声明依赖自身的 peer，也都会导致验证错误。错误会指出出错路径（例如 packages[0].peers[1].range is not a supported range: "=>1.0.0"），且不会生成不完整的说明。某个 peer 未出现在依赖树中并不算错误——它会作为 missing 冲突处理。计算过程是纯本地的：不访问网络、不需要配置，也不会读取你传入的输入之外的任何文件。

CLI

npx @reneturcios/peerconflict explain --input args.json
npx @reneturcios/peerconflict --version

args.json 包含完整的参数对象：

{
  "packages": [
    { "name": "react", "version": "17.0.2" },
    {
      "name": "app",
      "version": "1.0.0",
      "peers": [{ "name": "react", "range": "^18.0.0" }]
    }
  ]
}

每个软件包的 peers 默认为 []。说明将以 JSON 格式打印：

{
  "ok": false,
  "conflicts": [
    {
      "from": "app",
      "peer": "react",
      "range": "^18.0.0",
      "installed": "17.0.2",
      "type": "version",
      "detail": "app requires peer react (^18.0.0) but 17.0.2 is installed"
    }
  ],
  "edges": [
    { "from": "app", "to": "react", "range": "^18.0.0", "satisfied": false }
  ],
  "resolutions": [
    {
      "peer": "react",
      "installed": "17.0.2",
      "required_by": [{ "from": "app", "range": "^18.0.0", "lowest": "18.0.0" }],
      "suggestion": "change react from 17.0.2 to a version satisfying every listed range"
    }
  ]
}

退出码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/peerconflict mcp

MCP 客户端配置：

{
  "mcpServers": {
    "peerconflict": {
      "command": "npx",
      "args": ["-y", "@reneturcios/peerconflict", "mcp"]
    }
  }
}

工具

• explain_peer_conflict — 说明已安装依赖树中的 peer 依赖冲突。

  • packages（数组，必填，至少一个）— 软件包对象 {name, version, peers?}；name 在集合中必须唯一，version 是已安装的 MAJOR.MINOR.PATCH 版本，每个 peers 条目都是 {name, range} 要求

  返回 {ok, conflicts, edges, resolutions}。

Docker

docker run -i ghcr.io/cloudcorprecords/peerconflict
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/peerconflict explain --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios