ln-823-pip-upgrader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）均相对于技能仓库根目录。如果在当前工作目录（CWD）中未找到，请定位到本SKILL.md所在目录，再向上一级即为仓库根目录。

ln-823-pip-upgrader

Type: L3 Worker Category: 8XX Optimization Parent: ln-820-dependency-optimization-coordinator

Upgrades Python dependencies with automatic breaking change detection.

类型： L3 Worker 分类： 8XX 优化类 父级： ln-820-dependency-optimization-coordinator

自动检测破坏性变更并升级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

工作流程

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

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

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)
Git clean state	Yes	Block (need clean baseline for revert)

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

检查项	是否必填	缺失时的操作
requirements.txt 或 pyproject.toml 或 Pipfile	是	阻止升级
虚拟环境已激活	否	向用户发出警告（存在污染系统环境的风险）
Git处于干净状态	是	阻止升级（需要干净的基线以便回滚）

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

Worktree & Branch Isolation

工作树与分支隔离

MANDATORY READ: Load

shared/references/git_worktree_fallback.md

— use ln-823 row.

必读： 加载

shared/references/git_worktree_fallback.md

—— 使用ln-823对应的条目。

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提示信息 <package> 修复方案"

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

常见破坏性变更

MANDATORY READ: Load 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

breaking_changes_patterns.md
python_venv_handling.md

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

Definition of Done

—

Package manager detected (pip/poetry/pipenv) from indicator files
Security audit completed (pip-audit/poetry audit/pipenv check)
Outdated packages identified and listed
Upgrades applied with requirements.txt/pyproject.toml updated
Breaking changes handled via MCP migration guides
Import tests and pytest pass after upgrades
Report returned with upgrades applied and verification status

Version: 1.1.0 Last Updated: 2026-01-10

—