Fabric AIops

Fabric AIops

免责声明：由社区维护的开源项目。与 Cisco、Meraki、Arista、Ubiquiti 或任何网络控制器供应商均无关联，也未获得其认可或赞助。“Cisco”、“Meraki”、“Catalyst”、“DNA Center”、“Arista”、“CloudVision”、“Ubiquiti”、“UniFi”、“ACI”、“APIC”及所有产品／商标名称均归各自所有者所有。采用 MIT 许可。

面向通过控制器管理的网络 Fabric 的治理型 AI 运维——包括 Cisco Meraki Dashboard API（参考平台，支持完整读取和写入）、 Cisco Catalyst Center（前称 DNA Center；支持部分读取）、Arista CloudVision Portal (CVP)（支持部分读取）和 UniFi Network（可自托管 控制器或 UniFi OS 控制台；支持部分读取和设备重启），以及只读的 Cisco ACI (APIC) 端点路径重建和故障分析——并配备内置治理 框架：统一审计日志、令牌／失控预算防护、 撤销令牌记录和描述性风险等级。从设计上支持多平台：以 platform 为键的注册表将每项规范操作映射到各控制器的 REST API（路径模板 + 响应适配器），因此新增控制器只需添加注册表项，无需新增操作／CLI／MCP 界面。若某个平台不支持某项操作，会返回清晰的说明性错误（“X 尚不支持此操作—— 请提交问题”），绝不会静默地不执行。此工具尚未在任何实时控制器上测试过任何平台；ACI 读取是唯一基于真实控制器响应构建的部分（由生产环境用户提供的匿名化 APIC 负载）——请参阅 docs/VERIFICATION.md。

功能介绍

三项标志性分析，以及围绕这些分析的受控读取和写入操作：

• 上行链路丢包与延迟根因分析 — 获取整个组织中 MX WAN 上行链路的丢包和延迟数据，根据平均丢包率和延迟的综合指标对最差的上行链路排序，并将每条性能下降的上行链路映射到可能的原因和建议操作。每项排名都会附带具体数据，而不是黑盒结论。
• 网络健康评分 — 为每个网络计算 0-100 的综合评分，依据包括设备在线率、上行链路健康率和警报严重程度惩罚项（权重分别为 0.5/0.3/0.2），并返回所有组成部分，确保评分可解释。
• 配置模板偏差 — 对于绑定了配置模板的网络，列出偏离模板的设置（预期值与实际值）。

已实现功能

• CLI（fabric-aiops ...）：init、overview、org、network、device、client、health、aci、remediate、secret、doctor、mcp。
• MCP 服务（fabric-aiops mcp 或 fabric-aiops-mcp）：37 个工具（28 个读取工具、9 个写入工具），每个工具均由随附的 @governed_tool 框架封装。
• 加密凭据：控制器密钥（Meraki API 密钥／Catalyst Center 或 APIC 的 username:password／CVP 服务账户令牌／UniFi API 密钥）存储在加密存储中 ~/.fabric-aiops/secrets.enc（Fernet + scrypt）——绝不以明文形式存储在磁盘上。可通过 FABRIC_AIOPS_MASTER_PASSWORD（MCP/CI）提供主密码解锁，也可在 CLI 中通过交互式提示输入。
• 可逆性：执行更改的写入操作会先获取真实的变更前状态，并记录准确的逆向操作（update_device／update_network_vlan 会恢复先前的值；claim↔remove；bind↔unbind／重新绑定）。不可逆操作（reboot_device、blink_device_leds）会记录先前状态以供审计，但不声明可撤销操作。
• 安全性：每项会更改状态的 CLI 操作都支持 --dry-run，并要求双重确认；每个 MCP 写入工具都提供 dry_run 预览。

能力矩阵（37 个 MCP 工具）

领域	工具	数量	读/写
概览	overview	1	读取
组织	org_list, org_get, org_licensing, org_admins, org_device_statuses, org_api_requests	6	读取
网络	network_list, network_get, network_vlans, network_alerts, network_traffic	5	读取
设备	device_inventory, device_status, device_uplinks, switch_ports, wireless_ssids	5	读取
客户端	client_list, client_get, client_usage, client_connectivity	4	读取
健康状况（旗舰功能）	uplink_loss_and_latency_rca, network_health_score, config_template_drift	3	读取
Cisco ACI（仅限 APIC）	aci_endpoint_trace, aci_epg_segment, aci_faults_list	3	读取
修复	reboot_device, claim_devices_into_network, remove_device_from_network, bind_network_to_template, unbind_network_from_template	5	写入（高）
	update_device, update_network_vlan	2	写入（中）
	blink_device_leds	1	写入（低）
