Tools · 執行層
模型上真正被動到的那一下

自動調整剖面視圖的網格線 (Grids) 與樓層線 (Levels) 2D 範圍與氣泡顯示。

分析樓板頂面排水坡度：以 Solid→PlanarFace 法向量與 Z 軸夾角計算每片朝上頂面的坡度百分比，回傳每片樓板的 Min/Max 坡度。預設只分析、不寫入模型（不開 Transaction）；只有明確指定 paramName 時才會回寫該參數。未指定 elementIds 時自動收集 Function=Exterior 的樓板。

關閉目前 Revit 進程中已開啟的非連結文件（依標題比對）。常見情境：某個連結檔被獨立開啟以編輯，編輯完須先關閉才能讓宿主文件正常載入該連結。文件為目前作用文件時，Revit API 無法程式關閉作用文件，會回傳明確錯誤，需使用者先切換或開啟其他文件；連結文件與家族文件不受此限（家族文件可關閉，連結文件會被拒絕，須改由宿主文件的連結管理處理）。文件已修改時，預設拒絕關閉，除非指定 save 先儲存，或 discardChanges 放棄變更。

在 Revit 中建立一個新的樓層 (Level)。指定標高（公釐）與可選名稱；若名稱已存在 Revit 會自動附加尾號。

依 Element ID 刪除 Revit 元素。

翻轉指定的 Revit 建築元素（例如門或窗）。可以選擇翻轉面向(facing)或開向(hand)。

[Phase 1: Exploration] Get all categories and their element counts in the active view. ALWAYS run this first to confirm if the target category exists.

取得目前開啟的視圖資訊，包含視圖名稱、類型、樓層等。

取得專案中所有樓層的清單，包括樓層名稱和標高。

取得專案中所有視圖的清單，包含平面圖、天花圖、3D視圖、剖面圖等。

[Phase 2: Alignment] Get all parameter names for a specific category. MANDATORY: Run this before 'query_elements_with_filter' to identify exact localized parameter names.

一次撈全部門窗的座標清單：插入點 (LocationPoint) 與 boundingbox（含中心點），座標為 mm。可依門/窗/全部與樓層篩選，並可選擇一併掃描連結模型（自動套用 Transform 轉專案座標）。回傳每筆含 ElementId、族群、類型、標記、樓層、宿主牆ID、朝向。

取得指定元素的詳細資訊，包括參數、幾何資訊等。

[Optional Phase 2.5] Get the distribution of existing values for a specific parameter.

取得目前開啟的 Revit 專案基本資訊，包括專案名稱、建築物名稱、業主等。

取得使用者目前在 Revit 中選取的所有元素的基本資訊（ID、名稱、品類）。若是視圖或剖面標記，會一併回傳 Origin (X,Y,Z) 供空間排序使用。

列舉專案中所有品類 (Category) 及其 CategoryType (Model / Annotation / Internal / AnalyticalModel / Invalid)。回傳每個品類的 Name、CategoryType、Id、子品類數量，並附各 CategoryType 的統計。唯讀查詢。

列出目前 Revit 進程中所有非連結文件，適合在需要確認可操作的文件、作用文件或儲存目標前使用。

載入共享參數檔 (Shared Parameter File) 並將參數綁定至指定品類的 Type 或 Instance 層級。用於在寫入自訂參數前，先確保專案已載入參數定義。例如載入 GreenMaterial_SharedParams.txt 的 64 個綠建材參數（Mat1~Mat6 六槽位）至 Walls/Floors/Ceilings，之後用 set_green_material_type_parameters 寫值。

測量兩個點之間的距離。回傳距離（公釐）。

修改 Revit 元素的參數值。

移動指定的 Revit 元素（依 dx, dy, dz 指定位移量）。

開啟指定的本機 Revit 文件並設為作用文件；可選擇從中央模型卸離並保留工作集。若文件已開啟，Revit API 無法用程式切換作用視窗，需使用者手動點選該文件視窗。

查詢 Revit 專案中的元素。可依類別、族群、類型、樓層等條件篩選。

[Phase 3: Retrieval] Query elements with multi-filter support. NOTE: The 'field' name MUST match names from 'get_category_fields'.

重載作用文件中的 Revit 連結模型。可用連結類型 ID 或名稱篩選；兩者都省略時重載全部連結。個別連結失敗不會中斷其他連結的重載。

重新命名指定的 Revit 視圖（包含剖面圖、平面圖等），此工具不受軟體語系本地化影響。

儲存作用中的 Revit 文件，或依文件標題儲存已開啟的指定文件。此工具不支援另存新檔，唯讀文件無法儲存。

在 Revit 中選取指定的元素，讓使用者可以視覺化確認目標元素。

切換至指定的視圖。

一次把整個專案的顯示單位切換到指定系統/模式（全案性動作，單一 Transaction 可 Ctrl+Z 還原）。mode='taiwan' = 公制底 + Air Flow m³/h（建築技術規則 §102 通風量單位）+ Length 補單位符號；mode='taiwan-plumbing' = taiwan 再加給排水管路側六格（管徑 mm、流量 L/min、流速 m/s、壓力 mH2O、摩擦 mmH2O/m、坡度 1:ratio），對齊建築設備編 §43/§46 與給水排水設備設計技術規範；'metric' / 'imperial' 為純公制/英制預設。每個 spec 都會連同「精度」與「單位符號」一起設定——只設單位會讓 Length 顯示成裸數字（673 而非 673 mm），且流速精度 0.1 位會讓 2.98 與 3.05 看起來相同而產生假綠燈。可再用 length/area/volume/airFlow/pipeSize/flow/velocity/pressure/friction/slope 個別覆寫。⚠️ 台灣法規的壓力單位 kgf/cm² 在 Revit 2026 不存在（305 個 UnitTypeId 逐一反射確認），故以 mH2O 代用：1 kgf/cm² = 10.0 mH2O。回傳的 Result 是套用後從 Document 回讀的實際單位/符號/精度，不是參數回聲。

將視圖縮放至指定元素，讓使用者可以快速定位。

自動將結構構架（梁）端點的實體延伸切齊到相接的樑面或柱面，含連結檔 (RVT Links) 中的構材。只寫起點/終點延伸參數，構架的軸線位置不會被移動。相接構材貫穿本樑（T 接）時退到近端面貼齊；相接構材在此終止（L 轉角）時延伸到遠端面。節點過於繁忙（相接候選超過 4 個）的端點會跳過不動並回報，需人工確認。支援單一/多支構架或當前視圖中的所有結構構架。

分析特定結構梁上的套管穿孔。回傳精確的幾何數據，如距離柱心長度、梁深度、開孔直徑等。

將面板排列模式套用到帷幕牆。需要類型映射表和排列矩陣。

變更 Revit 元素的類型（例如將牆從 Type A 改為 Type B）。

從 CAD 指定圖層建立 Revit 結構樑（必須搭配文字標注圖層）。 重要：建議按類型分批執行（先大樑、再次樑、再地樑）， 每批只處理一個線條圖層與對應的文字圖層。 使用 beamRole 參數標示目前處理的批次。

在指定位置建立柱子。

從 CAD 指定圖層自動建立 Revit 結構柱或建築柱。會自動：辨識矩形輪廓、建立對應尺寸的族群類型、設定底頂樓層、套用旋轉角度。若指定 familyName，會從該族群的現有類型中依尺寸比對，直接使用原有柱名稱（如 C1、C2）；未指定時自動挑選最適族群並按尺寸建立新類型。執行前建議先呼叫 preview_dwg_columns 確認識別結果。此操作會修改 Revit 模型，無法自動復原，請謹慎使用。

走廊寬度標註 — 自動偵測房間邊界的平行牆對，建立精確的牆到牆尺寸標註。回傳每個區段的實測寬度與合規判定。

建立新的帷幕牆面板類型，可指定顏色（HEX）和透明度。

批次建立每一道帷幕牆的永久外立面視圖，建立/套用名為「帷幕立面」的視圖樣板，保留 crop box 與 far clip depth 可由各視圖自行控制，並回傳方向與 crop 診斷欄位。這個工具建立的是持久成果，不需要 cleanup；除非使用者明確要求清理，AI client 不得呼叫 delete_element 刪除這些 generated views。未指定 wallIds/maxWalls 時處理專案內全部帷幕牆；專案帷幕牆數量多時（例如數百道）建議用 maxWalls 分批處理，避免超過回應時限，可搭配回傳的 RemainingWallIds 續跑下一批。

在指定視圖中建立尺寸標註。

在指定的牆上建立門。可指定 sourceElementId 來複製現有門的類型、instance 參數與 facing/hand 朝向。

根據分析結果批次建立整面立面。在牆面前方批次建立多片 DirectShape 面板，支援多種面板類型和排列模式。

建立單片立面面板（DirectShape）。支援 5 種幾何：curved_panel、beveled_opening、angled_panel、rounded_opening、flat_panel。

以與 preview_family_instances_from_dwg_blocks 完全相同的參數重新掃描來源後建立 FamilyInstance——不信任任何先前呼叫的快取結果。主 Transaction + 逐筆 SubTransaction，單筆失敗不影響其他已成功項目。duplicate 項目預設會被阻擋，只有明確傳入 skipDuplicates=true 才會略過（不得由 AI 自行推定使用者已核准）。unsupported_family／untrustworthy_transform 一律不建立。回傳每筆結果（created/failed/skipped）與建立後獨立查詢驗證的 verifiedExists。此操作會修改 Revit 模型，無法自動復原，請先呼叫 preview 確認再執行。

在 Revit 中建立樓板。需要指定邊界點座標。回傳值會揭露實際採用的樓層與樓板類型。

依座標（公釐）批次建立直線網格線（軸線），可逐條指定名稱（如 1、2、A、B）。與既有網格線共線重疊者會略過（status=duplicate）；名稱已被其他網格線使用者不建立（status=name_conflict）。Revit 預設把軸號圓圈放在終點端，需要軸號在哪一端就把該端當 end。回傳逐筆 Results（status: created / duplicate / name_conflict / invalid / failed）。

依 CAD 指定圖層的直線建立 Revit 網格線（軸線）。參數與 preview_dwg_grids 相同，請先用相同參數預覽並經使用者確認。同一直線上被軸號圓圈打斷的線段會合併成一條；與既有網格線共線重疊者略過，名稱衝突者不建立。垂直軸線由下往上、水平軸線由左往右建立（軸號圓圈在上方／右方端）。此操作會修改 Revit 模型。

批次建立門/窗『型別』（FamilySymbol）：複製指定的種子型別（seed）→ 命名 → 設定寬×高。輸入寬高單位為公分（cm），內部自動換算為 Revit 英尺。**只建立型別，絕不在模型中放置任何門窗實體**。可重複執行（idempotent）：同一族群中已存在同名型別則略過。適合把 CAD 門窗表的『編號→寬×高』一次生成整套型別，供後續 door-window-legend-tools 產生門窗圖例使用。寬或高任一參數設定不到即回滾該筆並列入 failed（不留尺寸錯一半的型別）。回傳 created / skipped / failed 三個清單。

