ai-git-tools 2.0.57 → 2.0.59

package/bin/cli.js

@@ -15,6 +15,10 @@ 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 { planIssueCommand } from '../src/commands/plan-issue.js';
+import { generateCodeCommand } from '../src/commands/generate-code.js';
+import { writeAndTestCommand } from '../src/commands/write-and-test.js';
+import { autoDevCommand } from '../src/commands/auto-dev.js';
 
 // 讀取 package.json 獲取版本號
 const __filename = fileURLToPath(import.meta.url);
@@ -87,6 +91,7 @@ program
   .option('--no-confirm', '跳過確認直接創建')
   .option('--auto-labels', '自動添加 Labels (預設啟用)')
   .option('--include-impact', '在 PR 中包含影響範圍分析和注意事項 (預設關閉)')
+  .option('--force-new', '強制創建新 PR，不更新現有 PR')
   .action(async (options) => {
     try {
       await prCommand(options);
@@ -96,4 +101,77 @@ program
     }
   });
 
+// Plan Issue 命令
+program
+  .command('plan-issue')
+  .description('AI 讀取 GitHub Issue 並生成結構化的實現計畫')
+  .requiredOption('--number <number>', 'Issue 編號')
+  .option('--no-confirm', '跳過確認，自動返回計畫')
+  .option('--model <model>', '指定 AI 模型')
+  .option('-v, --verbose', '顯示 Issue 詳細內容')
+  .action(async (options) => {
+    try {
+      await planIssueCommand(options);
+      process.exit(0);
+    } catch (error) {
+      process.exit(1);
+    }
+  });
+
+// Generate Code 命令
+program
+  .command('generate-code')
+  .description('AI 依據 GitHub Issue 生成符合專案風格的代碼')
+  .requiredOption('--issue <number>', 'Issue 編號')
+  .requiredOption('--file <path>', '目標檔案路徑（不可已存在）')
+  .option('--context <description>', '額外說明或補充需求')
+  .option('--max-lines <number>', '最大行數限制（預設 500）', '500')
+  .option('--no-confirm', '跳過預覽確認，直接寫入')
+  .option('--model <model>', '指定 AI 模型')
+  .action(async (options) => {
+    try {
+      await generateCodeCommand(options);
+      process.exit(0);
+    } catch (error) {
+      process.exit(1);
+    }
+  });
+
+// Write And Test 命令
+program
+  .command('write-and-test')
+  .description('AI 為指定檔案生成 Jest 測試，並自動執行與修復（最多 2 次）')
+  .requiredOption('--file <path>', '原始碼路徑')
+  .option('--test-type <type>', '測試類型：unit 或 component（預設 unit）', 'unit')
+  .option('--max-fixes <number>', '最大自動修復次數（預設 2）', '2')
+  .option('--model <model>', '指定 AI 模型')
+  .action(async (options) => {
+    try {
+      await writeAndTestCommand(options);
+      process.exit(0);
+    } catch (error) {
+      process.exit(1);
+    }
+  });
+
+// Auto Dev 整合命令
+program
+  .command('auto-dev')
+  .description('一鍵自動化：從 GitHub Issue 到代碼生成、測試與提交')
+  .requiredOption('--issue <number>', 'GitHub Issue 編號')
+  .option('--file <path>', '目標檔案路徑（若無則提示）')
+  .option('--context <description>', '額外說明或補充需求')
+  .option('--test-type <type>', '測試類型：unit 或 component（預設 unit）', 'unit')
+  .option('--max-lines <number>', '最大行數限制（預設 500）', '500')
+  .option('--no-confirm', '全自動模式，跳過所有確認')
+  .option('--model <model>', '指定 AI 模型')
+  .action(async (options) => {
+    try {
+      await autoDevCommand(options);
+      process.exit(0);
+    } catch (error) {
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-git-tools",
-  "version": "2.0.57",
+  "version": "2.0.59",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",
@@ -8,7 +8,8 @@
     "ai-git-tools": "./bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "jest",
+    "test:watch": "jest --watch",
     "prepare": "chmod +x bin/cli.js",
     "lint": "eslint src/**/*.js",
     "format": "prettier --write \"src/**/*.js\" \"bin/**/*.js\"",
@@ -40,13 +41,15 @@
   ],
   "dependencies": {
     "@github/copilot-sdk": "0.1.30",
-    "commander": "^12.0.0",
     "chalk": "^5.3.0",
-    "ora": "^8.0.1",
-    "inquirer": "^9.2.0"
+    "commander": "^12.0.0",
+    "inquirer": "^9.2.0",
+    "ora": "^8.0.1"
   },
   "devDependencies": {
+    "@jest/globals": "^29.7.0",
     "eslint": "^8.57.0",
+    "jest": "^29.7.0",
     "prettier": "^3.2.0"
   },
   "repository": {
@@ -56,5 +59,15 @@
   "bugs": {
     "url": "https://github.com/YisoTsao/ai-git-tools/issues"
   },
-  "homepage": "https://github.com/YisoTsao/ai-git-tools#readme"
+  "homepage": "https://github.com/YisoTsao/ai-git-tools#readme",
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {},
+    "extensionsToTreatAsEsm": [
+      ".js"
+    ],
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.+)\\.js$": "$1"
+    }
+  }
 }

package/src/commands/auto-dev.js

