先判斷你遇到的是「看不到外掛」「無法連線」還是「有結果但不符合預期」，每種症狀都有固定四段：你可以先檢查、正式程序、要收集什麼、怎麼回報。維護者用的診斷表與 2026-05-18 的歷史案例放在後面。
點選最接近的症狀。三種都不像時，先看下方「先確認啟動順序」。
Revit ribbon 沒有 MCP Tools 面板。
AI 說找不到 Revit tools、連不上 localhost:8964，或被拒絕連線（HTTP 409）。
工具有回傳，但內容和你眼前的 Revit 或預期不同。
localhost:8964。來源：README.zh-TW.md「啟動流程」。
Revit 已開啟，但 ribbon 上沒有 MCP Tools 面板。
.addin 與 DLL 是否已部署到對應版本的 %APPDATA%\Autodesk\Revit\Addins\{version}。.\scripts\install-addon.ps1 -Version 2024-All。MCP/bin/Release.R{YY}/RevitMCP.dll），找不到 DLL 時看下方 經典問題。部署頁 · 手動安裝；第一次安裝的紅字錯誤見 docs/troubleshoot-first-install.md。
把上面三項填進下方 回報模板。
AI 說找不到 Revit tools，或 MCP Server 連不上 Revit。
localhost:8964 沒有被其他程式佔用；AI Client 的 REVIT_MCP_PORT 要與 Revit 端設定一致。MCP-Server 已執行過 npm run build、AI Client 設定指向 MCP-Server/build/index.js，並已重啟或重新載入 MCP servers。PID 4（System）卡住：用管理員身分執行 scripts\release-port.ps1。經典問題表、README.zh-TW.md 的「AI Client 切換與並用限制」與「常見問題」。
填寫 回報模板，並註明你已試過上面哪幾項。
連線正常，工具也有回傳，但內容和你眼前的 Revit 或預期不同。
get_active_view，確認目前的專案與作用視圖就是你正在看的那一個；不要沿用前一輪的視圖 ID 或樓層名稱。domain/*.md，不是寫死在工具裡（見 歷史案例 #4）。不要用猜的補 Revit 專案資料、部署頁 · 第一次查詢、歷史案例。
填寫 回報模板；貼出工具回傳前先移除專案與個人識別資料。
公開貼出前，請移除專案與個人識別資料。填好後到 GitHub Issues 回報。
前四列是使用者自己能處理的；最後兩列要看程式碼與 log，歸維護者診斷。
| Symptom | Root cause | Fix |
|---|---|---|
| Build 出現 warnings | warning 與 error 不同；warning 的數量依 Revit 版本而異 | 確認沒有 error 即可。 |
RevitMCP.dll not found |
Build config 拼錯或 output 路徑改了 | 使用 dotnet build -c Release.R{YY} RevitMCP.csproj，YY ∈ {22,23,24,25,26}。Output 在 MCP/bin/Release.R{YY}/RevitMCP.dll。 |
| MCP Server connection failed | (a) npm run build 沒跑 / (b) AI client 設定路徑錯 / (c) port 被佔 |
(a) 在終端機分兩行執行：build/index.js(c) 跑 scripts\release-port.ps1 |
Port 8964 被 PID 4（System）佔用 |
Revit 異常關閉後 HTTP.sys 留下孤兒 Request Queue | 以系統管理員身分執行 scripts\release-port.ps1。手動處理時，兩個指令分成兩行各自執行（部分終端機不接受把兩個指令串在同一行，見 docs/troubleshoot-first-install.md 問題一）： |
| Symptom | Root cause | Fix |
|---|---|---|
| Commands 送出去沒回應 | Revit UI thread 被卡（沒走 ExternalEventManager） | 確認從 WebSocket 進來的 Revit API 呼叫都經過 ExternalEventManager.Instance.ExecuteCommand(...)。看 %AppData%\RevitMCP\Logs\RevitMCP_YYYYMMDD.log 確認 ExternalEvent 是否被觸發。 |
| 握手立即被拒（HTTP 403） | 連線的 handshake 帶有瀏覽器的 Origin 標頭；Revit 端為擋掉瀏覽器分頁操控 add-in，一律拒絕，且沒有設定可關閉 |
MCP bridge 本身不會送 Origin；出現 403 時檢查是否有非 bridge 的程式（例如瀏覽器）在連 localhost:8964。 |
部署時哪些事不能做（例如不要新增版本專用的 project 或 .addin），統一寫在 部署頁 · 手動安裝。
以下是 2026-05-18 當時的紀錄，保留作為「工具邊界怎麼被發現」的案例，不是目前要你操作的步驟。5/18 demo 實機跑 5 個工具暴露 5 種典型 MCP 工具邊界樣態（output 過大 / API 不對稱 / 工具設計差異 / 真實 bug / 只回 raw data）。這個歷程本身是 P15「排程死線」 + 第二憲法 Data Honesty 的活體實證。
check_exterior_wall_openings · 輸出超限
對一整層樓跑外牆開口檢查，工具回傳 JSON 過大（每個 opening 都帶完整 geometry），AI 端 context window 被吃光，後續無法繼續對話。
原預設輸出 verbose mode，每個 opening 帶 BoundingBox + Solid geometry + 鄰地距離計算中間值。對 UI 顯示有用，對 AI context 是噪音。
新增 summary 模式（預設）：每個 opening 只回 ID + Wall reference + 鄰地距離 + PASS/FAIL。若需細節再傳 detail=true。
所有可能回大量 elements 的工具都應該預設 summary、選配 detail。這是「工具設計差異」型別。
check_smoke_exhaust_windows · 80+ 視圖污染
對整個專案跑排煙檢查，工具自動建立 80+ 個 annotated views（每個居室一個剖面圖）。專案視圖樹爆炸，用戶手動刪 30 分鐘。
原本想做 demo 視覺效果——「每個居室都附剖面與標註」。實務上大多數情境只想要 PASS/FAIL 列表，不想視圖。
把 createAnnotatedViews 預設改為 false。需要視圖才主動傳 true。批次工作流請顯式指定 viewId 不要靠 active view。
「會修改模型」的副作用必須 opt-in 不能 opt-out。這是「真實 bug + 工具設計」混合型別。
check_stair_headroom · 不支援 batch
整層樓有 5 個樓梯需要檢查淨高。工具一次只能檢一個 stair element，AI 連續呼叫 5 次造成 round-trip 延遲與容易超時。
初版設計時只想到「點選一個樓梯檢查」，沒考慮整層批次需求。API 不對稱——其他類似 check_* 工具都支援 batch。
新增 stairIds 陣列參數（可選），傳入則批次處理。原本單一 stairId 參數仍保留向後相容。
新工具的 API 預設要考慮「同類元素批次」需求。這是「API 不對稱」型別。
get_room_daylight_info · 只回 raw data
使用者期待工具直接回 PASS/FAIL「採光達標」，實際只回 raw data（窗 ID、面積、台度高度等），需要再套公式才知道結果。
這是 spec by design 不是 bug——PASS/FAIL 屬於 第三憲法 Domain Method Compliance 的範疇，由 domain/daylight-area-check.md 規定（含 75cm 台度扣除、外牆門納入等規則），不應該寫死在工具裡。法規修訂時改 domain 一份，工具不動。
不改工具，改練習頁說明。Step 4 改用 level='1FL' + 提示要手動套 75cm 公式，並連到 domain 完整 SOP。
Tool 回 raw data，PASS/FAIL 留給 domain SOP。這是 MCP 架構的核心紀律，違反會導致「法規一改要改 N 個工具」。這是「只回 raw data」型別。
%AppData%\RevitMCP\Logs\RevitMCP_YYYYMMDD.log
看 ExternalEvent 是否觸發、CommandExecutor 是否收到指令、有無 exception。
stdout / stderr — Claude Desktop 看 ~/Library/Logs/Claude/mcp*.log（Mac）或 %AppData%\Claude\logs\mcp*.log（Win）
看 WebSocket 連線是否建立、tool schema 是否載入。
log/YYYY-MM.md
保存 AI session 摘要、commit 對應、手動紀錄。看「最近發生什麼」。
git log --stat -5 或 git show 4975ceb
看最近 commit 改了什麼。比 log/ 還即時。
get_project_info smoke test）