diff --git a/runtime/workspaces/ops/ROLE_SYSTEM.en.md b/runtime/workspaces/ops/ROLE_SYSTEM.en.md index b79a0ff8..695bed42 100644 --- a/runtime/workspaces/ops/ROLE_SYSTEM.en.md +++ b/runtime/workspaces/ops/ROLE_SYSTEM.en.md @@ -35,6 +35,7 @@ You are the ops specialist (network operations expert). ## Required skills - For every netx/UME **alarm or NE** request, load and follow skill: `ops-netx-ume-playbook` (skill text may be Chinese; **user-facing output must still match the user's language**). - When logging into **netx managed NEs** (SSH/Telnet inventory under NE management) to run show/display CLI, load and follow: `ops-netx-managed-ne-playbook`. +- For **protocol troubleshooting, config baselines, historical cases, product-specific behavior, or IP ops SOPs** (e.g. how to triage BGP/MPLS/LDP/VPN, standard config, prior incidents), load and follow: `ops-ip-knowledge-playbook`; search `docs/ip-knowledge-base` first, then **verify with netx tools** — never conclude from the KB alone. ## Skill creation and installation constraints (mandatory) - When the user asks to create/write/install a skill, use only `skill_auto_install`; do not switch to any other install path. diff --git a/runtime/workspaces/ops/ROLE_SYSTEM.md b/runtime/workspaces/ops/ROLE_SYSTEM.md index dc34e123..28e7e8fd 100644 --- a/runtime/workspaces/ops/ROLE_SYSTEM.md +++ b/runtime/workspaces/ops/ROLE_SYSTEM.md @@ -27,6 +27,7 @@ ## 必须加载技能 - 每次处理 netx/UME **告警或网元** 问题时，必须加载并遵循技能：`ops-netx-ume-playbook`。 - 每次需要在 **netx 网元管理（纳管 SSH/Telnet 设备）** 上登录查配置/状态时，必须加载并遵循技能：`ops-netx-managed-ne-playbook`。 +- 每次涉及 **协议排障、配置规范、历史案例、产品特性或 IP 运维 SOP**（如 BGP/MPLS/LDP/VPN 怎么查、应该怎么配、类似故障是否发生过）时，必须加载并遵循技能：`ops-ip-knowledge-playbook`；检索 `docs/ip-knowledge-base` 后仍须用 netx 工具验证，不得仅凭知识库下结论。 ## Skill 创建与安装约束（强制） - 当用户要求“新建/编写/安装 skill”时，只能使用 `skill_auto_install`，禁止切换为其它安装路径。 diff --git a/skills/_workspace/ops/ops-ip-knowledge-playbook/SKILL.md b/skills/_workspace/ops/ops-ip-knowledge-playbook/SKILL.md new file mode 100644 index 00000000..6bd633b0 --- /dev/null +++ b/skills/_workspace/ops/ops-ip-knowledge-playbook/SKILL.md @@ -0,0 +1,102 @@ +--- +name: ops-ip-knowledge-playbook +description: 面向 ops 专家的 IP 运维知识库作业手册。覆盖协议排障、配置规范、历史案例检索，并与 netx 实时证据联动验证。 +--- + +# Ops IP 知识库作业手册 + +## 强制使用范围 + +凡是涉及以下主题的 ops 请求，**必须先加载并遵循本技能**，再下结论或给修复步骤： + +- 协议排障思路（BGP/OSPF/IS-IS/MPLS/LDP/VPN 等）：「为什么」「怎么查」「下一步看什么」 +- 配置规范与基线：「应该怎么配」「标准模板」「避坑」 +- 产品/平台特性：不认识的 CLI、版本 Bug、与友商对接差异 +- 历史故障案例：类似现象是否出现过、已知根因与修复 +- 监控阈值与 SOP：什么算异常、标准命令组合 + +**不触发本技能**（改用对应 netx playbook）： + +- 仅查 UME 当前告警/网元清单 → `ops-netx-ume-playbook` +- 仅需登录纳管设备执行 show/display → `ops-netx-managed-ne-playbook` + +可与上述 playbook **叠加使用**：知识库给假设与检查顺序，netx 给现场证据。 + +## 知识库根路径 + +``` +docs/ip-knowledge-base/ +└── zte/ # 厂商分区（当前仅 zte） + ├── 01_协议排障逻辑树/ # If...Then 决策树 + ├── 02_产品平台特性/ # 设备/版本特有知识（优先级最高） + ├── 03_配置规范与基线/ # 标准配置模板 + ├── 04_历史故障案例库/ # 真实案例 + 推理链 + ├── 05_监控指标与告警阈值/ # 量化异常标准 + └── 06_标准SOP与工具脚本/ # 命令速查与探索方法 +``` + +## 检索工具与顺序 + +ops 专家可用 `search_files`、`read_file`、`list_directory`（路径相对于仓库根 `PROJECT_ROOT`）。 + +### 标准流程（每次排障/配置咨询必走） + +1. **定位层级**：根据用户问题选目标目录（见下节「层级速查」） +2. **关键词搜索**： + - `search_files(pattern=<协议/现象关键词>, root=docs/ip-knowledge-base, file_glob=**/*.md, regex=false)` + - 同时搜中文与英文缩写（如 `下一跳NULL`、`next-hop-self`、`access-fec`） +3. **精读命中文件**： + - `read_file(path=docs/ip-knowledge-base/zte/...)`，大文件分段读（`offset`/`limit`） + - 优先读：`04_历史故障案例库` → `01_协议排障逻辑树` → `06_标准SOP` → `03_配置规范` → `02_产品平台特性` +4. **现场验证**（强制，不可跳过）： + - 知识库给出的是「检查什么、期望什么」；**必须用 netx MCP 在真实网元上验证** + - 纳管设备：`ops-netx-managed-ne-playbook` → `mcp__netx__execManagedNe` + - 告警关联：`ops-netx-ume-playbook` → 查相关网元/告警上下文 +5. **输出**：结论 + **知识库引用路径** + **CLI/MCP 证据摘录** + 最小修复步骤 + +### 检索失败时 + +- 明确告知「知识库暂无命中」，不得编造案例编号或根因 +- 改用 `06_标准SOP与工具脚本/命令探索方法论.md` 指导现场 `?` 探索 +- 排障闭环后，建议用户将案例沉淀到 `04_历史故障案例库`（勿擅自写入，除非用户明确要求） + +## 层级速查 + +| 用户意图 | 优先目录 | 典型关键词 | +|----------|----------|------------| +| 怎么排查 / 为什么这样 | `01_协议排障逻辑树/` | 邻居、标签、NULL、选路、泄露 | +| 命令不认识 / 版本差异 | `02_产品平台特性/` | access-fec、5800、ReleaseNotes | +| 应该怎么配 | `03_配置规范与基线/` | 基线、规范、Option-B、模板 | +| 以前遇到过吗 / 根因是什么 | `04_历史故障案例库/` | 案例编号、故障日期、关键词标签 | +| 多少算异常 / 要不要告警 | `05_监控指标与告警阈值/` | 阈值、超限、震荡 | +| 具体敲什么命令 | `06_标准SOP与工具脚本/` | SOP、速查、命令探索 | + +## 与 netx 的协作原则（证据优先） + +```text +用户问题 + ├─ 需要当前设备状态？ → 先/并行 netx MCP（ROLE_SYSTEM：证据优先） + ├─ 需要排障思路或历史经验？ → 本技能检索 ip-knowledge-base + ├─ KB 命中逻辑树/案例？ → 按树逐步 exec CLI 验证每一步 + └─ KB 无命中？ → 命令探索方法论 + 现场采集 → 建议沉淀案例 +``` + +**禁止**：仅凭知识库或模型常识下结论，而不调 netx 拿证据。 + +**禁止**：把 RFC/教科书大段复述给用户；知识库价值在于「本公司设备上的 If→Then 与实测案例」。 + +## 输出约定 + +- 必须包含： + - **结论**（一句话） + - **知识库依据**（文件相对路径，如 `docs/ip-knowledge-base/zte/04_.../BGP_跨域....md`） + - **现场证据**（netx 工具返回摘录；无证据时标明「未验证」） + - **下一步**（可执行的最小步骤） +- 引用案例时带上案例元数据中的 `案例编号`、`关键词标签`（若有） +- 修复步骤涉及配置变更：先说明影响范围与回滚，再给出命令（ROLE_SYSTEM 变更安全） +- **用户用英文提问时**：回复不得含汉字；知识库中文内容须译成英文后再写入正文 + +## 参考 + +- 目录索引与检索示例：[reference.md](reference.md) +- 命令在线探索：`docs/ip-knowledge-base/zte/06_标准SOP与工具脚本/命令探索方法论.md` diff --git a/skills/_workspace/ops/ops-ip-knowledge-playbook/reference.md b/skills/_workspace/ops/ops-ip-knowledge-playbook/reference.md new file mode 100644 index 00000000..7a2fafdb --- /dev/null +++ b/skills/_workspace/ops/ops-ip-knowledge-playbook/reference.md @@ -0,0 +1,116 @@ +# Ops IP 知识库快速参考 + +## 1) 根路径与工具参数 + +| 项 | 值 | +|----|-----| +| 根目录 | `docs/ip-knowledge-base` | +| 当前厂商分区 | `zte/` | +| 搜索工具 | `search_files` | +| 阅读工具 | `read_file` | +| 列目录 | `list_directory` | + +**search_files 推荐参数**： + +```json +{ + "pattern": "下一跳 NULL", + "root": "docs/ip-knowledge-base", + "file_glob": "**/*.md", + "regex": false, + "max_matches": 50 +} +``` + +**read_file 分段阅读**（逻辑树/案例较长时）： + +```json +{ + "path": "docs/ip-knowledge-base/zte/01_协议排障逻辑树/BGP/VPN跨域标签异常排查树.md", + "offset": 1, + "limit": 120 +} +``` + +## 2) 六层目录职责 + +| 目录 | 回答的问题 | RAG 优先级（排障场景） | +|------|------------|------------------------| +| `01_协议排障逻辑树` | 怎么想 | 高（决策顺序） | +| `02_产品平台特性` | 设备特有行为 | 最高（模型不知道） | +| `03_配置规范与基线` | 应该怎么配 | 中 | +| `04_历史故障案例库` | 真实发生过什么 | 高（根因链） | +| `05_监控指标与告警阈值` | 什么算异常 | 中（告警解读） | +| `06_标准SOP与工具脚本` | 敲什么命令 | 高（操作动作） | + +## 3) 当前已收录文档（截至维护时） + +### 01 协议排障逻辑树 + +- `zte/01_协议排障逻辑树/BGP/VPN跨域标签异常排查树.md` + +### 02 产品平台特性 + +- （占位，见目录 README） + +### 03 配置规范与基线 + +- `zte/03_配置规范与基线/LDP_配置基线.md` +- `zte/03_配置规范与基线/BGP_跨域配置规范.md` + +### 04 历史故障案例库 + +- `zte/04_历史故障案例库/BGP/标签与LDP类/BGP_跨域下一跳NULL_LDP策略与下一跳修复_20260720.md` + - 案例编号：`BGP-CROSS-DOMAIN-001` + - 关键词：`#下一跳NULL` `#LDP标签分配` `#access-fec` `#next-hop-self` + +### 05 监控指标与告警阈值 + +- （占位，见目录 README） + +### 06 标准 SOP 与工具脚本 + +- `zte/06_标准SOP与工具脚本/故障处理常用命令.md` +- `zte/06_标准SOP与工具脚本/命令探索方法论.md` + +## 4) 按场景的检索关键词 + +| 场景 | 建议 pattern（可多次搜索） | 预期命中层 | +|------|---------------------------|------------| +| VPN 跨域不通 / 下一跳 NULL | `下一跳NULL`、`access-fec`、`next-hop-self`、`VPN跨域` | 01 + 04 + 03 | +| MPLS 标签缺失 / Interface NULL | `标签`、`mpls forwarding`、`LDP` | 01 + 04 + 06 | +| BGP 跨域怎么配 | `Option-B`、`跨域配置`、`next-hop-self` | 03 | +| 不认识 LDP 命令 | `access-fec`、`ldp instance` | 02 + 03 | +| 命令忘了怎么敲 | `show bgp`、`命令探索` | 06 | +| 告警是否严重 | `阈值`、`超限` | 05 | + +## 5) BGP 跨域排障推荐阅读顺序（示例） + +1. `search_files` → 命中案例 `BGP_跨域下一跳NULL...` +2. `read_file` 案例 §1 现象 + §3 根因表 +3. `read_file` `VPN跨域标签异常排查树.md` 对应 If 分支 +4. `read_file` `BGP_跨域配置规范.md` 检查清单（若涉及配置修复） +5. `mcp__netx__execManagedNe` 按树执行验证命令（只读） +6. 输出：结论 + 案例路径 + CLI 摘录 + +## 6) 与 UME 告警联动（可选） + +当用户从告警切入排障： + +1. `ops-netx-ume-playbook`：定位网元 `host_name`、告警 `event_type`/`native_probable_cause` +2. 将告警关键词代入 `search_files`（如 BGP、LDP、Fan） +3. 若 `05_监控指标与告警阈值` 有对应阈值文档，对照是否真异常 +4. 需要设备侧确认时切 `ops-netx-managed-ne-playbook` + +## 7) 知识沉淀（闭环后） + +排障结束且用户同意记录时，新案例建议结构（写入 `04_历史故障案例库/`）： + +- 案例元数据表（编号、协议、关键词、日期、等级） +- §1 现象特征（含命令输出） +- §2 理论锚点（简短，不抄 RFC） +- §3 根因推理表（层层递进） +- §4 修复与验证 +- 维护者 + netx 实测网元 + +配套产出：从案例拆 `01` 逻辑树节点 + `06` 三五步速查。