ln-823-pip-upgrader

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-823-pip-upgrader

类型： L3 Worker 类别： 8XX 优化

升级 Python 依赖，并自动检测重大变更。

---

概述

方面	详情
输入	项目路径和包管理器类型
输出	更新后的依赖清单，以及机器可读的依赖升级摘要
支持	pip、poetry、pipenv

---

工作流

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

---

阶段 0：预检

检查项	必需	缺失时的操作
requirements.txt、pyproject.toml 或 Pipfile	是	阻止升级
Python 包管理器可用	是	阻止升级
虚拟环境已激活	否	如果无法确定环境是否受管理，则警告用户
工作区基线安全	是	受管理的运行中，协调器已完成准备；独立运行中，在本地保护回滚能力

运行时协调

受管理的运行会从 ln-820 接收确定性的 runId 和确切的 summaryArtifactPath。 仍支持独立运行；如果省略运行时参数，则在返回前生成一个作用域限定于该独立运行的工件。

---

阶段 1：检测包管理器

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

---

阶段 2：安全审计

包管理器	命令
pip	pip-audit --json
poetry	poetry audit
pipenv	pipenv check

操作：

严重程度	操作
严重	阻止并报告
高	警告并继续
中/低	仅记录

---

阶段 3：检查过期依赖

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

---

阶段 4：应用升级

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

---

用于迁移搜索的 MCP 工具

优先级	工具	使用时机
1	mcp__context7__query-docs	查询库文档的首选工具
2	mcp__Ref__ref_search_documentation	官方文档和 PyPI
3	WebSearch	最新信息和社区修复方案

当包升级跨越主版本，或导致导入错误时，务必使用 MCP 工具。

---

阶段 5：验证安装

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

常见的重大变更示例：

必须阅读： 加载 breaking_changes_patterns.md 以了解共享模式。

包	发生重大变更的版本	主要变更
pydantic	1 -> 2	需要兼容层
sqlalchemy	1 -> 2	查询 API 变更
fastapi	0.99 -> 0.100+	与 Pydantic v2 对齐

---

阶段 6：报告结果

字段	描述
project	项目路径
packageManager	pip、poetry 或 pipenv
duration	总耗时
upgrades[]	已应用的升级
verification	导入/测试判定结果
warnings[]	不阻止流程的问题
artifact_path	持久化的 Worker 报告路径（如已写入）

---

配置

Options:
  upgradeType: major          # major | minor | patch
  auditLevel: high
  minimumReleaseAge: 14
  pythonVersion: "3.12"
  useVirtualenv: true
  runTests: true

---

错误处理

错误	原因	解决方案
ImportError	API 重大变更	搜索当前迁移文档
依赖冲突	版本不匹配	重新生成锁文件，或回滚导致问题的包

---

参考资料

• breaking_changes_patterns.md
• python_venv_handling.md

---

运行时摘要产物

**必须阅读：**加载 references/coordinator_summary_contract.md

生成 dependency-worker 摘要信封。

托管模式：

• ln-820 传递确定性的 runId 和准确的 summaryArtifactPath
• 将摘要写入所提供的 summaryArtifactPath

独立模式：

• 省略 runId 和 summaryArtifactPath
• 将摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/dependency-worker/ln-823--{identifier}.json

**监控（2.1.98+）：**对于预计耗时超过 30 秒的安装、审计或测试命令，请使用 Monitor。备用方案：Bash(run_in_background=true)。

完成定义

• 根据项目指标检测包管理器
• 完成所选 Python 管理器的安全审计
• 找出过期的软件包
• 结合模式和当前文档检查破坏性变更
• 应用升级，并持久化更新后的清单和锁文件
• 导入冒烟测试和必需的测试均成功
• 将 dependency-worker 摘要产物写入托管或独立模式的路径

---

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