开发工具

此目录包含项目中使用的各种开发和生产力工具。这些工具旨在帮助开发者和产品经理完成常见任务，并保持代码库的一致性。

目录结构

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

工具概述

提示

prompts/目录包含AI辅助任务的模板：

• prompt_pr.md：生成详细拉取请求描述的模板
• prompt_commit.md：创建有意义提交消息的模板
• prompt_user_story.md：创建良好结构用户故事作为GitHub问题的模板

脚本

scripts/目录包含实用脚本：

• generate_git_diffs.py：生成git差异并收集提交消息
• check_env_files.py：验证所有服务中的环境文件
  • 检查是否缺少.env.example模板的.env文件
  • 确保所有必需变量已设置
  • 检测需要替换的示例/占位符值
  • 验证是否符合.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. 生成的用户故事将包括：

   • 从产品经理角度的业务需求
   • 从开发者角度的技术需求
   • 用户故事卡片的基本信息
   • 可选的历史记录部分
   • 可选的验收标准

工作流：检查环境文件

1. 运行环境检查器：

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

2. 脚本将执行以下操作：

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

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

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

贡献

添加新工具时：

1. 根据工具类型创建适当的子目录
2. 包括清晰的文档
3. 更新此README中的新工具描述
4. 对于Python脚本：
   • 将依赖项添加到pyproject.toml中，使用Poetry
   • 遵循pyproject.toml定义的代码风格
   • 如果需要更新设置说明