建立非結構直線牆，座標與高度為公釐。可明確指定樓層與基本牆類型；未指定樓層時使用目前平面視圖的樓層，無樓層則報錯。定位線為牆中心線、基準偏移為零。回傳值會揭露實際採用的樓層與牆類型（LevelSource / WallTypeSource）。

在指定牆上用牆飾條（Wall Sweep）或分隔縫（Reveal）把牆等分：垂直方向沿牆長、水平方向沿牆高，divisions 等分會建立 divisions-1 條。可指定既有輪廓，或給 profileWidth/profileDepth 自動新建矩形輪廓族群。先用 listOnly 查專案有哪些飾條類型與輪廓，或用 dryRun 預覽等分位置。

在指定的牆上建立窗。可指定 sourceElementId 來複製現有窗的類型、instance 參數與 facing/hand 朝向。

非破壞診斷帷幕立面的尺寸標示；可比較 CurtainGridLine profiles，或以 level_offset 在實際立面測試 Level plane、Invisible DetailCurve 與完整 production path，所有 level_offset 元素強制 rollback。

非破壞診斷指定帷幕牆的立面方向判定流程；以 rollback transaction 建立暫時 ElevationMarker/ViewSection，回傳 wall.Orientation、預期 marker 位置、暫時 view 方向與 dot 檢查，不留下視圖或 marker。

Batch, non-destructive curtain wall elevation direction diagnostic. Compares wall.Orientation and -wall.Orientation candidate sides for selected or all curtain walls; temporary markers/views are created inside rollback transactions.

取得專案中所有網格線（Grid）的資訊。

取得專案中所有可用的柱類型。

取得專案中所有可用的帷幕牆面板類型。

取得帷幕牆詳細資訊，包含 Grid 排列、面板尺寸、面板類型分佈等。

掃描目前 Revit 平面視圖中所有 CAD 匯入/連結的圖層名稱，回傳圖層清單並自動推薦可能包含樑、標註文字的圖層。使用前請確認 Revit 已開啟平面視圖且已匯入 CAD 檔案。

掃描目前 Revit 平面視圖中已連結（Linked，非 Imported）的 CAD DWG，列出可辨識的 Block（INSERT）名稱、每種數量、插入點與旋轉角範例。唯讀操作，不建立任何 Revit 元素。使用前請確認 DWG 已用「連結」方式匯入。

掃描目前 Revit 平面視圖中所有 CAD 匯入/連結的圖層名稱，回傳圖層清單並自動推薦可能包含柱子的圖層。使用前請確認 Revit 已開啟平面視圖且已匯入 CAD 檔案。

取得專案中已載入的家具類型清單。

取得目前專案中可用的線型 (GraphicsStyles)，例如：虛線、細線等。

取得牆的詳細資訊，包含厚度、長度、高度、位置線座標等。

取得專案中所有可用的牆類型，包含名稱和 Element ID。

依指定樓板底面的水平投影範圍整平 Toposolid；本次僅支援 footprint_only 模式。

將指定樓層的牆，其頂部與上方的樓板、天花板、結構樑做幾何接合 (JoinGeometry)。回傳成功接合/已接合跳過/失敗的統計與各樓層明細。常用於樓層牆體建模後的批次頂接合。

將指定的 CAD 檔案（.dwg / .dxf）連結（Link，非 Import）到 Revit 中的指定視圖。預設 thisViewOnly=true，連結僅在該視圖可見；3D 視圖不支援 thisViewOnly。視圖可用 viewId（最精確）或 viewName（會自動 fallback：精確 → 包含；多筆會回傳候選清單）。此操作會修改 Revit 模型，且 Revit 不允許程式化卸除連結，請謹慎使用。

批次將多個 CAD 檔連結到對應樓層的平面視圖，並把每個 CAD 平移對齊到指定的 Revit Grid 交點。自動從 CAD 檔名抽樓層代碼（支援 FL1/FL2、B1/B1F、RF、1F/2F、地下1樓、3樓 等格式）→ 找名稱含該代碼的 FloorPlan。對齊方式：Link 後做 ElementTransformUtils.MoveElement，translation = (Revit Grid 交點 − CAD 錨點)。強制 Placement=Origin、不旋轉、不支援自訂 referencePoint / orientToView / customScale（會干擾對齊）。全部在單一 Transaction 內，失敗會 commit 已成功的部分並回報每筆狀態。

在指定位置放置家具實例。

解析 CAD 指定圖層中的雙線幾何，預覽識別到的樑中心線資訊（區分 X 向與 Y 向）。此工具不會建立任何 Revit 元素，僅回傳解析結果供確認數量。建議在執行 create_beams_from_dwg 前先呼叫此工具確認數量。

解析 CAD 指定圖層中的矩形幾何，預覽識別到的柱資訊（位置、寬度、深度、旋轉角）。此工具不會建立任何 Revit 元素，僅回傳解析結果供確認。建議在執行 create_columns_from_dwg 前先呼叫此工具確認數量與尺寸。

讀取目前平面視圖中連結或匯入的 CAD（DWG/DXF）。不給 layerName：列出含直線的圖層與各層直線數，並推薦可能的軸線圖層（grid/axis/軸/柱心…）。給 layerName：把該圖層的直線（含 PolyLine、圖塊內一層）合併共線段後，預覽將建立的網格線與自動命名，不修改模型。建議流程：preview_dwg_grids（無參數）→ preview_dwg_grids（layerName）→ 使用者確認 → create_grids_from_dwg。

對指定 Block 的每個插入點做座標鏈健檢（Block insertion point → Block transform → ImportInstance TotalTransform），回傳每點狀態：ready / duplicate_existing / duplicate_in_batch / unsupported_family / untrustworthy_transform，並攤開完整座標鏈供核對。唯讀操作，不建立任何 Revit 元素。transform 不可信時只回傳警告，不做任何猜測性修正。familySymbolId 與 levelId 必須明確指定，本工具不自動選擇。

查詢指定座標附近的牆體，回傳牆厚度、位置線與牆面座標。

恢復先前由 unjoin_element_joins 取消的接合關係（共用 pair 儲存，限同一 Revit session）。

掃描目前視圖中所有被套管（Sleeves）穿過的結構梁。回傳包含梁 ID、連結模型 ID 及穿過該梁的套管數量的清單。

Convert structural framing (beams) and columns from a linked IFC model into native Revit structural framing/column instances, matching detected section sizes to family types. Supports dry-run preview, batched creation, section-based column base-type selection (steel / SHS / RC), and optional alignment of column tops to the floor bottom above.

自動分析視圖中的樓梯幾何，偵測被牆、版等物件遮擋的邊緣線段，回傳座標以供後續繪製虛線。

以指定來源類別為中心，解除其與鄰近 target 類別元素的幾何接合（BoundingBox 外擴 1 ft 搜尋）。預設 target 為 8 類（Walls、Floors、Columns、StructuralColumns、StructuralFraming、StructuralFoundation、Roofs、Ceilings）。常見用法：牆-柱（上色前置）＝ sourceCategory: Walls、targetCategories: [Columns, StructuralColumns]；柱本位 ＝ sourceCategories: [Columns, StructuralColumns]、targetCategories: [Walls, Floors, StructuralFraming]。解除的配對存在同一份 session 儲存，可用 rejoin_wall_joins 還原（限同一 Revit session）。

分析走廊寬度。使用 Revit 端的房間邊界線段找出平行牆對，回傳實測寬度、最小寬度與各區段檢討結果。

Find rooms on target levels that share or contain TYPE partition walls taller than a threshold. Uses room boundary segment ElementIds so shared room-to-room walls are assigned to both rooms, and can add upward ray evidence from room bottom to floor underside.

批次依房間名稱或用途分組，設定 Room 的 Upper Limit（ROOM_UPPER_LEVEL）與 Limit Offset（ROOM_UPPER_OFFSET）。不動樓層，只改 Room 參數。對 Model Group 內的 Room 會自動進入 EditGroup 模式（每個 GroupType 只編輯一次，變更同步到所有 instance），避免「modified outside group edit mode」警告。Transaction 內註冊 WarningSwallower 吞掉其他警告。單一 Transaction，可 Ctrl+Z 整批還原。

Reliable scaffold takeoff mode. Automatically detects exterior/perimeter walls from wall centerline geometry using ray exposure tests, excludes interior walls, sums the included wall lengths, optionally selects the result in Revit, and reports the classification evidence.

Indoor scaffold takeoff mode. Reads placed Revit Rooms and classifies them into general scaffold, interior finish scaffold, or excluded rooms. General scaffold for non-stair/elevator rooms is measured by perimeter x height. Interior finish scaffold for stair/elevator rooms is measured by length x width x height.

Fast scaffold takeoff mode. Sum curve lengths from the current Revit selection, including detail lines, detail component family geometry, and filled region boundaries. Use this when the user manually traces the scaffold outline.

依據台灣建築技術規則第45條及第110條檢討外牆開口。自動讀取地界線計算距離，以顏色標示違規。

Calculate sanitary fixture requirements by detecting the building type and applying the matching rule. This rule package currently supports C-1 factory/warehouse only; future building types should be added as separate rules. Output maps to the code table columns: building type, water closets, urinals, lavatories, and bathtubs/showers. Net area excludes stairs, elevators, air-raid shelter/refuge rooms, and parking spaces. This tool does not create or write Revit parameters.

在 Revit 中自動建立粉刷／油漆材料填滿圖例。同時偵測兩種資料來源：(1) 全專案房間的粉刷層（CompoundStructure Function=Finish）、(2) 被「油漆工具」塗在 Wall/Floor/Ceiling 的材料（依面法向量分類牆/地/天）。為每種材料建立 FilledRegionType 並在 Legend 視圖中繪製三張表（地坪/牆面/天花）。每張表三欄：編號 | 圖例 | 說明；粉刷類型使用 TypeMark/TypeName，油漆材料使用 Material.Mark/Description（空值顯示『(未填)』）。粉刷列在上、油漆列在下，中間以分隔列隔開。前提：專案必須已有任一 Legend 視圖（即使空白）作為複製模板，因 Revit API 不允許直接建立 Legend。版面固定（1:100 比例，欄寬 130/120/650 cm、列高 50 cm）。

產出建照送審用的樓板面積計算式文字（矩形 長×寬、三角形 底×高÷2），並可寫成圖面上的 TextNote。來源是使用者已用區域邊界線／房間分隔線切分好的封閉區域，本工具不自行分解多邊形；無法判定為矩形或三角形的區域、以及含內環（開口、管道間、樓梯間等鏤空）的區域，都會列入 Undecomposed 回報而不編入計算式。每一項都會拿「四捨五入後的邊長乘積」與「實際幾何面積」對帳，差異超過容差即列入 Mismatches，且 dryRun=false 時預設會擋下寫入。

取得房間的採光資訊，包含居室面積、外牆開口面積、採光比例。用於建築技術規則居室採光檢討。

Count doors by room. Each door is counted once against its primary room; default primary room is ToRoom with FromRoom fallback. Compatible with Revit 2020.

