ai-git-tools 2.1.2 → 2.1.4

package/README.md

@@ -352,7 +352,7 @@ ai-git-tools redmine-update --apply --from redmine-update.json
 
 Preview 會以色彩分開顯示每個 Issue 的開發內容、程式修改重點、API 變更、重要技術細節、修改檔案與實際 note。狀態由 Redmine API 提供選單，只有使用者選擇的 status 才會寫入。
 
-原始 Issue description 會保留不覆寫，更新內容會寫入 notes。只有找到明確測試或驗證證據時才會加入驗證段落；流程圖則使用 Redmine Mermaid macro：
+原始 Issue description 會保留原始內容；若 AI 產生可靠流程，工具只替換 description 中由 `ai-git-tools` 管理的 Mermaid 區塊，不會重複追加。更新摘要會寫入 notes，並使用 Markdown 標題、項目符號與雙反引號標示程式路徑、API path、function 與 class。只有找到明確測試或驗證證據時才會加入驗證段落；流程圖會使用 Redmine Mermaid macro 並放在 description（公司 Redmine 的 notes 不支援 Mermaid）：
 
 ```text
 {{mermaid
@@ -364,6 +364,8 @@ flowchart TD
 
 Issue note 的基本責任分工如下：`description` 保存原始需求，`status` 保存目前狀態，`notes` 保存 Git 開發與同步紀錄。
 
+當 preview 選擇「已解決」後套用，工具會同步將完成百分比設為 `100%`，並依欄位名稱找到 `程式碼更版進度` custom field，勾選測試機選項 `測`。custom field ID 會從 Issue API 動態取得，不會寫死公司 Redmine 的 ID。
+
 ## ⚙️ 配置
 
 配置檔案範例（\`.ai-git-config.js\`）：
@@ -440,7 +442,7 @@ github: {
 
 ## 🔧 環境需求
 
-- **Node.js** >= 18.0.0
+- **Node.js** >= 22.12.0
 - **Git** 已安裝並設定
 - **GitHub CLI** (用於 PR 功能)
   \`\`\`bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-git-tools",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",
@@ -27,7 +27,7 @@
   "author": "Yiso Tsao <yiso05255@gmail.com>",
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "files": [
     "bin/",

package/src/commands/redmine-update.js

@@ -63,6 +63,19 @@ export function hasApplyFailures(results = []) {
   return results.some(result => result.applied === false && !result.skipped);
 }
 
+/**
+ * 確認 preview 至少產生一筆可套用草稿
+ * @param {object} draft
+ */
+export function validateGeneratedDraft(draft = {}) {
+  if (!Array.isArray(draft.drafts) || draft.drafts.length === 0) {
+    const details = draft.failures?.map(failure => `#${failure.issueId}: ${failure.error}`).join('；');
+    throw new Error(
+      `沒有成功產生任何 Issue 更新草稿${details ? `。失敗原因：${details}` : ''}`
+    );
+  }
+}
+
 /**
  * 執行 Redmine Issue preview 或 apply
  * @param {object} options
@@ -94,10 +107,16 @@ export async function redmineUpdateCommand(options = {}) {
     maxRetries: config.ai.maxRetries,
   });
 
+  validateGeneratedDraft(draft);
   console.log(renderPreview(draft.drafts));
   for (const failure of draft.failures) {
     console.log(`❌ Issue #${failure.issueId} 無法產生更新：${failure.error}`);
   }
+  for (const item of draft.drafts) {
+    if (item.customFieldWarning) {
+      console.log(`⚠️ Issue #${item.issueId}：${item.customFieldWarning}`);
+    }
+  }
   console.log('\n尚未修改 Redmine。');
   if (options.output) {
     writeFileSync(options.output, serializeDraft(draft), 'utf-8');

package/src/core/ai-client.js

@@ -6,6 +6,31 @@
 import { CopilotClient, approveAll } from '@github/copilot-sdk';
 
 export class AIClient {
+  /**
+   * 判斷 Node.js 是否符合 Copilot SDK 的版本需求
+   * @param {string} version
+   * @returns {boolean}
+   */
+  static isSupportedNodeVersion(version = process.versions.node) {
+    const match = String(version).match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return false;
+
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return (major === 20 && minor >= 19) || (major >= 22 && (major > 22 || minor >= 12));
+  }
+
+  /**
+   * 確認 Node.js 符合 Copilot SDK 的版本需求
+   */
+  static assertSupportedNodeVersion() {
+    if (!AIClient.isSupportedNodeVersion()) {
+      throw new Error(
+        `目前 Node.js ${process.versions.node} 不符合 Copilot SDK 需求。請升級至 Node.js 20.19+ 或 22.12+。`
+      );
+    }
+  }
+
   /**
    * 檢測是否為 Copilot 授權相關的錯誤
    */
