【2026 最新】ACLIF 教學：把 MCP 工具海編成一條可審計 Agent CLI

如果你的 Agent 同時要碰 Salesforce、ServiceNow、DocuSign 與 Google Workspace，最直覺的做法是把每個動作都註冊成工具；工具一多，模型就要在名稱、schema 與權限之間做更多判斷。這篇 ACLIF 教學換一個角度：先把外部服務編成同一套 CLI 文法，模型只呼叫一個入口，再由 Agent 外面的 gateway 補上身份、憑證、授權與稽核。

先說界線：ACLIF 不是「MCP 終結者」，也不是裝好就安全的權限系統。它是 2026 年 9 月才公開、仍快速變動的 Agent CLI framework。本文固定在 @aclif/core 1.3.1、GitHub commit cd1f700…、Node 24.15.0；主要展示無憑證 introspection、唯讀 fixture 與 local dry-run，另跑完整 upstream test suite 記錄基線。沒有對真實 SaaS 發出請求，provider 行為以 fixture／local failure path 驗證。我們不放 production secret，也不把作者的效能主張冒充成獨立結果。

你會完成三件事：看懂「一個工具」真正代表什麼、跑通兩個唯讀 mock provider、設計一套能比較 many-MCP-tools 與 single-ACLIF-tool 的 A/B。最後還會拆開 1.3.1 的安全缺口，判斷何時應該直接用 API、一般 CLI、MCP，或 ACLIF。

先說結論：ACLIF 壓縮的是工具介面，不是責任

先記住全文的錨點：

可控 Agent 工具層 ＝ 固定文法 ＋ 按需說明 ＋ Agent 外、由你實作的政策閘門。

一個入口只減少選單；它不會自動完成 production-grade 的身份、授權、重試與稽核

ACLIF 的 provider command 大致遵循 <provider> [<topic> …] <command> [args] [flags]；version、discover、learn 等 core command 是例外。Agent 再透過 --schema、--examples 與 --shape 按需取得說明。這和MCP Tool Search／Lazy Loading解的是同一類問題：不要在每一輪都塞入所有工具細節。

差別是介面形狀。ACLIF 把選擇移進一套 CLI grammar；MCP 則是一個工具發現與呼叫協定，現代 host 也能動態載入、過濾或採用 Code Mode。兩者甚至可以疊在一起：MCP 只暴露一個受限的 gateway_execute，後面再交給 ACLIF。真正該比較的不是口號，而是你的 host、任務集與信任邊界。

ACLIF 教學 Step 0：固定版本，建立零憑證實驗室

截至 2026 年 9 月 18 日，npm 的 latest 是 1.3.1，而不是較早文件快照裡的 1.2.0；package 要求 Node 22 以上。不要先裝到 production runner，也不要沿用本機既有 credential。建立一個空目錄，鎖死版本：

mkdir aclif-readonly-lab
cd aclif-readonly-lab
npm init -y
npm install @aclif/core@1.3.1

npx aclif version --json
npx aclif discover --json

我們的乾淨環境回報 framework 1.3.1、contract 1.0.0，並發現 5 個 provider、56 個 provider command；這是該版本在該日的 inventory，不代表每個 SaaS 的完整 API。內建 command 是經挑選的 surface，另外可用 manifest 或自訂 provider 擴充。

若你只是閱讀與驗證，不必先登入任何 SaaS。以下 introspection 會從本地定義取得資料：

npx aclif learn salesforce --json
npx aclif salesforce data query --schema
npx aclif salesforce data query --examples
npx aclif salesforce data query --shape

npx aclif salesforce data query \
  --query "SELECT Id, Name FROM Account LIMIT 3" \
  --dry-run

--schema 告訴你有哪些參數；--examples 給可解析的例子；--shape 說明輸出輪廓；--dry-run 則只產生 local preview。它沒有去 Salesforce 驗證 SOQL，也不能證明遠端權限或 schema 還有效。拿掉 --dry-run 後，我們的零憑證查詢以 NO_CREDENTIALS 與 exit code 3 停止，沒有發出 SaaS 操作。

ACLIF 還有 --estimate，但 1.3.1 的實作只是按欄位數乘固定常數再加 envelope overhead，並非模型 tokenizer 或 API usage。把它當粗略提示可以；不要把它寫進「節省多少 token」的實驗結果。