取得房間詳細資訊，包含中心點座標和邊界範圍。

計算房間內部表面積（牆面、地板、天花板），支援門窗開口扣除。即使模型中無實體天花板或地板元素，仍會以房間平面面積估算。回傳含 EstimatedSurfaces 欄位標示哪些為估算值。用於材料估算、塗裝面積計算、聲學分析。啟用 includeFinishLayers 可偵測房間內非邊界粉刷層，自動寫入房間飾面參數、建立明細表、匯出 Excel。【兩次呼叫工作流程】當 includeFinishLayers=true 時，建議分兩次呼叫：第一次不帶 defaultXxxFinish 參數，取得分析結果後檢查哪些房間/表面缺少粉刷層（FloorFinishLayers / CeilingFinishLayers / Breakdown.FinishLayers 為 null），詢問使用者要統一填入什麼預設類型標記（地板/牆面/天花各一種，留空=不填），再以 defaultFloorFinish / defaultWallFinish / defaultCeilingFinish 參數第二次呼叫產出最終明細表與 Excel。

Count windows by room. Each window is counted once against its primary room; default primary room is ToRoom with FromRoom fallback. Compatible with Revit 2020.

取得指定樓層的所有房間清單，包含名稱、編號、面積、用途等。可用於容積檢討。

Batch-remap room finish code parameters in one Revit transaction. Designed for painting/finish schedules: split values by '+', replace exact code tokens such as F11 -> F10 without touching F1 inside F11, and let room schedules update from the changed room parameters. Defaults to dryRun=true.

Batch-renumber placed rooms on one level in a single Revit transaction. Sorts by room center from top to bottom, then left to right, using a configurable Y-row tolerance. Supports dry-run preview and starts from a seed such as B134.

依房間範圍偵測同樓層天花板，讀取天花板類型標記，預覽或寫回房間參數（預設：天花板塗層）以更新粉刷明細表。

在管件的未連線端安裝管帽或法蘭。自動尋找開放的接頭並連接。

安全地批次調整現有模型（改參數、換類型、移動、複製、旋轉），全部包在同一個交易群組，任一步失敗就整批回滾。預設 dryRun=true：實際跑過 Revit 的接合/約束/警告檢查後回滾，回報每個元素修改前後的值與會產生的警告，模型不變。流程：先 dryRun 檢查 → 向使用者說明結果 → 取得同意後 dryRun=false 正式執行（可在 Revit Ctrl+Z 復原）。參數值以專案顯示單位解讀（台灣專案通常 mm）。位移與旋轉中心一律 mm。不支援刪除（請用 delete_element）。

梁下淨高檢討（含連結的結構模型）：沿每支梁取樣，量測梁底到下方第一片樓板頂面的淨高，與要求值比較；同時量測梁底到天花板頂的管線可用空間與天花高度。回傳不合格清單、各樓層最小淨高，可選擇在模型放置檢討標記或在「AI檢討_結果3D」上色。方法見 domain/beam-clear-height-check.md。

管線間預留淨距檢討（管、風管、電纜架、導線管；含連結模型、含保溫）：找出彼此淨距小於要求或已碰撞的管段，可用 rules 依類別組合設定不同淨距，可用 checkAgainst 同時檢查管線與梁/柱等結構的淨距。經由管件相連的同一路由不互相比較。方法見 domain/mep-spacing-clearance-check.md。

清除 check_beam_clear_height / check_mep_spacing 放置的檢討標記（只刪除本工具建立的標記）。

將 detect_clashes 的結果視覺化上色到 CSA 元素。colorScheme 可選 by_csa_category（柱紅/樑橘/板黃/牆藍）、by_system（依 MEP 系統）、by_severity（依貫穿深度嚴重度）。

把一組風口與一台設備組成 Revit 風管系統（MechanicalSystem）。equipmentId 可省略，用於建立「已決定獨立成系統但設備尚未選定」的中間狀態（端點未歸屬任何系統代表還沒決定，已建系統但設備欄空白代表已決定獨立、設備待補）——省略時會把 baseConnector 傳 null 呼叫 Revit API；Revit API 文件明載 baseEquipmentConnector 為選填、允許傳 null（"The base equipment is optional for the system, so this argument may be null."），但此路徑目前僅為文件契約推導，執行期尚未實測，若實測發現與文件不符，例外訊息會原樣往上拋，不做替代方案。equipmentId、equipmentConnectorIndex、equipmentConnectorId 顯式傳 null 等同省略該參數。terminalIds 每筆若解析失敗（找不到元素、非 FamilyInstance、非整數 ElementId、該風口沒有任何 Connector、與 equipmentId 重複、在 terminalIds 內重複、Connector 已隸屬其他系統、方向或 Domain 不符、該風口有多於一個 HVAC Connector（本工具假設風口只有單一風管接頭，不自動挑選））都只記入該筆 TerminalResults 的 Error，不中止其餘風口；但全部風口都失敗時不建立系統，直接整體報錯。TerminalResults 陣列每筆對齊輸入 terminalIds 的同一位置，附 Index（輸入陣列位置，從 0 起算）、ElementId（terminalIds 該筆解析出的整數值；只有當這筆輸入本身不是合法整數時才為 null，一旦成功解析出整數，即使後續驗證失敗——與 equipmentId 重複、terminalIds 內重複、找不到元素、非 FamilyInstance、Connector 已隸屬其他系統等——ElementId 仍會回填該值方便對應是哪一筆，不會因為失敗就抹成 null，也不會用 0 這種本身合法的 ElementId 當失敗標記）、Success、Error、ConnectorIndex（該風口採用的 HVAC connector 在排序後清單中的位置索引，只有 Success=true 時才有值，其餘為 null）；另有 SystemNameAfter，只在該筆 Success=true 且整體 CommitStatus='Committed' 時才有值，其餘情況為 null；其值即頂層 SystemName 的逐筆複本。設備上常有多個 Connector（送風/回風/排風/水路/電源），選錯不會報錯、只會接成錯的系統類型：本工具依 systemType 篩選 Domain.DomainHvac 且 DuctSystemType 或 Direction 相符者，剛好 1 個才自動採用並在 EquipmentConnector 完整回報其 Index/ConnectorId/DuctSystemType/Direction/Shape/Origin（部分族群的非流體 Connector 讀取 Direction/Shape/Origin 會拋例外，已包 try/catch，讀不到回 "N/A"）；未帶 equipmentId 時 EquipmentConnector 為 null；找到 0 個或多於 1 個一律拋例外並在訊息列出全部候選，多於 1 個時請改用 equipmentConnectorIndex（清單位置索引，本工具已先依 Connector.Id 排序才建立索引，故同一族群在接頭數不變時穩定；但族群重載後若接頭增減，索引會位移且不會報錯，需跨次呼叫穩定指定同一接頭時請用 equipmentConnectorId）或 equipmentConnectorId（Connector.Id，穩定識別）明確指定，不會靜默取第一個；equipmentConnectorIndex/equipmentConnectorId 指定的 Connector 仍會驗證 DuctSystemType/Direction 是否與 systemType 相符，不符會拋例外（不會只驗 Domain 就放行）。設備或風口的 Connector 若已隸屬其他系統，Revit 不允許加入第二個系統，本工具會在對應的錯誤訊息中列出既有系統的 ElementId 與名稱。回傳的 SystemId 是新建立的 MechanicalSystem 的 ElementId，讀取時機在 trans.Commit() 之後——CommitStatus 非 'Committed'（交易未成功提交）或讀取本身失敗時為 null，此時沒有系統可供後續工具引用。SystemType 是實際採用的系統類型（即 systemType 參數解析後的值），恆有值、不受 CommitStatus 影響。EquipmentId 是實際採用的設備 ElementId，在設備 Connector 解析成功時（早於交易 Commit）就已決定；未帶 equipmentId 時為 null。SystemName 是實際生效的系統名稱，於 Commit 之後讀回；CommitStatus 非 Committed 或讀取失敗時為 null、不補值。SystemFlowReadBack 是建立後從系統本身讀回的總流量，不是呼叫端寫進去的，是 Revit 依系統成員實際計算的結果——但只有在回傳的 IsWellConnected=true 時才是有效計算值；IsWellConnected=false（例如風口已放置但風管尚未繪製，系統未良好連接）時 Revit 文件明載該計算參數無效，請勿用於驗算，回傳的 Note 會註明原因。IsWellConnected 讀 MechanicalSystem.IsWellConnected，CommitStatus 非 Committed 或讀取失敗時為 null。回傳同時附 SystemIsEmpty（讀 MEPSystem.IsEmpty），CommitStatus 非 Committed 或讀取失敗時同樣為 null、不補值。若有設備，一併讀回其 Air Flow 參數放進 EquipmentAirFlowReadBack（附 IsReadOnly 供核對是否唯讀；若該族群同名參數有多個，Ambiguous=true 且讀取的是 Revit GetParameters() 回傳的第一筆，比對結果依 Revit 文件為隨機且可能變動）。兩者都拆成 Found/DisplayValue（顯示值）/RawValue（內部值）/CalculationValid/IsReadOnly/Ambiguous/Note 欄位，互不補值。回傳另附 ActualMemberCount（系統實際成員數，讀不到為 null）與 ExpectedMemberCount（= SuccessCount；Revit API 文件明載 MEPSystem.Elements 不含 base equipment 或 panel，故預期成員數只算風口成功筆數、不含設備）供交叉比對，不一致時 MemberCountMismatch=true。設備是否已掛上系統由獨立欄位 BaseEquipmentAttached 回報（true/false；交易非 Committed 或讀取失敗時為 null，不補值），不混進成員數比對。整批在單一 Transaction 內完成；systemName 有給時嘗試命名，但 Revit 要求系統名稱在專案內唯一，撞名時系統仍會建立並保留 Revit 自動產生的名稱，命名失敗的原因放在 SystemNameError（不會整批 rollback），你要求的原始名稱回報在 SystemNameRequested。回傳的 CommitStatus 是 Transaction.Commit() 的實際回傳狀態，Success 欄位同時要求 CommitStatus='Committed' 且所有風口都成功；CommitStatus 非 Committed 時 CommitError 會說明、且不會讀回任何流量或系統成員資訊（避免對已回滾的元素讀值）。TerminalCount 是輸入 terminalIds 的總筆數（不論成敗）；SuccessCount／FailureCount 分別是成功／失敗筆數，兩者相加等於 TerminalCount。FailureCount=0 不等於整體 Success=true——即使所有風口都解析成功，只要 CommitStatus 不是 'Committed'，Success 仍為 false，請兩個欄位一起看。本工具的 MCP timeout 為 30 秒且逾時不會回滾——若逾時，Revit 端交易仍可能已提交，請務必用 query_elements_with_filter 或 get_element_info 核對模型實際狀態後再重試。直接重試會失敗——第一次已提交時，設備與風口的 Connector 已隸屬該系統，本工具會在設備端直接中止、或全部風口都記為失敗後因無可用成員而整體報錯（與 systemName 是否重複無關；名稱撞名本身不會讓呼叫失敗，只會填 SystemNameError）。作用視圖為明細表時，Revit 會在每次模型變更後重算整張表，依 domain/tool-capability-boundary.md L17 實測這會顯著提高逾時機率，回傳的 PerformanceWarning 會提醒（不擋執行），建議先用 set_active_view 切到一般平面圖再執行；回傳附 ElapsedMs 供核對耗時。

