ai-git-tools 2.1.1 → 2.1.2

package/.env.example

@@ -0,0 +1,5 @@
+# Redmine REST API base URL
+REDMINE_URL=https://redmine.example.com
+
+# 建議使用環境變數或 Secret Manager 保存，不要提交真實 API key
+REDMINE_API_KEY=your-redmine-api-key

package/README.md

@@ -245,6 +245,125 @@ npx ai-git-tools model-info --json
 
 > 第一次執行會連線到 Copilot CLI 取得模型清單，可能需要數秒鐘；後續預設使用 24 小時快取。
 
+### `ai-git-tools redmine-update`
+
+分析目前 Git branch 的程式變更，依照指定的 Redmine Issue 個別產生開發更新內容，並在確認後更新 Issue 的狀態與筆記。
+
+> 注意：npm 套件不會也不應該保存你的 Redmine API key。npm 上發布的是讀取環境變數的程式碼；每位使用者都要在自己的本機或 CI 執行環境設定變數。
+
+#### Redmine 設定
+
+請先在 Redmine 管理介面啟用 REST API，並從個人帳號頁面建立具備 Issue 讀寫權限的 API key。API key 只放在環境變數，不要放在 CLI 參數、設定檔或 Git。
+
+不同 shell 的設定語法如下。請只選擇符合你目前終端機的區塊執行：
+
+**bash / zsh（macOS、Linux 常見）**
+
+```bash
+export REDMINE_URL="https://redmine.example.com"
+export REDMINE_API_KEY="你的 Redmine API key"
+
+# 只確認是否已設定，不顯示 key 內容
+test -n "$REDMINE_URL" && echo "REDMINE_URL 已設定"
+test -n "$REDMINE_API_KEY" && echo "REDMINE_API_KEY 已設定"
+```
+
+**fish**
+
+```fish
+set -x REDMINE_URL "https://redmine.example.com"
+set -x REDMINE_API_KEY "你的 Redmine API key"
+
+test -n "$REDMINE_URL"; and echo "REDMINE_URL 已設定"
+test -n "$REDMINE_API_KEY"; and echo "REDMINE_API_KEY 已設定"
+```
+
+**PowerShell**
+
+```powershell
+$env:REDMINE_URL = "https://redmine.example.com"
+$env:REDMINE_API_KEY = "你的 Redmine API key"
+
+if ($env:REDMINE_URL) { Write-Output "REDMINE_URL 已設定" }
+if ($env:REDMINE_API_KEY) { Write-Output "REDMINE_API_KEY 已設定" }
+```
+
+**Windows Command Prompt（cmd）**
+
+```bat
+set REDMINE_URL=https://redmine.example.com
+set REDMINE_API_KEY=你的 Redmine API key
+
+if defined REDMINE_URL echo REDMINE_URL 已設定
+if defined REDMINE_API_KEY echo REDMINE_API_KEY 已設定
+```
+
+完成環境變數設定後，`npx` 的使用方式完全相同：
+
+```text
+npx ai-git-tools redmine-update --issue 124 --preview --output redmine-update.json
+```
+
+環境變數只對目前的 shell 工作階段有效。若重新開啟終端機後不想重新設定，請使用各 shell 的啟動設定檔或作業系統的 Secret Manager；不要把真實 API key 提交到 Git。
+
+也可以將專案內的 `.env.example` 複製成 `.env` 作為設定範本；目前 CLI 直接讀取 process environment，因此 shell 必須先載入該檔案：
+
+```bash
+cp .env.example .env
+# 編輯 .env 填入實際 URL 與 API key
+set -a
+source .env
+set +a
+```
+
+全域安裝或使用 `npx` 時，環境變數仍然設定在「執行命令的 shell」中：
+
+```bash
+npm install -g ai-git-tools
+export REDMINE_URL="https://redmine.example.com"
+export REDMINE_API_KEY="你的 Redmine API key"
+ai-git-tools redmine-update --issue 124 --preview --output redmine-update.json
+```
+
+發布前可用以下指令確認 `.env.example` 會被包含在 npm 套件中，但不會包含 `.env`：
+
+```bash
+npm pack --dry-run
+```
+
+#### Preview 與 Apply
+
+沒有 `--pr` 時，工具會比較目前 branch 與 `origin` 上依 branch 名稱版本號排序後最新的 `release-*` branch；`--base` 可指定其他比較基準。每個 `--issue` 都會先獨立讀取 Redmine 的 subject、description、status、tracker、custom fields 與 allowed statuses，再與共用 Git evidence 分開分析。
+
+```bash
+ai-git-tools redmine-update \
+  --issue 124 \
+  --issue 125 \
+  --issue 126 \
+  --issue 127 \
+  --preview \
+  --output redmine-update.json
+
+# 套用已檢查的草稿，不重新呼叫 AI
+ai-git-tools redmine-update --apply --from redmine-update.json
+```
+
+`--pr <number>` 是可選的補充 evidence，會加入 PR title、body、URL、merge state、commits 與 changed files；沒有 PR 仍可完整分析本機 Git diff。沒有 PR 時，工具不會自動推論已 merge、已部署或必須關閉 Issue。
+
+Preview 會以色彩分開顯示每個 Issue 的開發內容、程式修改重點、API 變更、重要技術細節、修改檔案與實際 note。狀態由 Redmine API 提供選單，只有使用者選擇的 status 才會寫入。
+
+原始 Issue description 會保留不覆寫，更新內容會寫入 notes。只有找到明確測試或驗證證據時才會加入驗證段落；流程圖則使用 Redmine Mermaid macro：
+
+```text
+{{mermaid
+flowchart TD
+    A[開始] --> B[處理]
+    B --> C[完成]
+}}
+```
+
+Issue note 的基本責任分工如下：`description` 保存原始需求，`status` 保存目前狀態，`notes` 保存 Git 開發與同步紀錄。
+
 ## ⚙️ 配置
 
 配置檔案範例（\`.ai-git-config.js\`）：

package/bin/cli.js

@@ -16,6 +16,7 @@ import { prCommand } from '../src/commands/pr.js';
 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 { registerCommand } from '../src/utils/cli-helpers.js';
 
 // 讀取 package.json 獲取版本號
@@ -84,4 +85,21 @@ registerCommand(program, 'model-info', '查看目前可用的 AI 模型資訊',
   { flags: '--no-cache', description: '忽略快取，強制重新連線 Copilot 取得最新模型清單' },
 ], modelInfoCommand);
 
+// Redmine Issue 更新命令
+registerCommand(program, 'redmine-update', '分析並更新 Redmine Issue 的開發內容', [
+  {
+    flags: '--issue <id>',
+    description: '指定 Redmine Issue ID，可重複使用',
+    argParser: (value, previous = []) => [...previous, value],
+    defaultValue: [],
+  },
+  { flags: '--pr <number>', description: '可選的 GitHub Pull Request 編號' },
+  { flags: '--base <branch>', description: '指定 Git 比較基準 branch' },
+  { flags: '--preview', description: '產生並顯示更新預覽，不修改 Redmine' },
+  { flags: '--output <file>', description: '保存 preview 草稿 JSON' },
+  { flags: '--apply', description: '套用已審核的草稿' },
+  { flags: '--from <file>', description: '指定要套用的 preview 草稿 JSON' },
+  { flags: '--force', description: '強制略過衝突與重複同步檢查' },
+], redmineUpdateCommand);
+
 program.parse();

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "ai-git-tools",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",
   "bin": {
-    "ai-git-tools": "./bin/cli.js"
+    "ai-git-tools": "bin/cli.js"
   },
   "scripts": {
     "test": "node --test test/*.test.js",
@@ -35,6 +35,7 @@
     "templates/",
     "README.md",
     "README.zh-TW.md",
+    ".env.example",
     "LICENSE",
     "CHANGELOG.md"
   ],

package/src/commands/redmine-update.js

@@ -0,0 +1,111 @@
+/**
+ * Redmine Issue 更新命令
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { loadConfig } from '../core/config-loader.js';
+import { collectGitEvidence, collectPullRequestEvidence } from '../redmine/git-evidence.js';
+import { buildRedmineConfig } from '../redmine/config.js';
+import { RedmineClient } from '../redmine/redmine-client.js';
+import {
+  applyRedmineDraft,
+  generateRedmineDraft,
+  parseDraft,
+  serializeDraft,
+} from '../redmine/issue-sync.js';
+import { formatRedminePreview as renderPreview } from '../redmine/redmine-formatters.js';
+
+function printApplyResults(results) {
+  for (const result of results) {
+    if (result.applied) {
+      console.log(`✅ Issue #${result.issueId} 已更新`);
+    } else if (result.skipped) {
+      const reason = result.reason === 'duplicate' ? '已同步，略過重複更新' : '資料已變更，略過更新';
+      console.log(`⚠️ Issue #${result.issueId} ${reason}`);
+    } else {
+      console.log(`❌ Issue #${result.issueId} 更新失敗：${result.error}`);
+    }
+  }
+}
+
+/**
+ * 驗證 Redmine update CLI 參數
+ * @param {object} options
+ */
+export function validateRedmineOptions(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.apply && !options.preview) {
+    throw new Error('請使用 --preview 產生草稿，確認後再使用 --apply --from <file>');
+  }
+  if (!options.apply && (!options.issue || options.issue.length === 0)) {
+    throw new Error('preview 模式至少需要一個 --issue <id>');
+  }
+  const invalidIssueIds = (options.issue || []).filter(id => !/^[1-9]\d*$/.test(String(id)));
+  if (invalidIssueIds.length > 0) {
+    throw new Error(`Issue ID 必須是正整數：${invalidIssueIds.join('、')}`);
+  }
+}
+
+/**
+ * 判斷 apply 是否有實際失敗的 Issue
+ * @param {Array<object>} results
+ * @returns {boolean}
+ */
+export function hasApplyFailures(results = []) {
+  return results.some(result => result.applied === false && !result.skipped);
+}
+
+/**
+ * 執行 Redmine Issue preview 或 apply
+ * @param {object} options
+ */
+export async function redmineUpdateCommand(options = {}) {
+  validateRedmineOptions(options);
+  const config = await loadConfig();
+  const redmineConfig = buildRedmineConfig(config, process.env);
+  const client = new RedmineClient(redmineConfig);
+
+  if (options.apply) {
+    const draft = parseDraft(readFileSync(options.from, 'utf-8'));
+    const results = await applyRedmineDraft({ draft, client, force: options.force });
+    printApplyResults(results);
+    if (hasApplyFailures(results)) {
+      throw new Error('部分 Redmine Issue 更新失敗，請查看上方結果並重新處理失敗項目');
+    }
+    return results;
+  }
+
+  const evidence = collectGitEvidence({ baseBranch: options.base });
+  const pullRequest = options.pr ? collectPullRequestEvidence(options.pr) : null;
+  const draft = await generateRedmineDraft({
+    issueIds: options.issue,
+    client,
+    evidence,
+    pullRequest,
+    model: config.ai.model,
+    maxRetries: config.ai.maxRetries,
+  });
+
+  console.log(renderPreview(draft.drafts));
+  for (const failure of draft.failures) {
+    console.log(`❌ Issue #${failure.issueId} 無法產生更新：${failure.error}`);
+  }
+  console.log('\n尚未修改 Redmine。');
+  if (options.output) {
+    writeFileSync(options.output, serializeDraft(draft), 'utf-8');
+    console.log(`預覽草稿已保存：${options.output}`);
+    console.log(`請使用 --apply --from ${options.output} 套用。`);
+  } else {
+    console.log('請重新執行並加入 --output redmine-update.json 保存草稿。');
+  }
+
+  return draft;
+}