Step 1：用兩個唯讀 mock SaaS 驗證共同文法

真正的 beginner build 不該從 production credential 開始。clone 官方 Repo、固定 commit，讓內建 MSW fixture 扮演 Salesforce 與 ServiceNow；這能驗證 command 解析、查詢結果、pagination 與欄位裁切，卻不會碰真實帳號。

git clone https://github.com/agent-cli-framework/aclif.git
cd aclif
git checkout cd1f70053ece9de8e1a6f2981e1af5fcb15d3c45
npm ci
npm run build

npx vitest run \
  test/providers/native/salesforce/salesforce.test.ts \
  test/providers/native/servicenow/servicenow.test.ts \
  -t 'READ' --reporter=verbose

我們在 macOS arm64、Node 24.15.0 得到 2 個 test file 通過、6 個 READ case 通過；涵蓋兩邊的正常 query、next command 與 --fields／--truncate。這只證明固定 fixture 下的唯讀 adapter 行為，不等於 live SaaS 穩定、token 更省或 production 已安全。

完整 npm test 在同一環境不是全綠，失敗集中在 session／tenant cache 期待值；因此本文不宣稱整套測試通過。正確做法是把「通過哪些 case」和「沒驗證什麼」一起寫進實驗紀錄，而不是只留下綠色截圖。

Step 2：把 canonical noun／verb 放在你自己的薄層

ACLIF 想讓不同 provider 共享概念，例如把 canonical customer 映射到 Salesforce Account 與 ServiceNow core_company。但 1.3.1 的 --canonical 並非所有 command 都支援；目前只出現在少數 Salesforce／ServiceNow describe 或 query 路徑。不要假設任何 provider、任何動作都能自動跨 SaaS 翻譯。

比較穩健的做法，是先在自己的 compiled workflow 固定 noun／verb，再把 provider 差異留在 adapter：

type CanonicalRequest = {
  noun: "account" | "ticket";
  verb: "find" | "list";
  fields: string[];
  limit: number;
};

// workflow 只允許唯讀 verb；adapter 再翻成 provider command
const allow = request.verb === "find" || request.verb === "list";
if (!allow) throw new Error("read-only lab");

這個型別才是你的穩定合約。ACLIF 的 schema、examples 與 shape 可以幫你生成或檢查 adapter，但不能取代業務語義。若流程已經固定，還可把它接進確定性核心、機率性邊緣：模型負責理解需求，普通程式負責批准並執行已知 command。

ACLIF 教學 Step 3：credential 留在 gateway，授權自己補

「一個 CLI」不等於「Agent 不會看到 secret」。standalone 模式仍可從 flag、環境變數或 profile 取得 credential。若要讓模型看不到 secret，典型做法是受控 host／gateway 或等價 credential broker；它必須禁止 Agent 讀取 secret，並由 server-side resolver 取 token。HN 討論裡，作者也明說 authorization 由 ACLIF 之外的系統處理。

先用這個 fail-closed 順序設計 gateway：

1. 先驗證 caller：從已驗證 session／JWT 建立 tenantId、userId 與 scopes，不相信 request 自報身份。
2. 再解析 credential：只向 vault 取該 tenant／user 可用的 token。1.3.1 的 embedded resolver 若沒有回傳 credential，仍可能退回 argv flag 與 process.env；host 必須拒絕 provider auth flags、清掉 ambient provider credential，並在 resolver miss 時自行 fail closed。
3. 按實際 command＋參數授權：read、write、delete 分開 allowlist；不要只相信 framework 的靜態 metadata。
4. 隔離連線：pool key 必須包含 tenant／acting identity；高敏感 provider 可先採每租戶獨立 process，直到你驗證共用 pool。
5. 自己留下 receipt：記錄 request ID、caller、provider、command、target、政策結果、duration、envelope success 與結果 digest；secret 不進 log。

特別注意 embedded mode：1.3.1 有些 provider error 會寫入 envelope.success=false，但外層 RunResult.success／exit code 仍可能呈現成功。HTTP status、重試與稽核判定都要先看 envelope，不能只看 process-level exit。

Step 4：1.3.1 的 safety metadata 不能單獨當政策

1.3.1 的部分 multi-operation command 使用 command-level 靜態 metadata；因此本文只把 metadata 當提示，不把它單獨當授權依據。production 應依 command 與 parsed args 重新分類，並預設拒絕 mutation。

