协作约定
本页约束开发者和自动化编码助手的协作行为。目标是减少误操作、减少文档漂移，并保持业务边界稳定。
修改代码前建议先读 开发者索引、目录与边界 和与本次任务对应的参考页。
基本原则
- 先读文档和现有代码，再判断实现方式。
- 后端是业务真相来源，前端只负责展示、输入、交互和调用。
- 数据库结构变化必须有 Alembic 迁移。
- 影响用户行为、API、协议、Docker、数据结构或安全策略的变更必须同步文档。
- 不要把临时文件、缓存目录、构建产物或依赖缓存落入工作区。
自动化助手限制
自动化助手不得擅自：
- 启动后端、前端、Docker、EMQX、数据库或客户端 agent。
- 执行构建命令。
- 安装、升级、卸载依赖或改变本机环境。
- 绕过权限不足问题。
- 删除用户未明确要求删除的数据。
遇到权限不足时，应申请提权并说明用途。不得通过临时目录、脚本绕行或改变环境来规避。
文档同步
以下变更必须同步文档：
- 新增或修改功能页面。
- 新增或修改环境变量。
- Docker compose、Dockerfile、gateway 或反向代理行为变化。
- API、MCP、MQTT、SSE 协议变化。
- 客户端命令和安装行为变化。
- 快照内容和恢复语义变化。
- 安全边界变化。
前后端协作
前端如果发现需要复杂推导，应优先要求后端提供投影或字段。不要在前端复制：
- 在线状态判断。
- Mesh 拓扑校验。
- 同步状态判断。
- 产物缓存状态。
- EMQX 状态。
Git 和工作区
工作区可能存在用户未提交修改。不要回滚、覆盖或清理与当前任务无关的文件。
如果需要删除、移动或大规模重写文件，应先确认这些文件是否属于当前任务，并确保不会误删用户内容。