@@ -0,0 +1,230 @@
+/**
+ * auto-dev 整合命令
+ * 將 plan-issue、generate-code、write-and-test 串連起來
+ * 支援全自動模式（--no-confirm）和分步互動模式
+ */
+
+import { resolve, dirname, basename, join } from 'path';
+import inquirer from 'inquirer';
+import { IssueReader } from '../core/issue-reader.js';
+import { CodeGenerator } from '../core/code-generator.js';
+import { TestGenerator } from '../core/test-generator.js';
+import { TestRunner } from '../core/test-runner.js';
+import { AIClient } from '../core/ai-client.js';
+import { GitOperations } from '../core/git-operations.js';
+import { Logger } from '../utils/logger.js';
+
+export async function autoDevCommand(options = {}) {
+  const logger = new Logger();
+
+  const issueNumber = options.issue;
+  if (!issueNumber) {
+    logger.error('請提供 Issue 編號（--issue <number>）');
+    throw new Error('缺少 Issue 編號');
+  }
+
+  const noConfirm = options.noConfirm;
+  let filePath = options.file;
+
+  logger.header('auto-dev 整合工作流');
+  if (noConfirm) {
+    console.log('模式：全自動（跳過所有確認）');
+  } else {
+    console.log('模式：分步互動（每步完成後詢問）');
+  }
+  console.log('');
+
+  // ============================================================
+  // 第一步：讀取 Issue
+  // ============================================================
+  logger.step(`正在讀取 Issue #${issueNumber}...`);
+  const issue = await IssueReader.readIssue(issueNumber);
+  logger.success(`Issue：${issue.title}`);
+  console.log(`作者：${issue.author} | URL：${issue.url}`);
+  console.log('');
+
+  // ============================================================
+  // 第二步：生成計畫
+  // ============================================================
+  logger.step('正在分析 Issue 並生成實現計畫...');
+  const planPrompt = buildPlanPrompt(issue);
+  const plan = await AIClient.sendAndWait(planPrompt, options.model);
+  logger.section('AI 生成的實現計畫');
+  console.log(plan);
+  console.log('');
+
+  // ============================================================
+  // 第三步：詢問是否繼續（若非全自動）
+  // ============================================================
+  if (!noConfirm) {
+    const { proceed } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'proceed',
+      message: '計畫確認無誤，是否繼續進行代碼生成？',
+      default: true,
+    }]);
+
+    if (!proceed) {
+      logger.info('已取消。');
+      return;
+    }
+  }
+
+  // ============================================================
+  // 第四步：詢問目標檔案路徑（若未指定）
+  // ============================================================
+  if (!filePath) {
+    const { file } = await inquirer.prompt([{
+      type: 'input',
+      name: 'file',
+      message: '請輸入要生成的檔案路徑（例如：src/core/new-feature.js）：',
+      validate: (input) => input.trim().length > 0 ? true : '路徑不能為空',
+    }]);
+    filePath = file;
+  }
+
+  const absoluteFilePath = resolve(process.cwd(), filePath);
+  console.log('');
+
+  // ============================================================
+  // 第五步：生成代碼
+  // ============================================================
+  logger.step(`正在生成代碼：${filePath}`);
+  let codeResult;
+  try {
+    codeResult = await CodeGenerator.generateFile(issue, absoluteFilePath, {
+      maxLines: parseInt(options.maxLines || '500', 10),
+      language: filePath.endsWith('.ts') ? 'ts' : 'js',
+      extraContext: options.context || '',
+      model: options.model,
+    });
+    logger.success(`代碼已生成：${codeResult.linesCount} 行`);
+  } catch (error) {
+    logger.error(`代碼生成失敗：${error.message}`);
+    throw error;
+  }
+
+  console.log('');
+
+  // ============================================================
+  // 第六步：詢問是否執行測試（若非全自動）
+  // ============================================================
+  if (!noConfirm) {
+    const { runTest } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'runTest',
+      message: '代碼已生成，是否為該檔案生成並執行測試？',
+      default: true,
+    }]);
+
+    if (!runTest) {
+      logger.success('完成！代碼已生成。可稍後手動運行：');
+      console.log(`  ai-git-tools write-and-test --file ${filePath}`);
+      return;
+    }
+  }
+
+  // ============================================================
+  // 第七步：生成與執行測試（自動修復最多 2 次）
+  // ============================================================
+  const testFilePath = deriveTestFilePath(absoluteFilePath);
+  const maxFixes = 2;
+
+  logger.step('正在生成測試...');
+  await TestGenerator.generateTests(
+    absoluteFilePath,
+    testFilePath,
+    options.testType || 'unit',
+    options.model
+  );
+  logger.success(`測試已生成：${testFilePath}`);
+  console.log('');
+
+  let lastErrors = [];
+  for (let attempt = 0; attempt <= maxFixes; attempt++) {
+    if (attempt > 0) {
+      logger.step(`進行第 ${attempt}/${maxFixes} 次自動修復...`);
+      await TestGenerator.generateFix(absoluteFilePath, lastErrors, attempt, options.model);
+      logger.success('修復代碼已更新。');
+    }
+
+    logger.step(`執行測試${attempt > 0 ? `（第 ${attempt} 次修復後）` : ''}...`);
+    const result = await TestRunner.runTests(testFilePath);
+
+    if (result.success) {
+      logger.success('所有測試通過！ 🎉');
+      console.log('');
+      break;
+    }
+
+    lastErrors = result.errors;
+    if (attempt < maxFixes) {
+      logger.warning(`測試失敗（${result.errors.length} 個錯誤），嘗試自動修復...`);
+    } else {
+      logger.warning(`測試在第 ${maxFixes} 次修復後仍未通過`);
+      console.log('');
+      lastErrors.slice(0, 2).forEach((e, i) => {
+        console.log(`\n[錯誤 ${i + 1}]`);
+        console.log(e.split('\n').slice(0, 8).join('\n'));
+      });
+      console.log('');
+      logger.error('自動修復失敗，需要手動介入。');
+      return;
+    }
+  }
+
+  // ============================================================
+  // 第八步：自動 Commit
+  // ============================================================
+  logger.step('正在自動提交...');
+  try {
+    GitOperations.exec(`git add "${absoluteFilePath}" "${testFilePath}"`, { silent: true });
+    const commitMsg = `feat(auto-dev): Issue #${issue.number} - ${issue.title}\n\n生成檔案：\n- ${filePath}\n- ${testFilePath.replace(process.cwd(), '.')}`;
+    GitOperations.exec(`git commit -m "${commitMsg.split('\n')[0]}"`, { silent: true });
+    logger.success('已自動提交');
+  } catch {
+    logger.warning('自動 commit 失敗（可能已有相同 commit 或尚未 staged）');
+  }
+
+  console.log('');
+  logger.section('✅ 自動化工作流完成');
+  console.log(`Issue #${issue.number}：${issue.title}`);
+  console.log(`生成檔案：${filePath}`);
+  console.log(`測試檔案：${testFilePath.replace(process.cwd(), '.')}`);
+  console.log(`合計行數：${codeResult.linesCount + ' (程式碼)'}`);
+}
+
+/**
+ * 建立計畫生成 prompt
+ */
+function buildPlanPrompt(issue) {
+  return `你是一位軟體架構師。請閱讀以下 GitHub Issue 並建立詳細的實現計畫。
+
+## Issue #${issue.number}
+標題：${issue.title}
+
+描述：
+${issue.body || '（無描述）'}
+
+${issue.labels.length ? `標籤：${issue.labels.join(', ')}` : ''}
+
+## 輸出要求
+請輸出包含以下內容的實現計畫：
+
+1. **摘要** - 一句話說明要做什麼
+2. **需要新增/修改的檔案** - 列出所有相關檔案路徑和各自的職責
+3. **實現步驟** - 有序的任務清單，說明每個步驟的目的
+4. **注意事項** - 潛在風險或需要留意的事項（若有）
+
+請使用繁體中文，格式清晰，簡潔有力。`.trim();
+}
+
+/**
+ * 依據原始檔案路徑推導測試檔案路徑
+ */
+function deriveTestFilePath(sourceFilePath) {
+  const dir = dirname(sourceFilePath);
+  const name = basename(sourceFilePath).replace(/\.(js|ts|mjs|cjs)$/, '');
+  const ext = sourceFilePath.endsWith('.ts') ? '.ts' : '.js';
+  return join(dir, '__tests__', `${name}.test${ext}`);
+}

