Phase 1：差異評估

差異評估的產出是一份 change manifest——列出所有已知的新舊差異、每項的風險等級、以及需要的應對措施。這份清單是後續所有階段的依據：平行環境要驗證清單上的每一項、切換策略要先處理高風險項、退役前要確認清單上的所有相容性問題都已解決。

差異的三個維度

第一個維度是目標本身的變化。版本升級要看 changelog、breaking changes list、deprecated features list。平台遷移要看兩個平台的功能差異（共享主機沒有的 cron 彈性、VPS 有的 SSH 存取）。資料庫升級要看 SQL 語法差異、預設行為變更（如 MySQL 8.0 的 caching_sha2_password 預設認證方式）。

第二個維度是依賴關係。升級 PHP 版本時，所有 Composer 套件都可能受影響；升級 MySQL 時，ORM 的 SQL 生成可能不相容；遷移平台時，原本靠主機面板設定的 cron job 要改用系統 crontab 或雲端排程。依賴關係沒列完整，平行環境的測試就會漏掉受影響的元件。

第三個維度是過渡期的雙版本相容性。升級不是瞬間完成的——在切換的過程中，系統的某些部分跑新版本、某些部分跑舊版本。這段期間兩個版本必須能共存：資料庫的 schema 要同時相容新舊版本的程式碼、API 的回應格式要讓新舊版本的客戶端都能處理、session 格式要能跨版本延續。

風險分級

每一項差異分級後，高風險和阻塞項決定升級的可行性與時程。阻塞項超過團隊能處理的量時，升級可能需要拆成多個階段（先升到中間版本、再升到目標版本）或延後。

時程與管理層報告

差異評估的時程通常佔整個升級的 20-30%——看起來「還沒開始做」但這段時間的產出（change manifest）決定了後面所有階段的範圍。向管理層報告時用 change manifest 的風險分級表：「共 N 項差異，其中 X 項低風險、Y 項中風險、Z 項高風險、W 項阻塞。中高風險項的處理估計 M 天，阻塞項的替代方案評估需要額外 K 天。」

Phase 2：平行環境驗證

平行環境驗證的責任是用事實證明「新版本在跟 production 相同的條件下能正常運作」。它的產出是一份驗證報告——每一項 change manifest 上的差異都標上「已驗證通過 / 有問題待修 / 不影響」。沒有這份報告就切換，等於在賭新版本會正常。

建立平行環境

平行環境跟 production 越相似，驗證結果越可信。理想狀態是完全複製 production 的架構（同規格、同設定、同網路拓撲），只差目標元件的版本不同。成本限制下的折衷是用縮小版（較小的 instance、較少的資料量），但關鍵設定（PHP 模組、MySQL 參數、安全設定）必須跟 production 一致。

資料的處理要特別注意。用 production 的資料副本驗證最可靠（能觸發真實的邊界狀況），但如果資料含 PII，需要先脫敏處理。另一個選項是用 staging 環境的資料，但要確認 staging 的 schema 跟 production 一致——schema drift 會讓驗證結果失真。

驗證清單

平行期的時間長度

平行環境跑多久才能切換？取決於業務週期。如果系統有月結、季結的批次處理，平行環境至少要跑過一次完整週期。電商系統要跑過至少一個促銷活動。沒有明顯週期的系統，一到兩週的平行驗證通常足夠發現主要問題。

Phase 3：分批切換

分批切換的核心原則是不一次切 100%——先把最低風險的流量導到新環境，觀察一段時間確認正常，再逐步增加比例。

切換策略

共享主機通常只能用維護窗口策略——沒有 load balancer 做流量分配、沒有 DNS 權重可調。維護窗口的關鍵是時間規劃：備份（15 分鐘）→ 切換（30 分鐘）→ 驗證（30 分鐘）→ 恢復或回退（15 分鐘），在窗口內必須完成全部步驟，超時就回退。

切換期間的監控

切換開始後要密切觀察的指標：

• 錯誤率：5xx / 4xx 比例相對於切換前的基線
• 回應時間：p50 和 p99 相對於基線
• 業務指標：轉換率、訂單數、付款成功率（如果適用）
• 外部整合：第三方 callback 是否正常

回退觸發條件

在切換前就定義好回退條件，避免事故發生時還要開會決定要不要退：

• 錯誤率超過基線的 2 倍持續 5 分鐘 → 回退
• 核心業務流程失敗（登入、結帳、金流） → 立刻回退
• 回應時間超過基線的 3 倍持續 10 分鐘 → 回退

