refactor: Tool 操作名稱簡化統一、Handler 重命名對齊、Session 使用範圍保護、CI/CD 版本管理集中化、測試腳本增強

1. Tool 操作名稱簡化統一
   - 所有模組 Tool 操作名稱從冗長動詞改為簡潔慣用命名
   - Email：load → get、detect_format → detect
   - Excel：get_workbook_properties → get、set_workbook_properties → set、edit_sheet_properties → set_sheet、get_sheet_properties → get_sheet、get_sheet_info → sheet_info、export_range_image → export、get_page_breaks → list
   - PDF：get_details → details、get_info → info、get_stamps → list
   - PowerPoint：get_used → list、get_layouts → list、get_masters → list
   - Word：insert_field → add、get_fields → list、get_field_detail → get、edit_field → edit、delete_field → delete、add_form_field → add_form、edit_form_field → edit_form、delete_form_field → delete_form、get_form_fields → list_forms、get_footnotes → list、get_endnotes → list、insert_blank_page → add、get_revisions → list、get_textboxes → list、get_styles → list
   - 通用模式：get_xxx → get/list、insert_xxx → add、edit_xxx → edit/set
   - 所有 Tool XML 文件註解、Description 屬性同步更新
   - docs/tools.html 文檔同步更新

2. Handler 類別重命名對齊
   - LoadEmailCalendarHandler → GetEmailCalendarHandler
   - LoadEmailContactHandler → GetEmailContactHandler
   - LoadEmailFileHandler → GetEmailFileHandler
   - ExportRangeImageExcelHandler → ExportImageExcelHandler
   - GetExcelPageBreaksHandler → ListExcelPageBreaksHandler
   - EditSheetPropertiesHandler → SetSheetPropertiesHandler
   - GetPdfStampsHandler → ListPdfStampsHandler
   - GetUsedPptFontsHandler → ListPptFontsHandler
   - GetLayoutsHandler → ListLayoutsHandler
   - GetMastersHandler → ListMastersHandler
   - InsertFieldWordHandler → AddFieldWordHandler
   - GetFieldsWordHandler → ListFieldsWordHandler
   - GetFormFieldsWordHandler → ListFormFieldsWordHandler
   - GetWordEndnotesHandler → ListWordEndnotesHandler
   - GetWordFootnotesHandler → ListWordFootnotesHandler
   - InsertBlankPageWordHandler → AddBlankPageWordHandler
   - GetRevisionsHandler → ListRevisionsHandler
   - GetTextboxesWordHandler → ListTextboxesWordHandler
   - GetWordStylesHandler → ListWordStylesHandler
   - 對應測試類別同步重命名（19 組 Handler + Tests）

3. Session 使用範圍保護機制
   - DocumentSession.cs：新增 _activeUsers 計數器追蹤活躍使用者數量
   - DocumentSession.cs：新增 AcquireUsage() 方法回傳 IDisposable 使用範圍
   - DocumentSession.cs：新增 HasActiveUsers 屬性判斷是否有進行中操作
   - DocumentSession.cs：新增 UsageScope 內部類別管理使用者計數生命週期
   - DocumentSessionManager.cs：閒置清理邏輯加入 HasActiveUsers 檢查，防止操作進行中被清除
   - DocumentContext.cs：持有 UsageScope 並在 Dispose 時釋放

4. CI/CD 版本管理集中化
   - build-multi-platform.yml：新增 prepare Job 獨立計算版本號
   - build-multi-platform.yml：build 與 create-release Job 改用 needs.prepare.outputs 取得版本資訊
   - 消除重複版本計算邏輯，提升可維護性

5. 程式碼品質改善
   - McpServerBuilderExtensions.cs：靜態方法呼叫改為擴充方法鏈式呼叫
   - FontHelper.cs：底線映射擴充支援布林字串（"true"/"false"）
   - WordListHelper.cs：操作名稱訊息對齊新命名規範

6. 測試腳本增強
   - test.ps1：新增 -LogFile 參數支援匯出失敗測試詳細資訊
   - test.ps1：解析 TRX 測試結果 XML 提取測試名稱、錯誤訊息與堆疊追蹤

Author: JaJa

.github/workflows/build-multi-platform.yml

@@ -30,8 +30,42 @@ on:
   workflow_dispatch:
 
 jobs:
