用途
coding 模型学习各库 API 的时间停留在其训练截止点,而项目的锁文件(lockfile)持续更新。since-cutoff 用于回答两类问题:你(模型)是否了解本项目依赖的版本;自你的训练数据以来,这些依赖发生了什么变化。它也适合在依赖升级后、基于升级后的库写代码之前使用,或当代码反复因某个被重命名、移动、移除的函数、类或参数而失败时排查原因。仅适用于 Python 项目。
主要能力
- 对每个锁定依赖,取模型截止日期当天或之前的最新发布版本,与项目锁定版本做公开 API 对比。对比为静态分析(griffe),不运行包代码。
- 报告项目中代码实际使用到的已变更 API,并列出使用这些 API 的文件。
- 在用户同意后,将简短说明写入 AGENTS.md(或项目使用的 CLAUDE.md),每条带证据标记(例如 [diff])。
- scan、status 不修改项目文件,仅写入自身被 git 忽略的 .since-cutoff/ 目录与本地缓存;scan 不做模型调用、无需 API 密钥。
- 可选 run 子命令用于测量模型实际在哪些变更上出错;它会向用户选定的模型提供商发送提示(包名、版本、公开 API 签名与生成的任务,不含项目源码),消耗用户额度,因此需先征得同意。
使用方式
在项目根目录(含 pyproject.toml、requirements*.txt 或 uv.lock、poetry.lock、pdm.lock、pylock.toml、Pipfile.lock 等锁文件的目录)操作。
先用 since-cutoff --version 检查运行器;若缺失或未报告 0.4.1,需先征得用户同意再运行 uvx since-cutoff@0.4.1(首次会从 PyPI 下载该版本)。不要安装其他内容或改动用户环境。
执行只读扫描并指明所用模型:
uvx since-cutoff@0.4.1 scan --model <provider>:<model>
例如 anthropic:claude-sonnet-4-5 或 openai:gpt-5.4。省略 --model 时,它会从编码代理设置中读取模型并打印来源。扫描会读取项目文件、PyPI 与 models.dev,不向任何地方发送项目代码。
向用户汇总结果:模型及其截止时间、哪些依赖发生变化、代码用到了哪些已变更 API 及所在文件。
仅在用户要求时写入说明:先运行 uvx since-cutoff@0.4.1 sync --dry-run 并展示差异,用户同意后再运行 uvx since-cutoff@0.4.1 sync --yes。它会在 AGENTS.md(或项目使用的 CLAUDE.md)中写入一个标记块,文件其余内容保持不变;后续升级后再运行可让该块与锁文件保持同步。退出码 4 表示该块被手工编辑过,应告知用户,仅在用户确认后使用 --force。uvx since-cutoff@0.4.1 unapply 可移除该块。
将这些说明视为项目锁定版本的参考事实,在编写使用这些库的代码时加以核对。
适用场景
- 判断模型是否了解项目当前锁定的依赖版本。
- 依赖升级后、写新代码前快速了解 API 差异。
- 排查因 API 重命名、迁移或移除导致的运行失败。
- 为编码代理生成与锁定版本同步的简短项目说明。
限制
- 仅支持 Python 项目。
- 只比较公开 API 的形态:名称、签名、参数与弃用标记;签名不变而行为变化的情况无法发现。
- 训练截止时间只决定查看哪些变更,不反映模型实际记住了什么;run 才测量后者。
- 需要访问 PyPI 与 models.dev 的网络连接;首次扫描会下载用于比较的发布版本,结果缓存在本地。
- 截止时间元数据与静态 API 差异属于假设,需对照准确的锁定版本核实,不能证明模型知识或服务接受度。使用前应审阅固定运行器/依赖下载行为;对下载包数据的静态分析与安装/运行时执行不同。
安全与隐私
scan 与 status 不修改项目文件,只写入自身被 git 忽略的 .since-cutoff/ 文件夹与本地缓存。sync 仅在用户同意后向 AGENTS.md 或 CLAUDE.md 写入一个标记块。不执行任何包代码,也不执行模型生成的代码。只有可选的 run 需要凭据。