Python依赖固定与冲突检查器

--- name: python-requirements-pin-and-conflict-checker description: 在构建失败前离线检查pip requirements和constraints文件 - 未固定版本和仅下限版本包、跨文件和标记的PEP 440说明符冲突、无提交哈希的git引用、可编辑和本地路径、部分哈希模式、预发布版本、--extra-index-url依赖混淆、http索引、标准库反向移植、运行时文件中的开发工具以及pip freeze漂移。包含一个带有--self-test的标准库Python检查器。 --- # Python Requirements固定与冲突检查器 你帮助Python开发者和DevOps工程师让`pip install -r requirements.txt`变得无趣：每台机器上版本相同，凌晨2点不会出现ResolutionImpossible，没有包悄悄从错误的索引获取。大多数安装失败源于文件中可见的几种模式：constraint文件与requirement矛盾、`requests`没有固定版本、git依赖指向`@main`、一行带`--hash`将整个文件切换为哈希模式、或额外索引让公共包遮蔽内部包。你读取pip会读取的每个文件，使用真正的PEP 440规则检查说明符，并将结果转化为简短的修复列表和锁文件计划。 ## 此技能中的文件 - `scripts/req_check.py` - 以pip的方式解析requirements文件（`-r`包含、`-c`约束、行延续、注释、extras、PEP 508标记、`--hash`、索引选项、VCS/URL/可编辑行），评估PEP 440说明符包括`~=`、通配符和预发布版本，为每个标记环境搜索满足所有说明符的版本，与`pip freeze`输出比较，并报告发现PR01-PR14（仅Python 3.8+标准库，无网络） - `references/specifiers-and-markers.md` - PEP 440运算符、预发布规则、约束与需求、标记评估，以及为什么检查器无法看到传递依赖 - `references/pinning-strategy.md` - 应用与库、requirements.in + 锁工作流、哈希、索引和供应链卫生，以及每个发现代码的含义 - `templates/requirements-review.md` - 要交回的审查 - `examples/requirements.txt` - 一个Django发票服务，包含拼写错误、git分支依赖、额外索引、标记拆分的numpy、重复的Django、enum34和运行时中的pytest - `examples/constraints.txt` - 平台团队的constraints文件，与其中两个requirements矛盾 - `examples/req-report.md` - 这些文件上的真实检查器输出 ## 工作流程 ### 1. 收集输入 询问目标所需的pip读取的每个文件：主requirements文件、通过`-r`或`-c`包含的任何内容，以及来自CI和Dockerfile的`pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL`设置（文件外的索引选项对检查器不可见；需手动添加）。询问项目是**应用**（部署的服务、笔记本镜像、作为容器发布的CLI：预期固定版本）还是**库**（由其他项目安装：预期范围），目标Python版本和平台，以及行为异常环境的`pip freeze`。 ### 2. 运行检查器 ``` python3 scripts/req_check.py examples/requirements.txt python3 scripts/req_check.py requirements.txt --python 3.12 --platform linux python3 scripts/req_check.py requirements.txt requirements-dev.txt --installed freeze.txt python3 scripts/req_check.py requirements.txt --mode lib --json python3 scripts/req_check.py --self-test ``` 退出0 = 无高发现，1 = 有高发现，2 = 文件无法读取。没有`--python`时，每个标记组合作为独立环境检查；有`--python`时，标记不适用的行被丢弃。没有shell时，逐行使用`references/specifiers-and-markers.md`并针对具体版本测试每个包的组合说明符。 ### 3. 读取结果 - 先看安装阻塞项：PR03（没有版本满足组合说明符）、PR07（部分哈希模式）、PR13（pip拒绝的行）。这些在任何安装前就失败。 - 供应链：PR09额外索引、PR10 http或受信任主机、PR05可移动的git引用、PR11虚假或危险包（`sklearn`、`enum34`、`pycrypto`）。 - 可重现性：应用中的PR01未固定和PR02开放范围；在库中，PR02标记会强制用户使用版本的精确固定。 - 漂移：PR12显示运行环境与文件的差异。 - 整理：PR04重复、PR06可编辑/本地路径、PR08预发布版本、PR14运行时文件中的开发工具。 ### 4. 修复并锁定 通过决定哪一方正确来解决每个冲突（通常constraint已过时；检查新版本的变更日志），然后将意图级范围移至`requirements.in`，并使用pip-tools或uv生成固定、哈希的锁文件（`references/pinning-strategy.md`）。在锁文件上重新运行检查器：应无高或中发现。切勿在未询问constraint所有者的情况下通过删除constraint来“修复”冲突。 ### 5. 交付 填写`templates/requirements-review.md`：结论、带精确替换行的阻塞项、供应链更改、锁工作流和CI命令，以及每项更改的所有者。 ## 示例结果 在`examples/requirements.txt`上，检查器发现6个高发现。两个冲突导致pip失败：`urllib3>=2.2`与平台约束`urllib3<2`，以及`numpy>=2.1`与Python 3.9+的约束`numpy==1.26.4`（Python < 3.9分支正常）。`pandas=2.2.3`使用单个`=`被拒绝。`pdf-stamp`从`@main`可编辑安装，内部索引通过`--extra-index-url`添加（`acme-billing-core`存在依赖混淆风险），`enum34`在现代Python上破坏标准库`enum`。中低发现：开放范围的`whitenoise`和`urllib3`、可编辑安装、Django作为`Django`和`django`声明两次、以及运行时文件中的`pytest`。 ## 规则 - 读取pip读取的每个文件，包括约束和包含；单独文件会隐藏冲突。 - 使用PEP 440语义，而非字符串比较（`2.10` > `2.9`，`~=2.1`允许2.9但不允许3.0，`<2.0`排除`2.0rc1`）。 - 明确说明检查器仅看到声明的包：传递冲突和CVE需要解析器（`pip install --dry-run`、`pip-compile`、`uv pip compile`）和`pip-audit`。 - 优先使用工具生成的锁文件而非手动固定；切勿发明版本号 - 从当前环境、锁文件或包变更日志中获取。 - 将索引和VCS发现视为安全问题，而非风格问题。