ai-git-tools 2.1.14 → 2.1.16

package/README.md

@@ -147,7 +147,7 @@ npx ai-git-tools commit [選項]
 
 \`\`\`bash
 npx ai-git-tools commit
-npx ai-git-tools commit --model claude-haiku-4.5
+npx ai-git-tools commit --model gpt-5.6-luna
 npx ai-git-tools commit --verbose
 \`\`\`
 
@@ -238,7 +238,7 @@ npx ai-git-tools model-info [選項]
 
 \`\`\`bash
 npx ai-git-tools model-info
-npx ai-git-tools model-info --model claude-haiku-4.5
+npx ai-git-tools model-info --model gpt-5.6-luna
 npx ai-git-tools model-info --filter claude
 npx ai-git-tools model-info --json
 \`\`\`
@@ -403,20 +403,41 @@ AI 產出的 notes 會固定整理成以下架構：
 
 ### `ai-git-tools redmine-subtasks`
 
-讀取一個 Redmine 主 Issue，依功能或頁面整理成少量、可獨立交付的大項子任務，並在人工審核後透過 Redmine API 建立 children。以 Issue #18793 為例：
+這是 Frontend 專用的主 Issue 拆分命令。它會先判斷 Frontend scope，再依頁面或使用者可感知的完整功能整理成少量大項子任務，最後在人工審核後透過 Redmine API 建立 children。以 Issue #18793 為例：
 
 ```bash
 # 只讀取與分析，不會建立子任務
-ai-git-tools redmine-subtasks \
-  --issue 18793 \
-  --preview \
-  --output redmine-subtasks.json
+ai-git-tools redmine-subtasks --issue 18793 --preview --output redmine-subtasks.json
 
 # 確認草稿中的 title 與 content 後才建立子任務
 ai-git-tools redmine-subtasks --apply --from redmine-subtasks.json
