ai-git-tools 2.0.79 → 2.0.81

package/README.md

@@ -14,6 +14,8 @@
 - **⚙️ 配置檔支援** - 靈活的配置選項，適應不同專案需求
 - **🌐 跨專案通用** - 可在任何 Git 專案中使用
 
+> 📊 想瞭解各命令的完整流程？請參考 [docs/flowchart.md](docs/flowchart.md)。
+
 ## 📦 安裝
 
 ### NPX 使用（推薦）
@@ -49,6 +51,27 @@ npm install --save-dev ai-git-tools
 }
 ```
 
+### 本機直接使用（尚未發布到 npm）
+
+如果你想在套件正式發布到 npm 前，直接從本機原始碼執行：
+
+```bash
+# 方式一：使用 npm link 將本機套件連結到全域
+npm link
+npx ai-git-tools model-info
+
+# 方式二：直接使用 node 執行 bin/cli.js
+node bin/cli.js model-info
+```
+
+其他命令也適用相同方式，例如：
+
+```bash
+npx ai-git-tools init
+npx ai-git-tools commit
+npx ai-git-tools pr
+```
+
 ## 🚀 快速開始
 
 ### 1. 初始化配置
@@ -98,7 +121,7 @@ npx ai-git-tools wf
 
 ## 📖 命令說明
 
-### \`gitai init\`
+### \`ai-git-tools init\`
 
 初始化配置檔案
 
@@ -106,7 +129,7 @@ npx ai-git-tools wf
 npx ai-git-tools init
 \`\`\`
 
-### \`gitai commit\`
+### \`ai-git-tools commit\`
 
 為已 staged 的變更生成並執行 commit
 
@@ -128,7 +151,7 @@ npx ai-git-tools commit --model claude-haiku-4.5
 npx ai-git-tools commit --verbose
 \`\`\`
 
-### \`gitai commit-all\` (別名: \`ca\`)
+### \`ai-git-tools commit-all\` (別名: \`ca\`)
 
 智能分析所有變更並自動分組提交
 
@@ -149,7 +172,7 @@ npx ai-git-tools commit-all
 npx ai-git-tools ca --verbose
 \`\`\`
 
-### \`gitai pr\`
+### \`ai-git-tools pr\`
 
 生成 PR 並發送到 GitHub
 
@@ -175,7 +198,7 @@ npx ai-git-tools pr --preview
 npx ai-git-tools pr --no-confirm
 \`\`\`
 
-### \`gitai workflow\` (別名: \`wf\`)
+### \`ai-git-tools workflow\` (別名: \`wf\`)
 
 完整工作流程：commit-all + pr
 
@@ -197,6 +220,31 @@ npx ai-git-tools workflow
 npx ai-git-tools wf --preview
 \`\`\`
 
+### \`ai-git-tools model-info\`
+
+查詢目前 GitHub Copilot SDK 支援的 AI 模型清單與詳細資訊
+
+\`\`\`bash
+npx ai-git-tools model-info [選項]
+
+選項:
+  --json                       以 JSON 格式輸出完整模型資料
+  --filter <keyword>           依模型名稱、供應商或描述關鍵字過濾
+  --model <model>              查詢單一模型的詳細資訊
+  --no-cache                   忽略快取，強制重新連線 Copilot 取得最新資料
+\`\`\`
+
+**範例：**
+
+\`\`\`bash
+npx ai-git-tools model-info
+npx ai-git-tools model-info --model gpt-4.1
+npx ai-git-tools model-info --filter claude
+npx ai-git-tools model-info --json
+\`\`\`
+
+> 第一次執行會連線到 Copilot CLI 取得模型清單，可能需要數秒鐘；後續預設使用 24 小時快取。
+
 ## ⚙️ 配置
 
 配置檔案範例（\`.ai-git-config.js\`）：
@@ -350,6 +398,49 @@ feat(auth): 新增使用者登入功能
 - 整合 JWT 認證機制
 \`\`\`
 
+## 🚀 發布到 npm
+
+若你是本專案維護者，發布新版本到 npm 的步驟如下：
+
+### 1. 確認已登入 npm
+
+```bash
+npm whoami
+```
+
+若未登入，請執行：
+
+```bash
+npm login
+```
+
+### 2. 確認版本號
+
+修改 [package.json](package.json) 中的 `version` 欄位（例如 `2.0.80`）。
+
+> 每次發布版本號必須遞增，否則 npm 會拒絕。
+
+### 3. 執行發布
+
+```bash
+npm run lint
+npm publish --access public
+```
+
+`prepublishOnly` 會自動執行 `npm run lint`，`prepare` 會自動設定 `bin/cli.js` 為可執行檔。
+
+### 4. 驗證發布
+
+```bash
+npm view ai-git-tools version
+```
+
+### 注意事項
+
+- 發布前請確認工作目錄乾淨（`git status` 無未提交變更）
+- npm 會自動修正 `package.json` 格式問題（例如 `repository.url` 會正規化為 `git+https://...`）
+- 公開套件請使用 `--access public`，私有套件可省略或改為 `--access restricted`
+
 ## 🤔 常見問題
 
 ### Q: 需要安裝 GitHub Copilot 嗎？
