🚀 开发工具

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

🚀 快速开始

环境变量

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：生成详细拉取请求描述的模板
• 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 文件
   • 填充必需变量
   • 替换示例/占位符值为实际值
   • 审查额外变量以确保其必要性

📚 详细文档

目录结构

.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 定义的代码风格
   • 如果需要更新设置说明