Imported from cenming1008/CampusEnergySystem (AGENTS.md). Install upstream with npx skills add cenming1008/CampusEnergySystem. Copyright stays with the author.

AGENTS.md

项目协作规则

本项目采用五角色协作模式（兼容旧称：五线程）：

1. 验收
2. 后端
3. 前端
4. 规则（原：规范）
5. 预判（原：探索）

协作流程、归档与主题收口的正式执行规范，统一以 docs/guides/ai-collaboration-sop.md 为准。 通用 Five Role 分流方法可调用 five-role-collaboration skill；本仓库的角色分流、切换、并行边界、契约承载与单轮闭环适配口径，统一以 docs/guides/five-role-vibe-coding-framework.md 为准。

所有角色开始工作前，必须先阅读：

• AGENTS.md
• docs/plans/current-status.md
• docs/plans/handoff.md
• 当前主题对应 PLAN-*.md（如存在）
• docs/guides/product-positioning.md
• docs/guides/five-role-vibe-coding-framework.md（本项目 Five Role 适配说明）

如果涉及具体实现，还必须继续阅读：

• 前端线程：docs/guides/frontend-guidelines.md
• 后端线程：docs/guides/backend-guidelines.md

如果涉及新增设备类型、设备协议接入、设备字段分层、专属遥测/参数/控制链建模，还必须继续阅读：

• 设备分类：docs/guides/device-data-classification.md

如果涉及脚本新增、迁移、整理或入口调整，还必须继续阅读：

• 脚本治理：docs/guides/script-guidelines.md

产品默认方向

当前项目默认产品定位为：

• 园区综合能源管理系统
• Campus Energy Management System
• 智慧园区 EMS

当前阶段主线为：

• 多能源接入
• 分层计量
• 分项分析
• 告警联动
• 驾驶舱展示

所有角色默认围绕以下核心业务对象推进：

• 园区
• 区域
• 楼栋
• 设备
• 表计
• 能源介质（电、水、气、冷、热）
• 分项能耗
• 告警
• 实时负荷

以下概念后续不再作为默认主线继续发散：

• 矿井专属表述
• 瓦斯抽采
• 通风 / 排水等煤矿专属对象
• 与当前园区方向无关的强行业叙事

原则：

• 保留技术底座，迁移产品定位
• 保留兼容能力，不继续扩张煤矿专属主线
• 新增分析、页面、接口、命名优先采用园区能源管理语境
• MineEnergySystem / Mine / “煤矿”不再作为当前产品主名继续扩写；若仍出现在仓库路径、历史归档或运行时兼容标识中，默认按历史或兼容层处理，不得直接据此发起批量 rename

角色职责

通用职责定义由 five-role-collaboration skill 承载；本项目只保留以下适配摘要。角色组合、切换、并行边界、文档分级与交接格式以 docs/guides/five-role-vibe-coding-framework.md 为准。

硬边界：

• 前端不直接修改后端逻辑；后端不直接修改前端页面逻辑。
• 预判优先产出事实和路径，不把验证性修改扩成正式实现。
• 规则只做边界和契约裁决，不顺手做业务实现。
• 即使没有单独的验收角色，每个主题结束时也必须执行验收动作。
• 若发现旧有煤矿专属能力，先判断其是否只是历史残留，不默认继续扩张。

工作顺序

所有角色默认遵循以下顺序：

1. 阅读 AGENTS.md
2. 阅读 current-status.md
3. 阅读 handoff.md
4. 阅读当前主题对应 PLAN-*.md（复杂任务必须具备正式 PLAN 或等价执行依据）
5. 阅读 product-positioning.md
6. 根据角色阅读对应 guide，并按 docs/guides/five-role-vibe-coding-framework.md 的“30 秒分流卡”判断角色分流、接力与并行
7. 先确认任务是否符合“园区能源管理系统”方向
8. 先分析，再修改
9. 修改后做最小验证
10. 按轻量 / 标准 / 重量三级规则决定是否写回 current-status.md / handoff.md / PLAN
11. 每天任务结束后，将状态快照与交接快照归档到 docs/plans/daily/YYYY-MM/
12. 主题完成后，执行一次“是否收口 / 是否归档 / 是否切换下一个主主题”的判断

修改原则

通用原则

• 优先最小修复
• 优先局部收敛
• 优先保留现有结构
• 不为“顺手优化”扩大改动范围
• 修改必须说明原因、影响范围、验证结果
• 优先保留底座、迁移定位，不在没有计划的情况下继续强化煤矿专属叙事

文档优先

如果角色之间需要传递上下文，不依赖聊天记录，统一通过以下文件同步：

• docs/plans/current-status.md
• docs/plans/handoff.md

历史总结、已完成计划、已合并来源和删除候选，统一查看：

• docs/archive/README.md

主区维护纪律：

• docs/plans/current-status.md 和 docs/plans/handoff.md 主区任意时刻只允许服务一个当前主主题
• current-status.md 只维护当前主主题状态，不保留按天累积的历史块
• handoff.md 只维护当前仍有行动价值的交接，不承担长期存史职责
• 每天任务结束后，必须将当天状态与交接快照归档到 docs/plans/daily/YYYY-MM/
• 长期追溯优先查看 docs/plans/daily/ 与 docs/archive/plans/
• 无接力、无边界变化、无主题变化，不动主区
• 前后端并行前，必须先有单一契约载体

默认文档分级：

• 轻量轮：单角色即可闭环的小修复，通常不动主区
• 标准轮：需要角色接力，至少维护 current-status.md 与 handoff.md
• 重量轮：新主题、多轮推进、复杂契约或连续打回升级，必须建立或更新 PLAN-*.md

脚本整理与维护规则

• 前端原生命令保留在 frontend/package.json，不要把仓库级运维或初始化命令塞进去
• 仓库级脚本统一落在 scripts/；bin/ 只保留少量高频快捷入口
• 正式脚本、调试脚本、一次性历史脚本必须区分，不要混作同一层入口
• 调整脚本路径或入口前，先检查 README.md、docs/、scripts/README.md、bin/README.md 中的引用
• 一次性历史脚本优先归档，不直接删除；是否清理由后续人工确认

输出格式要求

每次任务结束时，至少补充以下内容：

1. 本次目标
2. 发现的问题
3. 修改文件
4. 验证结果
5. 剩余风险
6. 需要交接给谁

当前项目特别要求

前端特别要求

• 优先排查事件绑定、disabled 条件、状态更新链路、路由跳转、接口响应后 UI 刷新
• 优先明确“按钮点了没反应”发生在哪一层：组件层 / 状态层 / 路由层 / 接口层

后端特别要求

• 优先确认接口权限、返回结构、字段命名、空值处理、异常状态码
• 尽量保持接口兼容，避免无必要 breaking change

推荐命令（按你的项目自行补全）

前端

• 安装依赖：cd frontend && npm install
• 本地启动：cd frontend && npm run dev
• 构建验证：cd frontend && npm run build
• 代码检查：cd frontend && npm run lint

后端

• 启动服务：uvicorn app.main:app --reload
• 测试命令：pytest
• 其他检查：根据项目实际补充

交接规则

探索 -> 前端

需要明确：

• 问题页面
• 涉及组件
• 事件入口
• 初步根因
• 建议最小修复路径

前端 -> 后端

需要明确：

• 哪个接口有问题
• 请求路径
• 请求参数
• 返回状态码 / 返回结构
• 前端依赖什么结果

后端 -> 前端

需要明确：

• 改了哪个接口
• 是否影响旧逻辑
• 前端需要如何联调