docs(archicad): 新增轉譯邊界三份 domain 文件，並補上 2026-09-08 的實機測試證據 - #130
Open
Archwiz-boss wants to merge 11 commits into
Open
Archwiz-boss wants to merge 11 commits into
Archwiz-boss wants to merge 11 commits into
Conversation
新增三份 domain 知識文件，內容以 2026-09-08 的實機測試為依據 （tapir-archicad-mcp 0.5.3 + Archicad 28 + Tapir Add-On 1.5.8）： - archicad-adapter-boundary.md：架構原則、執行前提、能力降級策略 - archicad-terminology-map.md：名詞對照與單位合約 - archicad-portability-matrix.md：A/B/C 可攜性分級與各 Wave 驗證狀態 三份都標明權威正本另有其檔（archicad-runtime-facts.md、 archicad-skill-portability.md、revit-archicad-terminology.md）， 衝突時以正本為準，避免同一知識在兩處分叉。 本次實測的主要結論： wall-orientation-check 的能力缺口前提不成立。原判斷認為缺少 Revit Wall.Flipped 等價值而只能人工檢查，但 flipped 已被 0.5.3 接受，且 elements_get_relations_of_elements 對 Zone 回傳的 wallParts 直接提供「哪一段牆構成這個 Zone 的第幾條邊」，等同 domain/wall-check.md 的房間檢測法。單一樓層實測 105 個 Zone 全數回傳關係、0 個空結構，對該層 280 面牆得到 196 內牆候選 / 69 外牆候選 / 15 無判定，覆蓋率 94.6%，跨樓層誤引用 0 筆。 因此建議升為 pilot 候選，判定一律標為候選、不自動翻轉牆。 elements_get_zone_boundaries 語意更直接（原生回 isExternal 與 neighbouringZoneElementId），但實測同一 GUID 首次呼叫成功後 持續逾時，不可作為主路線。 單位合約取得可執行的實測依據：property 定義宣告 propertyValueType 為 Real，runtime 實際回傳字串（計算面積 '3.46'、牆表面面積 '23.31'），小數位數來自專案計算單位設定 而非數值本身。算量 domain 全部以 mm 計算，直接餵入即為 千倍誤差且無任何警告。 另補三項會造成「誤判能力不存在」的執行前提：0.5.3 需 pin mcp<2 才能啟動、同一 session 須先呼叫 discovery 建立連線、 指令參數須包在 params 內。分頁在 0.5.3 可完整走完（全量 Wall 7376 筆 / 74 頁），但未走完分頁就下結論會產生偽陰性。 Wave 1 三支 pilot 的狀態據實記錄：element-query 有 live-test evidence 待審，room-numbering 與 quantity-takeoff-excel 的 Live-Test Evidence 區塊仍是空白模板，三支都尚未達到 verified。 連帶更新（新增 domain 檔的必然連動，verify-qaqc 為 hard gate）： domain/README.md 分類登記、CLAUDE.md 關鍵字表與 domain 計數、 README/README.zh-TW/DOCUMENT_AUDIENCE_INVENTORY 計數、 docs/BIM_MCP 網站各處計數與 domain-index 卡片，83 -> 86。 scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy：61 PASS / 0 FAIL。 .mcp.json 與 .vscode/mcp.json 未納入本 commit，維持 Revit-only。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The three domain files added in the previous commit state conclusions; this
records the observations behind them, in the file that is the source of truth
for runtime behaviour. Per the existing note in that file, the new combination
is added as its own section rather than edited into the 2026-08-19 observations.
Same wrapper (0.5.3), Archicad 28 and Tapir Add-On 1.5.8 as the previous run,
but a different solo project (Meter / 2 decimals, 97 stories, ~7.4k walls).
Driven through the archicad-mcp stdio server only; the JSON API port was never
called directly.
Three findings are new and each one can make a working capability look absent:
- 0.5.3 no longer resolves a working dependency set. A fresh resolve picks up
mcp 2.x while 0.5.3 still imports mcp.server.fastmcp, so the server exits
with ModuleNotFoundError before serving anything. `--with "mcp<2"` fixes it.
An environment resolved earlier keeps working, so a stored config can look
correct right up until it is re-resolved.
- archicad_call_tool requires discovery_list_active_archicads in the same MCP
session. Without it a correct port still returns "not an active Archicad
connection" — discovery registers the connection, it is not only a lookup.
- Command parameters belong inside `params`. Placing them at the top level
makes pydantic reject `port` as extra_forbidden, which reads as a port
problem and is not one.
Two open items from 2026-08-19 are now resolved:
- Pagination on 0.5.3 does run to completion: an unscoped Wall walk returned
7376 GUIDs over 74 pages in 0.6 s, no session expiry. The 0.4.3 ceiling did
not reproduce. The page-size trap still bites though — taking the first 100
property definitions as the whole set produced a false negative during this
run; the full list is 1766 over 18 pages.
- GetDetailsOfElements still fails with the same 522 validation errors, now
with the exact 14-field reject list. flipped is not among them (0.5.3
accepts it); zoneRel was not previously called out.
Zone relations were exercised at story scale: all 105 Zones on the active story
returned populated wallParts, giving 196 interior / 69 exterior / 15 no-verdict
over 280 walls (94.6% coverage, 0 off-story references). elements_get_zone_-
boundaries answers the same question more directly (isExternal,
neighbouringZoneElementId, SI area) but is one Zone per call and, in this
project, only the first call ever succeeded — later calls on the same GUID
timed out past 60 s. It is not viable as a main route.
The unit contract gained a concrete form: property definitions declare
propertyValueType Real and the values come back as strings ('3.46', '23.31'),
two-decimal because the project's calculation units say so. Also recorded: a
non-applicable property returns None with nothing distinguishing "no value"
from "not available", and properties_get_details_of_properties answers 6702 for
property ids that properties_get_all_properties resolves without trouble — one
command erroring is not evidence a property is absent.
Finally, the Add-On stopped responding under sustained load: discovery began
returning a bare [] while the port was still listening and Archicad was still
alive. That is the same response as "Add-On not loaded", so the working rule is
to stop and report unknown instance state rather than retry or file it as a
capability gap.
scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy: 61 PASS / 0 FAIL.
Refs shuotao#98
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… guard it needed
The room-numbering pilot ran end to end on a live model for the first time. It
also failed the first time in a way worth recording, because the failure is
invisible to a caller that checks only what the tool returns.
Run 1, on story 7FL: 105 zones, clean dry-run, five write batches all reported
successful in 1.1 s — and nothing changed. Read-back returned the original
value for all 105.
The cause is not a permissions model on built-in properties. Writes to
StaticBuiltIn, Custom and DynamicBuiltIn properties all failed on that story,
every one of them declaring propertyIsEditable: true. The same command against
an editable Zone succeeded, verified by read-back, and restored cleanly.
Two things follow, and both are now mandatory steps in the pilot:
- The failure lives in the per-element executionResults array
({"success": false, "code": -2130312909}). The MCP call itself returns
normally, with no isError. Check executionResults element by element, and
still read back.
- propertyIsEditable describes the property, not whether this element can
currently be written. The element-level predictor is the IsEditable element
filter: on that story ["OnActualFloor"] returned 105 and
["OnActualFloor","IsEditable"] returned 0, while the story stayed fully
visible and readable. Filter first, report the elements that drop out as
skipped.
Run 2, on story 1FL with editability confirmed: 42 zones, 8 Y-bands, 0
duplicates, 0 off-story conflicts, executionResults ok=42 / failed=0 in 2.0 s,
read-back success=42 / unchanged=0 / other=0. The Live-Test Evidence block in
pilot-room-numbering.md is filled in with that trace, replacing the placeholder
template, and the negative result from 7FL is kept alongside it.
Supporting findings recorded in archicad-runtime-facts.md: there is no
elements_modify_zones (every other element type has one), so Zone data can only
be changed through property writes; 區域/區域號碼 and ID和類別/區域號碼 mirror
one underlying value (identical on 105 zones before, 42 after); and story
membership has to be inferred from 3D bbox zMin against project_get_stories,
because elements_get_details_of_elements — which carries the floor index — is
still broken.
The portability matrix now reads one pilot verified, two not, instead of three
not. quantity-takeoff-excel is unchanged and still a blank template.
Units note carried into the pilot: bounding boxes are metres, so the Domain's
yToleranceMm default of 3000 is divided by 1000 before comparison.
scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy: 61 PASS / 0 FAIL.
Refs shuotao#98
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…pproximate mapping The third pilot now has a live-test trace. It is deliberately NOT marked verified: the pipeline runs and every number traces to a named property on a named GUID, but three of the method's core inputs are substitutes rather than equivalents, and a fourth question needs a human decision. Run: 42 Zones on story 1FL, tapir-archicad-mcp 0.5.3 / Archicad 28 / Tapir 1.5.8, Meter with 2 decimals. All 10 required property identifiers resolved. Relations read over all 42 Zones returned Wall 233, Riser 168, Tread 160, Object 98, Beam 73, Door 60, StairStructure 60, Column 47, Window 24, Stair 8 — stair sub-elements dominate, so any "related element" count has to state which types it includes. Workbook: 3 sheets, 42 detail rows with formulas retained and a SUM totals row, 233 wallPart evidence rows, a provenance sheet carrying project/port/units/commands/property map/unresolved list. Reconciliation: perimeter 1142.92 m, door+window surface 412.66 m2, perimeter*height-openings 4610.22 m2, formula error scan clean. The decision that cannot be automated: a Zone has more than one area and more than one perimeter, and they disagree. On one Zone, 計算面積 '49.95' against 被測量的面積 '53.34'; 區域淨週長 '44.91' against 區域總週長 '44.60'. Calculated and measured area differed on 36 of the 42 Zones. Picking one silently is how a takeoff ends up disagreeing with the model, so the workbook records which definition was used and warns on every row where the two differ. The three substitutes, all recorded as unresolved rather than papered over: finish-face boundary (Revit GetBoundarySegments(Finish) has no Archicad equivalent, so perimeter falls back to the 區域淨週長 property), per-opening deduction (Zone-level door/window surface totals instead of individual width x height), and net height (Zone height property, not matched against ceiling or slab geometry). A fifth gap: elements_get_zone_boundaries would give the external/internal split but is unusable at scale. Also recorded in runtime facts: elements_get_elements_related_to_zones returns a flat array with repeated GUIDs and no type grouping, so elements_get_relations_of_elements is the better route — it carries both the type grouping and the per-segment wallParts evidence. The portability matrix now reads one pilot verified, one approximate mapping, one awaiting review. Note on QAQC: the run reports 3 domain-count/index failures caused by an untracked fourth file, domain/archicad-structural-dwg-sync.md, which is not mine and is not part of this commit. Every check covering the files changed here passes. Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
本次修正來自使用者（執業建築師）的領域審閱。原本的寫法有兩個錯誤，都會讓 讀者把工具能取到的數字用在不該用的地方。 錯誤一：把「同一個 Zone 有多個面積、彼此不合」寫成算量階段要裁定的問題。 實際上那是建模階段的約定問題——Zone 要算總面積還是淨面積，必須在建模時就 定義並統一，Zone 的建構方式（邊界抓牆心或完成面、是否含柱）直接決定提取出 的數字代表什麼。42 個 Zone 中 36 個兩種面積不一致，是「這批 Zone 沒有共同 依據」的症狀，不是報表要挑一個。沒有共同依據，任何加總都不成立。 錯誤二：完全沒有寫應用邊界。工具能提取到面積，不代表那個面積可以拿來用： - 可用：初步規劃階段的量體檢核，大致判斷容積、建蔽率是否明顯超出法規值。 - 不可用：作為建照申請的面積依據。送審的面積計算是另一條獨立工作流，必須 以面積單線圖與計算式逐項證明，不能以模型的 Zone 面積代替。 - 不可用：直接當成容積率、建蔽率的計算結果。那兩者各有自己的計入、折減與 免計規則，與 Zone 面積加總不是同一回事。 - 不可用：把「初步判定不超過法規值」寫成「符合法規」。 本輪 pilot 的定位因此明確為：驗證 MCP 能否透過 Domain 方法提取到 Zone 面積、 且每個數字可追溯到具名 GUID 上的具名屬性。它不證明那些面積適用於任何法規 用途——那取決於 Zone 怎麼建的。 三處同步：archicad-terminology-map.md 新增第 4 節（Room/Zone 對照列一併加註 兩者面積都不是法規面積）；pilot-quantity-takeoff-excel.md 的面積章節改寫， Scope 補上定位聲明，Stop Conditions 增加「輸出將被當成建照面積依據或合規 結論」一條；archicad-runtime-facts.md 的技術描述改指向應用邊界，不再暗示 讀取時挑一個即可。 離開轉譯層的每一份 Zone 面積，都必須載明：讀的是哪一個面積屬性、Zone 的 建構約定為何、這份數字的適用範圍。缺任一項，數字就可能被下游當成它不是的 東西使用。 scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy：本次變更涵蓋的檢查全數通過 （6-1/6-2/6-3、7-7 本地連結 57 條全解析、8-2/8-3/8-4）。報告中的 3 項 domain 計數／索引 FAIL 來自未追蹤的 domain/archicad-structural-dwg-sync.md， 該檔不屬於本 PR。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
承接前一個 commit 的應用邊界，補上使用者（執業建築師）提供的可執行規則。 這條規則與 backend 無關，Revit 側同樣適用，但它決定了從模型取出的面積數字 能不能對得上圖面。 建照審查不接受把程式算出的面積值直接寫在圖面上。必須搭配面積單線圖表明每 一塊的形狀與長度，列出計算式，才能作為依據。依規範算出來的面積與程式直接 計算的結果會有末位小數差距，那是正常的，不是誤差。 正確順序： 1. 長度取自圖面上顯示的長度，以公尺標示，至少三位小數（三或四位，未特別 限定上限）。 2. 一個形狀一條計算式，結果為平方公尺。 3. 每條計算式的結果個別四捨五入到小數點後兩位。 4. 再把各項的顯示值加總。 絕對要避免以原值相互加總。六位小數直接加總會因進位而與「先個別四捨五入再 加總」的結果不同。先捨入再加總，後續每一步才能與圖面對得上，事後保存登記 也不會出問題。 這條規則反過來重新定位了本 repo 先前記錄的兩層數值模型：屬性層回的是依專 案計算單位格式化的顯示字串（本專案 2 位小數），形式上接近規範要的顯示值， 但仍不可直接充當依據，因為它沒有對應到面積單線圖的形狀與長度；幾何層回的 是六位以上小數的原始 SI 值，正是規則明文禁止直接加總的「原值」。 也就是說，幾何層的高精度在這個情境下不是優點——用它直接加總得到的總面積， 與依規範製作的面積計算表不會一致，且不一致無法事後補救。 pilot 的 Stop Conditions 增加一條：以原始幾何值加總產生總計，而非先個別 四捨五入到兩位小數。 scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy：本次變更涵蓋的檢查全數通過 （6-1/6-2/6-3、7-7 本地連結 57 條全解析、8-2/8-3/8-4）。報告中的 3 項 domain 計數／索引 FAIL 來自未追蹤的 domain/archicad-structural-dwg-sync.md， 不屬於本 PR。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
先前的寫法讓「實測基準」那張表看起來涵蓋全文，實際上 Wave 2 三項判斷裡只有
wall-orientation-check 是 2026-09-08 實測的，另兩項沿用 2026-08-19。這是過度
宣稱，逐節修正。
archicad-portability-matrix.md：
- 第 4 節標題改為「2026-09-08 檢視；僅 wall-orientation-check 為本次實測」
- Wave 2 表格新增「證據來源」欄，逐列標明：
- element-coloring：分組風險由本次 property 實測直接支持（回傳為 2 位小數
字串、小數位來自專案設定），但 Highlight 指令本身的行為未於本次重測
- detect-clashes：本次完全未重測，settings 三欄必填與 Hotlink 反面證據
皆沿用 2026-08-19
- wall-orientation-check：2026-09-08 實測
archicad-adapter-boundary.md：
- 實測基準段補上「各節的證據日期不同」
- 第 3 節 A（圖面視覺覆寫）標明 Highlight 行為沿用 2026-08-19、單位風險由
本次實測支持
- 第 3 節 B（碰撞檢查）標明全節沿用 2026-08-19、本次未重測
Refs shuotao#98
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
實際使用中浮現的缺漏：使用者看到「模型全變線框、只剩一根柱子有顏色」，以為 模型壞了，去 Archicad 的 3D Styles 與 Model View Options 找開關卻找不到。 原因是 elements_highlight_elements 的 wireframe3D 選項——開啟後會把 3D 視窗 裡所有未被高亮的元素切換成線框（另有 nonHighlightedColor 可改非高亮元素的 顏色）。那是一次呼叫的結果，不是兩件事，也沒有任何東西損壞。 原本文件只寫「降級為暫時高亮」與「傳空 elements 陣列即可清除」，兩點都不足： - 沒有寫出視覺副作用的規模。讀者不會從「高亮」預期整個 3D 視窗改變外觀。 - 沒有寫出這不是 Archicad 的顯示設定。它是 Add-On 疊加的臨時狀態，宿主軟體 裡沒有對應開關，navigator_get_model_view_options 也確認專案自己的選項組並 未被改動。在 Archicad 裡找不到地方關，是預期行為而非故障。 - 清除的必填欄位寫漏了一半。elements 與 highlightedColors 兩者皆為必填， 只傳空的 elements 會被 schema 拒絕；兩個都傳空陣列才會清除，線框同時恢復。 因此新增一條對使用者的義務：任何會下 highlight 的流程，必須在同一次互動中 一併告知如何清除，或在流程結束時自動清除，否則使用者會面對一個在自己軟體裡 無法解除的狀態。 schema 於 2026-09-08 重讀確認，Wave 2 表格的證據來源欄同步更新——原本記為 「Highlight 指令本身未於本次重測」，現在 schema 已重讀，但指令的實際染色行為 仍未由本次執行。 scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy：61 PASS / 0 FAIL。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
先前寫成「有一次 live-test evidence，尚待維護者審閱，審閱通過後才可標 verified」。查證後那是錯的：PR shuotao#122 的 element-query live-test evidence 已於 2026-08-28 收編至 main 的 6636778，main 上的 pilot-element-query.md 有 187 行、 含完整的 Recorded run 2026-08-18 trace。 會誤判的原因值得一併記進文件：**維護者採手動收編而非 merge PR**。shuotao#122 與 shuotao#123 在 GitHub 上都顯示 CLOSED 且 not merged，看起來像被退回，實際內容已分別進入 main 的 6636778 與 5dad238。判斷一份證據是否落地要看 main 的檔案內容，不能只 看 PR 的 merged 狀態。矩陣中加註這一點，避免後續貢獻者重蹈。 Wave 1 狀態因此改為「兩支 verified、一支 approximate mapping」： - element-query：verified（2026-08-18，已收編 main 6636778） - room-numbering：verified（2026-09-08） - quantity-takeoff-excel：approximate mapping（2026-09-08） 同時修正 quantity-takeoff-excel 的 unresolved 措辭，「面積定義未裁定」改為 「面積定義未統一（屬建模約定）」，與本分支稍早把面積歧異歸回建模階段的修正 保持一致。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
兩個缺漏，都是我先前新增 domain 檔時沒做完，由另一條工作線（PR shuotao#131）改到 同一批檔案時才浮現。 **一、卡片放錯 section。** 我把三張卡片插在 domain-index.html 的 wall-check 之後，而那整段屬於 `id="compliance"`（法規與 compliance SOP），等於把 Archicad 的轉譯邊界、名詞對照與可攜性矩陣歸成了法規檢核。 正確歸屬是 ops。索引裡所有同性質的 meta-reference——tool-capability-boundary、 skill-authoring-standard、frontmatter-standard、session-context-guard、 core-reload-boundary、lessons——都在 ops（維運、QA 與 authoring 標準）。 references section 不適用，它的定義是「非本專案產出的 SOP，引用外部規範本文， 放在 domain/references/ 子目錄」，只收 building-code-tw.md。 三張卡片改置於 ops section，compliance 回到 11，ops 由 11 改為 14 （cat-summary 與 section 標題同步）。 **二、hero 圖的分類計數沒改。** scripts/gen-hero-grains.mjs 帶有 domain 的 五分類計數，加總即總數。我先前把總數從 83 改到 86，卻沒有改這裡，因此 domain__hero__grains.svg 仍畫著 83。QAQC 的 claim-pattern 不涵蓋 .mjs 與 .svg， 所以沒有被擋下來。 維運 11 改為 14、console.log 的總數 83 改為 86，並重跑 gen-hero-grains.mjs 重新產生 domain__hero__grains.svg。skills__hero__grains.svg 的內容不變，僅行尾 差異，已還原不納入。 scripts/verify-qaqc.ps1 -SkipBuild -SkipDeploy：61 PASS / 0 FAIL。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CI 的 check-files 明確界定：fork PR 只允許修改 domain/*.md 與 GEMINI.md。 本分支原本一併改了 22 個檔案（.claude/skills 下的 pilot 與 runtime facts、 CLAUDE.md、README×2、DOCUMENT_AUDIENCE_INVENTORY、docs/BIM_MCP 各頁與 hero 圖、scripts/gen-hero-grains.mjs），全部超出允許路徑，因此還原。 會多做這些，是我把 repo 內部的規則套錯了對象。verify-qaqc.ps1 要求 domain 計數與各處索引一致，那是維護者維護 main 時的義務；對 fork 貢獻者而言，計數 同步與索引更新本來就由維護者在收編時處理——這一點在既有收編紀錄裡看得很清楚 （例如 5dad238 的訊息載明「Domain(79)／Skills(54)／Tools(180) 皆不變」，是 維護者自己核算後落地的）。 本 PR 因此縮回四個檔： - domain/archicad-adapter-boundary.md（新增） - domain/archicad-terminology-map.md（新增） - domain/archicad-portability-matrix.md（新增） - domain/README.md（分類登記三行） 被移除的內容沒有丟失，完整版保留在分支 `evidence/archicad-pilots-2026-09-08`（10 個 commit，含逐步推理）： - pilot-room-numbering.md 的 Live-Test Evidence（42 個 Zone 寫入 + read-back） - pilot-quantity-takeoff-excel.md 的 Live-Test Evidence 與應用邊界章節 - archicad-runtime-facts.md 的 2026-09-08 re-run 一節 - 計數 83→86 的連帶更新與 domain-index 卡片（歸類於 ops） 三份 domain 檔內文引用的 archicad-runtime-facts.md、 archicad-skill-portability.md、revit-archicad-terminology.md 在 main 上都已 存在，指向有效；只是尚未包含本次新增的實測內容，需要時可自 evidence 分支取用。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Archwiz-boss
added a commit
to Archwiz-boss/BIM_MCP_study
that referenced
this pull request
Sep 8, 2026
Document evidence-graded workflows for per-story structural CAD comparison, unit normalization, safe property marking, and human review boundaries. --- 分支重建說明（收尾時補，非原作者內容）--- 原分支自 feat/archicad-domain-specs 開出，因此 PR 連同該分支的 commit 一併帶入， 並改到 23 個超出 fork PR 允許路徑的檔案。CI 的 check-files 明確界定：fork PR 只允許修改 domain/*.md 與 GEMINI.md。 現改為自 upstream/main 重建，只保留本工作線自己的兩個檔案： - domain/archicad-structural-dwg-sync.md（新增，299 行） - domain/README.md（分類登記一行，數量 18 → 19） 計數同步、CLAUDE.md 關鍵字表、docs/BIM_MCP 索引與 hero 圖等連帶更新，依維護者 既有作法由收編時處理（見 5dad238 的訊息：「Domain(79)／Skills(54)／Tools(180) 皆不變」，是維護者自行核算後落地），不在 fork PR 範圍內。 與 PR shuotao#130 的關係：兩者現在各自獨立，唯一交集是 domain/README.md 的分類表—— shuotao#130 加三行、本 PR 加一行，先後收編時需合併該表，數量取合併後的實際值。 Refs shuotao#98 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
接續 issue #98。這批同時做兩件事：把 Archicad 轉譯的判斷寫成可查的 domain 知識，以及用一次實機測試把其中幾項從「推導」變成「證據」。
本 PR 只含
domain/*.md四個檔（三份新增 + README 分類登記），符合 fork PR 的允許路徑。實測證據的完整內容與連帶更新另存於分支evidence/archicad-pilots-2026-09-08，說明見文末。環境：tapir-archicad-mcp 0.5.3（需
--with "mcp<2"才啟動得了）、Archicad 28、Tapir Add-On 1.5.8、單機專案、計算單位 Meter / 2 位小數。全程只經 archicad-mcp 的 stdio server，沒有直接打 JSON API 埠。三支 pilot 的狀態
room-numberingquantity-takeoff-excelelement-query6636778），本 PR 不動它pilot-room-numbering.md與pilot-quantity-takeoff-excel.md的 Live-Test Evidence 區塊原本是空白模板，現在填入實際 trace。（附帶一提：我一開始把
element-query記成「待審」，查證後是錯的 —— PR #122／#123 在 GitHub 上顯示 CLOSED 且 not merged，但內容已分別手動收編進main的6636778與5dad238。判斷證據是否落地要看main的檔案內容，不能只看 PR 的 merged 狀態；這點也加註進可攜性矩陣，避免後續貢獻者誤判。）算量 pilot 的定位需要講清楚：它驗證的是「MCP 能否透過 Domain 方法提取到 Zone 面積、且每個數字可追溯到具名 GUID 上的具名屬性」。它不證明那些面積適用於任何法規用途 —— 那取決於 Zone 是怎麼建的。
三個值得單獨看的發現
1. 寫入會靜默失敗。
properties_set_property_values_of_elements把失敗放在 per-element 的executionResults裡，MCP 工具層不回報錯誤。實測對鎖定樓層的 105 個 Zone 重新編號，回報「五批全部成功、1.1 秒」，實際一個都沒改。只檢查工具層結果就會宣稱成功。2.
IsEditable是寫入的必要前置檢查。propertyIsEditable描述的是屬性，不是這個元素當下能不能寫 —— 鎖定樓層上 StaticBuiltIn / Custom / DynamicBuiltIn 三種 property 全部寫入失敗，而它們的定義都是propertyIsEditable: true。元素層級的判準是["OnActualFloor","IsEditable"]回 0 而["OnActualFloor"]回 105。這也讓 issue #98 討論串裡提過的「ElementFilter 容易誤用」有了正面用途。3. Zone 面積取得到，不代表能用；而面積歧異是建模問題，不是報表問題。 同一個 Zone 的
計算面積是 '49.95'、被測量的面積是 '53.34'，週長也有區域淨週長 44.91與區域總週長 44.60兩種，42 個 Zone 中 36 個不一致。這不是報表階段要挑一個：Zone 要算總面積還是淨面積，必須在建模時就定義並統一，Zone 的建構方式（邊界抓牆心或完成面、是否含柱）直接決定提取出的數字代表什麼。36/42 不一致是「這批 Zone 沒有共同依據」的症狀，沒有共同依據，任何加總都不成立。
應用邊界，文件裡現在明文界定：
並補上一條可執行的捨入規則（與 backend 無關，Revit 側同樣適用）：建照審查不接受把程式算出的面積值直接寫在圖面上，必須搭配面積單線圖表明每一塊的形狀與長度並列出計算式。正確順序是 —— 長度取自圖面顯示值（公尺，至少三位小數）、一個形狀一條計算式、每條結果個別四捨五入到兩位小數、再把顯示值加總。絕對不可以原值相互加總：六位小數直接加總會因進位而與「先個別四捨五入再加總」的結果不同，且事後無法補救，會影響保存登記。
這反過來重新定位了本 repo 先前記錄的兩層數值模型：屬性層的顯示字串形式上接近規範要的顯示值，但沒有對應到面積單線圖的形狀與長度，仍不可直接充當依據；幾何層的六位小數原始 SI 值，正是規則明文禁止直接加總的「原值」。幾何層的高精度在這個情境下不是優點。
對既有判斷的修正
wall-orientation-check原本因「缺少 Wall.Flipped 等價值」列為能力缺口，兩項前提都不成立：flipped已被 0.5.3 接受（GetDetailsOfElements仍因另外 14 個欄位失敗，是 wrapper 回應模型過期，非 API 缺口）；elements_get_relations_of_elements的zoneRelations.wallParts是 Revit 房間檢測的原生等價物。單層實測 105 Zone 全數回傳，280 面牆得 196 內 / 69 外 / 15 無判定，覆蓋率 94.6%。建議升為 pilot 候選，判定一律標為候選、不自動翻轉牆。分頁在 0.5.3 可完整走完（全量 Wall 7376 筆 / 74 頁 / 0.6 秒），0.4.3 時代的 1600 筆上限未重現 —— 這補上 archicad-runtime-facts.md 先前標為 unresolved 的一項。
證據來源分層，以及沒有驗證的部分
文件裡逐節標明證據日期，沒有把沿用的觀察寫成本次實測：
element-coloring：以 property 值分組上色會把不同數值併成同一組 —— 這個風險由本次的 property 實測直接支持（回傳為 2 位小數字串，小數位來自專案設定而非數值本身）。Highlight 指令的 schema 亦於 2026-09-08 重讀，因而補上兩件原本漏掉的事：wireframe3D會把 3D 視窗中所有未高亮元素轉為線框（使用者會看到整個模型變線框、只剩一個元件有顏色，並且在 Archicad UI 裡找不到開關，因為那不是 Archicad 的顯示設定），以及清除時elements與highlightedColors兩者皆為必填，只傳空的elements會被拒絕。指令的實際染色行為本身未執行。detect-clashes：本次完全未重測。settings三欄必填與 Hotlink 排除的反面證據（project_get_hotlinks不回 GUID ownership）皆沿用 2026-08-19。Wave 2 表格新增「證據來源」欄逐列標示，
archicad-adapter-boundary.md第 3 節 A、B 也各自加註證據日期，避免「實測基準」那張表被讀成涵蓋全文。三份 domain 檔都在開頭標明權威正本何在（
archicad-runtime-facts.md、archicad-skill-portability.md、revit-archicad-terminology.md），衝突時以正本為準，避免同一知識兩處分叉。分級用 repo 正本的 A/B/C，並附上與 issue #98 那組英文詞的對照。一個順帶的提醒（不在本 PR 修改範圍）
上面第 3 點的應用邊界與捨入規則是 backend-neutral 的建築實務通則，Revit 側同樣適用。
domain/floor-area-review.md目前的流程是「取房間面積 → 加總 → 比對法規 → 輸出符合／超過」，該文件並未聲稱可用於建照圖面，但也沒有寫明應用邊界。建議維護者評估是否補上一段，避免讀者把房間面積總和當成可送審的面積計算結果。本 PR 沒有動那個檔案。本 PR 的範圍，以及被移出的東西
四個檔：
domain/archicad-adapter-boundary.md（新增）domain/archicad-terminology-map.md（新增）domain/archicad-portability-matrix.md（新增）domain/README.md（分類登記三行）我一開始還一併改了 22 個檔案——
.claude/skills下的 pilot 與 runtime facts、CLAUDE.md、README×2、DOCUMENT_AUDIENCE_INVENTORY、docs/BIM_MCP各頁與 hero 圖、scripts/gen-hero-grains.mjs——全部超出允許路徑，已經還原。會多做這些，是我把 repo 內部的規則套錯了對象：
verify-qaqc.ps1要求 domain 計數與各處索引一致，那是維護者維護main時的義務；對 fork 貢獻者而言，計數同步與索引更新本來就由收編時處理。這一點在既有紀錄裡看得很清楚——5dad238的訊息載明「Domain(79)／Skills(54)／Tools(180) 皆不變」，是維護者自行核算後落地的。被移出的內容沒有丟失，完整版保留在分支
evidence/archicad-pilots-2026-09-08（10 個 commit，含逐步推理過程），需要時可直接取用：pilot-room-numbering.md的 Live-Test Evidence（42 個 Zone 的 dry-run → 寫入 → read-back 完整 trace）pilot-quantity-takeoff-excel.md的 Live-Test Evidence 與應用邊界章節archicad-runtime-facts.md的「2026-09-08 re-run」一節（啟動前提、分頁、寫入靜默失敗、IsEditable、highlight 的 wireframe3D 副作用等）ops，與其他 meta-reference 一致）三份 domain 檔內文引用的
archicad-runtime-facts.md、archicad-skill-portability.md、revit-archicad-terminology.md在main上都已存在，指向有效；只是尚未包含本次新增的實測內容。.mcp.json與.vscode/mcp.json全程未納入，維持 Revit-only。兩點說明
main起算，兩者現在各自獨立。唯一交集是domain/README.md的分類表——本 PR 加三行、docs(archicad): add guarded structural DWG sync #131 加一行，先後收編時需合併該表，數量取合併後的實際值。