用途
python-manager 是一个 Python 环境管理技能,用于智慧侦测与管理 Python 专案的虚拟环境与依赖套件。它支援 uv、Poetry 以及 venv/pip 三种工具方案,并包含工具安装导引。
它主要在以下情况被触发:
- 用户询问「如何安装套件?」或「这个专案使用哪个套件管理器?」
- 用户要求新增、移除或更新 Python 依赖
- 需要初始化虚拟环境,或执行 Python 脚本但不确定该用 uv run、poetry run 还是 python
- 专案缺乏明确的环境配置,需要合适的工具建议
主要能力
工作流程分为感知(Perceive)、推理(Reason)、行动(Act)三个阶段。
感知
- 扫描专案根目录的特征文件:uv.lock、poetry.lock、pyproject.toml、requirements.txt
- 检查系统环境中的工具是否已安装:执行 uv --version 或 poetry --version
推理
- 根据特征文件判断专案应使用的工具,优先级为 uv > Poetry > pip
- 检查工具可用性:若判断专案应使用 uv 但未安装,或用户想切换到 uv/Poetry 但环境未就绪,标记为「Pending Installation」
行动
- 工具安装建议:若工具未安装,必须先询问用户:「Detected that the project uses [Tool Name], but it is not installed in your environment. Would you like me to provide the installation command and assist with the installation?」
- 输出命令:针对识别出的管理工具提供正确操作命令
- 执行变更:若用户同意安装或依赖变更,提供 CLI 命令供用户确认
使用方式
技能会依识别结果提供对应工具的命令。
uv(推荐:超快速工具)
- 侦测条件:存在 uv.lock
- 安装(Unix/macOS):curl -LsSf https://astral.sh/uv/install.sh | sh
- 安装(Windows):powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
- 常用命令:
- uv add <package>(新增套件)
- uv sync(同步环境)
- uv run <script.py>(执行脚本)
Poetry
- 侦测条件:存在 poetry.lock,或 pyproject.toml 中有 [tool.poetry]
- 安装(跨平台):curl -sSL https://install.python-poetry.org | python3 -
- 常用命令:
- poetry add <package>(新增套件)
- poetry install(安装依赖)
- poetry run python <script.py>(执行脚本)
venv + pip(传统标准)
- 侦测条件:仅有 requirements.txt 或 .venv
- 常用命令:
- pip install <package>
- pip install -r requirements.txt
适用场景与限制
适用场景包括:不确定专案使用何种套件管理器、需要新增或移除依赖、初始化虚拟环境、执行脚本但不确定使用哪种运行方式,以及专案缺乏明确环境配置需要工具建议。
限制与验证规则:绝不在未询问用户的情况下直接执行安装命令;安装命令必须区分作业系统(macOS/Linux 与 Windows)。交付时需提供环境侦测报告,告知当前环境状态(例如 uv 已安装、侦测到 poetry.lock);若工具缺失,应主动询问安装同意并提供正确语法;并确保提供的命令与专案现有 lock 文件完全一致。