configure-package-management

/configure:package-management

检查并配置现代包管理器，以获得最佳开发体验。

何时使用此技能

适用场景……	应采用其他方式的场景……
使用现代包管理器（uv、bun）搭建新项目	只安装单个依赖项——直接运行 uv add 或 bun add
从旧版包管理器（pip、npm、yarn、poetry）迁移到现代包管理器	项目使用 cargo 或 go mod（已是最佳选择，无需迁移）
审核包管理器配置是否符合最佳实践	配置 lint 或格式化工具——使用 /configure:linting
确保锁定文件、依赖组和 CI/CD 集成配置正确	解决特定依赖冲突——使用 uv pip compile 或 bun install --verbose 进行调试
检测并清理多个包管理器产生的冲突锁定文件	只需安装依赖项——直接运行 uv sync 或 bun install

上下文

• 项目根目录： !pwd
• 包文件： !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \)
• 锁定文件： !find . -maxdepth 1 \( -name 'uv.lock' -o -name 'bun.lockb' -o -name 'package-lock.json' -o -name 'yarn.lock' -o -name 'pnpm-lock.yaml' -o -name 'poetry.lock' -o -name 'Pipfile.lock' \)
• Python 虚拟环境： !find . -maxdepth 1 -type d -name '.venv'
• 旧版文件： !find . -maxdepth 1 \( -name 'requirements.txt' -o -name 'Pipfile' \)
• 项目规范： !find . -maxdepth 1 -name '.project-standards.yaml'

参数

从命令参数中解析：

• --check-only：报告合规状态，不做任何修改（CI/CD 模式）
• --fix：自动应用修复，无需提示
• --manager <uv|bun|npm|cargo>：覆盖检测结果（专注于特定包管理器）

现代包管理器偏好：

• Python：uv（取代 pip、poetry、pipenv、pyenv）——速度提升 10–100 倍
• JavaScript/TypeScript：bun（npm/yarn/pnpm 的替代方案）——速度显著更快
• Rust：cargo（标准方案，无需替代）
• Go：go mod（标准方案，无需替代）

执行

执行此包管理合规性检查：

步骤 1：检测项目语言和当前包管理器

检查语言和包管理器标识：

标识	语言	当前包管理器	推荐
pyproject.toml	Python	uv / poetry / pip	uv
requirements.txt	Python	pip	uv
Pipfile	Python	pipenv	uv
poetry.lock	Python	poetry	uv
uv.lock	Python	uv	uv
package.json + bun.lockb	JavaScript/TypeScript	bun	bun
package.json + package-lock.json	JavaScript/TypeScript	npm	bun
package.json + yarn.lock	JavaScript/TypeScript	yarn	bun
package.json + pnpm-lock.yaml	JavaScript/TypeScript	pnpm	bun
Cargo.toml	Rust	cargo	cargo
go.mod	Go	go mod	go mod

配置前，使用 WebSearch 或 WebFetch 验证最新版本。

步骤 2：分析当前配置状态

针对检测到的每种语言，检查配置：

Python（uv）：

• 已安装 uv 且位于 PATH 中
• 存在包含 [project] 部分的 pyproject.toml
• 存在 uv.lock（锁定文件）
• .venv/ 中存在虚拟环境
• 已在 pyproject.toml 中固定 Python 版本
• 已配置依赖组（dev、test、docs）
• 已指定构建系统（hatchling、setuptools 等）

JavaScript/TypeScript（bun）：

• 已安装 bun 且位于 PATH 中
• 存在 package.json
• 存在 bun.lockb（锁定文件）
• 存在 node_modules/
• 已定义脚本（dev、build、test、lint）
• 已配置类型定义（TypeScript）
• 已配置工作区（如果是 monorepo）

步骤 3：生成合规报告

打印格式化的合规报告：

Package Management Configuration Report
=======================================
Project: [name]
Languages: Python, TypeScript

Python:
  Package manager           uv 0.5.x                   [MODERN | LEGACY pip]
  pyproject.toml            exists                     [EXISTS | MISSING]
  Lock file                 uv.lock                    [EXISTS | OUTDATED | MISSING]
  Virtual environment       .venv/                     [EXISTS | MISSING]
  Python version            3.12                       [PINNED | NOT PINNED]
  Dependency groups         dev, test, docs            [CONFIGURED | MINIMAL]
  Build backend             hatchling                  [CONFIGURED | MISSING]

