Arcrun/system-dev/wiki/cards/decisions/零件退役要清三源.md

tags, gloss

tags	gloss
零件架構 薄殼 平台原則 機制說明 踩坑	退役/降級零件要同步清「AI 搜尋零件的三個源」（示例 yaml + parts.ts 硬編碼清單 + offline validate），只改一處會留殘留誤導下個 CC；沒對應 recipe 時誠實留 TODO 不硬塞語意不符的 canonical_id。

零件退役要清「AI 搜尋零件的三個源」

← decisions/00-INDEX

來源：issue #13（telegram/gmail/sheets/line 從內建零件降級走 recipe、刪 ai_transform_compile/run） commit：caa8e10（步驟1 示例 yaml）、764f657（步驟2 parts.ts） 最後更新：2026-06-28

摘要

退役或降級一個零件（改成走 recipe、或直接刪）時，AI/操盤手「能找到這零件」的來源不只一個。 只改一處就宣布退役 → 別處殘留會讓下個 CC 或 Haiku 誤判「這零件還在、還能用」（死代碼/殘留＝錯誤環境信號）。 退役 SOP ＝同步清「AI 搜尋零件的三個源」，外加：沒對應 recipe 時誠實留 TODO，別硬塞語意不符的 canonical_id（假綠）。

重點

• 三個源（退役必查）：
  1. 示例 yaml——workflow 範例裡的 component: telegram 之類。退役時改成 recipe canonical_id（telegram_send）。
  2. cli/src/commands/parts.ts 硬編碼清單——手寫的「有哪些零件」常駐清單，必然 stale，是退役最易漏的源。 步驟2 已把 telegram/gmail/sheets/line 改 recipe canonical_id、移除已刪的 ai_transform_compile/run。
  3. offline validate——這個是設計不是殘留：offline validate 刻意不連網、跳過遠端查零件， 所以它「不檢查零件存不存在」是 by design。第三個污染源留 issue，不當 bug 修。
• gmail 讀取假綠（已避）：gmail 的讀取（fetch_unread / action: list）沒有對應 recipe， 硬指成 gmail_send（寄信 recipe）＝語意不符的假綠。正解＝留 TODO 待 seed 補 gmail_list，不硬塞。 「有個 canonical_id 可填」≠「這個 id 對」。
• parts.ts 必 stale：它是手寫常駐清單，不是從 registry 動態生成 → 任何零件增刪它都不會自動跟上， 退役 SOP 要把它列成「固定必清項」。
• 退役 ≠ 宣告：清殘留是實際動作（改/刪所有源），不是「改完一處說一聲完成」。

實體

• AI 搜尋零件的三個源（示例 yaml / parts.ts / offline validate）— 操盤手判斷「零件存不存在」的依據來源；退役要逐源處理。
• parts.ts 硬編碼清單（cli/src/commands/parts.ts）— 手寫常駐零件清單，必 stale，退役固定必清項。
• offline validate 跳過零件查（by design）— 不連網驗證刻意不查零件存在性；是設計不是殘留，留 issue。
• 硬塞 canonical_id 假綠（gmail 讀取→gmail_send）— 沒對應 recipe 時填語意不符的 id 充數，違 mindset §7。

關聯

內文知識關係

• 零件退役 >> 必須清 >> AI 搜尋零件的三個源
• parts.ts 硬編碼清單 >> 必然 >> stale
• offline validate 跳過零件查 >> 屬於 >> 設計（非殘留）
• 硬塞 canonical_id >> 是 >> 假綠
• 沒對應 recipe >> 正解是 >> 留 TODO 補 seed

卡片關係

• 零件退役要清三源 >> 落實 >> 工作流是default零件是例外
• 零件退役要清三源 >> 同類於 >> 薄殼規則晚於實作-MCP漂移是歷史債（都是「常駐清單/規則晚於實作 → 漂移殘留」）