3.3 API 與介面設計（ACI vs HCI）#

介面：模組之間的契約#

第 3.1 節強調了「介面」作為模組邊界的核心地位。本節把視角聚焦到介面設計這件事本身——尤其是現代系統中最重要的介面類型：API（Application Programming Interface，應用程式介面）。

一個好的 API，就像一張文明的合約：它定義了「你能怎麼用我、我保證回你什麼」。「API 設計得好不好」，直接決定了系統好不好用、好不好合作、以及（在 AI 時代）AI 能不能正確使用它。

HCI：以人為本的介面#

長久以來，介面設計的主流範式是 HCI（Human-Computer Interaction，人機互動）——研究如何讓「人」更友善地與電腦互動。

HCI 的關注點包括：按鈕要不要大、顏色對比夠不夠、操作步驟是不是直覺、有沒有清楚的錯誤提示。它服務的「使用者」是人類——有情感、有視覺偏好、會疲勞、會誤操作的人類。

ACI：以 Agent 為本的介面#

當 AI Agent 開始呼叫 API 時，出現了一個新問題：API 的「使用者」不再只是人，還包含 AI 模型。 這催生了 ACI（Agent-Computer Interface，Agent 電腦介面）——一個旨在讓工具與介面對 AI Agent 友善的新範式。

ACI 是 HCI 的類比延伸：如果 HCI 研究「人如何與電腦互動」，ACI 研究「AI Agent 如何與電腦互動」。它的核心洞察是：

介面設計的對象不同，設計原則也應該不同。 對人類友善的介面，不見得對 AI 友善；反之亦然。

同一個介面，人類和 Agent 的「用法」與「痛點」截然不同：

面向	HCI（對人）	ACI（對 Agent）
理解方式	靠視覺、直覺、點擊	靠文字描述、工具描述（tool definition）
錯誤處理	給親切的提示訊息	給結構化、可程式處理的錯誤
輸入	表單、點擊、語音	結構化參數、JSON、Schema
發現能力	看選單就能瀏覽	需要清楚地「描述」自己做什麼
容錯	容忍人類的誤操作	需要「防呆」讓錯誤根本無法發生

ACI 的設計原則#

根據這些差異，ACI 有以下幾條核心設計原則：

1. 命名與參數要直觀#

工具名稱、參數名稱應該清楚表明用途和參數含義。模糊的名稱會被模型誤用，進而放大成系統性錯誤——因為模型與工具之間唯一的溝通通道就是介面本身。

好的命名範例：get_weather(city, unit) 清楚易懂。糟糕的命名範例：fn1(a, b, x) 讓模型完全無法判斷用途與參數含義。

模糊的介面會被模型放大成系統性的錯誤。

2. 參數要有例子與說明#

為每個工具與參數提供描述、型別與例子。模型看到「參數 city 是字串，例：北京」，比只看到「city: string」更不容易用錯。

3. 邊界要有說明#

清楚說明工具能接受什麼、不能接受什麼。例如「此工具只接受 0-99 的整數」「此工具無法處理超過 10MB 的檔案」。把邊界講清楚，模型才不會超出範圍亂試。

4. 用設計消除錯誤（防呆，Poka-yoke）#

最好的介面，是讓錯誤根本無法發生。這在製造業有個專有名詞叫防呆（Poka-yoke），源自豐田生產體系：

SIM 卡的缺角讓卡片只能從一個方向插入，避免插反
微波爐門沒關好就不加熱，避免危險

應用到 ACI：如果一個參數只有三種合法值，就應該用列舉（enum）而非自由字串，讓模型無法傳入非法值；如果用例強制要求某欄位，就應該設為必填（required）而非可選。

一個對比實例#

假設要設計「查天氣」的功能。

粗糙的 API（不好用，HCI 思維不足也不適合 Agent）：

POST /weather
body: { "city": "...", "unit": "..." , "date": "..." }

缺點：參數無說明、無例子、無邊界，「unit」可能被傳成 "Celsius"、"c"、"°C" 等多種寫法。

好的 ACI 設計（對 Agent 友善）：

工具：get_weather
描述：查詢指定城市的當日天氣。
參數：
  city (string, 必填)：城市名稱，例："北京"
  unit (enum, 預設 Celsius)：溫度單位，取值僅限 Celsius / Fahrenheit
  date (string, 可選)：查詢日期，格式 YYYY-MM-DD，預設今天
例子：get_weather(city="北京", unit="Celsius")

優點：命名清楚、有描述、有例子、unit 用 enum 防呆、date 有格式說明。

API 設計的通用良好實踐#

除了 ACI 原則，API 設計還有一些長久以來的良好實踐（本書推薦作為底線）：

RESTful 資源導向：用資源（名詞）+ HTTP 方法（動作）表達，如 GET /orders、POST /orders/{id}/cancel
版本化：/v1/orders 讓介面可以演進而不破壞舊使用者
明確錯誤碼：回傳結構化的錯誤（如 { "code": "EMPTY_CART", "message": "..." }），而不是只有 500
文件即契約：用 OpenAPI/Swagger 描述 API（2.6 節的 Spec 精神）
冪等性（Idempotency）：同一請求重複執行結果一致，這對 AI/分散式重試尤其重要（見第 4 章）

本章小結#

HCI 研究人如何與電腦互動；ACI 研究 Agent 如何與電腦互動
ACI 的核心洞見：對人友善的介面，不見得對 Agent 友善
ACI 設計原則：命名直觀、參數有例子、邊界清楚、用設計防呆
防呆（Poka-yoke）讓錯誤根本無法發生（enum、必填等）
API 良好實踐：RESTful、版本化、明確錯誤碼、Spec 即契約、冪等性

想一想#

找出你使用過的一個 API 或函式庫，評估它的「對 Agent 友善程度」（命名、例子、邊界）。
為什麼「模糊的介面會被模型放大成系統性錯誤」？想想模型只靠介面描述在做決策這件事。
為「訂位系統」的「建立訂位」設計一份符合 ACI 原則的工具定義，包含命名、參數、例子與防呆。