---
tags: [薄殼, 平台原則, 架構決策, 機制說明]
gloss: 防 CLI/MCP 薄殼漂移（死端點假綠）的雙層機制——靜態能力對照清單 + 本機 smoke test 對真端點斷言非 404。
---
# 薄殼防複發 — 能力對照表 + 本機 smoke

← [[decisions/00-INDEX]]

**來源**：`system-dev/docs/3-specs/thin-shell-alignment/design.md §5`（issue #11）、`docs/4-guides/cli-mcp-capability-matrix.md`、`scripts/thin-shell-smoke.sh`
**最後更新**：2026-06-27

## 摘要
治「薄殼打了不存在的 server 端點」（死端點假綠）用雙層：靜態能力對照清單（review 防線）+ 本機 smoke test（對真端點斷言非 404，死端點當場現形）。本機手動跑，非 CI。

## 重點
- **根因是假綠**：MCP deploy 在宣稱「一致性落地」的同一 commit 裡打了不存在的 `/workflows/deploy`（必 404），從未端到端跑過。光靠「宣稱對齊」會再犯。
- **層 1 能力對照清單**（`docs/4-guides/cli-mcp-capability-matrix.md`）：表「能力 × CLI 端點 × MCP 端點 × route 存在? × 同源?」，新薄殼能力必填一行，填前 grep 確認 route 存在。
- **層 2 本機 smoke**（`scripts/thin-shell-smoke.sh`）：對每能力打真端點斷言非 404。**本機手動跑非 CI/cron/輪詢**（守 flag 紅線，對齊「執行鏈路不依賴 CI」鐵律）。
- **機制自驗**：注入故意死端點 → smoke 當場攔下、exit 1（已驗證能攔）。
- **smoke 區分「code 有 route」vs「prod 真部署」**：首跑就揭 #8 search/backfill 在 prod 仍 404（code 已 commit 但未部署）——這正是它要揭的假綠。
- **不用 CI 高頻打真端點**（違 flag 紅線）；smoke 是「宣布完成前手動跑一次」的閘。

## 實體
- **能力對照清單**（cli-mcp-capability-matrix）— 靜態表列每能力的 CLI/MCP 端點與 route 存在性，review 防線。
- **本機 smoke test**（thin-shell-smoke.sh）— 對真端點打、斷言非 404 的腳本，死端點現形，本機手動跑。
- **死端點假綠**（dead endpoint）— 薄殼打了 server 不存在的 route（404），卻被宣稱成完成。
- **機制自驗**（注入死端點測試）— 故意加不存在端點驗 smoke 能攔，證明機制有效。

## 關聯
### 內文知識關係
- 死端點假綠 >> 被攔於 >> 本機 smoke test
- 能力對照清單 >> 互補於 >> 本機 smoke test
- 機制自驗 >> 證明 >> 本機 smoke test
- 本機 smoke test >> 區分 >> 死端點假綠
### 卡片關係
- [[薄殼防複發-能力對照表加smoke]] >> 治理 >> [[薄殼規則晚於實作-MCP漂移是歷史債]]
- [[薄殼防複發-能力對照表加smoke]] >> 落實 >> [[薄殼原則-能力長在API]]