---
tags: [薄殼, 平台原則, 架構決策]
gloss: 所有業務能力只實作一次放在 API（cypher-executor），CLI/MCP/SDK 全是只做介面轉換的薄殼。
---
# 薄殼原則 — 能力長在 API

← [[decisions/00-INDEX]]

**來源**：`.claude/rules/07-thin-shell.md`、`system-dev/wiki/decisions-summary.md`（薄殼原則）
**最後更新**：2026-06-27

## 摘要
能力只實作一次放在 API；CLI / MCP / Python lib / JS lib 全是薄殼，只做參數解析 + HTTP 呼叫 + 格式轉換 + client 端加密，零業務邏輯。

## 重點
- 判準口訣：「這段邏輯換一個介面（CLI→MCP）要不要重寫？」要→它是能力，該在 API；不用→它是薄殼該做的。
- 違反例：CLI 迴圈 POST 多 recipe（seed 該是 API 行為）、MCP 先 update 失敗再 insert（upsert 該在 API）、SDK 自製 credential-injector（該在 WASM）。
- 齊的單位是「**能力**」不是「**端點**」：MCP=CLI 是出貨目標、不是任一時刻的不變量；底層 proxy 可有端點刻意不上 CLI/MCP（如 `/kbdb/entries` 裸 CRUD 消費者是 mira Python client）。
- 帳號統一：所有薄殼讀同一份身份來源（config.yaml / env），不可 CLI 連自架、MCP 連官方。
- hook 7.x 擋語法層可偵測的拼裝；藏在 helper 裡的邏輯擋不了，靠 code review。

## 實體
- **薄殼**（thin shell）— CLI/MCP/SDK 介面層，只暴露能力不實作能力。
- **能力**（business logic／業務邏輯）— 換介面要重寫的那段邏輯，必須下沉到 API 只實作一次。
- **API**（cypher-executor HTTP 端點）— 能力的唯一真相源、所有薄殼共同呼叫的後端。
- **端點**（endpoint）— API 的單一 HTTP 路由；齊的單位是能力不是端點，端點可刻意不上某介面。

## 關聯
### 內文知識關係
- 薄殼 >> 呼叫 >> API
- 能力 >> 下沉到 >> API
- 能力 >> 齊的單位是 >> 能力
- 端點 >> 不等於齊的單位 >> 能力
### 卡片關係
- [[薄殼原則-能力長在API]] >> 共享世界觀 >> [[工作流是default零件是例外]]
- [[薄殼原則-能力長在API]] >> 歷史成因見 >> [[薄殼規則晚於實作-MCP漂移是歷史債]]