simplemesh-global - SKILL.md Agent Skill

name: simplemesh-global

description: SimpleMesh2 全局框架约束。涉及入口、UCI、MQTT 文档、uloop、角色划分、文件映射时使用。Agent/Controller 具体逻辑见各自 skill。

SimpleMesh 全局框架（Global）

接到修改/新增需求时，先判断是否与 doc/0_architecture.md 及本 skill 的模块划分一致；若有偏离，先简要说明架构上的影响，再确认是否按该方式实现。

Controller 模式：只做策略 + MQTT 收发。不直接连 hostapd、不连 system_monitor/backhaul；不持有 WiFi/系统/回传的底层数据源。输入输出均为 MQTT。
Agent 模式：负责本机状态采集 + 状态机 + MQTT。数据源：ubus+hostapd（WiFi）、system_monitor（系统）、backhaul（回传）。状态机：init → connecting → connected → online。具体约束见 Agent skill。
Controller 设备：可同时运行 controller 与 agent（同进程双角色）；agent 仅负责本机上报与状态。
Agent 设备：只运行 agent 模式；不实现 controller 逻辑。
I/O 多路复用：使用 libubox (uloop)，不得使用 libuv。MQTT、Unix socket、定时器均通过 uloop 接入。
MQTT 主题与报文：以 doc/1_mqtt_topic.md 为准（ap/topology_query、ap/topology_report、HEARTBEAT 等）。

入口：src/main_uloop.c。解析 -m controller|agent|both、-b、-p；启动 uloop；可选同时跑 controller + agent。
配置：broker/port 未传 -b/-p 时从 UCI /etc/config/simplemesh 的 simplemesh.global 读取（mqtt_broker、mqtt_port）。mode（controller/agent/both）仅从 UCI simplemesh.global.mode 读取，用于 both 模式判断（见 Agent skill）。

both 模式：表示 controller 设备双模式；Agent 将 backhaul 视为已连，不依赖实际回传。判断方式：UCI simplemesh.global.mode='both'；由 config_load_simplemesh() 填充 struct simplemesh_uci_config.mode，Agent 在 init 时据此设 is_both_mode。不得在 agent 内依赖命令行 -m both 做 backhaul 逻辑。

| 职责 | 路径 |

|------------|------|

| 入口、-m | src/main_uloop.c |

| Agent 状态机 | src/agent_sm.c、agent_sm.h → 见 Agent skill |

| Controller | src/controller.c、controller.h → 见 Controller skill |

| 硬件/系统通用 | src/platform/system_api.c、system_api.h：设备 MAC、接口等通用参数；init_device_info 供 Controller 与 Agent 共用；新增硬件或系统级读取统一放此处。 |

| UCI 配置 | src/platform/config_uci.c、config_uci.h（global：broker、port、mode；wifi；backhaul） |

| MQTT/报文 | src/transport/mqtt_client.c、mesh_mqtt.c、mqtt_topics.h |

| 周期任务 | src/main_task.c、main_task.h（controller/agent 共用） |

| 日志 | src/log_simple.c、log_simple.h |

定时/重连：使用 uloop_timeout 或 main_task，不用 libuv timer。
Socket 事件：使用 uloop_fd_add，不用 libuv poll。
MQTT 主题：在 transport/mqtt_topics.h 或 doc/1_mqtt_topic.md 中定义；实现与文档一致。
角色边界：Controller 逻辑不加 hostapd/system_monitor/backhaul；Agent 逻辑按状态机与数据源放置，见各自 skill。
硬件/系统通用：获取设备 MAC、接口信息等硬件或系统通用参数统一放在 platform/system_api.c，通过 init_device_info 等接口供 Controller/Agent 共用；不把“读网卡 MAC”等通用逻辑放在 backhaul（backhaul 只做回传连接状态、STA 等）。