ai-git-tools 2.1.13 → 2.1.14

package/README.md

@@ -401,6 +401,39 @@ AI 產出的 notes 會固定整理成以下架構：
 
 所有 Copilot AI 回應會在程式內統一轉換為台灣繁體中文，包含 Redmine notes、需求說明、實作內容、行為規則、影響範圍與 Mermaid 文字；不依賴模型自行遵守語言設定。
 
+### `ai-git-tools redmine-subtasks`
+
+讀取一個 Redmine 主 Issue，依功能或頁面整理成少量、可獨立交付的大項子任務，並在人工審核後透過 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
+```
+
+預設會產生 2～8 個功能／頁面層級的大項；`--max-subtasks <number>` 可設定 1～12 的上限。工具不會把單一 endpoint、component、function 或測試案例拆成獨立 Issue。AI 產生的每個子任務會整理目的、工作範圍、實作重點、行為規則、驗收條件、依賴與待確認事項；`title` 會寫入 Redmine `subject`，完整 `content` 會寫入 `description`。
+
+需求能推導出使用流程時，content 會包含 Redmine Mermaid macro：
+
+```text
+{{mermaid
+flowchart TD
+    A[使用者操作] --> B[系統處理]
+    B --> C[顯示結果]
+}}
+```
+
+子任務涉及頁面但主 Issue 沒有明確畫面設計時，content 會附上純文字 wireframe，只描述資訊區塊、主要操作與已知狀態，不猜測顏色、尺寸或像素。沒有可靠流程或畫面需求時，對應區段會省略，未決事項會保留為待確認項目。
+
+apply 前會重新讀取主 Issue。若 subject、description、project 或 tracker 已變更，預設會停止建立；確認變更仍可套用時才使用 `--force`。既有子任務若有相同的 managed key 或完全相同的 title，會略過以避免重複建立。多筆建立採逐筆處理，部分成功不會回滾已建立的子任務。
+
+此命令只建立主 Issue 底下的子任務，不會修改主 Issue 的 status、description、notes、done ratio 或完成欄位。API key 沿用上方的 `REDMINE_API_KEY` 環境變數，不會放入 CLI 參數、草稿或輸出內容；AI 產出的拆分結果仍必須由使用者審核。
+
 ## ⚙️ 配置
 
 配置檔案範例（\`.ai-git-config.js\`）：

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,14 @@ registerCommand(program, 'redmine-update', '分析並更新 Redmine Issue 的開
   { flags: '--force', description: '強制略過 Issue 狀態或內容衝突檢查' },
 ], redmineUpdateCommand);
 
+registerCommand(program, 'redmine-subtasks', '分析主 Issue 並建立功能／頁面子任務', [
+  { flags: '--issue <id>', description: '指定 Redmine 主 Issue ID' },
+  { 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.14",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",

package/src/commands/redmine-subtasks.js

@@ -0,0 +1,146 @@
+import { readFileSync, writeFileSync } from 'fs';
+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.apply && !options.preview) {
+    throw new Error('請使用 --preview 產生草稿，確認後再使用 --apply --from <file>');
+  }
+
+  const issueIds = normalizeIssueOptions(options.issue);
+  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 'subtasks-analyzed':
+      return `已產生 ${progress.count} 個子任務候選`;
+    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) {
+      console.log(`❌ 主 Issue #${result.parentIssueId} 已變更，略過全部建立`);
+    } 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),
+    model: config.ai.model,
+    maxRetries: config.ai.maxRetries,
+    onProgress: printProgress,
+  });
+  console.log(formatSubtaskPreview({ parent: draft.parent, candidates: draft.subtasks }));
+  printProgress({ phase: 'preview' });
+
+  if (options.output) {
+    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

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

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) {

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');
 }
 

package/src/redmine/subtask-analyzer.js

