2026-06-21 活動快照 snapshot · 數字為當時狀態，最新統計見 BIM_MCP 知識站
2026-06-21 · 六月小聚 READING BRIEFING

族群盤點與清整 SOP

一條可重複、使用者把關的作業閉環;
以及一根「名字寫 30、其實是 24」的柱,
如何證明「簽章比對」非做不可。

Domain
family-inventory-cleanup
Skill
/family-inventory-cleanup
快照
96 tools · 45 domain · 22 skills
SCROLL ↓

Section 1 — 這個 Domain 在做什麼:作業閉環

CLOSED LOOP 閉環
① 查指定 category
② 雙軸盤點（載入 vs 放置）
③ 參數簽章比對
④ 提案【停,等你裁決】
⑤ 使用者裁決
⑥ 執行 purge / merge / rename
⑦ 驗證 + SELF-AUDIT
DOMAIN
1-1
一條使用者把關的清整閉環

查指定 category → 雙軸盤點 → 簽章比對 → 提案後「停」→ 使用者裁決 → 執行（purge 未使用 / merge 重複型 / rename 改名）→ 驗證 + 自我稽核。每一步都可重複,破壞性動作前一律先停。

未使用類型 = purge 對象
載入軸 − 放置軸
Project Browser 看得到 − 模型真用到
= 未使用類型
DOMAIN
1-2
核心觀念:雙軸盤點

載入軸是 Project Browser 看得到的所有類型（逐族群用 list_family_symbols）;放置軸是模型真的用到的（query_elements）。只看放置會漏掉未使用;只看載入不知道誰在用。兩軸相減才看得到 purge 對象。

Section 2 — 真實使用步驟:怎麼用它

最常見的卡關
「Command timed out」
這不是斷線、也不是埠問題。
是 MCP 指令在排隊等 Revit 閒置,
30 秒沒輪到就回報逾時。
解法:按 Esc、關對話框,把 Revit 放空再重試。
操作
2-1
先讓 Revit 畫面「閒置」再下指令

命令經 ExternalEvent 在 UI 執行緒執行,Revit 非閒置時不處理。逾時別去重點 ribbon,清掉進行中的命令、關掉對話框,把 Revit 放空再重試即可。

強制前置檢查 7 條
① 盤點逐族群過濾,避開 100 筆截斷
② 刪型前驗 0 實例
③ delete_element 連帶刪實例且不回報 → 動作前自己列影響
④ 判重複/名實一律讀簽章,禁名稱捷徑
⑤ 破壞性動作逐一執行,不並行
⑥ 告知 Ctrl+Z 可復原
⑦ 每批前重抓基準
7 RULES
2-2
每個破壞性動作前的「強制前置檢查」

叫用 /family-inventory-cleanup、指定 category 後,它跑到提案就停在那等你勾。你選了才執行,而每個破壞性動作前都會過這 7 條硬規則;做錯可在 Revit 按 Ctrl+Z 復原。

Section 3 — 本月實戰:柱 — 簽章鐵則救回 93 根

THE TRAP 陷阱
型名寫的是
30"D × 30"W
get_element_info 讀出實際
24" × 24"
93 根柱,名字完全反指
CASE
3-1
名字寫 30、其實是 24 的主力柱

全專案 121 根柱、4 個族群。主力型名為 30"D x 30"W（93 根）,但讀簽章發現 Depth/Width 實際是 24" × 24"。純名稱比對會把這 93 根誤判成 30×30——這就是「名稱會騙人」的鐵證。

簽章揭穿真重複
30"D x 30"W（實 24×24）
幾何簽章完全相同 =
24"D x 24"W 2（實 24×24）
→ 真重複,其中一個的名字是錯的
CASE
3-2
簽章揭穿真重複 → 修正 → purge

把 24"D x 24"W 2 的 1 根用 change_element_type 併入 → 刪掉空出的重複型 → 用 modify_element_parameter（Name 特例）把主力型改名為正確的 24"D x 24"W。再 purge 5 個未使用型。Rectangular 13 → 8 型,全部名實相符;總柱數 121 → 121,零實例誤刪。

⚠️
殘留風險
簽章只能揭露「名 ≠ 參數」,
不能決定設計本意。

若本意其實是 30×30,
那這 93 根是斷面不足的
結構錯誤,改名只是把問題藏起來。
RISK
3-3
殘留風險:改名不等於修對

這次依「24×24 為真、30×30 是名字打錯」執行。但這個前提需要結構技師確認——若設計本意是 30×30,改名等於把斷面不足的結構錯誤藏起來。這超出 MCP 能判的範圍。

Section 4 — 能力邊界

MCP 做得到MCP 做不到
盤點 · 簽章比對改格式 Text↔Number
改參數值 · 換類型改族群內部定義
單型改名 · 刪除類型結構柱 OST_StructuralColumns
BOUNDARY
4-1
能力邊界:這個 domain 的界線

MCP 可做盤點、簽章比對、改參數值、換類型、單型改名（modify_element_parameter 的 Name 特例,在 Transaction 內、可 Ctrl+Z）、刪除類型。改參數資料格式、改族群內部定義、處理結構柱則要回 Family Editor 或別解。

THE TAKEAWAY
名稱會騙人,參數不會。
判重複,先讀簽章。
Domain family-inventory-cleanup · 2026-06-21 六月小聚快照
96 tools · 45 domain · 22 skills（當時狀態）
← 0523 五月小聚（上個月） GitHub Repo
Field Notes No. 04 · 2026-06-21 · Shuotao Chiang