@@ -30,6 +55,7 @@ export class AIClient {
    * 發送 prompt 並等待回應（帶重試機制和超時保護）
    */
   static async sendAndWait(prompt, model = 'claude-haiku-4.5', maxRetries = 3, timeout = 150000) {
+    AIClient.assertSupportedNodeVersion();
     let lastError = null;
 
     for (let attempt = 1; attempt <= maxRetries; attempt++) {

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

@@ -1,5 +1,5 @@
 import { CopilotClient, approveAll } from '@github/copilot-sdk';
-import { CONSTANTS } from '../../utils/constants.js';
+import { AIClient } from '../../core/ai-client.js';
 import { log } from '../../utils/logger.js';
 import { isCopilotAuthError } from '../../utils/helpers.js';
 import {
@@ -26,6 +26,7 @@ export class AIAnalyzer {
    * 取得（或建立）共用的 CopilotClient
    */
   async _getOrCreateClient() {
+    AIClient.assertSupportedNodeVersion();
     if (!this._client) {
       this._client = new CopilotClient();
     }

package/src/redmine/issue-analyzer.js

@@ -45,7 +45,8 @@ export function buildIssueAnalysisPrompt({ issue, evidence }) {
 - 不得捏造 API endpoint、參數、檔案、function、class、測試或部署結果。
 - 沒有明確測試或驗證證據時，verification 必須是空陣列。
 - 沒有可靠 API 變更證據時，apiChanges 必須是空陣列。
-- 若能從實際流程推導出可靠的複製流程，才產生 flowchart；否則為 null。
+- 若能從實際流程推導出可靠的複製流程，才產生 flowchart；否則為 null。flowchart 必須以 graph TD 開始，不要加入 Mermaid wrapper 或 code fence。
+- developmentSummary、codeChanges、apiChanges、technicalDetails 中的程式路徑、API path、function 與 class 使用雙反引號標示；需要多行程式片段時使用 code block。
 - 不要產生 suggestedStatus、coverage 或 confidence，也不要決定 Redmine status。
 
 ## 指定 Redmine Issue

package/src/redmine/issue-sync.js

@@ -2,6 +2,7 @@ import { analyzeIssue as defaultAnalyzeIssue } from './issue-analyzer.js';
 import { createHash } from 'crypto';
 import {
   formatRedmineNote,
+  formatRedmineDescription,
   formatRedminePreview,
   selectIssueStatus,
 } from './redmine-formatters.js';
@@ -10,6 +11,41 @@ function uniqueIssueIds(issueIds = []) {
   return [...new Set(issueIds.map(id => Number(id)).filter(Number.isInteger))];
 }
 
+/**
+ * 判斷 Redmine 狀態是否代表已解決
+ * @param {string} statusName
+ * @returns {boolean}
+ */
+export function isResolvedStatus(statusName = '') {
+  return /已解決|resolved/i.test(statusName);
+}
+
+/**
+ * 建立測試機完成欄位更新
+ * @param {object} issue
+ * @param {{statusId: number, statusName: string}} selectedStatus
+ * @returns {{doneRatio?: number, customFields: Array<object>, warning?: string}}
+ */
+export function buildCompletionUpdate(issue, selectedStatus) {
+  if (!isResolvedStatus(selectedStatus.statusName)) return { customFields: [] };
+
+  const progressField = issue.customFields?.find(
+    field => field.name?.trim() === '程式碼更版進度'
+  );
+  if (!progressField) {
+    return {
+      doneRatio: 100,
+      customFields: [],
+      warning: '找不到 custom field「程式碼更版進度」，已略過 checkbox 更新',
+    };
+  }
+
+  return {
+    doneRatio: 100,
+    customFields: [{ id: progressField.id, value: ['測'] }],
+  };
+}
+
 /**
  * 建立單一 Issue 的同步識別
  * @param {{issueId: number|string, evidence: object, pullRequest?: object|null}}
@@ -47,6 +83,8 @@ export async function generateRedmineDraft({
       const issue = await client.getIssue(issueId);
       const analysis = await analyzeIssueFn({ issue, evidence: { ...evidence, pullRequest }, model, maxRetries });
       const selectedStatus = await selectStatusFn(issue, { client });
+      const completion = buildCompletionUpdate(issue, selectedStatus);
+      const description = formatRedmineDescription(issue.description, analysis.flowchart);
       const syncId = createSyncId({ issueId, evidence, pullRequest });
       const note = formatRedmineNote({
         issueId,
@@ -64,6 +102,10 @@ export async function generateRedmineDraft({
         originalDescription: issue.description,
         statusId: selectedStatus.statusId,
         statusName: selectedStatus.statusName,
+        doneRatio: completion.doneRatio,
+        customFields: completion.customFields,
+        customFieldWarning: completion.warning || null,
+        description: description !== issue.description ? description : undefined,
         analysis,
         note,
         syncId,
@@ -114,10 +156,12 @@ export async function applyRedmineDraft({ draft, client, force = false }) {
         continue;
       }
 
-      await client.updateIssue(item.issueId, {
-        statusId: item.statusId,
-        notes: item.note,
-      });
+      const update = { statusId: item.statusId, notes: item.note };
+      if (item.doneRatio !== undefined) update.doneRatio = item.doneRatio;
+      if (item.description !== undefined) update.description = item.description;
+      if (item.customFields?.length) update.customFields = item.customFields;
+
+      await client.updateIssue(item.issueId, update);
       results.push({ issueId: item.issueId, applied: true });
     } catch (error) {
       results.push({ issueId: item.issueId, applied: false, error: error.message });

package/src/redmine/redmine-client.js

@@ -130,14 +130,19 @@ export class RedmineClient {
   }
 
   /**
-   * @param {number|string} issueId
-   * @param {{statusId?: number, notes?: string}} update
+  * @param {number|string} issueId
+  * @param {{statusId?: number, doneRatio?: number, description?: string, notes?: string, customFields?: Array<object>}} update
    * @returns {Promise<object>}
    */
-  async updateIssue(issueId, { statusId, notes }) {
+  async updateIssue(issueId, { statusId, doneRatio, description, notes, customFields }) {
     const issue = {};
     if (statusId !== undefined && statusId !== null) issue.status_id = statusId;
+    if (doneRatio !== undefined && doneRatio !== null) issue.done_ratio = doneRatio;
+    if (description !== undefined) issue.description = description;
     if (notes) issue.notes = notes;
+    if (Array.isArray(customFields) && customFields.length > 0) {
+      issue.custom_fields = customFields;
+    }
 
     return this.request(`/issues/${encodeURIComponent(issueId)}.json`, {
       method: 'PUT',

package/src/redmine/redmine-formatters.js

@@ -3,9 +3,12 @@ import chalk from 'chalk';
 
 function bulletSection(title, items) {
   if (!Array.isArray(items) || items.length === 0) return '';
-  return `${title}：\n${items.map(item => `- ${item}`).join('\n')}\n`;
+  return `### ${title}\n${items.map(item => `- ${item}`).join('\n')}\n`;
 }
 
+const MERMAID_START = '<!-- ai-git-tools:mermaid:start -->';
+const MERMAID_END = '<!-- ai-git-tools:mermaid:end -->';
+
 /**
  * 將 Mermaid source 包成 Redmine macro
  * @param {string|null} source
@@ -27,6 +30,8 @@ export function formatMermaid(source) {
       .trim();
   }
 
+  cleanSource = cleanSource.replace(/^flowchart\s+TD\b/i, 'graph TD');
+
   if (
     cleanSource.includes('{{mermaid') ||
     cleanSource.includes('}}') ||
@@ -38,30 +43,55 @@ export function formatMermaid(source) {
   return `{{mermaid\n${cleanSource}\n}}`;
 }
 
+/**
+ * 將 Mermaid 放入 Redmine description 的受管理區塊
+ * @param {string} description
+ * @param {string|null} source
+ * @returns {string}
+ */
+export function formatRedmineDescription(description = '', source = null) {
+  const mermaid = formatMermaid(source);
+  if (!mermaid) return description;
+
+  const block = `${MERMAID_START}\n\n### 開發流程\n\n${mermaid}\n\n${MERMAID_END}`;
+  const markerPattern = new RegExp(
+    `${MERMAID_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${MERMAID_END.replace(/[.*+?^${}()|[\]\\\\]/g, '\\$&')}`
+  );
+
+  if (markerPattern.test(description)) {
+    return description.replace(markerPattern, block);
+  }
+
+  return `${description.trim()}\n\n${block}`.trim();
+}
+
 /**
  * 格式化 Redmine Issue note
  * @param {{issueId: number|string, analysis: object, evidence: object, pullRequest?: object|null, syncId?: string}} input
  * @returns {string}
  */
 export function formatRedmineNote({ issueId, analysis = {}, evidence = {}, pullRequest = null, syncId }) {
-  const sections = ['Git 開發更新', ''];
+  const sections = [`## Git 開發更新（Issue #${issueId}）`, ''];
   const development = bulletSection('開發內容', analysis.developmentSummary);
   const codeChanges = bulletSection('程式修改重點', analysis.codeChanges);
   const apiChanges = bulletSection('API 變更', analysis.apiChanges);
   const technicalDetails = bulletSection('重要技術細節', analysis.technicalDetails);
-  const modifiedFiles = bulletSection('修改檔案', analysis.modifiedFiles || evidence.changedFiles);
+  const modifiedFiles = bulletSection(
+    '修改檔案',
+    analysis.modifiedFiles?.length
+      ? analysis.modifiedFiles.map(file => `\`\`${file}\`\``)
+      : evidence.changedFiles?.map(file => `\`\`${file}\`\``)
+  );
   const verification = bulletSection('驗證結果', analysis.verification);
   const unresolved = bulletSection('尚未完成或待確認', analysis.unresolvedItems);
 
   sections.push(development, codeChanges, apiChanges, technicalDetails, modifiedFiles, verification);
-  const mermaid = formatMermaid(analysis.flowchart);
-  if (mermaid) sections.push('流程圖：\n', mermaid, '\n');
   sections.push(unresolved);
 
   if (evidence.currentBranch || evidence.baseBranch) {
     sections.push(
-      `Git branch：${evidence.currentBranch || '—'}`,
-      `比較基準：${evidence.baseBranch || '—'}`,
+      `### Git 關聯\n\n- Branch：\`\`${evidence.currentBranch || '—'}\`\``,
+      `- 比較基準：\`\`${evidence.baseBranch || '—'}\`\``,
       ''
     );
   }
@@ -114,6 +144,7 @@ export async function selectIssueStatus(issue, { client, prompt = inquirer.promp
   const statuses = getAvailableStatuses(issue, fallbackStatuses);
   const choices = createStatusChoices(statuses);
   if (choices.length === 0) throw new Error(`Issue #${issue.id} 沒有可用的 Redmine 狀態`);
+  const resolvedIndex = choices.findIndex(choice => /已解決|resolved/i.test(choice.name));
 
   const answer = await prompt([
     {
@@ -121,6 +152,7 @@ export async function selectIssueStatus(issue, { client, prompt = inquirer.promp
       name: 'statusId',
       message: `Issue #${issue.id}：選擇更新後狀態`,
       choices,
+      default: resolvedIndex >= 0 ? resolvedIndex : 0,
     },
   ]);
   const selected = statuses.find(status => status.id === answer.statusId);
@@ -140,8 +172,15 @@ export function formatRedminePreview(drafts = []) {
       chalk.bold.cyan(`Issue #${draft.issueId}`),
       `${chalk.dim('目前狀態：')} ${draft.currentStatusName || draft.originalStatusName || '—'}`,
       `${chalk.green('更新狀態：')} ${draft.statusName || '未選擇'}`,
+      draft.doneRatio !== undefined ? `${chalk.green('完成百分比：')} ${draft.doneRatio}%` : '',
+      draft.customFields?.length
+        ? `${chalk.green('程式碼更版進度：')} ${draft.customFields.flatMap(field => field.value || []).join('、')}`
+        : '',
       '',
       draft.note,
+      draft.description
+        ? `${chalk.bold('description Mermaid：')}\n${draft.description}`
+        : '',
       chalk.dim('─'.repeat(72)),
       ''
     );