feat: 新增 19 個視圖診斷／篩選器／Section Box／文件操作 MCP 工具（192→211）

[7alexhuang-ux]

摘要

相對 upstream main（2faacc5）新增 19 個 MCP 工具（192 → 211），並改善排煙檢討流程。upstream 既有工具無刪除、無改名；既有工具的新參數全部有預設值，不給時行為與原本一致。

主軸是補上 AI 端原本缺席的兩種能力：

1. 看得見：AI 可以直接取得 Revit 畫面（capture_view_image），不必再請使用者截圖。
2. 查得到為什麼：「元素明明在、卻看不到／顏色不對／主檔設了連結沒反應」這類問題，原本只能在 VG、篩選器、樣板、材質、視圖範圍、連結顯示設定之間逐層點開比對。現在每一層都有對應的唯讀查詢工具。

---

一、視圖表現法診斷（66b0e1c，+1 工具）

get_view_graphics_diagnostics（唯讀）

接手他人模型時，常遇到表現法跟預期不符：某面牆被填色、某元素不見、線變粗或變淡。最麻煩的是同時有兩個成因的情況，查到第一個就停手，往往會修錯地方。

本工具依 Revit 覆寫優先序一次掃完五個來源：

視覺型式 > 元素個別覆寫 > 視圖篩選器 > 類別覆寫 > 材料本身

• 回報所有命中的成因，不是只回第一個。每筆含 Priority / Source / Scope（整個視圖／這個元素／整個品類／全專案）/ Detail / Fix
• 偵測範圍：表面與剖面的前景／背景填滿（顏色與樣式）、投影線色、剖面線色、線寬、半色調、透明度
• 也偵測「元素根本看不到」的兩種情形：篩選器把可見性關掉、品類在本視圖被關閉
• 回報視圖樣板鎖住哪些圖形參數，也就是使用者在視圖上改不動的原因
• 唯讀保證：不開 Transaction，只呼叫 getter

已知限制：連結模型覆寫、設計選項、階段化圖形覆寫尚未涵蓋。都沒找到成因時，會以文字提示使用者自行檢查。

---

二、排煙檢討：3D Section Box 與窗型係數（cb3d31f、4925544，+1 工具）

問題 1：3D 視圖用 CropBox 裁切是錯的

原本 align_view_cropbox_to_element 對 3D 視圖也操作 CropBox。CropBox 在 3D 只是平面框，不做 Z 向裁切，房間上下的樓板、樑、上一層都會混進畫面，排煙檢討（天花板下 80 cm 有效帶）根本看不清楚。

修正：

• 新增 set_3d_section_box：用 View3D.SetSectionBox() 依元素完整 XYZ BoundingBox 做三向裁切，同時關閉 CropBox，避免雙重裁切
• align_view_cropbox_to_element 回到 2D 專用（只調 XY，保留 Z 深度與 Transform）。為了相容已快取舊 schema 的 client，目標是 View3D 時會轉交 set_3d_section_box，不會直接拒絕
• clearCropOnly=true：只關閉先前被舊流程誤啟用的 3D CropBox，不動 Section Box

問題 2：統一 padding 顧此失彼

實測時遇到的情況：房間底標高約 -2.8 m，但下方支承樑底到 -5.3 m。統一 600 mm padding 的結果是：

• 下方只切到樑的上半段
• 上方同時切進上一層的樑

修正：

• 非對稱 padding：padding_xy_mm / padding_bottom_mm / padding_top_mm，保留 padding_mm 當相容入口
• includeSupportingBeams=true：自動找出「樑頂貼近目標底面（容許值 supportingBeamTolerance_mm，預設 300）且 XY 相交」的結構構架，把完整樑身納入 Section Box，不必猜水平 padding 要給多少

問題 3：上層結構要不要看，依檢討目的而定（4925544）

新增 upperStructureMode 兩條路由：

模式	頂面位置	適用
current_level_only（預設，維持原行為）	目標頂 + padding_top_mm	只看當層
include_upper_structure_without_slab	最近上層樓板底 − upperSlabClearance_mm（預設 10 mm）	要看上層樑對排煙有效帶的影響，但不要樓板擋住視線

找不到上層樓板時會直接報錯，不修改 Section Box，不會留下半套狀態。

問題 4：窗型有效面積係數寫死在程式裡

