MikroTik 百科全书

概述

对 MikroTik 相关工作采用“文档优先”（docs-first）的工作流。优先查阅官方 MikroTik 文档站点 https://help.mikrotik.com/docs/；在重新拉取前，先检查本地缓存副本目录 .MikroTik-Encyclopedia/；并将有价值的官方文档摘录、以及环境特定的运维经验记录下来，以提升后续工作的效率与安全性。

本技能面向 MikroTik RouterOS/设备层。当问题明确涉及真实 RouterOS 的行为、配置或设备管理时应触发；不适用于通用网络原理建议，也不适用于通用 Linux 防火墙/路由器管理类问题。

工作流

1. 任务分类

   • 判断该任务属于 MikroTik 相关问题、故障排查、命令规划、配置审查，还是实时 SSH/API 操作任务。
   • 当请求明确指向 MikroTik 硬件、RouterOS 行为，或处于 MikroTik 上下文中的网络/管理任务时，启用本技能。
   • 除非上下文明确限定为 MikroTik/RouterOS，否则不得将本技能用于通用网络理论、厂商中立的防火墙设计，或通用 Linux 防火墙/管理工作。

2. 优先检查本地缓存

   • 以 .MikroTik-Encyclopedia/ 作为本地知识/缓存根目录。
   • 在相关场景下，优先检查以下路径：
     • .MikroTik-Encyclopedia/docs/help.mikrotik.com/docs/...
     • .MikroTik-Encyclopedia/notes/devices/...
     • .MikroTik-Encyclopedia/notes/patterns/...
     • .MikroTik-Encyclopedia/inventory/...
   • 若已有缓存页面或笔记足以清晰回答问题，则直接使用该内容。

3. 在作答或操作设备前，务必查阅官方 MikroTik 文档

   • 对于依赖 RouterOS 行为、语法、功能边界、安全态势或版本敏感细节的 MikroTik 问题（无论直接或间接），在作答前须查阅官方文档——除非本地缓存已提供充分支撑。
   • 在对 MikroTik 设备执行直接 SSH/API 访问前，如遇以下情形，须先查阅相关文档：
     • 命令路径必须精确无误
     • 功能语义容易被误记
     • 该操作可能影响路由、交换、桥接行为、VLAN、CAPsMAN、DHCP、防火墙策略或管理可达性
   • 当官方文档易于查阅时，切勿凭记忆即兴构造高影响度的 MikroTik 命令。

4. 将查阅过的文档本地缓存

   • 每次查阅 MikroTik 文档页面后，应在 .MikroTik-Encyclopedia/docs/help.mikrotik.com/docs/... 下保存一份标准化的 Markdown/纯文本缓存副本。
   • 尽可能镜像官方文档的路径结构。
   • 仅缓存实际查阅过的页面，不要主动尝试全量镜像整个文档站点。
   • 必要时可使用 scripts/cache_doc.py 工具。

5. 严格区分官方文档与本地观察结论

   • 源自官方文档的内容统一存放于 .MikroTik-Encyclopedia/docs/...。
   • 环境特定的运维知识存放于：
     • .MikroTik-Encyclopedia/notes/devices/
     • .MikroTik-Encyclopedia/notes/patterns/
     • .MikroTik-Encyclopedia/inventory/
   • 须清晰区分以下三类信息：
     • 官方明确定义的行为
     • 本地实际观测到的配置/状态
     • 基于经验推导的最佳实践建议

6. 记录有价值的本地经验

   • 完成有价值的实操任务后，应持久化记录如下类型笔记：
     • 设备角色与命名规范
     • 管理访问方式
     • 发现的拓扑关系
     • CAPsMAN/控制器部署位置
     • 反复出现的陷阱或 RouterOS 命令模式
     • 本环境中安全/不安全的操作边界
   • 优先编写简洁、可复用的持久化笔记，避免日后重复梳理相同拓扑。

实时访问规则

• 将查阅官方文档视为所有非平凡 MikroTik 工作的默认预检步骤。
• 首次进入近期未审查过的设备时，优先执行只读/检查操作。
• 将边缘路由器/防火墙、桥接/VLAN 变更、CAPsMAN 变更及管理服务变更视为高敏感区域。
• 在已核查缓存与文档后仍存不确定性时，应如实说明，切勿强行猜测作答。
• 回答问题时，若相关信息有价值，应注明其来源：来自缓存的官方文档、新近查阅的官方文档，还是实时观测到的设备状态。

数据根目录

请使用以下工作区本地根目录存放缓存与笔记：

• .MikroTik-Encyclopedia/

预期目录结构如下：

• .MikroTik-Encyclopedia/docs/help.mikrotik.com/docs/...
• .MikroTik-Encyclopedia/notes/devices/...
• .MikroTik-Encyclopedia/notes/patterns/...
• .MikroTik-Encyclopedia/inventory/...

可运行 scripts/init_workspace.py 创建或修复预期的目录结构。

笔记归档路径

• 设备特异性观察 → .MikroTik-Encyclopedia/notes/devices/.md
• 可复用的 RouterOS 模式/陷阱总结 → .MikroTik-Encyclopedia/notes/patterns/.md
• 全环境拓扑/访问信息 → .MikroTik-Encyclopedia/inventory/*.md
• 缓存的官方文档 → .MikroTik-Encyclopedia/docs/help.mikrotik.com/docs/...

密钥与敏感数据

• 禁止在百科全书笔记/资产清单树中存储明文凭证、API 密钥、会话令牌、私有 URL、恢复码或其他任何密钥类信息。
• 若笔记需提及访问细节，应保持高度抽象，并对密钥材料进行脱敏或完全省略。
• 应将这些工作区笔记视作运维记忆载体，而非密钥保险库。

资源

• scripts/init_workspace.py —— 创建或修复 .MikroTik-Encyclopedia/ 目录树。
• scripts/cache_doc.py —— 获取并缓存指定的官方 MikroTik 文档页面至 .MikroTik-Encyclopedia/docs/...。
• references/workflow.md —— 详尽的操作工作流及证据处理规范。
• references/cache-layout.md —— .MikroTik-Encyclopedia/ 目录结构的权威定义。
• references/topic-map.md —— 实用的 MikroTik 主题分组，便于快速定位文档。

理想成果

• 借助缓存或新近核查的官方文档回答 MikroTik 问题，而非依赖猜测。
• 在查阅相关文档后检查实时 MikroTik 设备，并记录任何新增的本地拓扑知识。
• 持续构建本地 MikroTik 知识缓存，使后续工作更高效、更安全、更具依据。
• 将一次性发现的 RouterOS 经验沉淀为持久化笔记，避免未来工作从零重新发现。

应避免的行为

• 在官方文档易于查阅的前提下，仅凭记忆回答 RouterOS 特定问题。
• 将本地观测到的行为等同于官方保证的、有据可查的行为。
• 无明确目的将大量低价值文档批量导入工作区。
• 将设备特异性观察写入官方文档缓存目录树。
• 在行为细节至关重要的前提下，未查阅相关文档即执行高影响度的实时变更。