ai-git-tools 2.1.8 → 2.1.10

package/README.md

@@ -372,6 +372,33 @@ Issue 的基本責任分工如下：`description` 保存原始需求與未來其
 
 同一個 Issue 若已經有先前的 notes，後續再次執行更新仍會新增一筆新的 Redmine journal，不會因為已有 notes 而略過；只有 Issue 的需求內容或狀態在產生草稿後被其他人修改時，才會停下來要求重新確認。
 
+AI 產出的 notes 會固定整理成以下架構：
+
+```markdown
+## 開發內容
+
+### 需求說明
+一句話說明這次為什麼修改。
+
+### 實作內容
+- 實際完成事項
+- 實際完成事項
+- 實際完成事項
+
+### 行為規則
+| 情境 | 行為 |
+|---|---|
+| ... | ... |
+
+### 影響範圍
+受影響的功能、API、頁面或模組。
+
+### 待確認
+- [ ] AI 無法確認的項目
+```
+
+實作內容最多顯示 6 個項目；沒有待確認事項時不會建立空的 `待確認` 區塊。Git 與流程圖區塊會維持既有格式。
+
 ## ⚙️ 配置
 
 配置檔案範例（\`.ai-git-config.js\`）：

package/bin/cli.js

@@ -99,7 +99,7 @@ registerCommand(program, 'redmine-update', '分析並更新 Redmine Issue 的開
   { flags: '--output <file>', description: '保存 preview 草稿 JSON' },
   { flags: '--apply', description: '套用已審核的草稿' },
   { flags: '--from <file>', description: '指定要套用的 preview 草稿 JSON' },
-  { flags: '--force', description: '強制略過衝突與重複同步檢查' },
+  { flags: '--force', description: '強制略過 Issue 狀態或內容衝突檢查' },
 ], redmineUpdateCommand);
 
 program.parse();

package/package.json

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

package/src/redmine/issue-analyzer.js

@@ -3,6 +3,8 @@ import { AIClient } from '../core/ai-client.js';
 const ANALYSIS_FIELDS = [
   'developmentSummary',
   'requirementDescription',
+  'implementationDetails',
+  'impactScope',
   'codeChanges',
   'apiChanges',
   'technicalDetails',
@@ -82,11 +84,12 @@ export function buildIssueAnalysisPrompt({ issue, evidence }) {
 - 這次只分析指定的 Issue #${issue.id}，不得把結果指派給其他 Issue。
 - 只能描述下方 Issue、Git commits、changed files、diff 或 PR evidence 中有明確證據的內容。
 - 不得捏造 API endpoint、參數、檔案、function、class、測試或部署結果。
+- requirementDescription 必須是一句話，說明這次為什麼修改。
+- implementationDetails 必須整理 3～6 個實際完成事項。
+- behaviorRules 必須使用 scenario/behavior 物件描述不同情境的行為。
+- impactScope 必須描述受到影響的功能、API、頁面或模組。
+- 若能從實際流程推導出可靠的流程，才產生 flowcharts；每張流程圖必須有穩定 id、title、source 與 evidence。
 - 沒有明確測試或驗證證據時，verification 必須是空陣列。
-- 沒有可靠 API 變更證據時，apiChanges 必須是空陣列。
-- requirementDescription 應整理指定 Issue 的需求重點；behaviorRules 使用 scenario/behavior 物件陣列。
-- 若能從實際流程推導出可靠的複製流程，才產生 flowcharts；否則為空陣列。每張流程圖必須有穩定、描述用途的 id，source 必須以 graph TD 開始，不要加入 Mermaid wrapper 或 code fence。
-- developmentSummary、codeChanges、apiChanges、technicalDetails 中的程式路徑、API path、function 與 class 使用雙反引號標示；需要多行程式片段時使用 code block。
 - 不要產生 suggestedStatus、coverage 或 confidence，也不要決定 Redmine status。
 
 ## 指定 Redmine Issue
@@ -100,6 +103,8 @@ ${JSON.stringify(evidence, null, 2)}
   "issueId": ${issue.id},
   "developmentSummary": [],
   "requirementDescription": "",
+  "implementationDetails": [],
+  "impactScope": "",
   "behaviorRules": [],
   "codeChanges": [],
   "apiChanges": [],
@@ -110,8 +115,7 @@ ${JSON.stringify(evidence, null, 2)}
   "unresolvedItems": [],
   "evidence": []
 }
-
-developmentSummary、codeChanges、apiChanges、technicalDetails、modifiedFiles、verification、unresolvedItems 與 evidence 必須是字串陣列；requirementDescription 必須是字串；behaviorRules 必須是包含 scenario 與 behavior 字串的物件陣列；flowcharts 必須是包含 id、title、source 與 evidence 的物件陣列。`;
+requirementDescription 與 impactScope 必須是字串；implementationDetails 必須是 3～6 個字串的陣列；behaviorRules 必須是包含 scenario 與 behavior 字串的物件陣列；flowcharts 必須是包含 id、title、source 與 evidence 的物件陣列；其它清單欄位必須是字串陣列。`;
 }
 
 /**
@@ -125,7 +129,7 @@ export function parseIssueAnalysis(content, issueId) {
   const result = { issueId };
 
   for (const field of ANALYSIS_FIELDS) {
-    result[field] = field === 'requirementDescription'
+    result[field] = field === 'requirementDescription' || field === 'impactScope'
       ? (typeof parsed[field] === 'string' ? parsed[field].trim() : '')
       : asStringArray(parsed[field]);
   }

package/src/redmine/issue-sync.js

@@ -137,7 +137,7 @@ export async function applyRedmineDraft({ draft, client, force = false, onProgre
   for (const [index, item] of draft.drafts.entries()) {
     try {
       onProgress({ phase: 'apply-issue', index: index + 1, total: draft.drafts.length, issueId: item.issueId });
-      const current = await client.getIssue(item.issueId, { include: 'allowed_statuses,journals' });
+      const current = await client.getIssue(item.issueId, { include: 'allowed_statuses' });
 
       const statusChanged = item.originalStatusId !== null && current.status?.id !== item.originalStatusId;
       const descriptionChanged = current.description !== item.originalDescription;

package/src/redmine/redmine-formatters.js

@@ -11,6 +11,23 @@ function paragraphSection(title, content) {
   return `### ${title}\n\n${content}\n`;
 }
 