+
+# 重新拆分後，覆蓋該 draft 快照中的既有受控子任務
+ai-git-tools redmine-subtasks --apply --from redmine-subtasks.json --replace
+```
+
+可以明確指定範圍；目前只接受 `frontend`：
+
+```bash
+ai-git-tools redmine-subtasks --issue 18793 --scope frontend --preview
 ```
 
-預設會產生 2～8 個功能／頁面層級的大項；`--max-subtasks <number>` 可設定 1～12 的上限。工具不會把單一 endpoint、component、function 或測試案例拆成獨立 Issue。AI 產生的每個子任務會整理目的、工作範圍、實作重點、行為規則、驗收條件、依賴與待確認事項；`title` 會寫入 Redmine `subject`，完整 `content` 會寫入 `description`。
+預設會產生 2～8 個功能／頁面層級的大項；`--max-subtasks <number>` 可設定 1～12 的上限。工具不會把單一 endpoint、component、hook、util、function、欄位或測試案例拆成獨立 Issue；明確服務多個頁面的共用 Frontend 基礎設施才可成為前置大項。
+
+如果主 Issue 同時包含 Frontend 與 Backend、Mobile、QA、DevOps 需求，預覽會顯示 Frontend scope decision，只建立 Frontend 子任務，並把排除內容與依據列出。沒有 Frontend 需求時不會保存可套用的空草稿；範圍不明時必須先補充需求。
+
+每個子任務會產生 schema v2 的完整開發內容，包括：
+
+- 一句話需求說明、功能需求、包含／不包含範圍、依賴與開發順序。
+- route、存取角色與 evidence；沒有明確 route 時保留未提供，不會猜測路徑。
+- 每個 list、detail、create、edit、view、dashboard、modal 畫面各自列出 screen 與 ASCII wireframe，不會把多個畫面合併成一張模糊示意圖。
+- 使用者流程與 loading、empty、success、error、permission、validation、disabled、unsaved 等有依據的狀態。
+- 每個可操作子任務的 Mermaid 流程圖；無法從需求確認流程時會保留 `not-supported` 狀態與原因，不製造假流程。
+- 有 API 依據時，逐筆保存 method、base URL、path、用途、auth、headers、path/query/body、request example、response status/body、response example、error、pagination、filter、sort 與 completeness。
+- API 只提供 path 或 method 時標記為 partial；沒有 API 依據時維持空的 `apiContract`／`requestResponse`，並列為待確認事項，不使用一般 REST 慣例補欄位。
+- validation、error handling、permission、authentication、authorization、responsive、accessibility、i18n、performance、security、analytics、browser compatibility、cache、polling、feature flag 與 Frontend test plan；未提及的項目使用空值，不會自動套用最佳實務。
+
+內容會區分 `explicit`（Issue 明確要求）、`repository`（安全提供的專案上下文）與 `derived`（為了讓需求可驗收的最小推導）。無法確認的決策會放入 `unresolvedItems`，不會被寫成確定需求。`title` 會寫入 Redmine `subject`，完整 Frontend content 會寫入 `description`。
 
 需求能推導出使用流程時，content 會包含 Redmine Mermaid macro：
 
@@ -430,7 +451,7 @@ flowchart TD
 
 子任務涉及頁面但主 Issue 沒有明確畫面設計時，content 會附上純文字 wireframe，只描述資訊區塊、主要操作與已知狀態，不猜測顏色、尺寸或像素。沒有可靠流程或畫面需求時，對應區段會省略，未決事項會保留為待確認項目。
 
-apply 前會重新讀取主 Issue。若 subject、description、project 或 tracker 已變更，預設會停止建立；確認變更仍可套用時才使用 `--force`。既有子任務若有相同的 managed key 或完全相同的 title，會略過以避免重複建立。多筆建立採逐筆處理，部分成功不會回滾已建立的子任務。
+這個流程使用 schema v2 draft。舊版 v1 草稿不可直接套用，請重新執行 preview。apply 前會重新讀取主 Issue；若 subject、description、project 或 tracker 已變更，預設會停止建立，確認變更仍可套用時才使用 `--force`。`--force` 只略過 parent snapshot conflict，不會略過 schema、payload 或 duplicate validation。既有子任務若有相同 managed key 或完全相同 title，會略過以避免重複建立；children summary 沒有 description 時，工具會再讀取 child detail 判斷 managed key。若重新產生 preview 後要覆蓋上一次拆分的內容，請在 apply 時加上 `--replace`；它只會依 draft 快照順序覆蓋帶有工具 managed marker 的既有子任務，數量增加時建立新的子任務，數量減少時不刪除多出的舊項目。多筆建立或更新採逐筆處理，部分成功不會回滾已建立或已更新的子任務。
 
 此命令只建立主 Issue 底下的子任務，不會修改主 Issue 的 status、description、notes、done ratio 或完成欄位。API key 沿用上方的 `REDMINE_API_KEY` 環境變數，不會放入 CLI 參數、草稿或輸出內容；AI 產出的拆分結果仍必須由使用者審核。
 
@@ -442,7 +463,7 @@ apply 前會重新讀取主 Issue。若 subject、description、project 或 trac
 export default {
   // AI 設定
   ai: {
-    model: 'claude-haiku-4.5', // AI 模型
+    model: 'gpt-5.6-luna', // AI 模型
     maxDiffLength: 8000, // 最大 diff 長度
     maxRetries: 3, // 失敗重試次數
   },

package/bin/cli.js

@@ -103,14 +103,21 @@ registerCommand(program, 'redmine-update', '分析並更新 Redmine Issue 的開
   { flags: '--force', description: '強制略過 Issue 狀態或內容衝突檢查' },
 ], redmineUpdateCommand);
 
-registerCommand(program, 'redmine-subtasks', '分析主 Issue 並建立功能／頁面子任務', [
-  { flags: '--issue <id>', description: '指定 Redmine 主 Issue ID' },
+registerCommand(program, 'redmine-subtasks', '分析主 Issue 的 Frontend 需求並建立功能／頁面子任務', [
+  {
+    flags: '--issue <id>',
+    description: '指定 Redmine 主 Issue ID（僅允許一個）',
+    argParser: (value, previous = []) => [...previous, value],
+    defaultValue: [],
+  },
+  { flags: '--scope <scope>', description: '分析範圍（目前只支援 frontend）' },
   { flags: '--max-subtasks <number>', description: '子任務大項上限（預設：8）' },
   { flags: '--preview', description: '產生並顯示拆分預覽，不修改 Redmine' },
   { flags: '--output <file>', description: '保存 preview 草稿 JSON' },
   { flags: '--apply', description: '套用已審核的子任務草稿' },
   { flags: '--from <file>', description: '指定要套用的子任務草稿 JSON' },
   { flags: '--force', description: '強制略過主 Issue 內容衝突檢查' },
+  { flags: '--replace', description: '覆蓋 draft 快照中的既有受控子任務' },
 ], redmineSubtasksCommand);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-git-tools",
-  "version": "2.1.14",
+  "version": "2.1.16",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",

package/src/commands/init.js

@@ -16,7 +16,7 @@ const DEFAULT_CONFIG = `/**
 export default {
   // AI 相關配置
   ai: {
-    model: 'claude-haiku-4.5', // AI 模型
+    model: 'gpt-5.6-luna', // AI 模型
     maxDiffLength: 8000, // 最大 diff 長度
     maxRetries: 3, // 最大重試次數
   },

package/src/commands/redmine-subtasks.js

@@ -1,4 +1,5 @@
-import { readFileSync, writeFileSync } from 'fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
 import { loadConfig } from '../core/config-loader.js';
 import { RedmineClient } from '../redmine/redmine-client.js';
 import { buildRedmineConfig } from '../redmine/config.js';
@@ -27,11 +28,21 @@ export function validateRedmineSubtaskOptions(options = {}) {
   if (options.from && !options.apply) throw new Error('--from 只能搭配 --apply 使用');
   if (options.output && !options.preview) throw new Error('--output 只能搭配 --preview 使用');
   if (options.force && !options.apply) throw new Error('--force 只能搭配 --apply 使用');
+  if (options.replace && !options.apply) throw new Error('--replace 只能搭配 --apply 使用');
+  if (options.scope !== undefined && options.scope !== 'frontend') {
+    throw new Error('目前 redmine-subtasks 只支援 frontend scope');
+  }
   if (!options.apply && !options.preview) {
     throw new Error('請使用 --preview 產生草稿，確認後再使用 --apply --from <file>');
   }
 
   const issueIds = normalizeIssueOptions(options.issue);
+  if (issueIds.length > 1) {
+    throw new Error('redmine-subtasks 只允許指定一個 parent Issue');
+  }
+  if (options.apply && issueIds.length > 0) {
+    throw new Error('--issue 只能搭配 --preview 使用，apply 請以 draft 的 parent 為準');
+  }
   if (!options.apply && issueIds.length === 0) throw new Error('preview 模式需要 --issue <id>');
   const invalidIssueIds = issueIds.filter(id => !/^[1-9]\d*$/.test(String(id)));
   if (invalidIssueIds.length > 0) throw new Error(`Issue ID 必須是正整數：${invalidIssueIds.join('、')}`);
@@ -57,10 +68,16 @@ export function formatSubtaskProgress(progress = {}) {
       return `主 Issue #${progress.parentIssueId} 已讀取：${progress.subject || '無標題'}`;
     case 'analyze-subtasks':
       return `分析 Issue #${progress.parentIssueId} 的功能／頁面大項...`;
+    case 'scope-analysis':
+      return `分析 Issue #${progress.parentIssueId} 的 Frontend scope...`;
     case 'subtasks-analyzed':
       return `已產生 ${progress.count} 個子任務候選`;
+    case 'screen-enrichment':
+      return `[${progress.index}/${progress.total}] 整理 screen wireframe...`;
     case 'create-child':
       return `[${progress.index}/${progress.total}] 建立子任務：${progress.title || '無標題'}`;
+    case 'replace-child':
+      return `[${progress.index}/${progress.total}] 覆蓋子任務：${progress.title || '無標題'}`;
     case 'preview':
       return '預覽完成，尚未修改 Redmine';
     default:
@@ -80,12 +97,17 @@ function printProgress(progress) {
 
 function printApplyResults(results) {
   for (const result of results) {
-    if (result.created) {
+    if (result.updated) {
+      console.log(`✅ 子任務「${result.title}」已覆蓋：#${result.childId || '—'}`);
+    } else if (result.created) {
       console.log(`✅ 子任務「${result.title}」已建立：#${result.childId || '—'}`);
     } else if (result.skipped) {
       console.log(`⚠️ 子任務「${result.title}」略過：已有相同子任務`);
     } else if (result.blocked) {
-      console.log(`❌ 主 Issue #${result.parentIssueId} 已變更，略過全部建立`);
+      const reason = result.reason === 'child-detail-unavailable'
+        ? `無法讀取既有子任務內容（${result.childIds?.join('、') || '未知'}），為避免重複建立而停止`
+        : '已變更，略過全部建立';
+      console.log(`❌ 主 Issue #${result.parentIssueId} ${reason}`);
     } else {
       console.log(`❌ 子任務「${result.title}」建立失敗：${result.error}`);
     }
@@ -93,7 +115,7 @@ function printApplyResults(results) {
 }
 
 function hasSubtaskFailures(results = []) {
-  return results.some(result => result.blocked || result.created === false);
+  return results.some(result => result.blocked || result.created === false || result.updated === false);
 }
 
 /**
@@ -114,6 +136,7 @@ export async function redmineSubtasksCommand(options = {}) {
       draft,
       client,
       force: options.force,
+      replace: options.replace,
       onProgress: printProgress,
     });
     printApplyResults(results);
@@ -128,14 +151,21 @@ export async function redmineSubtasksCommand(options = {}) {
     parentIssueId,
     client,
     maxSubtasks: options.maxSubtasks === undefined ? 8 : Number(options.maxSubtasks),
+    repositoryContext: options.repositoryContext || config.frontend?.repositoryContext || {},
     model: config.ai.model,
     maxRetries: config.ai.maxRetries,
     onProgress: printProgress,
   });
-  console.log(formatSubtaskPreview({ parent: draft.parent, candidates: draft.subtasks }));
+  console.log(formatSubtaskPreview({
+    parent: draft.parent,
+    candidates: draft.subtasks,
+    analysisScope: draft.analysisScope,
+    scopeDecision: draft.scopeDecision,
+  }));
   printProgress({ phase: 'preview' });
 
   if (options.output) {
+    mkdirSync(dirname(options.output), { recursive: true });
     writeFileSync(options.output, serializeSubtaskDraft(draft), 'utf-8');
     console.log(`預覽草稿已保存：${options.output}`);
     console.log(`請使用 --apply --from ${options.output} 套用。`);

package/src/core/ai-client.js

@@ -98,7 +98,7 @@ export class AIClient {
   /**
    * 發送 prompt 並等待回應（帶重試機制和超時保護）
    */