package/src/commands/generate-code.js

@@ -0,0 +1,88 @@
+/**
+ * generate-code 命令
+ * 讀取 GitHub Issue，依照指定路徑生成符合專案風格的代碼
+ */
+
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import inquirer from 'inquirer';
+import { IssueReader } from '../core/issue-reader.js';
+import { CodeGenerator } from '../core/code-generator.js';
+import { Logger } from '../utils/logger.js';
+
+export async function generateCodeCommand(options = {}) {
+  const logger = new Logger();
+
+  // 驗證必要參數
+  const issueNumber = options.issue;
+  const filePath = options.file;
+  const extraContext = options.context || '';
+  const maxLines = parseInt(options.maxLines || '500', 10);
+
+  if (!issueNumber) {
+    logger.error('請提供 Issue 編號（--issue <number>）');
+    throw new Error('缺少 Issue 編號');
+  }
+  if (!filePath) {
+    logger.error('請提供目標檔案路徑（--file <path>）');
+    throw new Error('缺少目標檔案路徑');
+  }
+
+  const absolutePath = resolve(process.cwd(), filePath);
+
+  logger.header(`generate-code`);
+  console.log(`Issue：#${issueNumber}`);
+  console.log(`目標檔案：${absolutePath}`);
+  console.log(`最大行數：${maxLines}`);
+  console.log('');
+
+  // 1. 讀取 Issue
+  logger.step(`正在讀取 Issue #${issueNumber}...`);
+  const issue = await IssueReader.readIssue(issueNumber);
+  logger.info(`Issue：${issue.title}`);
+
+  // 2. 詢問確認後再生成
+  if (!options.noConfirm) {
+    const { confirmed } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirmed',
+      message: `確認為檔案 ${filePath} 生成代碼？`,
+      default: true,
+    }]);
+
+    if (!confirmed) {
+      logger.info('已取消。');
+      return;
+    }
+  }
+
+  // 3. 生成代碼
+  logger.step('正在生成代碼中，請稍候...\n');
+
+  const result = await CodeGenerator.generateFile(issue, absolutePath, {
+    maxLines,
+    language: absolutePath.endsWith('.ts') ? 'ts' : 'js',
+    extraContext,
+    model: options.model,
+  });
+
+  // 4. 顯示結果
+  logger.section(`生成完成`);
+  logger.success(`檔案已寫入：${result.filePath}`);
+  logger.info(`共 ${result.linesCount} 行`);
+
+  // 5. 預覽前 20 行
+  try {
+    const preview = readFileSync(result.filePath, 'utf-8').split('\n').slice(0, 20).join('\n');
+    console.log('\n--- 預覽（前 20 行）---');
+    console.log(preview);
+    console.log('---');
+  } catch {
+    // 忽略預覽讀取失敗
+  }
+
+  console.log('\n💡 下一步：執行 write-and-test 為此檔案生成並執行測試');
+  console.log(`   ai-git-tools write-and-test --file ${filePath}`);
+
+  return result;
+}

