simplemesh-agent - SKILL.md Agent Skill

name: simplemesh-agent description: Agent 专用约束：状态机唯一入口、backhaul 先于 MQTT、both 模式从 UCI、周期任务用 main_task。修改 src/agent_sm.c、agent 状态机、backhaul/MQTT 连接逻辑时使用。

接到与 Agent 相关的修改时，先判断是否符合本 skill 与全局架构；若有偏离，先简要说明再确认是否执行。

状态定义（agent_sm.h）：AGENT_STATE_INIT → AGENT_STATE_CONNECTING → AGENT_STATE_CONNECTED → AGENT_STATE_ONLINE。
唯一状态机入口：只有 agent_connection_state_machine_task（main_task 周期任务）可以修改 ctx->state。其他位置（如 agent_mqtt_on_connect、agent_mqtt_on_disconnect、agent_sm_start、agent_sm_stop）不得改状态，只做标志或清理。
判断“是否在线”：用 ctx->state == AGENT_STATE_ONLINE（或 state >= AGENT_STATE_CONNECTED 视需求）。不要在 agent_ctx 里维护 mqtt_connected；底层连接状态用 ctx->mqtt.connected（mqtt_client_t 的字段）即可。

both 模式：从 UCI simplemesh.global.mode='both' 判定。config_load_simplemesh() 填充 uci_cfg.mode；agent_sm_init() 中 strcmp(uci_cfg.mode, "both") == 0 时设 ctx->is_both_mode = 1。
backhaul 判断：在 agent_connection_state_machine_task 中，若 ac->is_both_mode 为真，则 bh_connected = 1，不调用 backhaul_is_connected(iface)；否则 bh_connected = backhaul_is_connected(iface)。both 模式下不依赖实际回传即可连 MQTT。

hostapd：根据 UCI simplemesh.wifi.wifi_iface 对全部 interface 连接 hostapd（ubus 订阅）；收到事件后及时打印处理。
状态：start 时状态为 AGENT_STATE_CONNECTING；由 agent_connection_state_machine_task 根据 backhaul（或 both）决定是否连 MQTT → connected → online。
backhaul：非 both 时检查 backhaul（backhaul_is_connected(bh_iface)）；可结合 simplemesh.backhaul 的 ssid/key 做扫描连接与周期检查（如 20s）。
connected → online：MQTT 连上后发 Topology_query（如 JOIN）；收到 controller 的 topology_report（带 JOIN 响应）并解析通过后，state 设为 AGENT_STATE_ONLINE；可回 topology_ack。仅当 state 为 ONLINE 后做日常 HEARTBEAT、Topology report 等。

统一入口：Agent 的周期逻辑全部通过 main_task 调度（main_task_add 注册，由 task_timer_cb → agent_main_task_tick → main_task_tick 驱动）。不要用独立的 conn_retry、report_timer；连接与上报节奏由 agent_connection_state_machine_task、agent_join_query_task、agent_topology_query_task 等 main_task 任务完成。
心跳：仅在 state == AGENT_STATE_ONLINE 时启动/续期 heartbeat（uloop_timeout_set(&ctx->heartbeat, ...)）。

配置：broker/port、bh_iface、wifi_ifaces、mode 等从 UCI（platform/config_uci.c，config_load_simplemesh）读取；命令行 -b/-p 可选，未传时用 UCI。both 仅看 UCI mode，不看 -m。
设备身份（AL MAC 等）：通过 platform/system_api.c 的 init_device_info 获取（与 Controller 共用）；硬件/系统通用参数统一在 system_api，不依赖 backhaul 的“读 MAC”语义。
数据源：WiFi 用 platform/wifi_ubus.c（ubus/hostapd）、platform/hostapd_ubus.c（事件订阅）；backhaul 用 platform/backhaul.c（回传连接状态、wpa_cli 等，不用于设备身份 MAC）；系统状态预留 system_monitor。不把 controller 逻辑或策略引擎放进 agent。

新增状态或状态转移：只可在 agent_connection_state_machine_task 内修改 state 及触发 MQTT 连接/断开、topology_query、heartbeat 启动。
新增周期任务：用 main_task_add 注册到 ctx->main_tasks，不要在 agent 里增加新的 uloop_timeout 做连接重试或周期上报（除非明确是 heartbeat 等已约定定时器）。
判断 MQTT 是否连接：用 ctx->mqtt.connected，不要恢复 agent_ctx.mqtt_connected 字段。

全局框架：.cursor/skills/simplemesh/SKILL.md
架构与 MQTT：doc/0_architecture.md、doc/1_mqtt_topic.md
实现：src/agent_sm.c 中 agent_connection_state_machine_task、main_task_add、agent_main_task_tick、agent_sm_init（is_both_mode 从 UCI）。