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 报告“找不到命令”，说明运行时无法在 $PATH 中找到二进制所在目录。在验证成功之前，请勿继续执行技能命令。
一个用于 Afi 的开源 CLI 和 MCP 服务器，其供应商明确不鼓励 API 轮询。此 CLI 会将整个层级结构一次性同步到本地 SQLite 数据库中（fleet-sync），然后离线回答全局性问题（覆盖缺口、全局健康状态、备份陈旧性、许可证对账）。一个带有保护机制的离职命令会执行供应商自己的归档-然后-释放序列，并带有门户网站所缺少的验证门。
何时使用此 CLI
对于任何关于 Afi SaaS 备份集群的程序化查询，请使用此 CLI：备份覆盖率、夜间任务健康状态、配额违规、归档陈旧性、许可证对账以及为离职员工执行的安全归档与离职流程。对于跨多个租户的 MSP 规模问题，它是正确的选择，因为门户网站强制逐个租户操作，而速率受限的 API 会惩罚轮询——一次性同步，然后查询本地存储。
反触发词
请勿将此 CLI 用于：
- 执行恢复、导出或浏览实际的备份数据——Afi 公开 API 不暴露恢复/导出启动或数据下载功能；请使用 Afi 网页门户
- 创建或编辑备份策略——公开 API 中策略为只读；请在门户中配置
- 实时监控或持续轮询任务状态——Afi 明确会限制并可能暂停轮询应用程序；请改用计划同步
- 管理 Afi 门户用户账户、SSO 或通知设置——不在公开 API 范围内
独特能力
以下能力是此 API 的任何其他工具都不具备的。
可累积的本地状态
-
fleet-sync——以一次对 Afi 的尊重性遍历，将整个 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 "employee departure"
命令参考
applications — 管理应用程序
afi-cli applications— 列出由认证密钥标识的应用程序的安装信息。
orgs — 管理组织
afi-cli orgs create— 创建一个新的子组织。afi-cli orgs get— 通过 ID 检索组织。
tenants — 管理租户
afi-cli tenants <id>— 通过 ID 检索租户。
查找正确的命令
当您知道想要做什么但不知道是哪个命令时，可以直接询问 CLI：
afi-cli which "<用您自己的话描述的能力>"
which 将自然语言的能力查询解析为此 CLI 精心策划的功能索引中最佳匹配的命令。退出码 0 表示至少有一个匹配；退出码 2 表示没有确信的匹配——请回退到 --help 或使用更窄的查询。
配方
周一集群检查
afi-cli fleet-sync --skip-archives && afi-cli fleet-health --failed-only --agent
刷新集群存储（跳过繁重的归档遍历），然后仅列出有失败任务或配额违规的租户。
查找单个租户中的备份盲点
afi-cli coverage-gaps --tenant 01F000000000000411Z1101G1Y --agent --select items.name,items.kind,items.external_id
资源表与保护表的 LEFT JOIN，缩小到代理打开工单所需的三个字段。
安全地处理离职员工
afi-cli resolve [email protected] && afi-cli offboard 01F0RESOURCE0000000000000A --tenant 01F0TENANT00000000000000B --policy 01F0POLICY000000000000000C --reason "employee departure" --dry-run
将模糊的邮箱解析为规范的 Afi 资源，然后预览安全的最终备份-验证-释放序列，最后再实际执行。
捕获静默失败的备份
afi-cli backup-stale --max-age 48h --json
最新归档早于两天的受保护资源——任何门户屏幕都无法显示的故障类别。
许可证漂移检查
afi-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。
-
可管道输出 — JSON 到标准输出，错误信息到标准错误
-
可过滤 —
--select保留字段子集。点符号路径可深入嵌套结构；数组会自动按元素遍历。对于需要保持上下文精简的冗长 API 至关重要：afi-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": <data>
}
解析 .results 以获取数据，解析 .meta.source 以了解数据是来自线上还是本地。只有在标准输出是终端且未设置任何机器可读格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要打印到标准错误——管道/代理消费者和显式格式运行只会得到纯净的 JSON 到标准输出。
代理反馈
当您（或代理）注意到此 CLI 有什么问题时，请记录它：
afi-cli feedback "--since 标志是包含性的，但文档说它是排他性的"
afi-cli feedback --stdin < notes.txt
afi-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 | 默认；仅写入标准输出 |
file:<path> | 自动将输出写入 <path>（临时文件 + 重命名） |
webhook:<url> | 将输出体 POST 到该 URL（application/json 或当 --compact 时为 application/x-ndjson） |
未知的方案将被拒绝，并返回一个包含所支持集合的结构化错误。Webhook 失败会返回非零退出码，并在标准错误上记录 URL 和 HTTP 状态。
命名配置文件
配置文件是一组保存的标志值，可在多次调用中重用。当计划性代理每次运行时都以相同的配置调用相同的命令时，请使用它。
afi-cli profile save briefing --json
afi-cli --profile briefing orgs get <org-id>
afi-cli profile list --json
afi-cli profile show briefing
afi-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标志执行：afi-cli <command> [subcommand] [args] --agent - 如果不明确，深入查看子命令帮助：
afi-cli <command> --help。