package/src/commands/plan-issue.js

@@ -0,0 +1,91 @@
+/**
+ * plan-issue 命令
+ * 讀取 GitHub Issue，使用 AI 生成結構化的實現計畫
+ */
+
+import inquirer from 'inquirer';
+import { IssueReader } from '../core/issue-reader.js';
+import { AIClient } from '../core/ai-client.js';
+import { Logger } from '../utils/logger.js';
+
+export async function planIssueCommand(options = {}) {
+  const logger = new Logger();
+
+  const issueNumber = options.number || options.issue;
+  if (!issueNumber) {
+    logger.error('請提供 Issue 編號（--number <number>）');
+    throw new Error('缺少 Issue 編號');
+  }
+
+  logger.header(`plan-issue #${issueNumber}`);
+
+  // 1. 讀取 Issue
+  logger.step(`正在讀取 Issue #${issueNumber}...`);
+  const issue = await IssueReader.readIssue(issueNumber);
+
+  logger.section(`Issue #${issue.number}：${issue.title}`);
+  if (options.verbose) {
+    console.log(`作者：${issue.author}`);
+    console.log(`標籤：${issue.labels.join(', ') || '（無）'}`);
+    console.log(`URL：${issue.url}`);
+    console.log(`\n描述：\n${issue.body || '（無描述）'}`);
+  }
+
+  // 2. 呼叫 AI 生成計畫
+  logger.step('正在分析 Issue 並生成實現計畫...\n');
+  const prompt = buildPlanPrompt(issue);
+  const plan = await AIClient.sendAndWait(prompt, options.model);
+
+  // 3. 顯示計畫
+  logger.section('AI 生成的實現計畫');
+  console.log(plan);
+  console.log('');
+
+  // 4. 詢問確認（除非 --no-confirm）
+  if (options.noConfirm) {
+    logger.success('自動模式：跳過確認，繼續進行代碼生成。');
+    return { issue, plan };
+  }
+
+  const { proceed } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'proceed',
+    message: '是否確認此計畫並繼續進行代碼生成？',
+    default: false,
+  }]);
+
+  if (proceed) {
+    logger.success('計畫已確認！可以使用 generate-code 命令開始生成代碼。');
+    console.log('');
+    console.log(`  ai-git-tools generate-code --issue ${issue.number} --file <目標檔案路徑> --context <描述>`);
+  } else {
+    logger.info('已取消。請根據上方計畫手動進行後續操作。');
+  }
+
+  return { issue, plan };
+}
+
+/**
+ * 建立計畫生成 prompt
+ */
+function buildPlanPrompt(issue) {
+  return `你是一位軟體架構師。請閱讀以下 GitHub Issue 並建立詳細的實現計畫。
+
+## Issue #${issue.number}
+標題：${issue.title}
+
+描述：
+${issue.body || '（無描述）'}
+
+${issue.labels.length ? `標籤：${issue.labels.join(', ')}` : ''}
+
+## 輸出要求
+請輸出包含以下內容的實現計畫：
+
+1. **摘要** - 一句話說明要做什麼
+2. **需要新增/修改的檔案** - 列出所有相關檔案路徑和各自的職責
+3. **實現步驟** - 有序的任務清單，說明每個步驟的目的
+4. **注意事項** - 潛在風險或需要留意的事項（若有）
+
+請使用繁體中文，格式清晰，簡潔有力。`.trim();
+}

package/src/commands/pr.js