撤销	undo_list	1	读取
	undo_apply	1	写入（中）

network_health_score 和 config_template_drift 仅接受注入数据（用于评估您已持有的数据）；uplink_loss_and_latency_rca 接受注入的 records，用于离线分析，也可以从已配置的目标拉取实时数据。设备型号带有产品类型前缀：MX 设备，MS 交换机，MR 无线 AP，MV 摄像头，MG 蜂窝网关。

平台支持矩阵

一个工具，支持五种控制器平台。对于下表中的四种平台，ops/CLI/MCP 接口处处相同；每个平台都会映射其支持的规范操作，并对其余操作返回教学错误（“<platform> 尚不支持 — 请提交 issue 或 PR”）。ACI 不映射其中任何操作 — 请参阅下文的 Cisco ACI。

规范操作	meraki	catalyst	cvp	unifi
overview（组织/站点/容器汇总）	✅	✅	✅	✅
org_list / org_get	✅	✅ 站点	✅ 容器	✅ 站点（list；get ❌）
org_licensing、org_api_requests	✅	❌	❌	❌
org_admins	✅	❌	✅ 用户	❌
org_device_statuses	✅	✅ 设备运行状况	✅ 清单 + 流式状态	✅ stat/device（状态、运行时间、固件）
network_list / network_get	✅	✅ 站点运行状况 / 站点	✅ 容器	✅ 站点 / stat/health（子系统汇总）
network_vlans、network_traffic	✅	❌	❌	❌
network_alerts	✅	✅ 问题（P1→严重，P2→警告）	✅ 事件	✅ 告警（*_Lost_Contact→严重）
device_inventory、device_status	✅	✅ 网络设备	✅ 清单（+ complianceCode 漂移信号）	✅ stat/device（id = 设备 MAC）
device_uplinks	✅	❌	❌	❌
switch_ports	✅	✅ 接口统计信息（传入设备 uuid）	❌	✅ 设备 port_table（传入设备 MAC）
wireless_ssids	✅	❌	❌	❌
client_list / client_get	✅	✅ 客户端运行状况（聚合） / 客户端详情（按 MAC）	❌	✅ stat/sta（已连接） / stat/user（按 MAC）
client_usage、client_connectivity	✅	❌	❌	❌
uplink_loss_and_latency_rca（实时拉取）	✅	❌（注入的 records 仍可使用）	❌（注入的 records 仍可使用）	❌（注入的 records 仍可使用）
network_health_score、config_template_drift（仅注入）	✅	✅	✅	✅
reboot_device	✅	❌ 教学错误	❌ 教学错误	✅ cmd/devmgr 重启设备
其他 7 项写入操作（闪灯/更新/认领/移除/绑定/解绑/VLAN）	✅	❌ 教学错误	❌ 教学错误	❌ 教学错误

概念映射：规范的 organizations/networks 对应 Catalyst Center 站点、CVP 容器和 UniFi 站点（规范 ID 是站点的简称 — 即 /api/s/{site}/ 路径段）；它们都只有一棵全局树，因此组织范围不会筛选其列表。在 unifi 上，设备范围的调用（device get / switch_ports / reboot）会从目标设备的默认 org_id 填入站点 — 请在 config.yaml（或初始化向导）中设置该值。写入操作仅适用于 Meraki，UniFi 设备重启除外 — Catalyst Center 和 CVP 的变更模型（任务/配置片段工作流）无法与这些规范写入操作顺利对应，因此每项写入操作都会在调用控制器之前快速失败并返回教学错误（绝不会静默无操作）。CVP 配置漂移可通过 device_inventory（每台设备的 complianceCode/complianceIndication）和 network_alerts（事件）查看；catalyst/cvp/unifi 上的配置片段内容检索和深度分页目前已知尚未实现。

Cisco ACI (APIC)

ACI 有两个维度——租户 → VRF → bridge domain → EPG，以及 pod → node → interface——但都不是组织 → 网络 → 设备树。与其让每次调用中的 network_id 各有不同含义，不如让 aci 目标在调用规范工具时返回教学提示错误，并提供三个接受 ACI 引用（MAC/IP、租户/应用/EPG 名称、DN）的 只读 ACI 原生工具：