check_smoke_exhaust_windows / export_smoke_review_excel 新增參數，係數改成可稽核的專案政策：

參數	窗型	預設
projectedOpeningRatio	推射／外推／上懸	1.0
casementOpeningRatio	推開／平開	1.0
slidingOpeningRatio	橫拉（整樘面積基準）	0.5
unknownWindowAssumption	族群名稱無法判定時的暫定窗型	manual

• 回傳結果多一個 WindowOperationPolicy 欄位，記錄這次檢討用了哪組係數。Excel 匯出沿用同一組
• 用了假設值的窗會保留「需人工確認」標記，不會因為給了假設就被當成確定值
• projectedOpeningRatio 預設改為 1.0（f817e03）；domain／skill 的推開／平開窗係數統一為 1.0，與工具預設一致。兩者皆視為可完整開啟，開啟角度受限的專案可調低
• 正式名稱統一為「橫拉窗（Horizontal Sliding Window）」，「推拉窗」只作搜尋別名

其他：天花板高度來源路由（domain + skill）

domain/smoke-exhaust-review.md 與 smoke-exhaust skill 新增 ceilingHeightSource 選擇規則：

• 天花尚未建模或只建一部分 → room_parameter
• 受檢範圍逐房覆蓋可確認 → ceiling_element
• 同一次檢討與它的 Excel 匯出必須用相同來源
• 揭露既有行為：ceiling_element 找不到匹配天花時會靜默回退到 Room 參數。文件明定部分建模階段不得依賴這個隱性回退
• 禁止把口述的「標準 3000 mm」直接覆蓋模型實值，須先核對逐房 Upper Limit / Limit Offset

⚠️ 請 reviewer 留意：窗型係數（推射 1.0、平開 1.0、橫拉 0.5、固定 0）是經設計端確認的預設政策，不是法規常數；domain/smoke-exhaust-review.md 已註明各專案應依實際開啟方式調整並人工核對。

---

三、視圖篩選器（92e7d57，+3 工具）

動機：逐元素的 override_element_graphics 不是規則，新增元素不會套用，接手的人也看不出意圖。檢討用視圖應該寫成「規則 → 表現法」，資料一改，顏色跟著變。

工具	說明
get_filterable_parameters	用 ParameterFilterUtilities.GetFilterableParametersInCommon 列出某些類別實際可以當篩選條件的參數，附 StorageType 與支援的運算子，不必憑印象猜
create_view_filter	建立 ParameterFilterElement 並套用到視圖（含圖形覆寫）。回傳 MatchedElementCount，規則有沒有命中當場就看得到。同名預設報錯，要 overwriteExisting=true 才會更新
remove_view_filter	從視圖移除篩選器，可選擇一併刪除篩選器本身

484ff4c 再擴充 create_view_filter：新增 patternName / backgroundPatternName / backgroundColor，篩選器可以畫 hatch，不只是色塊（例如前景土壤紋加背景淺綠實心，組成草地）。填充樣式名稱填錯會直接報錯，不會靜默退回實心。不給這些參數時，行為與原本完全相同。

---

四、診斷層與文件操作（484ff4c，+14 工具）

看得見畫面

工具	說明
capture_view_image	把指定視圖（省略時用作用中視圖）匯出成點陣圖並直接回傳影像。用途：確認圖形設定實際長什麼樣、判斷 hatch 密度與配色、驗收批次操作結果。只讀模型，只寫系統暫存檔

Server 端配套（MCP-Server/src/index.ts）：結果裡有 ImageBase64 時，改用 MCP image content block 回傳，其餘欄位（視圖名稱、尺寸、Warnings）另附在 text block。原本的一般路徑會把 base64 塞進 JSON 字串，AI client 只拿到一長串文字、看不到圖，工具等於白做。這個分支只在結果含 ImageBase64 時觸發，不影響其他工具。

「看不到」的三個常見盲區