JavaScript/TypeScript:
  Package manager           bun 1.1.x                  [MODERN | npm | yarn]
  package.json              exists                     [EXISTS | MISSING]
  Lock file                 bun.lockb                  [EXISTS | MISSING]
  Scripts                   dev, build, test, lint     [COMPLETE | INCOMPLETE]
  Type definitions          tsconfig.json              [CONFIGURED | MISSING]
  Engine constraints        package.json engines       [PINNED | NOT PINNED]

Overall: [X issues found]

Recommendations:
  - Migrate from pip to uv for faster installs
  - Add uv.lock to version control
  - Configure dependency groups in pyproject.toml
  - Migrate from npm to bun for better performance

如果指定了 --check-only，则在此处停止。

步骤 4：配置包管理器（如果指定了 --fix 或用户确认）

根据检测到的语言应用配置。使用 REFERENCE.md 中的模板：

使用 uv 管理 Python

1. 安装 uv（通过 mise、curl 或 homebrew）
2. 使用 uv init 初始化项目，或从现有管理器迁移
3. 创建或更新 pyproject.toml，添加项目元数据和依赖组
4. 生成 uv.lock
5. 更新 .gitignore

使用 bun 管理 JavaScript/TypeScript

1. 安装 bun（通过 mise、curl 或 homebrew）
2. 删除旧的锁文件（package-lock.json、yarn.lock、pnpm-lock.yaml）
3. 运行 bun install 以生成 bun.lockb
4. 更新 package.json 中的脚本
5. 更新 .gitignore

步骤 5：处理迁移

如果要从旧版管理器迁移：

从 pip/poetry 迁移到 uv：

1. 安装 uv
2. 运行 uv init
3. 迁移依赖项：运行 uv add -r requirements.txt 或从 poetry 复制
4. 删除旧文件（requirements.txt、Pipfile、poetry.lock）
5. 更新 CI/CD 工作流

从 npm/yarn/pnpm 迁移到 bun：

1. 安装 bun
2. 删除旧的锁文件和 node_modules
3. 运行 bun install
4. 更新脚本，改用 bun 对应的命令
5. 更新 CI/CD 工作流

使用 REFERENCE.md 中的迁移模板。

步骤 6：配置 CI/CD 集成

更新 GitHub Actions 工作流，以使用现代包管理器：

• Python：将 pip install 替换为 astral-sh/setup-uv@v8 + uv sync
• JavaScript：将 actions/setup-node 替换为 oven-sh/setup-bun@v2

使用 REFERENCE.md 中的 CI 工作流模板。

步骤 7：更新标准跟踪

更新 .project-standards.yaml：

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  package_management: "2025.1"
  python_package_manager: "uv"
  javascript_package_manager: "bun"
  lock_files_committed: true

步骤 8：打印最终报告

打印已应用的更改、已执行的迁移以及验证配置的后续步骤摘要。

有关详细的配置模板和迁移指南，请参阅 REFERENCE.md。

Agent 优化

使用场景	命令
快速检查合规性	/configure:package-management --check-only
自动修复所有问题	/configure:package-management --fix
检查 uv 版本	uv --version
检查 bun 版本	bun --version
列出 Python 依赖项	uv pip list --format json
列出 JS 依赖项	bun pm ls --json

标志

标志	描述
--check-only	报告状态，不提供迁移选项
--fix	无需提示，自动应用所有迁移
--manager <manager>	覆盖检测结果（uv、bun、npm、cargo）

示例

# Check compliance and offer migrations
/configure:package-management

# Check only, no modifications
/configure:package-management --check-only

# Auto-migrate Python to uv
/configure:package-management --fix --manager uv

# Auto-migrate JavaScript to bun
/configure:package-management --fix --manager bun

错误处理

• 检测到多个 Python 管理器：警告存在冲突，并建议指定唯一可信来源
• 缺少包管理器：提供通过 mise 安装的选项
• 无效的 pyproject.toml：报告解析错误，并提供模板
• 锁文件冲突：警告存在多个锁文件，并建议清理
• 工作区/monorepo：检测并配置工作区设置

另请参阅

• /configure:linting - 配置 lint 工具（ruff、biome）
• /configure:formatting - 配置格式化工具
• /deps:install - 通用依赖安装器
• /configure:all - 运行所有合规性检查
• uv 文档：https://docs.astral.sh/uv
• bun 文档：https://bun.sh/docs