ai-git-tools 2.1.13 → 2.1.15

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
 \`\`\`
@@ -401,6 +401,57 @@ AI 產出的 notes 會固定整理成以下架構：
 
 所有 Copilot AI 回應會在程式內統一轉換為台灣繁體中文，包含 Redmine notes、需求說明、實作內容、行為規則、影響範圍與 Mermaid 文字；不依賴模型自行遵守語言設定。
 
+### `ai-git-tools redmine-subtasks`
+
+這是 Frontend 專用的主 Issue 拆分命令。它會先判斷 Frontend scope，再依頁面或使用者可感知的完整功能整理成少量大項子任務，最後在人工審核後透過 Redmine API 建立 children。以 Issue #18793 為例：
+
+```bash
+# 只讀取與分析，不會建立子任務
+ai-git-tools redmine-subtasks --issue 18793 --preview --output redmine-subtasks.json
+
+# 確認草稿中的 title 與 content 後才建立子任務
+ai-git-tools redmine-subtasks --apply --from redmine-subtasks.json
+```
+
+可以明確指定範圍；目前只接受 `frontend`：
+
+```bash
+ai-git-tools redmine-subtasks --issue 18793 --scope frontend --preview
+```
+
+預設會產生 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：
+
+```text
+{{mermaid
+flowchart TD
+    A[使用者操作] --> B[系統處理]
+    B --> C[顯示結果]
+}}
+```
+
+子任務涉及頁面但主 Issue 沒有明確畫面設計時，content 會附上純文字 wireframe，只描述資訊區塊、主要操作與已知狀態，不猜測顏色、尺寸或像素。沒有可靠流程或畫面需求時，對應區段會省略，未決事項會保留為待確認項目。
+
+這個流程使用 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。多筆建立採逐筆處理，部分成功不會回滾已建立的子任務。
+
+此命令只建立主 Issue 底下的子任務，不會修改主 Issue 的 status、description、notes、done ratio 或完成欄位。API key 沿用上方的 `REDMINE_API_KEY` 環境變數，不會放入 CLI 參數、草稿或輸出內容；AI 產出的拆分結果仍必須由使用者審核。
+
 ## ⚙️ 配置
 
 配置檔案範例（\`.ai-git-config.js\`）：
@@ -409,7 +460,7 @@ AI 產出的 notes 會固定整理成以下架構：
 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

@@ -17,6 +17,7 @@ import { initCommand } from '../src/commands/init.js';
 import { usageCommand } from '../src/commands/usage.js';
 import { modelInfoCommand } from '../src/commands/model-info.js';
 import { redmineUpdateCommand } from '../src/commands/redmine-update.js';
+import { redmineSubtasksCommand } from '../src/commands/redmine-subtasks.js';
 import { registerCommand } from '../src/utils/cli-helpers.js';
 
 // 讀取 package.json 獲取版本號
@@ -102,4 +103,20 @@ registerCommand(program, 'redmine-update', '分析並更新 Redmine Issue 的開
   { flags: '--force', description: '強制略過 Issue 狀態或內容衝突檢查' },
 ], redmineUpdateCommand);
 
+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 內容衝突檢查' },
+], redmineSubtasksCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-git-tools",
-  "version": "2.1.13",
+  "version": "2.1.15",
   "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

@@ -0,0 +1,170 @@
+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';
+import {
+  applySubtaskDraft,
+  generateSubtaskDraft,
+  parseSubtaskDraft,
+  serializeSubtaskDraft,
+} from '../redmine/subtask-sync.js';
+import { formatSubtaskPreview } from '../redmine/subtask-formatters.js';
+import { Logger } from '../utils/logger.js';
+
+const logger = new Logger();
+
+function normalizeIssueOptions(issue) {
+  return Array.isArray(issue) ? issue : issue === undefined ? [] : [issue];
+}
+
+/**
+ * 驗證 Redmine 子任務命令參數
+ * @param {object} options
+ */
+export function validateRedmineSubtaskOptions(options = {}) {
+  if (options.apply && options.preview) throw new Error('--apply 與 --preview 不可同時使用');
+  if (options.apply && !options.from) throw new Error('--apply 必須搭配 --from <file> 使用');
+  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.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('、')}`);
+
+  if (options.maxSubtasks !== undefined) {
+    const maxSubtasks = Number(options.maxSubtasks);
+    if (!Number.isInteger(maxSubtasks) || maxSubtasks < 1 || maxSubtasks > 12) {
+      throw new Error('maxSubtasks 必須是 1 到 12 的整數');
+    }
+  }
+}
+
+/**
+ * 格式化子任務處理進度
+ * @param {object} progress
+ * @returns {string}
+ */
+export function formatSubtaskProgress(progress = {}) {
+  switch (progress.phase) {
+    case 'read-parent':
+      return `讀取 Redmine Issue #${progress.parentIssueId}...`;
+    case 'parent-read':
+      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 'preview':
+      return '預覽完成，尚未修改 Redmine';
+    default:
+      return '';
+  }
+}
+
+function printProgress(progress) {
+  const message = formatSubtaskProgress(progress);
+  if (!message) return;
+  if (progress.phase === 'parent-read' || progress.phase === 'subtasks-analyzed' || progress.phase === 'preview') {
+    logger.success(message);
+  } else {
+    logger.step(message);
+  }
+}
+
+function printApplyResults(results) {
+  for (const result of results) {
+    if (result.created) {
+      console.log(`✅ 子任務「${result.title}」已建立：#${result.childId || '—'}`);
+    } else if (result.skipped) {
+      console.log(`⚠️ 子任務「${result.title}」略過：已有相同子任務`);
+    } else if (result.blocked) {
+      const reason = result.reason === 'child-detail-unavailable'
+        ? `無法讀取既有子任務內容（${result.childIds?.join('、') || '未知'}），為避免重複建立而停止`
+        : '已變更，略過全部建立';
+      console.log(`❌ 主 Issue #${result.parentIssueId} ${reason}`);
+    } else {
+      console.log(`❌ 子任務「${result.title}」建立失敗：${result.error}`);
+    }
+  }
+}
+
+function hasSubtaskFailures(results = []) {
+  return results.some(result => result.blocked || result.created === false);
+}
+
+/**
+ * 執行 Redmine 子任務拆分 preview 或 apply
+ * @param {object} options
+ */
+export async function redmineSubtasksCommand(options = {}) {
+  validateRedmineSubtaskOptions(options);
+  logger.header('Redmine Issue 子任務拆分');
+  const config = await loadConfig();
+  const redmineConfig = buildRedmineConfig(config, process.env);
+  const client = new RedmineClient(redmineConfig);
+
+  if (options.apply) {
+    logger.step(`讀取已審核草稿：${options.from}`);
+    const draft = parseSubtaskDraft(readFileSync(options.from, 'utf-8'));
+    const results = await applySubtaskDraft({
+      draft,
+      client,
+      force: options.force,
+      onProgress: printProgress,
+    });
+    printApplyResults(results);
+    if (hasSubtaskFailures(results)) {
+      throw new Error('部分子任務建立失敗或主 Issue 發生衝突，請處理後重新套用');
+    }
+    return results;
+  }
+
+  const [parentIssueId] = normalizeIssueOptions(options.issue);
+  const draft = await generateSubtaskDraft({
+    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,
+    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} 套用。`);
+  }
+  return draft;
+}
+
+export { hasSubtaskFailures };

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;
 
@@ -160,7 +160,7 @@ export class AIClient {
         try {
           return JSON.parse(candidate);
         } catch {
-          // 繼續嘗試下一個完整 JSON 區塊
+          continue;
         }
       }
 

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

@@ -25,7 +25,7 @@ function normalizeFlowcharts(value) {
         : [];
 
   const usedIds = new Set();
-  return flowcharts.slice(0, 1)
+  return flowcharts
     .filter(flowchart => flowchart && typeof flowchart === 'object')
     .map((flowchart, index) => {
       const title = typeof flowchart.title === 'string' ? flowchart.title.trim() : '';
@@ -48,7 +48,8 @@ function normalizeFlowcharts(value) {
         evidence: asStringArray(flowchart.evidence),
       };
     })
-    .filter(flowchart => flowchart.source);
+    .filter(flowchart => flowchart.source)
+    .slice(0, 1);
 }
 
 function asStringArray(value) {
@@ -159,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

@@ -28,16 +28,30 @@ export class RedmineAPIError extends Error {
  * @returns {object}
  */
 export function normalizeIssue(rawIssue = {}) {
+  const project = rawIssue.project || null;
+  const tracker = rawIssue.tracker || null;
+  const children = rawIssue.children || rawIssue.child_issues || [];
+
   return {
     id: rawIssue.id,
     subject: rawIssue.subject || '',
     description: rawIssue.description || '',
     status: rawIssue.status || null,
-    tracker: rawIssue.tracker || null,
+    tracker,
+    trackerId: rawIssue.tracker_id ?? tracker?.id ?? null,
     parentId: rawIssue.parent_issue_id || rawIssue.parent?.id || null,
     customFields: rawIssue.custom_fields || rawIssue.customFields || [],
     allowedStatuses: rawIssue.allowed_statuses || rawIssue.allowedStatuses || [],
-    project: rawIssue.project || null,
+    project,
+    projectId: rawIssue.project_id ?? project?.id ?? null,
+    children: Array.isArray(children)
+      ? children.map(child => ({
+          id: child.id,
+          subject: child.subject || '',
+          description: child.description || '',
+        }))
+      : [],
+    relations: Array.isArray(rawIssue.relations) ? rawIssue.relations : [],
     assignedTo: rawIssue.assigned_to || rawIssue.assignedTo || null,
     raw: rawIssue,
   };
@@ -121,6 +135,36 @@ export class RedmineClient {
     return normalizeIssue(data.issue || data);
   }
 
+  /**
+   * @param {{projectId: number|string, trackerId: number|string, subject: string, description: string, parentIssueId: number|string}} input
+   * @returns {Promise<object>}
+   */
+  async createIssue({ projectId, trackerId, subject, description, parentIssueId }) {
+    if (projectId === undefined || projectId === null || trackerId === undefined || trackerId === null) {
+      throw new Error('建立 Redmine 子任務需要 projectId 與 trackerId');
+    }
+    if (!subject?.trim() || !description?.trim()) {
+      throw new Error('建立 Redmine 子任務需要 subject 與 description');
+    }
+    if (parentIssueId === undefined || parentIssueId === null) {
+      throw new Error('建立 Redmine 子任務需要 parentIssueId');
+    }
+
+    const data = await this.request('/issues.json', {
+      method: 'POST',
+      json: {
+        issue: {
+          project_id: projectId,
+          tracker_id: trackerId,
+          subject,
+          description,
+          parent_issue_id: parentIssueId,
+        },
+      },
+    });
+    return data.issue || data;
+  }
+
   /**
    * @returns {Promise<RedmineStatus[]>}
    */

package/src/redmine/redmine-formatters.js

@@ -41,7 +41,7 @@ function formatBehaviorRules(rules = []) {
 function formatFlowcharts(flowcharts = []) {
   if (!Array.isArray(flowcharts) || flowcharts.length === 0) return '';
 
-  return flowcharts.slice(0, 1)
+  return flowcharts
     .map((flowchart, index) => {
       const mermaid = formatMermaid(flowchart?.source);
       if (!mermaid) return '';
@@ -50,6 +50,7 @@ function formatFlowcharts(flowcharts = []) {
       return `### 流程圖：${title}\n\n<!-- flowchart-id: ${id} -->\n${mermaid}\n`;
     })
     .filter(Boolean)
+    .slice(0, 1)
     .join('\n');
 }