ln-713-pip-upgrader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ln-713-pip-upgrader

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader

Upgrades Python dependencies with automatic breaking change detection.

类型： L3 Worker 分类： 7XX 项目引导 父级： ln-710-dependency-upgrader

自动检测破坏性变更并升级Python依赖项。

Overview

概述

Aspect	Details
Input	Project path, package manager type
Output	Updated requirements.txt/pyproject.toml
Supports	pip, poetry, pipenv

方面	详情
输入	项目路径、包管理器类型
输出	更新后的requirements.txt/pyproject.toml
支持的工具	pip, poetry, pipenv

Workflow

工作流

See diagram.html for visual workflow.

Phases: Pre-flight → Detect Manager → Security Audit → Check Outdated → Apply Upgrades → Verify Installation → Report

查看diagram.html获取可视化工作流。

阶段： 预检 → 检测包管理器 → 安全审计 → 检查过时依赖 → 应用升级 → 验证安装 → 报告

Phase 0: Pre-flight Checks

阶段0：预检检查

Check	Required	Action if Missing
requirements.txt OR pyproject.toml OR Pipfile	Yes	Block upgrade
Virtual environment active	No	Warn user (risk of system pollution)

Workers assume coordinator (ln-710) already verified git state and created backup.

检查项	是否必需	缺失时的操作
requirements.txt 或 pyproject.toml 或 Pipfile	是	阻止升级
虚拟环境已激活	否	警告用户（存在系统污染风险）

Worker 假设协调器（ln-710）已验证Git状态并创建备份。

Phase 1: Detect Manager

阶段1：检测包管理器

Manager	Indicator Files
pip	requirements.txt
poetry	pyproject.toml + poetry.lock
pipenv	Pipfile + Pipfile.lock

包管理器	标识文件
pip	requirements.txt
poetry	pyproject.toml + poetry.lock
pipenv	Pipfile + Pipfile.lock

Phase 2: Security Audit

阶段2：安全审计

Commands

命令

Manager	Command
pip	`pip-audit --json`
poetry	`poetry audit` (via plugin)
pipenv	`pipenv check`

包管理器	命令
pip	`pip-audit --json`
poetry	`poetry audit` （通过插件）
pipenv	`pipenv check`

Actions

操作

Severity	Action
Critical	Block upgrade, report
High	Warn, continue
Moderate/Low	Log only

严重程度	操作
严重（Critical）	阻止升级，生成报告
高（High）	发出警告，继续执行
中/低（Moderate/Low）	仅记录日志

Phase 3: Check Outdated

阶段3：检查过时依赖

Commands

命令

Manager	Command
pip	`pip list --outdated --format=json`
poetry	`poetry show --outdated`
pipenv	`pipenv update --outdated`

包管理器	命令
pip	`pip list --outdated --format=json`
poetry	`poetry show --outdated`
pipenv	`pipenv update --outdated`

Phase 4: Apply Upgrades

阶段4：应用升级

Commands

命令

Manager	Command
pip	`pip install --upgrade <package>`
pip (freeze)	`pip freeze > requirements.txt`
poetry	`poetry update`
pipenv	`pipenv update`

包管理器	命令
pip	`pip install --upgrade <package>`
pip（冻结版本）	`pip freeze > requirements.txt`
poetry	`poetry update`
pipenv	`pipenv update`

MCP Tools for Migration Search

用于迁移搜索的MCP工具

Priority Order (Fallback Strategy)

优先级顺序（回退策略）

Priority	Tool	When to Use
1	mcp__context7__query-docs	First choice for library docs
2	mcp__Ref__ref_search_documentation	Official docs and PyPI
3	WebSearch	Latest info, community solutions

优先级	工具	使用场景
1	mcp__context7__query-docs	库文档的首选工具
2	mcp__Ref__ref_search_documentation	官方文档和PyPI
3	WebSearch	最新信息、社区解决方案

Context7 Usage

Context7 使用方法

Step	Tool	Parameters
1. Find library	mcp__context7__resolve-library-id	libraryName: "pydantic"
2. Query docs	mcp__context7__query-docs	query: "pydantic v1 to v2 migration breaking changes"

步骤	工具	参数
1. 查找库	mcp__context7__resolve-library-id	libraryName: "pydantic"
2. 查询文档	mcp__context7__query-docs	query: "pydantic v1 to v2 migration breaking changes"

MCP Ref Usage

MCP Ref 使用方法

Action	Tool	Query Example
Search	mcp__Ref__ref_search_documentation	"python pydantic 2 migration guide"
Read	mcp__Ref__ref_read_url	URL from search results

操作	工具	查询示例
搜索	mcp__Ref__ref_search_documentation	"python pydantic 2 migration guide"
读取	mcp__Ref__ref_read_url	搜索结果中的URL

WebSearch Fallback

WebSearch 回退方案

Use when Context7/Ref return no results:

"<package> python <version> breaking changes migration"

```
"<ImportError message> <package> fix"
```

当Context7/Ref未返回结果时使用：

"<package> python <version> breaking changes migration"

```
"<ImportError message> <package> fix"
```

Phase 5: Verify Installation

阶段5：验证安装

Commands

命令

Check	Command
Import test	`python -c "import <package>"`
Tests	`pytest` or `python -m pytest`

检查项	命令
导入测试	`python -c "import <package>"`
测试	`pytest` 或 `python -m pytest`

Phase 6: Report Results

阶段6：报告结果

Report Schema

报告 Schema

Field	Description
project	Project path
packageManager	pip, poetry, or pipenv
duration	Total time
upgrades[]	Applied upgrades
verification	PASSED or FAILED

字段	描述
project	项目路径
packageManager	pip, poetry, 或 pipenv
duration	总耗时
upgrades[]	已应用的升级
verification	通过（PASSED）或失败（FAILED）

Common Breaking Changes

常见破坏性变更

See breaking_changes_patterns.md for full patterns.

Package	Breaking Version	Key Changes
pydantic	1 → 2	V1 compatibility layer needed
sqlalchemy	1 → 2	Query syntax changes
fastapi	0.99 → 0.100+	Pydantic v2 required

详见breaking_changes_patterns.md获取完整模式。

包	破坏性版本	主要变更
pydantic	1 → 2	需要V1兼容层
sqlalchemy	1 → 2	查询语法变更
fastapi	0.99 → 0.100+	依赖Pydantic v2

Configuration

配置

yaml

Options:
  # Upgrade scope
  upgradeType: major          # major | minor | patch

  # Security
  auditLevel: high
  minimumReleaseAge: 14

  # Python specific
  pythonVersion: "3.12"
  useVirtualenv: true

  # Verification
  runTests: true

yaml

Options:
  # 升级范围
  upgradeType: major          # major | minor | patch

  # 安全设置
  auditLevel: high
  minimumReleaseAge: 14

  # Python相关配置
  pythonVersion: "3.12"
  useVirtualenv: true

  # 验证设置
  runTests: true

Error Handling

错误处理

Error	Cause	Solution
ImportError	Breaking API change	Search Context7/Ref for migration
Dependency conflict	Version mismatch	Try pip-compile or poetry lock

错误	原因	解决方案
ImportError	API破坏性变更	搜索Context7/Ref获取迁移方案
依赖冲突	版本不匹配	尝试使用pip-compile或poetry lock

References

参考资料

breaking_changes_patterns.md
python_venv_handling.md

Version: 1.1.0 Last Updated: 2026-01-10

breaking_changes_patterns.md
python_venv_handling.md

版本： 1.1.0 最后更新： 2026-01-10