核心觀念:雙軸盤點

族群清整最容易出錯的地方,是「只看到一半」。這個 domain 強制你同時看兩個軸:

軸看的是什麼工具
載入軸Project Browser 裡看得到的所有類型（不管有沒有被放進模型）逐族群跑 list_family_symbols
放置軸模型裡真的有實例的類型query_elements

關鍵等式

載入 − 放置 = 未使用類型（purge 對象）

各階段用哪些工具

階段工具目的
Phase 0get_active_viewre-anchor 當前視圖（活躍狀態重新錨定）
Phase 1query_elements_with_filter + list_family_symbols雙軸盤點:放置 vs 載入
Phase 2get_element_info讀「簽章」（實際參數值）
執行change_element_type / delete_element / modify_element_parametermerge / purge / rename

為什麼要逐族群

list_family_symbols 一次有 100 筆截斷上限。直接全抓會漏。盤點時用逐族群過濾,才不會被截斷吃掉尾巴。

真實使用流程(5 步)

  1. 先讓 Revit 閒置:按 Esc 清掉進行中的命令、關掉對話框。否則 MCP 指令會排隊等 Revit 閒置,30 秒沒輪到就回報「Command timed out」——這不是斷線、也不是埠問題,別去重點 ribbon,把 Revit 放空再重試即可。（原因:命令經 ExternalEvent 在 UI 執行緒執行,Revit 非閒置時不處理。）
  2. 叫用 /family-inventory-cleanup,指定要整理的 category（門 Doors / 窗 Windows / 柱 Columns…）。
  3. 讓它跑 Phase 0 → 1 → 2 → 提案,然後停在提案等你選。
  4. 你勾選要做的（purge / merge / rename）後才執行;每個破壞性動作前會過「強制前置檢查」;破壞性動作逐一執行、不並行;做錯可在 Revit 按 Ctrl+Z 復原。
  5. 執行後重查驗證,輸出 SELF-AUDIT。

逾時不是斷線

看到「Command timed out」是最常見的誤判點。它代表 Revit 當下不在閒置狀態（有對話框、有未結束的命令、滑鼠正在拖曳)。不要重啟服務、不要去戳 ribbon——按 Esc、關對話框,把畫面放空後再下一次指令就會通。

強制前置檢查(7 條硬規則)

每個破壞性動作前都要過這份清單。它們不是建議,是擋掉「靜默誤刪」的護欄。

  1. 盤點用逐族群過濾,避開 list_family_symbols 的 100 筆截斷。
  2. 刪型前驗 0 實例——確認真的沒人在用才刪。
  3. delete_element 會連帶刪實例且不回報,動作前自己先列出影響範圍。
  4. 判重複 / 名實一律用 get_element_info 讀簽章,禁用名稱捷徑。
  5. 逐一執行,不並行——破壞性動作彼此可能互相影響基準。
  6. 告知 Ctrl+Z 可復原——所有動作在 Transaction 內,使用者可在 Revit 撤銷。
  7. 每批前重抓基準——前一批的執行會改變現況,下一批要重新盤點。

121 根柱的族群分佈

全專案共 121 根柱,分 4 個族群:

族群根數
Rectangular Column (Off Center)111
Corinthian Column Schematic (with Pedestal)4
Round Column2
Pergola Post4

陷阱在哪

主力型名為 30"D x 30"W(93 根),但 get_element_info 讀出的實際 Depth/Width = 24" × 24"——名字完全反指。純名稱比對會把這 93 根判成 30×30。

完整修正步驟 + 先導試水

簽章揭穿真重複

30"D x 30"W(實 24×24)與另一個 24"D x 24"W 2(實 24×24)幾何簽章完全相同 = 真重複,其中一個(主力那個)名字是錯的。

修正(柱 Columns)

  1. 把 24"D x 24"W 2 的 1 根用 change_element_type 併入。
  2. 刪掉空出的重複型。
  3. 用 modify_element_parameter(Name 特例)把主力型改名為正確的 24"D x 24"W。
  4. 再 purge 5 個未使用型:10"D x 12"W、10"D x 16"W、15"D x 25"W、17.5"D x 25"W、Round Column 的 12" Diameter。

結果:Rectangular 13 → 8 型,全部名實相符;總柱數 121 → 121,零實例誤刪。

先導試水(門 Door-Opening)

在動柱之前先拿門練手:10 型 → 3 型——刪一個疑誤建的 50" x 60"(連帶 1 實例)、purge 5 個未使用、merge 一個 36" x 84" 2 重複。

這次測試補進 domain 的 5 條硬規則

  1. 未知 category 要先做「族群發現」再盤點。
  2. 簽章強制,禁名稱 / get_category_fields 捷徑——後者在異質類別會抽錯樣本(柱實測抽到 Corinthian,根本沒回 Depth/Width)。
  3. 結尾的「 N」尾碼只是線索,要分辨真重複 / 孤兒 / 名字錯三種情況。
  4. Mark 群聚法只在有 Mark 的類別有效(柱無 Mark)。
  5. filter 字串打錯會回「假 0」,0 實例驗證優先用完整列舉,別只信 filter 回傳的 0。

殘留風險(再次提醒)

這次依「24×24 為真、30×30 是名字打錯」執行。但簽章只能揭露「名≠參數」,不能決定設計本意。若本意其實是 30×30,那這 93 根是斷面不足的結構錯誤,改名只是把問題藏起來——需結構技師確認,超出 MCP 能判範圍。

能力邊界

MCP 做得到

MCP 做不到(需 Family Editor 或別解)