@@ -36,7 +36,7 @@ function checkGHAuth(logger) {
 /**
  * PR 命令主函數（完全照抄 scripts/ai-auto-pr.mjs）
  */
-export async function prCommand() {
+export async function prCommand(options = {}) {
   const logger = new Logger();
 
   // ── 第一步：確認 gh CLI 已登入 ──────────────────────────
@@ -46,6 +46,7 @@ export async function prCommand() {
     logger.header('AI Auto PR Generator (v2.0 Enhanced)');
 
     // 載入配置（使用 scripts/ 的配置載入邏輯）
+    
     const config = await loadConfig();
 
     if (config.output.verbose) {
@@ -54,6 +55,11 @@ export async function prCommand() {
       console.log(`   Max Diff Length: ${config.ai.maxDiffLength}`);
     }
 
+    // 將命令行選項合併到配置中
+    if (options.forceNew) {
+      config.forceNew = true;
+    }
+
     // 執行工作流程（使用 scripts/ 的完整工作流）
     const workflow = new PRWorkflow(config);
     await workflow.execute();

package/src/commands/write-and-test.js

@@ -0,0 +1,128 @@
+/**
+ * write-and-test 命令
+ * 為指定檔案生成 Jest 測試，執行測試，失敗時自動修復（最多 2 次）
+ */
+
+import { resolve, basename, dirname, join } from 'path';
+import { existsSync } from 'fs';
+import { execSync } from 'child_process';
+import inquirer from 'inquirer';
+import { TestGenerator } from '../core/test-generator.js';
+import { TestRunner } from '../core/test-runner.js';
+import { Logger } from '../utils/logger.js';
+
+export async function writeAndTestCommand(options = {}) {
+  const logger = new Logger();
+
+  const filePath = options.file;
+  const testType = options.testType || 'unit';
+  const maxFixes = parseInt(options.maxFixes || '2', 10);
+
+  if (!filePath) {
+    logger.error('請提供原始碼路徑（--file <path>）');
+    throw new Error('缺少原始碼路徑');
+  }
+
+  const absoluteSourcePath = resolve(process.cwd(), filePath);
+  if (!existsSync(absoluteSourcePath)) {
+    logger.error(`原始碼不存在：${absoluteSourcePath}`);
+    throw new Error(`找不到原始碼：${absoluteSourcePath}`);
+  }
+
+  // 推導測試檔案路徑
+  const testFilePath = deriveTestFilePath(absoluteSourcePath);
+
+  logger.header('write-and-test');
+  console.log(`原始碼  ：${absoluteSourcePath}`);
+  console.log(`測試檔案：${testFilePath}`);
+  console.log(`測試類型：${testType}`);
+  console.log(`最大修復：${maxFixes} 次`);
+  console.log('');
+
+  // 1. 詢問是否繼續
+  const { confirmed } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'confirmed',
+    message: `確認為 ${filePath} 生成 ${testType} 測試並執行？`,
+    default: true,
+  }]);
+
+  if (!confirmed) {
+    logger.info('已取消。');
+    return;
+  }
+
+  // 2. 生成測試
+  logger.step('正在生成測試代碼...');
+  await TestGenerator.generateTests(absoluteSourcePath, testFilePath, testType, options.model);
+  logger.success(`測試已寫入：${testFilePath}`);
+
+  // 3. 執行測試 + 自動修復循環
+  let lastErrors = [];
+  for (let attempt = 0; attempt <= maxFixes; attempt++) {
+    if (attempt > 0) {
+      logger.step(`正在進行第 ${attempt}/${maxFixes} 次自動修復...`);
+      await TestGenerator.generateFix(absoluteSourcePath, lastErrors, attempt, options.model);
+      logger.success('修復代碼已更新。');
+    }
+
+    logger.step(`正在執行測試${attempt > 0 ? `（第 ${attempt} 次修復後）` : ''}...`);
+    const result = await TestRunner.runTests(testFilePath);
+
+    if (result.success) {
+      logger.success('所有測試通過！ 🎉');
+
+      // 4. 自動 commit 測試檔案
+      await commitTestFile(testFilePath, absoluteSourcePath, logger);
+      return { success: true, testFilePath };
+    }
+
+    lastErrors = result.errors;
+    logger.warning(`測試失敗（${result.errors.length} 個錯誤）：`);
+    result.errors.forEach((e) => {
+      console.log('');
+      console.log(e.split('\n').slice(0, 10).join('\n'));
+    });
+
+    if (attempt >= maxFixes) {
+      // 已達最大嘗試次數，升級給使用者
+      logger.section('⚠️  自動修復失敗，需要人工介入');
+      console.log(`已嘗試自動修復 ${maxFixes} 次，測試仍未通過。`);
+      console.log('');
+      console.log('請手動查看以下錯誤並修正：');
+      lastErrors.forEach((e, i) => {
+        console.log(`\n[錯誤 ${i + 1}]`);
+        console.log(e);
+      });
+      console.log('');
+      console.log(`原始碼路徑：${absoluteSourcePath}`);
+      console.log(`測試路徑  ：${testFilePath}`);
+      return { success: false, testFilePath, errors: lastErrors };
+    }
+  }
+}
+
+/**
+ * 依據原始檔案路徑推導測試檔案路徑
+ * e.g. src/core/foo.js → src/core/__tests__/foo.test.js
+ */
+function deriveTestFilePath(sourceFilePath) {
+  const dir = dirname(sourceFilePath);
+  const name = basename(sourceFilePath).replace(/\.(js|ts|mjs|cjs)$/, '');
+  const ext = sourceFilePath.endsWith('.ts') ? '.ts' : '.js';
+  return join(dir, '__tests__', `${name}.test${ext}`);
+}
+
+/**
+ * 將測試檔案 commit 到 git
+ */
+async function commitTestFile(testFilePath, sourceFilePath, logger) {
+  try {
+    execSync(`git add "${testFilePath}"`, { stdio: 'pipe' });
+    const name = basename(sourceFilePath);
+    execSync(`git commit -m "test: 為 ${name} 新增自動生成的測試"`, { stdio: 'pipe' });
+    logger.success('測試檔案已自動 commit。');
+  } catch (error) {
+    logger.warning('無法自動 commit 測試檔案（可能沒有 staged 變更或不在 git 倉庫中）。');
+  }
+}

package/src/core/code-generator.js

@@ -0,0 +1,128 @@
+/**
+ * CodeGenerator 服務
+ * 使用 AIClient 生成符合專案風格的代碼，並執行 ESLint 驗證後寫入檔案
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { execSync } from 'child_process';
+import { AIClient } from './ai-client.js';
+import { RepoContext } from './repo-context.js';
+
+export class CodeGenerator {
+  /**
+   * 生成指定檔案的代碼
+   * @param {object} issueContext - Issue 資料 { number, title, body, labels }
+   * @param {string} filePath - 要生成的目標檔案路徑（絕對路徑）
+   * @param {object} constraints - 限制條件
+   * @param {number} constraints.maxLines - 最大行數（預設 500）
+   * @param {string} constraints.language - 語言（預設 'js'）
+   * @param {string} constraints.extraContext - 額外的使用者描述
+   * @param {string} constraints.model - AI 模型（可選）
+   * @returns {Promise<{ filePath, linesCount }>}
+   */
+  static async generateFile(issueContext, filePath, constraints = {}) {
+    const { maxLines = 500, language = 'js', extraContext = '', model } = constraints;
+
+    // 防止覆蓋現有檔案
+    if (existsSync(filePath)) {
+      throw new Error(`檔案已存在，拒絕覆蓋：${filePath}\n請選擇一個新的目標路徑。`);
+    }
+
+    // 取得專案上下文
+    const conventions = RepoContext.getProjectConventions();
+    const examples = RepoContext.getSimilarFileExamples(filePath, 2);
+
+    // 建立 prompt
+    const prompt = CodeGenerator._buildPrompt({
+      issueContext,
+      filePath,
+      maxLines,
+      language,
+      extraContext,
+      conventions,
+      examples,
+    });
+
+    // 呼叫 AI
+    const rawCode = await AIClient.sendAndWait(prompt, model);
+    const code = CodeGenerator._cleanCode(rawCode);
+
+    // 行數驗證
+    const lines = code.split('\n').length;
+    if (lines > maxLines) {
+      throw new Error(`生成的代碼超過行數限制（${lines} 行 > ${maxLines} 行）`);
+    }
+
+    // 確保目錄存在
+    mkdirSync(dirname(filePath), { recursive: true });
+
+    // 寫入暫時檔案並 lint
+    writeFileSync(filePath, code, 'utf-8');
+    CodeGenerator._lintFile(filePath);
+
+    return { filePath, linesCount: lines };
+  }
+
+  /**
+   * 建立代碼生成 prompt
+   */
+  static _buildPrompt({ issueContext, filePath, maxLines, language, extraContext, conventions, examples }) {
+    return `你是一位 ${language.toUpperCase()} 專家。請依照以下需求生成代碼。
+
+## GitHub Issue
+標題：${issueContext.title}
+描述：
+${issueContext.body || '（無描述）'}
+${issueContext.labels?.length ? `標籤：${issueContext.labels.join(', ')}` : ''}
+
+## 目標檔案
+${filePath}
+
+## 專案約定
+${conventions}
+
+## 代碼範例（相似檔案）
+${examples}
+
+## 使用者補充說明
+${extraContext || '（無）'}
+
+## 生成規則
+- 最多 ${maxLines} 行
+- 使用 ESM (import/export) 語法
+- 包含必要的 JSDoc 註解
+- 僅輸出程式碼本身，不要 markdown 區塊（\`\`\`）
+- 不要輸出任何說明文字，直接輸出可執行的程式碼`.trim();
+  }
+
+  /**
+   * 移除 AI 回傳中的 markdown code fence
+   */
+  static _cleanCode(raw) {
+    return raw
+      .replace(/^```[\w]*\n?/gm, '')
+      .replace(/\n?```$/gm, '')
+      .trim();
+  }
+
+  /**
+   * 對指定檔案執行 ESLint（若存在 eslint 設定）
+   * 不強制中止——只在 lint 有 error 時拋出例外
+   */
+  static _lintFile(filePath) {
+    try {
+      execSync(`npx eslint --no-eslintrc --rule '{"no-undef": "warn"}' "${filePath}"`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      });
+    } catch (error) {
+      const output = error.stdout || error.stderr || '';
+      // 若 eslint 回傳 exit code 1 表示有 error
+      if (error.status === 1 && output.includes('error')) {
+        throw new Error(`ESLint 驗證失敗：\n${output}`);
+      }
+      // exit code 2 為 eslint 設定問題，忽略
+    }
+  }
+}