+function formatRequirement(content) {
+  if (!content) return '';
+  return content.replace(/\s+/g, ' ').trim();
+}
+
+function getImplementationDetails(analysis = {}) {
+  if (analysis.implementationDetails?.length) {
+    return analysis.implementationDetails.slice(0, 6);
+  }
+
+  return [
+    ...(analysis.codeChanges || []),
+    ...(analysis.apiChanges || []),
+    ...(analysis.technicalDetails || []),
+  ].slice(0, 6);
+}
+
 function formatBehaviorRules(rules = []) {
   if (!Array.isArray(rules) || rules.length === 0) return '';
   const rows = rules
@@ -148,59 +165,50 @@ export function formatRedmineDescription(description = '', source = null) {
 
 /**
  * 格式化 Redmine Issue note
- * @param {{issueId: number|string, analysis: object, evidence: object, pullRequest?: object|null, syncId?: string}} input
+ * @param {{issue?: object, analysis?: object, evidence?: object, pullRequest?: object|null}} input
  * @returns {string}
  */
 export function formatRedmineNote({ issue = {}, analysis = {}, evidence = {}, pullRequest = null }) {
   const sections = ['## 開發內容', ''];
-  const development = Array.isArray(analysis.developmentSummary)
-    ? analysis.developmentSummary.join('\n\n')
-    : analysis.developmentSummary || '';
-  const requirementDescription = analysis.requirementDescription || issue.description || '';
-  const behaviorRules = formatBehaviorRules(analysis.behaviorRules);
-  const codeChanges = bulletSection('程式修改重點', analysis.codeChanges);
-  const apiChanges = bulletSection('API 變更', analysis.apiChanges);
-  const technicalDetails = bulletSection('重要技術細節', analysis.technicalDetails);
-  const modifiedFiles = bulletSection(
-    '修改檔案',
-    analysis.modifiedFiles?.length
-      ? analysis.modifiedFiles.map(file => `\`\`${file}\`\``)
-      : evidence.changedFiles?.map(file => `\`\`${file}\`\``)
+  const requirementDescription = formatRequirement(
+    analysis.requirementDescription || analysis.developmentSummary?.[0] || issue.description || ''
   );
-  const verification = bulletSection('驗證結果', analysis.verification);
+  const implementationDetails = getImplementationDetails(analysis);
+  const behaviorRules = formatBehaviorRules(analysis.behaviorRules);
+  const implementation = bulletSection('實作內容', implementationDetails);
+  const impactScope = paragraphSection('影響範圍', analysis.impactScope);
   const unresolved = analysis.unresolvedItems?.length
     ? `### 待確認\n${analysis.unresolvedItems.map(item => `- [ ] ${item}`).join('\n')}\n`
     : '';
   const flowcharts = formatFlowcharts(analysis.flowcharts);
 
   sections.push(
-    development,
     paragraphSection('需求說明', requirementDescription),
+    implementation,
     behaviorRules,
-    modifiedFiles,
-    codeChanges,
-    apiChanges,
-    technicalDetails,
-    flowcharts,
-    verification
+    impactScope,
+    unresolved,
+    flowcharts
   );
-  sections.push(unresolved);
 
   if (evidence.currentBranch || evidence.baseBranch || pullRequest) {
     const branch = evidence.currentBranch || '—';
-    const branchUrl = evidence.repository
+    const branchUrl = evidence.repository && branch !== '—'
       ? `https://github.com/${evidence.repository}/tree/${encodeURI(branch)}`
       : '';
+    const base = evidence.baseBranch || '—';
+    const baseUrl = evidence.repository && base !== '—'
+      ? `https://github.com/${evidence.repository}/tree/${encodeURI(base)}`
+      : '';
     const gitLines = [
       '### Git',
       '',
       `- Branch：${branchUrl ? `[${branch}](${branchUrl})` : `\`\`${branch}\`\``}`,
-      `- Base：${branchUrl ? `[${evidence.baseBranch || '—'}](https://github.com/${evidence.repository}/tree/${encodeURI(evidence.baseBranch || '')})` : evidence.baseBranch || '—'}`,
+      `- Base：${baseUrl ? `[${base}](${baseUrl})` : base}`,
     ];
     if (pullRequest) {
       gitLines.push(
-        `- PR：${pullRequest.url ? `[${pullRequest.url}](${pullRequest.url})` : `#${pullRequest.number}`}`,
-        `- PR 狀態：${pullRequest.state || '—'}${pullRequest.mergedAt ? `（合併於 ${pullRequest.mergedAt}）` : ''}`
+        `- PR：${pullRequest.url ? `[${pullRequest.url}](${pullRequest.url})` : `#${pullRequest.number}`}`
       );
     }
     sections.push(