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中定義的代碼風格。
• 如果需要，更新設置說明。