package/src/redmine/config.js

@@ -0,0 +1,27 @@
+/**
+ * Redmine 連線設定
+ */
+
+/**
+ * 建立 Redmine API 設定
+ * @param {object} projectConfig
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{url: string, apiKey: string}}
+ */
+export function buildRedmineConfig(projectConfig = {}, env = process.env) {
+  const url = env.REDMINE_URL || projectConfig.redmine?.url;
+  const apiKey = env.REDMINE_API_KEY;
+
+  if (!url || !apiKey) {
+    throw new Error(
+      '缺少 Redmine 設定。請先設定 REDMINE_URL 與 REDMINE_API_KEY 環境變數。\n' +
+        '請依照目前使用的 shell 參考 README 中的 Redmine 設定說明。\n' +
+        'API key 不要放在 CLI 參數或提交到 Git。'
+    );
+  }
+
+  return {
+    url: url.replace(/\/+$/, ''),
+    apiKey,
+  };
+}

package/src/redmine/git-evidence.js

@@ -0,0 +1,186 @@
+import { execFileSync } from 'child_process';
+import { GitOperations } from '../core/git-operations.js';
+
+/**
+ * 解析 release branch 名稱中的版本 token
+ * @param {string} branchName
+ * @returns {{year: number, cycle: number, patch: number, cadence: string} | null}
+ */
+export function parseReleaseVersion(branchName) {
+  const normalized = branchName.replace(/^origin\//, '');
+  const semverMatch = normalized.match(/^release-(\d+)\.(\d+)\.(\d+)$/i);
+  if (semverMatch) {
+    return {
+      major: Number(semverMatch[1]),
+      minor: Number(semverMatch[2]),
+      patch: Number(semverMatch[3]),
+      cadence: 'semver',
+    };
+  }
+
+  const match = normalized.match(/^release-(\d{4})-([mw])(\d+)(?:\.(\d+))?$/i);
+  if (!match) return null;
+
+  return {
+    year: Number(match[1]),
+    cycle: Number(match[3]),
+    patch: Number(match[4] || 0),
+    cadence: match[2].toLowerCase(),
+  };
+}
+
+/**
+ * 依版本號選擇最新 release branch
+ * @param {string[]} branches
+ * @returns {string | null}
+ */
+export function selectLatestReleaseBranch(branches = []) {
+  const normalized = branches
+    .map(branch => branch.replace(/^origin\//, ''))
+    .filter(branch => branch.startsWith('release-'));
+  const monthly = normalized.filter(branch => parseReleaseVersion(branch)?.cadence === 'm');
+  const weekly = normalized.filter(branch => parseReleaseVersion(branch)?.cadence === 'w');
+  const semver = normalized.filter(branch => parseReleaseVersion(branch)?.cadence === 'semver');
+  const candidates = monthly.length > 0 ? monthly : weekly.length > 0 ? weekly : semver;
+
+  return candidates
+    .filter(branch => parseReleaseVersion(branch))
+    .sort((left, right) => {
+      const leftVersion = parseReleaseVersion(left);
+      const rightVersion = parseReleaseVersion(right);
+      if (leftVersion.cadence === 'semver' && rightVersion.cadence === 'semver') {
+        return (
+          rightVersion.major - leftVersion.major ||
+          rightVersion.minor - leftVersion.minor ||
+          rightVersion.patch - leftVersion.patch
+        );
+      }
+      return (
+        rightVersion.year - leftVersion.year ||
+        rightVersion.cycle - leftVersion.cycle ||
+        rightVersion.patch - leftVersion.patch
+      );
+    })[0] || null;
+}
+
+/**
+ * 從 GitHub remote 解析 repository
+ * @param {string} remoteUrl
+ * @returns {{owner: string, repo: string} | null}
+ */
+export function parseGitHubRemote(remoteUrl = '') {
+  const match = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+function run(command, args, execImpl = execFileSync) {
+  return execImpl(command, args, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+
+function getRemoteBranches(execImpl) {
+  const remoteUrl = run('git', ['remote', 'get-url', 'origin'], execImpl);
+  const repository = parseGitHubRemote(remoteUrl);
+  if (!repository) throw new Error('無法從 origin remote 解析 GitHub repository');
+
+  const output = run(
+    'gh',
+    ['api', `repos/${repository.owner}/${repository.repo}/branches`, '--paginate', '--jq', '.[].name'],
+    execImpl
+  );
+  return output.split('\n').filter(Boolean);
+}
+
+function getLocalRemoteBranches(execImpl) {
+  try {
+    execImpl('git', ['fetch', '--prune', 'origin'], { stdio: 'ignore' });
+  } catch {
+    // 使用本機已快取的 remote branches
+  }
+
+  return run('git', ['branch', '-r'], execImpl)
+    .split('\n')
+    .map(branch => branch.trim().replace(/^origin\//, ''))
+    .filter(Boolean);
+}
+
+/**
+ * 解析要比較的 base branch
+ * @param {{baseBranch?: string, execImpl?: Function}} options
+ * @returns {{branch: string, source: string}}
+ */
+export function resolveBaseBranch({ baseBranch, execImpl = execFileSync } = {}) {
+  if (baseBranch) return { branch: baseBranch.replace(/^origin\//, ''), source: 'explicit' };
+
+  let branches;
+  try {
+    branches = getRemoteBranches(execImpl);
+  } catch {
+    branches = getLocalRemoteBranches(execImpl);
+  }
+
+  const branch = selectLatestReleaseBranch(branches);
+  if (!branch) {
+    throw new Error('找不到可用的 release branch，請使用 --base <branch> 指定比較基準');
+  }
+  return { branch, source: 'latest-versioned-release' };
+}
+
+/**
+ * 收集目前 branch 相對於 base 的 Git 變更
+ * @param {{baseBranch?: string, headBranch?: string, git?: typeof GitOperations}} options
+ * @returns {object}
+ */
+export function collectGitEvidence({ baseBranch, headBranch, git = GitOperations, execImpl = execFileSync } = {}) {
+  const resolvedBase = resolveBaseBranch({ baseBranch, execImpl });
+  const head = headBranch || git.getCurrentBranch();
+  let repository = null;
+  try {
+    repository = parseGitHubRemote(run('git', ['remote', 'get-url', 'origin'], execImpl));
+  } catch {
+    // 本地分析仍可使用 Git evidence，不要求 repository metadata
+  }
+
+  return {
+    currentBranch: head,
+    baseBranch: resolvedBase.branch,
+    baseSource: resolvedBase.source,
+    repository: repository ? `${repository.owner}/${repository.repo}` : null,
+    commits: git.getCommits(resolvedBase.branch, head, { useRemoteHead: false }),
+    changedFiles: git.getChangedFiles(resolvedBase.branch, head, false),
+    diff: git.truncateDiff(git.getDiff(resolvedBase.branch, head, false)),
+    stats: git.getChangeStats(resolvedBase.branch, head, false),
+  };
+}
+
+/**
+ * 取得可選的 GitHub PR evidence
+ * @param {number|string} pullRequestNumber
+ * @param {Function} execImpl
+ * @returns {object}
+ */
+export function collectPullRequestEvidence(pullRequestNumber, execImpl = execFileSync) {
+  const raw = run(
+    'gh',
+    [
+      'pr',
+      'view',
+      String(pullRequestNumber),
+      '--json',
+      'title,body,url,state,mergedAt,commits,files',
+    ],
+    execImpl
+  );
+  const pullRequest = JSON.parse(raw);
+
+  return {
+    number: Number(pullRequestNumber),
+    title: pullRequest.title || '',
+    body: pullRequest.body || '',
+    url: pullRequest.url || '',
+    state: pullRequest.state || '',
+    mergedAt: pullRequest.mergedAt || null,
+    commits: pullRequest.commits || [],
+    changedFiles: pullRequest.files || [],
+  };
+}

package/src/redmine/issue-analyzer.js

@@ -0,0 +1,110 @@
+import { AIClient } from '../core/ai-client.js';
+
+const ANALYSIS_FIELDS = [
+  'developmentSummary',
+  'codeChanges',
+  'apiChanges',
+  'technicalDetails',
+  'modifiedFiles',
+  'verification',
+  'unresolvedItems',
+  'evidence',
+];
+
+function asStringArray(value) {
+  return Array.isArray(value) ? value.filter(item => typeof item === 'string') : [];
+}
+
+function filterEvidenceBackedClaims(result, evidence = {}) {
+  const source = JSON.stringify(evidence);
+  const evidenceRefs = result.evidence.filter(
+    reference => reference.trim() && source.includes(reference)
+  );
+  const changedFiles = new Set(evidence.changedFiles || []);
+
+  return {
+    ...result,
+    evidence: evidenceRefs,
+    apiChanges: evidenceRefs.length > 0 ? result.apiChanges : [],
+    verification: evidenceRefs.length > 0 ? result.verification : [],
+    modifiedFiles: result.modifiedFiles.filter(file => changedFiles.has(file)),
+  };
+}
+
+/**
+ * 建立單一 Redmine Issue 的 AI 分析 prompt
+ * @param {{issue: object, evidence: object}} input
+ * @returns {string}
+ */
+export function buildIssueAnalysisPrompt({ issue, evidence }) {
+  return `你是資深軟體工程師，請針對指定的 Redmine Issue 分析目前的實際程式變更。
+
+重要規則：
+- 這次只分析指定的 Issue #${issue.id}，不得把結果指派給其他 Issue。
+- 只能描述下方 Issue、Git commits、changed files、diff 或 PR evidence 中有明確證據的內容。
+- 不得捏造 API endpoint、參數、檔案、function、class、測試或部署結果。
+- 沒有明確測試或驗證證據時，verification 必須是空陣列。
+- 沒有可靠 API 變更證據時，apiChanges 必須是空陣列。
+- 若能從實際流程推導出可靠的複製流程，才產生 flowchart；否則為 null。
+- 不要產生 suggestedStatus、coverage 或 confidence，也不要決定 Redmine status。
+
+## 指定 Redmine Issue
+${JSON.stringify(issue, null, 2)}
+
+## 共用 Git / PR Evidence
+${JSON.stringify(evidence, null, 2)}
+
+請只回傳 JSON，不要使用 Markdown code fence，格式如下：
+{
+  "issueId": ${issue.id},
+  "developmentSummary": [],
+  "codeChanges": [],
+  "apiChanges": [],
+  "technicalDetails": [],
+  "modifiedFiles": [],
+  "verification": [],
+  "flowchart": null,
+  "unresolvedItems": [],
+  "evidence": []
+}
+
+各欄位都必須是字串陣列，flowchart 必須是合法 Mermaid source 字串或 null。`;
+}
+
+/**
+ * 解析並正規化 AI 分析結果
+ * @param {string} content
+ * @param {number|string} issueId
+ * @returns {object}
+ */
+export function parseIssueAnalysis(content, issueId) {
+  const parsed = AIClient.parseJSON(content);
+  const result = { issueId };
+
+  for (const field of ANALYSIS_FIELDS) {
+    result[field] = asStringArray(parsed[field]);
+  }
+
+  result.flowchart = typeof parsed.flowchart === 'string' && parsed.flowchart.trim()
+    ? parsed.flowchart.trim()
+    : null;
+
+  return result;
+}
+
+/**
+ * 針對單一 Issue 呼叫 AI
+ * @param {{issue: object, evidence: object, aiClient?: typeof AIClient, model?: string, maxRetries?: number}} input
+ * @returns {Promise<object>}
+ */
+export async function analyzeIssue({
+  issue,
+  evidence,
+  aiClient = AIClient,
+  model = 'claude-haiku-4.5',
+  maxRetries = 3,
+}) {
+  const prompt = buildIssueAnalysisPrompt({ issue, evidence });
+  const content = await aiClient.sendAndWait(prompt, model, maxRetries);
+  return filterEvidenceBackedClaims(parseIssueAnalysis(content, issue.id), evidence);
+}

package/src/redmine/issue-sync.js

@@ -0,0 +1,151 @@
+import { analyzeIssue as defaultAnalyzeIssue } from './issue-analyzer.js';
+import { createHash } from 'crypto';
+import {
+  formatRedmineNote,
+  formatRedminePreview,
+  selectIssueStatus,
+} from './redmine-formatters.js';
+
+function uniqueIssueIds(issueIds = []) {
+  return [...new Set(issueIds.map(id => Number(id)).filter(Number.isInteger))];
+}
+
+/**
+ * 建立單一 Issue 的同步識別
+ * @param {{issueId: number|string, evidence: object, pullRequest?: object|null}}
+ * @returns {string}
+ */
+export function createSyncId({ issueId, evidence = {}, pullRequest = null }) {
+  const identity = pullRequest?.number
+    ? `pr-${pullRequest.url || pullRequest.number}`
+    : `${evidence.repository || 'local'}-${evidence.currentBranch || 'branch'}-${createHash('sha256')
+      .update(`${evidence.commits || ''}\n${evidence.diff || ''}`)
+      .digest('hex')
+      .slice(0, 12)}`;
+  return `redmine-sync:${issueId}:${identity}`;
+}
+
+/**
+ * 產生一份待審核的 Redmine 更新草稿
+ * @param {object} options
+ * @returns {Promise<object>}
+ */
+export async function generateRedmineDraft({
+  issueIds,
+  client,
+  evidence,
+  pullRequest = null,
+  analyzeIssueFn = defaultAnalyzeIssue,
+  selectStatusFn = selectIssueStatus,
+  model,
+  maxRetries,
+}) {
+  const drafts = [];
+  const failures = [];
+  for (const issueId of uniqueIssueIds(issueIds)) {
+    try {
+      const issue = await client.getIssue(issueId);
+      const analysis = await analyzeIssueFn({ issue, evidence: { ...evidence, pullRequest }, model, maxRetries });
+      const selectedStatus = await selectStatusFn(issue, { client });
+      const syncId = createSyncId({ issueId, evidence, pullRequest });
+      const note = formatRedmineNote({
+        issueId,
+        analysis,
+        evidence,
+        pullRequest,
+        syncId,
+      });
+
+      drafts.push({
+        issueId,
+        subject: issue.subject,
+        originalStatusId: issue.status?.id ?? null,
+        originalStatusName: issue.status?.name || '',
+        originalDescription: issue.description,
+        statusId: selectedStatus.statusId,
+        statusName: selectedStatus.statusName,
+        analysis,
+        note,
+        syncId,
+      });
+    } catch (error) {
+      failures.push({ issueId, error: error.message });
+    }
+  }
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    evidence,
+    pullRequest,
+    drafts,
+    failures,
+  };
+}
+
+function hasSyncId(issue, syncId) {
+  const journals = issue.raw?.journals || [];
+  return journals.some(journal => journal.notes?.includes(syncId));
+}
+
+/**
+ * 套用已審核的 Redmine 更新草稿
+ * @param {{draft: object, client: object, force?: boolean}} options
+ * @returns {Promise<Array<object>>}
+ */
+export async function applyRedmineDraft({ draft, client, force = false }) {
+  if (!draft || !Array.isArray(draft.drafts)) {
+    throw new Error('無效的 Redmine draft');
+  }
+
+  const results = [];
+  for (const item of draft.drafts) {
+    try {
+      const current = await client.getIssue(item.issueId, { include: 'allowed_statuses,journals' });
+      if (!force && hasSyncId(current, item.syncId)) {
+        results.push({ issueId: item.issueId, skipped: true, reason: 'duplicate' });
+        continue;
+      }
+
+      const statusChanged = item.originalStatusId !== null && current.status?.id !== item.originalStatusId;
+      const descriptionChanged = current.description !== item.originalDescription;
+      if (!force && (statusChanged || descriptionChanged)) {
+        results.push({ issueId: item.issueId, skipped: true, reason: 'conflict' });
+        continue;
+      }
+
+      await client.updateIssue(item.issueId, {
+        statusId: item.statusId,
+        notes: item.note,
+      });
+      results.push({ issueId: item.issueId, applied: true });
+    } catch (error) {
+      results.push({ issueId: item.issueId, applied: false, error: error.message });
+    }
+  }
+  return results;
+}
+
+/**
+ * 將 draft 序列化為可保存的 JSON
+ * @param {object} draft
+ * @returns {string}
+ */
+export function serializeDraft(draft) {
+  return `${JSON.stringify(draft, null, 2)}\n`;
+}
+
+/**
+ * 解析 draft JSON
+ * @param {string} content
+ * @returns {object}
+ */
+export function parseDraft(content) {
+  const draft = JSON.parse(content);
+  if (draft.version !== 1 || !Array.isArray(draft.drafts)) {
+    throw new Error('Redmine draft 格式不受支援');
+  }
+  return draft;
+}
+
+export { formatRedminePreview };

package/src/redmine/redmine-client.js

@@ -0,0 +1,147 @@
+/**
+ * Redmine REST API 客戶端
+ */
+
+/**
+ * @typedef {{id: number, name: string}} RedmineStatus
+ */
+
+export class RedmineAPIError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} status
+   * @param {string} method
+   * @param {string} path
+   */
+  constructor(message, status, method, path) {
+    super(message);
+    this.name = 'RedmineAPIError';
+    this.status = status;
+    this.method = method;
+    this.path = path;
+  }
+}
+
+/**
+ * 將 Redmine Issue response 轉成命令內部使用的資料
+ * @param {object} rawIssue
+ * @returns {object}
+ */
+export function normalizeIssue(rawIssue = {}) {
+  return {
+    id: rawIssue.id,
+    subject: rawIssue.subject || '',
+    description: rawIssue.description || '',
+    status: rawIssue.status || null,
+    tracker: rawIssue.tracker || 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,
+    assignedTo: rawIssue.assigned_to || rawIssue.assignedTo || null,
+    raw: rawIssue,
+  };
+}
+
+export class RedmineClient {
+  /**
+   * @param {{url: string, apiKey: string, fetchImpl?: typeof fetch}} config
+   */
+  constructor({ url, apiKey, fetchImpl = globalThis.fetch }) {
+    if (!url || !apiKey) {
+      throw new Error('RedmineClient 需要 url 與 apiKey');
+    }
+    if (typeof fetchImpl !== 'function') {
+      throw new Error('目前 Node.js 環境沒有可用的 fetch');
+    }
+
+    this.baseUrl = url.replace(/\/+$/, '');
+    this.apiKey = apiKey;
+    this.fetchImpl = fetchImpl;
+  }
+
+  /**
+   * @param {string} path
+   * @param {RequestInit & {json?: object}} options
+   * @returns {Promise<object>}
+   */
+  async request(path, options = {}) {
+    const { json, headers = {}, ...requestOptions } = options;
+    const requestHeaders = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Redmine-API-Key': this.apiKey,
+      ...headers,
+    };
+
+    if (json !== undefined) {
+      requestHeaders['Content-Type'] = 'application/json';
+      requestOptions.body = JSON.stringify(json);
+    }
+
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      ...requestOptions,
+      headers: requestHeaders,
+    });
+    const responseText = await response.text();
+    let responseData = null;
+
+    if (responseText) {
+      try {
+        responseData = JSON.parse(responseText);
+      } catch {
+        responseData = null;
+      }
+    }
+
+    if (!response.ok) {
+      const apiErrors = Array.isArray(responseData?.errors)
+        ? `：${responseData.errors.join('、').replaceAll(this.apiKey, '[REDACTED]')}`
+        : '';
+      throw new RedmineAPIError(
+        `Redmine API 請求失敗 (${response.status})${apiErrors}`,
+        response.status,
+        requestOptions.method || 'GET',
+        path
+      );
+    }
+
+    return responseData || {};
+  }
+
+  /**
+   * @param {number|string} issueId
+   * @returns {Promise<object>}
+   */
+  async getIssue(issueId, { include = 'allowed_statuses' } = {}) {
+    const query = include ? `?include=${encodeURIComponent(include)}` : '';
+    const data = await this.request(
+      `/issues/${encodeURIComponent(issueId)}.json${query}`
+    );
+    return normalizeIssue(data.issue || data);
+  }
+
+  /**
+   * @returns {Promise<RedmineStatus[]>}
+   */
+  async getIssueStatuses() {
+    const data = await this.request('/issue_statuses.json');
+    return data.issue_statuses || [];
+  }
+
+  /**
+   * @param {number|string} issueId
+   * @param {{statusId?: number, notes?: string}} update
+   * @returns {Promise<object>}
+   */
+  async updateIssue(issueId, { statusId, notes }) {
+    const issue = {};
+    if (statusId !== undefined && statusId !== null) issue.status_id = statusId;
+    if (notes) issue.notes = notes;
+
+    return this.request(`/issues/${encodeURIComponent(issueId)}.json`, {
+      method: 'PUT',
+      json: { issue },
+    });
+  }
+}

package/src/redmine/redmine-formatters.js

@@ -0,0 +1,151 @@
+import inquirer from 'inquirer';
+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`;
+}
+
+/**
+ * 將 Mermaid source 包成 Redmine macro
+ * @param {string|null} source
+ * @returns {string}
+ */
+export function formatMermaid(source) {
+  if (typeof source !== 'string' || !source.trim()) return '';
+
+  let cleanSource = source.trim()
+    .replace(/^```mermaid\s*/i, '')
+    .replace(/^```\s*/, '')
+    .replace(/\s*```$/, '')
+    .trim();
+
+  if (cleanSource.startsWith('{{mermaid')) {
+    cleanSource = cleanSource
+      .replace(/^\{\{mermaid\s*/, '')
+      .replace(/\s*\}\}$/, '')
+      .trim();
+  }
+
+  if (
+    cleanSource.includes('{{mermaid') ||
+    cleanSource.includes('}}') ||
+    !/^(flowchart|graph|sequenceDiagram|stateDiagram|classDiagram|erDiagram|journey)\b/m.test(cleanSource)
+  ) {
+    return '';
+  }
+
+  return `{{mermaid\n${cleanSource}\n}}`;
+}
+
+/**
+ * 格式化 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 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 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 || '—'}`,
+      ''
+    );
+  }
+
+  if (pullRequest) {
+    sections.push(
+      `GitHub PR：${pullRequest.url || `#${pullRequest.number}`}`,
+      `PR 狀態：${pullRequest.state || '—'}${pullRequest.mergedAt ? `（合併於 ${pullRequest.mergedAt}）` : ''}`,
+      ''
+    );
+  }
+
+  if (analysis.evidence?.length) {
+    sections.push(`分析依據：${analysis.evidence.join('、')}`, '');
+  }
+
+  if (syncId) sections.push(`<!-- ${syncId} issue:${issueId} -->`);
+  return sections.filter((section, index) => section || index === 1).join('\n').trim();
+}
+
+/**
+ * 選取 Issue 可用的狀態清單
+ * @param {object} issue
+ * @param {Array<object>} fallbackStatuses
+ * @returns {Array<object>}
+ */
+export function getAvailableStatuses(issue, fallbackStatuses = []) {
+  return issue.allowedStatuses?.length ? issue.allowedStatuses : fallbackStatuses;
+}
+
+/**
+ * 建立 inquirer 狀態選項
+ * @param {Array<object>} statuses
+ * @returns {Array<{name: string, value: number}>}
+ */
+export function createStatusChoices(statuses = []) {
+  return statuses
+    .filter(status => status?.id !== undefined && status?.name)
+    .map(status => ({ name: status.name, value: status.id }));
+}
+
+/**
+ * 互動選擇 Issue 更新後狀態
+ * @param {object} issue
+ * @param {{client: object, prompt?: Function}} options
+ * @returns {Promise<{statusId: number, statusName: string}>}
+ */
+export async function selectIssueStatus(issue, { client, prompt = inquirer.prompt } = {}) {
+  const fallbackStatuses = issue.allowedStatuses?.length ? [] : await client.getIssueStatuses();
+  const statuses = getAvailableStatuses(issue, fallbackStatuses);
+  const choices = createStatusChoices(statuses);
+  if (choices.length === 0) throw new Error(`Issue #${issue.id} 沒有可用的 Redmine 狀態`);
+
+  const answer = await prompt([
+    {
+      type: 'list',
+      name: 'statusId',
+      message: `Issue #${issue.id}：選擇更新後狀態`,
+      choices,
+    },
+  ]);
+  const selected = statuses.find(status => status.id === answer.statusId);
+  return { statusId: answer.statusId, statusName: selected?.name || String(answer.statusId) };
+}
+
+/**
+ * 產生有色 terminal preview
+ * @param {Array<object>} drafts
+ * @returns {string}
+ */
+export function formatRedminePreview(drafts = []) {
+  const lines = [chalk.bold.cyan('═'.repeat(72)), chalk.bold('Redmine 更新預覽'), chalk.bold.cyan('═'.repeat(72)), ''];
+
+  for (const draft of drafts) {
+    lines.push(
+      chalk.bold.cyan(`Issue #${draft.issueId}`),
+      `${chalk.dim('目前狀態：')} ${draft.currentStatusName || draft.originalStatusName || '—'}`,
+      `${chalk.green('更新狀態：')} ${draft.statusName || '未選擇'}`,
+      '',
+      draft.note,
+      chalk.dim('─'.repeat(72)),
+      ''
+    );
+  }
+
+  return lines.join('\n').trim();
+}

package/src/utils/cli-helpers.js

@@ -4,6 +4,7 @@
  */
 
 import { handleError } from './helpers.js';
+import { Option } from 'commander';
 
 /**
  * 註冊一個 CLI 命令，統一包裝 try/catch 與退出碼
@@ -17,6 +18,13 @@ export function registerCommand(program, name, description, options = [], action
   const command = program.command(name).description(description);
 
   for (const option of options) {
+    if (option.argParser) {
+      const commandOption = new Option(option.flags, option.description).argParser(option.argParser);
+      if (option.defaultValue !== undefined) commandOption.default(option.defaultValue);
+      command.addOption(commandOption);
+      continue;
+    }
+
     if (option.defaultValue !== undefined) {
       command.option(option.flags, option.description, option.defaultValue);
     } else {