MikroTik 词典

概述

采用以文档为先的工作流程处理 MikroTik 相关任务。优先查阅官方 MikroTik 文档（https://help.mikrotik.com/docs/），在重新获取前先检查本地缓存副本 .MikroTik-Encyclopedia/，并记录有用的官方文档内容以及环境相关的操作经验，以便未来工作更快速、更安全。

本技能适用于 MikroTik RouterOS / 设备层。应在涉及真实 RouterOS 行为、配置或设备管理的问题时触发——不适用于通用网络建议或通用 Linux 防火墙/路由器管理。

工作流程

1. 分类任务

- 判断任务是 MikroTik 问题、故障排查、命令规划、配置审查还是实时 SSH/API 操作。

- 当请求明确涉及 MikroTik 硬件、RouterOS 行为或 MikroTik 上的网络/管理任务时使用此技能。

- 不用于通用网络理论、跨厂商防火墙设计或通用 Linux 防火墙/管理任务，除非明确指出与 MikroTik/RouterOS 上下文相关。

1. 优先检查本地缓存

- 使用 .MikroTik-Encyclopedia/ 作为本地知识库和缓存根目录。

- 在相关时优先检查以下位置：

- .MikroTik-Encyclopedia/docs/help.mikrotik.com/docs/...

- .MikroTik-Encyclopedia/notes/devices/...

- .MikroTik-Encyclopedia/notes/patterns/...

- .MikroTik-Encyclopedia/inventory/...

- 若已有缓存内容能充分回答问题，则直接使用。

1. 在回答或操作设备前查阅官方文档

- 在回答依赖 RouterOS 行为、语法、功能边界、安全策略或版本敏感细节的 MikroTik 问题前，除非本地缓存已充分支持，否则应查阅官方文档。

- 在执行对 MikroTik 设备的直接 SSH/API 访问前，若满足以下任一条件，也应先查阅相关文档：

- 命令路径精确性至关重要

- 功能语义容易记错

- 操作可能影响路由、交换、桥接行为、VLAN、CAPsMAN、DHCP、防火墙或管理可达性

- 当文档易于查阅时，不要凭记忆随意编写高影响的 MikroTik 命令。

1. 将查阅的文档本地缓存

- 查阅 MikroTik 文档页面后，将其标准化的 Markdown/文本副本保存至 .MikroTik-Encyclopedia/docs/help.mikrotik.com/docs/...。

- 尽量保持与官方文档路径结构一致。

- 仅缓存实际查阅的页面，避免盲目镜像整个文档站点。

- 适时使用 scripts/cache_doc.py。

1. 区分官方文档与本地观察

- 官方文档来源的内容存储于 .MikroTik-Encyclopedia/docs/...。

- 环境特定的操作知识存储于：

- .MikroTik-Encyclopedia/notes/devices/

- .MikroTik-Encyclopedia/notes/patterns/

- .MikroTik-Encyclopedia/inventory/

- 明确区分：

- 官方文档中记载的行为

- 本地配置或状态的观察结果

- 推断出的最佳实践建议

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

- 在完成有效现场操作后，保存持久性笔记，例如：

- 设备角色与命名规范

- 管理访问方式

- 发现的拓扑关系

- 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/<device-name>.md
• 可复用的 RouterOS 模式/常见陷阱 → .MikroTik-Encyclopedia/notes/patterns/<topic>.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 相关问题。
• 将本地观察到的行为视为已正式文档化且确定无疑的规则。
• 无明确目的地将大量低价值文档内容导入工作区。
• 将设备特定的观察结果写入官方文档缓存树中。
• 在精确行为至关重要的情况下，未查阅相关文档就进行高影响的实时变更。