工具（CLI）	可查询内容
aci_endpoint_trace（aci trace --mac/--ip）	此端点在哪里、由什么承载：接入位置（pod / leaf / interface 或 vPC）→ EPG → bridge domain → VRF → EPG 的合约 → 筛选器条目，以及 DN 中包含该 EPG 或接入 interface 的故障
aci_epg_segment（aci segment TENANT APP EPG）	从 EPG 名称查询相同的 EPG → BD → VRF → 合约链
aci_faults_list（aci faults）	Fabric 故障，按严重性从高到低排列

阅读方式：

• 这是静态重建，不是可达性测试。 staticPathResolved: true 表示 Fabric 已配置为承载该端点，并不代表流量确实能够通过。不会向 APIC 写入任何内容，也不会创建故障排查会话。
• 链接遵循 APIC 解析出的关系（tDn），因此会跟踪指向 common 的跨租户链接；未处于 formed 状态的关系会连同其状态一起列为发现项。
• 相关故障是候选项，按 DN 匹配（EPG、接入 interface、leaf 上已部署的 EPG 策略副本）——表示接近，并非因果关系。
• 故障行是记录，不是事件：delegated 记录会镜像其他对象上的故障。已清除的故障仍保留其触发时的描述。
• 未评估的内容（每个结果都会在 notChecked 中列出）：vzAny 合约、禁用合约、导入的合约接口、首选组对等项、服务图 / L3Out。

leaf/spine 清单和 interface 状态（fabricNode、topSystem、l1PhysIf）不在此版本中——待获得这些类的真实响应后再实现，就像上面的功能一样。

各平台的身份验证

平台	platform:	存储的密钥（加密）	网络上的身份验证方式	基础 URL
Cisco Meraki Dashboard	meraki	API 密钥（Dashboard → Organization → Settings → API access）	Authorization: Bearer（或 auth_style: meraki-key → X-Cisco-Meraki-API-Key）	默认值 https://api.meraki.com/api/v1
Cisco Catalyst Center	catalyst	username:password（一个字符串）	通过 POST /dna/system/api/v1/auth/token（HTTP Basic）换取有效期约 1 小时的 X-Auth-Token，遇到 401 时自动刷新一次	必填，例如 https://<catalyst-center-host>
Arista CloudVision Portal	cvp	服务账户令牌（Settings → Access Control → Service Accounts）	Authorization: Bearer	必填，例如 https://<cvp-host>
Cisco ACI (APIC)	aci	username:password（一个字符串；只读角色即可——所有 ACI 读取操作都是 GET，只有登录是 POST）	POST /api/aaaLogin.json 会开启一个通过 cookie 传递的会话；在会话生命周期过半时通过 /api/aaaRefresh.json 延长；遇到 401/403 时重新登录一次（APIC 会以 403 报告会话过期）	必填，例如 https://<apic-host>
UniFi Network	unifi	API 密钥（UniFi OS：Settings → Control Plane → Integrations；自托管的 Network Server 9.0+）	X-API-KEY（无状态；旧版 cookie 登录已知暂不支持）	必填——经典控制器 https://<host>:8443，或 UniFi OS 控制台 https://<console>/proxy/network（保留此前缀）

fabric-aiops init 会引导用户选择平台并存储相应类型的密钥；fabric-aiops doctor 会通过规范的最高层级读取操作探测每个目标（组织 / 站点 / 容器 / UniFi 站点；对于 APIC，则读取租户数量），以验证完整的身份验证流程。

这个工具会做什么，不会决定什么

它能准确、高效地执行网络结构的操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入操作。这由 Agent 自行判断，或由你连接的账户权限决定：如果你提供的 Meraki API 密钥对应的管理员只有组织的只读访问权限（或控制器上的等效只读权限），那么写入操作会在控制器处失败——真正掌握权限的地方就在这里。

因此，你无需配置只读开关、策略文件或审批关卡。这个工具唯一保证的是，不会有任何操作悄无声息地发生：每次调用，无论通过 MCP 还是 CLI，都将在 ~/.fabric-aiops/audit.db 中生成一条审计记录；对于修改性写入操作，它仍会捕获操作前的状态，并在存在可用逆操作时记录该操作。

