Jessica

🚀 开发工具

本项目的此目录收纳了各类开发与生产力工具，旨在助力开发者与产品经理高效完成常见任务，同时确保代码库的一致性。

🚀 快速开始

此开发工具集为开发者和产品经理提供了丰富的功能，下面将为你介绍如何快速上手。

环境变量设置

1. 创建本地环境文件：

cd .dev-tools/scripts
cp .env.example .env

2. 按需调整.env中的变量：

• GIT_DIFF_BRANCH：要比较的分支（默认为origin/dev用于PR）。
• 注意：大多数PR应针对dev分支，仅在热修复或发布PR时使用origin/main。

Python依赖安装

1. 若尚未安装Poetry，可执行以下命令进行安装：

curl -sSL https://install.python-poetry.org | python3 -

2. 安装依赖项：

cd .dev-tools/scripts
poetry install

3. 激活虚拟环境：

poetry shell

✨ 主要特性

提示模板

prompts/目录下的模板可辅助AI完成各类任务：

• prompt_pr.md：用于生成详细的PR描述。
• prompt_commit.md：帮助创建有意义的提交信息。
• prompt_user_story.md：能够创建结构良好的用户故事，并作为GitHub问题呈现。

实用脚本

scripts/目录包含多个实用脚本：

• generate_git_diffs.py：可在分支之间生成git差异，并收集提交信息。
• check_env_files.py：对所有服务的环境文件进行验证，涵盖检查缺失文件、确保必需变量设置、检测示例/占位符值、验证.gitignore模式等，还会提供清晰的进度指示器和总结报告。

📦 安装指南

环境变量

1. 创建本地环境文件：

cd .dev-tools/scripts
cp .env.example .env

2. 按需调整.env中的变量：

• GIT_DIFF_BRANCH：要比较的分支（默认为origin/dev用于PR）。
• 注意：大多数PR应针对dev分支，仅在热修复或发布PR时使用origin/main。

Python依赖

1. 安装Poetry：

curl -sSL https://install.python-poetry.org | python3 -

2. 安装依赖项：

cd .dev-tools/scripts
poetry install

3. 激活虚拟环境：

poetry shell

💻 使用示例

基础用法

工作流程：使用AI创建用户故事

1. 在Cursor的Composer中：

• 参考或拖放prompt_user_story.md。
• 描述要实现的目标。
• AI将分析输入和代码库，生成全面的用户故事。
• 查看并确认生成的故事。
• AI将协助创建具有适当项目分配的GitHub问题。

2. 生成的用户故事包含：

• 从产品经理角度的业务需求。
• 从开发者角度的技术需求。
• 明确的问题描述和目标。

工作流程：生成git差异

1. 运行脚本生成差异：

cd .dev-tools/scripts
poetry run python generate_git_diffs.py

2. 脚本将：

• 选择要比较的两个分支或提交。
• 显示详细的文件级差异。
• 提供可复制粘贴的git命令。

工作流程：检查环境文件

1. 运行环境检查器：

cd .dev-tools/scripts
poetry run python check_env_files.py

2. 脚本将：

• 扫描项目以查找服务目录。
• 加载并尊重.gitignore模式。
• 检查每个服务的环境配置。
• 提供详细报告，显示：
  • ✅ 配置正确的环境文件。
  • ❌ 缺少的环境文件。
  • ⚠️ 使用示例值的变量。
  • ⚠️ 不在示例文件中的额外变量。

3. 修复报告中指出的问题：

• 根据.env.example模板创建缺失的.env文件。
• 填充所需的变量。
• 替换示例/占位符值为实际值。
• 审查额外变量以确保它们是必需的。

📚 详细文档

目录结构

.dev-tools/
├── prompts/           # AI提示模板，用于各种任务
│   ├── prompt_pr.md   # 生成PR描述的模板
│   ├── prompt_commit.md # 创建有意义提交信息的模板
│   └── prompt_user_story.md # 创建结构良好的用户故事作为GitHub问题
│
└── scripts/          # 开发实用脚本
    ├── generate_git_diffs.py  # 用于生成git差异的Python脚本
    ├── check_env_files.py  # 验证所有服务的环境文件
    ├── pyproject.toml       # Poetry项目配置
    ├── .env.example        # 环境变量示例
    └── .env               # 您的本地环境变量（被git忽略）

🔧 技术细节

本项目中的工具旨在帮助开发者和产品经理完成常见任务并保持代码库的一致性。通过使用AI提示模板和实用脚本，能够提高工作效率，减少手动操作的错误。例如，check_env_files.py脚本通过检查环境文件的完整性和正确性，确保项目在不同环境下的稳定运行。

📄 许可证

文档中未提及许可证相关信息。

🔧 贡献指南

添加新工具时，请遵循以下步骤：

1. 根据工具类型创建适当的子目录。
2. 提供清晰的文档。
3. 更新此README中的工具描述。
4. 对于Python脚本：

• 将依赖项添加到pyproject.toml中，使用Poetry。
• 遵循pyproject.toml中定义的代码风格。
• 如果需要，更新设置说明。