package/src/core/issue-reader.js

@@ -0,0 +1,58 @@
+/**
+ * IssueReader 服務
+ * 透過 gh CLI 從 GitHub 讀取 Issue 詳情
+ */
+
+import { execSync } from 'child_process';
+
+export class IssueReader {
+  /**
+   * 讀取指定 Issue 的詳情
+   * @param {number|string} issueNumber - Issue 編號
+   * @returns {{ number, title, body, labels, author, url }}
+   */
+  static async readIssue(issueNumber) {
+    if (!issueNumber || isNaN(Number(issueNumber))) {
+      throw new Error(`無效的 Issue 編號：${issueNumber}`);
+    }
+
+    const json = IssueReader._fetchIssueJson(issueNumber);
+    return IssueReader._parseIssue(json);
+  }
+
+  /**
+   * 使用 gh CLI 抓取 Issue 的 JSON 資料
+   */
+  static _fetchIssueJson(issueNumber) {
+    try {
+      const raw = execSync(
+        `gh issue view ${issueNumber} --json number,title,body,labels,author,url`,
+        { encoding: 'utf-8', stdio: 'pipe' }
+      );
+      return JSON.parse(raw.trim());
+    } catch (error) {
+      if (error.message.includes('Could not resolve') || error.message.includes('not found')) {
+        throw new Error(`Issue #${issueNumber} 不存在或無法存取`);
+      }
+      if (error.message.includes('gh: command not found') || error.message.includes('not found: gh')) {
+        throw new Error('找不到 gh CLI，請先安裝：https://cli.github.com');
+      }
+      throw new Error(`讀取 Issue 失敗：${error.message}`);
+    }
+  }
+
+  /**
+   * 解析 gh CLI 回傳的 JSON 為標準結構
+   */
+  static _parseIssue(json) {
+    const labels = (json.labels || []).map((l) => (typeof l === 'string' ? l : l.name));
+    return {
+      number: json.number,
+      title: json.title || '',
+      body: json.body || '',
+      labels,
+      author: json.author?.login || json.author || '',
+      url: json.url || '',
+    };
+  }
+}

package/src/core/repo-context.js