增減 MEP 尺寸目錄（會修改模型設定）。規則:增無限制;減只能刪「模型中沒有任何元件在用」的尺寸,工具會自行跑用量盤點把在用的擋下並說明是誰在用。執行採四步:①列表(dryRun,預設 true)→②單一 Transaction 執行(可 Ctrl+Z)→③QC 重讀目錄逐筆比對→④偵測到誤刪自動以快照原樣加回。回傳一律附 RestorePayload(被移除尺寸的完整定義),供事後人工復原。新增管尺寸必須同時給 inner_mm 與 outer_mm(內外徑是水力計算依據,不由工具臆造);風管只需 nominal_mm。務必先用 get_mep_size_usage 確認用量。協定見 domain/mep-mechanical-settings.md。

執行 MEP 管線（連結模型）與 CSA 結構體（主模型）的碰撞偵測，使用 Curve-to-Solid 策略：MEP 抽中心線、CSA 保留實體、計算穿透線段。回傳每筆碰撞的入口/出口座標、貫穿長度、截面積、佔用體積，以及依系統/依 CSA 品類的統計摘要。

匯出 detect_clashes 結果為報表。format 可選 csv、json、both。預設輸出到桌面，檔名含時間戳。

把專案中已載入的可編輯族群另存為 .rfa 檔到指定資料夾,建立可重用元件庫。預設匯出管配件(OST_PipeFitting)與管附件(OST_PipeAccessory)。自動依類別建立子資料夾;subFolderBySeries=true 時再依族群名稱系列(CIP/DWV/碳鋼.../)細分。略過系統族群、現地(in-place)與不可編輯族群。

把 Revit 視圖輸出成 PNG 影像回傳給 AI 檢視（不需要使用者截圖）。可指定視圖名稱/ID，或用 focusElementIds 在「AI檢討_結果3D」視圖以剖面框框住指定元素後輸出，適合修改後目視確認或查看檢討結果。

取得 MEP 元素（管、風管、線管等）的接頭（Connector）資訊，包含座標、連接狀態、形狀等。

抽取元素的幾何資訊，支援主模型或連結模型元素。geometryType 可選 centerline（中心線）、boundingbox（範圍盒）、solid（實體統計）、all（全部）。連結模型的座標會套用 Transform。

列出當前專案中所有連結模型（RevitLinkInstance），含 LinkInstanceId、檔名、路徑、載入狀態、Transform 原點。用於碰撞偵測第一步：找到 MEP 連結的 LinkInstanceId。

一次盤點整個專案的 MEP Segment 與 Size 目錄（唯讀）。對應 Manage → MEP Settings 裡 Segments and Sizes 對話框的內容：每個管段（PipeSegment＝材質 × Schedule，如 Copper - K、PVC - Sch 40）各一份尺寸表，含 nominal / inner / outer 直徑與 Used in Size Lists、Used in Sizing 兩個勾選狀態；可一併回傳風管（Round / Rectangular / Oval）尺寸表（風管只有 nominal，Revit 的 duct inner/outer 是佔位值故不輸出）。這些資訊 Schedule 與 System Browser 都撈不到。所有尺寸以 mm 回傳，供台灣 CNS 尺寸對帳使用。全量 dump 可達數百筆，先用 summaryOnly=true 看全貌，再用 segmentName 鑽單一管段。

讀取 Manage → MEP Settings 裡「尺寸目錄以外」的所有設定頁（唯讀）：Duct/Pipe 的 Angles（fitting 角度用法與各角度勾選狀態）、Pipe 的 Slopes（坡度清單）與 Fluids（流體類型，可選溫度/黏度/密度表）、兩邊的 Calculation（空氣密度與黏度、network-based 計算、接頭容差）、尺寸命名與註記字串、標高文字（Centerline / Set Up / Flat on Top …）、以及 Hidden Line。角度以度回傳、長度以 mm 回傳，物理量另附以專案顯示單位格式化的字串。管段與尺寸目錄不在這裡，請用 get_mep_segments_and_sizes。

盤點模型裡「真的有元件在用」哪些 MEP 尺寸（唯讀）。這與 get_mep_segments_and_sizes 讀的「目錄裡列了哪些尺寸」是兩件事——目錄不知道自己有沒有被用，只看目錄就刪除等於盲刪。掃描來源包含直管/直風管的寬高與直徑，以及配件與附件的 Connector 尺寸（漏掃配件會把「只有變徑頭在用」的尺寸誤判成可刪）。管的用量以 Pipe.PipeSegment 精確歸戶到各 segment。回傳每個目錄尺寸的 usageCount 與 removable 旗標，另列 orphans（模型有用但目錄沒有的尺寸，屬「該增」的候選）。刪除任何尺寸前一定要先跑這支。方法見 domain/mep-mechanical-settings.md。

一次取得 Revit 目前狀態，不需要截圖：文件、作用視圖（含平面視圖範圍）、目前選取、樓層與標高、軸網、連結模型、主要類別數量、警告總數、變更序號 changeSeq。開始任何建模或檢討前先呼叫，用來確認 AI 對模型的認知是最新的。長度值單位 mm。

讀取 Revit 警告（依訊息分組，含數量與範例元素 ID）。修改模型後用 elementIds 只看受影響元素的警告，可提早發現重疊牆、重複實例、房間未封閉等建置錯誤。

取得模型變更紀錄（使用者手動或 AI 的每筆交易：新增/修改/刪除數量、類別、範例 ID）。把 get_model_snapshot 回傳的 changeSeq 當 sinceSeq 傳入，就能知道之後使用者在 Revit 改了什麼，避免拿過期狀態做決策。

回傳每個 Revit Space（OST_MEPSpaces）的代表點座標（mm）。這是本專案第一個支援 Space 品類的工具——get_room_info 等既有工具只吃 OST_Rooms，傳 Space 進去會 cast 失敗。供後續自動放置元件（如風口）使用。代表點依序嘗試 LocationPoint → BoundingBox 中心 → BoundingBox 內網格取樣，每一步都用 Space.IsPointInSpace 驗證是否真的落在空間內（凹形空間的 BoundingBox 中心可能落在空間外），全部失敗則回傳 null 並標示 PointSource='None'，不做靜默 fallback。也回傳 BoundedHeight（= Volume / Area，可用來估算前期天花高度）。未放置或未封閉的 Space 仍會列出，但標示 IsPlaced=false 且幾何欄位為 null；IsPlaced=false 時可再看 HasLocation 與 IsEnclosed 區分「根本沒放置」與「已放置但未封閉（unenclosed）」這兩種處置方式完全不同的狀況。

批次把族群實例放置到指定世界座標點，可放置後設定實例參數。這是本專案第一個不綁死品類的泛用放置工具——place_furniture 寫死 OST_Furniture、create_door/create_window 需要 hosting 牆，都無法放風口（Air Terminal）等 MEP 族群。placements 每筆優先用 typeId（FamilySymbol 的 ElementId）直接取用，不做名稱比對；未給 typeId 才走 familyName/typeName 名稱比對（支援「FamilyName: TypeName」複合寫法）。名稱比對採兩段式：給了 familyName 就只在該族群底下比對 typeName，命中多個會直接報錯要求改用 typeId，不會悶聲選第一個；familyName 為空才允許 typeName 全域比對，同樣命中多個會報錯。x/y/z 皆為世界座標，單位 mm，get_space_centroid 回傳的座標可直接餵入（歷史註記：2026-08-14 曾實測 z 是「相對所在樓層標高的偏移」而非世界座標，直接餵 get_space_centroid 的 Z 會整批高出一個樓層標高且無錯誤訊息；2026-08-15 已將 C# 端 z 語意改為世界座標，換算改在工具內部用 Level.ProjectElevation 完成，見下方 z 欄位的部署時滯警告；此偏移語意僅在單一模型的特定設備族群上實測過，可能為族群／放置型式相依，Revit API 文件並未記載此語意）。levelName 省略時的自動選層邏輯是取「ProjectElevation 最接近 z 且不高於 z」的樓層，z 改為世界座標後這段邏輯才自洽（此分支同樣未經 Revit 實測，見下方 levelName 欄位說明）。回傳結果的 LevelName 是實際採用的樓層，請與你給的 levelName 核對是否一致；並務必用回傳的 PlacedPoint（與 PlacedBBoxCenter，見下方）核對實際落點。rotation 為繞放置點鉛直軸旋轉的角度（度），預設 0。tag 是呼叫端自訂識別字串，原樣回傳供比對。整批只開一個 Transaction，單筆失敗不影響其他筆；若實例已建立但後續步驟（旋轉/設參數）才失敗，該筆結果仍會附上 ElementId 並在 Error 註明「實例已建立但後續步驟失敗」，避免孤兒元件追蹤不到。放置後、讀取旋轉軸與最終落點之前，工具會補一次 Regenerate（2026-08-14 實測某些族群如 Exhauster with Cabinet，放置後未 Regenerate 直接讀 LocationPoint 會拿到 (0,0,0)，即使 BoundingBox 證實位置正確；同批 AHU 沒有這個問題，屬族群相依）；加上參數設定完後的既有一次性 Regenerate，每筆 placement 在這兩個時點各至多一次、上限共兩次；另外每個尚未啟用的族群類型（FamilySymbol）在批次中第一次用到時會多觸發一次 Activate 後的 Regenerate，但只發生在該 symbol 第一次出現時，不隨 placement 筆數累加。批次規模較大時請沿用 domain/space-centroid-placement.md 的分批估算，避免撞破 MCP-Server 的 30 秒 timeout。回傳結果每筆附 PlacedPointSource：'LocationPoint' 代表 PlacedPoint 是讀到的實際落點（可用來偵測 Revit 放置時是否對點做了吸附/調整）；'RequestedFallback' 代表讀不到 LocationPoint、PlacedPoint 只是回聲你給的 x/y/z，此時不可用它判斷是否發生吸附。另附 PlacedBBoxCenter：取元件 BoundingBox 中心（mm），與 PlacedPoint 是兩個獨立訊號、互不補值——LocationPoint 因族群相依而失真時（如上述 Exhauster 案例），可用 PlacedBBoxCenter 交叉核對；BoundingBox 讀不到時為 null，不會用 PlacedPoint 頂替。PlacedBBoxCenter 是元件整體外接盒的中心，對非對稱族群本來就不等於插入點，且依 Revit API 文件該盒會納入 flip controls 等不明顯的幾何；交叉核對的用途是判斷量級是否合理（例如 PlacedPoint 回 (0,0,0) 而 BBox 中心落在預期位置附近），不是逐位比對相等。回傳逐筆 Success/Error 與整體成功/失敗計數。parameters 是放置後要設定的實例參數 {參數名: 值}；每個參數設定後會讀回兩個獨立欄位：WrittenBackDisplay（Parameter.AsValueString()，Revit 依專案顯示單位格式化的值）與 WrittenBackRaw（依 StorageType 取的內部單位原始值，ElementId 類參數若讀到有效 ID 就回該 ID、讀到「已設定但無效」則回 -1、真正讀不出來才回 null），兩者互不補值、各自可能為 null，務必併看才能判斷是數字寫錯還是單位換算錯——modify_element_parameter 走 Revit 內部單位，Set() 成功不代表寫進去的是你要的量（domain/tool-capability-boundary.md 的 lesson L16，實測表在該檔「寫入值／讀回值／比值」表格，記錄過「寫入 89.2 讀回 9093」的落差），這裡不做任何單位換算或猜測，只誠實回報寫進去之後實際是什麼，請自行比對 Requested 與這兩個 WrittenBack 欄位判斷是否正確。⚠️ 部署時滯警告（2026-08-15）：z 的世界座標語意是 C# 端的改動，需重新編譯部署 DLL 並重啟 Revit 才會生效；若你連到的 add-in 尚未更新，行為仍是舊版的「相對樓層偏移」語意，且不會有任何錯誤提示你版本不符。PlacedBBoxCenter 亦為本次新增欄位；若回傳結果中沒有這個欄位，即代表你連到的 add-in 尚未更新，z 仍為舊版的相對樓層偏移語意——這是唯一可用的版本判別訊號。首次使用本工具時請先只放 1 件，用回傳的 PlacedPoint 與 PlacedBBoxCenter 核對落點是否符合世界座標預期，確認無誤後再批次放置。