每个工具都会声明一个 risk_level，并由测试确保它与 [READ]/[WRITE] 文档标签一致；该级别还会作为描述性等级记录在审计行中，让审核者一眼就能看出某条记录涉及高风险删除。这只是一个标签，不是关卡。

快速开始

作为 Claude Code 插件

安装一次，即可同时为 Agent 提供技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install fabric-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定为此插件声明的软件包版本，因此可以追溯审计记录对应的写入代码。凭据仍需通过 fabric-aiops init 配置——请参阅下文。

作为 OpenClaw 插件

同一套插件包也发布在 ClawHub，安装一次即可同时获得技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/fabric-aiops
openclaw skills info fabric-aiops          # expect: Visible to model: yes

之后请重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定为此确切版本，因此 uvx 必须位于 PATH 中——否则技能仍会安装，但会显示 Visible to model: no。凭据配置方式与下文完全相同。

作为 CLI 或独立 MCP 服务

uv tool install fabric-aiops              # or: pipx install fabric-aiops
fabric-aiops init                         # wizard: choose platform (meraki/catalyst/cvp/unifi) + store the secret (encrypted)
fabric-aiops doctor                       # verify config, secrets, connectivity (per-platform auth probe)
fabric-aiops overview                     # one-shot fabric fleet health
fabric-aiops health uplink-rca            # rank worst MX WAN uplinks + cause/action (meraki)
fabric-aiops device inventory --model MS  # switches in the org

作为 MCP 服务运行（stdio）：

export FABRIC_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
fabric-aiops-mcp

密码之后会存放在哪里：导出的变量可被此 shell 启动的每个进程读取，也会记录在 shell 历史中。在共享主机或长期运行的主机上，建议使用交互式提示，或通过密钥管理器注入密码，仅在需要该密码的单条命令运行期间提供。

治理

每项操作——无论通过 MCP 还是 CLI——都会经过内置的 @governed_tool 机制。它负责记录，不负责授权（见上文）。

• 审计——每次调用的参数、结果、状态、耗时、风险等级，以及操作员提供的审批者/理由，都会记录到 ~/.fabric-aiops/audit.db（可通过 FABRIC_AIOPS_HOME 更改路径）。CLI 写入的记录与 MCP 路径完全相同——不存在未经审计的入口。
• 失控防护——这是安全后备措施，不是授权关卡：如果相同调用在短时间内被反复执行，就会触发断路器，防止卡住的 Agent 无限制地消耗调用次数或时间。使用 FABRIC_RUNAWAY_MAX=0 可禁用；也可通过 FABRIC_MAX_TOOL_CALLS / FABRIC_MAX_TOOL_SECONDS 设置可选的硬上限。
• 撤销记录——对于可逆写入操作，会根据获取到的操作前状态构建并记录逆操作描述符。
• 风险等级——根据 risk_level 得出的描述性标签，记录在审计行中；不用于限制任何操作。

范围

这是 AIops-tools 系列中的网络结构/控制器成员（提供受治理的 AI 运维能力，包括审计、预算、撤销和风险等级）。不要将它用于 OT/工业边缘设备（Modbus、OPC-UA、PROFINET）——请使用独立的 industrial-aiops 系列——也不要用于设备级 CLI/SSH 网络自动化。

缺少某项能力？

这里有意精选了各控制器 API 的一部分。你希望在 Meraki 中调用某个缺失的 API，或支持某类设备吗？Catalyst Center、CloudVision Portal 或 UniFi Network 的支持矩阵中有你需要的 ❌（包括写入操作，例如针对 9.0 之前控制器的 UniFi Cookie 登录回退方案）吗？想支持其他控制器平台吗？提交 issue 或 PR——欢迎贡献（一个平台只需一个描述符模块：路径模板 + 响应适配器）。

状态

此工具尚未针对任何平台的真实环境进行过测试，包括 Meraki 组织、Catalyst Center 设备、CloudVision Portal 实例、UniFi 控制器或 APIC。前四个平台的 API 路径依据公开的 API 结构建模，并通过模拟数据进行测试。ACI 读取操作使用来自生产网络 fabric 的真实匿名化 APIC 响应进行测试（端点、EPG、桥接域、VRF、合约、过滤器条目、故障），查询机制则使用 Cisco 自己的 SDK 进行测试——但此工具仍未在真实 APIC 上运行。 docs/VERIFICATION.md 列出了真实运行必须覆盖的检查清单；fabric-aiops doctor 是最快的实时检查方式。