---
tags: [平台原則, 架構決策]
gloss: 缺能力的補救階梯：自家 API 缺→補進 API；第三方 API 缺→workflow/code-node 補丁；純計算→code-node；才建零件。
---
# 自力救濟階梯 — 缺能力怎麼補

← [[decisions/00-INDEX]]

**來源**：`system-dev/wiki/decisions-summary.md`（自力救濟階梯）、`.claude/rules/07-thin-shell.md §3.5`
**最後更新**：2026-06-27

## 摘要
缺一個能力時的補救路徑分級。主問「那個 API 你能改嗎」：能改→補 API；改不了（第三方）→走 workflow/code-node 補丁；不入任何 API 的純計算→code-node；真需新穩定能力（極少）→零件 PR。

## 重點
- **階梯概覽**：
  | 情況 | 正解 | 為何 |
  |---|---|---|
  | 能打既有 API | **recipe**（無則建） | 單一 API 呼叫的封裝 |
  | 自家 API 缺能力 | **補進 API** + 可同時發 issue | 你能改，能力該長在 API |
  | 第三方 API 缺能力 | **可投稿的 workflow 補丁** | 改不了第三方，用資料方式自救 |
  | 純計算（如文本轉大寫） | **code-node**（空白零件寫 JS） | 不該為此建一堆專用零件 |
  | 真需新穩定能力（極少） | 自建零件 → PR | 維持零件庫最小 |

- **第三方 API 缺能力的實例**：Google Sheets 一次只能倒全部、輸出前無法 filter；原廠不開此 API → arcrun 補不進去 → 正解是投稿一個 workflow 補丁「倒出後自己篩」。
- **Upsert 範例**（區分自家/第三方）：
  - Stripe 原廠提供 upsert API → recipe 直打
  - Notion 沒 upsert API → 做一個 upsert workflow（先 GET 找、有則 PATCH 無則 POST），不是建零件
- **Hook 無法防守的**：§3.1 禁的是「介面層 TS 拼裝」（hook 7.x 擋），不是禁「資料方式補丁」。workflow/code-node 是 YAML/空白零件內的 JS，非介面層 TS → hook 範圍外、合法不被擋。
- **補丁轉正**：原廠出 API 後，補丁 workflow 因效能較差自然淘汰；不需特別移除。

## 實體
- **自家 API**（arcrun-owned API）— arcrun 官方開發的 API（如 cypher-executor 端點、KBDB 基本盤），改動權掌握在 arcrun。
- **第三方 API**（third-party API）— 外部服務提供的 API（Google Sheets、Stripe、Notion），改不了。
- **Workflow 補丁**（workflow patch）— 用戶投稿的 workflow YAML，用來補第三方 API 缺的能力，可被多人重用。
- **Code-node**（代碼節點）— 空白 zero-logic 零件內直接寫 JavaScript，用於純計算。
- **零件庫污染**（component bloat）— 為了單一功能、改不了的第三方 API 新建零件，長期難維護。

## 關聯
### 內文知識關係
- 自家 API 缺 >> 正解是 >> 補進 API
- 第三方 API 缺 >> 無法補 API >> 走 workflow 補丁
- 純計算 >> 應該 >> code-node
- 零件庫污染 >> 來自 >> 為第三方缺口建零件
- 補丁 workflow >> 因效能差 >> 自然淘汰
### 卡片關係
- [[自力救濟階梯-缺能力怎麼補]] >> 補充 >> [[工作流是default零件是例外]]
- [[自力救濟階梯-缺能力怎麼補]] >> 關聯 >> [[薄殼原則-能力長在API]]