Afi - Claude Code 技能
先決條件：安裝 CLI
此技能驅動 afi-cli 二進位檔。在執行任何此技能的命令之前，你必須確認 CLI 已安裝。 如果缺少，請先安裝：
- macOS / Linux：
bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/afi/install.sh) - Windows (PowerShell)：
iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/afi/install.ps1 | iex - 驗證：
afi-cli --version - 確保
~/.local/bin(macOS / Linux) 或%LOCALAPPDATA%\Programs\msp-skills(Windows) 在$PATH中。
安裝程式會將 afi-cli 與 afi-mcp 二進位檔下載至 ~/.local/bin (macOS / Linux) 或 %LOCALAPPDATA%\Programs\msp-skills (Windows)。它不會向你的代理註冊此技能，也不會寫入任何 MCP 客戶端設定——關於此連線設定請參閱 mcp-install.md。
如果安裝後 --version 回報「command not found」，表示執行時期無法在 $PATH 中找到二進位檔目錄。在驗證成功之前，請勿繼續執行技能命令。
用於 Afi 的開源 CLI 與 MCP 伺服器，該供應商明確不鼓勵輪詢 API。此 CLI 會在一次執行中將整個階層結構擷取至本機 SQLite（fleet-sync），然後離線回答全網問題（覆蓋缺口、全網健康狀態、備份過時、授權核對）。一個受保護的 offboard 命令會執行供應商自己的歸檔-然後-釋放序列，並含有人口網站缺乏的驗證關卡。
何時使用此 CLI
對於任何關於 Afi SaaS 備份網域的程式化問題，請使用此 CLI：備份覆蓋率、夜間任務健康狀態、配額違規、封存過時、授權核對，以及針對離職員工的受保護歸檔與撤銷序列。對於跨許多租戶的 MSP 規模問題，它是正確的選擇——入口網站強制逐租戶瀏覽，而限速的 API 則懲罰輪詢——同步一次，然後查詢本機儲存體。
反觸發
請勿將此 CLI 用於：
- 執行還原、匯出或瀏覽實際備份資料——Afi 公開 API 未公開還原/匯出啟動或資料下載功能；請使用 Afi 網頁入口網站
- 建立或編輯備份原則——原則在公開 API 中為唯讀；請在入口網站中設定
- 即時監控或持續輪詢任務狀態——Afi 明確會進行節流，並可能暫停輪詢應用程式；請改用排程同步
- 管理 Afi 入口網站使用者帳戶、SSO 或通知設定——不屬於公開 API 範圍
獨特功能
這些功能在此 API 的其他工具中均無法使用。
可累積的本機狀態
-
fleet-sync—— 在一次尊重性的傳遞中，遍歷整個 Afi 階層結構——安裝、組織、租戶，然後每個租戶的資源、保護、原則、封存、配額與任務統計——至本機 SQLite。請先執行此命令（並排程執行）：之後的每個網域問題——覆蓋率、過時、授權、評分卡——皆可離線回答，不會觸發 Afi 的速率限制。
afi-cli fleet-sync -
coverage-gaps—— 找出租戶中未套用備份保護的資源——備份盲點。當被問及每個信箱、網站或磁碟機是否實際受到備份時使用此命令——它能回答 API 無法提供的網域覆蓋問題。
afi-cli coverage-gaps --tenant 01F000000000000411Z1101G1Y --agent -
fleet-health—— 所有已同步租戶的單一表格：任務成功/失敗計數、失敗任務清單與配額違規。使用此命令進行週一早晨的「整個網域是否綠燈」檢查，而不必逐個入口網站分頁瀏覽租戶。
afi-cli fleet-health --since 24h --agent -
resolve—— 將 Microsoft 365 / Google Workspace ID、電子郵件或名稱對應到規範的 Afi 資源或租戶，包括 Multi-Geo 分叉。在任何撤銷或稽核之前執行此命令，以確認哪個 Afi 物件對應到外部系統的身分。
afi-cli resolve [email protected] --agent -
reconcile-licenses—— 比較每個租戶的已購買訂閱數量與實際受保護的資源計數，以標記超額與不足配置。使用此命令進行每週授權漂移檢查——目前需要手動在兩個入口網站畫面之間拼接試算表。
afi-cli reconcile-licenses --org 01F0ORG0000000000000000000 --json -
backup-stale—— 標記其最新備份封存年齡超過閾值的受保護資源——已保護但靜默失敗的資源。使用此命令來捕捉靜默失敗類別：已套用原則但其備份已悄悄停止送達的資源。
afi-cli backup-stale --max-age 48h --agent -
tenant-scorecard—— 單一租戶的完整備份狀態：覆蓋百分比、最後任務狀態、最新/最舊封存年齡與配額狀態。在準備客戶工單或 QBR 時產生此卡片——補足 fleet-health 的逐租戶深入分析。
afi-cli tenant-scorecard 01F000000000000411Z1101G1Y --agent --select tenant_id,coverage_pct,quotas_exceeded
受保護的工作流程
-
offboard—— 安全地備份離職員工的資源、驗證封存已送達，然後釋放保護——在備份確認前拒絕執行不可逆的步驟。在離職員工撤銷時使用此命令，以便在 M365/GWS 席位釋放前驗證最終備份——絕不遺失離職者的資料。
afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "員工離職"
命令參考
applications —— 管理應用程式
afi-cli applications—— 列出由驗證金鑰識別之應用程式的安裝。
orgs —— 管理組織
afi-cli orgs create—— 建立一個新的子組織。afi-cli orgs get—— 根據 ID 擷取組織。
tenants —— 管理租戶
afi-cli tenants <id>—— 根據 ID 擷取租戶。
尋找正確的命令
當你知道想做什麼，但不確定哪個命令時，直接詢問 CLI：
aki-cli which "<以你自己的話描述的能力>"
which 會將自然語言能力查詢解析為此 CLI 精選功能索引中最匹配的命令。退出碼 0 表示至少有一個匹配；退出碼 2 表示沒有自信的匹配——請退回使用 --help 或使用更精確的查詢。
配方
週一網域掃描
aki-cli fleet-sync --skip-archives && afi-cli fleet-health --failed-only --agent
重新整理網域儲存體（跳過大型的封存瀏覽），然後僅列出有失敗任務或配額違規的租戶。
找出單一租戶中的備份盲點
aki-cli coverage-gaps --tenant 01F000000000000411Z1101G1Y --agent --select items.name,items.kind,items.external_id
資源表與保護表的 LEFT JOIN，縮小至代理開啟工單所需的三個欄位。
安全地撤銷離職員工
aki-cli resolve [email protected] && afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "員工離職" --dry-run
將模糊的電子郵件解析為規範的 Afi 資源，然後在實際執行前預覽受保護的最終備份-驗證-釋放序列。
捕捉靜默失敗的備份
aki-cli backup-stale --max-age 48h --json
最新封存年齡超過兩天的受保護資源——這是沒有任何入口網站畫面能呈現的失敗類別。
授權漂移檢查
aki-cli reconcile-licenses --org 01F0ORG0000000000000000000 --json
依租戶比較已購買訂閱數量與實際受保護的資源計數。
驗證設定
在 Afi 入口網站中建立應用程式與 API 金鑰（組織層級：設定 → 應用程式；租戶層級：服務 → 設定 → 應用程式），然後設定 AFI_API_KEY。金鑰會以原始 Authorization 標頭值傳送（Afi 金鑰看起來像 appkey-...；無 Bearer 前綴）。每個應用程式支援兩個金鑰以利輪換。金鑰繼承應用程式的安裝範圍——如果結果中缺少某個租戶或組織，請檢查應用程式的安裝位置。
執行 afi-cli doctor 來驗證設定。
代理模式
在任何命令中加上 --agent。展開為：--json --compact --no-input --no-color --yes。
-
可管線化 —— stdout 輸出 JSON，錯誤輸出至 stderr
-
可過濾 ——
--select保留部分欄位。點分隔路徑可深入巢狀結構；陣列則逐元素遍歷。對於在詳細 API 上保持上下文精簡至關重要：aki-cli orgs get <org-id> --agent --select id,name,status -
可預覽 ——
--dry-run顯示請求而不發送 -
離線友善 —— 同步/搜尋命令可在可用時使用本機 SQLite 儲存體
-
非互動式 —— 永不提示，每個輸入皆為旗標
-
明確重試 —— 僅在已存在的建立應視為成功時使用
--idempotent，僅在缺少的刪除目標應視為成功時使用--ignore-missing
回應信封
從本機儲存體或 API 讀取的命令會將輸出包裝在來源信封中：
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <資料>
}
解析 .results 取得資料，解析 .meta.source 以了解資料是即時還是本機。僅當 stdout 是終端機且未設定任何機器格式旗標（--json、--csv、--compact、--quiet、--plain、--select）時，人類可讀的 N results (live) 摘要才會輸出到 stderr——管線/代理消費者以及明確格式執行會將純 JSON 輸出到 stdout。
代理回饋
當你（或代理）發現此 CLI 有什麼不對勁時，請記錄下來：
aki-cli feedback "--since 旗標是包含性的，但文件說是不包含性的"
aki-cli feedback --stdin < notes.txt
aki-cli feedback list --json --limit 10
條目會儲存在本機 ~/.local/share/afi-cli/feedback.jsonl。除非設定了 AFI_FEEDBACK_ENDPOINT 且傳遞了 --send 或設定了 AFI_FEEDBACK_AUTO_SEND=true，否則絕不會 POST 出去。預設行為僅為本機儲存。
寫下讓你感到意外的部分，而非錯誤回報。簡短、具體、一行：那就是會累積的部分。
輸出傳遞
每個命令都接受 --deliver <sink>。輸出會（除了 stdout 之外或代替 stdout）傳送到指定的接收器，以便代理無需手動管線即可路由命令結果。支援三種接收器：
| 接收器 | 效果 |
|---|---|
stdout | 預設；僅寫入 stdout |
file:<path> | 將輸出原子性地寫入 <path>（暫存檔 + 重新命名） |
webhook:<url> | 將輸出主體 POST 到 URL（application/json，或使用 --compact 時為 application/x-ndjson） |
未知的方案會連同支援的集合名稱以結構化錯誤拒絕。Webhook 失敗會回傳非零值，並在 stderr 上記錄 URL 與 HTTP 狀態。
命名設定檔
設定檔是一組儲存的旗標值，可在多次叫用中重複使用。當排程代理每次執行時都以相同組態執行相同命令時，請使用它。
aki-cli profile save briefing --json
aki-cli --profile briefing orgs get <org-id>
aki-cli profile list --json
aki-cli profile show briefing
aki-cli profile delete briefing --yes
明確的旗標總是優先於設定檔值；設定檔值優先於預設值。agent-context 會在 available_profiles 下列出所有可用的設定檔，以便內省的代理在執行時期發現它們。
退出碼
| 碼 | 意義 |
|---|---|
| 0 | 成功 |
| 2 | 使用錯誤（錯誤的引數） |
| 3 | 找不到資源 |
| 4 | 需要驗證 |
| 5 | API 錯誤（上游問題） |
| 7 | 達到速率限制（等待後重試） |
| 10 | 設定錯誤 |
引數解析
解析 $ARGUMENTS：
- 空值、
help或--help→ 顯示afi-cli --help輸出 - 以
install開頭 → 以mcp結尾 → MCP 安裝；否則 → 請參閱上方的先決條件 - 其他任何內容 → 直接使用（以
--agent作為 CLI 命令執行）
MCP 伺服器安裝
- 安裝 MCP 二進位檔（執行先決條件區段中的安裝腳本，或參閱 mcp-install.md 了解每個代理的連線設定）。
- 向 Claude Code 註冊：
claude mcp add afi-mcp -- afi-mcp - 驗證：
claude mcp list
直接使用
- 檢查是否已安裝：
which afi-cli如果找不到，請提供安裝服務（請參閱此技能頂部的先決條件）。 - 將使用者查詢與上方「獨特功能」與「命令參考」中的最佳命令進行比對。
- 使用
--agent旗標執行：aki-cli <command> [subcommand] [args] --agent - 如果有歧義，鑽研子命令的說明：
afi-cli <command> --help。