ai-git-tools 2.0.78 → 2.0.80

package/src/pr-modules/ai/code-analyzer.js

@@ -1,6 +1,11 @@
 import { CopilotClient, approveAll } from '@github/copilot-sdk';
-import { CONSTANTS, PROJECT_SKILLS_CONTEXT } from '../utils/constants.js';
-import { getSkillsSummaryForPrompt, log } from '../utils/helpers.js';
+import { CONSTANTS } from '../../utils/constants.js';
+import { log } from '../../utils/logger.js';
+import { isCopilotAuthError } from '../../utils/helpers.js';
+import {
+  generatePRContentPrompt,
+  generateImpactAnalysisPrompt,
+} from '../../ai/prompts/pr-content.js';
 
 // 讓 CopilotClient 啟動的 Node 子程序繼承此設定，靜音 SQLite ExperimentalWarning
 process.env.NODE_NO_WARNINGS = '1';
@@ -65,7 +70,7 @@ export class AIAnalyzer {
    * 生成 PR 內容（失敗時自動重建 client 重試一次）
    */
   async generatePRContent(commits, diff) {
-    const prompt = this.buildPRPrompt(commits, diff);
+    const prompt = generatePRContentPrompt(commits, diff);
 
     for (let attempt = 1; attempt <= 2; attempt++) {
       try {
@@ -106,6 +111,16 @@ export class AIAnalyzer {
           log.info(`  建議改用更快的模型：ai-git-tools pr --model gpt-5.4\n`);
           throw new Error(`AI 生成超時：模型 ${this.model} 回應過慢，請加 --model gpt-5.4 重試`);
         }
+
+        // 檢測 Copilot 授權錯誤
+        if (isCopilotAuthError(error)) {
+          log.error('看起來是 GitHub Copilot 授權問題');
+          log.error('  1. 確認你的 GitHub 帳號已訂閱 GitHub Copilot');
+          log.error('  2. 驗證 VS Code 中使用的 GitHub 帳號是否有 Copilot 存取權限');
+          log.error('  3. 嘗試重新登入: gh auth logout && gh auth login');
+          throw error;
+        }
+
         throw error;
       }
     }
@@ -118,8 +133,7 @@ export class AIAnalyzer {
    * 分析程式碼影響範圍
    */
   async analyzeImpact(changedFiles, diff, commits) {
-    const skillsSummary = getSkillsSummaryForPrompt(PROJECT_SKILLS_CONTEXT);
-    const prompt = this.buildAnalysisPrompt(changedFiles, diff, commits, skillsSummary);
+    const prompt = generateImpactAnalysisPrompt(changedFiles, diff, commits);
 
     const session = await this._createSession();
 
@@ -168,143 +182,7 @@ export class AIAnalyzer {
     // 注意：不在此 stop() client，改由 close() 統一清理以便複用
   }
 
-  /**
-   * 建立 PR 生成 Prompt
-   */
-  buildPRPrompt(commits, diff) {
-    return `你是一個專業的前端工程師，熟悉 Next.js、React 效能優化和團隊開發規範。
-請根據以下 commit 訊息和程式碼變更，直接輸出一個清晰的 Pull Request 標題和描述。
-
-**輸出格式**（不要加任何引導語，直接輸出以下內容）：
-
-# [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；新增檔案/功能優先 feat，可複選多種類型；Risk Level：HIGH=核心流程，MEDIUM=影響現有功能，LOW=新增或重構；Reviewer 重點列 1-3 個值得仔細看的地方。
-
----
-
-**Commit 訊息**：
-${commits}
-
-**程式碼變更**：
-${diff}`;
-  }
-
-  /**
-   * 建立影響分析 Prompt
-   */
-  buildAnalysisPrompt(changedFiles, diff, commits, skillsSummary) {
-    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": "改善建議"
-    }
-  ]
-}
-\`\`\`
-
-**分析重點**：
-
-1. **影響範圍 (blastRadius)**：
-   - 真實分析程式碼變更內容，不要只看檔案路徑
-   - 識別實際影響的模組
-   - 分析影響層面（API、資料庫、UI、商業邏輯、效能、安全性等）
-   - 評估風險等級，並說明原因
-   - 識別對外行為變更
-
-2. **規範警告 (warnings)**：
-   - 檢查是否有安全風險
-   - 檢查是否缺少錯誤處理
-   - 檢查是否有效能問題
-   - 檢查是否違反最佳實踐
-
-**回應格式**：只輸出有效的 JSON，不要有任何前綴或後綴文字。`;
-  }
 
   /**
    * 解析 AI 生成的 PR 內容

package/src/pr-modules/ai/label-analyzer.js

@@ -1,5 +1,5 @@
 import { execSync } from 'child_process';
-import { log } from '../utils/helpers.js';
+import { log } from '../../utils/logger.js';
 
 /**
  * Label 分析器 - 自動為 PR 添加合適的標籤

package/src/pr-modules/core/github-api.js

@@ -1,7 +1,7 @@
 import { execSync } from 'child_process';
 import { writeFileSync, unlinkSync, existsSync } from 'fs';
-import { log } from '../utils/helpers.js';
-import { colors } from '../utils/constants.js';
+import { log } from '../../utils/logger.js';
+import { colors } from '../../utils/constants.js';
 
 /**
  * GitHub API 操作封裝
@@ -63,10 +63,46 @@ export class GitHubAPI {
    */
   checkAuth() {
     try {
-      execSync('gh api user --jq .login', { stdio: 'pipe' });
-      return { authenticated: true };
+      const login = execSync('gh api user --jq .login', {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      }).trim();
+      return { authenticated: true, login };
     } catch (error) {
-      return { authenticated: false };
+      return { authenticated: false, login: null };
+    }
+  }
+
+  /**
+   * 檢查目前認證使用者對此倉庫的權限
+   * @returns {{permission: string|null, canCreatePR: boolean, owner: string|null, repo: string|null}}
+   */
+  checkRepositoryPermission() {
+    try {
+      const remoteUrl = execSync('git remote get-url origin', {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+
+      // 解析 owner/repo，支援 HTTPS 與 SSH
+      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+      if (!match) {
+        return { permission: null, canCreatePR: false, owner: null, repo: null };
+      }
+
+      const [, owner, repo] = match;
+      const viewerJson = execSync(
+        `gh repo view ${owner}/${repo} --json viewerPermission`,
+        { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      const { viewerPermission } = JSON.parse(viewerJson);
+
+      // ADMIN / MAINTAIN / WRITE 通常可以建立 PR；READ / TRIAGE 不行
+      const canCreatePR = ['ADMIN', 'MAINTAIN', 'WRITE'].includes(viewerPermission);
+
+      return { permission: viewerPermission, canCreatePR, owner, repo };
+    } catch (error) {
+      return { permission: null, canCreatePR: false, owner: null, repo: null };
     }
   }
 
@@ -271,6 +307,21 @@ export class GitHubAPI {
           return prUrl;
         } catch (error) {
           this.safeUnlink(bodyFile);
+
+          // 偵測常見權限錯誤並給出清楚提示
+          const stderr = error.stderr?.toString?.() || error.message || '';
+          if (stderr.includes('must be a collaborator')) {
+            const auth = this.checkAuth();
+            const perm = this.checkRepositoryPermission();
+            throw new Error(
+              `建立 PR 失敗：帳號 ${auth.login || '目前使用者'} 不是 ${perm.owner}/${perm.repo} 的協作者（權限：${perm.permission}）。\n` +
+              '解決方式：\n' +
+              `  1. 請 ${perm.owner} 到 Settings > Collaborators 將你加入（需要 Write 權限）\n` +
+              '  2. 或執行 gh auth login 切換到有權限的帳號\n' +
+              '  3. 若是從 fork 開發，請推送分支到自己的 fork 後再建立 PR'
+            );
+          }
+
           throw error;
         }
       }

package/src/pr-modules/core/workflow.js

@@ -1,13 +1,13 @@
 import { createInterface } from 'readline';
 import { execSync } from 'child_process';
-import { GitOperations } from './git-operations.js';
+import { GitOperations } from '../../core/git-operations.js';
 import { GitHubAPI } from './github-api.js';
 import { AIAnalyzer } from '../ai/code-analyzer.js';
 import { LabelAnalyzer } from '../ai/label-analyzer.js';
 import { ReviewerSelector } from '../reviewers/reviewer-selector.js';
-import { Logger } from '../ui/logger.js';
-import { PRError, log } from '../utils/helpers.js';
-import { CONSTANTS, colors } from '../utils/constants.js';
+import { Logger, log } from '../../utils/logger.js';
+import { PRError } from '../../utils/helpers.js';
+import { CONSTANTS, colors } from '../../utils/constants.js';
 
 /**
  * PR 工作流程編排
@@ -15,7 +15,7 @@ import { CONSTANTS, colors } from '../utils/constants.js';
 export class PRWorkflow {
   constructor(config) {
     this.config = config;
-    this.git = new GitOperations();
+    this.git = GitOperations;
     this.github = new GitHubAPI(); // 自動從 git remote 偵測組織名稱
     this.ai = new AIAnalyzer({ model: config.ai.model });
     this.labelAnalyzer = new LabelAnalyzer();
@@ -40,6 +40,26 @@ export class PRWorkflow {
           log.error('GitHub CLI 未登入，請先執行: gh auth login');
           throw new Error('GitHub CLI 未登入');
         }
+
+        // 0.1 確認對當前倉庫有建立 PR 的權限
+        const perm = this.github.checkRepositoryPermission();
+        if (!perm.canCreatePR) {
+          log.error(`目前帳號 ${auth.login} 對 ${perm.owner}/${perm.repo} 的權限為「${perm.permission}」，無法建立 Pull Request`);
+          log.info('解決方案：');
+          console.log(`  1. 請倉庫擁有者將 ${auth.login} 加入 Collaborator（需要 Write 以上權限）`);
+          console.log('  2. 或切換到有權限的帳號：gh auth login');
+          console.log('  3. 如果是 fork 的倉庫，請推送分支到自己的 fork 後再建立 PR');
+          console.log('');
+          throw new PRError(
+            `權限不足：${auth.login} 無法在 ${perm.owner}/${perm.repo} 建立 PR`,
+            'INSUFFICIENT_PERMISSION',
+            [
+              `請 ${perm.owner} 將 ${auth.login} 加入 Collaborator`,
+              '執行 gh auth login 切換到有權限的帳號',
+              '若是 fork，請推送到自己的 fork 再建立 PR',
+            ]
+          );
+        }
       }
 
       // 0.5 提前預熱 AI client（異步非阻塞），讓 subprocess 在 git 操作期間並行啟動

package/src/pr-modules/reviewers/reviewer-selector.js

@@ -1,6 +1,6 @@
 import { execSync } from 'child_process';
-import { CONSTANTS, colors } from '../utils/constants.js';
-import { log } from '../utils/helpers.js';
+import { CONSTANTS, colors } from '../../utils/constants.js';
+import { log } from '../../utils/logger.js';
 import { InteractiveSelect } from '../ui/interactive-select.js';
 
 /**

package/src/pr-modules/ui/interactive-select.js

@@ -1,5 +1,5 @@
 import { emitKeypressEvents } from 'readline';
-import { colors, cursor } from '../utils/constants.js';
+import { colors, cursor } from '../../utils/constants.js';
 
 /**
  * 互動式選擇工具（使用方向鍵和空白鍵）

package/src/utils/cli-helpers.js

@@ -0,0 +1,51 @@
+/**
+ * CLI 命令註冊輔助函式
+ * 統一處理命令註冊、錯誤處理與 process exit
+ */
+
+import { handleError } from './helpers.js';
+
+/**
+ * 註冊一個 CLI 命令，統一包裝 try/catch 與退出碼
+ * @param {import('commander').Command} program
+ * @param {string} name
+ * @param {string} description
+ * @param {Array<{flags: string, description: string, defaultValue?: any}>} options
+ * @param {Function} action
+ */
+export function registerCommand(program, name, description, options = [], action) {
+  const command = program.command(name).description(description);
+
+  for (const option of options) {
+    if (option.defaultValue !== undefined) {
+      command.option(option.flags, option.description, option.defaultValue);
+    } else {
+      command.option(option.flags, option.description);
+    }
+  }
+
+  command.action(async (options) => {
+    try {
+      await action(options);
+      process.exit(0);
+    } catch (error) {
+      handleError(error);
+      process.exit(1);
+    }
+  });
+}
+
+/**
+ * 簡化版的命令 action 包裝器（用於已自行設定 option 的場景）
+ */
+export function wrapAction(action) {
+  return async (options) => {
+    try {
+      await action(options);
+      process.exit(0);
+    } catch (error) {
+      handleError(error);
+      process.exit(1);
+    }
+  };
+}

package/src/utils/constants.js

@@ -0,0 +1,49 @@
+/**
+ * 常數定義
+ * 統一供所有命令與核心模組使用
+ */
+
+export const CONSTANTS = {
+  // API 與緩衝區限制
+  MAX_DIFF_LENGTH: 8000,
+  MAX_BUFFER_SIZE: 10 * 1024 * 1024,
+
+  // 顯示限制
+  MAX_COMMIT_PREVIEW: 5,
+  MAX_FILES_IN_PROMPT: 50,
+  MAX_COMMITS_IN_PROMPT: 10,
+  DIFF_CONTEXT_LINES: 50,
+
+  // Reviewer 相關
+  MAX_SUGGESTED_REVIEWERS: 5,
+  AUTO_REVIEWERS_COUNT: 2,
+  GIT_HISTORY_COMMITS: 20,
+
+  // GitHub API 延遲
+  GITHUB_API_DELAY: 500,
+  GITHUB_SYNC_DELAY: 2000,
+  GITHUB_TEAM_SYNC_DELAY: 1000,
+};
+
+// 顏色輸出
+export const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+// ANSI 游標控制
+export const cursor = {
+  hide: '\x1B[?25l',
+  show: '\x1B[?25h',
+  up: (n = 1) => `\x1B[${n}A`,
+  down: (n = 1) => `\x1B[${n}B`,
+  clearLine: '\x1B[2K\r',
+  saveCursor: '\x1B[s',
+  restoreCursor: '\x1B[u',
+};

package/src/utils/helpers.js

@@ -1,8 +1,23 @@
 /**
  * Helper 工具函式
- * 基於 scripts/ai-pr-modules/utils/helpers.mjs
+ * 統一供所有命令使用
  */
 
+import { colors } from './constants.js';
+
+/**
+ * 自訂錯誤類別（PR 流程使用）
+ */
+export class PRError extends Error {
+  constructor(message, code, suggestions = [], diagnosticCommand = null) {
+    super(message);
+    this.name = 'PRError';
+    this.code = code;
+    this.suggestions = suggestions;
+    this.diagnosticCommand = diagnosticCommand;
+  }
+}
+
 /**
  * 清理 commit message
  * 移除 markdown 程式碼區塊標記
@@ -43,19 +58,75 @@ export function validateCommitMessage(message) {
   return { valid: true };
 }
 
+/**
+ * 檢測 Copilot 授權錯誤（code-analyzer 使用別名）
+ */
+export const isCopilotAuthError = isCopilotSubscriptionError;
+
+/**
+ * 檢測 Copilot 授權錯誤
+ */
+export function isCopilotSubscriptionError(error) {
+  if (!error) return false;
+
+  const message = (error.message || error.toString() || '').toLowerCase();
+  const originalError = (error.originalError?.message || '').toLowerCase();
+
+  return (
+    error.isCopilotAuth === true ||
+    message.includes('permission') ||
+    message.includes('unauthorized') ||
+    message.includes('forbidden') ||
+    message.includes('not authorized') ||
+    originalError.includes('permission') ||
+    originalError.includes('unauthorized')
+  );
+}
+
 /**
  * 錯誤處理
  */
 export function handleError(error) {
+  // 先檢查是否為 Copilot 授權相關的錯誤
+  if (isCopilotSubscriptionError(error)) {
+    console.log('\n🔐 看起來是 GitHub Copilot 授權問題\n');
+    console.log('解決方案:');
+    console.log('  1. 確認你的 GitHub 帳號已訂閱 GitHub Copilot');
+    console.log('  2. 驗證 VS Code 中使用的 GitHub 帳號是否有 Copilot 訪問權限');
+    console.log('  3. 嘗試重新登入:');
+    console.log('     gh auth logout');
+    console.log('     gh auth login');
+    console.log('  4. 若是公司帳號，確保使用公司的 GitHub 帳號登入');
+    console.log('');
+    return;
+  }
+
+  if (error instanceof PRError) {
+    console.error(`\n❌ 錯誤: ${error.message}`);
+
+    if (error.suggestions && error.suggestions.length > 0) {
+      console.log(`\n${colors.cyan}💡 建議解決方案:${colors.reset}`);
+      error.suggestions.forEach((suggestion, index) => {
+        console.log(`  ${index + 1}. ${suggestion}`);
+      });
+    }
+
+    if (error.diagnosticCommand) {
+      console.log(`\n${colors.yellow}🔍 診斷命令:${colors.reset}`);
+      console.log(`  ${error.diagnosticCommand}`);
+    }
+    return;
+  }
+
   console.error('\n❌ 錯誤:', error.message);
-  
+
   if (error.suggestions && error.suggestions.length > 0) {
     console.log('\n💡 建議解決方案:');
     error.suggestions.forEach((suggestion, index) => {
       console.log(`  ${index + 1}. ${suggestion}`);
     });
   }
-  
+
   if (error.stack && process.env.VERBOSE) {
     console.error('\n堆疊追蹤:');
     console.error(error.stack);

package/src/utils/logger.js

@@ -1,18 +1,9 @@
 /**
  * Logger 工具
- * 基於 scripts/ai-pr-modules/ui/logger.mjs
+ * 統一供所有命令使用
  */
 
-const colors = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  red: '\x1b[31m',
-  cyan: '\x1b[36m',
-  magenta: '\x1b[35m',
-};
+import { colors } from './constants.js';
 
 export class Logger {
   info(msg) {
@@ -49,3 +40,14 @@ export class Logger {
     console.log('═'.repeat(60));
   }
 }
+
+/**
+ * 簡易日誌輔助物件（用於不需要實例化的場景）
+ */
+export const log = {
+  info: (msg) => console.log(`${colors.blue}ℹ${colors.reset} ${msg}`),
+  success: (msg) => console.log(`${colors.green}✅${colors.reset} ${msg}`),
+  warning: (msg) => console.log(`${colors.yellow}⚠️${colors.reset} ${msg}`),
+  error: (msg) => console.log(`${colors.red}❌${colors.reset} ${msg}`),
+  step: (msg) => console.log(`${colors.cyan}▶${colors.reset} ${msg}`),
+};

package/src/{pr-modules/utils/constants.js → utils/project-skills.js}

@@ -1,53 +1,8 @@
 /**
- * 常數定義
+ * 專案規範知識（供 AI prompt 使用）
+ * 集中管理 skills 相關的 prompt 內容
  */
 
-export const CONSTANTS = {
-  // API 與緩衝區限制
-  MAX_DIFF_LENGTH: 8000,
-  MAX_BUFFER_SIZE: 10 * 1024 * 1024,
-
-  // 顯示限制
-  MAX_COMMIT_PREVIEW: 5,
-  MAX_FILES_IN_PROMPT: 50,
-  MAX_COMMITS_IN_PROMPT: 10,
-  DIFF_CONTEXT_LINES: 50,
-
-  // Reviewer 相關
-  MAX_SUGGESTED_REVIEWERS: 5,
-  AUTO_REVIEWERS_COUNT: 2,
-  GIT_HISTORY_COMMITS: 20,
-
-  // GitHub API 延遲
-  GITHUB_API_DELAY: 500,
-  GITHUB_SYNC_DELAY: 2000,
-  GITHUB_TEAM_SYNC_DELAY: 1000,
-};
-
-// 顏色輸出
-export const colors = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  red: '\x1b[31m',
-  cyan: '\x1b[36m',
-  magenta: '\x1b[35m',
-};
-
-// ANSI 游標控制
-export const cursor = {
-  hide: '\x1B[?25l',
-  show: '\x1B[?25h',
-  up: (n = 1) => `\x1B[${n}A`,
-  down: (n = 1) => `\x1B[${n}B`,
-  clearLine: '\x1B[2K\r',
-  saveCursor: '\x1B[s',
-  restoreCursor: '\x1B[u',
-};
-
-// 專案規範知識（來自 .github/skills/）
 export const PROJECT_SKILLS_CONTEXT = {
   techStack: {
     framework: 'Next.js 12+ (Pages Router)',
@@ -57,7 +12,6 @@ export const PROJECT_SKILLS_CONTEXT = {
     serverState: 'SWR',
     forms: 'React Hook Form + Zod',
   },
-  // 來自 .github/skills/react-best-practices/SKILL.md
   reactBestPractices: [
     { id: 'async-parallel', category: '消除 Waterfall', desc: '使用 Promise.all() 處理獨立操作' },
     { id: 'async-suspense-boundaries', category: '消除 Waterfall', desc: '使用 Suspense 串流內容' },
@@ -93,7 +47,6 @@ export const PROJECT_SKILLS_CONTEXT = {
     { id: 'js-early-exit', category: 'JS 效能', desc: '提早返回函式' },
     { id: 'js-set-map-lookups', category: 'JS 效能', desc: '使用 Set/Map 做 O(1) 查找' },
   ],
-  // 來自 .github/skills/frontend-guidelines/SKILL.md
   frontendGuidelines: {
     architecture: 'Modified Atomic Design（UI / Page / Feature 三層）',
     naming: {
@@ -113,3 +66,27 @@ export const PROJECT_SKILLS_CONTEXT = {
     },
   },
 };
+
+/**
+ * 取得 skills 規則的文字摘要（供 AI prompt 使用）
+ */
+export function getSkillsSummaryForPrompt(skillsContext = PROJECT_SKILLS_CONTEXT) {
+  const rbp = skillsContext.reactBestPractices
+    .map(r => `  - [${r.id}] ${r.category}: ${r.desc}`)
+    .join('\n');
+  const fg = skillsContext.frontendGuidelines;
+  return `
+## 專案規範（來自 .github/skills/）
+
+### React Best Practices 規則（共 ${skillsContext.reactBestPractices.length} 條核心規則）
+${rbp}
+
+### Frontend Guidelines 規範
+- 架構: ${fg.architecture}
+- 元件命名: ${fg.naming.component}
+- 工具檔案: ${fg.naming.utility}
+- 變數: ${fg.naming.variable} / 常數: ${fg.naming.constant} / 布林值: ${fg.naming.boolean}
+- Import 順序: ${fg.importOrder}
+- 狀態管理: 客戶端=${fg.stateManagement.client} | 伺服器=${fg.stateManagement.server} | 表單=${fg.stateManagement.form}
+`;
+}