回退不是失敗——它是風險控制機制的正常運作。回退後排查問題、修正、重新走 Phase 2 驗證、再嘗試切換。

切換的通知

Phase 4：退役舊環境

切換完成後不要立刻刪掉舊環境——保留 1-2 週的冷備。這段時間處理長尾問題：DNS 快取還沒更新的客戶端、排程任務還指向舊 endpoint 的外部系統、舊環境上可能還有未遷移的資料。

退役前的檢查

• 舊環境的存取 log 是否歸零？（有流量代表還有東西指向它）
• 所有 cron job 是否都已在新環境運行？
• 外部系統的 webhook / callback URL 是否都已更新？
• 舊環境上有沒有需要歸檔的資料？（log、上傳檔案、備份快照）

退役步驟

1. 停止舊環境的應用服務（但不刪除）
2. 觀察 1 週——如果有問題可以快速重啟
3. 匯出需要保留的資料（log、uploaded files）
4. 刪除舊環境的運算資源（VM、容器）
5. 保留舊環境的最後一份備份 30 天，作為最後的保險
6. 清理舊環境的 DNS 記錄、SSL 憑證、IAM 角色

貫穿全程的升級紀律

一次只升一個東西

同時升級 PHP 版本 + 遷移到新主機 + 重構資料庫 schema，出問題時無法判斷是哪個變更造成的。每次升級只改一個主要元件，穩定後再升下一個。如果業務壓力要求一次完成，至少在 Phase 2 的驗證環境裡逐一引入、逐一確認。

每個階段轉換前備份

Phase 1 結束前備份 production 現況、Phase 3 切換前備份、Phase 4 退役前備份。三份備份各自獨立、各自有還原驗證。備份不只是「做了」——要實際測試過還原，確認備份的完整性。

記錄每一步

每個升級操作記錄在 repo 的 changelog 裡：什麼時間、誰做的、改了什麼、觀察到什麼結果。升級出問題時，changelog 是回溯「上一步做了什麼」的唯一依據。

在平行階段就練習回退

不要等到 Phase 3 切換時才第一次嘗試回退。在 Phase 2 的平行環境裡，刻意從新版本切回舊版本一次，確認回退路徑能走通、回退後服務能正常恢復。回退的演練跟升級的驗證同等重要。

跨分類引用

• → 接手維運：接手後穩定維運的下一步常是升級
• → 模組五：核心服務上 IaC：stateful 資源（RDS、S3）的升級涉及特殊的備份與切換策略
• → 模組八：治理好習慣：升級期間的變更紀錄對齊治理紀律
• → 模組七：infra 走 PR 流程：升級涉及的 IaC 變更走 PR review

矩陣本體

怎麼用這張表

讀到一篇文章時依下面三步定位：

第一步：辨識媒介。在哪個平台？電子報、部落格、新聞媒體、學術出版？對應到表中的一列。

第二步：辨識預設讀者。文章開頭幾段假設讀者知道什麼？如果開頭就用 COGS、CAC、LTV 而不解釋，預設讀者是 VC / 創辦人；如果開頭解釋每個術語，預設讀者是入門讀者。

第三步：辨識寫作目的。作者是要「告訴你發生了什麼」「給你交易訊號」「建立分析框架」還是「安撫某群人的焦慮」？目的決定該怎麼用文章的結論。

常見誤讀

把深度部落格當投資建議是最常見的誤讀。深度部落格寫「估值會被壓縮」是在建立分析框架，不是叫你賣股票；把它當交易訊號去做決策會出大事。

把產業內幕當大眾財經也常見。技術圈的「某家公司賣掉了」對工程師是賽道訊號，對大眾財經讀者沒太大意義；如果把這類文章轉給不懂技術的朋友看，他們會抓不到重點。

把大眾財經當深度分析則相反—大眾財經為了易懂會犧牲精確度，用它的結論去做策略判斷會踩到簡化過的論證。

判讀訊號

文章的術語密度、論證鏈長度、結論是否帶條件，三者能反映文章類型。深度部落格術語密度高、論證鏈長、結論帶條件；大眾財經三者都低；學術期刊三者都更高且引用嚴謹。把這三個訊號當定位錨點，能快速識別文章類型。

跟其他框架的關係

這個矩陣處理的是「文章類型定位」。它不處理「文章內容是否正確」（那要靠領域知識卡片 跟外部查證），也不處理「作者立場是否中立」（那需要立場揭露檢查）。三者組合起來才完整—類型定位告訴你該怎麼讀、領域知識告訴你內容是不是對、立場揭露告訴你該打多少折扣。