查詢指定連結模型中的元素，支援品類篩選、參數過濾、自訂回傳欄位。座標會自動套用連結模型 Transform，確保與主模型對齊。

唯讀掃描 MEP 管線穿越結構的開孔候選。沿用 detect_clashes 的 Curve-to-Solid 幾何核心，依明確的每側 clearanceMm 計算建議孔徑，並以 candidate / review_required 與 warningCodes 保守分流；不建立套管、開孔族群、標記或視圖圖形。

偵煙探測器設置分析：掃描當前視圖的探測器、空調出風口（FCU/冷風機）、房間，回傳各探測器的距出風口距離、距牆/樑距離、距天花板距離，以及各房間的探測器數量與樑區格數。供 JS 端進行五項法規判定。

無開口樓層判定：檢查樓層外牆有效開口面積是否 ≥ 樓地板面積 1/30。法源：消防§4 + §28③。

排煙窗檢討：檢查天花板下 80cm 內可開啟窗面積是否 ≥ 區劃面積 2%。窗型採推射/外推、推開/平開、橫拉、固定的明確分類，並可傳入專案係數與未知窗型假設；假設值會保留人工確認標記。法源：建技規§101① + 消防§188。

檢查樓梯淨高是否符合法規要求（190cm + 裝修厚度）

在視圖上繪製詳圖線（天花板線、有效帶範圍線等），可指定顏色和標籤。

建立填充區域（如排煙有效帶色塊），可設定顏色和透明度。

建立剖面視圖，面向指定牆面。可用於檢視窗戶與天花板的高度關係。

建立樓梯法規檢核剖面視圖（自動判斷長向走向以顯示踏板剖面）

建立帶有引線的文字標註 (專用於樓梯檢核標示違規位置)

在視圖上建立文字標註。

匯出排煙窗檢討 Excel 報告（.xlsx），含樓層總覽、房間明細、窗戶明細、改善建議、§101補充檢討（排風量提醒+中央管理室偵測）五個工作表。

取得樓梯梯段的真實實測寬度（透過 StairsRun.ActualRunWidth 屬性）

依照法規判定結果對偵煙探測器上色：綠=PASS、紅=FAIL、橙=WARN（出風口資料缺失）。

批次將多個 sheet 上的 titleblock 移動到同一個 anchor 座標。可用『referenceSheetNumber』指定要拷貝某張 sheet 上 titleblock 的位置，或用『referencePositionMm』直接給絕對座標。anchor 決定要對齊 titleblock bbox 的哪個角（top-left / top-right / bottom-left / bottom-right / center）。建議先 dryRun=true 預覽 delta，確認後再實際執行。觸發條件：使用者提到 titleblock 對齊、圖框對齊、把所有 sheet 圖框對齊到 X、change_element_type 後圖框沒跟著移動、align titleblock、move titleblock to match。

將指定視圖對齊到目標元素的 BoundingBox。2D 使用 CropBox（只調整 XY，保留原 Z 深度與 Transform）；3D 為舊客戶端相容入口，會轉交 set_3d_section_box 並使用真正的 View3D Section Box，不操作 CropBox。3D 可分別設定 XY、上方與下方 padding。viewId 不指定時使用 active view。

依指定順序排列圖紙上的視埠（僅限 DraftingView）。支援水平或垂直排列，邊緣對齊（edge-to-edge）。第一個視埠的位置作為錨點。可用 viewNames（view 名稱陣列）或 viewportIds（視埠 ID 陣列）指定順序，二擇一。

自動掃描專案中所有帶有 -1 後綴的圖紙（例如 ARB-D0417-1），並將其合併至主序列中（變成 ARB-D0418），後續編號會自動順延。

批次將指定的 ViewTemplate 套用到多個 views。支援透過圖紙（sheets）、view ID、view 名稱或名稱子字串來選取目標 views。可搭配 viewTypeFilter 篩選特定視圖類型。dryRun 模式可預覽變更內容而不實際修改。觸發條件：使用者提到批次修改 view template、套用視圖樣版、sheet 中的 view 改 template。

批次建立牆面套管剖面：以當前視圖的 BoundingBox 範圍過濾指定連結模型中的牆，再比對所有 MEP 連結模型的管附件（圓形套管）與風管附件（矩形開口），只對有開孔的牆建立剖面視圖。

計算給定 X 與 Y 網格範圍的邊界 BoundingBox 座標。可指定外擴偏移量 (offset_mm)。

管理相機的具名「視角版本」（與相機管理面板右鍵「視角版本 ▸」同一段程式碼）。版本存在相機視圖的 Extensible Storage（JSON：眼睛位置、前方向、上方向、裁剪框與其 Transform、遠裁剪），同事開同一個 .rvt 也能切換。action=list 唯讀列出；save 以 name 儲存目前視角（同名覆蓋）；restore 以一個交易「還原相機視角：<名稱>」套回該版本（面板已載入時相機標記會自動更新）；delete 只移除該筆版本資料，不刪除任何模型元素。回傳目前相機姿態與全部版本（眼睛 mm、水平角、俯仰角、裁剪框尺寸、遠裁剪）。觸發條件：相機版本、儲存視角、還原視角、A 案 B 案視角、camera version。

把指定視圖（省略 = 目前作用中的視圖）匯出成點陣圖並直接回傳影像，讓 AI 看得見 Revit 畫面，不必再請使用者手動截圖。用於：確認一項圖形設定實際長什麼樣、判斷 hatch 密度與配色、排查「明明設了卻看不到」的問題、驗收批次操作的結果。只讀模型、只寫系統暫存檔（預設用完即刪），不異動 Revit 模型。明細表（Schedule）與瀏覽器類視圖無法匯出會直接報錯；視圖樣板本身也不行。影像過大時會自動降一階解析度重匯並在 Warnings 說明。觸發條件：使用者提到截圖、擷取畫面、看一下畫面、這樣對不對、幫我確認圖面、screenshot、capture view、或需要目視排查顯示問題。

把一台透視相機複製到另一個樓層（同平面位置、同離樓板高度、同方向與視野），與相機管理面板「複製到其他樓層」／清單改樓層同一段程式碼；新名稱「原名 - 樓層名」，重名自動加序號。原相機與其 Key Plan 視圖不變。回傳新相機 id 與名稱。觸發條件：複製相機、相機複製到樓層、copy camera。

從來源 .rvt 檔案複製圖紙到目前開啟的專案。讀取來源的 sheet/viewport/view metadata，在目標專案中重建 sheets、匹配或建立 views、放置 viewports 並同步設定。View 依四級分類處理：Tier 1（FloorPlan/CeilingPlan）可自動建立；Tier 2（Section/3D/DraftingView）可部分建立；Tier 3（Legend/Schedule）只匹配不建立；Tier 4（Elevation/Callout/AreaPlan）回報 manual_action_required。衝突項目必須在 conflictResolution 中指定處理方式。

為一台透視相機建立或更新圖紙「Key Plan-<相機名>」（與相機管理面板「一鍵出圖紙」同一段程式碼）：左側約 55% 放透視圖，右欄由上而下放 Key Plan 平面／剖面／等角（列高依內容長寬比分配）；可繪區＝圖框在圖紙上的外接框內縮邊界，再扣掉圖框標題欄（分析圖框線；偵測不到＝橫式保留右側 20%）。本工具的 Key Plan 視圖自動改為放得進格子的最細標準比例（1:20–1:200），出圖用透視複本等比放大裁剪框填滿格子約 90%（FOV 不變）；視埠類型沿用專案既有、會顯示標題的類型，不新建。相機還沒有 Key Plan 視圖時先執行一鍵 4 視圖。已在本相機圖紙上的視埠重新排版；透視圖若已在其他圖紙上，改放（或沿用）出圖用透視複本「<相機名>-Key Plan 圖紙」並同步到原相機的方向／裁剪／遠裁剪；其他視圖在別張圖紙上則回報並略過。回傳圖紙 id／編號／名稱、圖框來源、可繪區與每個視埠的 id、狀態、中心與尺寸（圖紙座標 mm）、是否超出格子。寫入模型（交易「建立相機圖紙」），不刪除任何使用者元素。觸發條件：相機出圖、一鍵出圖紙、相機圖紙、camera sheet。

依據指定的母視圖 ID 與 BoundingBox 邊界，批次建立並裁切從屬視圖 (Dependent View)。

以指定的 FloorPlan 視圖作為範本，在多個 Level 上批次建立新的樓層平面視圖。複製範本的 ViewFamilyType、View Template、Phase、Phase Filter。適用於補齊缺漏的正式建築圖系列（例：A- 前綴的樓層平面圖）。已存在同名 view 時會跳過並在回傳的 Skipped 清單中記錄原因。

依牆面開孔位置自動建立平行剖面視圖。自動偵測牆上的套管族群，以開孔群組為單位裁剪剖面範圍；支援長牆分割（相鄰開孔 > 3m 則各自建立獨立剖面）、房間方向自動判定。無開孔時建立整面牆的全寬剖面。

依據指定的清單批次建立空的圖紙。

診斷工具：dump 一個 viewport 的所有座標資料（boxOutline、cropbox、view origin、scale 等）。用於反推 Revit 內部 cropbox vs viewport 的座標映射規則。指定 viewportId 或 viewId 其中之一。

Duplicate one or more views with detailing (ViewDuplicateOption.WithDetailing keeps view-specific detailing/annotation), optionally renaming them and copying the crop region from the source view. Typical use: create the '高於6m牆標示' tall-partition markup views from a base plan.