+  prepare:
+    name: Calculate Next Version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.next_version.outputs.version }}
+      tag: ${{ steps.next_version.outputs.tag }}
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Calculate next version
+      id: next_version
+      shell: bash
+      run: |
+        git fetch --prune --tags --force
+        latest_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v1.0.0")
+        version=${latest_tag#v}
+        IFS='.' read -r major minor patch <<< "$version"
+        # Increment patch version until finding one that doesn't exist
+        while true; do
+          patch=$((patch + 1))
+          candidate="v${major}.${minor}.${patch}"
+          if ! git rev-parse "$candidate" >/dev/null 2>&1; then
+            break
+          fi
+          echo "Version $candidate already exists, trying next..."
+        done
+        echo "version=${major}.${minor}.${patch}" >> $GITHUB_OUTPUT
+        echo "tag=v${major}.${minor}.${patch}" >> $GITHUB_OUTPUT
+        echo "Next version: ${major}.${minor}.${patch} (tag: v${major}.${minor}.${patch})"
+
   build:
     name: Build ${{ matrix.platform }}
+    needs: prepare
     runs-on: ${{ matrix.os }}
 
     strategy:
@@ -59,15 +93,6 @@ jobs:
       with:
         fetch-depth: 0
 
-    - name: Get version from Git tag
-      id: get_version
-      shell: bash
-      run: |
-        latest_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v1.0.0")
-        version=${latest_tag#v}
-        echo "version=$version" >> $GITHUB_OUTPUT
-        echo "Detected version: $version"
-    
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
@@ -111,7 +136,7 @@ jobs:
     - name: Build and publish
       run: ${{ matrix.script }}
       env:
-        VERSION: ${{ steps.get_version.outputs.version }}
+        VERSION: ${{ needs.prepare.outputs.version }}
 
     - name: Clean up license files from build output (Unix)
       if: runner.os != 'Windows'
@@ -156,7 +181,7 @@ jobs:
 
   create-release:
     name: Create Release
-    needs: build
+    needs: [prepare, build]
     runs-on: ubuntu-latest
     # Security: Only create releases for pushes to main/master branches, not for PRs
     if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
@@ -174,40 +199,7 @@ jobs:
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    
-    - name: Get latest version tag
-      id: get_version
-      shell: bash
-      run: |
-        # 確保獲取最新的 tag（包括遠程）
-        git fetch --prune --tags --force
-        latest_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "v1.0.0")
-        echo "latest_tag=$latest_tag" >> $GITHUB_OUTPUT
-        echo "Latest tag: $latest_tag"
-    
-    - name: Calculate next version
-      id: next_version
-      shell: bash
-      run: |
-        latest_tag="${{ steps.get_version.outputs.latest_tag }}"
-        # 移除 v 前綴
-        version=${latest_tag#v}
-        # 分割版本號
-        IFS='.' read -r major minor patch <<< "$version"
-        # 遞增補丁版本號，直到找到不存在的版本號
-        while true; do
-          patch=$((patch + 1))
-          candidate_version="v${major}.${minor}.${patch}"
-          # 檢查 tag 是否已存在
-          if ! git rev-parse "$candidate_version" >/dev/null 2>&1; then
-            next_version="$candidate_version"
-            break
-          fi
-          echo "Version $candidate_version already exists, trying next..."
-        done
-        echo "next_version=$next_version" >> $GITHUB_OUTPUT
-        echo "Next version: $next_version"
-    
+
     - name: Download all artifacts
       uses: actions/download-artifact@v4
       with:
@@ -248,7 +240,7 @@ jobs:
       env:
         GH_TOKEN: ${{ github.token }}
       run: |
-        tag_name="${{ steps.next_version.outputs.next_version }}"
+        tag_name="${{ needs.prepare.outputs.tag }}"
         release_notes=$(cat <<'EOF'
         Automated build from commit ${{ github.sha }}
 
@@ -322,7 +314,7 @@ jobs:
           exit 0
         fi
 
-        tag_name="${{ steps.next_version.outputs.next_version }}"
+        tag_name="${{ needs.prepare.outputs.tag }}"
         version="${tag_name#v}"
 
         # Calculate sha256 for macOS archives
@@ -376,7 +368,7 @@ jobs:
         fi
 
     outputs:
-      release_tag: ${{ steps.next_version.outputs.next_version }}
+      release_tag: ${{ needs.prepare.outputs.tag }}
 
   docker-build-and-push:
     name: Build and Push Docker Image

Core/McpServerBuilderExtensions.cs

@@ -103,7 +103,7 @@ public static IMcpServerBuilder WithFilteredToolsAndSchemas(
         ServerConfig serverConfig,
         SessionConfig sessionConfig)
     {
-        return WithFilteredToolsAndSchemas(builder, serverConfig, sessionConfig, new ExtensionConfig());
+        return builder.WithFilteredToolsAndSchemas(serverConfig, sessionConfig, new ExtensionConfig());
     }
 
     /// <summary>

Core/Session/DocumentContext.cs

@@ -33,6 +33,11 @@ public sealed class DocumentContext<T> : IDisposable
     /// </summary>
     private readonly DocumentSessionManager? _sessionManager;
 
+    /// <summary>
+    ///     Usage scope that prevents the session from being cleaned up during tool execution
+    /// </summary>
+    private readonly IDisposable? _usageScope;
+
     /// <summary>
     ///     Tracks whether this context has been disposed
     /// </summary>
@@ -47,15 +52,17 @@ public sealed class DocumentContext<T> : IDisposable
     /// <param name="path">Source file path (null for session mode)</param>
     /// <param name="ownsDocument">Whether this context owns and should dispose the document</param>
     /// <param name="identity">The requestor identity for session isolation</param>
+    /// <param name="usageScope">Usage scope to hold during the lifetime of this context (null for file mode)</param>
     private DocumentContext(T document, DocumentSessionManager? sessionManager, string? sessionId, string? path,
-        bool ownsDocument, SessionIdentity identity)
+        bool ownsDocument, SessionIdentity identity, IDisposable? usageScope = null)
     {
         Document = document;
         _sessionManager = sessionManager;
         _sessionId = sessionId;
         SourcePath = path;
         _ownsDocument = ownsDocument;
         _identity = identity;
+        _usageScope = usageScope;
     }
 
     /// <summary>
@@ -87,6 +94,7 @@ public void Dispose()
         if (_disposed) return;
         _disposed = true;
 
+        _usageScope?.Dispose();
         if (_ownsDocument && Document is IDisposable disposable) disposable.Dispose();
     }
 
@@ -119,8 +127,18 @@ public static DocumentContext<T> Create(
                 throw new InvalidOperationException(
                     "Session management is not enabled. Use --enable-sessions flag or provide a file path.");
 
-            var doc = sessionManager.GetDocument<T>(sessionId, identity);
-            return new DocumentContext<T>(doc, sessionManager, sessionId, null, false, identity);
+            var session = sessionManager.GetSession(sessionId, identity);
+            var usageScope = session.AcquireUsage();
+            try
+            {
+                var doc = session.GetDocument<T>();
+                return new DocumentContext<T>(doc, sessionManager, sessionId, null, false, identity, usageScope);
+            }
+            catch
+            {
+                usageScope.Dispose();
+                throw;
+            }
         }
 
         if (string.IsNullOrEmpty(path))

Core/Session/DocumentSession.cs

@@ -10,6 +10,11 @@ public sealed class DocumentSession : IDisposable
     /// </summary>
     private readonly SemaphoreSlim _lock = new(1, 1);
 
+    /// <summary>
+    ///     Tracks the number of active users currently holding a usage scope on this session
+    /// </summary>
+    private int _activeUsers;
+
     /// <summary>
     ///     Tracks whether this session has been disposed (0 = not disposed, 1 = disposed)
     /// </summary>
@@ -112,6 +117,11 @@ public DateTime LastAccessedAt
     /// </summary>
     public bool IsDisposed => Volatile.Read(ref _disposed) == 1;
 
+    /// <summary>
+    ///     Whether this session has active users currently executing operations
+    /// </summary>
+    public bool HasActiveUsers => Volatile.Read(ref _activeUsers) > 0;
+
     /// <summary>
     ///     Disposes the session and releases all resources including the document.
     ///     Thread-safe: uses Interlocked to prevent double-dispose.
@@ -138,6 +148,33 @@ private void ThrowIfDisposed()
             throw new ObjectDisposedException(nameof(DocumentSession), $"Session {SessionId} has been disposed");
     }
 
