# python环境管理rules加skills **Repository Path**: bj110101/python-env-rules-skills ## Basic Information - **Project Name**: python环境管理rules加skills - **Description**: 核心原则: Homebrew Python(系统)+ uv(应用级 venv)+ conda(仅 ML/底层库) 默认背景: 创建 Cursor 全局 Rules(简洁原则)+ Skills(完整能力)实现 Python 环境管理。 即,将 Python 环境管理规范固化到 Cursor 全局规则中,可以确保所有项目都遵循一致的最佳实践。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-14 - **Last Updated**: 2026-04-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Python 环境管理 Rules + Skills > **项目版本**: v1.0.0 > **创建日期**: 2026-04-14 > **适用场景**: Cursor IDE 中的 Python 开发环境自动化管理 --- ## 📋 项目概述 本项目是一套**Python 环境管理规则与技能系统**,专为 Cursor IDE 设计,用于: - ✅ **自动检测** Python 环境问题(虚拟环境、依赖冲突、PEP 668 保护等) - ✅ **智能应用** 项目规则(基于文件位置自动激活对应规范) - ✅ **快速修复** 常见环境错误(ModuleNotFoundError、依赖缺失、版本冲突) - ✅ **标准化** 测试策略(单元测试、集成测试、E2E 测试模板) --- ## 🎯 核心特性 ### 1. 规则自动检测机制 Cursor 会根据当前编辑的文件路径,**自动激活**对应的 `.cursor/rules/` 规则文件: | 文件路径模式 | 激活规则 | 规范内容 | |---|---|---| | `src/agents/` | `02-agent-system.mdc` | Agent 设计规范 | | `src/workflows/` | `03-workflow-system.mdc` | Workflow 架构规则 | | `src/services/` | `04-service-layer.mdc` | 服务层设计原则 | | `config/` 或 `settings.py` | `05-configuration.mdc` | 配置管理规范 | | `tests/` 或 `test_*.py` | `06-testing-strategy.mdc` | 测试策略指南 | | `docs/` 或 `.md` 文件 | `07-documentation.mdc` | 文档编写标准 | | **Python 文件(全局)** | **`08-python-env.mdc`** | **Python 环境管理(核心)** | ### 2. Python 环境专项规则 **规则文件**: `~/.cursor/rules/08-python-env.mdc`(用户级全局规则) 该规则会自动检测以下问题: | 检测项 | 检测方式 | 违规处理 | |---|---|---| | 虚拟环境未激活 | `sys.prefix` 检查 | 提示 `source .venv/bin/activate` | | 多 Python 环境冲突 | `which python` + `pip show` | 建议统一使用 `uv` | | PEP 668 保护绕过 | 检测 `--break-system-packages` | 禁止使用,建议虚拟环境 | | 依赖缺失 | 模块导入测试 | 提供 `uv pip install` 命令 | | 依赖文件缺失 | `pyproject.toml` 存在性检查 | 提示创建配置文件 | ### 3. 三层测试体系 项目提供完整的测试策略,覆盖: #### 单元测试(Unit Tests) 验证环境配置类、工具函数的正确性。 ```python # 示例:配置类测试 class TestSettings: def test_default_values(self): settings = Settings() assert settings.default_backend == BackendType.PIPELINE assert settings.enable_formula is True def test_env_override(self): with patch.dict(os.environ, {"MINERU_DEVICE_MODE": "cuda"}): settings = Settings() assert settings.mineru_device_mode == "cuda" ``` #### 集成测试(Integration Tests) 验证模块间协作和解释器一致性,确保使用当前虚拟环境的 Python。 ```python # 关键:使用 sys.executable 而非硬编码 "python" result = subprocess.run( [sys.executable, "-m", "src.cli.client", "--help"], capture_output=True, text=True ) assert result.returncode in [0, 2] ``` #### 端到端测试(E2E Tests) 验证完整工作流在隔离环境中的执行。 ### 4. 技能触发机制 当检测到特定问题时,Cursor 会**自动读取技能库**并应用对应技能: ``` 问题模式识别 → 技能匹配 → 读取 SKILL.md → 执行修复步骤 ``` **现有可用技能**(位于 `~/.cursor/skills-cursor/`): | 技能名称 | 用途 | 触发场景 | |---|---|---| | `create-rule` | 创建 Cursor 规则文件 | 用户请��添��项目规范 | | `update-cursor-settings` | 修改 Cursor/VSCode 设置 | 修改编辑器配置 | | `python-env-fixer` | Python 环境自动修复 | 检测到环境问题(建议添加) | --- ## 📁 项目结构 ``` python环境管理_Rules-Skills/ ├── python环境管理rules+skills.plan.md # 核心规划文档 ├── PYTHON_ENV_TESTING_GUIDE.md # 环境问题处理机制详解 └── README.md # 本文件 ``` --- ## 🚀 快速开始 ### 环境要求 - **Python**: >= 3.11(推荐 3.11 或 3.13) - **包管理器**: `uv`(推荐)或 `pip` - **IDE**: Cursor(最新版本) ### 安装步骤 1. **克隆项目** ```bash git clone https://gitee.com/bj110101/python-env-rules-skills.git cd python环境管理_Rules-Skills ``` 2. **创建虚拟环境** ```bash uv venv --python 3.11 .venv source .venv/bin/activate # Windows: .venv\Scripts\activate ``` 3. **验证环境** ```bash python -c "import sys; print(sys.prefix)" # 输出应包含 ".venv" ``` 4. **查看规则文件** ```bash # 用户级全局规则(已安装) cat ~/.cursor/rules/08-python-env.mdc # 项目级规则(需自行创建) mkdir -p .cursor/rules # 将相关规则复制到项目中 ``` --- ## 🔧 使用指南 ### 日常开发流程 ```bash # 1. 激活虚拟环境 source .venv/bin/activate # 2. 安装/更新依赖 uv pip install -e ".[dev]" # 从 pyproject.toml 安装 # 或 uv pip install package-name # 单独安装 # 3. 运行测试 pytest tests/ # 4. 环境验证 python scripts/check_environment.py # 或 ./scripts/setup.sh --verify ``` ### 遇到环境问题时 当出现 `ModuleNotFoundError` 或其他导入错误时,Cursor 会自动: 1. **检测错误类型** → 识别是依赖缺失还是环境问题 2. **检查当前环境** → 运行 `python -c "import sys; print(sys.prefix)"` 3. **匹配规则** → 读取 `08-python-env.mdc` 中的规范 4. **应用技能** → 触发 `python-env-fixer`(如存在)或提供修复建议 5. **显示建议** → 在编辑器中显示快速修复选项 **示例诊断输出**: ``` 检测到导入错误:ModuleNotFoundError: No module named 'pypdfium2' 环境诊断: 1. 当前解释器:/usr/local/bin/python (Homebrew Python) 2. 依赖位置:/path/to/project/.venv/lib/python3.11/site-packages 3. 问题原因:脚本使用系统 Python,但依赖安装在 .venv 中 解决方案: 方案A(推荐): $ source .venv/bin/activate $ uv pip install pypdfium2 方案B: $ .venv/bin/python script.py ``` --- ## 📚 文档说明 ### 核心文档 | 文档 | 描述 | 适合读者 | |---|---|---| | [`python环境管理rules+skills.plan.md`](python环境管理rules+skills.plan.md) | 规则与技能系统的整体规划、架构设计、实施细节 | 项目维护者、架构师 | | [`PYTHON_ENV_TESTING_GUIDE.md`](PYTHON_ENV_TESTING_GUIDE.md) | Python 环境问题自动检测、测试策略、技能触发机制的完整指南 | 开发者、测试工程师 | ### 推荐阅读顺序 1. **初学者**:先读本文档(README.md)了解项目概览 2. **开发者**:阅读 `PYTHON_ENV_TESTING_GUIDE.md` 掌握环境问题处理流程 3. **维护者**:深入学习 `python环境管理rules+skills.plan.md` 理解系统架构 --- ## 🛠️ 常见问题 ### Q1: 如何创建项目级规则文件? **A**: 在项目根目录创建 `.cursor/rules/` 目录,然后复制或创建所需的规则文件: ```bash mkdir -p .cursor/rules # 从用户级规则复制需要的规则 cp ~/.cursor/rules/0*-*.mdc .cursor/rules/ # 或使用 create-rule 技能创建新规则 # 在 Cursor 中说:"为项目创建 Python 代码风格规则" ``` ### Q2: 如何验证规则是否生效? **A**: 故意违反一条规则(如使用 `print()` 调试),观察 Cursor 是否显示波浪线和快速修复建议。 详细方法见 `PYTHON_ENV_TESTING_GUIDE.md` §6.1。 ### Q3: 如何添加新的技能? **A**: 在 `~/.cursor/skills-cursor/` 下创建新目录,编写 `SKILL.md` 文件。详细步骤见 `PYTHON_ENV_TESTING_GUIDE.md` §8.2。 ### Q4: 如何禁用某条规则? **A**: 删除或重命名对应的 `.mdc` 文件即可。规则系统会按文件名顺序加载,缺失的文件不会生效。 --- ## 🤝 贡献指南 欢迎提交 Issue 和 Pull Request! ### 贡献方式 1. **报告问题**:提交环境问题案例,帮助完善规则库 2. **分享技能**:创建新的技能模板,帮助其他开发者 3. **改进文档**:修正错误、补充使用示例 4. **代码优化**:改进测试脚本、工具函数 ### 提交规范 ``` feat: 添加新功能 fix: 修复问题 docs: 文档更新 rule: 添加/修改规则 skill: 添加/修改技能 test: 测试相关 ``` --- ## 📄 许可证 本项目采用 **MIT License**,详见 [LICENSE](LICENSE) 文件。 --- ## 🔗 参考资源 ### 官方文档 - [Cursor 规则系统文档](https://docs.cursor.com/context/rules) - [UV 官方文档](https://github.com/astral-sh/uv) - [PEP 668 - Python 环境保护](https://peps.python.org/pep-0668/) ### 相关项目 - [Claude-code-Rules](https://github.com/your-org/Claude-code-Rules) - 规则体系参考 - [ai-scanreader-trans](https://gitee.com/your-org/ai-scanreader-trans) - 实际应用案例 - [ai-polyengine-trans](https://gitee.com/your-org/ai-polyengine-trans) - 工作流编排案例 --- ## 📮 联系方式 - **维护团队**: AI-Preliminary-Research 项目组 - **问题反馈**: [Gitee Issues](https://gitee.com/bj110101/python-env-rules-skills/issues) - **最后更新**: 2026-04-14 --- **⭐ 如果这个项目对你有帮助,请给个 Star!**