為什麼會寫超過目標讀者一級

寫商業分析的常見陷阱是把「自己熟悉的術語密度」當預設。寫作者跟 VC / 創辦人對 PLG、CAC、單位經濟、毛利 是日常詞彙、一句話三個術語也通順；但對技術背景讀者、這些術語都需要查、一句話三個術語就成了「停下來查三次」。

實際 case：Claude for Legal 之後 第一層擠壓段原本寫成：

毛利下降是讓 P&L 跑不過去的差距。PLG 的數學算不過來、要轉成 Sales-led 或 FDE、但這又拉高 CAC。兩頭夾擊—單位經濟受傷、估值倍數被壓。

3 句話塞了 6 個術語（毛利、P&L、PLG、Sales-led、FDE、CAC、單位經濟、估值倍數）。對 VC / 創辦人來說 3 秒讀完；對工程背景讀者來說每句都要停下來解碼、整段讀完得花 2-3 分鐘。

降一級的四個策略

策略一：拆因果鏈、每個邏輯 step 獨立成句

原版把「毛利下降 → PLG 數學算不過來 → 要轉 Sales-led 或 FDE → CAC 拉高 → 兩頭夾擊 → 單位經濟受傷 → 估值倍數被壓」這個 7 步推論壓進 3 句話。每步邏輯跳躍對熟悉領域的人是省力、對讀者是要在腦中補完跳過的步驟。

降一級的做法是把每個邏輯 step 獨立成段、用「第一 / 第二 / 第三」結構讓讀者跟得上：

• 第一、賺到的錢不夠付業務跟行銷（毛利下降的直接後果）
• 第二、免費試用變成燒錢（為什麼 PLG 數學算不過來）
• 第三、被迫轉成更貴的銷售模式（為什麼要轉 Sales-led / FDE）

每段獨立、讀者一次處理一個概念、不用在腦中疊三個跳躍。

策略二：術語首次出現時 unpack

原版的「PLG」連結到卡片、技術上沒問題、但讀者要中斷閱讀去點連結看卡片才能繼續。

降一級的做法是首次出現時直接在括號裡解釋一句：

PLG（Product-Led Growth、靠產品自己吸引用戶上來、不靠業務推銷）

讀者讀到這裡不用點開連結、括號裡的一句話就夠跟上後續論證。卡片連結保留、是給想深入的讀者用、不是預設動作。

策略三：加具體算式 / 數字

原版的「毛利下降」「兩頭夾擊」「估值倍數被壓」都是抽象描述。降一級的做法是配具體數字：

• 毛利下降 → 「從 70-80% 掉到 50% 出頭、30 個百分點差距」
• 兩頭夾擊 → 「收入端毛利從 70% 掉到 50%、支出端 CAC 從幾十美元跳到幾千甚至幾萬美元」
• 估值倍數被壓 → 沒有直接數字、但前後的因果鏈讓讀者能自己推導

抽象描述對熟悉領域的人是「我知道你在說什麼」、對讀者是「我不知道這個尺度多大」。具體數字提供尺度感。

策略四：避免術語連發、術語之間用「白話橋」連接

原版「PLG 的數學算不過來、要轉成 Sales-led 或 FDE、但這又拉高 CAC」是 4 個術語連發、白話讀者要在腦中組裝因果。

降一級的做法是用白話句連接術語：

PLG 不能用、改回業務面對面賣（Sales-led）、或乾脆派工程師駐點客戶辦公室（FDE、Forward Deployed Engineer）

「改回業務面對面賣」「乾脆派工程師駐點客戶辦公室」這兩句白話橋讓讀者看到從 PLG 轉到 Sales-led 或 FDE 的具體畫面、不是術語對術語的跳躍。

對照示範

同一段內容、用兩個 register 寫：

原版（深度部落格 / VC、創辦人）：

毛利下降是讓 P&L 跑不過去的差距。PLG 的數學算不過來、要轉成 Sales-led 或 FDE、但這又拉高 CAC。兩頭夾擊—單位經濟 受傷、估值 倍數被壓。

3 句、約 100 字。

降一級（MBA 教材 / 學生、經理人 / 工程背景讀者）：

這個毛利下降會連動三件事。