@@ -372,18 +463,3 @@ A: 目前遵循 Conventional Commits 規範。未來版本會支援自訂格式
 
 A: 支援。工具會分析整個倉庫的變更。
 
-## 📝 授權
-
-MIT License
-
-## 🤝 貢獻
-
-歡迎提交 Issue 和 Pull Request！
-
-## 📧 聯絡
-
-有問題或建議？歡迎[提交 Issue](https://github.com/yourusername/ai-git-tools/issues)
-
----
-
-Made with ❤️ by AI Git Tools Team

package/bin/cli.js

@@ -2,9 +2,8 @@
 
 /**
  * AI Git Tools CLI
- * 
+ *
  * AI-powered Git automation for commit messages and PR generation
- * 完全重寫版本基於 scripts/ 原始實現
  */
 
 import { Command } from 'commander';
@@ -15,6 +14,9 @@ import { commitCommand } from '../src/commands/commit.js';
 import { commitAllCommand } from '../src/commands/commit-all.js';
 import { prCommand } from '../src/commands/pr.js';
 import { initCommand } from '../src/commands/init.js';
+import { usageCommand } from '../src/commands/usage.js';
+import { modelInfoCommand } from '../src/commands/model-info.js';
+import { registerCommand } from '../src/utils/cli-helpers.js';
 
 // 讀取 package.json 獲取版本號
 const __filename = fileURLToPath(import.meta.url);
@@ -31,70 +33,55 @@ program
   .version(packageJson.version);
 
 // Init 命令
-program
-  .command('init')
-  .description('初始化配置檔案 (.ai-git-config.mjs)')
-  .action(async (options) => {
-    try {
-      await initCommand(options);
-      process.exit(0);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
+registerCommand(program, 'init', '初始化配置檔案 (.ai-git-config.mjs)', [], initCommand);
 
 // Commit 命令
-program
-  .command('commit')
-  .description('AI 自動生成 commit message 並提交')
-  .option('--model <model>', '指定 AI 模型')
-  .option('-v, --verbose', '顯示詳細輸出')
-  .option('--max-diff <number>', '最大 diff 長度')
-  .option('--max-retries <number>', '最大重試次數')
-  .action(async (options) => {
-    try {
-      await commitCommand(options);
-      process.exit(0);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
+registerCommand(program, 'commit', 'AI 自動生成 commit message 並提交', [
+  { flags: '--model <model>', description: '指定 AI 模型' },
+  { flags: '-v, --verbose', description: '顯示詳細輸出' },
+  { flags: '--max-diff <number>', description: '最大 diff 長度' },
+  { flags: '--max-retries <number>', description: '最大重試次數' },
+], commitCommand);
 
 // Commit All 命令
-program
-  .command('commit-all')
-  .description('智慧分析所有變更並自動分組提交')
-  .option('--model <model>', '指定 AI 模型')
-  .option('-v, --verbose', '顯示詳細輸出')
-  .option('--max-diff <number>', '最大 diff 長度')
-  .option('--max-retries <number>', '最大重試次數')
-  .action(async (options) => {
-    try {
-      await commitAllCommand(options);
-      process.exit(0);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
+registerCommand(program, 'commit-all', '智慧分析所有變更並自動分組提交', [
+  { flags: '--model <model>', description: '指定 AI 模型' },
+  { flags: '-v, --verbose', description: '顯示詳細輸出' },
+  { flags: '--max-diff <number>', description: '最大 diff 長度' },
+  { flags: '--max-retries <number>', description: '最大重試次數' },
+], commitAllCommand);
 
 // PR 命令
-program
-  .command('pr')
-  .description('AI 自動生成 PR 並創建 Pull Request')
-  .option('--base <branch>', '指定目標分支')
-  .option('--model <model>', '指定 AI 模型')
-  .option('--preview', '僅預覽 PR 內容，不實際創建')
-  .option('--no-confirm', '跳過確認直接創建')
-  .option('--auto-labels', '自動添加 Labels (預設啟用)')
-  .option('--include-impact', '在 PR 中包含影響範圍分析和注意事項 (預設關閉)')
-  .option('--force-new', '強制創建新 PR，不更新現有 PR')
-  .action(async (options) => {
-    try {
-      await prCommand(options);
-      process.exit(0);
-    } catch (error) {
-      process.exit(1);
-    }
-  });
+registerCommand(program, 'pr', 'AI 自動生成 PR 並創建 Pull Request', [
+  { flags: '--base <branch>', description: '指定目標分支' },
+  { flags: '--model <model>', description: '指定 AI 模型' },
+  { flags: '--preview', description: '僅預覽 PR 內容，不實際創建' },
+  { flags: '--no-confirm', description: '跳過確認直接創建' },
+  { flags: '--auto-labels', description: '自動添加 Labels (預設啟用)' },
+  { flags: '--include-impact', description: '在 PR 中包含影響範圍分析和注意事項 (預設關閉)' },
+  { flags: '--force-new', description: '強制創建新 PR，不更新現有 PR' },
+], prCommand);
+
+// Usage 命令
+registerCommand(program, 'usage', '查看組織 GitHub Copilot 使用狀態與用量', [
+  { flags: '--org <org>', description: '指定組織名稱（預設自動從 git remote 偵測）' },
+  { flags: '--from <date>', description: '開始日期，格式 YYYY-MM-DD（預設：本月第一天）' },
+  { flags: '--to <date>', description: '結束日期，格式 YYYY-MM-DD（預設：今天）' },
+  { flags: '--top <n>', description: '只顯示前 N 名用戶' },
+  { flags: '--sort <by>', description: '排序方式：credits（預設）| amount | name | activity' },
+  { flags: '--team <slug>', description: '只顯示指定團隊的成員' },
+  { flags: '--inactive', description: '同時顯示非活躍用戶' },
+  { flags: '--breakdown', description: '顯示每日使用量明細' },
+  { flags: '--export <file>', description: '匯出為 CSV 檔案（例如 usage.csv）' },
+  { flags: '--json', description: '以 JSON 格式輸出完整資料' },
+], usageCommand);
+
+// Model Info 命令
+registerCommand(program, 'model-info', '查看目前可用的 AI 模型資訊', [
+  { flags: '--json', description: '以 JSON 格式輸出完整模型資料' },
+  { flags: '--filter <keyword>', description: '依模型名稱或描述關鍵字過濾' },
+  { flags: '--model <model>', description: '查詢單一模型的詳細資訊' },
+  { flags: '--no-cache', description: '忽略快取，強制重新連線 Copilot 取得最新模型清單' },
+], modelInfoCommand);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-git-tools",
-  "version": "2.0.79",
+  "version": "2.0.81",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",
@@ -51,7 +51,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/YisoTsao/ai-git-tools.git"
+    "url": "git+https://github.com/YisoTsao/ai-git-tools.git"
   },
   "bugs": {
     "url": "https://github.com/YisoTsao/ai-git-tools/issues"

package/src/ai/prompts/commit-message.js

@@ -0,0 +1,42 @@
+/**
+ * Commit Message Prompt 生成
+ * 集中管理 commit message 的 AI prompt 與後處理
+ */
+
+import { getProjectTypePrompt } from '../../utils/helpers.js';
+
+/**
+ * 生成 commit message prompt
+ * @param {string} diff - git diff 內容
+ * @param {Object} config - 配置物件
+ * @returns {string}
+ */
+export function generateCommitMessagePrompt(diff, config = {}) {
+  const projectPrompt = getProjectTypePrompt();
+
+  return `${projectPrompt}
+
+請根據以下 git diff 產生一則 commit message。
+
+**Commit Message 規則**：
+1. 使用 Conventional Commits 格式：type(scope): subject
+2. type 必須是：feat/fix/docs/style/refactor/test/chore/perf 其中之一
+3. scope: 影響範圍（如 member、report、auth、api、ui、config）
+4. subject 限制在 50 字內，使用繁體中文
+5. 如果變更複雜，加上 body 說明（使用 bullet points）
+
+**重要**：
+- 直接輸出 commit message 純文字，不要使用 markdown 程式碼區塊（\`\`\`）
+- 不要加上任何前綴說明或後綴文字
+- 第一行是標題，如有需要可加上空行後的詳細說明
+
+**範例格式**：
+feat(member): 新增會員管理頁面
+
+- 實作會員列表查詢功能
+- 新增會員資料編輯表單
+- 整合 Zustand 狀態管理
+
+git diff:
+${diff}`;
+}

package/src/ai/prompts/pr-content.js

@@ -0,0 +1,151 @@
+/**
+ * PR Content Prompt 生成
+ * 集中管理 PR 標題、描述與影響分析的 AI prompt
+ */
+
+import { CONSTANTS } from '../../utils/constants.js';
+import { getSkillsSummaryForPrompt, PROJECT_SKILLS_CONTEXT } from '../../utils/project-skills.js';
+
+/**
+ * 生成 PR 內容 prompt
+ * @param {string} commits - commit 訊息
+ * @param {string} diff - 程式碼變更 diff
+ * @returns {string}
+ */
+export function generatePRContentPrompt(commits, diff) {
+  return `你是一個專業的前端工程師，熟悉 Next.js、React 效能優化和團隊開發規範。
+請根據以下 commit 訊息和程式碼變更，直接輸出一個清晰的 Pull Request 標題和描述。
+
+**重要原則**：
+- 只根據實際的 commit 訊息和 diff 內容描述變更，不要臆測或誇大
+- 如果 commit 中沒有提到「新增指令 / 新增 API / 新增組件」，請不要用這些詞
+- 文件（如 .github/copilot-instructions.md、prompt 檔案、README）應描述為「新增/更新文件」而非「新增指令」
+- 如果 OpenSpec prompt 被刪除並改為 OpsX prompt，請描述為「以 OpsX 取代 OpenSpec」，不要說「新增 OpenSpec prompt」
+- package.json 若只有版本號變更，請描述為「更新版本號」，不要說「更新相依」
+- 重構相關的改動請優先使用 refactor 類型
+
+**輸出格式**（不要加任何引導語，直接輸出以下內容）：
+
+# [type]: [PR 標題]
+
+> type 必須是以下之一：feat / fix / refactor / style / docs / test / chore / perf
+> **重要**：如果有新增任何功能、新增檔案、新增 API、新增組件，優先使用 **feat**
+
+## 📝 變更摘要
+[簡述這個 PR 的主要目的和影響範圍，2-3 句話]
+
+## 🎯 主要變更
+- [變更項目 1]
+- [變更項目 2]
+- [變更項目 3]
+
+## 🔀 變更類型
+- [ ] ✨ 新功能 (feat)
+- [ ] 🐛 Bug 修復 (fix)
+- [ ] ♻️ 重構 (refactor)
+- [ ] 💄 樣式調整 (style)
+- [ ] 📝 文件更新 (docs)
+- [ ] ⚡ 效能改進 (perf)
+- [ ] 🔧 其他 (chore)
+
+> 根據 diff 和 commit 自動勾選（可複選），[ ] 改為 [x]；有新增檔案或功能必勾 ✨ feat
+
+## 🧪 測試方法
+1. [具體的測試步驟 1]
+2. [具體的測試步驟 2]
+3. [具體的測試步驟 3]
+
+## 💥 Breaking Changes
+[如果有破壞性變更請詳細說明，沒有則填寫「無」]
+
+## 📌 注意事項
+[需要特別注意的事項]
+
+## 📸 截圖
+[如果是 UI 變更，提醒需要截圖]
+
+---
+
+## ⚠️ 風險與注意事項
+**Risk Level**: \`LOW\` / \`MEDIUM\` / \`HIGH\`
+
+[說明潛在風險、破壞性變更（breaking changes）、需要特別小心的地方；沒有則填「無」]
+
+## 👀 Reviewer 重點
+- [請 reviewer 特別關注的邏輯或設計決策 1]
+- [請 reviewer 特別關注的邏輯或設計決策 2]
+
+---
+
+**規則**：
+- 直接輸出 # [type]: [標題]，繁體中文（台灣正體）
+- type 必須符合 Conventional Commits；以 commit 內容為準，新增檔案/功能優先 feat，重構優先 refactor
+- 變更類型只勾選實際出現的類型，沒有 fix 類 commit 就不要勾 Bug 修復
+- Risk Level：HIGH=核心流程，MEDIUM=影響現有功能，LOW=新增或純重構
+- Reviewer 重點列 1-3 個值得仔細看的地方
+- 描述必須和 commit 訊息一致，禁止虛構功能或誇大影響範圍
+
+---
+
+**Commit 訊息**：
+${commits}
+
+**程式碼變更**：
+${diff}`;
+}
+
+/**
+ * 生成影響分析 prompt
+ * @param {string[]} changedFiles - 變更檔案列表
+ * @param {string} diff - 程式碼變更 diff
+ * @param {string} commits - commit 訊息
+ * @returns {string}
+ */
+export function generateImpactAnalysisPrompt(changedFiles, diff, commits) {
+  const skillsSummary = getSkillsSummaryForPrompt(PROJECT_SKILLS_CONTEXT);
+
+  return `你是一個資深的程式碼審查專家，精通 React/Next.js 效能優化與前端架構設計。
+請分析以下程式碼變更，提供專業的影響範圍分析與規範合規檢查。
+
+${skillsSummary}
+
+**變更檔案列表**：
+${changedFiles.slice(0, CONSTANTS.MAX_FILES_IN_PROMPT).join('\n')}
+${
+  changedFiles.length > CONSTANTS.MAX_FILES_IN_PROMPT
+    ? `... 還有 ${changedFiles.length - CONSTANTS.MAX_FILES_IN_PROMPT} 個檔案`
+    : ''
+}
+
+**Commit 訊息**：
+${commits.split('\n').slice(0, CONSTANTS.MAX_COMMITS_IN_PROMPT).join('\n')}
+
+**程式碼變更內容**：
+\`\`\`diff
+${diff.substring(0, CONSTANTS.MAX_DIFF_LENGTH)}
+${diff.length > CONSTANTS.MAX_DIFF_LENGTH ? '\n... (內容過長已截斷)' : ''}
+\`\`\`
+
+---
+
+請以 JSON 格式輸出分析結果（不要加任何其他文字，只輸出 JSON）：
+
+\`\`\`json
+{
+  "blastRadius": {
+    "modules": ["影響的模組1", "影響的模組2"],
+    "impacts": ["影響層面1", "影響層面2"],
+    "riskLevel": "低|中|高",
+    "riskReasons": ["風險原因1", "風險原因2"],
+    "externalBehaviors": ["對外行為變更說明"]
+  },
+  "warnings": [
+    {
+      "level": "⚠️|ℹ️",
+      "message": "問題描述",
+      "suggestion": "改善建議"
+    }
+  ]
+}
+\`\`\``;
+}