+    /// <summary>
+    ///     Acquires a usage scope that prevents the session from being cleaned up while in use.
+    ///     The caller must dispose the returned scope when the operation is complete.
+    /// </summary>
+    /// <returns>A disposable usage scope</returns>
+    /// <exception cref="ObjectDisposedException">Thrown when session is already disposed</exception>
+    public IDisposable AcquireUsage()
+    {
+        Interlocked.Increment(ref _activeUsers);
+        if (IsDisposed)
+        {
+            Interlocked.Decrement(ref _activeUsers);
+            throw new ObjectDisposedException(nameof(DocumentSession),
+                $"Session {SessionId} has been disposed");
+        }
+
+        return new UsageScope(this);
+    }
+
+    /// <summary>
+    ///     Releases a usage scope, decrementing the active user count
+    /// </summary>
+    private void ReleaseUsage()
+    {
+        Interlocked.Decrement(ref _activeUsers);
+    }
+
     /// <summary>
     ///     Execute a synchronous operation on the document with thread-safety
     /// </summary>
@@ -293,4 +330,24 @@ public async Task<T> GetDocumentAsync<T>(CancellationToken cancellationToken = d
             _lock.Release();
         }
     }
+
+    /// <summary>
+    ///     Represents a usage scope that prevents the session from being cleaned up.
+    ///     Disposing this scope releases the usage count.
+    /// </summary>
+    private sealed class UsageScope : IDisposable
+    {
+        private DocumentSession? _session;
+
+        public UsageScope(DocumentSession session)
+        {
+            _session = session;
+        }
+
+        public void Dispose()
+        {
+            var s = Interlocked.Exchange(ref _session, null);
+            s?.ReleaseUsage();
+        }
+    }
 }