取得專案中所有的圖紙清單，包含 ID、編號與名稱。

讀取 3D 視圖／相機的實際位置：眼睛的 XYZ 座標（內部原點座標系 mm）、在哪一層之上、離各樓層多高、視線俯仰角（0° = 水平）。同時讀出性質面板的 Eye Elevation / Target Elevation 參數，並用實際眼睛高度反推該參數的 0 點，逐一比對內部原點、專案基準點、測量點與每個樓層，回報它跟哪一個一致。用途：排查「在 1F 平面放相機，Eye Elevation 卻是負值」這類看不出基準的問題，以及確認人視高是否真的在樓板上方 150–175 cm。唯讀。viewId 可給 3D 視圖本身，也可給平面上選到的相機元件；省略時用目前作用中的 3D 視圖。觸發條件：使用者提到人視高、相機高度、camera、eye elevation、target elevation、視點高度、目標高度、透視圖高度不對、相機在地下。

取得指定圖紙上所有視埠的詳細資訊，包含中心點座標、邊界框（MinX/MinY/MaxX/MaxY）、寬度與高度（mm）。若不指定 sheetId，則使用當前作用視圖（必須是圖紙）。

取得專案中所有可用的圖框（Title Blocks）類型。

讀取任一視圖的範圍與表現設定：視圖類型、比例、裁剪框（啟用／可見、Min/Max 與 Transform，mm）、註解裁剪與四邊外擴、3D 視圖的 Section Box／眼睛／方向／透視遠裁剪、剖面遠裁剪、Display Model、詳細等級、視覺型式、視圖樣板、被隱藏的類別（名稱與數量）、各連結模型在此視圖的顯示設定，此視圖專屬的詳圖線／填滿區域／文字註記數量，以及 Scope Box（id／名稱）、方位、圖紙上的標題、目前可見的其他視圖標記數（剖面／立面／詳圖索引 viewer 與立面標記）。唯讀。觸發條件：視圖範圍、裁剪框、Section Box、視圖為什麼看不到、view extents。

讀取平面類視圖的視圖範圍（View Range）四個平面設定：topClip（頂部）、cutPlane（剖切面）、bottomClip（底部）、viewDepth（視圖深度），各含所指樓層與偏移量(mm)。排查「元素在模型裡、類別也開著、卻在平面圖看不到」時的第一順位檢查——最常見成因就是該元素落在 View Depth 之外（例如地形、基礎位於樓板下方）。同時回報該視圖的 View Range 是否被視圖樣板鎖住。唯讀。觸發條件：使用者提到視圖範圍、view range、視圖深度、view depth、剖切面高度、cut plane、平面圖看不到某個東西、平面圖顯示不出來。

取得專案中所有視埠（Viewport）與圖紙（Sheet）的對應關係。可用於查詢特定視圖被放置在哪張圖紙上。

列出專案中所有透視相機，逐台回報相機管理面板看到的同一份資料：所在樓層（室內＝眼睛所在房間的樓層、室外＝眼睛正下方的建築樓層，附判定來源）、離樓板高度（cm 與 mm）、水平角（0°=+Y 順時針）、俯仰角、視野角（左／右／下／上邊界與水平／垂直總角）、遠裁剪、室內／室外與眼睛所在房間、相機放置時記錄的平面、③ 位置圖底圖挑選器會選哪張平面與步驟、已連結的 Key Plan 平面／剖面／等角視圖 id（KeyPlan.PlanLevelMismatch＝平面的樓層與相機目前樓層不符，重跑一鍵 4 視圖會重建）、剖面方向與剖面位置設定、這台相機是否啟用「剖面轉 90°」（SectionOrientation.Rotate90）、剖面是否被手動移過。唯讀。觸發條件：相機清單、相機管理、Key Plan、人視高檢查、camera list。

批次移動 viewport 標題（label line + text）的位置。支援兩種模式：(1) below-view-center: 將標題置中放在 view 正下方（自動計算 cropbox 底邊中心 + gapMm 距離）；(2) reset: LabelOffset 還原為 XYZ.Zero（Revit 預設位置，通常在 viewport 左下角）。識別目標 viewports 與 position_viewports_on_sheet 相同：viewportIds / viewIds / viewNames / viewNameContains，可加 sheetNumbers / viewTypeFilter 過濾。觸發條件：使用者提到 viewport 標題位置、視埠標題、view title 對齊、把標題挪到視圖下方、reset title position。建議搭配 dryRun=true 先預覽。

批次將 viewports 移動到 sheet 上的指定位置。位置是用「view 的某個錨點 + sheet 上某個參考點 + offset」三段組合定義。例：『所有平面圖的左上角』移到『title block 左上角 X+10mm Y+10mm』。識別目標 viewports 有多種方式（viewportIds / viewIds / viewNames / viewNameContains），可結合 sheetNumbers 和 viewTypeFilter 進一步過濾。建議搭配 dryRun=true 先預覽位移，再實際執行。觸發條件：使用者提到 viewport 位置、視埠定位、移動視埠到圖框、view 對齊圖框、批次定位、align viewport to titleblock、move viewport。

開啟來源 .rvt 檔案並讀取所有圖紙 (sheets)、視埠 (viewports)、視圖 (views) 與 ScheduleSheetInstance 的 metadata。同時偵測與目標檔（目前開啟的專案）的衝突。回傳結構化 JSON 供 AI agent 預覽與規劃後續 copy_sheets_from_file 操作。不修改任何檔案。

對一台透視相機執行相機管理面板的「一鍵 4 視圖」核心（建立或更新 Key Plan 平面／剖面／等角三張視圖＋相機標記），與面板同一段程式碼，不經面板 UI。回傳三張視圖的 id、名稱、比例、範圍（平面裁剪框、剖面裁剪框、等角 Section Box，mm）、各視圖內本相機標記元素數（依角色分組），以及關鍵判定（室內／室外、使用的房間、本層頂、扇形半徑、實際剖面方向、是否啟用剖面轉 90°、等角範圍模式、等角近側牆切掉哪兩面）、實際生效的相機標記型式，與裁剪框讀回不符預期（> 1 %）的警告。複製來的平面會先解除 Scope Box、改專案北、圖紙上的標題改為「Key Plan 平面」；平面／剖面隱藏其他剖面／立面／詳圖索引標記（平面保留本相機剖面）。寫入模型（一個交易「建立相機 Key Plan」），不刪除任何使用者元素。室內相機的等角預設切掉觀看者側兩道牆（近側兩面＝房間邊界往內 100 mm，遠側維持房間 +0.6 m）。觸發條件：一鍵 4 視圖、Key Plan、相機平面剖面等角、run keyplan。

建立或更新相機管理的每層總覽平面「Key Plan-總覽-<樓層名>」（與面板「一鍵 4 視圖 ▾ → 更新樓層總覽」同一段程式碼）：複製該樓層由底圖挑選器選出的平面、套淡化表現法，裁剪＝該層室內相機視野扇形聯集 +3 m（有室外相機時再聯集底圖的建築範圍），把該層每台相機的 B 型標記（眼睛圓圈、視線、扇形、眼睛楔形）與名稱文字畫在同一張平面上；重跑更新同一張、不重複。複製來的平面會先解除 Scope Box、改專案北、圖紙上的標題改為「樓層總覽 <樓層>」，並隱藏其他剖面／立面／詳圖索引標記。回傳每層的視圖 id、名稱、相機數與名稱、底圖來源、裁剪範圍（mm，讀回視圖的實際值，另附預期值與不符警告）與比例。室內相機以房間所在樓層分組。寫入模型（一個交易「更新樓層總覽」），不刪除任何使用者元素。觸發條件：樓層總覽、相機總覽平面、所有相機畫在一張平面、camera overview。

縮放圖紙上所有 DraftingView 中表格的行高（僅 Y 軸），寬度不變。以每個 view 的上邊緣為錨點，將所有 DetailCurve 和 TextNote 的 Y 座標按比例縮放。

縮放圖紙上所有 DraftingView 中表格的寬度（僅 X 軸），高度不變。以每個 view 的左邊緣為錨點，將所有 DetailCurve 和 TextNote 的 X 座標按比例縮放。

將非樣板 3D 視圖的真正 Section Box 對齊到指定元素的完整 XYZ BoundingBox，並關閉 CropBox 避免雙重裁切。可分別設定水平、上方與下方 padding，並可自動納入與目標底面相接的完整支承樑，可用 upperStructureMode 選擇只看當層，或延伸到上層樓板底以顯示上層樑但不含樓板。若只需清理由舊流程誤啟用的 3D CropBox，設 clearCropOnly=true，此時可省略 elementId。

修改透視相機的姿態，與相機管理面板清單就地編輯走同一條程式路徑（一個交易「編輯相機」）：可給離樓板高度 cm、水平角、俯仰角、平面 X/Y（cm，內部原點座標）、遠裁剪 cm，至少一項；未給的欄位維持原值（沿用相機目前實際值）。回傳修改前後的值與 Timing {transactionMs, refreshMs, totalMs}（編輯快速路徑：小交易＋立刻重繪透視圖）。Key Plan 標記／剖面於最後一次編輯 800 ms 後依變動分級自動更新（高度只重畫剖面標記；換樓層／房間才完整重算），不在回應中同步執行。觸發條件：調相機高度、改相機角度、移動相機、set camera pose。

批次將 ScopeBox 套用到一組 views（透過設定 view 的 VIEWER_VOLUME_OF_INTEREST_CROP 參數）。被套用後 view 的 CropBox 會自動跟隨 ScopeBox 的範圍，以後 ScopeBox 移動或調整大小時 view 會跟著更新。三選一指定目標 views，優先序：viewIds（最精確）> viewNames > viewNameContains。可選 viewTypeFilter 進一步篩選。View template、不支援 ScopeBox 的 view（Schedule, Legend 等）會自動跳過並記錄在 Skipped 中。觸發條件：使用者提到 scope box、範圍框、套用 scope box、批次設定 scope box、scopebox to views。

直接設定非樣板 3D 視圖（正交或透視）的 Section Box，不需目標元素。二擇一：(A) minMm＋maxMm＝世界座標（內部原點，mm）軸向對齊的絕對範圍；(B) offsetsMm＝在「目前」Section Box 各面上的相對位移（正＝往外擴、負＝往內縮，可只給部分面；目前框有旋轉時在框自身座標系內位移）。enable 預設 true（開啟 Section Box）。與 set_3d_section_box 相同會關閉正交視圖的 CropBox 避免雙重裁切（透視視圖必須保留裁剪，不動）。每軸必須 min < max。單一交易「設定剖面框」，回傳前後的世界座標 min/max 與尺寸。

設定平面類視圖的視圖範圍。四個平面各自獨立指定，只給要改的即可。level 可填樓層名稱，或四個特殊值：Unlimited（無限延伸，View Depth 最常用）、Level Above、Level Below、Current（視圖關聯樓層）。offsetMm 是相對該樓層的偏移，負值往下。典型用途：把 viewDepth 設成 Unlimited，讓樓板下方的地形或基礎在平面圖顯示出來。視圖範圍被視圖樣板鎖住時會直接報錯而不是靜默失敗；完成後會回讀實際落地的值作為驗收證據。觸發條件：使用者提到改視圖範圍、調 view range、改視圖深度、view depth 設成無限、讓平面圖看到下面的東西、剖切面調高調低。

