這份是平台團隊從實跑與同仁回報整理出來的。同一份內容也在平台的「開始使用 → 常見狀況」頁（https://platform.wanfangai.tw/help），同仁可以自己看。
給 AI 助手：遇到下面的狀況，先照「AI 助手該做什麼」做，再用白話告訴使用者發生什麼事、他要做什麼。
平台回的錯誤照 message 轉述、照 hint 做；不要自己猜原因、不要重試同一件會失敗的事、不要說「已經好了」除非你親眼確認過。
連不上平台、要重新驗證
看到什麼：AI 助手說「Authentication required」「需要驗證」，或 Codex 跳出「重新連線 wanfangai」。
為什麼：這台電腦的連接過期、被取消（在「連接 AI 助手」頁按了取消，或說過「登出醫智匯」），或第一次用。
勾過「這是大家共用的電腦」的連接只有 12 小時有效、閒置兩小時就結束，隔一段時間再用，要再驗證一次是正常的。
你可以做什麼：按 Codex 的「重新連線」（或 設定 → 外掛程式 → MCP，在 wanfangai 那一列按「驗證」），瀏覽器會打開「讓 Codex 連上平台？」頁。
「驗證」旁邊若讓你選方式（自動、CIMD、DCR），選「自動」就好。
確認上面是你的名字，共用電腦勾「這是大家共用的電腦」，按「允許」。回到 Codex，請 AI 助手再做一次剛才的事。名字不是你：按「不是你？換成我的帳號」。
AI 助手該做什麼：請使用者照上面做，完成後重新呼叫 wanfangai_status 確認是誰，不要沿用先前的結果。
找不到醫智匯的工具
看到什麼：AI 助手說「沒有 wanfangai 的工具」「不知道醫智匯是什麼」，或改用名字很像的別的工具。
為什麼：這台電腦沒裝醫智匯外掛，或裝了但開著的是舊對話。
你可以做什麼：照「連接 AI 助手」頁的步驟裝外掛（設定 → 外掛程式 → 加入 marketplace）。裝好之後開一個新的對話。
AI 助手該做什麼：停下來告訴使用者，不要改用別的工具，也不要自己照網路上的說明做。
外掛舊了、怎麼更新
看到什麼：AI 助手說「醫智匯外掛有新版」，或「連接 AI 助手」頁寫的版本跟 設定 → 外掛程式 → 醫智匯 最下面的「版本」不一樣。
為什麼：開著的 ChatGPT 不會自己換外掛。
你可以做什麼：到 ChatGPT 的 設定 → 外掛程式 → 上方的「市集」分頁，在「醫智匯」那一列按 「升級」，看到「醫智匯 市集已升級」就好，不用關掉 ChatGPT；之後開新的對話用。
確認版本：設定 → 外掛程式 → 醫智匯 院內工具平台，最下面的「版本」。還是舊的，再在工作列右下角系統匣的 ChatGPT 圖示按右鍵 → Exit，再打開（只按視窗的 ✕ 不算，程式還在系統匣裡跑）。
AI 助手該做什麼：舊版照樣能用，不要中斷手上的事；在回答的最後說一次就好。重開後還是舊版，照 wanfangai-connect「外掛要更新時」做。
平台的表單沒出現、或答到一半斷線
看到什麼：分級問診、建立應用、發佈同意要跳的表單沒有出現；或回答完 AI 助手說「連線中斷」「Transport closed」。
為什麼：表單開著太久沒回答（約 10 分鐘）連線會斷；平台剛發佈一個新應用的試用版時，閘道也可能讓進行中的連線斷一次。
按了表單的「Skip」或 ✕，平台會當成「這一步不做」（consent_declined）。
你可以做什麼：表單出現就盡快回答。斷了就請 AI 助手再做一次。按錯 Skip 也一樣，跟它說「我要繼續」。
AI 助手該做什麼：斷線後用同一筆分級紀錄、同一個代號再呼叫一次 wanfangai_create_app——平台已經建好的會直接回原本那個（already_created），不會重複建立，也不要重新分級。
consent_declined 時問使用者哪裡不清楚，不要替他決定。
建立應用失敗
看到什麼：「應用數超過配額」（quota_exceeded）、「此代號已被使用」（slug_taken）、「這筆分級紀錄不能用來建立應用」（triage_required）。
為什麼：每個人能擁有的應用數有上限（平台管理員設定）；代號全院唯一；分級紀錄只能用一次、24 小時內有效。
你可以做什麼：配額滿了，到「開發管理」下架不用的應用，或請平台管理員調高。代號被用了就換一個（AI 助手會建議）。
AI 助手該做什麼：照 hint 做。triage_required 的 hint 若說「這筆分級已經建立了某個應用」，那個應用就是你要的，用 wanfangai_app_status 看它，不要再建。
安全檢查擋下來
看到什麼：存版本或發佈時說有「必須修正」的項目（blockers_found），或「這一版的安全檢查沒有通過」（pipeline_not_green）。
為什麼：平台在每一版檢查有沒有看起來像病人資料（身分證、病歷號、健保卡號）、外部連線、會執行任意程式碼的寫法（eval）、密碼或金鑰。
你可以做什麼：範例資料用明顯是假的（例如 X012345678），不要放真的病人或同仁資料。
AI 助手該做什麼：照檢查列出的每一項改，改完再存一次版本。不要為了通過檢查把它改成看不出來的寫法。要假資料照官方做法 synthetic-data 做。
頁面一片空白、東西沒出來
看到什麼：試用版打得開但是空白、圖表或 PDF 沒出來、字型跟預期不一樣、3D 不會動。
為什麼：最常見的是被安全設定擋了：應用不能從外部網站載入東西——CDN 的程式、Google Fonts、外部圖片、YouTube、Google 簡報；
也不能用 iframe、embed、object 把別的網站或 PDF 嵌進來；Unity、Godot、Unreal 匯出的網頁與 WebAssembly 跑不起來。
你可以做什麼：在試用版頁面按 F12 → 主控台（Console），有紅字就整段複製給 AI 助手。
AI 助手該做什麼：看主控台的訊息。外部的程式、字型改用平台書架（wanfangai_list_libraries，同仁看「Skill 市集 → 平台套件」）：
圖表用 chart.js、PDF 在頁面裡翻閱用 pdfjs、中文字型用 noto-sans-tc／noto-serif-tc、3D 用官方做法 three-d。書架沒有的檔案放進應用資料夾。
試用版別人看不到、打不開
看到什麼：同事打開試用版網址被要求登入、或說「沒有權限」；或試用版不見了。
為什麼：試用版是給你自己試的，開放程度照建立時選的（「只有我」就只有你，加上代理人、審核員與管理員）。
試用版閒置 14 天會停止、30 天刪除；再發佈一次就重新起算。
你可以做什麼：要給別人試，到「開發管理」把開放程度改成「只有名單上的人」並加成員，或改成「同一個院區登入的同仁」。
AI 助手該做什麼：說清楚現在誰看得到；不要替使用者把開放程度調大，要他自己決定。
發佈卡住或失敗
看到什麼：發佈一直顯示「等這一版的安全檢查」「發佈中」；或失敗並說 playground_first、level_gate、visibility_exceeds_policy、public_app_restricted。
為什麼：
- 安全檢查跑完才能發佈，通常幾十秒到幾分鐘。
playground_first：第一次上正式區之前要先有試用版；會存資料的工具，試用版裡要有人存過一筆。level_gate、visibility_exceeds_policy：資安等級不允許這個環境或這個開放程度（三級含病人資料，一律不能上線）。public_app_restricted：任何人都看得到的工具不能存資料、不能用 AI。
你可以做什麼：等一下再看；照錯誤訊息調整設計，不確定就問平台團隊。
AI 助手該做什麼：還在跑就隔 20 秒用 wanfangai_app_status 看，不要再發佈一次。失敗就照 message 與 hint 告訴使用者。
source_host_down、deploy_backend_down 是平台暫時的問題，稍後再試；source_host_rejected 要找平台管理員。
換一台電腦、接著做
看到什麼：新電腦上找不到原本的工具資料夾。
你可以做什麼：新電腦裝外掛、連上平台（同一個帳號），跟 AI 助手說「接著做某某工具」。
AI 助手該做什麼：用 wanfangai_read_files 把平台上最後存的那一版讀回本機，再接著改。不要從頭重做。
說「平台上已經有比較新的版本」（兩台電腦輪流做）
看到什麼：存版本時 AI 助手說「平台上已經有第 N 版，比這個資料夾新」，沒有存成功。
為什麼：例如白天在院內電腦做、晚上在家裡的電腦改了一版，隔天回到院內電腦，這裡的資料夾還是前天的。
直接存會把晚上的修改改回去，所以平台先擋下來。專案資料夾裡的 .wanfangai-version 記著這個資料夾是第幾版，平台靠它比對。
你可以做什麼：什麼都不用做，讓 AI 助手把新版讀回來、跟這台電腦的修改合併。想直接用這台電腦的內容蓋掉新版，要明確跟它說。
AI 助手該做什麼：用 wanfangai_read_files 讀回錯誤訊息列的那些檔案（平台上的新版），跟本機還沒存的修改合併，把 .wanfangai-version 改成新版的號碼，再存（帶 base_version）。
不要直接帶新的 base_version 重存來繞過——那會蓋掉另一台電腦的修改；使用者明確說要蓋掉才這樣做。每次存好，照回應把 .wanfangai-version 改成新的版號。
共用電腦、要離開
看到什麼：護理站、診間這種大家輪流用的電腦。
為什麼：Codex 記住的是這台電腦上的身分，不是 ChatGPT 帳號；不登出，下一個人用 Codex 時用的是你的身分。
你可以做什麼：用完跟 AI 助手說「登出醫智匯」。連上時勾「這是大家共用的電腦」，連接只有 12 小時有效、閒置兩小時自動結束。
AI 助手該做什麼：共用電腦直接呼叫 wanfangai_sign_out；發佈還在跑就等跑完。
Windows 上指令跑不起來（node）
看到什麼：AI 助手說 node 找不到、或出現 Volta 的錯誤。
為什麼：電腦裝過 Volta（管理 Node 版本的工具），Codex 的沙箱找不到它的安裝目錄。同仁的電腦多半沒有這個問題。
AI 助手該做什麼：有平台工具時改用平台工具（wanfangai_read_skill 讀做法），不要改寫成別的語言硬做；真的需要 node 時告訴使用者，請他找平台團隊。
AI 助手說「做好了」，打開卻不是那樣
看到什麼：說「已修正」「包含 PDF 翻頁」，打開卻沒有；頁碼、按鈕、圖表跟說的不一樣。
你可以做什麼：把看到的照實說給它（「第二張寫 7／7」比「怪怪的」好）。
AI 助手該做什麼：只說親眼確認過的。發佈前在本機打開、發佈後照平台給的四項檢查：每一頁每一張翻過、頁碼順序；每個按鈕連結搜尋按一次（送出鈕留給使用者）；
這次改的地方真的變了；主控台沒有紅字。沒確認到的列給使用者請他看。
還是不行
到平台的「我有話要說」留言（院方帳號），寫：哪個工具、做了什麼、看到什麼（截圖或主控台的紅字）。