@@ -0,0 +1,238 @@
+import { AIClient } from '../core/ai-client.js';
+import { normalizeAnalysisLanguage } from '../utils/traditional-chinese.js';
+
+const DEFAULT_MAX_SUBTASKS = 8;
+const MIN_MAX_SUBTASKS = 1;
+const MAX_MAX_SUBTASKS = 12;
+
+function assertMaxSubtasks(maxSubtasks = DEFAULT_MAX_SUBTASKS) {
+  if (!Number.isInteger(maxSubtasks) || maxSubtasks < MIN_MAX_SUBTASKS || maxSubtasks > MAX_MAX_SUBTASKS) {
+    throw new Error(`maxSubtasks 必須介於 ${MIN_MAX_SUBTASKS} 到 ${MAX_MAX_SUBTASKS} 之間`);
+  }
+  return maxSubtasks;
+}
+
+function asString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function asStringArray(value) {
+  return Array.isArray(value)
+    ? value.filter(item => typeof item === 'string').map(item => item.trim()).filter(Boolean)
+    : [];
+}
+
+function asBehaviorRules(value) {
+  return Array.isArray(value)
+    ? value
+      .filter(item => item && typeof item === 'object')
+      .map(item => ({ scenario: asString(item.scenario), behavior: asString(item.behavior) }))
+      .filter(item => item.scenario && item.behavior)
+    : [];
+}
+
+function slugify(value, fallback) {
+  return (asString(value) || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || fallback;
+}
+
+function normalizeFlowcharts(value) {
+  const flowcharts = Array.isArray(value)
+    ? value
+    : value && typeof value === 'object'
+      ? [value]
+      : [];
+  const usedIds = new Set();
+
+  return flowcharts
+    .filter(flowchart => flowchart && typeof flowchart === 'object')
+    .map((flowchart, index) => {
+      const fallback = `flowchart-${index + 1}`;
+      const id = slugify(flowchart.id || flowchart.title, fallback);
+      let uniqueId = id;
+      let suffix = index + 1;
+      while (usedIds.has(uniqueId)) uniqueId = `${id}-${suffix++}`;
+      usedIds.add(uniqueId);
+      return {
+        id: uniqueId,
+        title: asString(flowchart.title),
+        source: asString(flowchart.source || flowchart.mermaid),
+        evidence: asStringArray(flowchart.evidence),
+      };
+    })
+    .filter(flowchart => flowchart.source);
+}
+
+function normalizeSubtask(rawSubtask, index) {
+  const rawScope = rawSubtask.scope && typeof rawSubtask.scope === 'object' ? rawSubtask.scope : {};
+  return {
+    key: slugify(rawSubtask.key || rawSubtask.title, `subtask-${index + 1}`),
+    title: asString(rawSubtask.title),
+    category: rawSubtask.category === 'page' ? 'page' : rawSubtask.category === 'feature' ? 'feature' : '',
+    granularity: asString(rawSubtask.granularity || rawSubtask.level || 'large').toLowerCase(),
+    purpose: asString(rawSubtask.purpose),
+    inScope: asStringArray(rawSubtask.inScope || rawScope.inScope || rawScope.in),
+    outOfScope: asStringArray(rawSubtask.outOfScope || rawScope.outOfScope || rawScope.out),
+    implementationDetails: asStringArray(rawSubtask.implementationDetails),
+    behaviorRules: asBehaviorRules(rawSubtask.behaviorRules),
+    acceptanceCriteria: asStringArray(rawSubtask.acceptanceCriteria),
+    dependsOnKeys: asStringArray(rawSubtask.dependsOnKeys || rawSubtask.dependencies),
+    flowcharts: normalizeFlowcharts(rawSubtask.flowcharts || rawSubtask.flowchart),
+    wireframe: asString(rawSubtask.wireframe),
+    unresolvedItems: asStringArray(rawSubtask.unresolvedItems),
+    evidence: asStringArray(rawSubtask.evidence),
+  };
+}
+
+function validateSubtasks(result, parentIssueId, maxSubtasks) {
+  const expectedParentId = Number(parentIssueId);
+  if (result.parentIssueId === undefined || result.parentIssueId === null) {
+    throw new Error('AI 回應缺少 parentIssueId');
+  }
+  const actualParentId = Number(result.parentIssueId);
+  if (!Number.isInteger(expectedParentId) || actualParentId !== expectedParentId) {
+    throw new Error(`AI 回應的 parent Issue ID 不符合指定的 #${parentIssueId}`);
+  }
+
+  if (!Array.isArray(result.subtasks) || result.subtasks.length === 0) {
+    throw new Error('AI 沒有產生任何有效的子任務');
+  }
+  if (result.subtasks.length > maxSubtasks) {
+    throw new Error(`子任務數量超過 maxSubtasks 上限 ${maxSubtasks}`);
+  }
+  if (result.isIndivisible && result.subtasks.length !== 1) {
+    throw new Error('isIndivisible 為 true 時子任務數量必須恰好為 1');
+  }
+  if (result.subtasks.length === 1 && !result.isIndivisible) {
+    throw new Error('只有不可再拆的需求才能只產生 1 個子任務，請提供 indivisibleReason');
+  }
+  if (result.subtasks.length === 1 && !asString(result.indivisibleReason)) {
+    throw new Error('不可再拆的需求必須提供 indivisibleReason');
+  }
+
+  const keys = new Set();
+  const titles = new Set();
+  const sourceKeys = new Set();
+  for (const rawSubtask of result.subtasks) {
+    const sourceKey = asString(rawSubtask?.key).toLocaleLowerCase();
+    if (sourceKey && sourceKeys.has(sourceKey)) throw new Error(`子任務 key 重複：${sourceKey}`);
+    if (sourceKey) sourceKeys.add(sourceKey);
+  }
+  const subtasks = result.subtasks.map((rawSubtask, index) => normalizeSubtask(rawSubtask || {}, index));
+  for (const subtask of subtasks) {
+    const normalizedTitle = subtask.title.toLocaleLowerCase();
+    if (!subtask.title) throw new Error('子任務 title 不可為空');
+    if (titles.has(normalizedTitle)) throw new Error(`子任務 title 重複：${subtask.title}`);
+    if (keys.has(subtask.key)) throw new Error(`子任務 key 重複：${subtask.key}`);
+    if (!['feature', 'page'].includes(subtask.category)) {
+      throw new Error(`子任務 ${subtask.title} 必須是 feature 或 page category`);
+    }
+    if (subtask.granularity !== 'large') {
+      throw new Error(`子任務 ${subtask.title} 必須是大項，禁止 ${subtask.granularity} microtask`);
+    }
+    keys.add(subtask.key);
+    titles.add(normalizedTitle);
+  }
+
+  for (const subtask of subtasks) {
+    for (const dependency of subtask.dependsOnKeys) {
+      if (!keys.has(dependency)) throw new Error(`子任務 ${subtask.title} 使用未知 dependency：${dependency}`);
+      if (dependency === subtask.key) throw new Error(`子任務 ${subtask.title} 不可依賴自己`);
+    }
+  }
+
+  return {
+    parentIssueId: expectedParentId,
+    isIndivisible: Boolean(result.isIndivisible),
+    indivisibleReason: asString(result.indivisibleReason),
+    unresolvedItems: asStringArray(result.unresolvedItems),
+    subtasks,
+  };
+}
+
+/**
+ * 建立主 Issue 子任務拆分 prompt
+ * @param {{issue: object, maxSubtasks?: number}} input
+ * @returns {string}
+ */
+export function buildSubtaskAnalysisPrompt({ issue, maxSubtasks = DEFAULT_MAX_SUBTASKS }) {
+  assertMaxSubtasks(maxSubtasks);
+  const issuePromptData = { ...issue };
+  delete issuePromptData.raw;
+  return `你是資深產品分析師與軟體工程師，請將指定的 Redmine 主 Issue #${issue.id} 整理成少量、可獨立交付的功能或頁面大項子任務。
+
+重要規則：
+- 只根據主 Issue、既有子任務與 relations 進行需求消化，不得捏造未出現的需求。
+- 所有自然語言欄位必須使用台灣繁體中文。
+- 只拆分功能或頁面大項，不得把單一 endpoint、API 參數、component、function 或 test 拆成獨立子任務。
+- 每個子任務必須是 granularity: large，category 只能是 feature 或 page。
+- 預設產生 2 到 8 個子任務；只有一個不可再合理分離的交付範圍時，才能產生 1 個並填寫 isIndivisible 與 indivisibleReason。
+- 流程能由需求明確推導時才產生 Mermaid；頁面沒有明確設計時才產生純文字 wireframe，不得猜測顏色、尺寸或像素。
+- 不確定的權限、狀態、API 契約或畫面決策必須列入 unresolvedItems。
+- 每個 evidence 必須能在輸入資料中找到對應文字；不要產生 API、角色或狀態的無證據敘述。
+
+## 拆分限制
+${JSON.stringify({ maxSubtasks }, null, 2)}
+
+## 主 Issue
+${JSON.stringify(issuePromptData, null, 2)}
+
+請只回傳 JSON，不要使用 Markdown code fence：
+{
+  "parentIssueId": ${issue.id},
+  "isIndivisible": false,
+  "indivisibleReason": "",
+  "unresolvedItems": [],
+  "subtasks": [{
+    "key": "stable-feature-key",
+    "title": "功能或頁面大項標題",
+    "category": "feature",
+    "granularity": "large",
+    "purpose": "這個子任務要交付什麼",
+    "inScope": [],
+    "outOfScope": [],
+    "implementationDetails": [],
+    "behaviorRules": [{ "scenario": "情境", "behavior": "行為" }],
+    "acceptanceCriteria": [],
+    "dependsOnKeys": [],
+    "flowcharts": [{ "id": "stable-flow-id", "title": "流程名稱", "source": "flowchart TD\\n A[開始] --> B[完成]", "evidence": [] }],
+    "wireframe": "",
+    "unresolvedItems": [],
+    "evidence": []
+  }]
+}`;
+}
+
+/**
+ * 解析並驗證 AI 子任務拆分結果
+ * @param {string} content
+ * @param {number|string} parentIssueId
+ * @param {{maxSubtasks?: number}} options
+ * @returns {object}
+ */
+export function parseSubtaskAnalysis(content, parentIssueId, { maxSubtasks = DEFAULT_MAX_SUBTASKS } = {}) {
+  assertMaxSubtasks(maxSubtasks);
+  const parsed = normalizeAnalysisLanguage(AIClient.parseJSON(content));
+  return validateSubtasks(parsed, parentIssueId, maxSubtasks);
+}
+
+/**
+ * 呼叫 AI 產生主 Issue 的子任務拆分
+ * @param {{issue: object, maxSubtasks?: number, aiClient?: typeof AIClient, model?: string, maxRetries?: number}} input
+ * @returns {Promise<object>}
+ */
+export async function analyzeSubtasks({
+  issue,
+  maxSubtasks = DEFAULT_MAX_SUBTASKS,
+  aiClient = AIClient,
+  model = 'claude-haiku-4.5',
+  maxRetries = 3,
+}) {
+  const prompt = buildSubtaskAnalysisPrompt({ issue, maxSubtasks });
+  const content = await aiClient.sendAndWait(prompt, model, maxRetries);
+  return parseSubtaskAnalysis(content, issue.id, { maxSubtasks });
+}
+
+export { DEFAULT_MAX_SUBTASKS, MAX_MAX_SUBTASKS, MIN_MAX_SUBTASKS };

package/src/redmine/subtask-formatters.js

@@ -0,0 +1,156 @@
+import chalk from 'chalk';
+
+const MANAGED_KEY_PREFIX = 'ai-git-tools:redmine-subtask';
+
+function asString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function asStringArray(value) {
+  return Array.isArray(value)
+    ? value.filter(item => typeof item === 'string').map(item => item.trim()).filter(Boolean)
+    : [];
+}
+
+function bulletList(items) {
+  return asStringArray(items).map(item => `- ${item}`).join('\n');
+}
+
+function addSection(sections, title, body) {
+  const content = asString(body);
+  if (content) sections.push(`## ${title}\n\n${content}`);
+}
+
+function formatScope(subtask) {
+  const parts = [];
+  if (subtask.inScope?.length) parts.push(`### 包含\n${bulletList(subtask.inScope)}`);
+  if (subtask.outOfScope?.length) parts.push(`### 不包含\n${bulletList(subtask.outOfScope)}`);
+  return parts.join('\n\n');
+}
+
+function formatBehaviorRules(rules) {
+  const rows = Array.isArray(rules)
+    ? rules
+      .filter(rule => rule?.scenario && rule?.behavior)
+      .map(rule => `| ${String(rule.scenario).replaceAll('|', '\\|')} | ${String(rule.behavior).replaceAll('|', '\\|')} |`)
+    : [];
+  return rows.length > 0 ? `| 情境 | 行為 |\n|---|---|\n${rows.join('\n')}` : '';
+}
+
+function formatMermaid(source) {
+  let cleanSource = asString(source)
+    .replace(/^```mermaid\s*/i, '')
+    .replace(/^```\s*/, '')
+    .replace(/\s*```$/, '')
+    .replace(/^\{\{\s*mermaid\s*/i, '')
+    .replace(/\s*\}\}\s*$/, '')
+    .trim();
+  if (!cleanSource || cleanSource.includes('{{mermaid') || cleanSource.includes('}}')) return '';
+  if (!/^(flowchart|graph|sequenceDiagram|stateDiagram|classDiagram|erDiagram|journey)\b/m.test(cleanSource)) return '';
+  return `{{mermaid\n${cleanSource}\n}}`;
+}
+
+function formatFlowcharts(flowcharts) {
+  if (!Array.isArray(flowcharts)) return '';
+  return flowcharts
+    .map(flowchart => {
+      const mermaid = formatMermaid(flowchart?.source);
+      if (!mermaid) return '';
+      const title = asString(flowchart.title) || '流程';
+      const id = asString(flowchart.id) || 'flowchart-1';
+      return `### ${title}\n\n<!-- flowchart-id: ${id} -->\n${mermaid}`;
+    })
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function formatWireframe(wireframe) {
+  const value = asString(wireframe);
+  return value ? `\`\`\`text\n${value}\n\`\`\`` : '';
+}
+
+/**
+ * 建立受控的子任務識別字串
+ * @param {number|string} parentIssueId
+ * @param {string} key
+ * @returns {string}
+ */
+export function buildManagedSubtaskKey(parentIssueId, key) {
+  return `${MANAGED_KEY_PREFIX} parent=${parentIssueId} key=${asString(key)}`;
+}
+
+/**
+ * 從子任務 description 讀取受控識別字串
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function getManagedSubtaskKey(content = '') {
+  const match = String(content).match(/<!--\s*(ai-git-tools:redmine-subtask parent=\S+ key=\S+)\s*-->/);
+  return match?.[1] || null;
+}
+
+/**
+ * 將單一候選子任務格式化為 Redmine description
+ * @param {{subtask: object, parentIssueId: number|string}} input
+ * @returns {string}
+ */
+export function formatSubtaskContent({ subtask = {}, parentIssueId }) {
+  const sections = [];
+  addSection(sections, '目的', subtask.purpose);
+  addSection(sections, '工作範圍', formatScope(subtask));
+  addSection(sections, '實作重點', bulletList(subtask.implementationDetails));
+  addSection(sections, '行為規則', formatBehaviorRules(subtask.behaviorRules));
+  addSection(sections, '驗收條件', bulletList(subtask.acceptanceCriteria));
+
+  const dependencies = bulletList(subtask.dependsOnKeys);
+  const unresolvedItems = asStringArray(subtask.unresolvedItems);
+  const dependencyParts = [];
+  if (dependencies) dependencyParts.push(`### 依賴\n${dependencies}`);
+  if (unresolvedItems.length) {
+    dependencyParts.push(`### 待確認\n${unresolvedItems.map(item => `- [ ] ${item}`).join('\n')}`);
+  }
+  addSection(sections, '依賴與待確認', dependencyParts.join('\n\n'));
+  addSection(sections, '流程圖', formatFlowcharts(subtask.flowcharts));
+  addSection(sections, 'Wireframe', formatWireframe(subtask.wireframe));
+  addSection(sections, '證據', bulletList(subtask.evidence));
+
+  sections.push(`<!-- ${buildManagedSubtaskKey(parentIssueId, subtask.key)} -->`);
+  return sections.join('\n\n').trim();
+}
+
+/**
+ * 產生主 Issue 子任務 terminal preview
+ * @param {{parent: object, candidates: Array<object>}} input
+ * @returns {string}
+ */
+export function formatSubtaskPreview({ parent = {}, candidates = [] }) {
+  const lines = [
+    chalk.bold.cyan('═'.repeat(72)),
+    chalk.bold('Redmine 子任務拆分預覽'),
+    chalk.bold.cyan('═'.repeat(72)),
+    '',
+    chalk.bold.cyan(`Issue #${parent.id || '—'}：${parent.subject || '無標題'}`),
+    '既有子任務：',
+  ];
+
+  if (parent.children?.length) {
+    for (const child of parent.children) lines.push(`- #${child.id} ${child.subject || '無標題'}`);
+  } else {
+    lines.push('- 無');
+  }
+
+  for (const [index, candidate] of candidates.entries()) {
+    lines.push(
+      '',
+      chalk.bold.green(`[${index + 1}/${candidates.length}] ${candidate.title || '無標題'}`),
+      `分類：${candidate.category || '—'}`,
+      candidate.dependsOnKeys?.length ? `依賴：${candidate.dependsOnKeys.join('、')}` : '依賴：無',
+      candidate.evidence?.length ? `依據：${candidate.evidence.join('、')}` : '依據：未提供',
+      candidate.content || '',
+      chalk.dim('─'.repeat(72))
+    );
+  }
+
+  lines.push('', chalk.yellow('尚未修改 Redmine。請審核 title 與 content 後再使用 --apply。'));
+  return lines.join('\n').trim();
+}

package/src/redmine/subtask-sync.js

@@ -0,0 +1,208 @@
+import { analyzeSubtasks as defaultAnalyzeSubtasks } from './subtask-analyzer.js';
+import {
+  formatSubtaskContent,
+  getManagedSubtaskKey,
+  buildManagedSubtaskKey,
+} from './subtask-formatters.js';
+
+function getProjectId(issue = {}) {
+  return issue.projectId ?? issue.project?.id ?? null;
+}
+
+function getTrackerId(issue = {}) {
+  return issue.trackerId ?? issue.tracker?.id ?? null;
+}
+
+function sameValue(left, right) {
+  return (left ?? null) === (right ?? null);
+}
+
+function getParentSnapshot(parent) {
+  const snapshot = { ...parent, children: Array.isArray(parent.children) ? parent.children : [] };
+  delete snapshot.raw;
+  return snapshot;
+}
+
+function assertParentMetadata(parent) {
+  if (getProjectId(parent) === null || getTrackerId(parent) === null) {
+    throw new Error(`Issue #${parent.id} 缺少建立子任務需要的 project 或 tracker 資訊`);
+  }
+}
+
+function sanitizeError(error, client) {
+  const secret = client?.apiKey;
+  return secret ? String(error?.message || error).replaceAll(secret, '[REDACTED]') : String(error?.message || error);
+}
+
+function hasParentConflict(expected, current) {
+  return expected.subject !== current.subject
+    || expected.description !== current.description
+    || !sameValue(getProjectId(expected), getProjectId(current))
+    || !sameValue(getTrackerId(expected), getTrackerId(current));
+}
+
+function getExistingChildTitles(children = []) {
+  return new Set(children.map(child => String(child.subject || '').trim().toLocaleLowerCase()).filter(Boolean));
+}
+
+function getExistingManagedKeys(children = []) {
+  return new Set(children.map(child => getManagedSubtaskKey(child.description)).filter(Boolean));
+}
+
+async function loadChildDetails(client, children = []) {
+  if (typeof client?.getIssue !== 'function') return children;
+  return Promise.all(children.map(async child => {
+    if (child.description || child.id === undefined || child.id === null) return child;
+    try {
+      const detail = await client.getIssue(child.id, { include: '' });
+      return { ...child, description: detail.description || '' };
+    } catch {
+      return child;
+    }
+  }));
+}
+
+/**
+ * 產生主 Issue 子任務 draft
+ * @param {{parentIssueId: number|string, client: object, analyzeSubtasksFn?: Function, maxSubtasks?: number, model?: string, maxRetries?: number, onProgress?: Function}} options
+ * @returns {Promise<object>}
+ */
+export async function generateSubtaskDraft({
+  parentIssueId,
+  client,
+  analyzeSubtasksFn = defaultAnalyzeSubtasks,
+  maxSubtasks = 8,
+  model,
+  maxRetries,
+  onProgress = () => {},
+}) {
+  onProgress({ phase: 'read-parent', parentIssueId });
+  const parent = await client.getIssue(parentIssueId, { include: 'children,relations' });
+  assertParentMetadata(parent);
+  onProgress({ phase: 'parent-read', parentIssueId, subject: parent.subject });
+  onProgress({ phase: 'analyze-subtasks', parentIssueId });
+  const analysis = await analyzeSubtasksFn({
+    issue: parent,
+    maxSubtasks,
+    model,
+    maxRetries,
+  });
+  onProgress({ phase: 'subtasks-analyzed', parentIssueId, count: analysis.subtasks.length });
+
+  const subtasks = analysis.subtasks.map(subtask => ({
+    ...subtask,
+    title: subtask.title,
+    content: formatSubtaskContent({ subtask, parentIssueId: parent.id }),
+  }));
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    parent: getParentSnapshot(parent),
+    subtasks,
+    unresolvedItems: analysis.unresolvedItems || [],
+  };
+}
+
+/**
+ * 套用已審核的子任務 draft
+ * @param {{draft: object, client: object, force?: boolean, onProgress?: Function}} options
+ * @returns {Promise<Array<object>>}
+ */
+export async function applySubtaskDraft({ draft, client, force = false, onProgress = () => {} }) {
+  validateSubtaskDraft(draft);
+  const parentIssueId = draft.parent.id;
+  const current = await client.getIssue(parentIssueId, { include: 'children,relations' });
+  if (!force && hasParentConflict(draft.parent, current)) {
+    return [{ parentIssueId, blocked: true, reason: 'conflict' }];
+  }
+  assertParentMetadata(draft.parent);
+
+  const children = await loadChildDetails(
+    client,
+    Array.isArray(current.children) ? current.children : []
+  );
+  const managedKeys = getExistingManagedKeys(children);
+  const titles = getExistingChildTitles(children);
+  const results = [];
+  for (const [index, subtask] of draft.subtasks.entries()) {
+    onProgress({
+      phase: 'create-child',
+      index: index + 1,
+      total: draft.subtasks.length,
+      parentIssueId,
+      key: subtask.key,
+      title: subtask.title,
+    });
+    const managedKey = buildManagedSubtaskKey(parentIssueId, subtask.key);
+    if (managedKeys.has(managedKey) || titles.has(String(subtask.title).trim().toLocaleLowerCase())) {
+      results.push({ key: subtask.key, title: subtask.title, skipped: true, reason: 'duplicate' });
+      continue;
+    }
+
+    try {
+      const child = await client.createIssue({
+        projectId: getProjectId(draft.parent),
+        trackerId: getTrackerId(draft.parent),
+        subject: subtask.title,
+        description: subtask.content,
+        parentIssueId,
+      });
+      results.push({
+        key: subtask.key,
+        title: subtask.title,
+        created: true,
+        childId: child?.id ?? child?.issue?.id ?? null,
+      });
+      managedKeys.add(managedKey);
+      titles.add(String(subtask.title).trim().toLocaleLowerCase());
+    } catch (error) {
+      results.push({
+        key: subtask.key,
+        title: subtask.title,
+        created: false,
+        error: sanitizeError(error, client),
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * 驗證子任務 draft 基本結構
+ * @param {object} draft
+ */
+export function validateSubtaskDraft(draft = {}) {
+  if (draft.version !== 1 || !draft.parent || !Array.isArray(draft.subtasks) || draft.subtasks.length === 0) {
+    throw new Error('子任務 draft 格式不受支援');
+  }
+  if (draft.parent.id === undefined || draft.parent.id === null) {
+    throw new Error('子任務 draft 缺少 parent Issue ID');
+  }
+  for (const subtask of draft.subtasks) {
+    if (!subtask?.key || !subtask.title?.trim() || !subtask.content?.trim()) {
+      throw new Error('子任務 draft 缺少 key、title 或 content');
+    }
+  }
+}
+
+/**
+ * 將子任務 draft 序列化為 JSON
+ * @param {object} draft
+ * @returns {string}
+ */
+export function serializeSubtaskDraft(draft) {
+  validateSubtaskDraft(draft);
+  return `${JSON.stringify(draft, null, 2)}\n`;
+}
+
+/**
+ * 解析子任務 draft JSON
+ * @param {string} content
+ * @returns {object}
+ */
+export function parseSubtaskDraft(content) {
+  const draft = JSON.parse(content);
+  validateSubtaskDraft(draft);
+  return draft;
+}