在 CropBox 自身座標系中平移視圖的 CropBox。dx 正值往右、dy 正值往上（單位公釐）。viewId 不指定時使用 active view。

補丁工具：為 target 中已存在的 sheets 從 source 同號 sheet 補齊 custom parameters（例如修補先前 copy_sheets_from_file 沒帶到的 sheet folder/圖集 / Discipline / 繪圖人 等）。**不會重建 sheet、不會動 viewport**，只比對同 SheetNumber 並複製 custom parameters。同名 + 同 StorageType 的 writable parameter 才會被複製，ElementId 類型跳過。觸發條件：使用者提到 sheet folder 缺失、補圖集、修圖紙分組、sheet 沒歸入 folder、補 sheet metadata、sync sheet parameter、batch update sheet parameter。

Automatically fix fill patterns on rotated viewports so hatch orientation follows the rotation correctly. Takes no parameters.

批次自動標註牆段尺寸（不需要 Room）。三種模式：overall_bbox（外圍兩條總長串：top 邊沿 X、right 邊沿 Y，預設）/ chained（同列同排共線牆串成 string dimension）/ per_wall（每牆一條長度標註）。標註用 DetailCurve 當 reference，不抓牆面，但建模一次性場景剛好。常用於 sketch-to-revit 蓋完牆後自動補尺寸。

Batch-create RC filled-region stickers across multiple views, or across every placed viewport on the given sheets.

Convert drafting fill patterns to model fill patterns in the document so hatching stays fixed to the model rather than the sheet. Takes no parameters.

批次複製詳圖項目（DetailCurve、TextNote、FilledRegion、DetailComponent、Dimension）從來源視圖到一或多個目標視圖（同一專案內）。支援 DraftingView 與 model view。

指定詳圖項目族群，複製並設定新名稱（圖紙編號-圖紙名稱-詳圖名稱），同時自動填寫 詳圖圖號、圖說名稱、詳圖名稱、詳圖編號 等類型參數。

使用房間邊界框自動標註房間淨尺寸（保證100%覆蓋率）

使用射線偵測 (Ray-Casting) 建立尺寸標註。從指定原點向正反方向發射射線，偵測牆面並建立標註。

⚠️ 若目的是把 Excel 內容繪製到 Revit view，**請改用 `import_excel_to_drafting_views`**（一站式、自動 viewport 還原）。本工具僅複製已存在的 seed legend，**不會繪製任何內容**，使用情境僅限：(1) 需要 Legend View 而非 Drafting View 以便在多張 sheet 重複放置同份內容；(2) 純複製空白 legend 模板。從 seed legend 批次複製出多個 legend 視圖。Revit API 不支援憑空建立 legend，必須先在樣板/專案中手動放置一個 seed legend（建議命名為 _SEED_BLANK）。

Create RC (reinforced-concrete) filled-region stickers in the active view by detecting RC element outlines, drawn with an invisible line style so only the hatch shows.

Create filled regions covering rooms in a view (e.g. to colour/mark rooms), optionally clearing previously created markers and setting colour and transparency.

在視圖上依順序放置編號 TextNote，對象可以是任意元件（車位、設備、開口皆可）。支援數字（1,2,3）與字母（a,b,c）兩種序列，搭配 prefix 可組出 A1、A2；可選擇跳過含 4 的號碼。順序取自 elementIds 的給定次序，或依 Y 上到下、X 左到右自動排序。

在 Revit 中建立一個新的視圖明細表（Schedule/Quantities）。可以指定名稱、品類以及要包含的欄位。

找出當前視圖（或指定視圖）中重複的 detail element（同 Type + 位置量化後相同），保留 Detail Group 內的副本，刪除 group 外的副本。涵蓋 DetailComponent / DetailCurve / FilledRegion / TextNote / Dimension。只認 Detail Group（OST_IOSDetailGroups），不認 Model Group。預設 dryRun=true 只列清單；確認後設 dryRun=false 才實際刪除。邊界情形（全部都在 group 中、或全部都不在 group 中）會回報但不動。

門窗圖例工具。mode=list 列出專案中已使用的門/窗型；mode=create 以 seed Legend 複製生成 A+ managed 圖例；mode=update 更新既有門窗圖例；mode=migrate 預覽或套用 legacy item 的 A+ ownership migration；mode=scaffold_template 一鍵自動搭建空白門窗圖例樣板視圖（自動畫格線、放佔位文字與圖例）。

一次讀取全專案所有標籤（Tag）資料。涵蓋 IndependentTag（門/窗/梁/柱/牆/材料/多類別標籤）與空間標籤（房間 RoomTag、面積 AreaTag、空間 SpaceTag）。每筆重點回傳：標籤頭座標 TagHeadPosition{x,y,z}（mm）、標註對象 TaggedElements（哪根梁/柱/房間，含 ElementId、類別、族群、類型、Mark；被標註者若在連結模型會標示來源與引線末端座標）、TagText 顯示文字、HasLeader、Orientation、所在視圖 ViewId/ViewName。可用 viewName 只掃單一視圖、category 篩選標籤類別（子字串比對，如「門」「柱」「房間」）、includeSpatialTags 關閉空間標籤、maxCount 限制數量。

查詢專案中的詳圖元件（Detail Components）實例。可依族群名稱篩選，回傳每個實例的 ID、族群名稱、類型名稱、所屬視圖及參數。

原子化命令：讀 Excel → 對每張有列印範圍的 worksheet 建立 Drafting View → 畫框線（merge-aware）→ 寫文字。固定 viewScale=1:1、textSize=3mm、rowH=4.5mm、colW=30mm。Claude 端只送檔案路徑與 sheet 清單，所有座標計算、Revit Transaction 都在 C# 內完成，token 用量極低（25 sheet ≈ 1.5K）。已自動正規化 \r\n → \n。**Overwrite 時會在 doc.Delete 之前先擷取舊 view 在所有 sheet 上的 viewport 中心點，重建後自動 Viewport.Create 放回原位**，使用者不需再到 UI 手動補放。回應新增 ViewportsRestored 計數與 ViewportFailures 列表（個別失敗不會影響整批 Commit）。

列出目前 Revit 專案可用的 DimensionType。door-window-legend-tools create/update 需要先由使用者選擇 dimensionTypeName，再把對應 dimensionTypeId 傳回。

列出專案中的 FamilySymbol（族群類型）。可依名稱篩選，回傳 ID、類型名稱、族群名稱、類別。用於查詢可用的詳圖項目族群。

列出目前 Revit 專案中的 Legend 視圖與其中的門窗 legend component 數量。door-window-legend-tools update 需要先由使用者選擇 viewName。

列出目前專案中所有可讀取的明細表（排除樣板、圖框修訂表）。回傳每張表的 ElementId、名稱、品類、列數與欄數，供儀錶板分類與展開使用。

列出 seed 候選資料。這版支援 seedType=legend，會回傳所有非樣板 Legend 視圖與其中 Legend Component 數量。此 tool 的結果必須顯示給使用者選擇；assistant 不得根據清單自動決定 seed，也不得在使用者未選 ViewName 前自動重試 create。

在多個 DraftingView 中，依文字內容子字串搜尋 TextNote 並批次平移。適用於跨圖面統一調整法規文字位置。

⚠️ 若目的是把 Excel 內容繪製到 Revit Drafting View，**請改用 `import_excel_to_drafting_views`**（一站式命令，內部自帶 Excel 解析、layout、wrap、viewport 還原，token 省 95%+）。本工具僅用於純讀取/探索 Excel 結構，**不會建立任何 view 或畫任何元素**。讀取 Excel 檔案中的 named table（或整張 worksheet），僅回傳落在 worksheet 列印範圍 (PrintArea) 內的儲存格內容。沒有設定列印範圍的 worksheet 會被略過。預設不傳 borders 陣列以節省 token；若需粗細資訊請傳 includeBorders=true。summary=true 模式只回每張表的維度與是否含非 Thin 邊框，適合大量 sheet 的初探階段。

讀取單一明細表的完整表格內容（欄位標頭 + 逐格 body 資料，忠實呈現 Revit 畫面顯示的文字）。用 scheduleId 或 scheduleName 指定。

依幾何位置批次重編停車格編號並寫入參數（預設「備註」）。汽車／機車／大客車各自獨立起號，先依 Y 由上到下分排、同排依 X 由左到右排序。可指定起點元件把某一格釘為該類別的第一號。預設 dryRun=true，必須先看過排序結果再正式寫入。

自動同步所有詳圖元件的類型參數（詳圖圖號、圖說名稱）與其所在圖紙的編號和名稱。僅更新類型名稱已匹配圖紙編號的元件，不會影響共用標準詳圖。

將既有材質（透過名稱查找）套用到指定的 Type。不建立新材質。用於復原或批次指派既有材質（例如把 9 個柱子從 'White_MCP' 改回 '鋼 AISI 1015'）。

批次修改指定 Type 的材質（複製原材質模式）。為每個 Type 的原材質建立複本 '{原名}_{suffix}'，只修改複本的 Appearance Asset（diffuse color），保留 Graphics 顏色與原材質其他屬性。影響 Enscape/V-Ray 等渲染引擎，但平面圖切割填充和 Revit Shaded 3D 維持原材質外觀。牆/樓板只修改 CompoundStructure 最外層（Layer 0），其他層保留。已含 suffix 的材質會被冪等跳過。

清除元素在指定視圖中的圖形覆寫。

在 Revit 專案材質庫 (OST_Materials) 中實體發動 Duplicate/Create 獨立建立純淨綠建材或測試 Material (如 'test材質' 或 'GBM0104106_水性漆(居室外用)')。

在 Revit 專案資料庫 (OST_Materials) 中建立獨立 Material 並關聯獨立 AppearanceAssetElement。

遵循 Domain 規範建立純淨獨立的 Revit Material（不加前綴、絕不上預設牆字串）。

通用多材料構造層工具：複製指定 ElementType（Wall/Floor/Ceiling 皆可），依任意數量的材料清單建立獨立綠建材 Material，依序套入 CompoundStructure 各層。跟 duplicate_element_type（寫死 2 個材料的牆體 Finish1/Structure/Finish2 三明治）不同，這裡層數、材料、層位機能完全由呼叫端指定，適用於 2 個以上材料、或非 Wall 品類的單一組合情境（例如地板：飾面地磚 Finish1 + 隔音緩衝墊 Substrate + 混凝土 Structure 三層）。layers 陣列請依實際構造由上到下（或由外到內）的順序排列。

