云简WLAN巡检技能（极简版）

版本：V0.0.1

🎯 设计原则：大模型做数据提取+判定，脚本仅做报告格式输出（MD+DOCX双格式）。

第0步：前置检查（必须最先执行）

0.1 读取配置文件

# 读取skill根目录的config.json
cat config.json

config.json 格式：

{
  "mcporter_name": "oasis",
  "api_key": "xxxxxxxx",
  "shops": [
    { "name": "场所名称" }
  ]
}

💡 shops 只需填写 name（场所名称），shopId 在巡检时由第1步 API 自动获取。

如果 api_key 为占位文本（如"在此填入"），提示用户填入真实 API Key 后重新巡检。

0.2 检查mcporter CLI

mcporter --version

• 通过：≥ 0.9.0 | 未通过：提示 npm install -g mcporter

0.3 检查并配置云简MCP连接

唯一MCP地址（正式环境）：

https://oasis.h3c.com/mcp-server/api/sse

mcporter config list

• 如果列表中已存在 mcporter_name 对应的配置 → ✅ 通过
• 如果不存在 → 自动执行配置：

mcporter config add \x3Cmcporter_name> https://oasis.h3c.com/mcp-server/api/sse --header "Authorization=Bearer \x3CAPI_KEY>"

0.4 确认巡检场所

优先使用 config.json 中的 shops 列表（仅 name 字段）：

• 仅1个场所 → 直接使用，无需询问
• 多个场所 → 列出供用户选择
• shops 为空 → 询问用户输入场所名称

⚠️ 不可假设场所名称，必须有明确来源。shopId 由第1步 API 查询后获取，无需在 config.json 中预填。

0.5 检查python-docx（DOCX报告用）

python -c "import docx; print('OK')"

• 通过：✅ | 未通过：提示 pip install python-docx（仅影响DOCX输出，MD仍可生成）

0.6 输出检查结果

✅ mcporter v0.9.0
✅ 云简MCP连接：\x3Cmcporter_name>
✅ 巡检场所：XXX
✅ python-docx

全部就绪，开始巡检。

如有未通过项，逐条列出 ❌ 并提示修复方法，不继续执行。

mcporter调用规范（必读）

规则1：无参工具不传任何参数

# ✅ 正确
mcporter call \x3Cmcp-name> getallshopsanddevofuser

# ❌ 错误
mcporter call \x3Cmcp-name> getallshopsanddevofuser --args '{}'

规则2：有参工具使用 key=value 格式（PowerShell兼容）

# ✅ 正确
mcporter call \x3Cmcp-name> getDeviceRunInfo devSN=210235A2G0B206000003
mcporter call \x3Cmcp-name> getProblemDistribute shopId=2673243 "startTime=2026-05-19 00:00:00.000" "endTime=2026-05-19 10:00:00.000" timezone=Asia/Shanghai

# ❌ 错误 — PowerShell下单引号JSON解析失败
mcporter call \x3Cmcp-name> getDeviceRunInfo --args '{"devSN":"210235A2G0B206000003"}'

规则3：每个API结果保存为独立JSON文件

mcporter输出含大量schema信息，日志中易截断。使用 mcporter_call.py 保存纯净JSON。

# ✅ 正确
python scripts/mcporter_call.py \x3Cmcp-name> \x3Ctool-name> reports/stepX.json [key=value ...]

# ❌ 错误 — PowerShell重定向有编码问题
mcporter call ... > reports/stepX.json

💡 mcporter_call.py 是唯一保留的Python脚本，仅做mcporter输出提取和文件保存，无第三方依赖。如Python也不可用，可改用cmd重定向：cmd /c "mcporter call ... > reports/stepX.json 2>&1"

巡检步骤

第1步：获取场所shopId和AC信息（串行，必须先完成）

工具： getallshopsanddevofuser（无参数！）

python scripts/mcporter_call.py \x3Cmcp-name> getallshopsanddevofuser reports/step1.json

大模型处理： 从step1.json中提取：

• 匹配用户指定场所名称（来自 config.json 或用户输入）→ shopId
• 该场所下customType=ac的设备 → devSN、devModel、devAlias、status、softVer
• 如匹配不到场所名称，列出所有场所供用户选择

💡 shopId 由本步骤从 API 实时获取，config.json 无需预填。

第2-5步：并行采集数据

⚠️ 步骤2/3/4/5 相互无依赖，必须同时发起。

第2步：AC健康度

工具： getDeviceRunInfo

python scripts/mcporter_call.py \x3Cmcp-name> getDeviceRunInfo reports/step2.json devSN=\x3CAC序列号>

大模型提取： cpuRatio / memoryRatio / diskRatio / speed_up / speed_down

判定标准：

第3步：问题分布 + 接入成功率（2个调用并行）

工具A： getProblemDistribute

python scripts/mcporter_call.py \x3Cmcp-name> getProblemDistribute reports/step3a.json shopId=\x3C场所ID> "startTime=\x3C当天 00:00:00.000>" "endTime=\x3C当前时间>" timezone=Asia/Shanghai

大模型提取： 按times降序排列取TOP5问题类型及子类明细

工具B： getHistoryAccessSucOneDay（参数同上）