Core/Session/DocumentSessionManager.cs

@@ -625,6 +625,14 @@ private void CleanupIdleSessions(object? state)
         foreach (var session in allSessions)
             if (now - session.LastAccessedAt > timeout)
             {
+                if (session.HasActiveUsers)
+                {
+                    _logger?.LogDebug(
+                        "Skipping cleanup of idle session {SessionId} because it has active users",
+                        session.SessionId);
+                    continue;
+                }
+
                 _logger?.LogInformation("Session {SessionId} timed out after {Minutes} minutes of inactivity",
                     session.SessionId, Config.IdleTimeoutMinutes);
 

…ail/Calendar/LoadEmailCalendarHandler.cs …mail/Calendar/GetEmailCalendarHandler.csHandlers/Email/Calendar/LoadEmailCalendarHandler.cs renamed to Handlers/Email/Calendar/GetEmailCalendarHandler.cs Handlers/Email/Calendar/LoadEmailCalendarHandler.cs renamed to Handlers/Email/Calendar/GetEmailCalendarHandler.cs

@@ -10,10 +10,10 @@ namespace AsposeMcpServer.Handlers.Email.Calendar;
 ///     Handler for loading and reading calendar appointment information from an ICS file.
 /// </summary>
 [ResultType(typeof(AppointmentEmailInfo))]
-public class LoadEmailCalendarHandler : OperationHandlerBase<object>
+public class GetEmailCalendarHandler : OperationHandlerBase<object>
 {
     /// <inheritdoc />
-    public override string Operation => "get_info";
+    public override string Operation => "get";
 
     /// <summary>
     ///     Loads a calendar appointment from the specified ICS file and returns its information.

…Email/Contact/LoadEmailContactHandler.cs …/Email/Contact/GetEmailContactHandler.csHandlers/Email/Contact/LoadEmailContactHandler.cs renamed to Handlers/Email/Contact/GetEmailContactHandler.cs Handlers/Email/Contact/LoadEmailContactHandler.cs renamed to Handlers/Email/Contact/GetEmailContactHandler.cs

@@ -10,10 +10,10 @@ namespace AsposeMcpServer.Handlers.Email.Contact;
 ///     Handler for loading and retrieving email contact information.
 /// </summary>
 [ResultType(typeof(ContactEmailInfo))]
-public class LoadEmailContactHandler : OperationHandlerBase<object>
+public class GetEmailContactHandler : OperationHandlerBase<object>
 {
     /// <inheritdoc />
-    public override string Operation => "get_info";
+    public override string Operation => "get";
 
     /// <summary>
     ///     Loads an email contact from a VCF or MSG file and returns its information.

Handlers/Email/Contact/SaveEmailContactHandler.cs

@@ -38,7 +38,7 @@ public override object Execute(OperationContext<object> context, OperationParame
         if (!File.Exists(path))
             throw new FileNotFoundException($"Input file not found: {path}");
 
-        var contact = LoadEmailContactHandler.LoadContact(path);
+        var contact = GetEmailContactHandler.LoadContact(path);
 
         var ext = format?.ToLowerInvariant() ?? Path.GetExtension(outputPath).ToLowerInvariant().TrimStart('.');
         contact.Save(outputPath, ext == "msg" ? ContactSaveFormat.Msg : ContactSaveFormat.VCard);

Handlers/Email/Contact/SetPhotoEmailContactHandler.cs

@@ -41,7 +41,7 @@ public override object Execute(OperationContext<object> context, OperationParame
         if (!File.Exists(photoPath))
             throw new FileNotFoundException($"Photo file not found: {photoPath}");
 
-        var contact = LoadEmailContactHandler.LoadContact(path);
+        var contact = GetEmailContactHandler.LoadContact(path);
         var photoBytes = File.ReadAllBytes(photoPath);
         contact.Photo = new MapiContactPhoto(photoBytes, MapiContactPhotoImageFormat.Jpeg);
 

Handlers/Email/FileOperations/DetectFormatEmailFileHandler.cs

@@ -14,7 +14,7 @@ namespace AsposeMcpServer.Handlers.Email.FileOperations;
 public class DetectFormatEmailFileHandler : OperationHandlerBase<object>
 {
     /// <inheritdoc />
-    public override string Operation => "detect_format";
+    public override string Operation => "detect";
 
     /// <summary>
     ///     Detects the format of an email file using Aspose.Email's format detection.