工具	對應盲區
get_view_range / set_view_range	元素在模型裡、類別也開著，平面圖卻看不到。最常見的成因是元素落在 View Depth 之外。四個平面（topClip / cutPlane / bottomClip / viewDepth）可以各自設定，level 支援樓層名稱或 Unlimited / Level Above / Level Below / Current
get_link_display_settings / set_link_display_settings	主檔篩選器或類別覆寫對連結模型沒反應。關鍵欄位 HostFiltersApply：連結設成 ByLinkView 或 Custom 時，主檔覆寫完全不作用，畫面上又看不出來。set 可以改成 byHostView，逐個連結獨立處理，一個失敗不影響其他
list_fill_patterns	列出所有 FillPatternElement 的名稱、ID 與 Model/Drafting 類型。指定任何 hatch 之前先查名稱，不要猜。同名有兩種時優先取 Model 樣式（隨視圖比例縮放）

材質層級與相機

工具	說明
get_material_graphics / set_material_graphics	讀寫材質「圖形」頁籤：著色顏色、透明度、表面／切割的前景與背景填充。改的是材質本身，所有視圖都會跟著變，跟篩選器、V/G 只作用單一視圖是關鍵差異。給了 shadingColor 會自動關閉「使用彩現外觀」
get_camera_info	讀取 3D 視圖相機的眼睛 XYZ、所在樓層、離各樓層高度、俯仰角。另外用實際眼睛高度反推性質面板 Eye Elevation 參數的 0 點，逐一比對內部原點、專案基準點、測量點與各樓層。解決「Eye Elevation 顯示負值、卻不知道基準在哪」的問題

文件操作

工具	說明
list_open_documents	列出目前 Revit 進程中所有非連結文件
open_document	開啟本機 Revit 文件並設為作用文件，可選擇從中央模型卸離並保留工作集。文件已開啟時，Revit API 無法用程式切換作用視窗，會回報需使用者手動點選
save_document	儲存作用中文件，或依標題儲存指定文件。不支援另存新檔
close_document	依標題關閉非連結文件。典型情境：連結檔被獨立開啟編輯，宿主要重載它之前必須先關閉。有三道防呆：(1) 作用中文件無法用 API 關閉，會回傳明確錯誤；(2) 連結文件拒絕關閉；(3) 已修改的文件預設拒絕，要 save=true 或 discardChanges=true 才會關
reload_links	重載連結模型，可依連結類型 ID 或名稱篩選，省略時重載全部。個別連結失敗不中斷其他連結

Bug 修正

• get_all_materials 整份查詢 crash：部分材質的 Color 未初始化，讀 Red/Green/Blue 會丟 The color represents an invalid or uninitialized color，導致 searchKeyword="*" 整份失敗。改為單一材質取色失敗時回 null，不拖垮整份清單

---

文件同步（a8d2c16 等）

工具數 211 同步到 CLAUDE.md、README.md、README.zh-TW.md、docs/DOCUMENT_AUDIENCE_INVENTORY.md、docs/BIM_MCP/**。tools-index.html 每支新工具各有一張卡片。每次改動都依 Logging Protocol 記錄在 log/2026-09.md。

---

驗證

項目	結果
verify-qaqc.ps1 -SkipBuild -SkipDeploy	PASS 67 / FAIL 0 / WARN 2（兩項 WARN 都是既有項目：3-5 working-tree 提示、check_sanitary_fixture_requirements 隔離）
7-14 tools-index 卡片	211 支工具各一張卡片，頁面自身統計一致
7-15 TS ↔ C# dispatcher	所有註冊工具都有對應 case
9-1 annotations	211 支都有 title / readOnlyHint；destructiveHint=true 仍只限既有白名單
C# 編譯	get_view_graphics_diagnostics 與 Section Box 系列：R22–R26 皆 0 errors；484ff4c 批次：R24 / R26 0 errors
MCP Server build	0 errors

實機驗證狀態（誠實揭露）

工具	狀態
set_3d_section_box（含 includeSupportingBeams）	✅ Revit 2024 實跑：SectionBoxActive=true、CropBoxActive=false，自動納入 7 支當層支承樑，底面涵蓋完整樑身、頂面不外擴到上一層；部署 DLL 與 build output SHA256 一致
upperStructureMode、窗型係數參數	⚠️ 已編譯，未實機
get_view_graphics_diagnostics	⚠️ 已編譯，未實機；多個成因同時命中時的排序目前只依 API 語意，未對照 Revit 實際勝出規則
視圖篩選器三工具	⚠️ 已編譯，未完整實機
484ff4c 的 14 支新工具	⚠️ 已編譯，未逐一實機

建議 merge 前或 merge 後補上實機測試。有問題的工具我可以再追修。

🤖 Generated with Claude Code