@@ -0,0 +1,114 @@
+/**
+ * RepoContext 服務
+ * 掃描專案目錄結構，提供代碼生成所需的上下文
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'fs';
+import { join, extname, relative, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, '..', '..');
+
+// 要排除的目錄
+const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.nyc_output']);
+// 支援的程式碼副檔名
+const CODE_EXTS = new Set(['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx']);
+
+export class RepoContext {
+  /**
+   * 依據目標檔案路徑尋找相似的現有檔案片段
+   * @param {string} targetPath - 要生成的目標檔案路徑（相對或絕對）
+   * @param {number} maxExamples - 最多回傳幾個範例，預設 3
+   * @returns {string} 格式化的範例文字
+   */
+  static getSimilarFileExamples(targetPath, maxExamples = 3) {
+    const ext = extname(targetPath);
+    const allFiles = RepoContext._scanFiles(ROOT);
+    const codeFiles = allFiles.filter(
+      (f) => extname(f) === ext && !f.includes('.test.') && !f.includes('.spec.')
+    );
+
+    // 按路徑相似度排序，取前 N 個
+    const sorted = codeFiles
+      .filter((f) => f !== targetPath)
+      .slice(0, maxExamples);
+
+    if (sorted.length === 0) return '（無相似範例）';
+
+    return sorted
+      .map((f) => {
+        try {
+          const content = readFileSync(f, 'utf-8');
+          const lines = content.split('\n').slice(0, 40).join('\n');
+          const relPath = relative(ROOT, f);
+          return `// 範例檔案：${relPath}\n${lines}`;
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .join('\n\n---\n\n');
+  }
+
+  /**
+   * 取得專案主要約定（依據 package.json 及目錄結構判斷）
+   * @returns {string}
+   */
+  static getProjectConventions() {
+    const hints = [];
+
+    // 讀取 package.json
+    const pkgPath = join(ROOT, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        hints.push(`模組系統：${pkg.type === 'module' ? 'ESM (import/export)' : 'CommonJS (require)'}`);
+        if (pkg.dependencies?.typescript || pkg.devDependencies?.typescript) {
+          hints.push('語言：TypeScript');
+        } else {
+          hints.push('語言：JavaScript');
+        }
+        const testDep = pkg.devDependencies?.jest || pkg.dependencies?.jest;
+        if (testDep) hints.push('測試框架：Jest');
+      } catch {
+        // 忽略解析錯誤
+      }
+    }
+
+    // 目錄結構提示
+    const srcExists = existsSync(join(ROOT, 'src'));
+    if (srcExists) hints.push('原始碼位於 src/ 目錄');
+
+    return hints.length > 0 ? hints.join('\n') : '（無法自動偵測專案約定）';
+  }
+
+  /**
+   * 遞迴掃描目錄，回傳所有程式碼檔案的絕對路徑
+   */
+  static _scanFiles(dir) {
+    const results = [];
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return results;
+    }
+    for (const name of entries) {
+      if (EXCLUDED_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      try {
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+          results.push(...RepoContext._scanFiles(full));
+        } else if (CODE_EXTS.has(extname(name))) {
+          results.push(full);
+        }
+      } catch {
+        // 忽略無法存取的路徑
+      }
+    }
+    return results;
+  }
+}

package/src/core/test-generator.js

@@ -0,0 +1,115 @@
+/**
+ * TestGenerator 服務
+ * 為指定的原始碼檔案使用 AIClient 生成 Jest 測試
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { AIClient } from './ai-client.js';
+
+export class TestGenerator {
+  /**
+   * 為原始檔案生成測試並寫入測試檔案
+   * @param {string} sourceFilePath - 原始碼路徑（絕對路徑）
+   * @param {string} testFilePath - 測試檔案輸出路徑（絕對路徑）
+   * @param {'unit'|'component'} testType - 測試類型（預設 'unit'）
+   * @param {string} [model] - AI 模型（可選）
+   * @returns {Promise<{ testFilePath, linesCount }>}
+   */
+  static async generateTests(sourceFilePath, testFilePath, testType = 'unit', model) {
+    let sourceCode;
+    try {
+      sourceCode = readFileSync(sourceFilePath, 'utf-8');
+    } catch {
+      throw new Error(`無法讀取原始碼：${sourceFilePath}`);
+    }
+
+    const prompt = TestGenerator._buildPrompt(sourceCode, sourceFilePath, testType);
+    const rawTests = await AIClient.sendAndWait(prompt, model);
+    const testCode = TestGenerator._cleanCode(rawTests);
+
+    // 確保目錄存在
+    mkdirSync(dirname(testFilePath), { recursive: true });
+    writeFileSync(testFilePath, testCode, 'utf-8');
+
+    return { testFilePath, linesCount: testCode.split('\n').length };
+  }
+
+  /**
+   * 使用錯誤訊息重新生成修復後的原始碼
+   * @param {string} sourceFilePath - 原始碼路徑
+   * @param {string[]} testErrors - Jest 錯誤訊息陣列
+   * @param {number} attempt - 第幾次修復嘗試（1 或 2）
+   * @param {string} [model] - AI 模型（可選）
+   * @returns {Promise<void>}
+   */
+  static async generateFix(sourceFilePath, testErrors, attempt, model) {
+    let sourceCode;
+    try {
+      sourceCode = readFileSync(sourceFilePath, 'utf-8');
+    } catch {
+      throw new Error(`無法讀取原始碼：${sourceFilePath}`);
+    }
+
+    const prompt = TestGenerator._buildFixPrompt(sourceCode, testErrors, attempt);
+    const rawFixed = await AIClient.sendAndWait(prompt, model);
+    const fixedCode = TestGenerator._cleanCode(rawFixed);
+
+    writeFileSync(sourceFilePath, fixedCode, 'utf-8');
+  }
+
+  /**
+   * 建立測試生成 prompt
+   */
+  static _buildPrompt(sourceCode, sourceFilePath, testType) {
+    return `你是一位 Jest 測試專家。請為以下 ${testType === 'component' ? 'React 元件' : '模組'} 撰寫全面的 ${testType} 測試。
+
+## 原始碼（${sourceFilePath}）
+\`\`\`
+${sourceCode}
+\`\`\`
+
+## 測試要求
+1. 使用現代 Jest 語法（describe / it / expect）
+2. 涵蓋所有主要函數及邊界情況
+3. Mock 所有外部依賴（檔案系統、網路、子程序等）
+4. 使用 beforeEach / afterEach 管理測試狀態
+5. 測試名稱使用繁體中文描述
+
+## 輸出規則
+- 只輸出可直接執行的測試程式碼
+- 不要 markdown 區塊（\`\`\`）、不要任何說明文字
+- 第一行必須是 import 或 require 陳述式`.trim();
+  }
+
+  /**
+   * 建立修復 prompt
+   */
+  static _buildFixPrompt(sourceCode, testErrors, attempt) {
+    return `這是第 ${attempt} 次修復嘗試。以下是目前的原始碼和失敗的測試錯誤，請修正原始碼使測試通過。
+
+## 當前原始碼
+\`\`\`
+${sourceCode}
+\`\`\`
+
+## 測試錯誤
+${testErrors.join('\n')}
+
+## 修復規則
+- 只修改原始碼，不修改測試
+- 保留原有功能，只修正造成測試失敗的部分
+- 只輸出修正後的完整原始碼，不要任何說明文字
+- 不要 markdown 區塊（\`\`\`）`.trim();
+  }
+
+  /**
+   * 移除 AI 回傳中的 markdown code fence
+   */
+  static _cleanCode(raw) {
+    return raw
+      .replace(/^```[\w]*\n?/gm, '')
+      .replace(/\n?```$/gm, '')
+      .trim();
+  }
+}