第一、賺到的錢不夠付業務跟行銷。 傳統 SaaS 賣 100 元、扣掉伺服器費用後剩 70-80 元（毛利 70-80%）、即使花 30% 在業務跟行銷也還能賺；AI 應用賣 100 元、要付給上游模型供應商的 token 費後只剩 50 元出頭（毛利 50%）、同樣花 30% 在業務跟行銷只剩 20% 利潤、損益表 P&L（公司一段期間內賺賠的財務報表）從正轉負。

第二、免費試用變成燒錢。 傳統 SaaS 的「免費試用」幾乎零成本—多開帳號伺服器頂多多用一點；AI 應用的免費試用每次都在燒 GPU 算力、是真實的成本支出。PLG（Product-Led Growth、靠產品自己吸引用戶上來、不靠業務推銷）模式靠的就是「免費試用零成本」這個前提、毛利掉到 50% 時這套數學就跑不下去了。

第三、被迫轉成更貴的銷售模式。 PLG 不能用、改回業務面對面賣（Sales-led）、或乾脆派工程師駐點客戶辦公室（FDE、Forward Deployed Engineer）、但這兩條路都讓 CAC（Customer Acquisition Cost、獲取一個新客戶要花的所有成本）從 PLG 的幾十美元跳到 Sales-led 的幾千美元、再到 FDE 的幾萬甚至幾十萬美元。

收入端（毛利從 70% 掉到 50%）被壓縮、支出端（CAC 上升 100 倍）被拉高—兩頭夾擊讓 單位經濟（每個客戶能不能帶來足夠收入回本獲客成本）受傷。投資人計算 估值 倍數時看到這個結構性壓縮、給的估值就低、新創 burn rate（每月燒錢速度）變相加速、生存難度提高。

5 段、約 500 字。長度增 5 倍、但讀者一次處理一個概念、不用中斷查術語。

篇幅成本跟對齊讀者的取捨

降一級的代價是篇幅 3-5 倍。寫作者要判斷這個代價值不值：

判別線：「我希望讀者直接吸收還是先學術語」。前者降級、後者保留密度。

跨領域應用：技術文章降級給商業讀者

降一級寫法不只用在「商業降給工程師」這個方向、反方向也成立。寫技術文章給商業讀者看時、同樣的策略適用：

• 拆因果鏈：把「Eventually Consistency 導致 stale read」拆成「資料更新後不會立刻所有人都看到、可能會看到舊版」
• Unpack 術語：「Eventual Consistency（最終一致性、資料更新會慢慢傳到所有副本）」
• 加具體數字 / 例子：「副本之間最多差 100 毫秒、千分之一的請求會讀到舊版」
• 用白話橋連接術語：「資料庫一寫入、其他副本可能要 100 毫秒才同步過來、這段時間讀到的是舊版」

矩陣框架的可遷移性：判別目標讀者層級 → 降一級寫法 → 對照原版檢查篇幅 vs 易讀性的取捨。任何跨領域知識傳達都適用。

完稿時的「降級檢查」

寫完一段後跑：

1. 數一下這段塞了幾個術語（縮寫、行話、領域特定詞）
2. 三個以上術語連發、考慮拆段或加白話橋
3. 因果鏈跳躍超過 2 步、考慮用「第一 / 第二 / 第三」結構拆細
4. 術語首次出現時、考慮在括號裡加一句解釋
5. 抽象描述（「夾擊」「擠壓」「鬆動」）配具體數字或例子

完稿後找一個目標讀者層級的人試讀、看哪段需要解釋、就是降級沒做夠的地方。

延伸閱讀

• 媒介—讀者—目的矩陣 — 識別文章類型跟目標讀者
• Claude for Legal 之後 — 採用降一級寫法的 case-analyses 示範

外部分析改寫的交付物是可遷移框架、不是風格轉換。把其他分析師文章交給 AI 改寫時，任務目標不能停在「改成本站語氣」「更正向」「更像教學」；真正要交付的是讀者能帶到下一個市場事件使用的判讀工具。

判別問題：「讀者讀完後，是否多了一個可重用的判斷問題或檢查表？」沒有，就還只是改寫。

情境

content/business/ 的建立過程是一場從「外部分析文章」到「本站教學型商業知識」的轉換實驗。commit 演變顯示，早期版本雖然有 WRAP、知識卡與 case analyses，但仍多次被讀者 feedback 拉回核心問題：

• #140：Widen Options 不能用稻草人修辭展示作者結論。
• #141：WRAP 是內部工具，不能直接當文章章節。
• #142：即使章節標題改了，正文仍要對齊標題承諾。
• writing-down-a-level：目標讀者是工程背景讀者，不是原文的投資人或創辦人。