python scripts/mcporter_call.py \x3Cmcp-name> getHistoryAccessSucOneDay reports/step3b.json shopId=\x3C场所ID> "startTime=\x3C当天 00:00:00.000>" "endTime=\x3C当前时间>" timezone=Asia/Shanghai

大模型提取： 找出最低接入成功率、对应时间、低于98%的时段数

判定： ≥98% 🟢 | ≥95% ⚠️ | \x3C95% 🔴

第4步：Oasis问题推理

工具： getShopNetworkProblem

python scripts/mcporter_call.py \x3Cmcp-name> getShopNetworkProblem reports/step4.json shopId=\x3C场所ID>

大模型提取：

• data.summary[] → 按alarmLevel统计高危(3)/中危(2)数量
• data.data[] → 按alarmLevel分组，提取 reasoningType / count / reasoningCategory / suggestion / status

第5步：AP上线率（2个调用并行）

工具A： getCurrentApCount

python scripts/mcporter_call.py \x3Cmcp-name> getCurrentApCount reports/step5a.json shopId=\x3C场所ID>

大模型提取： online / offline / total，计算上线率

工具B： getApRegularMatch

python scripts/mcporter_call.py \x3Cmcp-name> getApRegularMatch reports/step5b.json shopId=\x3C场所ID> dim=1

大模型提取： 从detail[]中筛选Ss=2的AP，提取apName列表

判定： ≥98% 🟢 | ≥95% ⚠️ | \x3C95% 🔴

第6步：组装数据 + 生成双格式报告

6.1 组装结构化巡检数据

大模型逐个读取 step1~step5b 的JSON文件，从 response.data 中提取关键字段，组装为符合 references/data-format.md 格式的JSON文件。

# 将结构化数据写入 reports/巡检数据_\x3C场所>_\x3C时间>.json

📄 数据格式参考：读取 references/data-format.md 了解完整JSON schema。

告警级别判定标准：

6.2 生成MD+DOCX双格式报告

python scripts/gen_report.py --data-file reports/巡检数据_\x3C场所>_\x3C时间>.json --output-dir reports/

此脚本同时输出：

• MD报告：reports/巡检报告_\x3C场所>_\x3C时间戳>.md
• DOCX报告：reports/巡检报告_\x3C场所>_\x3C时间戳>.docx

报告结构（6章）：

一、执行摘要 → 关键指标 + 风险概览
二、健康度评估 → AC健康度 + 问题分布 + 接入成功率 + AP上线率
三、问题详细分析 → 高危/中危问题明细
四、问题处理优先级 → P0/P1/P2 分级
五、整改计划 → 短期/中期/长期
六、巡检结论 → 总体评价 + 关键风险 + 趋势建议

报告撰写要求：

• 全部中文，术语/缩写保留英文（CPU、RSSI、AP、AC、SSID、Portal、DHCP、SNMP、ARP、DNS、MTU、MSS、MCP、Oasis、mcporter等）
• 首页：标题"无线网络运维巡检报告（极简版）" + 场所名称 + 巡检时间 + 巡检工具名
• 按告警级别判定标准进行各项评级
• 问题分析基于实际数据，不可编造
• 整改计划结合实际问题给出针对性建议

6.3 向用户输出巡检摘要（必须执行）

⚠️ 报告生成后，必须在聊天界面输出摘要，不要只说"报告已生成"。

📋 巡检完成 — {场所名称}

🏥 AC健康度：CPU {x}% / 内存 {x}% / 磁盘 {x}% — {🟢正常/⚠️需关注/🔴严重}
📊 接入成功率：{min}%~100% — {🟢/⚠️/🔴}
📡 AP上线率：{rate}%（在线{on}/总计{total}）— {🟢/⚠️/🔴}
⚠️ 问题：高危{h}项 / 中危{m}项

🔴 需立即处理：
  1. {最高优先级问题} — {建议}
  2. {次高优先级问题} — {建议}

📁 报告已生成：
  MD：{md文件完整路径}
  DOCX：{docx文件完整路径}

执行流程图

第0步：读取config.json → mcporter检查 → MCP连接配置 → 场所确认
        │
        ▼
第1步：获取shopId + devSN（串行）→ step1.json
        │
        ├──────────┬──────────┬──────────┐
        ▼          ▼          ▼          ▼
     第2步       第3步       第4步       第5步       ← 并行
     step2.json  step3a/b   step4.json  step5a/b
        │          │          │          │
        └──────────┴──────────┴──────────┘
                        │
                        ▼
第6步：LLM提取数据 → 组装结构化JSON → gen_report.py
        │
        ├── reports/巡检报告_XXX.md    (MD格式)
        └── reports/巡检报告_XXX.docx  (DOCX格式)
                        │
                        ▼
                  输出巡检摘要

文件结构

skills/cloudnet-wlan-inspection-lite/
├── SKILL.md                        # 本文件
├── config.json                     # API Key + 场所配置（用户填写）
├── scripts/
│   ├── mcporter_call.py            # mcporter输出提取（无第三方依赖）
│   └── gen_report.py              # MD+DOCX双格式报告生成（依赖python-docx）
└── references/
    └── data-format.md              # 巡检数据结构化JSON格式定义

config.json 字段说明