package/src/core/test-runner.js

@@ -0,0 +1,79 @@
+/**
+ * TestRunner 服務
+ * 執行 Jest 測試、解析結果，並在失敗時觸發自動修復（最多 2 次）
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+
+export class TestRunner {
+  /**
+   * 執行指定的測試檔案
+   * @param {string} testFilePath - 測試檔案路徑（絕對路徑）
+   * @returns {Promise<{ success: boolean, errors: string[] }>}
+   */
+  static async runTests(testFilePath) {
+    if (!existsSync(testFilePath)) {
+      return { success: false, errors: [`測試檔案不存在：${testFilePath}`] };
+    }
+
+    try {
+      execSync(`npx jest "${testFilePath}" --no-coverage --forceExit`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        timeout: 120000, // 2 分鐘超時
+      });
+      return { success: true, errors: [] };
+    } catch (error) {
+      const output = (error.stdout || '') + (error.stderr || '');
+      const errors = TestRunner._parseErrors(output);
+      return { success: false, errors };
+    }
+  }
+
+  /**
+   * 解析 Jest 輸出，提取失敗訊息
+   * @param {string} output
+   * @returns {string[]}
+   */
+  static _parseErrors(output) {
+    const errors = [];
+    const lines = output.split('\n');
+
+    let inFailBlock = false;
+    let currentError = [];
+
+    for (const line of lines) {
+      // 偵測失敗區塊的開始
+      if (line.includes('● ') || line.includes('FAIL ')) {
+        if (currentError.length > 0) {
+          errors.push(currentError.join('\n').trim());
+          currentError = [];
+        }
+        inFailBlock = true;
+      }
+
+      if (inFailBlock) {
+        currentError.push(line);
+
+        // 限制每個錯誤區塊最多 30 行，防止輸出過長
+        if (currentError.length >= 30) {
+          errors.push(currentError.join('\n').trim());
+          currentError = [];
+          inFailBlock = false;
+        }
+      }
+    }
+
+    if (currentError.length > 0) {
+      errors.push(currentError.join('\n').trim());
+    }
+
+    // 若未能解析出具體錯誤，回傳原始輸出的前 50 行
+    if (errors.length === 0) {
+      errors.push(lines.slice(0, 50).join('\n'));
+    }
+
+    return errors;
+  }
+}

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

@@ -193,20 +193,22 @@ export class GitHubAPI {
    * 創建或更新 PR
    */
   async createOrUpdatePR(params) {
-    const { title, body, baseBranch, headBranch, reviewers } = params;
+    const { title, body, baseBranch, headBranch, reviewers, forceNew } = params;
     const bodyFile = '/tmp/pr-body.md';
     writeFileSync(bodyFile, body);
 
     try {
-      // 檢查 PR 是否已存在
+      // 檢查 PR 是否已存在（除非強制創建新 PR）
       let existingPRUrl = null;
-      try {
-        existingPRUrl = execSync(
-          `gh pr list --head "${headBranch}" --base "${baseBranch}" --json url --jq '.[0].url'`,
-          { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
-        ).trim();
-      } catch (error) {
-        // PR 不存在
+      if (!forceNew) {
+        try {
+          existingPRUrl = execSync(
+            `gh pr list --head "${headBranch}" --base "${baseBranch}" --json url --jq '.[0].url'`,
+            { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+          ).trim();
+        } catch (error) {
+          // PR 不存在
+        }
       }
 
       const escapedTitle = title.replace(/"/g, '\\"');

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

@@ -422,6 +422,7 @@ export class PRWorkflow {
       headBranch,
       reviewers,
       config: this.config,
+      forceNew: this.config.forceNew,
     });
   }