情境 2「各別建立」：複製指定 ElementType（Wall/Floor/Ceiling Type）建立新類型，並實體建立一個純淨綠建材 Material，指派到新 Type 的全部 CompoundStructure 層。Type 名稱與 Material 名稱使用同一組字串（GBM編號_材料名稱），不套 TABC_ 前綴。用於一個 Set 裡每個材料各自獨立建 Type 的情境（例如地板材料各別建立），跟 duplicate_element_type（牆板+塗料兩材料合併一個 Type 的單一組合情境）是不同情境，不要混用。

建立視圖篩選器（ParameterFilterElement）並套用到指定視圖，含圖形覆寫。這是「規則式」上色：規則命中哪些元素就套哪種表現法，新增的元素會自動納入，改參數值就改顏色——與 override_element_graphics 的逐個元素覆寫不同，後者不是規則、不涵蓋新元素、也看不出意圖。回傳 MatchedElementCount 讓你立刻知道規則在該視圖內實際命中幾個元素（0 代表規則沒抓到東西，通常是參數值寫錯或元素不在視圖範圍內）。參數名稱請先用 get_filterable_parameters 確認。同名篩選器存在時預設報錯，帶 overwriteExisting=true 才會沿用並更新。視圖若被視圖樣板控制 V/G 篩選器，會在 Warnings 提醒（不擋執行）。

複製指定 ElementType 建立新類型（如綠建材 Set 專屬牆類型），並依指定的飾面/結構材質名稱實體建立 2 個獨立 Material，套入 Finish1/Structure/Finish2 三層 CompoundStructure 構造層。用於將牆板＋塗料組合 Set 導入為單一牆體 Element Type。

單純複製指定 ElementType（Wall/Floor/Ceiling 皆可），不修改 CompoundStructure、不建立或指派任何 Material，新類型與來源類型構造層完全一致。用於 TASK-005.5 情境 5「單選非模型綠建材」路徑 A：先複製出一個不影響既有元件的新 Type，再另外呼叫 set_green_material_type_parameters 寫入 adhesive/sealant/waterproofing 等 Construction 欄位。與 duplicate_element_type（寫死板材+塗料兩種材料）、create_single_material_type/create_multi_layer_type（會重新指派構造層材質）不同。

查詢 Project Materials（材質瀏覽器）清單中所有現存材質，用於在建立材質後主動驗收確認是否已實體存在。

列出指定類別可以拿來當「視圖篩選器規則」的參數清單（唯讀）。回傳的就是 Revit 篩選器對話框下拉選單的實際內容，用 ParameterFilterUtilities.GetFilterableParametersInCommon 取得，所以不必憑印象猜某個參數能不能拿來篩（例如樓層型的 Base Constraint / Reference Level 是否可用）。每筆附 StorageType 與該型別支援的運算子，可直接餵給 create_view_filter。多個類別時回傳的是「共同可用」的交集。專案中若該類別沒有任何實例，StorageType 會是 None（規則仍可建，但建議先放一個元素再查）。

列出指定視圖中每個連結模型（RevitLinkInstance）的 Display Settings：ByHostView / ByLinkView / Custom，以及它在該視圖是否被隱藏。關鍵欄位是 HostFiltersApply——為 false 時，主檔的視圖篩選器與類別覆寫完全不會作用在該連結的元素上，這是「主檔怎麼設、連結都沒反應」最常見也最難從畫面看出來的成因。唯讀。觸發條件：使用者提到連結模型的顯示設定、Revit Links 頁籤、By Host View、連結沒反應、篩選器對連結無效、link display settings。

讀取材質「圖形」頁籤的設定：是否使用彩現外觀著色、著色顏色、透明度，以及表面／切割的前景與背景填充樣式與顏色。唯讀。作用在目前作用中的文件（要讀連結檔的材質，須先把該連結檔開成作用文件）。觸發條件：使用者問材質顏色、著色顏色、材質填充圖案、材質 hatch、為什麼這個材質在平面圖是這個顏色。

查詢指定類別中所有元素類型及其目前材質資訊。回傳每個 Type 的 ID、名稱、族群、實例數量、目前材質。用於在批次修改材質前，讓使用者確認要修改哪些類型。

唯讀診斷『這張圖現在為什麼長這樣』：依 Revit 覆寫優先序一次回報視覺型式 (DisplayStyle)、套用中的視圖樣板與它鎖住的參數、視圖篩選器（含是否抓到目標元素、是否把它隱藏）、指定元素的個別圖形覆寫、其品類覆寫與可見性，以及該元素材料的 Surface/Cut 填充樣式與顏色。Verdict 會列出『所有』命中的成因並依優先序排序（不是只回第一個），涵蓋填滿顏色、線色、線寬、半色調、透明度與隱藏，每筆附影響範圍與修正方式。用於接手他人模型時追查表現法被誰改掉，省去逐層手動比對。不開 Transaction、不修改模型。

取得專案中所有視圖樣版的完整設定。可用於視圖樣版比對與整併分析。

在指定視圖中隱藏元素。使用 View.HideElements() API，支援單一或批次操作。

門窗／獨立元件 RFA 綠建材導入（TASK-005.7 / domain/GM_rfa-family-injection.md）：以使用者指定的既有相似 FamilySymbol 為基底，開啟該家族文件 → 立即另存可復原備份（規則2，先於任何修改）→ 在家族文件內新增一個 Type，絕不改動來源 Type（規則1）→ 寫入 Identity Data 與 GreenMaterial_Mat1_* 共享參數、嘗試寫入 GreenMaterial_Certified 全域欄位（best-effort，部分家族會被 Revit 拒絕新增此 YESNO 欄位，屬已知限制，失敗不影響 Mat1 資料）+ 遮陽係數/隔音等級門窗專屬欄位（規則3）→ 另存為新家族檔名 → LoadFamily 載回專案，且在同一個 Transaction 內做載入前後同名家族 Type 參數簽章快照比對，一偵測到非目標 Type 被異動就整批回滾並報錯，不會靜默覆蓋（規則4）。單一原子呼叫涵蓋整個家族文件生命週期（開啟→備份→編輯→另存→關閉→載回），因為家族文件物件無法跨多次 MCP 呼叫保持開啟。呼叫前必須已由使用者明確指定 sourceTypeId——規則1禁止 AI 自行臆測或無型錄依據挑選基底 Family。

列出專案中所有填充樣式（FillPatternElement）的名稱、ID 與 Model/Drafting 類型。在指定任何 hatch 之前應先呼叫這個工具確認名稱，不要憑印象猜——create_view_filter 的 patternName、以及材質表面樣式都吃這裡的名稱。Model 樣式隨視圖比例縮放（實際尺寸，地形與材質紋理用這種）；Drafting 樣式在圖紙上固定大小。唯讀。觸發條件：使用者提到填充樣式、hatch、剖面線、網格線、fill pattern、有哪些樣式可以選、或要設 hatch 但不知道名稱。

在指定視圖中覆寫元素的圖形顯示（填滿顏色、圖樣、線條顏色等）。

遞迴搜尋新的材料影像資料夾，依完整檔名（含副檔名、不分大小寫）重新連結目前作用中 Revit 文件內遺失的 Appearance Asset 貼圖。呼叫前必須取得使用者提供的資料夾路徑；若使用者尚未提供，請先要求使用者貼上新的材料影像根資料夾路徑，不要猜測或自行挑選。有效連結保持不變；同名多檔只回報衝突，不自動選擇。dryRun=true 只預覽，不修改模型。

把篩選器從指定視圖移除；deleteFilter=true 時一併從專案刪除該篩選器本身。用於還原 create_view_filter 的變更。以 name 或 filterId 指定其中之一。

在指定視圖中隱藏或顯示整個類別（同時影響主模型與連結模型）。使用 View.SetCategoryHidden() API。

將綠建材共享參數 Schema（GreenMaterial_SharedParams.txt，Mat1~Mat6 六槽位 + Construction 群組共 67 個欄位）實體寫入指定 ElementType 的 Identity Data。參數須已透過 load_shared_parameters 綁定至該 Type 所屬品類（如 Walls），否則對應欄位會列在回傳的 MissingParameters 中。Mat1=主體/牆板，Mat2=面材/塗料，Mat3=附屬/膠材（僅有基本欄位，無 TVOC/Formaldehyde/CNS），Mat4/Mat5/Mat6=追加構造層（欄位與 Mat1/Mat2 同樣完整）。一個 Set 有幾種材料就只傳幾個 matN 物件，其餘留空，不必寫滿 6 組；哪個材料進哪個槽位請依 GM_generate_revit_injection_plan.py 產出的 plan['materialSlotAssignment'] 決定，不要自行猜測順序——非幾何輔助材料（接著劑/填縫劑/防水材料）一樣要填一個 matN 物件（Mat 槽位記錄的是「這個元件用了哪些綠建材」的完整清單，不是只有物理構造層才算數），另外再用 adhesive/sealant/waterproofing 額外補記它們的施工用途，兩者並存不衝突、不是二選一。

設定指定視圖中連結模型的 Display Settings。設成 byHostView 後，主檔的視圖篩選器與類別覆寫才會套用到連結元素——這通常是讓主檔覆寫對連結生效的前置步驟。可用 linkInstanceIds 或 linkNames 指定目標，兩者都省略 = 該視圖的所有連結。逐個連結獨立處理，一個失敗不影響其他。觸發條件：使用者提到把連結設成 By Host View、改連結顯示方式、讓篩選器對連結生效、連結改用主檔設定。

修改材質「圖形」頁籤：著色顏色（shadingColor）、透明度、表面／切割的前景與背景填充樣式與顏色。改的是材質本身，所以所有用到這個材質的元件、所有視圖都會一起變——這是與 create_view_filter／V/G 覆寫（只作用單一視圖）的關鍵差異。給了 shadingColor 會自動關閉「使用彩現外觀」，否則顏色不會生效。只給要改的欄位即可；dryRun=true 只驗證輸入不寫入。回傳 Before / After（After 為寫入後回讀）。作用在目前作用中的文件：連結檔的材質要在該連結檔內改（改完存檔，主檔重新載入連結）。典型用途：地形草地顏色調淺、給草地材質加 hatch。觸發條件：使用者提到改材質顏色、材質太深/太淺、材質加 hatch、材質表面填充、所有視圖都要生效。

為綠建材 Material 建立（或重用既有，依名稱去重不重複建立）Model 目標的 Surface Pattern 並套入該材質的表面／剖切樣式。用於地磚 600×600 網格縫線、木地板木紋等依產品規格需要在平面/剖面顯示紋理的飾面材料（TASK-005.2 情境 2）。

列出或切換視圖樣版（View Template）的「控制參數」清單，對應 Revit「View Template」對話框每一列的 Include 勾選框。常見用途：使用者在視圖上看不到篩選器上色，原因是樣版正在控制『V/G Overrides Filters』——把該項目從控制中排除（uncontrol），使用者才能在個別視圖自行開關篩選器。不帶 uncontrol/control 時為純唯讀列表模式，用來查出合法的參數名稱（比對用，不分大小寫）；不確定名稱時應先這樣呼叫一次。dryRun=true 只預覽變更、不寫入模型。

在指定視圖中取消隱藏元素。使用 View.UnhideElements() API，支援單一或批次操作。