這些問題共同指向一件事：AI 轉換文章風格不夠。文章要從「原作者如何看這件事」轉成「本站讀者以後如何判讀同類事件」。

理想做法

第一步：把任務定義成 frame extraction

輸入外部文章時，先問：

若事件只能產出「某公司發生某事」的摘要、沒有可遷移框架，就放在筆記，不硬寫成 case-analysis。

第二步：正文結構服務可遷移框架

教學型商業分析的穩定結構可以是：

1事件本身 → 結構性機制 → 長期影響 → 預警訊號 → 可遷移框架

這是責任順序，可依標題承諾調整。事件段讓讀者進場；機制段教為什麼；長期影響處理時間軸；預警訊號讓框架可被反證；可遷移框架讓讀者能帶走。

若某篇文章的標題承諾需要不同順序，可以調整；但最後仍要回答「這個事件教讀者下次看什麼」。

第三步：把原文觀點轉成判斷問題

風格轉換會把原文句子改得更順；框架轉換會把原文觀點改成讀者可問的問題。

判斷問題比結論更有價值，因為問題可以帶到下一個 case。

第四步：用預警訊號保護框架

可遷移框架需要知道何時失效。每篇 case-analysis 至少要有一段預警訊號，列出哪些觀察會推翻或削弱本文判讀。

沒有預警訊號的框架只是一組漂亮分類。讀者需要知道「何時重新評估」，才會把框架當工具，而不是把它當口號。

沒這樣做的麻煩

文章會變成原文摘要

AI 很擅長把原文改成不同語氣，但摘要仍然沿著原文的 frame 走。讀者得到的是「另一個版本的原文」，不是本站累積出的知識單元。

事件評論不可重用

若文章只回答「這件事代表什麼」，下次遇到不同公司、不同市場、不同產品時，讀者還是要從頭判斷。可遷移框架要回答「下次遇到相似事件，我要看哪些訊號」。

寫作規範會被誤解成表面風格

正向陳述、核心原則先行、商業邏輯先於 CASE 不是語氣規則；它們是把思考過程變成可重用知識的結構規則。若只做風格轉換，會通過部分表面檢查，但仍不符合知識庫目標。

跟其他抽象層原則的關係

判讀徵兆

核心原則：外部分析改寫的交付物是讀者可遷移的判讀框架，把原文變順只是表層。沒有框架、預警與下一步路由，文章仍停在摘要層。

適用：跟 vendor library / framework component（pagefind、Vue widget、React component、jQuery plugin）共存的客製、注入客製 UI、覆寫 vendor 樣式。 不適用：完全自家寫的元件（沒有 framework 介入）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 framework 邊界辨識、JS 操作的四級安全度、外部組件客製的四層合作。

何時參閱本文件

為什麼 framework-managed DOM 要當禁區

Framework（React / Vue / vendor JS widget）對它管的 DOM 子樹有所有權：

• State 變動觸發 reconciliation、子樹重建
• 我們改的 attribute / textContent / 子節點被還原
• innerHTML 改動可能觸發 Vue / React 的 dev mode 警告
• Event listener 失效（節點被替換）

把客製 UI 注入到 framework 邊界外（vendor root 的 sibling、或上一層 container 的另一個 child）→ framework 不管它 → 不會被還原。

Framework 邊界的識別

邊界的可見訊號

邊界外的 sibling / parent 通常是「自家 HTML」、安全。

範例：Pagefind 的邊界

 1<div class="search-page">           ← 自家 (邊界外、可控)
 2  <h1>Search</h1>                   ← 自家
 3  <div class="custom-filter">       ← 自家、客製 UI 放這裡
 4  </div>
 5  <div class="pagefind-ui">          ← Vendor root (邊界、入內就是禁區)
 6    <form class="pagefind-ui__form"> ← Pagefind 管
 7      <input ...>
 8      <div class="pagefind-ui__drawer">  ← Pagefind 管（重渲染時清空）
 9      </div>
10    </form>
11  </div>
12</div>

.custom-filter 跟 .pagefind-ui 是 sibling、不在 vendor 子樹內 → 用 CSS grid / absolute 定位讓它看起來在 search 流程內、但實際 framework 不管它。

JS 操作的四級安全度

對 framework-managed 元素的操作、按穩定性排序：

選擇規則：從最高安全度起步、不行才升級。

客製 UI 注入的兩種模式

模式 1：注入到 framework 邊界外（推薦）