-  static async sendAndWait(prompt, model = 'claude-haiku-4.5', maxRetries = 3, timeout = 150000) {
+  static async sendAndWait(prompt, model = 'gpt-5.6-luna', maxRetries = 3, timeout = 150000) {
     AIClient.assertSupportedNodeVersion();
     let lastError = null;
 
@@ -110,13 +110,7 @@ export class AIClient {
           onPermissionRequest: approveAll,
         });
 
-        // 使用 Promise.race 實現超時控制
-        const responsePromise = session.sendAndWait({ prompt });
-        const timeoutPromise = new Promise((_, reject) => {
-          setTimeout(() => reject(new Error(`AI 請求超時 (${timeout}ms)`)), timeout);
-        });
-
-        const response = await Promise.race([responsePromise, timeoutPromise]);
+        const response = await session.sendAndWait({ prompt }, timeout);
 
         const content = response?.data?.content || '';
         return toTraditionalChinese(content.trim());

package/src/core/config-loader.js

@@ -12,7 +12,7 @@ import { resolve } from 'path';
  */
 const DEFAULT_CONFIG = {
   ai: {
-    model: 'claude-haiku-4.5',
+    model: 'gpt-5.6-luna',
     maxDiffLength: 8000,
     maxRetries: 3,
   },
@@ -193,7 +193,7 @@ function showHelp() {
 
 選項：
   --base <branch>      指定目標分支 (預設: 使用配置檔的 defaultBase 或自動偵測)
-  --model <model>      指定 AI 模型 (預設: claude-haiku-4.5)
+  --model <model>      指定 AI 模型 (預設: gpt-5.6-luna)
   --preview            僅預覽 PR 內容，不實際創建
   --no-confirm         跳過確認直接創建
   --auto-labels        自動添加 Labels (預設啟用)

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

@@ -18,7 +18,7 @@ const AI_TIMEOUT_MS = 150000;
  */
 export class AIAnalyzer {
   constructor(config = {}) {
-    this.model = config.model || 'claude-haiku-4.5';
+    this.model = config.model || 'gpt-5.6-luna';
     this._client = null; // 複用同一個 CopilotClient，避免重複啟動子程序
   }
 

package/src/redmine/issue-analyzer.js

@@ -160,7 +160,7 @@ export async function analyzeIssue({
   issue,
   evidence,
   aiClient = AIClient,
-  model = 'claude-haiku-4.5',
+  model = 'gpt-5.6-luna',
   maxRetries = 3,
 }) {
   const prompt = buildIssueAnalysisPrompt({ issue, evidence });

package/src/redmine/redmine-client.js

@@ -175,14 +175,15 @@ export class RedmineClient {
 
   /**
   * @param {number|string} issueId
-  * @param {{statusId?: number, doneRatio?: number, dueDate?: string, description?: string, notes?: string, customFields?: Array<object>}} update
+  * @param {{statusId?: number, doneRatio?: number, dueDate?: string, subject?: string, description?: string, notes?: string, customFields?: Array<object>}} update
    * @returns {Promise<object>}
    */
-  async updateIssue(issueId, { statusId, doneRatio, dueDate, description, notes, customFields }) {
+  async updateIssue(issueId, { statusId, doneRatio, dueDate, subject, description, notes, customFields }) {
     const issue = {};
     if (statusId !== undefined && statusId !== null) issue.status_id = statusId;
     if (doneRatio !== undefined && doneRatio !== null) issue.done_ratio = doneRatio;
     if (dueDate !== undefined && dueDate !== null) issue.due_date = dueDate;
+    if (subject !== undefined) issue.subject = subject;
     if (description !== undefined) issue.description = description;
     if (notes) issue.notes = notes;
     if (Array.isArray(customFields) && customFields.length > 0) {