這也說明 --confirm、--dry-run 與 metadata 都不是 authorization。把它們當成 policy input 可以；真正的批准仍要綁定已驗證 caller、target resource、實際 operation、當次 request ID 與不可由 caller 自行偽造的 approval。

唯讀 allowlist 還要有 command-level 例外：1.3.1 的 servicenow introspect 雖標為 read，普通執行路徑含遠端 write probe；read-only lab 應直接拒絕。若只要掃描 schema，在讀過該版本 source 後，限隔離測試帳號使用 servicenow introspect --bootstrap，並以 provider 端 audit 確認沒有資料寫入。

本文沒有驗證 1.3.1 的共享多租戶連線隔離，因此目前只建議在單租戶或每租戶隔離的測試環境評估，不直接作為共享 production gateway。

Step 5：正確做 many-MCP-tools vs single-ACLIF-tool A/B

ACLIF 官方提供自家 workflow 的 token 比較，但那不是獨立的 MCP 對照。Cloudflare Code Mode 與 Anthropic 的 MCP code execution案例能支持「按需載入比一次塞滿 schema 省 context」，也不能替 ACLIF 宣布勝利。要回答你的系統是否更省、更準，必須在相同模型與任務上自己跑。

剛才 6 個 READ case 是 adapter assertion，不是可以直接丟給 Agent 的 task prompt。先把每個 case 的行為轉寫成盲測用自然語言任務，另存預期 fixture 結果；再凍結以下條件：

• 相同模型與設定：model snapshot、temperature、system prompt、max turns、timeout 完全一致。
• A 組：每個 read command 是一個 typed MCP tool；若 host 會 Tool Search 或延遲載入，就保留，不准故意使用最差版本。
• B 組：只提供一個 ACLIF-specific structured gateway tool，欄位固定為 provider、topic、command 與 args；允許 discover、learn 與 introspection，但不暴露通用 shell。
• 凍結能力面：hash A 組的完整 tool inventory 與 B 組可達 command；兩邊使用 capability-equivalent adapter、相同 mock dataset，避免把工具數量與後端能力混成同一個變因。
• 共同政策：credential resolver 與逐 command 唯讀 allowlist 相同，已知含 write probe 的 introspection 路徑明確拒絕；不能只按 aciMetadata.mutability 篩選。
• 預先登記評分：在看結果前固定 exact-match／validator scorer、排除規則與主要指標；任務撰寫者不替單一介面量身訂題。
• 隨機化與規模：隨機化 arm 順序與 seed，保存完整 trace 與 fixture hash。每題三次只能找出 wiring 問題，不能做統計勝負；要比較效果量，先做 power analysis 再決定 run 數。

每題記錄模型 API／host usage metadata 回報的 input／output tokens、選錯工具或 command 的次數、參數錯誤、重試、time-to-first-valid-action、總延遲與最後是否完成。token 要包含最初工具定義、後續 introspection、錯誤與 history；只量初始 schema 會偏袒某一邊。更多實驗拆法可接著看MCP vs CLI Token A/B 教學。

Step 6：注入四種故障，確認不是把複雜度藏起來

① Provider timeout：不要自動重送未知結果的 write

先在 test harness／gateway 明確設定 deadline，再讓 mock 延遲超過它；不要假設 ACLIF provider 已內建統一 timeout。read 可以依明確政策重試；write 若不知道遠端是否已提交，就先標成 unknown_outcome，查詢狀態或由人處理。ACLIF 的 idempotent 是 metadata，不是 transaction、idempotency key 或 exactly-once 保證。

② Schema drift：讓 fixture 故意少一個欄位

移除一個必用欄位或改 enum，確認 adapter 會 fail closed，並把 drift 指向 provider／command／field。local --schema 可能是 built-in 定義，不等於 instance 的最新真相；需要 instance introspection 時才使用隔離的測試 credential。ServiceNow 1.3.1 的 read-only lab 僅允許檢查過 source 的 introspect --bootstrap 路徑，普通 introspect 要拒絕。

③ 重複寫入：用 business key，而不是相信 retry

讓 mock 先記錄 side effect 已提交，但故意不在 deadline 前回應，再觀察 orchestrator 是否重送。預期結果應是 gateway 以 idempotency／business key 查重，或把任務轉人工；若直接送第二次，就算 CLI grammar 完全一致，系統仍不安全。

