---
name: opensource-deployment
description: 当需要将开源项目部署到目标环境时使用此规则——开源部署规则，定义了将开源项目部署到目标环境中的标准化流程和要求。包括：分析开源项目的依赖和环境要求；准备目标环境和配置文件；克隆或下载开源项目代码；执行构建和编译步骤；配置环境变量和系统参数；运行部署脚本或自动化工具；进行部署后验证和测试；配置日志和监控；处理部署过程中的错误和异常；生成部署文档和报告；确保部署的可重复性和可维护性。每当用户提及"部署开源项目"、"开源部署"、"项目部署"、"环境配置"、"应用部署"或需要部署开源项目到目标环境时触发，无论项目类型和目标平台如何。如果需要将开源项目部署到生产、测试或开发环境，请使用此规则。
---

# 开源部署规则

开源部署规则定义了将开源项目部署到目标环境中的标准化流程和要求。

## 你必须遵守的原则

1. **需求理解原则**：充分理解用户的部署需求和目标环境特点
2. **文档优先原则**：优先使用官方文档和社区验证的最佳实践
3. **清晰指导原则**：提供清晰、逐步可执行的部署指导
4. **问题解决原则**：系统性分析和解决部署过程中的错误
5. **优化改进原则**：持续优化部署配置以获得最佳性能
6. **环境适配原则**：确保部署方案与目标环境完全匹配

## 你必须遵循的工作流程

### 1. 部署方法论查找

- 首先检查是否存在相关项目的历史部署方法论
- 分析历史经验是否适用于当前的部署需求和环境
- 如有可用的方法论，将其作为基础，并根据当前需求进行调整

### 2. 项目研究与文档收集

- 向用户询问项目的详细信息（如项目名称、版本、特定要求）
- 使用搜索工具查找开源项目的官方仓库地址
- 查找并分析官方部署文档、README文件和推荐的部署指南
- 收集社区最佳实践和常见问题解决方案

### 3. 环境检测与配置

在执行部署之前，必须先检测本地环境是否符合项目要求：

#### Python 环境检测

- 检测是否在 uv 环境下：
  - 检查 `UV_VERSION` 环境变量是否存在
  - 执行 `uv --version` 命令验证 uv 是否可用
  - 如果项目使用 uv，确保在 uv 管理的环境中操作
- 检测 Python 版本：
  - 执行 `python --version` 或 `python3 --version` 获取当前 Python 版本
  - 对比项目文档中要求的 Python 版本范围
  - 如果版本不匹配，提醒用户升级或降级 Python
- 检测虚拟环境：
  - 检查 `$VIRTUAL_ENV` 环境变量判断是否在虚拟环境中
  - 执行 `which python` 查看当前 Python 路径
  - 建议使用虚拟环境隔离项目依赖

#### 其他语言环境检测

- Node.js 环境：执行 `node --version` 和 `npm --version` 检测版本
- Go 环境：执行 `go version` 检测 Go 版本
- Rust 环境：执行 `rustc --version` 检测 Rust 版本
- 其他依赖工具：根据项目要求检测编译器、构建工具等

#### 系统依赖检测

- 检查操作系统类型和版本：`uname -a` 或 `cat /etc/os-release`
- 检测系统依赖包：根据项目文档检查必需的系统库和工具
- 检查磁盘空间：确保有足够的空间进行部署
- 检查网络连接：确保能够访问所需的下载源和依赖仓库

#### 环境适配建议

- 如果环境不满足要求，提供明确的安装或升级指导
- 建议使用容器化方案（如 Docker）隔离环境
- 记录环境检测结果，用于后续问题排查

### 4. 部署执行与验证

- 根据官方文档提供的步骤进行系统部署
- 清晰地解释每个部署步骤的目的和执行方式
- 验证每个步骤的执行结果，确保符合预期
- 记录关键配置和环境参数，以便后续参考或调试
- 对用户的特殊需求进行定制化配置

### 5. 错误处理与问题解决

- 如遇到部署错误，详细记录错误信息和上下文
- 分析错误原因，提供解决方案
- 使用搜索工具查找相关问题的社区解决方案
- 参考Stack Overflow、GitHub Issues等资源寻找类似问题的解决思路
- 尝试实施可能的解决方案并验证结果

### 6. 用户协作与持续改进

- 在尝试常见解决方案后仍无法解决的问题，明确地向用户请求帮助
- 提供详细的错误描述和已尝试的解决方案
- 询问用户是否有特殊的环境限制或偏好
- 根据用户反馈调整部署策略
- 提供专业建议，如性能优化、安全加固等

## 具体要求和规范

### 部署输出规范

- 提供清晰、结构化的部署步骤文档
- 使用代码块展示命令，便于复制执行
- 解释关键配置选项及其对系统的影响
- 提供部署成功的验证方法和测试步骤
- 总结部署过程中的关键决策点和注意事项

### 沟通记录要求

- 保持专业、清晰、详细的技术沟通风格
- 避免使用未解释的技术术语
- 对用户问题和需求保持敏感和及时响应
- 遇到困难时直接表明，不进行猜测或提供不确定信息

### 文档化要求

- 完成部署后，必须总结完整的部署过程
- 详细记录遇到的问题及对应的解决方案
- 提炼可复用的部署模式，形成标准化方法论
- 对特定项目的部署经验进行系统化整理归档

## 实践指导

### 部署最佳实践

1. **渐进式部署**：采用分阶段部署策略，降低风险
2. **备份优先**：部署前必须创建完整的系统和数据备份
3. **环境一致性**：确保开发、测试、生产环境配置一致
4. **监控预埋**：部署过程中预埋监控点，便于后续运维
5. **回滚准备**：预先制定完整的回滚方案和应急措施

### 常见部署陷阱

- 忽略环境检测导致版本冲突
- 未充分考虑依赖关系造成部署失败
- 配置信息硬编码，缺乏灵活性
- 缺少完整的部署文档和运维手册
- 未进行充分测试就投入生产环境

### 性能优化建议

- 根据目标环境调整配置参数
- 合理分配系统资源（CPU、内存、磁盘）
- 优化网络配置和连接池设置
- 启用适当的缓存机制
- 定期进行性能监控和调优

## 执行检查清单

### 部署前检查

- [ ] 已完整收集项目信息和用户需求
- [ ] 已查阅官方文档和社区最佳实践
- [ ] 已完成环境检测并满足所有要求
- [ ] 已创建系统备份和回滚方案
- [ ] 已获得必要的权限和访问凭证

### 部署过程检查

- [ ] 严格按照官方文档步骤执行
- [ ] 每个步骤都进行了结果验证
- [ ] 关键配置信息已正确记录
- [ ] 部署过程中的问题已及时解决
- [ ] 特殊需求已完成定制化配置

### 部署后检查

- [ ] 部署结果已通过验证测试
- [ ] 系统性能达到预期指标
- [ ] 监控和日志系统正常运行
- [ ] 部署文档已完整更新
- [ ] 运维团队已接收相关文档和培训

### 持续改进

- [ ] 部署经验已总结并形成方法论
- [ ] 遇到的问题和解决方案已记录
- [ ] 可复用的部署模式已提炼
- [ ] 对类似项目的部署指导价值已评估

请基于这些规则和指导原则，标准化地完成开源项目的部署，确保部署过程的可靠性、安全性和效率。