1const customEl = document.createElement('div');
2customEl.className = 'custom-filter';
3customEl.textContent = 'Filter: All / Title / Content';
4document.querySelector('.search-page').appendChild(customEl);
5// 注意：appendChild 到 .search-page、不是 .pagefind-ui

 1.search-page {
 2  display: grid;
 3  grid-template:
 4    "h1"
 5    "form"
 6    "custom-filter"
 7    "results";
 8}
 9.pagefind-ui { grid-area: form / form / results / results; }
10.custom-filter { grid-area: custom-filter; }

CSS grid 把客製 UI 排到 search 流程的某個位置、framework 不知情、不還原。

模式 2：reparent framework 內節點（次優）

如果客製需要把 framework 內的某個元素移到別處 — reparent 整節點而不是改內部：

1const filter = document.querySelector('.pagefind-ui__filters');
2const target = document.querySelector('.sidebar');
3target.appendChild(filter);  // 整節點搬到 sidebar、不複製

整節點搬遷通常 framework 不會「還原」、因為 vDOM diff 看到 node 還在（只是 parent 變了）。

但有 case 例外（部分 framework 用 portal pattern、reparent 會被視為 unmount）→ 第 1 次嘗試後用 playwright 驗證行為、第 2 次失敗就停（見 requirement-protocol/failure-pivot-protocol）。

外部組件客製的四層合作（穩定性梯度）

跟外部組件合作時、選哪一層客製、決定升級時會不會壞。

選擇順序：先看公共介面有沒有提供（讀 docs）、沒有再用邊界層、再不行才碰邊界 DOM。內部結構層幾乎不要碰 — 升級時 minor version 都會壞。

範例：Pagefind 的客製優先順序

Wrong vs Right 對照

範例 1：客製 filter UI

錯（注入到 vendor 子樹內）：

1const filter = document.createElement('div');
2filter.textContent = 'Filter: ...';
3document.querySelector('.pagefind-ui__form').appendChild(filter);
4// → search 觸發 → form 重渲染 → filter 消失

對（注入到邊界外）：

1const filter = document.createElement('div');
2filter.className = 'custom-filter';
3filter.textContent = 'Filter: ...';
4document.querySelector('.search-page').appendChild(filter);

1.search-page { display: grid; grid-template-areas: "h1" "form" "filter" "results"; }
2.pagefind-ui { grid-area: form / form / results / results; }
3.custom-filter { grid-area: filter; }

範例 2：改 vendor 主題色

錯：

1.pagefind-ui__form { background: blue !important; }
2.pagefind-ui__search-input { color: white !important; }
3.pagefind-ui__button { background: darkblue !important; }
4/* ... 8 條 important */

升級後 class 改名 → 全壞。

對：

1:root {
2  --pagefind-ui-primary: #2c5282;
3  --pagefind-ui-text: #fff;
4  --pagefind-ui-background: #1a202c;
5}

讀 vendor docs、用提供的 CSS var。升級安全、5 行解決。

範例 3：把 vendor filter 移到 sidebar

錯（複製 + 同步）：

1const original = document.querySelector('.pagefind-ui__filters');
2const clone = original.cloneNode(true);
3sidebar.appendChild(clone);
4// → 兩份、state 不同步、click 事件 listener 沒複製

對（reparent 整節點）：

1const filter = document.querySelector('.pagefind-ui__filters');
2sidebar.appendChild(filter);  // 整節點搬遷、event listener 跟著、state 唯一

整節點搬遷通常安全 — vDOM 看到 node 還在、不會 reconcile。寫完先用 playwright 驗證行為（dispatch input / click 看 filter 是否還工作）。

自檢清單（dogfooding）

跟 framework / vendor library 共處時：

• 我有沒有先看 vendor docs、確認有沒有公共介面（CSS var / API）？
• 客製 UI 是注入到 framework 邊界外、還是內部？
• JS 操作的元素是 framework 管的子節點嗎？如果是、有沒有用「四級安全度」最高的操作？
• reparent / 改 attribute 後、有沒有用 playwright 驗證 framework 沒還原？
• 升級風險有攤給使用者嗎？（見 requirement-protocol/cost-and-checkpoint）

延伸閱讀

對應的事後檢討（在 content/report/）：

• coexisting-with-framework-managed-dom — 客製 UI 留 framework 邊界外、用 CSS 控制視覺位置
• component-boundary-and-js-impact — JS 操作 framework 元件的邊界辨識
• external-component-customization — 在外部組件上加客製功能：以邊界為中心
• external-component-collaboration-layers — 跟外部組件合作的四層次

Last Updated: 2026-04-26 Version: 0.1.0