④ 取消：區分「本機停了」與「遠端已取消」

1.3.1 宣告了 abort signal 介面，但 provider request 未普遍接上它。Ctrl-C 只會結束 CLI process；關閉 caller 的 HTTP connection 若未由 host 傳遞取消，甚至不會停止 gateway 內的工作。兩者都不能證明 SaaS 已取消。audit 要留下 cancellation requested、upstream state unknown 與後續 reconcile 結果。

Direct API、一般 CLI、MCP、ACLIF 怎麼選？

選 Direct API：型別、deadline 與 provider 原生能力最重要

單一 provider、高流量、需要 streaming、原生 idempotency、細緻 retry 或完整 SDK 型別時，direct API 通常最直接。代價是每一家都要自己整合與正規化。

選一般 CLI：工作已經穩定，而且人與 CI 都要操作

既有官方 CLI 已成熟、命令少、shell trace 容易重現時，不必為了「Agent-ready」再加一層 framework。要處理環境繼承、quoting、filesystem 與 process signal。

選 MCP：需要標準協定與 host 生態

工具要被多個 MCP client 發現、host 已有 OAuth／approval／Tool Search，或希望避免 shell argv 時，MCP 更自然。工具多不代表一定把全部 schema 放進每輪；先確認 client 的實際載入策略。

選 ACLIF：多 provider 需要共同 grammar 與自我描述 CLI

你願意維護 adapter、希望同一套 command 能被 Agent subprocess、host app 與 gateway 重用，而且會自行實作 authn／authz／audit 時，ACLIF 才有明顯價值。可以先從AI Agent Harness 原理和最小 Harness 實作補齊 host 層，再評估是否導入。

ACLIF 教學 FAQ

ACLIF 是 MCP 的替代品嗎？

不是一對一替代。ACLIF 是 CLI framework 與 provider adapter；MCP 是工具協定。你可以只用其中之一，也能用一個 MCP gateway tool 呼叫 ACLIF。

只有一個 ACLIF tool 就一定比較省 token 嗎？

不一定。它能減少初始工具定義，但 discover、schema、錯誤重試與 history 也會花 token；相對組的 MCP host 若支援 lazy loading，差距可能縮小。以完整 episode usage 為準。

可以直接把 production credential 放進 ACLIF profile 嗎？

不建議讓 Agent 可讀的 process 使用 production secret。教學先用 fixture；上線時由獨立 gateway 驗證 caller，再從 vault 解析最小權限 credential。

–dry-run 代表遠端一定不會變更嗎？

只能信你已檢查過的 command 實作。本文的 query／DML preview 是 local path；不要把 base flag 的存在當成每個 mutation 都正確處理 dry-run。尤其不要用真帳號測第一次。

safety metadata 可以拿來自動批准嗎？

不能單靠 metadata。它可作為政策輸入，但自動批准前仍須逐 command 驗證其參數、caller、target 與實際操作。

ACLIF 會自動完成 audit、rate limit 與取消嗎？

embedded gateway 不會替你完成整套控制。standalone 的一般非豁免 command 會輸出簡短 audit line，也有粗略的敏感 key masking；durable log、correlation、rate-limit enforcement、policy-driven field redaction 與上游取消仍是 host 的責任。

每個 provider 都要重寫 CLI 嗎？

未涵蓋的 surface 仍要做 adapter 或 manifest。共同 contract 能降低使用端差異，不會消除 provider API 的語義、版本與維護成本。

新手最安全的下一步是什麼？

停在唯讀 lab，先產出一份自己的 trace。固定 1.3.1，跑 discover、schema、examples、shape、兩個 provider fixture，再把所有 mutation 在 gateway 預設拒絕；沒有這條基線，不要接 production。

新手重點：先證明邊界，再追求少一點 token

• ACLIF 的價值是固定 grammar、自我描述與 progressive disclosure，不是自動安全。
• 先用兩個唯讀 mock provider 建立可重現 trace；不要拿 dry-run 當 live-provider 驗證。
• credential、身份驗證、授權、連線隔離與 durable audit 都要留在 Agent 外。
• 1.3.1 的靜態 metadata 不足以單獨承擔授權；mutation 必須由外層預設拒絕並依實際參數分類。
• A/B 要量完整 episode，而且公平保留 MCP host 的 lazy-loading 能力；沒有 API usage 就不要報 token 勝負。