复现已有算法

2026-07-14 15:43:18 +08:00
parent abebd2a683
commit 50b8111fd9
860 changed files with 182250 additions and 18 deletions
@@ -0,0 +1,31 @@
 ---
 name: analyze-questions
 description: 问题分析规范。用于当用户使用疑问句提问时，约束模型行为：优先分析问题并给出解答或排查思路，不要直接进行自动解决或修改代码。
 ---
 # 问题分析规范
 当用户的提问是疑问句（例如："为什么..."、"是什么..."、"怎么排查..."、"这个命令的作用是？"等）时，这通常意味着用户正在进行探索、学习、调试或排查，他们更需要理解现象和背后的原理，而不是立刻执行修改。
 为了提供更好的交互体验，请严格遵守以下行为准则：
 ## 1. 优先只读与收集信息
 - 可以并且鼓励使用**只读工具**（如 `view_file`, `grep_search`, `list_dir`，以及通过 `run_command` 执行 `cat`、`ls`、查看日志或状态的命令）来获取上下文和现场信息。
 - 在收集到充分信息后，进行逻辑分析。
 ## 2. 深入分析与耐心解答
 - 基于收集到的信息，直接回答用户的疑问，指出问题所在、原因、或者代码/命令的实际作用。
 - 保证解答的逻辑清晰，让用户能够理解你的推导过程。
 ## 3. 严禁自动修改或“自作主张”
 - **绝对不要**直接调用修改文件的工具（如 `write_to_file`, `multi_replace_file_content`, `replace_file_content`）。
 - **绝对不要**通过 `run_command` 自动执行具有副作用的命令（如安装依赖、修改配置、重启服务、删除文件等）。
 - 即使你已经找到了问题的解决方案，也不要“自作主张”地直接实施。
 ## 4. 提供建议并等待确认
 - 在解答完疑问后，你可以提供解决该问题的候选方案或建议（例如：“如果您希望修复此问题，我建议修改文件 X 的 Y 行”或“您可以执行以下命令：...”）。
 - 最后，必须将控制权交还给用户，询问用户：“您希望我帮您进行这些修改吗？”或者“是否需要我帮您执行？”。只有在用户给予明确的指令（如“好的”、“修改吧”、“执行”）后，才能进行实际的操作。
@@ -0,0 +1,84 @@
 ---
 name: backend-conventions
 description: 后端 C++ 规范。用于修改本仓库后端接口、Controller、Manager、配置文件与接口文档时，统一 JSON 处理、字段命名、响应结构与文档同步要求。
 ---
 # 后端规范
 ## JSON 规则
 - 统一使用 `nlohmann/json`
 - 在实现文件中统一写：`using json = nlohmann::json;`
 - 禁止新增 `jsoncpp` 依赖
 - 解析请求体时必须处理非法 JSON 分支
 ## Drogon 响应构建
 - 优先复用 `ResponseUtil`，避免每个接口自行拼装响应
 - 明确设置 `Content-Type: application/json`
 - 可预期失败走业务错误响应，不直接向前端暴露底层异常细节
 示例：
 ```cpp
 auto resp = HttpResponse::newHttpResponse();
 resp->setContentTypeCode(CT_APPLICATION_JSON);
 resp->setStatusCode(k200OK);
 resp->setBody(ResponseUtil::GenerateSuccessResponse(data).dump());
 callback(resp);
 ```
 ## 字段命名
 - 请求体、响应体、配置文件统一 `snake_case`
 - 禁止在 JSON 中混用 `camelCase`
 ## 响应约定
 - 响应结构和状态码语义以当前模块现状为准（不要凭空定义新格式）
 - 错误码与错误文案保持稳定，避免前后端契约漂移
 ## 日志与错误信息
 - 先复用同模块既有日志前缀和措辞
 - 对外错误信息默认中文（除非该接口已约定英文）
 - 不要无故把已有中文日志改成英文
 ## 文档同步
 - 改后端接口时，必须同步更新该模块 `docs/接口文档.md`
 - 若前端有 API 封装，同提交同步更新封装层
 - 新增接口时补齐：路径、方法、参数、成功/失败示例
 - **每次新增或修改协议时，必须同步更新 `collector/docs/协议支持清单.md` 文档**
 - **每次新增协议或修改协议细节时，必须在 `collector/docs/protocols/` 下新增或更新对应的协议实现文档，并且文档内强制要求写入底层依赖库来源及其具体安装/编译方式**
 ## 协议开发规范
 - **新增协议驱动时，严禁在应用层类中直接调用底层的原生 API（如原生 Socket API、原生串口操作函数等），除非有特殊需求需要和我确认。**
 - **必须注入并使用通用的公共类进行通信，例如：**
  - TCP 连接使用 `TcpTransport`
  - UDP 连接使用 `UdpTransport`
  - 串口连接使用 `SerialTransport`
  - 这些类均应继承自核心抽象接口 `ITransport`。
 ## 协议配置规范
 > 详细规则参见 `collector/docs/协议支持清单.md` 的"更新规范"章节。
 ### protocol_name
 - 全大写 + 下划线：`MODBUS_TCP`、`FINS_TCP`
 - 同一协议不同连接方式**拆分为独立条目**，后缀：`_TCP`/`_RTU`/`_SERIAL`/`_OVERTCP`
 - 驱动注册标识必须与 `protocol_name` 完全一致
 ### brand
 - 有品牌协议：使用品牌原名，不附加连接方式或描述
 - 通用协议（Modbus/OPC UA）：使用标准协议名
 - 无品牌行业标准：使用**应用领域**（如 `"电力仪表"`, `"水气仪表"`），避免与 protocol_name 重复
 - ✅ `"西门子"`, `"电力仪表"` / ❌ `"哈斯串口"`, `"IEC104"`（与 protocol_name 冗余）
 ### connection_type
 - 每个协议条目只允许一种 `connection_type`（`"ethernet"` 或 `"serial"`）
 - 需要同时支持串口和以太网时，新增独立协议条目
@@ -0,0 +1,62 @@
 ---
 name: cloud-deploy-verify
 description: 云平台部署与验证流程。用于用户说“部署云平台”“用 deploy_cloud.sh 部署”“部署到云服务器”“云端部署并验证”“发布云平台前端/后端”等场景，默认使用 deploy_cloud.sh 部署到 ubuntu@119.45.4.75 并验证 cloud-server 与关键接口。
 ---
 # 云平台部署与验证
 ## 何时使用
 - 部署云平台
 - 用 `deploy_cloud.sh` 部署
 - 部署到云服务器
 - 云端部署并验证
 - 发布云平台前端或后端
 ## 固定约定
 - 部署脚本：`./deploy_cloud.sh`
 - 默认目标：`ubuntu@119.45.4.75`
 - 默认云平台地址：`http://119.45.4.75`
 - systemd 服务：`cloud-server`
 - 默认不要加 `--init`；只有用户明确要求初始化、清库、重置云端状态时才使用 `--init`
 ## 执行流程
 1. 在仓库根目录执行部署：
 ```bash
 ./deploy_cloud.sh
 ```
 2. 确认脚本完成并输出：
 ```text
 [OK] cloud-server is running
 ```
 3. 验证远端服务状态：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo systemctl is-active cloud-server'
 ```
 4. 验证云平台登录与关键接口：
   - 登录接口：`POST http://119.45.4.75/api/auth/login`
   - OTA 包列表：`GET http://119.45.4.75/api/admin/edge-upgrades/packages`
   - 如果本次改动涉及 OTA 包字段，确认响应包含预期字段，例如 `release_type`、`description`、`release_notes`
 5. 如果本次改动影响边缘侧 OTA 查询，再验证边缘侧代理透传：
   - 先登录边缘侧，例如 87：`POST http://192.168.40.87/api/login`
   - 再调用：`POST http://192.168.40.87/api/ota/cloud/packages`
   - 确认云端字段能透传到边缘侧响应
 ## 注意
 - `deploy_cloud.sh` 会构建云端前端和 `cloud_server`，同步 `runtime/cloud_server/`，迁移/校验 Mosquitto Dynamic Security，并重启 `cloud-server`。
 - 不要手写云端 rsync/scp/systemctl 流程，优先使用 `deploy_cloud.sh`。
 - 如果部署失败，先看脚本输出；服务启动失败再查：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo journalctl -u cloud-server --since "5 min ago" --no-pager'
 ```
@@ -0,0 +1,3 @@
 display_name: 云平台部署验证
 short_description: 使用 deploy_cloud.sh 部署云平台并验证关键接口
 default_prompt: Use this skill when the user asks to deploy the cloud platform, deploy to the cloud server, run deploy_cloud.sh, or verify a cloud frontend/backend release. From the repo root, run ./deploy_cloud.sh by default, targeting ubuntu@119.45.4.75. Do not pass --init unless explicitly requested. After deployment, verify cloud-server is running, test /api/auth/login and relevant cloud APIs, and if OTA package fields changed, also verify the 87 edge proxy /api/ota/cloud/packages returns those fields.
@@ -0,0 +1,120 @@
 ---
 name: cloud-public-deploy
 description: edge_collector 云平台公网部署流程规范。用于整理、审查或执行云平台公网部署方案时参考 deploy_cloud.sh，覆盖 package.sh --cloud-only、runtime/cloud_server 同步、远端配置保护、Mosquitto Dynamic Security、systemd/nginx 初始化、cloud-server 重启和公网接口验证。
 ---
 # 云平台公网部署
 ## 固定约定
 - 部署脚本：`./deploy_cloud.sh`
 - 默认目标：`ubuntu@119.45.4.75`
 - 远端目录：`~/cloud_server`
 - systemd 服务：`cloud-server`
 - 公网入口：`http://119.45.4.75`
 - 本地构建输出：`runtime/cloud_server/`
 ## 使用边界
 - 常规部署使用 `./deploy_cloud.sh`。
 - 只看流程或生成文档时可以参考本 skill，不直接执行。
 - 只有用户明确要求“初始化、清库、重置云端状态”时才允许加 `--init`。
 - 不要手写 rsync、scp、systemctl 流程替代 `deploy_cloud.sh`。
 ## deploy_cloud.sh 实际流程
 ```text
 1. bash ./package.sh --cloud-only
 2. 校验 runtime/cloud_server 和 cloud_server/config/server_config.json
 3. 读取 MQTT dynsec、PostgreSQL、TDengine 配置
 4. 检查 SSH 连通性
 5. 备份远端 server_config.json 和 ai_config.json
 6. rsync runtime/cloud_server/ 到 ~/cloud_server/
 7. 恢复/生成远端运行密钥，保留远端 AI 配置
 8. 迁移并校验 Mosquitto Dynamic Security
 9. --init 模式下安装 systemd 服务和 nginx
 10. 重启 cloud-server 并输出公网 URL
 ```
 ## 运行配置保护
 部署脚本会保护：
 - `~/cloud_server/config/server_config.json` 中的 `jwt_secret`。
 - `custom_config.terminal.credential_key`。
 - `~/cloud_server/config/ai_config.json`。
 审查或修改部署逻辑时，必须确认这些运行态配置不会被打包产物覆盖。
 ## MQTT Dynamic Security
 脚本会根据 `server_config.json` 配置：
 - 禁用旧的 Mosquitto 静态账号/ACL 配置。
 - 初始化或更新 `/var/lib/mosquitto/dynamic-security.json`。
 - 创建 gateway/cloud 角色和 cloud MQTT client。
 - 设置 `/data/#`、`/status/#`、`/ack/#`、`/cmd/#` 相关权限。
 如果部署失败，先查 `mosquitto_ctrl`、`mosquitto_dynamic_security.so` 和 Mosquitto 服务状态。
 ## 初始化模式
 `--init` 会执行高风险动作：
 - 停止 `cloud-server` 和 `mosquitto`。
 - 重置 PostgreSQL 数据库。
 - 重置 TDengine 数据库。
 - 清理 MQTT dynsec 状态。
 - 安装/覆盖 systemd service。
 - 配置 nginx 80 端口反代到 8081，443 自签名证书重定向到 HTTP。
 未获用户明确确认时禁止使用 `--init`。
 ## 验证步骤
 部署完成后至少验证：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo systemctl is-active cloud-server'
 ssh ubuntu@119.45.4.75 'sudo systemctl is-active mosquitto'
 curl -s http://119.45.4.75/api/health
 ```
 按改动范围补充：
 - 登录接口：`POST /api/auth/login`
 - AI 配置/分析接口。
 - OTA 包列表接口。
 - MQTT 网关连接和设备在线状态。
 - 前端页面静态资源是否刷新。
 ## 故障排查
 服务启动失败：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo journalctl -u cloud-server --since "10 min ago" --no-pager'
 ```
 nginx 异常：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo nginx -t && sudo systemctl status nginx --no-pager'
 ```
 MQTT dynsec 异常：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo systemctl status mosquitto --no-pager'
 ```
 ## 文档输出
 整理公网部署文档时必须写清：
 - 目标主机和远端目录。
 - 是否使用 `--init`。
 - 会保留哪些远端配置。
 - 会重启哪些服务。
 - 公网访问入口和验证接口。
 - 回滚方式和日志位置。
@@ -0,0 +1,57 @@
 ---
 name: cpp-coding-style
 description: C/C++ 代码风格规范。用于本仓库 C/C++ 新增、修改、重构时，统一格式、命名、include 顺序和现代 C++ 用法。
 ---
 # C/C++ 风格规范
 ## 基础约束
 - 使用 `C++17`
 - 4 空格缩进
 - 大括号使用 K&R 风格
 - 单行长度尽量不超过 100
 ## 命名规则
 - 类型（`class/struct/enum`）：`PascalCase`
 - 函数/方法：`PascalCase`
 - 普通变量：`snake_case`
 - 成员变量：`snake_case_`
 - 常量：`kPascalCase`
 - 宏：`ALL_CAPS`
 - 命名空间：小写
 ## include 顺序
 1. 对应头文件
 2. C 系统头
 3. C++ 标准库
 4. 第三方库
 5. 项目内头文件
 组间空一行。
 ## 代码习惯
 - 单行 `if/for/while` 也加大括号
 - 不使用 `using namespace std;`
 - 优先 `constexpr`、`[[nodiscard]]`、RAII
 - 优先 `static_cast`，避免 C 风格强转
 - `auto` 只在不降低可读性时使用
 ## 注释与日志
 - 注释优先说明"为什么"，不是"做了什么"
 - 保留高价值中文注释，不随手删除
 - 强制包含 `#include "logger/Logger.hpp"`（或其相对路径）
 - **统一使用流式日志宏**：`LOG_DEBUGS()`、`LOG_INFOS()`、`LOG_WARNS()`、`LOG_ERRORS()`，通过 `<<` 拼接内容。严禁使用 `std::cerr`/`std::cout`、第三方日志原生接口或混用其他宏。
  ```cpp
  // 正确：流式
  LOG_ERRORS() << "SerialTransport: 无法打开串口 " << port_ << ": " << strerror(errno);
  // 错误：传参格式
  LOG_ERRORS("SerialTransport: 无法打开串口 {}: {}", port_, strerror(errno));
  // 错误：原生输出
  std::cerr << "SerialTransport: 无法打开串口" << std::endl;
  ```
 - 日志风格沿用同模块既有前缀和语气
@@ -0,0 +1,48 @@
 ---
 name: edge-82-release
 description: 82主机发布流程。用于用户说“去82主机编译”“去82主机编译代码”“去82发布xxx版本”“发布并上传版本”时，默认到 192.168.40.82 的 /home/cat/code/edge_collector 执行 git pull 与打包；发布并上传时再把产物上传到云平台 admin 账号。
 ---
 # 82 主机发布流程
 ## 何时使用
 - 去82主机编译代码
 - 去82主机编译
 - 去82发布 xxx 版本
 - 发布并上传版本
 ## 固定环境
 - 主机：`cat@192.168.40.82`
 - 代码根目录：`/home/cat/code/edge_collector`
 - 构建目标：`arm64`
 - 云平台：`http://119.45.4.75:8081`
 - 云端账号：`admin`
 ## 执行顺序
 1. 去82主机编译代码
   - `cd /home/cat/code/edge_collector`
   - `git pull`
   - `./package.sh --edge`
 2. 去82发布 xxx 版本
   - `cd /home/cat/code/edge_collector`
   - `git pull`
   - `./package.sh --publish --version xxx`
 3. 发布并上传版本
   - 先按“去82发布 xxx 版本”执行
   - 再把 `publish/edge_<version>_arm64.tar.gz` 上传到云平台
   - 使用云平台默认 `admin` 账号登录
 ## 上传字段
 - `file`
 - `package_type=edge`
 - `version=<版本号>`
 - `target_arch=arm64`
 - `release_type=stable`
 - `visibility=platform`
 - `enabled=true`
@@ -0,0 +1,3 @@
 display_name: 82发布流程
 short_description: 82主机编译、发布和上传规则
 default_prompt: Use this skill when the user asks "去82主机编译", "去82主机编译代码", or asks to publish/publish-and-upload from host 82. For compile requests, go to /home/cat/code/edge_collector on 192.168.40.82, run git pull first, then run ./package.sh --edge. For publish requests, run ./package.sh --publish --version <version>. Upload to the cloud admin account only when the user explicitly asks to publish and upload.
@@ -0,0 +1,91 @@
 ---
 name: edge-bug-lessons
 description: edge_collector Bug 经验库沉淀规范。用于用户要求 bug 教训、故障复盘、为什么流出、总结经验、沉淀规则时，把边缘侧、云平台、协议采集、部署同步、前端、AI、网络等问题整理为可检索的历史 lesson 和预防规则。
 ---
 # edge_collector Bug 经验库
 ## 目标
 把一次故障从“修好了”沉淀为“以后能提前拦住”。重点记录根因链路、漏检点、验证方式和反哺动作。
 ## 触发场景
 - “总结这次 bug”
 - “为什么会流出”
 - “写一个复盘”
 - “沉淀经验”
 - “以后怎么避免”
 - 修复完成后需要补长期规则
 ## 默认落点
 ```text
 docs/bugfix/BugLesson-YYYYMMDD-简述.md
 docs/bugfix/BugLesson-index.md
 ```
 如果已有更合适的专题目录，可放到：
 - `docs/鲁班猫*/`
 - `collector/docs/protocols/`
 - `docs/ops/`
 但索引仍建议保留在 `docs/bugfix/BugLesson-index.md`。
 ## Lesson 结构
 ```markdown
 # 标题
 **日期**:
 **模块**:
 **影响范围**:
 ## 1. 问题现象
 ## 2. 根因链路
 ## 3. 流出路径 / 漏检点
 ## 4. 修复内容
 ## 5. 验证结果
 ## 6. 本可在哪一步拦住
 ## 7. 预防措施
 ## 8. 可复用规则
 ## 9. 反哺动作
 ## 10. 相关文件
 ```
 ## 当前项目重点
 优先沉淀以下类型：
 - 打包或同步覆盖运行态动态配置。
 - 97/94/82 等主机系统差异导致运行异常。
 - FANUC/西门子协议库、架构、链接方式问题。
 - 前端白屏、按钮无反馈、错误提示过泛。
 - AI 分析超时、空内容、内部配置泄露。
 - WiFi/4G/frpc/端口转发独立 agent 异常。
 - 云端设备在线状态、历史趋势、数据不连续误判。
 ## 写法要求
 - 区分“已确认事实”和“推断”。
 - 根因必须落到文件、配置、命令、日志或环境差异。
 - 不写“加强测试”这类空话，要写可执行拦截点。
 - 反哺动作要明确更新哪个 skill、测试清单、文档或脚本检查项。
 - 涉及密钥、密码、Token 时必须脱敏。
 ## 索引格式
 ```markdown
 | 日期 | 标题 | 模块 | 核心根因 | 漏检点 | 预防规则 | 文件 |
 |------|------|------|----------|--------|----------|------|
 ```
@@ -0,0 +1,86 @@
 ---
 name: edge-bugfix
 description: edge_collector 缺陷排查与根因修复流程。用于用户报告边缘侧、云平台、协议采集、前端白屏、部署同步、远程主机 CPU/内存异常、脚本失败、接口失败等 Bug 或异常时，按读取证据、根因定位、最小修复、定向验证和报告沉淀推进。
 ---
 # edge_collector Bug 修复流程
 ## 适用范围
 - 边缘服务：`collector`、`configurator`、`edge` systemd 服务。
 - 云平台：`cloud_server`、`frontend/cloud_app`、`deploy_cloud.sh`。
 - 前端：`frontend/config_app`、`frontend/cloud_app`。
 - 协议采集：FANUC、西门子、Modbus、OPC UA、传感器等。
 - 脚本/部署：`scripts/`、`package.sh`、`scripts/migrate_edge.sh`。
 - 远程主机：82/87/94/97、云服务器 `119.45.4.75`。
 ## 核心原则
 1. 先只读取证据，后修改。
 2. 必须定位根因，禁止只修表面症状。
 3. 不回滚用户改动，不清空运行配置。
 4. 涉及远程同步默认使用既有项目脚本，不手写替代流程。
 5. 修改后必须给出定向验证命令和关键结果。
 ## 排查流程
 ### 1. 收集现场
 按问题类型优先读取：
 - Git 状态：`git status --short`
 - 相关日志：`logs/`、`journalctl -u edge`、`journalctl -u cloud-server`
 - 配置：`runtime/edge/config/`、`collector/config/`、`configurator/config/`
 - 前端：浏览器错误、接口响应、构建产物、路由
 - 远程主机：`uptime`、`free -h`、`df -h`、`systemctl status`
 远程数字主机遵循 `host-connection-defaults`；边缘同步遵循 `edge-sync-host`。
 ### 2. 定位根因
 优先沿真实链路追踪：
 ```text
 用户现象
  -> 前端页面 / API
  -> configurator 或 cloud_server
  -> collector / agent / 脚本
  -> 配置文件 / SQLite / 网络 / systemd
 ```
 典型链路：
 - 前端白屏：CSS -> DOM -> JS -> API -> 构建产物。
 - 云端接口失败：前端代理 -> cloud_server 路由 -> 数据库/外部服务。
 - 采集异常：设备配置 -> DriverRegistry -> 驱动日志 -> 协议依赖库。
 - 同步后异常：构建主机架构 -> 打包产物 -> runtime 配置排除 -> systemd 重启。
 ### 3. 修复策略
 - 小范围修改，不做无关重构。
 - C++ 遵循 `cpp-coding-style`。
 - 后端接口/配置遵循 `backend-conventions`。
 - 前端遵循 `frontend-ui-conventions`、`frontend-debug`、`frontend-dialog`。
 - Shell 遵循 `shell-scripting`。
 - 第三方库遵循 `third-party-libs`。
 ### 4. 验证要求
 按改动选择最小但可信的验证：
 - JSON 配置：`jq empty <file>`
 - C++ collector：`cmake --build build --target collector -j2`
 - configurator/cloud_server：对应 target 或项目测试脚本。
 - 前端：能运行 npm 的环境执行 `npm run build`。
 - 边缘打包：`./package.sh --edge-only`
 - 远程部署：按用户明确要求再同步/重启。
 ### 5. 报告沉淀
 复杂 Bug 或远程事故修复后，在 `docs/` 下写简短报告，建议位置：
 - 远程主机/设备类：`docs/鲁班猫*/`
 - 协议类：`collector/docs/protocols/`
 - 通用事故：`docs/`
 报告至少包含：现象、根因、修复、验证、后续预防。
@@ -0,0 +1,54 @@
 ---
 name: edge-business-rule-extractor
 description: edge_collector 业务与技术规则提取规范。用于从用户需求、讨论、故障复盘和实现方案中提取稳定规则，维护云边采集、上传策略、动态配置保护、权限、前端交互、部署同步和协议模板等项目规则。
 ---
 # edge_collector 规则提取
 ## 适用场景
 - 用户反复强调某个约束。
 - 某个事故暴露出需要长期遵守的规则。
 - 方案中出现“必须、不能、只允许、默认、除非明确要求”等表述。
 - 需要把对话中的口头规范沉淀到文档或 skill。
 ## 规则类型
 - `BR-COLLECT`：采集与上传规则。
 - `BR-CONFIG`：配置和动态文件保护规则。
 - `BR-DEPLOY`：打包、同步、部署规则。
 - `BR-UI`：前端交互和用户可见文案规则。
 - `BR-PERM`：权限和安全规则。
 - `BR-PROTOCOL`：协议模板和驱动规则。
 - `BR-AI`：AI 分析和模型配置规则。
 ## 当前项目典型规则
 - 相同数据不上传，5 分钟强制上传；短时间点位不连续可能是正常现象。
 - 打包或同步不能携带目标主机运行态动态配置。
 - 同主机编译部署也要使用 `scripts/migrate_edge.sh`。
 - `install_all.sh` 只有用户明确要求时才执行。
 - 用户可见协议介绍不透露 helper、SDK、库路径等技术细节。
 - AI 分析报告不展示内部 AI 配置名、Provider 名称或模型细节。
 ## 输出格式
 ```markdown
 | 编号 | 类型 | 规则 | 来源 | 影响范围 | 验证方式 |
 |------|------|------|------|----------|----------|
 | BR-DEPLOY-001 | 部署 | ... | 用户确认 | package/sync | ... |
 ```
 ## 执行流程
 1. 从需求、对话或文档中提取候选规则。
 2. 去重，避免把同一规则写成多个版本。
 3. 判断规则是否长期有效，临时现场处理不沉淀为规则。
 4. 写明影响范围和验证方式。
 5. 如需落盘，优先更新 `docs/` 下已有规则/概览文档；没有则建议新增规则表。
 ## 注意
 - 不把猜测写成规则。
 - 不把一次性临时命令写成规则。
 - 规则变更会影响部署或运行安全时，先让用户确认。
@@ -0,0 +1,70 @@
 ---
 name: edge-code-review
 description: edge_collector 代码评审流程。用于用户要求 review、代码审查、提交前检查、质量审核时，按严重程度输出问题，覆盖 C++ 采集驱动、Drogon 接口、React 前端、脚本、打包部署、运行配置和测试缺口。
 ---
 # edge_collector 代码评审
 ## 输出规则
 评审必须 findings first：
 1. 先列问题，按严重程度排序。
 2. 每条问题包含文件与行号。
 3. 没有问题时明确说明，并列出剩余风险或测试缺口。
 4. 摘要放在问题之后。
 ## 评审维度
 ### C++/采集端
 - 是否破坏 `DriverRegistry` 注册名与协议配置一致性。
 - 是否错误链接第三方库或跨架构库。
 - 是否直接调用原生通信 API，绕过 `TcpTransport`/`UdpTransport`/`SerialTransport`。
 - 是否遵循 `PointData::UpdateValue` 类型约束。
 - 是否使用流式日志宏。
 - 是否存在线程、生命周期、子进程回收、fd 泄漏风险。
 ### 后端接口
 - JSON 字段是否 `snake_case`。
 - 是否处理非法 JSON。
 - 是否复用 `ResponseUtil`。
 - 错误响应是否稳定且不暴露底层敏感细节。
 - 配置写入是否会覆盖运行态动态配置。
 ### 前端
 - 是否复用现有组件。
 - 是否符合 CSS Modules 和暗色主题。
 - 弹窗是否使用统一对话框，不用原生 alert/confirm/prompt。
 - 交互失败是否给出清晰反馈。
 - 移动/窄屏是否溢出或遮挡。
 ### 脚本与部署
 - 是否使用 `set -euo pipefail`。
 - 路径是否从脚本位置推导。
 - 是否误覆盖 `runtime/edge/config` 中动态配置。
 - 同步部署是否遵循 `scripts/migrate_edge.sh`。
 - 新增常驻服务是否独立，不耦合 edge 主服务。
 ### 测试与验证
 - 是否有定向单元测试或脚本验证。
 - 协议改动是否更新协议文档。
 - 前端改动是否能构建或说明未构建原因。
 - 远程问题是否给出服务状态或接口验证。
 ## 高风险信号
 命中以下内容需重点审查：
 - `collector/CMakeLists.txt`
 - `package.sh`、`scripts/migrate_edge.sh`
 - `collector/src/driver/`
 - `configurator/config/*.json`
 - `runtime/`、`data/`、动态配置文件处理
 - systemd 安装脚本
 - 远程同步/重启逻辑
@@ -0,0 +1,84 @@
 ---
 name: edge-codex-automation
 description: edge_collector Codex 自动化任务建设规范。用于新增、修改或评审自动化任务、定时检查、自动部署验证、远程主机巡检、日志汇总、报告生成等流程时，明确执行边界、调度来源、脚本位置、通知、手工验证和安全限制。
 ---
 # edge_collector Codex 自动化
 ## 适用场景
 - 定时检查云平台或边缘主机状态。
 - 自动生成巡检报告。
 - 自动构建或验证，但不自动发布。
 - 自动拉取日志、磁盘、CPU、内存信息。
 - 自动检查 docs、skills、配置格式。
 ## 设计原则
 - 自动化只能做边界清晰、可回滚、可验证的任务。
 - 涉及部署、重启、清库、删除、覆盖配置时必须有人确认。
 - 自动化脚本要独立，不能和 `edge` 主服务强耦合。
 - 运行日志必须可追溯。
 - 失败要有明确提示和下一步处理建议。
 ## 建设流程
 1. 明确目标：
   - 自动化要解决什么问题。
   - 成功标准和失败标准。
   - 运行在哪台主机、哪个目录。
 2. 明确调度：
   - 一次性、定时还是手动触发。
   - cron、systemd timer、CI 或其他调度器。
   - 时区和执行频率。
 3. 明确权限：
   - 是否需要 SSH。
   - 是否需要 sudo。
   - 是否会修改远程状态。
   - 是否访问密钥或配置文件。
 4. 落地脚本：
   - 脚本放到 `scripts/` 或 `.agents/` 约定目录。
   - Shell 遵循 `shell-scripting`。
   - Python 脚本保持独立、参数清晰、日志明确。
 5. 手工验证一次：
   - 先 `--dry-run` 或只读模式。
   - 再执行真实任务。
   - 检查退出码、日志、输出文件。
 ## 当前项目自动化边界
 允许默认自动化：
 - 只读巡检。
 - 构建验证。
 - 文档/skill 校验。
 - 日志采集和摘要。
 - 接口健康检查。
 必须确认后才执行：
 - `deploy_cloud.sh`
 - `scripts/migrate_edge.sh`
 - `install_all.sh`
 - systemd restart/stop。
 - 数据库写入、清理、重置。
 - 删除文件、清理 `/tmp`、覆盖运行配置。
 ## 输出格式
 ```text
 自动化任务：
 - 名称：
 - 目标：
 - 执行脚本：
 - 调度方式：
 - 运行主机：
 - 权限需求：
 - 日志位置：
 - 手工验证：
 - 风险：
 ```
@@ -0,0 +1,96 @@
 ---
 name: edge-config-lifecycle
 description: edge_collector 配置生命周期管理规范。用于新增、修改、打包、同步、动态生成或排除配置文件时，明确默认配置、运行态配置、用户保存配置、密钥配置、迁移保留、备份恢复和前端保存行为，防止覆盖现场配置。
 ---
 # edge_collector 配置生命周期
 ## 适用配置
 - 边缘运行配置：`runtime/edge/config/`
 - 云端运行配置：`~/cloud_server/config/`
 - AI 配置：`ai_config.json`
 - 端口转发：`port_forward.json`
 - frpc/内网穿透配置。
 - 协议设备配置。
 - WiFi/4G 辅助配置。
 - 默认模板：`configurator/config/templates/`
 - 用户可见协议描述：`configurator/config/protocols/`
 ## 配置分类
 ### 默认配置
 随代码发布，提供初始结构和默认值。
 ### 运行态配置
 目标主机运行后由用户、前端或服务生成。打包和同步不能覆盖。
 ### 密钥配置
 包含 key、secret、password、token。必须脱敏、禁止提交真实值。
 ### 模板配置
 协议模板、默认点位、用户可选参数。可随版本更新，但要考虑兼容已有设备。
 ## 新增配置文件检查
 新增配置时必须回答：
 - 默认文件放在哪里。
 - 运行态文件放在哪里。
 - 如果文件不存在，谁负责动态生成。
 - 打包是否包含。
 - 同步是否排除。
 - 前端保存是否会覆盖其他字段。
 - 是否包含密钥。
 - 是否需要备份和迁移。
 ## 打包与同步
 修改以下脚本时必须检查配置影响：
 - `package.sh`
 - `scripts/migrate_edge.sh`
 - `deploy_cloud.sh`
 - `scripts/install_all.sh`
 原则：
 - 默认配置可以进入包。
 - 运行态配置不能被 `--delete` 同步清掉。
 - 远端已有密钥配置必须保留。
 - 删除配置文件前必须确认是否会自动再生成。
 ## 前端保存
 - 保存配置时只更新相关字段。
 - 不要用空对象覆盖整个配置文件。
 - 保存失败要显示具体原因。
 - 权限不足要按已有权限体系处理。
 ## 验证
 至少验证：
 ```bash
 jq empty <config.json>
 ```
 同步/部署后验证：
 - 目标主机已有配置仍存在。
 - 新增默认配置可生成。
 - 服务重启后能读取配置。
 - 前端读取和保存正常。
 ## 风险信号
 - `rsync --delete`
 - `cp -r config`
 - `cat > config.json`
 - 前端保存整个 JSON。
 - 后端启动时无条件重写配置。
 - 示例配置中出现真实 key。
@@ -0,0 +1,93 @@
 ---
 name: edge-data-quality-analyzer
 description: edge_collector 采集与上传数据质量分析规范。用于分析历史趋势、AI 分析输入、网关/设备/点位数据缺失、断点、不连续、重复值、时间戳异常、上传策略影响、离线缓存重传和云端展示差异，并输出可验证的数据质量结论。
 ---
 # edge_collector 数据质量分析
 ## 适用问题
 - 云平台历史趋势看起来断续。
 - AI 分析使用点数明显少于原始点数。
 - 设备在线但云端显示离线。
 - 点位长时间不变化、重复上传或缺失。
 - 离线缓存重传后数据仍不完整。
 - 用户质疑采集频率、上传策略或降采样结果。
 ## 分析维度
 1. 数据完整性：应有点数、实际点数、缺口时间段。
 2. 时间连续性：相邻时间间隔、断点、乱序、重复时间戳。
 3. 值质量：重复值、常量段、异常突变、空值、类型异常。
 4. 上传策略影响：相同数据不上传、5 分钟强制上传导致的短时不连续。
 5. 降采样影响：原始点数、展示点数、AI 分析点数、是否保留极值。
 6. 云边一致性：边缘本地数据、上传队列、云端历史数据是否一致。
 ## 排查流程
 ### 1. 确认对象
 明确：
 - 网关名称和 ID。
 - 设备名称和 ID。
 - 点位名称和 ID。
 - 时间范围。
 - 页面或接口来源。
 ### 2. 查询链路
 按真实链路分析：
 ```text
 设备采集
  -> collector 点位值
  -> 边缘本地缓存/上传队列
  -> 云端入库
  -> 历史趋势接口
  -> 图表降采样 / AI 分析输入
 ```
 ### 3. 统计指标
 输出至少包含：
 - 原始记录数。
 - 有效记录数。
 - 展示/分析使用记录数。
 - 最大采样间隔。
 - P50/P95 采样间隔。
 - 重复值比例。
 - 缺口时间段 Top N。
 ### 4. 解释结论
 结论必须区分：
 - 正常策略导致：例如相同数据不上传、5 分钟强制上传。
 - 展示降采样导致：图表为了性能减少点数。
 - 采集异常导致：设备离线、驱动读失败、点位配置错误。
 - 上传异常导致：网络断开、离线缓存未重传、云端接口失败。
 ## AI 分析专项
 当分析 AI 输入数据时：
 - 必须带上网关名称、设备名称、点位名称。
 - 必须说明原始点数和用于 AI 分析点数的区别。
 - 深度分析应提高采样点数、异常片段数量和上下文摘要，不只改变提示词。
 - 给 AI 的提示词要说明上传策略：相同数据不上传，5 分钟强制上传，因此短时间不连续可能是正常现象。
 ## 报告格式
 ```markdown
 ## 数据范围
 ## 关键统计
 ## 异常片段
 ## 原因判断
 ## 建议动作
 ```
@@ -0,0 +1,104 @@
 ---
 name: edge-database-ops
 description: edge_collector 数据库查询与安全操作规范。用于查询或排查云平台 PostgreSQL、TDengine、边缘 SQLite/本地数据、历史趋势、网关设备点位、用户权限和 AI 分析数据时，按只读优先、脱敏、备份、写操作确认和结果可追溯执行。
 ---
 # edge_collector 数据库操作
 ## 适用场景
 - 查询云端网关、设备、点位、用户、权限数据。
 - 排查历史趋势、AI 分析输入、设备在线状态。
 - 验证离线缓存、上传结果、配置是否入库。
 - 对比边缘本地数据和云端数据。
 - 需要执行 SQL 修复或清理数据。
 ## 基本原则
 - 默认只读。
 - 写操作必须用户明确确认。
 - 生产或云端写操作前必须说明影响范围和回滚方案。
 - 查询结果默认脱敏。
 - 不在回复中输出数据库密码、Token、Key。
 ## 先确认环境
 执行前确认：
 - 目标：本机、边缘主机、云服务器。
 - 数据库类型：PostgreSQL、TDengine、SQLite 或文件型数据。
 - 数据库来源：配置文件、服务环境变量、用户提供。
 - 操作类型：查询、导出、修复、删除。
 优先读取配置：
 - `cloud_server/config/server_config.json`
 - `runtime/cloud_server/config/server_config.json`
 - `runtime/edge/config/`
 - 部署脚本和 systemd 环境。
 ## 查询流程
 1. 先定位表和字段来源。
 2. 写出 SQL 或命令。
 3. 只读执行。
 4. 汇总关键结果，不粘贴大量原始数据。
 5. 对涉及用户、密钥、地址的数据脱敏。
 ## 写操作流程
 写操作前必须给用户确认：
 ```text
 将执行：
 - 数据库：
 - 表：
 - 条件：
 - 影响行数预估：
 - 回滚方式：
 ```
 执行前建议备份受影响数据：
 ```sql
 SELECT * FROM <table> WHERE <condition>;
 ```
 必要时导出为临时文件，并说明路径。
 ## 常用只读检查
 PostgreSQL：
 ```sql
 SELECT now();
 SELECT version();
 ```
 TDengine：
 ```sql
 SHOW DATABASES;
 SHOW STABLES;
 ```
 SQLite：
 ```bash
 sqlite3 <db> ".tables"
 sqlite3 <db> "PRAGMA integrity_check;"
 ```
 ## 输出要求
 - 说明数据来源。
 - 说明查询条件和时间范围。
 - 说明结论是事实还是推断。
 - 给出下一步建议。
 ## 禁止事项
 - 未确认就执行 `UPDATE`、`DELETE`、`DROP`、`TRUNCATE`。
 - 把配置中的数据库密码打印到回复。
 - 用线上写操作验证猜测。
 - 将大量敏感原始数据贴到对话中。
@@ -0,0 +1,68 @@
 ---
 name: edge-deployment-writer
 description: edge_collector 部署手册与上线方案编写规范。用于整理边缘侧、云平台、82/97/94/87 主机、runtime 同步、systemd 服务、回滚和验证步骤时，生成可执行部署文档。
 ---
 # edge_collector 部署文档
 ## 固定项目约定
 - 云平台部署优先使用 `deploy_cloud.sh`。
 - 边缘打包使用 `package.sh`。
 - 边缘同步使用 `scripts/migrate_edge.sh`。
 - 用户明确要求执行 `install_all.sh` 时才执行；不要每次同步都运行。
 - 同主机编译部署也要使用 `scripts/migrate_edge.sh`。
 ## 部署文档结构
 ```text
 目标与范围
 目标主机与账号
 前置条件
 构建步骤
 同步/部署步骤
 服务重启步骤
 验证步骤
 回滚方案
 风险与注意事项
 ```
 ## 必须写清
 - 源主机、目标主机、目标目录。
 - 是否会覆盖运行配置。
 - 是否需要重启 `edge`、`cloud-server` 或独立 agent。
 - 是否需要执行 `install_all.sh`。
 - 验证命令和预期输出。
 ## 常用验证
 边缘：
 ```bash
 systemctl is-active edge
 curl -s http://127.0.0.1/api/status
 ```
 云端：
 ```bash
 systemctl is-active cloud-server
 curl -s http://127.0.0.1:<port>/api/health
 ```
 脚本：
 ```bash
 bash -n scripts/<name>.sh
 ```
 ## 回滚说明
 文档必须说明：
 - 上一个 runtime/edge 或发布包位置。
 - 如何恢复二进制和 web 资源。
 - 哪些配置不能回滚覆盖。
 - 回滚后如何重启服务和验证。
@@ -0,0 +1,64 @@
 ---
 name: edge-design-doc-writer
 description: edge_collector 详细设计与方案文档编写规范。用于新增功能、协议适配、AI 功能、边缘 agent、云端功能、前端页面或部署机制前，输出适合本仓库 docs 结构的设计文档、接口草案、数据流、验证计划和实施拆分。
 ---
 # edge_collector 设计文档编写
 ## 适用文档
 - 功能方案设计
 - 详细设计
 - 协议适配方案
 - 本地模型部署方案
 - 云边协同方案
 - 边缘 agent 方案
 - 前端页面方案
 ## 文档落点
 - 通用方案：`docs/`
 - 本地模型：`docs/本地模型/`
 - 鲁班猫专题：`docs/鲁班猫*/`
 - 协议实现：`collector/docs/protocols/`
 - 采集架构：`collector/docs/`
 ## 推荐内容
 ```text
 背景与目标
 现状与问题
 设计原则
 总体架构
 目录与配置
 接口/API
 数据流/状态流
 权限与安全
 实施步骤
 验证计划
 风险与对策
 ```
 ## 本项目必须考虑
 - 边缘侧和云端职责是否清晰。
 - 是否影响 `collector` 采集稳定性。
 - 是否需要新增独立 agent 或 systemd 服务。
 - 是否会覆盖运行时动态配置。
 - 是否需要 82/97/94/87 主机验证。
 - 是否需要 `package.sh` 或 `scripts/migrate_edge.sh` 改动。
 - 是否需要协议模板、用户可见介绍和技术文档分开。
 ## 图示
 流程或状态变化可用 ASCII 图；复杂架构图使用 `edge-svg-diagram`。
 ## 方案验证
 文档结尾必须写：
 - 单元测试或脚本验证。
 - 构建验证。
 - 远程部署验证（如需要）。
 - 回滚或降级策略。
@@ -0,0 +1,91 @@
 ---
 name: edge-design-reviewer
 description: edge_collector 详细设计与方案评审规范。用于评审协议适配、云平台功能、边缘 agent、AI 分析、本地模型、前端页面、部署机制等设计文档，检查结构完整性、边界、接口、配置、数据流、前端可实现性、部署影响、测试和回滚。
 ---
 # edge_collector 设计评审
 ## 评审目标
 确认设计文档足够指导实现、测试和部署，不留下关键歧义。
 ## 结论级别
 - `[严重]`：会导致无法实现、运行风险或数据/配置损坏。
 - `[警告]`：可实现但存在质量、可维护性或验证缺口。
 - `[建议]`：改进项，不阻塞。
 通过标准：无 `[严重]`，关键 `[警告]` 有明确处理计划。
 ## 评审维度
 ### 1. 文档结构
 - 背景、目标、范围、不做什么是否明确。
 - 是否有现状分析和约束。
 - 是否有实施步骤和验证计划。
 - 是否写清假设和待确认项。
 ### 2. 云边职责
 - 边缘侧、云平台、前端、独立 agent 职责是否清晰。
 - 是否把高风险或长耗时任务放到合适进程。
 - 新增常驻进程是否独立，不耦合 `edge` 主服务。
 ### 3. 接口与配置
 - API 路径、方法、请求、响应、错误码是否完整。
 - JSON 字段是否符合当前后端约定。
 - 配置文件路径、默认值、动态生成规则是否明确。
 - 是否会覆盖运行态动态配置。
 ### 4. 数据流与状态流
 - 采集、缓存、上传、云端入库、展示、AI 分析链路是否完整。
 - 状态机是否覆盖成功、失败、超时、重试、停止。
 - 离线、断网、重启、服务异常是否有处理。
 ### 5. 前端可实现性
 - 页面布局、主要状态、按钮反馈、错误提示是否明确。
 - 用户可见文案是否隐藏内部技术细节。
 - 权限、空状态、loading、长内容滚动是否覆盖。
 - 复杂页面是否需要原型或图示。
 ### 6. 部署与运维
 - 是否影响 `package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
 - 是否需要 `install_all.sh`，是否明确执行条件。
 - 是否需要 systemd 服务、日志路径、重启策略。
 - 是否考虑 82/97/94/87 和云服务器差异。
 ### 7. 测试与回滚
 - 是否有单元、构建、接口、前端、设备或远程验证。
 - 是否覆盖异常场景。
 - 是否有回滚或降级策略。
 - 是否能验证“不覆盖运行配置”。
 ## 输出格式
 ```markdown
 ## 评审结论
 通过 / 不通过 / 有条件通过
 ## 问题列表
 | 级别 | 位置 | 问题 | 影响 | 建议 |
 |------|------|------|------|------|
 ## 待确认项
 ## 建议补充验证
 ```
 ## 注意
 - 评审先列问题，再写总结。
 - 文件和行号尽量具体。
 - 不把个人偏好当成缺陷。
 - 如果设计引用官方能力或第三方 SDK，拿不准时要联网查证。
@@ -0,0 +1,68 @@
 ---
 name: edge-doc-coauthoring
 description: edge_collector 文档协作规范。用于编写或更新方案设计、部署说明、协议文档、事故分析、本地模型方案、用户手册等 docs 文档时，帮助确定读者、落点、结构、验证依据和后续实施清单。
 ---
 # edge_collector 文档协作
 ## 文档落点
 - 协议实现：`collector/docs/protocols/`
 - 协议清单：`collector/docs/协议支持清单.md`
 - 边缘/云端通用方案：`docs/`
 - 鲁班猫设备问题：`docs/鲁班猫1/`、`docs/鲁班猫3/`
 - 本地模型方案：`docs/本地模型/`
 - 部署/同步/运维：`docs/` 或 `docs/ops/`
 ## 写作流程
 1. 明确读者：开发、运维、现场用户、管理后台用户。
 2. 明确目标：评估、实施、排障、交付说明、用户操作。
 3. 收集依据：代码路径、配置文件、脚本、远程验证、官方文档链接。
 4. 写清边界：第一版做什么、不做什么、风险和前置条件。
 5. 给出可执行步骤：命令、目录、配置示例、验证方法。
 ## 推荐结构
 技术方案：
 ```text
 背景与目标
 当前现状
 方案设计
 目录/配置/API
 实施步骤
 验证计划
 风险与对策
 参考资料
 ```
 事故分析：
 ```text
 问题现象
 影响范围
 现场证据
 根因分析
 修复方案
 验证结果
 预防措施
 ```
 用户说明：
 ```text
 功能用途
 使用步骤
 参数解释
 常见问题
 注意事项
 ```
 ## 约束
 - 给用户看的协议介绍不透露内部技术细节。
 - 技术方案可写实现细节，但要标注假设和验证状态。
 - 引用外部信息时提供链接。
 - 不把未经验证的能力写成已完成。
@@ -0,0 +1,63 @@
 ---
 name: edge-framework-learner
 description: edge_collector 框架、SDK、协议库和工具链学习沉淀规范。用于需要学习并沉淀 ONNX Runtime、RKNN、FOCAS SDK、Snap7、Drogon、React/Vite、Playwright、交叉编译工具链、AI Provider SDK 等新技术，并生成适合本仓库使用的 skill 或技术笔记。
 ---
 # edge_collector 技术学习沉淀
 ## 适用场景
 - 用户要求“学习某框架并生成 skill”。
 - 新接入第三方 SDK、协议库、AI Provider 或模型推理框架。
 - 当前知识可能过期，需要联网查官方文档。
 - 需要把一次调研变成后续可复用的项目规则。
 ## 信息来源
 优先级：
 1. 官方文档、官方仓库、官方示例。
 2. 当前仓库已有实现和构建脚本。
 3. 设备或 SDK 随包文档。
 4. 社区资料，仅用于补充，并标注来源。
 涉及外部技术版本、接口或模型能力时必须联网确认，避免凭记忆。
 ## 学习输出
 ```text
 技术定位
 适用版本
 当前项目使用场景
 安装与依赖
 最小可用示例
 项目集成方式
 构建/部署注意事项
 常见错误
 验证命令
 是否需要新增 skill
 ```
 ## 生成 skill 时
 - 名称使用小写短横线。
 - 放到 `.agents/skills/<name>/SKILL.md`。
 - frontmatter 只保留 `name` 和 `description`。
 - 内容必须面向 `edge_collector`，不要生成通用教程。
 - 复杂资料可放 `references/`，但优先保持 SKILL.md 简洁。
 - 用 `skill-creator` 的 `quick_validate.py` 校验。
 ## 本项目集成检查
 新增技术必须检查：
 - 是否影响 `collector` 稳定性。
 - 是否需要新增第三方库目录和架构分层。
 - 是否需要修改 `package.sh` 或 `scripts/migrate_edge.sh`。
 - 是否会引入运行配置覆盖风险。
 - 是否需要 82/97/94/87 或云平台验证。
 - 是否需要文档区分用户说明和技术细节。
 ## 输出语气
 给用户的是选型和落地建议，不堆砌官方概念；每条建议都要说明对当前工程的影响。
@@ -0,0 +1,84 @@
 ---
 name: edge-frontend-design
 description: edge_collector 前端页面设计与 UI 落地规范。用于设计或优化边缘侧 frontend/config_app、云平台 frontend/cloud_app 页面、组件、布局、交互、按钮状态、弹窗、图表、AI 分析、WiFi、端口转发、内网穿透等用户界面时，结合当前 React/Vite/CSS Modules 暗色主题输出可落地设计。
 ---
 # edge_collector 前端设计
 ## 适用前端
 - 边缘侧：`frontend/config_app`
 - 云平台：`frontend/cloud_app`
 ## 设计原则
 - 先阅读相邻页面和 CSS Modules，沿用当前视觉语言。
 - 首屏直接呈现可用工具，不做营销式 landing page。
 - 工业/运维页面要安静、清晰、密集但不拥挤。
 - 不引入新的 UI 框架。
 - 不把内部技术细节展示给最终用户。
 - 卡片、按钮、启停、危险操作样式要与已有模块一致。
 ## 视觉基线
 后续前端设计按以下口径走：
 - 暗色底。
 - 细边框。
 - 蓝紫作为主操作色。
 - 状态色克制使用，只用于表达成功、警告、错误、运行中等明确状态。
 - 避免营销页式大渐变。
 - 避免装饰感过强的科技视觉，如大面积霓虹、发光线框、玻璃拟态、纯装饰光效。
 - 页面应像工业网关/运维工具，而不是宣传页或展示大屏。
 现有颜色基线：
 ```text
 背景：#0d0d14 / #14141e
 面板：#1e1e2e
 边框：#2a2a3a
 主文字：#e0e0e0
 标题文字：#ffffff
 主操作色：#6366f1
 ```
 ## 工作流
 1. 明确目标用户：现场用户、运维、管理员、开发。
 2. 梳理核心任务：用户进页面后最需要完成什么。
 3. 阅读现有页面，提取布局、按钮、表格、弹窗和状态样式。
 4. 先给信息架构，再给具体组件布局。
 5. 覆盖加载、空状态、错误、保存中、权限不足、操作成功。
 6. 实现时遵循 `frontend-ui-conventions`、`frontend-conventions`、`frontend-dialog`。
 ## 当前项目常见布局
 - 高级功能：模块标签页 + 左右均分列表/配置区 + 底部操作区靠右。
 - 数据查看/AI 分析：图表区域与报告区域独立，报告内容向下延展，不向上挤占图表。
 - 配置页：表单和列表并排，避免单列垂直堆叠导致右侧空白。
 - 规则列表：单条启用/停用放操作列，不使用复选框表达启停。
 ## 交互要求
 - 点击连接、扫描、保存、分析、启停等耗时操作，按钮必须出现 loading 或局部状态反馈。
 - 危险操作必须二次确认。
 - 失败提示要说明可执行下一步，不只显示接口失败。
 - 普通按钮、危险按钮、启停按钮风格要统一。
 - 长文本和长报告必须支持滚动查看，不能遮挡上方关键内容。
 ## 文案规则
 - 用户可见文案使用业务语言。
 - 不展示 AI Provider 名称、内部模型名、helper、SDK 路径、接口路径、堆栈、SQL。
 - 参数说明写影响和建议值。
 - 空状态告诉用户下一步操作。
 ## 设计检查
 - 是否有大片空白。
 - 文本是否溢出。
 - 窄屏是否可用。
 - 操作后是否有反馈。
 - 图表、表格、报告是否互相遮挡。
 - 权限不足是否有清晰状态。
 - 与相邻模块按钮和标签风格是否一致。
@@ -0,0 +1,104 @@
 ---
 name: edge-frontend-testing
 description: edge_collector 前端测试与浏览器验证规范。用于边缘侧或云平台 React/Vite 页面白屏、布局错乱、按钮无反馈、弹窗异常、图表遮挡、接口失败、构建后验证时，使用 npm build、浏览器控制台、Network、Playwright 截图和交互脚本进行验证。
 ---
 # edge_collector 前端测试
 ## 适用范围
 - `frontend/config_app`
 - `frontend/cloud_app`
 - 云平台公网页面 `http://119.45.4.75`
 - 边缘网关页面，如 `http://192.168.40.<host>/`
 ## 验证顺序
 1. 构建验证。
 2. 页面加载验证。
 3. 控制台错误检查。
 4. Network 接口响应检查。
 5. 关键交互点击。
 6. 布局截图和窄屏检查。
 7. 状态反馈检查。
 ## 构建命令
 按实际目录执行：
 ```bash
 npm run build
 ```
 如果不能构建，最终说明原因，例如缺少依赖、Node 版本不对或远程主机不可用。
 ## Playwright 验证流程
 使用浏览器验证时：
 ```text
 打开目标 URL
  -> wait networkidle
  -> 收集 console error
  -> 截图
  -> 定位关键按钮/输入框
  -> 执行操作
  -> 检查 loading/toast/dialog/network
  -> 再截图
 ```
 优先使用稳定选择器：
 - 可见文本。
 - button role/name。
 - 表单 label。
 - 现有 data 属性。
 - 必要时再用 CSS selector。
 ## 重点页面检查
 - 高级功能：WiFi、内网穿透、端口转发、硬件控制。
 - 数据查看：历史趋势、AI 分析弹窗、AI 分析报告。
 - 离线缓存：参数默认值、保存反馈、状态展示。
 - OTA：包列表、升级确认、进度和失败提示。
 - 管理后台：AI 配置、权限、启用配置唯一性。
 ## 失败提示检查
 前端不能只显示：
 ```text
 failed to request cloud config
 AI 服务请求失败
 操作失败
 ```
 应尽量展示后端或 agent 给出的具体原因，并转成用户可理解文案：
 - 连接失败。
 - 请求超时。
 - 权限不足。
 - 配置缺失。
 - 服务未运行。
 - 返回格式异常。
 ## 截图要求
 复杂 UI 改动至少检查：
 - 桌面宽度。
 - 窄屏或移动宽度。
 - 长内容状态。
 - 操作中状态。
 - 错误状态。
 最终说明截图路径或验证 URL。
 ## 回归重点
 - 页面不白屏。
 - 无严重 console error。
 - 按钮 loading 不导致布局抖动。
 - 报告和表格区域可滚动。
 - 文案不泄露内部实现。
 - 动态配置不会因为前端保存被清空。
@@ -0,0 +1,94 @@
 ---
 name: edge-local-dev-services
 description: edge_collector 本地开发与联调服务管理规范。用于在本机或远程开发主机启动、检查、停止 edge/cloud 前后端开发服务和依赖服务，包含 collector、configurator、cloud_server、React/Vite 前端、PostgreSQL、TDengine、Mosquitto、端口占用和日志验证。
 ---
 # edge_collector 本地开发服务
 ## 适用场景
 - 本机启动边缘侧或云平台开发环境。
 - 前端页面需要 dev server 联调。
 - 后端接口需要本地验证。
 - E2E 前需要确认依赖服务。
 - 端口冲突、服务没起来、接口连接失败。
 ## 先读配置
 不要假设服务和端口，优先读取：
 - `docs/project-overview.md`
 - `cloud_server/config/server_config.json`
 - `configurator/config/`
 - `frontend/*/package.json`
 - `package.sh`
 - `deploy_cloud.sh`
 - `scripts/install_all.sh`
 - systemd service 安装脚本
 ## 常见服务
 - 边缘：`collector`、`configurator`、`edge` systemd 服务。
 - 云端：`cloud_server`、`cloud-server` systemd 服务。
 - 前端：`frontend/config_app`、`frontend/cloud_app`。
 - 依赖：PostgreSQL、TDengine、Mosquitto。
 - 独立 agent：frpc agent、port forward agent、4G/WiFi 相关脚本。
 ## 检查流程
 1. 查看端口占用：
 ```bash
 ss -lntp
 ```
 2. 查看服务状态：
 ```bash
 systemctl status edge --no-pager
 systemctl status cloud-server --no-pager
 ```
 3. 查看最近日志：
 ```bash
 journalctl -u edge --since "10 min ago" --no-pager
 journalctl -u cloud-server --since "10 min ago" --no-pager
 ```
 4. 验证接口：
 ```bash
 curl -s http://127.0.0.1/api/status
 curl -s http://127.0.0.1:8081/api/health
 ```
 ## 前端开发
 进入对应目录后：
 ```bash
 npm install
 npm run dev
 npm run build
 ```
 如果 Node 环境在 97/ARM64 主机异常，优先参考 `scripts/set_env/install_nvm_npm.sh` 和本地 nvm 离线安装规则。
 ## 禁止事项
 - 不要直接连接生产库做写操作。
 - 不要随意 kill 非本次启动的进程。
 - 不要删除用户已有容器、数据库或运行配置。
 - 不要把本地端口和临时密码写死进代码。
 - 不要每次同步后都执行 `install_all.sh`，除非用户明确要求。
 ## 输出
 最终说明：
 - 启动或检查了哪些服务。
 - 使用了哪些端口。
 - 哪些接口验证通过。
 - 日志里是否有错误。
 - 如何停止本次启动的临时服务。
@@ -0,0 +1,91 @@
 ---
 name: edge-markdown-docs
 description: edge_collector Markdown 文档编写与处理规范。用于创建、更新、拆分、合并、校对 docs、collector/docs、协议文档、部署说明、测试报告、故障报告、本地模型方案等 Markdown 文档，并维护目录、链接、图片引用和读者边界。
 ---
 # edge_collector Markdown 文档处理
 ## 适用范围
 - `docs/`
 - `collector/docs/`
 - `collector/docs/protocols/`
 - `docs/本地模型/`
 - `docs/鲁班猫*/`
 - `.agents/skills/`
 ## 工作流
 1. 先确认读者：用户、运维、开发、客户交付。
 2. 选择落点：优先更新已有文档，避免重复文档。
 3. 读取相邻文档，保持标题层级和术语一致。
 4. 写完后检查链接、图片路径、代码块语言和表格可读性。
 5. 技术文档标注假设和验证状态，用户文档隐藏内部实现细节。
 ## 推荐结构
 技术方案：
 ```text
 背景与目标
 现状与问题
 方案设计
 接口/配置/目录
 实施步骤
 验证计划
 风险与回滚
 ```
 操作说明：
 ```text
 功能用途
 使用前准备
 操作步骤
 参数说明
 常见问题
 注意事项
 ```
 故障报告：
 ```text
 问题现象
 影响范围
 证据
 根因
 修复
 验证
 预防措施
 ```
 ## 格式规则
 - 标题层级从 `#` 开始，不跳级。
 - 命令使用 `bash` 代码块。
 - JSON 使用 `json` 代码块。
 - 表格列不要过宽，必要时拆成列表。
 - 图片放到文档同级 `assets/` 或专题目录下，并用相对路径引用。
 - 引用外部资料时给链接。
 ## 当前项目特别规则
 - 协议用户介绍不要透露 helper、SDK、库路径、内部进程。
 - 部署文档要写清是否会覆盖运行配置。
 - 云平台 AI 文档不要展示真实 key。
 - 远程主机文档不要写明密码。
 - 同主机编译部署仍要使用 `scripts/migrate_edge.sh`。
 ## 校验
 至少执行：
 ```bash
 rg -n "TODO|待确认|change_me|password|secret" docs collector/docs .agents/skills
 ```
 按文档类型补充：
 - JSON 示例：`jq empty`
 - Shell 示例：`bash -n`
 - SVG 引用：浏览器或图片查看器打开检查
@@ -0,0 +1,182 @@
 ---
 name: edge-mcp-tools
 description: edge_collector 边缘侧本地模型与 MCP 工具接入规范。用于在鲁班猫/RK3566/RK3576/RK3588 等边缘设备部署本地模型后，设计或实现 MCP 工具服务，让模型安全调用网关状态、设备点位、历史数据、诊断、配置查询和运维只读能力。
 ---
 # edge_collector MCP 工具接入
 ## 目标
 让边缘侧本地模型可以通过受控工具访问网关能力，而不是直接读取任意文件、执行任意命令或绕过现有服务。
 典型链路：
 ```text
 本地模型
  -> MCP Client
  -> edge MCP tools
  -> configurator / collector / 本地数据库 / 只读诊断命令
 ```
 ## 适用场景
 - 在 RK3566/RK3576/RK3588 鲁班猫上部署 Qwen 等本地模型。
 - 给本地模型增加“查询设备状态”“分析点位趋势”“解释报警”“读取网关状态”等工具。
 - 把边缘侧诊断能力封装成 AI 可调用工具。
 - 设计 MCP 工具权限、输入输出和安全边界。
 ## 设计原则
 - 默认只读。
 - 工具服务独立运行，不耦合 `edge` 主服务。
 - 本地模型不直接访问数据库文件、配置文件和 shell。
 - 所有工具必须有明确输入 schema、输出 schema 和错误语义。
 - 写配置、重启服务、删除数据等高风险动作第一版不开放。
 - 工具返回用户可理解信息，不泄露密钥、路径、Token、内部模型配置。
 ## 推荐第一版工具
 优先做只读工具：
 - `edge_get_gateway_status`：读取网关状态、版本、运行时间。
 - `edge_list_devices`：列出设备名称、协议、在线状态。
 - `edge_list_points`：列出某设备点位名称、类型、单位。
 - `edge_read_latest_values`：读取指定设备/点位最新值。
 - `edge_query_history_summary`：查询历史数据摘要，不返回超大原始数据。
 - `edge_get_alarm_summary`：读取报警或异常摘要。
 - `edge_get_network_status`：读取网络、WiFi、4G、端口转发只读状态。
 - `edge_get_service_health`：读取 `edge`、独立 agent 状态。
 暂不开放：
 - 修改协议配置。
 - 保存 AI Key。
 - 重启服务。
 - 删除缓存或历史数据。
 - 执行任意 shell。
 - 读取任意文件。
 ## 工具命名
 - 使用 `edge_` 前缀。
 - 动词清晰：`get`、`list`、`query`、`analyze`。
 - 避免泛化工具名，例如 `run_command`、`read_file`。
 ## 输入输出
 输入必须限制范围：
 ```text
 gateway_id
 device_id 或 device_name
 point_id 或 point_name
 time_range
 limit
 ```
 输出建议结构：
 ```json
 {
  "ok": true,
  "data": {},
  "warnings": [],
  "source": "configurator",
  "timestamp": "2026-06-16T00:00:00+08:00"
 }
 ```
 错误要可行动：
 ```json
 {
  "ok": false,
  "error_code": "DEVICE_NOT_FOUND",
  "message": "未找到指定设备，请确认设备名称或 ID",
  "suggestion": "可先调用 edge_list_devices 查看可用设备"
 }
 ```
 ## 与现有服务集成
 优先通过现有 API 或受控本地接口访问：
 - `configurator` API。
 - `collector` 状态接口或已有数据接口。
 - 本地只读数据库查询。
 - systemd 只读状态命令。
 不要绕过业务逻辑直接修改配置文件。
 ## 本地模型注意
 参考已有本地模型文档：
 - `docs/本地模型/Qwen2.5-0.6B-Instruct在RK3566本地部署方案.md`
 - `docs/本地模型/Qwen2.5-VL-3B-Instruct在RK3576鲁班猫3边缘图文模型部署方案.md`
 - `docs/本地模型/Qwen2.5-14B-Instruct在16G_RK3588鲁班猫5部署方案.md`
 设计工具时必须考虑：
 - 模型上下文有限，工具返回要摘要化。
 - RK3566/RK3576 资源有限，工具查询要分页、限流。
 - 大历史数据先聚合摘要，再按需返回异常片段。
 - 离线运行时不要依赖云端 AI Provider。
 ## 安全边界
 结合 `edge-security-secrets`：
 - 不返回 API Key、JWT、MQTT 密码、SSH 密码。
 - 不暴露真实配置文件完整内容。
 - 不开放任意命令执行。
 - 日志中记录工具名、参数摘要、耗时、结果状态，不记录敏感值。
 - 对外接口只监听本机或受控内网，默认不暴露公网。
 ## 部署方式
 第一版建议使用 Python 独立 agent：
 - 遵循 `edge-python-agent`。
 - 使用 systemd 独立托管。
 - 配置文件动态生成但不覆盖已有配置。
 - 打包和同步遵循 `edge-config-lifecycle`。
 服务名建议：
 ```text
 edge-mcp-tools
 ```
 ## 验证计划
 至少验证：
 - 工具列表可发现。
 - 每个工具 schema 正确。
 - 正常查询返回结构化数据。
 - 设备不存在、点位不存在、时间范围过大时错误可理解。
 - 返回内容脱敏。
 - 大数据查询有 limit 或摘要。
 - 服务重启后配置保留。
 - 本地模型能完成一个端到端问题，例如“分析最近 1 小时某设备是否异常”。
 ## 文档输出
 设计 MCP 工具时输出：
 ```markdown
 ## 工具清单
 ## 权限边界
 ## 输入输出 schema
 ## 数据来源
 ## 部署方式
 ## 安全与脱敏
 ## 验证计划
 ```
@@ -0,0 +1,116 @@
 ---
 name: edge-observability
 description: edge_collector 运行观测与资源诊断规范。用于排查边缘主机或云服务器 CPU 高、内存占用、磁盘空间、/tmp 清理、进程数量、jq/python/agent 异常、服务日志、端口监听和系统负载时，按只读证据链输出分析结论。
 ---
 # edge_collector 运行观测
 ## 适用场景
 - CPU 占用高。
 - 内存比其他主机高。
 - `/tmp` 或工程目录占用大。
 - `jq`、Python、agent 进程很多。
 - 服务频繁重启。
 - 网关在线状态异常。
 - 前端或云端接口偶发失败。
 ## 排查顺序
 1. 系统概况。
 2. CPU 和进程。
 3. 内存。
 4. 磁盘。
 5. systemd 服务。
 6. 应用日志。
 7. 网络端口。
 8. 与对照主机比较。
 ## 常用命令
 系统：
 ```bash
 uptime
 free -h
 df -h
 uname -a
 date
 ```
 CPU/进程：
 ```bash
 ps -eo pid,ppid,user,stat,pcpu,pmem,rss,etime,cmd --sort=-pcpu | head -30
 ps -eo pid,ppid,user,stat,pcpu,pmem,rss,etime,cmd --sort=-rss | head -30
 ```
 进程树：
 ```bash
 pstree -ap
 ```
 磁盘：
 ```bash
 du -h --max-depth=1 /home/cat 2>/dev/null | sort -h
 du -h --max-depth=1 /tmp 2>/dev/null | sort -h
 ```
 服务：
 ```bash
 systemctl status edge --no-pager
 journalctl -u edge --since "30 min ago" --no-pager
 systemctl list-units --type=service --state=running
 ```
 端口：
 ```bash
 ss -lntp
 ```
 ## 分析规则
 - 短时尖峰和持续高占用分开判断。
 - 先找父进程，再判断是脚本循环、服务重启还是用户命令。
 - 内存分析区分 RSS、缓存和可用内存。
 - 磁盘清理只给建议，删除必须等用户确认。
 - 与 119.45.4.75 或其他主机对比时，列出相同指标。
 ## 高风险操作
 以下操作必须用户明确同意：
 - 删除文件或目录。
 - kill 进程。
 - 重启服务。
 - 清理日志。
 - apt 安装诊断工具。
 ## 报告格式
 ```text
 结论：
 证据：
 - CPU:
 - 内存:
 - 磁盘:
 - 进程:
 - 日志:
 判断：
 建议：
 ```
 ## 当前项目常见根因
 - shell + `jq` 高频轮询导致短时 CPU 尖峰。
 - 未插 SIM/设备缺失导致 4G 脚本重复探测。
 - 前端构建产物或代码仓库占用较大。
 - `/tmp` 离线安装包、构建缓存未清理。
 - 独立 agent 异常退出后被 systemd 频繁拉起。
@@ -0,0 +1,76 @@
 ---
 name: edge-pdf-docs
 description: edge_collector PDF 文档读取、提取、转换和交付检查规范。用于处理客户 PDF、导出报告、部署手册、测试报告、扫描件、表格提取、PDF 转图片预览，以及从 DOCX/Markdown 生成 PDF 交付件。
 ---
 # edge_collector PDF 处理
 ## 适用场景
 - 阅读客户 PDF 需求、手册、协议资料。
 - 从 PDF 提取文字或表格。
 - 把 Word/Markdown 报告转 PDF。
 - 将 PDF 页面转图片用于视觉检查。
 - 合并、拆分或旋转 PDF。
 ## 文本提取
 优先使用：
 ```bash
 pdftotext -layout input.pdf output.txt
 ```
 需要表格时使用 `pdfplumber`：
 ```python
 import pdfplumber
 with pdfplumber.open("input.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())
        print(page.extract_tables())
 ```
 扫描件需要 OCR 时，先说明 OCR 可能有识别误差，并保留人工复核步骤。
 ## PDF 转图片
 用于检查版式、截图或报告附件：
 ```bash
 pdftoppm -png -r 150 input.pdf page
 ```
 只转指定页：
 ```bash
 pdftoppm -png -r 150 -f 1 -l 3 input.pdf page
 ```
 ## 合并与拆分
 优先使用 `qpdf`：
 ```bash
 qpdf --empty --pages a.pdf b.pdf -- merged.pdf
 qpdf input.pdf --pages . 1-5 -- part.pdf
 ```
 ## 交付检查
 生成 PDF 后检查：
 - 页面是否缺失。
 - 中文是否乱码。
 - 表格是否截断。
 - 图片是否模糊。
 - 页眉页脚和页码是否正确。
 - 是否包含未脱敏的密钥、账号、密码、内网地址。
 ## 当前项目注意
 - 用户手册 PDF 不写内部技术细节。
 - 故障报告 PDF 要保留证据截图和验证命令摘要。
 - 部署报告 PDF 要写清目标主机但隐藏敏感凭据。
 - AI 分析报告 PDF 不展示内部 AI Provider 和模型配置。
@@ -0,0 +1,70 @@
 ---
 name: edge-presentation-docs
 description: edge_collector PPT/汇报材料编写与处理规范。用于把方案设计、部署方案、测试结果、故障复盘、AI/本地模型方案、协议适配方案整理成汇报型 PPT 或演示大纲，并可读取、检查、转换已有 .pptx。
 ---
 # edge_collector 汇报材料处理
 ## 适用场景
 - 方案汇报。
 - 项目进展汇报。
 - 故障复盘汇报。
 - 部署上线说明。
 - 本地模型或 AI 功能方案展示。
 - 协议适配方案展示。
 ## 默认结构
 ```text
 1. 背景与目标
 2. 当前现状/问题
 3. 方案总览
 4. 核心设计或流程
 5. 实施计划
 6. 验证结果
 7. 风险与对策
 8. 下一步
 ```
 ## 设计口径
 - 面向工业网关和云边协同场景，风格稳重、清晰、克制。
 - 优先用流程图、架构图、对比表，而不是大段文字。
 - 一页只表达一个核心结论。
 - 保留必要证据：截图、日志摘要、测试结果、关键指标。
 - 不展示密钥、密码、真实 Token。
 ## 内容转换
 从 Markdown 方案转 PPT 时：
 - 每个二级标题通常对应 1 页或 1 组页。
 - 长表格改成摘要表 + 附录。
 - 命令行只保留关键命令和结果，不放完整日志。
 - 复杂架构图优先使用 `edge-svg-diagram` 生成 SVG 后嵌入。
 ## 读取 PPTX
 提取文本：
 ```bash
 python3 -m markitdown input.pptx > output.md
 ```
 没有 `markitdown` 时，先说明无法直接提取，改用 LibreOffice 或解包 XML。
 检查结构：
 ```bash
 unzip -l input.pptx | rg "ppt/slides/slide|ppt/media|ppt/theme"
 ```
 ## 交付检查
 - 标题是否能单独表达结论。
 - 字体和颜色是否统一。
 - 截图是否清晰。
 - 图表文字是否不截断。
 - 每页是否有明确层级。
 - 是否隐藏内部 AI 配置、密钥和调试信息。
@@ -0,0 +1,72 @@
 ---
 name: edge-project-overview
 description: edge_collector 项目概览维护规范。用于读取、生成或更新本仓库项目总览，沉淀边缘侧、云平台、前端、协议采集、脚本部署、远程主机、运行目录、动态配置保护和常用验证命令，帮助新任务快速建立上下文。
 ---
 # edge_collector 项目概览
 ## 何时使用
 - 用户要求“整理项目概览”“说明当前工程结构”。
 - 新增较大功能前需要建立上下文。
 - 部署、协议、前端、云端多模块同时涉及。
 - 文档或 skill 需要引用项目约定。
 ## 建议落点
 默认维护：
 ```text
 docs/project-overview.md
 ```
 如果已有同类文档，优先更新已有文档，不新增重复总览。
 ## 必须覆盖
 ```text
 项目定位
 模块结构
 边缘侧服务
 云平台服务
 前端应用
 协议采集架构
 运行目录 runtime/edge
 配置文件与动态配置保护
 构建与打包脚本
 部署与同步脚本
 常用远程主机
 常用验证命令
 风险与注意事项
 推荐阅读路径
 ```
 ## 事实来源
 生成或更新概览时优先读取：
 - `CMakeLists.txt`、`collector/CMakeLists.txt`
 - `package.sh`
 - `deploy_cloud.sh`
 - `scripts/migrate_edge.sh`
 - `scripts/install_all.sh`
 - `frontend/*/package.json`
 - `configurator/config/`
 - `collector/docs/`
 - `.agents/skills/`
 ## 环境与主机
 概览可记录常用主机，但不要写敏感密钥：
 - 82：常用 arm64 发布构建主机。
 - 97：arm64 编译/同步验证主机。
 - 94、87：边缘运行验证主机。
 - 云平台：`119.45.4.75`。
 ## 输出要求
 - 明确“已确认事实”和“从文件推断”。
 - 不把历史临时问题写成永久事实。
 - 动态配置保护规则要写清楚，避免打包/同步覆盖运行配置。
 - 同主机编译部署也要使用 `scripts/migrate_edge.sh` 的规范需要写入。
@@ -0,0 +1,80 @@
 ---
 name: edge-project-plan-writer
 description: edge_collector 项目计划与实施拆分编写规范。用于为协议适配、云平台功能、边缘 agent、AI 分析、本地模型、前端页面、部署机制、故障治理等工作编写项目计划、里程碑、任务拆分、风险清单和验证排期。
 ---
 # edge_collector 项目计划编写
 ## 适用场景
 - 新协议适配计划。
 - 云平台功能迭代计划。
 - 边缘独立 agent 实施计划。
 - AI 分析或本地模型接入计划。
 - 前端复杂页面改造计划。
 - 部署/打包/同步机制优化计划。
 - 故障治理和稳定性专项计划。
 ## 推荐结构
 ```text
 目标与范围
 现状与约束
 阶段划分
 里程碑
 任务拆分
 依赖关系
 验证计划
 部署计划
 风险与缓解
 交付物
 ```
 ## 阶段模板
 ```text
 阶段 1：调研与方案
 阶段 2：最小可用实现
 阶段 3：联调与异常场景
 阶段 4：部署验证
 阶段 5：文档与交付
 ```
 按任务实际裁剪，不要机械套用。
 ## 任务拆分要求
 每个任务写清：
 - 目标。
 - 涉及目录。
 - 负责人或执行对象。
 - 前置依赖。
 - 验收标准。
 - 验证命令或验证页面。
 ## 当前项目必须考虑
 - 是否影响 `collector` 稳定性。
 - 是否影响 `runtime/edge` 或 `runtime/cloud_server` 动态配置。
 - 是否需要 82/97/94/87 或云服务器验证。
 - 是否需要修改 `package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
 - 是否需要新增 systemd 服务或独立 agent。
 - 是否需要用户文档和技术文档分开。
 ## 风险清单
 常见风险：
 - 跨架构第三方库不可用。
 - 目标主机系统版本差异。
 - 前端构建环境不一致。
 - 配置同步覆盖运行态文件。
 - AI Provider 超时、费用或响应格式差异。
 - 真实设备不可用导致只能 mock 验证。
 ## 输出要求
 - 计划要能直接转成执行清单。
 - 不确定项标为“待确认”，不要伪装成已完成。
 - 时间排期必须留出联调、回归和远程部署验证。
@@ -0,0 +1,81 @@
 ---
 name: edge-protocol-research
 description: edge_collector 协议调研与适配评估规范。用于调研 FANUC、西门子 CNC、PLC、传感器、第三方 SDK 或参考仓实现时，按当前协议模板、驱动代码、参考实现、官方资料和验证计划输出适配差异、点位补充和实现建议。
 ---
 # edge_collector 协议调研
 ## 适用场景
 - 新增协议驱动。
 - 完善 FANUC/西门子 CNC 点位。
 - 参考外部仓采集程序。
 - 判断第三方 SDK 架构和库是否可用。
 - 协议模板是否合理、是否缺常用点位。
 ## 调研顺序
 1. 读取当前协议模板和用户可见描述。
 2. 读取当前驱动实现和文档。
 3. 对比参考仓或历史实现。
 4. 拿不准的协议语义联网查官方资料或 SDK 文档。
 5. 输出差异、风险、实施建议和验证计划。
 ## 当前项目路径
 优先查看：
 - `configurator/config/templates/`
 - `configurator/config/protocols/`
 - `collector/src/driver/`
 - `collector/docs/protocols/`
 - `third_party/`
 - `collector/CMakeLists.txt`
 ## 对比重点
 - 连接参数是否够用。
 - 点位名称、类型、单位、默认采集周期是否合理。
 - 模板点位和驱动读取逻辑是否一致。
 - 是否保留现有 `PointData::UpdateValue` 行为。
 - 用户可见协议介绍是否隐藏内部技术细节。
 - 第三方库是否按架构分层放置。
 - ARM64/ARM32/x64 构建模式是否明确。
 ## 联网规则
 遇到以下情况必须联网查证：
 - 协议函数含义不确定。
 - SDK 架构、库名、系统依赖不确定。
 - 西门子/FANUC 指标语义不确定。
 - 第三方资料可能过期。
 优先官方文档、SDK 手册、厂商资料；社区资料只能作为补充。
 ## 输出格式
 ```markdown
 ## 当前现状
 ## 参考实现差异
 ## 点位/参数建议
 ## 驱动实现建议
 ## 构建与第三方库影响
 ## 用户文档影响
 ## 验证计划
 ## 风险与待确认
 ```
 ## 禁止事项
 - 不凭猜测写协议语义。
 - 不提交未知来源二进制库。
 - 不把参考仓问题照搬进当前工程。
 - 不在用户可见协议介绍中写 helper、SDK 路径、库文件细节。
@@ -0,0 +1,50 @@
 ---
 name: edge-prototype-design
 description: edge_collector 高保真原型设计规范。用于设计边缘侧或云平台前端页面、复杂交互、管理后台页面、AI 分析、WiFi、端口转发、OTA、数据趋势等功能原型时，先分析现有 React/CSS Modules 风格，再输出适合当前项目落地的原型和实现建议。
 ---
 # edge_collector 原型设计
 ## 适用范围
 - `frontend/config_app` 边缘侧页面。
 - `frontend/cloud_app` 云平台页面。
 - AI 分析、WiFi 管理、端口转发、内网穿透、OTA、离线缓存、数据趋势等复杂页面。
 ## 工作流
 1. 阅读现有页面和 CSS Modules，提取当前视觉语言。
 2. 明确目标用户和核心任务。
 3. 先画信息架构和布局，不急着写代码。
 4. 给出关键状态：加载、空状态、失败、保存中、禁用、权限不足。
 5. 再进入实现，遵循 `frontend-ui-conventions`。
 ## 原型输出形式
 按任务选择：
 - 文档内 ASCII 线框：适合接口/流程方案。
 - HTML 静态原型：适合复杂页面评估。
 - React 组件草案：适合直接落地到现有前端。
 - SVG 交互说明图：适合文档配图。
 ## 本项目 UI 约束
 - 使用 React + Vite + CSS Modules。
 - 保持现有暗色主题。
 - 暗色底、细边框、蓝紫主操作色、状态色克制使用。
 - 避免营销页式大渐变和装饰感过强的科技视觉。
 - 原型应呈现工业网关/运维工具气质，优先清晰、稳定、可操作。
 - 不引入 Ant Design、Tailwind 或新的 UI 框架。
 - 按 `frontend-dialog` 使用统一弹窗。
 - 普通操作按钮、危险按钮、启停按钮样式要与现有模块一致。
 - 页面首屏应是可用工具，不做营销式 landing page。
 ## 设计检查
 - 右侧是否有大片空白。
 - 文本是否溢出或遮挡。
 - 操作后是否有 loading/反馈。
 - 是否支持窄屏。
 - 危险操作是否二次确认。
 - 用户可见文案是否隐藏内部实现细节。
@@ -0,0 +1,88 @@
 ---
 name: edge-python-agent
 description: edge_collector Python 独立 agent 开发规范。用于新增或修改 frpc agent、port forward agent、WiFi/4G 辅助进程、巡检脚本、数据分析脚本等 Python3 常驻或命令行工具时，统一配置、日志、systemd、资源占用、退出码和与 edge 主服务解耦要求。
 ---
 # edge_collector Python Agent
 ## 适用范围
 - `scripts/frp/start_*.py`
 - `scripts/port_forward/start_*.py`
 - WiFi/4G 辅助脚本。
 - 远程巡检和数据分析脚本。
 - 需要 systemd 托管的 Python 常驻进程。
 ## 命名与位置
 - 常驻启动脚本使用 `start_` 前缀，保持现有风格。
 - 按功能放到独立目录，例如 `scripts/frp/`、`scripts/port_forward/`。
 - 不要把独立 agent 代码塞进 `collector` 或 `configurator`。
 ## 配置
 - 配置文件放到运行目录的 `config/` 或功能子目录。
 - 支持配置缺失时生成默认文件，但不得覆盖已有配置。
 - 动态配置必须被打包和同步规则排除，避免目标主机运行配置被覆盖。
 - 密钥、Token、URL 不写死在代码中。
 ## 日志
 - 使用 Python `logging`。
 - 日志包含时间、级别、模块、关键状态。
 - 不打印密钥、密码、Token。
 - 高频循环日志要限流，避免 CPU/磁盘压力。
 - 错误日志要保留具体原因，供前端展示更明确错误。
 ## 常驻进程要求
 - 支持优雅退出 `SIGTERM`/`SIGINT`。
 - 主循环有固定 sleep 或事件等待，禁止无休眠空转。
 - 外部命令调用设置 timeout。
 - 子进程必须回收。
 - 网络请求必须设置连接和读取超时。
 - 异常后退避重试，不要短时间无限重启。
 ## systemd
 服务文件应明确：
 ```text
 WorkingDirectory
 ExecStart
 Restart=on-failure
 RestartSec
 User
 Environment
 ```
 新增服务应独立，不替代已有 `edge`、`frpc_agent` 或其他服务，除非用户明确要求迁移。
 ## CLI
 建议支持：
 ```bash
 --config <path>
 --log-level <level>
 --once
 --dry-run
 ```
 `--once` 适合调试和安装后验证。
 ## 验证
 至少验证：
 ```bash
 python3 -m py_compile scripts/<dir>/<file>.py
 python3 scripts/<dir>/<file>.py --help
 ```
 常驻服务验证：
 ```bash
 systemctl status <service> --no-pager
 journalctl -u <service> --since "5 min ago" --no-pager
 ```
@@ -0,0 +1,90 @@
 ---
 name: edge-release-notes
 description: edge_collector 版本说明与变更日志编写规范。用于提交、push、边缘包发布、云平台部署、OTA 发布、阶段交付时，生成面向用户、运维和开发的 release notes，区分用户可见变化、部署影响、配置影响、验证结果和回滚说明。
 ---
 # edge_collector 版本说明
 ## 适用场景
 - 提交前整理变更。
 - push 后总结。
 - 边缘版本发布。
 - 云平台部署。
 - OTA 包说明。
 - 阶段交付说明。
 ## 读者分层
 - 用户可见：功能变化、操作入口、体验优化。
 - 运维可见：部署步骤、配置变化、服务重启、回滚。
 - 开发可见：代码结构、接口、测试、技术债。
 不要把内部 helper、SDK 路径、密钥、模型配置写进用户可见说明。
 ## 推荐结构
 ```markdown
 ## 版本信息
 - 版本：
 - 日期：
 - 范围：
 ## 用户可见变化
 ## 运维与部署影响
 ## 配置变化
 ## 修复问题
 ## 验证结果
 ## 已知风险
 ## 回滚说明
 ```
 ## 从 Git 生成摘要
 可参考：
 ```bash
 git log --oneline -10
 git diff --stat HEAD~1..HEAD
 git status --short
 ```
 只总结和本次发布相关内容，不把无关工作区改动写进版本说明。
 ## 边缘发布说明
 必须说明：
 - 目标架构。
 - 是否需要执行 `install_all.sh`。
 - 是否需要重启 `edge` 或独立 agent。
 - 是否影响运行态动态配置。
 - 是否通过目标主机验证。
 ## 云平台发布说明
 必须说明：
 - 是否执行 `deploy_cloud.sh`。
 - 是否使用 `--init`。
 - 是否影响 `ai_config.json`、`server_config.json`。
 - 是否重启 `cloud-server`、Mosquitto、nginx。
 - 公网接口验证结果。
 ## OTA 包说明
 面向用户时写：
 - 新增能力。
 - 修复问题。
 - 升级注意事项。
 - 回滚建议。
 避免写内部提交号、代码路径和密钥。
@@ -0,0 +1,67 @@
 ---
 name: edge-release-prepare
 description: 边缘侧版本发布确认流程。用于用户说“发布边缘侧版本”“准备发布边缘侧版本”“发布边缘侧版本 版本号 xxx”等场景：先去 82 主机拉取最新代码，整理版本信息和版本说明，等待用户确认后才允许执行 package.sh --publish。
 ---
 # 边缘侧版本发布确认
 ## 何时使用
 - 发布边缘侧版本
 - 准备发布边缘侧版本
 - 发布边缘侧版本 版本号 xxx
 - 先整理边缘侧发布说明
 ## 固定环境
 - 82 主机：`cat@192.168.40.82`
 - 82 代码根目录：`/home/cat/code/edge_collector`
 - 构建目标：`arm64`
 - 默认云平台：`http://119.45.4.75`
 - 默认云平台账号：`admin`
 ## 第一阶段：只准备，不发布
 用户说“发布边缘侧版本”时，先执行：
 ```bash
 sshpass -p 'i7568737i' ssh -o StrictHostKeyChecking=no cat@192.168.40.82 \
  'cd /home/cat/code/edge_collector && git pull && git status --short && git log -5 --oneline'
 ```
 然后根据用户输入和最新代码状态整理发布草案，至少包含：
 - 目标版本号：用户已给则使用；未给则请用户确认版本号
 - 目标架构：`arm64`
 - 发布类型：用户已给则使用；未给则建议 `release` 或请用户选择
 - 产物名称：`publish/edge_<version>_arm64.tar.gz`
 - 版本信息：一句话概括本次发布
 - 版本说明：多行列点，来自用户说明、最近提交、已完成改动和验证结果
 - 后续动作预览：确认后将在 82 执行 `./package.sh --publish --version <version>`，必要时上传云平台
 ## 确认边界
 - 在用户明确确认前，禁止执行 `./package.sh --publish --version ...`
 - 在用户明确确认前，禁止上传云平台
 - 用户确认后，再按 `edge-82-release` 的发布流程执行
 ## 建议输出格式
 ```text
 发布草案：
 - 版本号：<version>
 - 架构：arm64
 - 发布类型：release
 - 产物：publish/edge_<version>_arm64.tar.gz
 版本信息：
 <一句话说明>
 版本说明：
 - <说明 1>
 - <说明 2>
 确认后执行：
 1. 82: ./package.sh --publish --version <version>
 2. 如需上传云平台，使用上述版本说明和发布类型
 ```
@@ -0,0 +1,3 @@
 display_name: 边缘发布确认
 short_description: 去82拉最新代码，整理版本信息和说明，确认后才发布
 default_prompt: Use this skill when the user says "发布边缘侧版本" or asks to prepare an edge-side release. First SSH to cat@192.168.40.82, cd /home/cat/code/edge_collector, run git pull, inspect git status and recent commits, then produce a release draft with version, arm64 architecture, release type, artifact name, version summary, and release notes. Do not run ./package.sh --publish or upload to the cloud until the user explicitly confirms.
@@ -0,0 +1,110 @@
 ---
 name: edge-remote-access
 description: edge_collector 远程主机访问与操作规范。用于 SSH 到 82/87/94/97 等边缘主机或云服务器执行命令、采集日志、传文件、检查端口、做临时隧道和远程排障时，约束只读优先、命令安全、敏感信息脱敏和避免误操作。
 ---
 # edge_collector 远程访问
 ## 主机解析
 数字主机连接规则由 `host-connection-defaults` 提供：
 ```text
 87 -> cat@192.168.40.87
 97 -> cat@192.168.40.97
 ```
 云服务器常用：
 ```text
 ubuntu@119.45.4.75
 ```
 如果用户明确给出账号、IP、密码或端口，以用户本次说明为准。
 ## 操作原则
 - 只读排查优先。
 - 多条只读命令可以合并一次 SSH 执行。
 - 写操作、重启、删除、同步、清库必须有用户明确要求。
 - 不要在最终回复中暴露密码、Token、Key。
 - 不要手写替代项目已有部署脚本。
 ## 常用只读命令
 ```bash
 hostname
 uptime
 date
 uname -a
 df -h
 free -h
 ss -lntp
 systemctl status edge --no-pager
 journalctl -u edge --since "10 min ago" --no-pager
 ```
 云端：
 ```bash
 systemctl status cloud-server --no-pager
 journalctl -u cloud-server --since "10 min ago" --no-pager
 systemctl status mosquitto --no-pager
 ```
 ## 传文件
 优先使用项目脚本：
 - 边缘同步：`scripts/migrate_edge.sh`
 - 云平台部署：`deploy_cloud.sh`
 只有用户要求临时取日志、截图或单个文件时，才使用 `scp`/`rsync`。传输前说明源路径、目标路径和是否覆盖。
 ## sudo
 使用 sudo 前先确认是否必要。常见只读 sudo：
 ```bash
 sudo journalctl -u edge --since "10 min ago" --no-pager
 sudo systemctl status edge --no-pager
 ```
 避免执行：
 ```bash
 sudo rm -rf
 sudo systemctl restart <service>
 sudo apt install
 ```
 除非用户明确要求。
 ## 端口和网络
 检查端口：
 ```bash
 ss -lntp
 curl -s http://127.0.0.1/api/status
 curl -s http://127.0.0.1:8081/api/health
 ```
 排查同网段设备时：
 ```bash
 ip addr
 ip route
 ip neigh show <ip>
 arp -an | grep <ip>
 ```
 ## 输出要求
 最终说明：
 - 连接的主机。
 - 执行的关键只读检查。
 - 发现的异常证据。
 - 未执行的高风险动作。
 - 建议下一步。
@@ -0,0 +1,60 @@
 ---
 name: edge-requirement-interview
 description: edge_collector 需求采访规范。用于较大功能、跨模块改造、协议适配、云端 AI、边缘 agent、前端复杂页面、部署机制调整或重要文档编写前，通过少量关键问题澄清目标、范围、成功标准、约束和交付物。
 ---
 # edge_collector 需求采访
 ## 触发场景
 - 新增协议或重构协议采集。
 - 新增边缘独立 agent 或 systemd 服务。
 - 云平台新增 AI、数据分析、设备管理能力。
 - 前端新增复杂页面或复杂交互。
 - 修改打包、同步、部署、运行目录规则。
 - 编写重要方案、详细设计或交付文档。
 ## 原则
 - 一次只问一个关键问题。
 - 优先问影响方案方向的问题。
 - 最多 8 个问题；需求很明确时可以少问或不问。
 - 用户已经给出明确实施指令时，不用采访拖延，直接执行并在关键假设处说明。
 ## 标准问题池
 按需要选择：
 1. 核心目标是什么，完成后用户能做什么？
 2. 涉及哪些模块，哪些明确不包含？
 3. 成功标准是什么，如何验证？
 4. 目标用户是谁，是现场用户、运维还是开发？
 5. 是否需要兼容已有配置、协议模板或运行数据？
 6. 是否涉及 82/97/94/87 或云服务器部署验证？
 7. 是否允许新增独立进程、配置文件或 systemd 服务？
 8. 文档需要写给谁看，放到哪个目录？
 ## 输出摘要
 采访结束或信息足够时，输出：
 ```markdown
 ## 需求摘要
 - 目标：
 - 范围：
 - 不包含：
 - 成功标准：
 - 关键约束：
 - 交付物：
 - 验证方式：
 - 待确认：
 ```
 ## 本项目特别关注
 - 不能覆盖运行时动态配置。
 - 用户可见协议介绍不暴露内部技术细节。
 - 边缘采集稳定性优先于 UI 或辅助功能。
 - 新增常驻进程应独立，不耦合 `edge` 主服务。
 - 同步部署遵循 `scripts/migrate_edge.sh`。
@@ -0,0 +1,96 @@
 ---
 name: edge-security-secrets
 description: edge_collector 密钥、权限和敏感配置处理规范。用于处理 AI Key、JWT secret、MQTT dynsec、SSH 密码、数据库密码、Token、配置同步、日志脱敏、提交检查和用户可见文档时，防止泄露、覆盖运行密钥或把敏感信息提交到仓库。
 ---
 # edge_collector 敏感配置安全
 ## 敏感信息范围
 - AI Provider API Key。
 - `jwt_secret`。
 - terminal `credential_key`。
 - MQTT dynsec 管理员和客户端密码。
 - 数据库账号密码。
 - SSH 密码和私钥。
 - Token、Cookie、Session。
 - 内网穿透访问密钥。
 - 客户设备真实敏感地址。
 ## 基本原则
 - 不在最终回复中打印完整密钥。
 - 不把密钥写死进代码。
 - 不提交真实配置。
 - 不用打包产物覆盖远端运行密钥。
 - 日志和前端错误提示要脱敏。
 - 用户文档隐藏内部模型、Provider、Key、URL 中的敏感部分。
 ## 配置文件
 运行态配置优先保存在目标主机 `runtime` 或服务目录下：
 - `runtime/edge/config/`
 - `~/cloud_server/config/server_config.json`
 - `~/cloud_server/config/ai_config.json`
 打包和同步脚本必须保护动态配置。修改以下脚本时要特别检查：
 - `package.sh`
 - `deploy_cloud.sh`
 - `scripts/migrate_edge.sh`
 - `scripts/install_all.sh`
 ## 脱敏规则
 展示时保留前后少量字符：
 ```text
 sk-abc...xyz
 ```
 URL 中如包含 key、token、password 参数，必须隐藏参数值。
 日志中禁止输出：
 ```text
 Authorization
 api_key
 password
 secret
 token
 credential_key
 ```
 ## 提交前检查
 提交前建议：
 ```bash
 git status --short
 git diff --cached
 rg -n "api[_-]?key|password|secret|token|credential_key|Authorization" .
 ```
 发现真实密钥时：
 1. 不提交。
 2. 改为配置文件或环境变量。
 3. 如已暴露，提醒用户轮换密钥。
 ## 云平台 AI 配置
 - 后端配置可保存 Provider、Base URL、模型名、思考模式等。
 - 前端和报告不展示内部 Provider 名称、模型细节和 Key。
 - AI 请求失败日志可以记录错误类型和状态码，但不要记录 Key。
 ## 远程操作
 - SSH 命令中可使用既有默认连接规则，但最终回复不要打印密码。
 - 采集远程配置时，输出前先脱敏。
 - 复制配置文件前确认是否包含密钥。
 ## 用户可见文档
 - 协议介绍、用户手册、AI 报告、导出报告不写内部技术细节和密钥。
 - 运维文档可以写配置路径和字段含义，但示例值必须使用占位符。
@@ -0,0 +1,81 @@
 ---
 name: edge-skill-builder
 description: edge_collector 技能建设规范。用于从外部仓库、已有流程、项目经验、框架/SDK 学习结果中创建或改写 .agents/skills 下的 Codex skills，要求结合当前 C++/Drogon/React/Vite/云边部署/现场主机实际情况，避免原封不动照搬无关技术栈。
 ---
 # edge_collector 技能建设
 ## 目标
 把项目中重复出现的流程和判断沉淀为 `.agents/skills/<name>/SKILL.md`，让后续任务能稳定复用。
 ## 适用来源
 - 当前仓库脚本，如 `deploy_cloud.sh`、`package.sh`、`scripts/migrate_edge.sh`。
 - 已完成的故障排查和现场经验。
 - 外部仓库中的通用 skill。
 - 官方文档或 SDK 调研结果。
 - 用户明确确认的长期规则。
 ## 命名规则
 - 使用小写短横线。
 - 本项目专用优先加 `edge-` 前缀。
 - 云平台专用可用 `cloud-` 前缀。
 - 名称要表达动作或场景，例如 `edge-frontend-testing`。
 ## frontmatter
 只写：
 ```yaml
 ---
 name: <skill-name>
 description: <做什么 + 什么时候使用 + 当前项目关键上下文>
 ---
 ```
 `description` 必须包含触发词，例如“部署云平台”“前端测试”“协议适配”“同步到97”。
 ## 改写原则
 - 先读当前仓库真实文件，再写 skill。
 - 保留流程骨架，替换成当前工程技术栈。
 - 删除 Java、Spring、K3s、Ant Design、Umi、ClickHouse 等与当前工程不匹配的固定假设，除非当前文件真实使用。
 - 不写通用教程，只写能指导本仓库工作的规则。
 - 不把临时现场处理写成永久规则。
 ## 当前项目必须体现
 - C++ collector 和 Drogon 后端。
 - React/Vite/CSS Modules 前端。
 - `runtime/edge` 与 `runtime/cloud_server`。
 - `package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
 - 82/97/94/87 边缘主机和云服务器 `119.45.4.75`。
 - 运行态动态配置不能被打包或同步覆盖。
 - 用户可见文档不能透露内部技术细节。
 ## 校验
 新增或修改 skill 后执行：
 ```bash
 python3 /home/cloud/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/<name>
 ```
 同时检查：
 ```bash
 grep -R "Java\\|Spring\\|K3s\\|Ant Design\\|Umi\\|one_person" -n .agents/skills/<name> || true
 ```
 如果出现这些词，要确认是项目真实需要，还是外部 skill 残留。
 ## 输出
 最终向用户说明：
 - 新增或修改了哪些 skill。
 - 每个 skill 覆盖什么场景。
 - 是否通过校验。
 - 是否只改了 skill 文件，是否未提交。
@@ -0,0 +1,83 @@
 ---
 name: edge-spreadsheet-docs
 description: edge_collector 表格、CSV、XLSX 文档处理规范。用于整理点位清单、协议模板、测试用例、数据质量统计、AI 分析数据摘要、设备清单、问题回溯表和导入导出表格，支持读取、生成、校验 CSV/XLSX。
 ---
 # edge_collector 表格文档处理
 ## 适用场景
 - 点位清单和协议模板对照。
 - 系统测试用例表。
 - 数据质量统计表。
 - 设备/网关清单。
 - 故障问题回溯表。
 - AI 分析输入/输出摘要。
 - CSV/XLSX 导入导出检查。
 ## 工具选择
 - 简单 CSV：优先用 Python `csv` 或 `pandas`。
 - XLSX 格式和样式：使用 `openpyxl`。
 - 需要公式：使用 Excel 公式，不在 Python 中硬编码计算结果。
 - 大文件分析：分块读取，避免一次性加载导致内存过高。
 ## 表格设计
 每张表应明确：
 - 表名。
 - 数据来源。
 - 时间范围。
 - 字段含义。
 - 单位。
 - 是否脱敏。
 - 生成时间。
 ## 当前项目常用列
 点位/设备：
 ```text
 网关名称, 网关ID, 设备名称, 设备ID, 点位名称, 点位ID, 协议, 数据类型, 单位, 说明
 ```
 测试用例：
 ```text
 编号, 模块, 场景, 前置条件, 操作步骤, 预期结果, 实际结果, 状态, 问题记录
 ```
 数据质量：
 ```text
 对象, 时间范围, 原始点数, 有效点数, 分析点数, 最大间隔, 缺口数量, 重复值比例, 结论
 ```
 ## 校验
 CSV：
 ```bash
 python3 - <<'PY'
 import csv
 with open("file.csv", newline="", encoding="utf-8-sig") as f:
    rows = list(csv.reader(f))
 print(len(rows), rows[0] if rows else [])
 PY
 ```
 XLSX：
 ```python
 from openpyxl import load_workbook
 wb = load_workbook("file.xlsx", data_only=False)
 print(wb.sheetnames)
 ```
 ## 注意
 - 中文 CSV 优先使用 `utf-8-sig`，方便 Excel 打开。
 - 导出给用户的表格不要出现内部字段名、接口路径或密钥。
 - 公式表必须检查 `#REF!`、`#DIV/0!`、`#VALUE!`、`#NAME?`。
 - 修改既有模板时保留原列顺序和样式，除非用户明确要求调整。
@@ -0,0 +1,59 @@
 ---
 name: edge-svg-diagram
 description: edge_collector 可编辑 SVG 图示规范。用于用户要求画架构图、部署拓扑图、协议链路图、流程图、方案配图、报告示意图时，生成可提交到 docs 的静态 SVG，并结合当前边缘/云平台/鲁班猫/协议采集场景设计。
 ---
 # edge_collector SVG 图示
 ## 适用场景
 - 云边架构图
 - 边缘 runtime 目录结构图
 - 协议采集链路图
 - FANUC helper / proxy 架构图
 - OTA 升级流程图
 - AI 本地模型部署图
 - WiFi/4G/frpc/端口转发 agent 关系图
 ## 输出位置
 - 文档配图优先放在对应文档旁边的子目录，例如 `docs/assets/` 或专题目录下。
 - 文件名使用清晰中文或 `snake_case`，扩展名 `.svg`。
 - Markdown 中使用相对路径引用。
 ## 设计要求
 - SVG 必须可编辑、可 diff。
 - 使用真实项目元素命名：`collector`、`configurator`、`cloud_server`、`runtime/edge`、`scripts/migrate_edge.sh`。
 - 不使用复杂渐变和难维护滤镜。
 - 字号、间距、线条保持清晰，适合 Markdown 预览。
 - 区域超过 3 个或节点超过 8 个时，先做布局骨架，再补细节。
 ## 风格规则
 按用途选择风格，不要混用：
 - 文档/方案/报告配图：优先浅色、打印友好，白色或近白背景，深色文字，少量蓝/绿/橙用于区分云端、边缘、设备、风险。
 - 前端原型/交互说明图：应贴近当前前端暗色风格，参考 `frontend/config_app` 和 `frontend/cloud_app` 的视觉基线：
  - 背景：`#0d0d14`、`#14141e`
  - 边框：`#2a2a3a`
  - 主文字：`#e0e0e0`
  - 标题/高亮文字：`#ffffff`
  - 强调色：`#6366f1`
  - 状态色按现有页面语义选择，避免一整张图只有紫蓝色
  - 避免营销页式大渐变和装饰感过强的科技视觉
 - 用户故事中的业务场景图：优先清晰、业务化，不必强行模拟前端 UI；如果故事本身是前端页面或交互改造，再使用暗色项目风格。
 ## 推荐布局
 - 云边拓扑：左边缘、右云端，中间网络/隧道。
 - 进程架构：上层 UI/API，中层服务，底层配置/数据库/设备。
 - 部署流程：从构建主机到 runtime 到目标主机。
 ## 验证
 - 用浏览器或图片查看工具打开 SVG。
 - 确认文字不重叠、不截断。
 - 确认中文显示正常。
 - 确认风格与用途匹配：文档图可打印，前端原型图与项目暗色主题一致。
 - 文档引用路径有效。
@@ -0,0 +1,73 @@
 ---
 name: edge-sync-host
 description: 边缘运行目录同步流程。用于用户说“同步到87主机”“同步到85主机”“把边缘包同步到某主机”等场景，默认执行 scripts/migrate_edge.sh，并把用户说出的数字主机作为 --dst_host；87 只是示例，其他数字主机同理。
 ---
 # 边缘运行目录同步
 ## 何时使用
 - 同步到87主机
 - 同步到 85 主机
 - 把边缘包同步到某主机
 - 将 runtime/edge 部署到目标主机
 ## 固定规则
 - 脚本：`scripts/migrate_edge.sh`
 - 默认源：82 主机的 `/home/cat/code/edge_collector/runtime/edge`
 - 默认目标目录：`/home/cat/edge`
 - 数字主机解析：`87` -> `192.168.40.87`
 - 默认用户：`cat`
 - 默认密码：`i7568737i`
 - 如果用户要求“在某台主机编译，再同步到同一台主机”，也必须使用 `scripts/migrate_edge.sh` 的同步方式；不要改成手写 `scp`、`rsync` 或本机 `cp`。
 - 同主机编译部署时，显式传入相同的源和目标主机，例如在 97 编译并同步到 97：
 ```bash
 bash scripts/migrate_edge.sh --src_host 97 --dst_host 97
 ```
 ## 执行方式
 用户说“同步到87主机”时，在本仓库根目录执行：
 ```bash
 bash scripts/migrate_edge.sh --dst_host 87
 ```
 同步完成后，必须在目标主机重启边缘服务并验证状态：
 ```bash
 sshpass -p 'i7568737i' ssh -o StrictHostKeyChecking=no cat@192.168.40.87 \
  'echo i7568737i | sudo -S systemctl restart edge && systemctl is-active edge'
 ```
 用户说其他数字主机时，把数字替换到 `--dst_host`：
 ```bash
 bash scripts/migrate_edge.sh --dst_host <host_number>
 ```
 随后也要把重启命令中的目标地址替换为 `192.168.40.<host_number>`，执行 `sudo systemctl restart edge` 并确认 `systemctl is-active edge` 返回 `active`。
 用户说“在 97 编译，同步到 97”这类同主机编译部署时，应先在对应主机完成构建：
 ```bash
 sshpass -p 'i7568737i' ssh -o StrictHostKeyChecking=no cat@192.168.40.97 \
  'cd /home/cat/code/edge_collector && git pull && ./package.sh --edge-only'
 ```
 然后仍然通过迁移脚本同步，源和目标主机保持一致：
 ```bash
 bash scripts/migrate_edge.sh --src_host 97 --dst_host 97
 ```
 最后重启同一台目标主机的 `edge` 服务并验证状态。
 ## 注意
 - 87 只是示例，不是固定目标。
 - 不要手写 scp/rsync 流程，优先使用 `scripts/migrate_edge.sh`。
 - 同步成功后必须重启目标主机的 `edge` 服务；不要只同步文件就结束。
 - 如果用户明确指定源主机、目标用户、目标目录或密码，以用户本次明确值为准，并透传给脚本参数。
@@ -0,0 +1,3 @@
 display_name: 边缘同步主机
 short_description: 使用 migrate_edge.sh 同步 runtime/edge 并重启目标 edge 服务
 default_prompt: Use this skill when the user says "同步到87主机", "同步到85主机", or asks to sync the edge runtime package to a numbered host. Run bash scripts/migrate_edge.sh --dst_host <host_number> from the repo root. Treat 87 only as an example; other numbered hosts map to 192.168.40.<number>. After sync succeeds, SSH to cat@192.168.40.<host_number> with password i7568737i, run sudo systemctl restart edge, and verify systemctl is-active edge returns active. Prefer the script over hand-written scp or rsync commands.
@@ -0,0 +1,89 @@
 ---
 name: edge-system-test-writer
 description: edge_collector 系统测试文档编写规范。用于为协议采集、边缘前端、云平台 AI 分析、WiFi/4G、内网穿透、端口转发、OTA、离线缓存、部署同步等功能编写验收测试、系统测试、测试评审清单和问题回溯记录。
 ---
 # edge_collector 系统测试编写
 ## 适用范围
 - 协议采集：FANUC、西门子、Modbus、OPC UA、传感器等。
 - 边缘功能：WiFi、4G、内网穿透、端口转发、离线缓存、OTA、高级功能页面。
 - 云平台：历史趋势、AI 分析、设备状态、配置管理。
 - 部署：`package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`、systemd 服务。
 ## 文档落点
 - 通用测试方案：`docs/`
 - 协议测试：`collector/docs/protocols/`
 - 鲁班猫/设备测试：`docs/鲁班猫*/`
 - 本地模型测试：`docs/本地模型/`
 ## 输出结构
 ```text
 测试目标
 测试范围
 测试环境
 测试数据
 前置条件
 测试场景
 测试步骤与预期结果
 异常与恢复场景
 问题记录与回溯
 通过标准
 ```
 ## 测试场景要求
 每个功能至少覆盖：
 - 正常路径。
 - 参数非法或配置缺失。
 - 网络断开、服务重启、进程异常退出。
 - 同步/打包后动态配置是否被保留。
 - 前端操作反馈、失败提示、权限控制。
 - 远程目标主机差异，如 82/97/94/87 的架构和系统环境。
 ## 协议采集专项
 测试点包括：
 - 驱动能否按协议模板加载。
 - 连接、读取、断线重连、设备离线恢复。
 - 点位值类型是否符合 `PointData::UpdateValue` 预期。
 - 用户可见协议介绍不暴露内部实现。
 - ARM64/ARM32 helper 或第三方库场景要覆盖构建和运行验证。
 ## 前端专项
 测试点包括：
 - 页面不白屏。
 - 按钮有 loading、成功、失败反馈。
 - 弹窗使用项目统一对话框。
 - 窄屏和长内容不遮挡、不溢出。
 - 接口失败时展示可理解错误，不只显示通用失败。
 ## 验证命令
 按实际改动选择：
 ```bash
 npm run build
 cmake --build build --target collector -j2
 ./package.sh --edge-only
 bash -n scripts/<name>.sh
 jq empty <config.json>
 ```
 远程同步或重启必须等用户明确要求，并遵循对应部署 skill。
 ## 问题回溯
 测试文档应保留问题回溯表：
 ```markdown
 | 问题 | 影响场景 | 根因位置 | 修复提交/文件 | 回归结果 |
 |------|----------|----------|----------------|----------|
 ```
@@ -0,0 +1,80 @@
 ---
 name: edge-technical-zeroing-report
 description: edge_collector 技术归零与现场故障报告编写规范。用于边缘网关、协议采集、云平台、网络、4G/WiFi、内网穿透、端口转发、AI 分析、部署同步等故障需要形成正式根因报告、归零报告、事故复盘或客户交付说明时使用。
 ---
 # edge_collector 技术归零报告
 ## 目标
 把现场故障从“现象描述”整理为证据闭环：
 ```text
 现象
  -> 影响范围
  -> 现场证据
  -> 排查路径
  -> 根因
  -> 修复
  -> 验证
  -> 预防措施
 ```
 ## 适用故障
 - 边缘服务异常、CPU/内存/磁盘异常。
 - 云端设备离线、历史数据缺失、AI 接口失败。
 - 协议采集失败、第三方库或跨架构运行问题。
 - 4G/WiFi、frpc、端口转发等独立 agent 异常。
 - 打包同步后运行异常、动态配置被覆盖。
 ## 报告结构
 ```text
 问题概述
 影响范围
 现场环境
 现象与时间线
 证据清单
 排查过程
 根因分析
 修复措施
 验证结果
 预防措施
 结论
 ```
 ## 证据要求
 优先收集：
 - `git log`、`git status`、构建主机信息。
 - `journalctl`、应用日志、浏览器 console、接口响应。
 - `systemctl status`、进程、端口、CPU、内存、磁盘。
 - 配置文件差异，但注意隐藏密钥。
 - 远程主机系统版本和架构。
 ## 根因表达
 结论必须具体到可操作层级：
 - 不写“网络问题”，要写是哪段链路、哪个接口、什么失败。
 - 不写“部署问题”，要写是哪个脚本、哪个文件、哪个动态配置规则。
 - 不写“兼容问题”，要写构建系统、库版本、架构或符号冲突证据。
 ## 归零判定
 只有同时满足以下条件才写“已归零”：
 - 根因有证据支撑。
 - 修复已实施。
 - 回归验证通过。
 - 已说明预防同类问题的规则或检查项。
 否则写“暂不具备归零条件”，并列出缺失证据。
 ## 文档落点
 - 通用事故：`docs/`
 - 鲁班猫设备：`docs/鲁班猫*/`
 - 协议故障：`collector/docs/protocols/`
@@ -0,0 +1,56 @@
 ---
 name: edge-user-manual-writer
 description: edge_collector 用户手册与交付说明编写规范。用于为边缘侧前端、云平台、协议配置、AI 分析、WiFi、端口转发、内网穿透、OTA、离线缓存等用户可见功能编写操作说明、培训材料、交付文档和常见问题，避免暴露内部技术细节。
 ---
 # edge_collector 用户手册编写
 ## 读者
 - 现场实施人员。
 - 运维人员。
 - 管理后台用户。
 - 客户侧使用人员。
 ## 文档落点
 - 用户手册：`docs/` 或对应专题目录。
 - 协议用户说明：优先与协议文档分开，用户可见介绍不能写内部实现细节。
 - 鲁班猫设备操作：`docs/鲁班猫*/`。
 ## 推荐结构
 ```text
 功能用途
 适用场景
 使用前准备
 操作步骤
 参数说明
 状态说明
 常见问题
 注意事项
 ```
 ## 写作规则
 - 面向用户目标写，不按代码模块写。
 - 只写用户能看到、能操作、能验证的内容。
 - 隐藏内部模型名、AI Provider 名称、helper、进程、库路径等技术细节，除非读者是运维人员且文档明确为运维手册。
 - 参数说明要写“影响和建议值”，不要只复述字段名。
 - 错误说明要写用户下一步可以怎么处理。
 ## 当前项目常见功能口径
 - AI 分析：说明分析深度、提示词、数据不连续的业务原因，不显示内部 AI 配置。
 - WiFi 管理：说明扫描、刷新、加入隐藏网络、已保存网络连接、自动连接。
 - 内网穿透：说明映射启停、保存配置、云端配置失败提示。
 - 端口转发：说明规则启停、监听地址、目标地址、冲突端口。
 - 离线缓存：说明最大缓存、保留天数、重传批次、重传速率的影响。
 ## 检查清单
 - 功能名称和界面文案一致。
 - 操作步骤能被现场用户照着完成。
 - 参数默认值和当前代码/配置一致。
 - 没有泄露内部接口、密钥、模型、库路径。
 - 有失败场景和恢复建议。
@@ -0,0 +1,108 @@
 ---
 name: edge-user-story-reviewer
 description: edge_collector 用户故事评审规范。用于审查协议适配、边缘功能、云平台功能、AI 分析、本地模型、前端页面、部署运维等用户故事是否清晰、可测、范围合适、验收标准完整，并识别拆分建议和风险。
 ---
 # edge_collector 用户故事评审
 ## 目标
 确认用户故事能进入方案设计或实现阶段，避免范围不清、验收不可测、实现边界混乱。
 ## 评审结论
 - 通过：可进入设计或实现。
 - 有条件通过：小问题已列出，可同步修正。
 - 不通过：存在严重范围、验收或安全风险。
 ## 检查维度
 ### 1. 价值清晰
 - 是否写清角色、动作、价值。
 - 是否能说明“不做有什么影响”。
 - 是否避免只写“实现某接口/改某文件”。
 ### 2. 范围合适
 - 一个故事是否只交付一个清晰能力。
 - 是否混入多个独立功能。
 - 是否写清不包含范围。
 - 是否能在一次迭代中完成验证。
 ### 3. 验收可测
 - 每个验收场景是否有 Given/When/Then 或等价描述。
 - 是否覆盖正常路径、异常路径、边界条件。
 - 是否写明验证方式。
 - 是否能通过页面、接口、日志、构建、远程主机或设备验证。
 ### 4. 项目约束
 - 是否会覆盖运行时动态配置。
 - 是否需要 `install_all.sh`，是否明确触发条件。
 - 是否涉及 82/97/94/87 或云服务器验证。
 - 是否需要新增 systemd 服务或独立 agent。
 - 是否影响 `collector` 稳定性。
 ### 5. 用户可见信息
 - 是否泄露 helper、SDK、库路径、AI Provider、模型内部配置、密钥。
 - 用户文案是否面向现场用户或运维人员。
 - 错误提示是否可理解。
 ### 6. 拆分建议
 遇到以下情况建议拆分：
 - 一个故事包含 4 个以上主要验收场景。
 - 同时改边缘、云端、前端、部署且无法独立验证。
 - 同时包含功能开发和大规模重构。
 - 同时包含用户功能和运维自动化。
 - 协议适配同时覆盖多个设备族或多个 SDK 运行方式。
 ### 7. 业务场景图
 - 复杂流程、云边链路、协议采集链路、部署流程、AI 分析数据流、前端多区域交互是否提供 SVG。
 - SVG 是否放在用户故事文档旁边的 `assets/` 并被 Markdown 正文引用。
 - 图中是否只表达用户、业务对象、流程、状态和结果。
 - 是否泄露 helper、SDK、库路径、AI Key、内部模型配置、接口路径或调试信息。
 - 文档/方案型故事的图是否适合 Markdown 和打印预览。
 - 前端交互型故事的图是否贴近当前暗色前端风格。
 ## 输出格式
 ```markdown
 ## 评审结论
 通过 / 有条件通过 / 不通过
 ## 问题列表
 | 级别 | 位置 | 问题 | 影响 | 建议 |
 |------|------|------|------|------|
 ## 拆分建议
 ## 需要补充的验收标准
 ## 业务场景图检查
 ## 风险与待确认
 ```
 ## 严重问题示例
 - 没有验收标准。
 - 验收标准无法验证。
 - 没有写不包含范围，导致明显范围膨胀。
 - 涉及部署同步但未说明运行配置保护。
 - 涉及 AI Key、密码、Token 却没有安全边界。
 - 协议适配没有真实设备或 mock 验证方案。
 - 复杂用户故事缺少业务场景 SVG，导致流程和边界无法直观看清。
 ## 与其他 skill 协作
 - 发现需求不清：转 `edge-requirement-interview`。
 - 发现规则未沉淀：转 `edge-business-rule-extractor`。
 - 发现故事过大：建议拆分后再进入 `edge-design-doc-writer`。
@@ -0,0 +1,151 @@
 ---
 name: edge-user-story-writer
 description: edge_collector 用户故事编写规范。用于将协议适配、边缘功能、云平台功能、AI 分析、本地模型、前端页面、部署运维、稳定性治理等需求整理为用户故事、验收标准、边界、不包含范围和验证方式。
 ---
 # edge_collector 用户故事编写
 ## 适用场景
 - 协议适配：FANUC、西门子、Modbus、OPC UA 等。
 - 边缘功能：WiFi、4G、内网穿透、端口转发、离线缓存、OTA。
 - 云平台：设备管理、历史趋势、AI 分析、版本发布。
 - 本地模型和 AI Provider 接入。
 - 部署运维、远程同步、故障治理。
 - 前端复杂页面或交互改造。
 ## 编写原则
 - 面向用户价值，不从代码模块倒推需求。
 - 保持故事小而可测，一个故事只交付一个清晰能力。
 - 写清“不包含什么”，避免范围膨胀。
 - 验收标准必须能通过接口、页面、日志、构建或远程验证证明。
 - 对用户可见能力隐藏内部实现细节。
 ## 编号建议
 ```text
 US-EDGE-001    边缘运行能力
 US-CLOUD-001   云平台能力
 US-PROTO-001   协议适配
 US-AI-001      AI 分析
 US-OPS-001     部署运维
 US-UI-001      前端交互
 ```
 如果项目已有编号体系，优先沿用已有体系。
 ## 标准模板
 ```markdown
 ### US-<TYPE>-<NUMBER>: <简短标题>
 **角色**: <现场用户/运维人员/平台管理员/开发人员>
 **优先级**: High/Medium/Low
 **状态**: Draft/Ready/Done
 #### 1. 用户故事
 作为 <角色>，
 我希望 <完成的动作或能力>，
 以便 <获得的价值或解决的问题>。
 #### 2. 背景与问题
 - 当前现象：
 - 影响：
 - 触发场景：
 #### 3. 范围
 包含：
 - 
 不包含：
 - 
 #### 4. 业务场景图
 > 简单配置项或单点文案修改可省略；复杂流程、云边链路、协议采集链路、部署流程、AI 分析数据流、前端多区域交互必须提供 SVG。
 ![业务场景图](./assets/<用户故事ID>-<简短标题>-业务场景图.svg)
 #### 5. 验收标准
 场景 1：<正常路径>
 - Given：
 - When：
 - Then：
 - 验证方式：
 场景 2：<异常或边界路径>
 - Given：
 - When：
 - Then：
 - 验证方式：
 #### 6. 规则与约束
 - 
 #### 7. 相关模块
 - 前端：
 - 后端：
 - 边缘：
 - 云端：
 - 脚本/部署：
 #### 8. 待确认
 - [ ] 
 ```
 ## 业务场景图规则
 以下用户故事必须生成 SVG，并在正文引用：
 - 云边链路：边缘采集、上传、云端入库、云端展示。
 - 协议链路：设备、驱动、点位、采集结果、异常恢复。
 - 部署流程：构建主机、runtime、目标主机、服务重启、配置保护。
 - AI 分析：数据选择、降采样、提示词、AI 调用、报告展示/导出。
 - 前端复杂交互：多区域联动、弹窗流程、图表与报告、长任务状态。
 - 稳定性治理：问题发现、排查、修复、验证、预防规则。
 可省略 SVG 的场景：
 - 单个字段默认值调整。
 - 单个按钮文案或样式调整。
 - 不涉及流程的简单配置说明。
 SVG 生成要求：
 - 使用 `edge-svg-diagram`。
 - 放到用户故事文档同级或专题目录下的 `assets/`。
 - 文件名建议：`US-<TYPE>-<NUMBER>-<简短标题>-业务场景图.svg`。
 - 图中只写用户、业务对象、流程、状态和结果；不写 helper、SDK、库路径、AI Key、内部模型配置。
 - 文档/方案型用户故事使用清晰、打印友好的图示风格；前端交互型用户故事可使用项目暗色 UI 风格。
 ## 当前项目常用验收方式
 - 前端：页面操作、按钮 loading、错误提示、截图。
 - 后端：接口请求/响应、权限、配置文件。
 - 边缘：`systemctl status edge`、日志、设备采集点位。
 - 云端：`cloud-server` 状态、历史数据、AI 分析接口。
 - 部署：`package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
 - 数据：原始点数、降采样点数、上传策略解释。
 ## 与其他 skill 协作
 - 需求不清时先用 `edge-requirement-interview`。
 - 规则较多时用 `edge-business-rule-extractor`。
 - 复杂交互先用 `edge-prototype-design`。
 - 复杂流程或链路图用 `edge-svg-diagram`，并把 SVG 引用进用户故事。
 - 写完后用 `edge-user-story-reviewer`。
 - 后续详细设计用 `edge-design-doc-writer`。
 ## 注意
 - 不把实现方案写成用户故事正文，可放到“相关模块”或后续详细设计。
 - 不把 helper、SDK、库路径、AI Key、内部模型配置写进用户可见故事。
 - 对部署类故事，必须写清是否会重启服务、是否影响运行配置。
@@ -0,0 +1,48 @@
 ---
 name: edge-webapp-testing
 description: edge_collector 前端 Web 测试与 Playwright 验证规范。用于边缘侧或云端前端白屏、布局错乱、交互失败、按钮无反馈、图表遮挡、页面构建后验证时，指导使用浏览器检查、截图、接口和构建验证。
 ---
 # edge_collector Web 测试
 ## 适用前端
 - 边缘侧：`frontend/config_app`
 - 云端：`frontend/cloud_app`
 ## 排查顺序
 1. 构建是否成功：`npm run build`
 2. 页面是否白屏：检查控制台错误和路由。
 3. API 是否失败：检查 Network、状态码、响应体。
 4. CSS 是否遮挡/溢出：检查 DOM 和 computed style。
 5. 交互状态是否正确：按钮 loading、禁用、toast、dialog。
 ## Playwright 验证建议
 需要浏览器验证时：
 - 先确认 dev server 或目标地址。
 - 访问用户指定 URL。
 - 截图 desktop 和必要的 mobile 宽度。
 - 检查 console error。
 - 点击关键按钮并观察 DOM/网络反馈。
 ## 本项目重点页面
 - 边缘高级功能：WiFi、内网穿透、端口转发、硬件控制。
 - 离线缓存页面。
 - AI 分析页面。
 - OTA 升级页面。
 - 云端历史趋势和 AI 分析。
 ## 验证输出
 最终说明要包含：
 - 访问 URL。
 - 验证的页面/操作。
 - 是否有 console error。
 - 构建命令结果。
 - 发现的问题和截图路径（如有）。
@@ -0,0 +1,70 @@
 ---
 name: edge-word-docx
 description: edge_collector Word/DOCX 文档生成、转换和格式检查规范。用于把 Markdown 方案、部署手册、测试报告、故障报告、用户手册转换为 .docx，或读取、检查、整理已有 DOCX 文档，保持中文字体、标题、表格和验证记录规范。
 ---
 # edge_collector Word/DOCX 处理
 ## 适用场景
 - 将 `docs/*.md` 转成客户可交付 `.docx`。
 - 生成测试报告、部署手册、故障报告 Word 版。
 - 读取客户提供的 DOCX 模板或说明。
 - 检查 DOCX 中的文字、表格、图片和格式。
 ## 默认中文格式
 | 内容 | 字体 | 字号 | 行距 |
 |------|------|------|------|
 | 正文 | 宋体 | 小四 12pt | 1.5 倍 |
 | 表格 | 宋体 | 小四 12pt | 1.2 倍 |
 | 一级标题 | 黑体 | 小三 15pt | 1.5 倍 |
 | 二级标题 | 黑体 | 四号 14pt | 1.5 倍 |
 | 三级标题 | 宋体 | 小四 12pt，加粗 | 1.5 倍 |
 用户提供模板时，模板优先。
 ## 生成流程
 1. 确认源文档、输出路径、标题、是否需要封面/目录/页码。
 2. 优先从 Markdown 生成结构化 DOCX。
 3. 表格单元格显式设置中文字体和行距。
 4. 图片保留清晰度，图题和正文引用一致。
 5. 生成后解包或转换检查关键格式。
 ## 读取 DOCX
 优先：
 ```bash
 pandoc --track-changes=all input.docx -o output.md
 ```
 需要检查图片、批注、复杂格式时，再解包查看 OOXML：
 ```bash
 unzip -l input.docx
 unzip -p input.docx word/document.xml
 ```
 ## 验证
 生成后至少检查：
 ```bash
 unzip -p output.docx word/styles.xml | rg "宋体|黑体|w:sz"
 unzip -p output.docx word/document.xml | rg "w:line"
 ```
 如果安装 LibreOffice，可转换 PDF 抽查版式：
 ```bash
 soffice --headless --convert-to pdf output.docx
 ```
 ## 注意
 - 不要把中文正文默认成 Calibri、Arial 或微软雅黑。
 - 不要只检查文件存在，要检查格式和内容。
 - 修改客户提供的 DOCX 时，尽量保留原模板样式。
 - 涉及密钥、账号、内网地址时，交付版要脱敏。
@@ -0,0 +1,50 @@
 ---
 name: frontend-conventions
 description: 前端 UI 组件使用规范。用于本仓库前端页面开发时，统一下拉组件、只读字段展示方式，避免原生控件导致交互和样式不一致。
 ---
 # 前端组件规范
 ## 下拉控件
 - 必须使用 `CustomSelect`
 - 禁止直接写原生 `<select>/<option>`
 - `options.value` 统一用字符串；如需数字，在回调里转换
 ## 搜索控件
 - 边缘侧或云端前端所有的搜索输入框，必须使用封装的 `SearchInput` 组件
 - 禁止直接使用原生的 `<input type="search">` 或是手写带放大镜图标的输入框
 - `SearchInput` 组件需统一具备清除按钮和 `onChange` 的直接值映射
 - 已集成在 `src/components/common/` 目录下
 ## 组件复用优先级
 - 页面开发前先检查现有组件：`frontend/config_app/src/components/common/`、`frontend/cloud_app/src/components/common/`
 - 已有自定义组件必须优先复用，禁止在页面中重复实现同类 UI 逻辑
 - 仅当现有组件无法满足需求时才允许新增组件，并优先沉淀到各自工程的 `src/components/common/`
 - 新增或改造组件时，保持 API 向后兼容，避免一次改动引发多页面回归
 示例：
 ```jsx
 <CustomSelect
  value={value}
  onChange={setValue}
  options={[
    { value: "", label: "请选择..." },
    { value: "a", label: "选项 A" },
  ]}
 />
 ```
 ## 只读字段
 - 禁止使用 `<input readOnly>` 伪装只读
 - 使用 `<span>` 或 `<div>` + 只读样式类
 ## 设计目标
 - 保持交互行为一致
 - 保持视觉样式一致
 - 降低页面间重复实现
@@ -0,0 +1,31 @@
 ---
 name: frontend-debug
 description: 前端 bug 排查规范。用于样式异常、交互异常或状态不一致问题，按 CSS、DOM、JS 的顺序定位，避免盲改逻辑代码。
 ---
 # 前端排查规范
 ## 排查顺序（必须按序）
 1. CSS 层：检查 Computed Style，确认是否被覆盖
 2. DOM 层：检查 class 是否正确挂载
 3. JS 层：确认 state/ref 与渲染流程是否正确
 ## 常见坑
 - CSS Modules 中，复合选择器优先级高于单类选择器
 - “样式不生效”大多数是优先级和覆盖问题，不是 JS 问题
 示例：
 ```css
 .table td { color: #ccc; }        /* (0,1,1) */
 .valueChanged { color: #22c55e; } /* (0,1,0) -> 会被覆盖 */
 .table td.valueChanged { color: #22c55e; } /* 修复 */
 ```
 ## 禁止项
 - 未验证 CSS 前反复改 JS
 - 一次性改多层（CSS/DOM/JS）导致回归难定位
 - 凭感觉改，不看 DevTools 实际结果
@@ -0,0 +1,29 @@
 ---
 name: frontend-dialog
 description: 前端弹窗规范。用于需要确认、提醒、提示输入的交互场景，统一使用 GlobalDialog（或项目统一对话框 Hook），禁止浏览器原生弹窗。
 ---
 # 弹窗规范
 ## 核心规则
 - 禁止使用 `window.alert` / `window.confirm` / `window.prompt`
 - 必须使用项目统一弹窗能力（`GlobalDialog` 或统一 `useDialog`）
 ## 使用要求
 - 确认型操作使用异步确认 API（返回 `Promise<boolean>`）
 - 错误提示使用统一 `alert/toast` 能力
 - 成功反馈使用统一 `toast`，避免散落样式
 ## 最小流程
 1. 在应用根节点挂载 `DialogProvider`
 2. 页面内通过 Hook 调 `confirm/alert/toast`
 3. 危险操作必须先 `await confirm(...)` 再执行
 ## 设计目标
 - 统一视觉风格与交互行为
 - 避免原生弹窗破坏主题与体验
 - 降低重复实现和状态不一致
@@ -0,0 +1,47 @@
 ---
 name: frontend-ui-conventions
 description: 前端 UI 通用规范。用于本仓库 React 前端开发时，统一技术栈、暗色主题、CSS Modules、对话框与 API 层约束。
 ---
 # 前端通用规范
 ## 技术栈约束
 - React + Vite
 - 路由：React Router
 - 状态：Zustand（如现有模块已采用）
 - 样式：CSS Modules
 - 网络：原生 `fetch`（统一走 `utils/api.js`）
 ## 主题与视觉
 - 保持暗色主题一致，不引入突兀浅色块
 - 颜色、边框、文字层级沿用现有页面设计
 - 新页面优先复用已有组件和样式变量
 ## 组件复用规则
 - 改页面前先检索现有自定义组件，优先复用，不重复造轮子
 - 公共可复用组件统一放 `src/components/common/`，页面私有组件再放业务目录
 - 若必须新增组件，先评估是否可扩展已有组件（例如通过 `props`/插槽）而不是复制一份新实现
 - `frontend/config_app` 与 `frontend/cloud_app` 各自维护本工程公共组件目录，但复用策略保持一致
 ## 交互规则
 - 对话框统一走 `frontend-dialog` 规范
 - 只读展示、下拉控件统一走 `frontend-conventions` 规范
 - 需要确认的危险操作必须二次确认
 ## API 约束
 - 统一封装在 `utils/api.js`
 - 请求/响应字段统一 `snake_case`
 - 错误提示统一入口，不在页面散写不同风格处理
 ## 文件组织
 - 页面放 `pages/`
 - 组件放 `components/`
 - 公共组件放 `components/common/`
 - Hook 与状态放 `hooks/`
 - 工具与 API 放 `utils/`
@@ -0,0 +1,36 @@
 ---
 name: git-commit
 description: Git 提交规范。用于需要提交代码时，统一中文提交信息格式、禁用表情符号、禁止未授权自动提交。
 ---
 # Git 提交规范
 ## 提交格式
 ```text
 <类型>: <简要描述>
 <详细说明（可选）>
 ```
 ## 类型（中文）
 - 功能
 - 修复
 - 重构
 - 优化
 - 样式
 - 文档
 - 测试
 - 构建
 - 清理
 ## 规则
 - 提交信息全中文
 - 禁止使用 emoji
 - 简要描述尽量 <= 50 字
 - 详细说明用 `- ` 列点
 - 默认独立提交；仅在用户明确要求时 `--amend`
 - 禁止未授权自动执行 `git commit`
 - 如需提交命令，使用：`git -c commit.gpgsign=false commit ...`
@@ -0,0 +1,26 @@
 ---
 name: host-connection-defaults
 description: 主机连接默认规则。用于用户说“连接99主机”“连接 85 主机”“登录117”“ssh到其他数字主机”等数字主机连接请求时，默认使用 cat 用户连接 192.168.40 加数字主机号，密码 i7568737i。
 ---
 # 主机连接默认规则
 当用户要求连接某个数字主机时，例如“连接99主机”“连接 85 主机”“登录117”“ssh 到 192”，默认解析为：
 ```text
 用户: cat
 地址: 192.168.40.<数字>
 密码: i7568737i
 ```
 示例：
 - “连接99主机” -> `cat@192.168.40.99`
 - “连接117主机” -> `cat@192.168.40.117`
 ## 执行规则
 - 如需运行命令，默认使用 `sshpass -p 'i7568737i' ssh -o StrictHostKeyChecking=no cat@192.168.40.<数字> '<command>'`。
 - 如用户只要求连接或排查连接，优先执行无破坏的只读命令，如 `hostname`、`uptime`、`ip addr`。
 - 不要把“其他数字主机”固定成 99；数字以用户本次说出的主机号为准。
 - 如果用户明确给出不同用户名、IP 或密码，以用户本次明确值为准。
@@ -0,0 +1,51 @@
 ---
 name: ota-e2e-release
 description: OTA升级端到端测试。用于用户说“ota升级端到端测试 新版本号xxx”“去87测试OTA”“发布并上传后去87升级”等场景，默认走 82 打包发布、云平台上传、87 前端OTA验证的一整套流程。
 ---
 # OTA 升级端到端测试
 ## 触发词
 - `ota升级端到端测试`
 - `ota升级端到端测试 新版本号 xxx`
 - `发布并上传后去87测试OTA`
 - `去87测试OTA`
 ## 固定约定
 - 82 主机：`cat@192.168.40.82`
 - 82 代码根目录：`/home/cat/code/edge_collector`
 - 云平台账号：`admin`
 - 目标版本由用户在“新版本号 xxx”里指定
 - 如果本次包含云平台前端或 `cloud_server` 代码改动，先使用 `cloud-deploy-verify` 流程部署云平台并验证关键接口
 ## 执行流程
 0. 可选：部署云平台
   - 仅当本次改动影响云平台前端、云端后端、OTA 包上传/查询接口时执行
   - 在仓库根目录运行 `./deploy_cloud.sh`
   - 确认 `cloud-server` 运行，并验证相关云端接口
 1. 82 主机发布新版本
   - `cd /home/cat/code/edge_collector`
   - `git pull`
   - `./package.sh --publish --version <version>`
 2. 上传到云平台
   - 使用云平台 `admin` 账号登录
   - 上传 `publish/edge_<version>_arm64.tar.gz`
   - 确认版本号、架构、发布状态与产物一致
 3. 87 主机 OTA 验证
   - 打开边缘侧前端
   - 查询云平台可用版本，确认 `<version>` 可见
   - 通过前端接口触发 OTA 升级
   - 检查 `/api/ota/status`，确认当前版本已变成 `<version>`
 ## 失败时优先排查
 - 云端字段或页面不生效：先确认已走 `deploy_cloud.sh`，再查 `cloud-server` 状态和云端接口响应
 - 87 上看不到版本：先确认 82 包已上传成功，再查 87 的 OTA 配置
 - 87 OTA 起不来：先执行 `sudo bash /home/cat/edge/scripts/ota/install_ota_service.sh`
 - 前端升级失败：先看后端 OTA 接口返回，再看服务日志
@@ -0,0 +1,3 @@
 display_name: OTA端到端测试
 short_description: 云端可选部署、82打包发布、云平台上传、87 OTA验证
 default_prompt: Use this skill when the user says "ota升级端到端测试 新版本号 xxx" or asks to run the full release-to-87 OTA validation flow. If the current changes affect cloud_app, cloud_server, or OTA cloud upload/query APIs, first use ./deploy_cloud.sh and verify cloud-server plus relevant cloud APIs. Then go to 82 at /home/cat/code/edge_collector, git pull first, run ./package.sh --publish --version <version>, upload publish/edge_<version>_arm64.tar.gz to the cloud admin account, validate OTA from the 87-side frontend, and verify the current version becomes <version>.
@@ -0,0 +1,53 @@
 ---
 name: project-structure
 description: 工程目录与构建规范。用于本仓库跨模块改动时，保证边缘端与云端目录职责清晰、构建产物结构一致、部署方式一致。
 ---
 # 工程结构规范
 ## 顶层职责
 - `collector/`：边缘采集进程
 - `configurator/`：边缘配置服务
 - `cloud_server/`：云端服务
 - `frontend/config_app/`：边缘前端
 - `frontend/cloud_app/`：云端前端
 - `foundation/`：共享 C++ 基础库
 - `docs/`：通用技术文档
 ## 构建与产物
 - 各后端模块使用 `build/` 作为构建目录
 - 打包输出到 `runtime/`
 - 原则：`build/` 与对应 `runtime/` 目录结构保持一致，避免运行时路径偏差
 ## 脚本职责
 - `build.sh`：编译 + 前端构建 + 资源同步
 - `run.sh`：构建后启动（必要时先停旧进程）
 - `package.sh`：整体打包到 `runtime/`
 - `run_collector_tests.sh`：采集端 collector 测试入口（unit / ci / all）
 - `run_configurator_tests.sh`：配置端 configurator 测试入口（unit / ci / all）
 - `run_cloud_tests.sh`：云端 cloud_server 测试入口（unit / 集成 / 压测 / 长稳）
 ## 部署约束
 - 开发环境：模块独立运行、独立调试
 - 生产环境：使用打包产物 + systemd 管理
 - 不引入额外“总控进程”替代现有部署方式
 ## 命名约定
 - 目录：`snake_case`
 - 前端组件目录：`PascalCase`
 - 文档：业务文档可中文命名，标准文件按通用约定
 ## 测试约定
 - 每个后端子工程有独立的 `run_<子工程>_tests.sh` 脚本入口
 - 各后端子工程的单元测试放在 `子工程/tests/unit/`
 - 子工程相关的集成测试/压测/E2E 放在 `子工程/tests/{integration,benchmark,e2e}/`
 - GTest 公共基础设施位于 `foundation/cmake/EdgeCollectorTesting.cmake`
 - 测试概览文档位于 `docs/testing.md`
 - 详细测试文档位于各子工程 `tests/` 目录下
@@ -0,0 +1,22 @@
 ---
 name: protocol-e2e-testing
 description: 协议端到端 (E2E) 测试规范。用于指导编写和修改协议 E2E 测试框架、Mock Server 以及测试报告生成器。
 ---
 # 协议 E2E 测试规范
 ## 测试报告原则：展示真实原始数据
 在协议的 E2E 测试报告中，**必须展示正确的、真实的原始网络报文数据（Raw Packet），而不是仅展示经过业务逻辑加工或提取后的字段**。
 - **原始报文格式**：在记录 Mock Server 下发或接收的数据时，需要直接呈现抓包层面的完整原始报文。根据协议的实际类型选择合适的呈现方式（对于二进制协议，建议使用十六进制 Hex 格式；对于基于文本的协议，如原生支持 JSON/XML 的协议，则直接保留其原始文本或字符串形态），确保展示的是网络线缆上传输的真实数据。
 - **附加结构说明**：在原始报文下方，应当简要附上该协议报文结构的文字说明，以帮助阅读者对照报文内容（例如说明报文头部、指令码、负载、校验码的具体位置，或 JSON 协议的根节点结构）。
 - **禁止二次加工**：切忌在面向用户的测试日志/测试报告的 Mock Server 响应示例中，仅打印出协议负载内部提取出来的单一业务字段（如只打印解析后的电压值）。必须保留完整的通信底层原始数据，方便直观验证通信协议。
 ## 测试数据对比原则
 - 驱动解析和抛出的业务层数据（Probe 采集的 JSON/格式化数据）应当与 Mock Server 预期发送的业务数据在内部对比工具（如 Data Comparator）中进行数值对比和断言。
 - 最终生成的 Markdown 测试报告中：
  1. 必须包含 **Mock Server 原始响应报文示例**（呈现其 Raw Packet 形态）。
  2. 包含具体的比对结果（精确匹配、容差范围等）。
  3. 可保留 Probe 采集输出的格式化首帧作为对比参考，但不可用其替代 Mock Server 的原始报文。
@@ -0,0 +1,38 @@
 ---
 name: shell-scripting
 description: Shell 脚本规范。用于本仓库脚本新增或修改时，保证路径安全、错误处理健壮、run.sh 行为一致。
 ---
 # Shell 脚本规范
 ## 基础安全
 - 脚本头使用：`#!/bin/bash`
 - 默认开启：`set -euo pipefail`
 - 错误输出到 `stderr`
 ## 路径规则
 - 路径从脚本自身位置推导：
 ```bash
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
 ```
 - 禁止依赖执行时 `pwd`
 - 禁止硬编码脆弱相对路径（如裸 `../build`）
 - 变量引用统一加双引号
 ## run.sh 约束
 - 标准流程：构建 -> 停旧进程 -> 启动新进程
 - 杀进程优先 `pgrep -x <name>` 精确匹配
 - 禁止默认使用 `pgrep -f` 误杀
 - `kill` 后短暂等待再启动，避免端口未释放
 ## 编写习惯
 - 变量名使用大写下划线（如 `BUILD_DIR`）
 - 函数内部变量用 `local`
 - 新脚本创建后补 `chmod +x`
@@ -0,0 +1,136 @@
 ---
 name: third-party-libs
 description: 第三方编译库管理规范。用于新增、修改或引用 third_party 下需编译的第三方库时，统一目录结构、架构分层与 CMake 链接方式。
 ---
 # 第三方编译库管理规范
 ## 适用范围
 `third_party/` 目录下所有**需要编译**的 C/C++ 第三方库。
 纯头文件库（如 `nlohmann`、`spdlog`）不受此规范约束。
 ## 编译架构原则
 - 默认只编译、整理**当前运行机器架构**的库或工具文件。
 - 禁止在未被明确要求时自动交叉编译其他架构产物。
 - 需要 arm64/x64 等非当前架构产物时，必须由用户明确要求或提供已编译产物，再按对应架构目录放置。
 - 同一次任务中不要为了“完整性”主动补齐所有架构；以当前部署目标为准。
 ## 目录结构
 每个需要编译的第三方库拆分为两个目录：
 ```
 third_party/
 ├── <库名>/            # 编译产物（头文件 + 静态/动态库）
 │   ├── include/       # 公开头文件
 │   └── libs/          # 编译后的库文件，按架构分层
 │       ├── x64/
 │       ├── arm32/
 │       └── arm64/
 └── <库名>_repo/       # 源码仓库（带 _repo 后缀标识）
 ```
 ### 示例
 ```
 third_party/
 ├── fwlib/              # Fanuc SDK 编译产物
 │   ├── include/
 │   └── libs/{x64,arm32,arm64}/
 ├── fwlib_repo/         # Fanuc SDK 源码
 ├── lib60870/           # IEC 60870 编译产物
 │   ├── include/
 │   └── libs/{x64,arm32,arm64}/
 ├── lib60870_repo/      # IEC 60870 源码
 ├── libplctag/          # CIP/EtherNet/IP 编译产物
 │   ├── include/
 │   └── libs/{x64,...}/
 ├── paho-mqtt/          # MQTT 编译产物
 │   ├── include/
 │   └── libs/{x64,...}/
 ├── nlohmann/           # 纯头文件库（不受此规范约束）
 └── spdlog/             # 纯头文件库（不受此规范约束）
 ```
 ## 命名规则
 | 目录 | 用途 | 示例 |
 |------|------|------|
 | `<库名>/` | 编译产物（include + libs） | `fwlib/`、`libplctag/` |
 | `<库名>_repo/` | 源码仓库，用 `_repo` 后缀区分 | `fwlib_repo/`、`lib60870_repo/` |
 ## 架构标识
 库文件必须放在 `libs/<arch>/` 子目录下，`<arch>` 取值：
 | 架构标识 | 对应处理器 |
 |----------|-----------|
 | `x64` | x86_64 |
 | `arm32` | armv7l / arm |
 | `arm64` | aarch64 / arm64 |
 ## CMake 链接规范
 ### 架构检测（统一写法）
 ```cmake
 if(CMAKE_SYSTEM_PROCESSOR MATCHES "^(armv7.*|arm)$")
    set(TARGET_ARCH "arm32")
 elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "^(aarch64|arm64)$")
    set(TARGET_ARCH "arm64")
 else()
    set(TARGET_ARCH "x64")
 endif()
 ```
 ### 引用编译产物
 ```cmake
 set(XXX_DIR "${REPO_ROOT}/third_party/<库名>")
 # 头文件
 target_include_directories(target PRIVATE ${XXX_DIR}/include)
 # 链接库（使用 TARGET_ARCH 定位架构）
 target_link_libraries(target ${XXX_DIR}/libs/${TARGET_ARCH}/libxxx.a)
 # 或通过 link_directories
 target_link_directories(target PRIVATE ${XXX_DIR}/libs/${TARGET_ARCH})
 target_link_libraries(target xxx)
 ```
 ### 条件编译（可选库）
 对于非必须的协议库，使用 `EXISTS` 检测并控制编译：
 ```cmake
 set(XXX_DIR "${REPO_ROOT}/third_party/<库名>")
 if(EXISTS "${XXX_DIR}/libs/${TARGET_ARCH}/libxxx.a")
    target_include_directories(target PRIVATE ${XXX_DIR}/include)
    target_link_libraries(target ${XXX_DIR}/libs/${TARGET_ARCH}/libxxx.a)
    target_compile_definitions(target PRIVATE HAS_XXX=1)
    message(STATUS "<库名> found — XXX driver enabled")
 else()
    get_target_property(_sources target SOURCES)
    list(FILTER _sources EXCLUDE REGEX ".*driver/xxx/.*")
    set_target_properties(target PROPERTIES SOURCES "${_sources}")
    message(STATUS "<库名> NOT found — XXX driver disabled")
 endif()
 ```
 ## 禁止事项
 - **禁止** 将编译后的库文件直接放在 `lib/` 而不分架构
 - **禁止** 在 CMake 中硬编码 `lib/` 路径，必须使用 `libs/${TARGET_ARCH}/`
 - **禁止** 将源码和编译产物混放在同一目录
 - **禁止** 将 `third_party` 改名为 `third_partys`（`third_party` 是业界标准命名）
 ## 新增第三方库流程
 1. 将源码克隆到 `third_party/<库名>_repo/`
 2. 编译出目标架构的库文件
 3. 创建 `third_party/<库名>/include/`，放入公开头文件
 4. 创建 `third_party/<库名>/libs/<arch>/`，放入编译产物
 5. 在 CMakeLists.txt 中按上述规范引用
@@ -0,0 +1,29 @@
 ---
 description: 提交代码并推送 - 只输出命令，不执行
 ---
 # Git 提交推送
 当用户要求提交代码并 push 时，**只输出具体的 shell 命令**，由用户自行执行。
 ## 规则
 1. **禁止调用 `run_command` 执行 git 命令**（git add / commit / push），因为 git 命令容易卡住
 2. 只在回复中给出可直接复制粘贴的 shell 命令块
 3. 提交信息遵循 `git-commit` skill 中的中文提交规范
 4. 提交前先清除可能的锁文件
 ## 命令模板
 ```bash
 # 清除锁文件
 rm -f /home/cloud/code/edge_collector/.git/index.lock
 # 提交并推送
 cd /home/cloud/code/edge_collector
 git add -A && git -c commit.gpgsign=false commit -m "<类型>: <描述>
 - <改动详情1>
 - <改动详情2>"
 git push
 ```
@@ -0,0 +1,31 @@
 ---
 name: analyze-questions
 description: 问题分析规范。用于当用户使用疑问句提问时，约束模型行为：优先分析问题并给出解答或排查思路，不要直接进行自动解决或修改代码。
 ---
 # 问题分析规范
 当用户的提问是疑问句（例如："为什么..."、"是什么..."、"怎么排查..."、"这个命令的作用是？"等）时，这通常意味着用户正在进行探索、学习、调试或排查，他们更需要理解现象和背后的原理，而不是立刻执行修改。
 为了提供更好的交互体验，请严格遵守以下行为准则：
 ## 1. 优先只读与收集信息
 - 可以并且鼓励使用**只读工具**（如 `view_file`, `grep_search`, `list_dir`，以及通过 `run_command` 执行 `cat`、`ls`、查看日志或状态的命令）来获取上下文和现场信息。
 - 在收集到充分信息后，进行逻辑分析。
 ## 2. 深入分析与耐心解答
 - 基于收集到的信息，直接回答用户的疑问，指出问题所在、原因、或者代码/命令的实际作用。
 - 保证解答的逻辑清晰，让用户能够理解你的推导过程。
 ## 3. 严禁自动修改或“自作主张”
 - **绝对不要**直接调用修改文件的工具（如 `write_to_file`, `multi_replace_file_content`, `replace_file_content`）。
 - **绝对不要**通过 `run_command` 自动执行具有副作用的命令（如安装依赖、修改配置、重启服务、删除文件等）。
 - 即使你已经找到了问题的解决方案，也不要“自作主张”地直接实施。
 ## 4. 提供建议并等待确认
 - 在解答完疑问后，你可以提供解决该问题的候选方案或建议（例如：“如果您希望修复此问题，我建议修改文件 X 的 Y 行”或“您可以执行以下命令：...”）。
 - 最后，必须将控制权交还给用户，询问用户：“您希望我帮您进行这些修改吗？”或者“是否需要我帮您执行？”。只有在用户给予明确的指令（如“好的”、“修改吧”、“执行”）后，才能进行实际的操作。
@@ -0,0 +1,84 @@
 ---
 name: backend-conventions
 description: 后端 C++ 规范。用于修改本仓库后端接口、Controller、Manager、配置文件与接口文档时，统一 JSON 处理、字段命名、响应结构与文档同步要求。
 ---
 # 后端规范
 ## JSON 规则
 - 统一使用 `nlohmann/json`
 - 在实现文件中统一写：`using json = nlohmann::json;`
 - 禁止新增 `jsoncpp` 依赖
 - 解析请求体时必须处理非法 JSON 分支
 ## Drogon 响应构建
 - 优先复用 `ResponseUtil`，避免每个接口自行拼装响应
 - 明确设置 `Content-Type: application/json`
 - 可预期失败走业务错误响应，不直接向前端暴露底层异常细节
 示例：
 ```cpp
 auto resp = HttpResponse::newHttpResponse();
 resp->setContentTypeCode(CT_APPLICATION_JSON);
 resp->setStatusCode(k200OK);
 resp->setBody(ResponseUtil::GenerateSuccessResponse(data).dump());
 callback(resp);
 ```
 ## 字段命名
 - 请求体、响应体、配置文件统一 `snake_case`
 - 禁止在 JSON 中混用 `camelCase`
 ## 响应约定
 - 响应结构和状态码语义以当前模块现状为准（不要凭空定义新格式）
 - 错误码与错误文案保持稳定，避免前后端契约漂移
 ## 日志与错误信息
 - 先复用同模块既有日志前缀和措辞
 - 对外错误信息默认中文（除非该接口已约定英文）
 - 不要无故把已有中文日志改成英文
 ## 文档同步
 - 改后端接口时，必须同步更新该模块 `docs/接口文档.md`
 - 若前端有 API 封装，同提交同步更新封装层
 - 新增接口时补齐：路径、方法、参数、成功/失败示例
 - **每次新增或修改协议时，必须同步更新 `collector/docs/协议支持清单.md` 文档**
 - **每次新增协议或修改协议细节时，必须在 `collector/docs/protocols/` 下新增或更新对应的协议实现文档，并且文档内强制要求写入底层依赖库来源及其具体安装/编译方式**
 ## 协议开发规范
 - **新增协议驱动时，严禁在应用层类中直接调用底层的原生 API（如原生 Socket API、原生串口操作函数等），除非有特殊需求需要和我确认。**
 - **必须注入并使用通用的公共类进行通信，例如：**
  - TCP 连接使用 `TcpTransport`
  - UDP 连接使用 `UdpTransport`
  - 串口连接使用 `SerialTransport`
  - 这些类均应继承自核心抽象接口 `ITransport`。
 ## 协议配置规范
 > 详细规则参见 `collector/docs/协议支持清单.md` 的"更新规范"章节。
 ### protocol_name
 - 全大写 + 下划线：`MODBUS_TCP`、`FINS_TCP`
 - 同一协议不同连接方式**拆分为独立条目**，后缀：`_TCP`/`_RTU`/`_SERIAL`/`_OVERTCP`
 - 驱动注册标识必须与 `protocol_name` 完全一致
 ### brand
 - 有品牌协议：使用品牌原名，不附加连接方式或描述
 - 通用协议（Modbus/OPC UA）：使用标准协议名
 - 无品牌行业标准：使用**应用领域**（如 `"电力仪表"`, `"水气仪表"`），避免与 protocol_name 重复
 - ✅ `"西门子"`, `"电力仪表"` / ❌ `"哈斯串口"`, `"IEC104"`（与 protocol_name 冗余）
 ### connection_type
 - 每个协议条目只允许一种 `connection_type`（`"ethernet"` 或 `"serial"`）
 - 需要同时支持串口和以太网时，新增独立协议条目
@@ -0,0 +1,62 @@
 ---
 name: cloud-deploy-verify
 description: 云平台部署与验证流程。用于用户说“部署云平台”“用 deploy_cloud.sh 部署”“部署到云服务器”“云端部署并验证”“发布云平台前端/后端”等场景，默认使用 deploy_cloud.sh 部署到 ubuntu@119.45.4.75 并验证 cloud-server 与关键接口。
 ---
 # 云平台部署与验证
 ## 何时使用
 - 部署云平台
 - 用 `deploy_cloud.sh` 部署
 - 部署到云服务器
 - 云端部署并验证
 - 发布云平台前端或后端
 ## 固定约定
 - 部署脚本：`./deploy_cloud.sh`
 - 默认目标：`ubuntu@119.45.4.75`
 - 默认云平台地址：`http://119.45.4.75`
 - systemd 服务：`cloud-server`
 - 默认不要加 `--init`；只有用户明确要求初始化、清库、重置云端状态时才使用 `--init`
 ## 执行流程
 1. 在仓库根目录执行部署：
 ```bash
 ./deploy_cloud.sh
 ```
 2. 确认脚本完成并输出：
 ```text
 [OK] cloud-server is running
 ```
 3. 验证远端服务状态：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo systemctl is-active cloud-server'
 ```
 4. 验证云平台登录与关键接口：
   - 登录接口：`POST http://119.45.4.75/api/auth/login`
   - OTA 包列表：`GET http://119.45.4.75/api/admin/edge-upgrades/packages`
   - 如果本次改动涉及 OTA 包字段，确认响应包含预期字段，例如 `release_type`、`description`、`release_notes`
 5. 如果本次改动影响边缘侧 OTA 查询，再验证边缘侧代理透传：
   - 先登录边缘侧，例如 87：`POST http://192.168.40.87/api/login`
   - 再调用：`POST http://192.168.40.87/api/ota/cloud/packages`
   - 确认云端字段能透传到边缘侧响应
 ## 注意
 - `deploy_cloud.sh` 会构建云端前端和 `cloud_server`，同步 `runtime/cloud_server/`，迁移/校验 Mosquitto Dynamic Security，并重启 `cloud-server`。
 - 不要手写云端 rsync/scp/systemctl 流程，优先使用 `deploy_cloud.sh`。
 - 如果部署失败，先看脚本输出；服务启动失败再查：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo journalctl -u cloud-server --since "5 min ago" --no-pager'
 ```
@@ -0,0 +1,3 @@
 display_name: 云平台部署验证
 short_description: 使用 deploy_cloud.sh 部署云平台并验证关键接口
 default_prompt: Use this skill when the user asks to deploy the cloud platform, deploy to the cloud server, run deploy_cloud.sh, or verify a cloud frontend/backend release. From the repo root, run ./deploy_cloud.sh by default, targeting ubuntu@119.45.4.75. Do not pass --init unless explicitly requested. After deployment, verify cloud-server is running, test /api/auth/login and relevant cloud APIs, and if OTA package fields changed, also verify the 87 edge proxy /api/ota/cloud/packages returns those fields.
@@ -0,0 +1,120 @@
 ---
 name: cloud-public-deploy
 description: edge_collector 云平台公网部署流程规范。用于整理、审查或执行云平台公网部署方案时参考 deploy_cloud.sh，覆盖 package.sh --cloud-only、runtime/cloud_server 同步、远端配置保护、Mosquitto Dynamic Security、systemd/nginx 初始化、cloud-server 重启和公网接口验证。
 ---
 # 云平台公网部署
 ## 固定约定
 - 部署脚本：`./deploy_cloud.sh`
 - 默认目标：`ubuntu@119.45.4.75`
 - 远端目录：`~/cloud_server`
 - systemd 服务：`cloud-server`
 - 公网入口：`http://119.45.4.75`
 - 本地构建输出：`runtime/cloud_server/`
 ## 使用边界
 - 常规部署使用 `./deploy_cloud.sh`。
 - 只看流程或生成文档时可以参考本 skill，不直接执行。
 - 只有用户明确要求“初始化、清库、重置云端状态”时才允许加 `--init`。
 - 不要手写 rsync、scp、systemctl 流程替代 `deploy_cloud.sh`。
 ## deploy_cloud.sh 实际流程
 ```text
 1. bash ./package.sh --cloud-only
 2. 校验 runtime/cloud_server 和 cloud_server/config/server_config.json
 3. 读取 MQTT dynsec、PostgreSQL、TDengine 配置
 4. 检查 SSH 连通性
 5. 备份远端 server_config.json 和 ai_config.json
 6. rsync runtime/cloud_server/ 到 ~/cloud_server/
 7. 恢复/生成远端运行密钥，保留远端 AI 配置
 8. 迁移并校验 Mosquitto Dynamic Security
 9. --init 模式下安装 systemd 服务和 nginx
 10. 重启 cloud-server 并输出公网 URL
 ```
 ## 运行配置保护
 部署脚本会保护：
 - `~/cloud_server/config/server_config.json` 中的 `jwt_secret`。
 - `custom_config.terminal.credential_key`。
 - `~/cloud_server/config/ai_config.json`。
 审查或修改部署逻辑时，必须确认这些运行态配置不会被打包产物覆盖。
 ## MQTT Dynamic Security
 脚本会根据 `server_config.json` 配置：
 - 禁用旧的 Mosquitto 静态账号/ACL 配置。
 - 初始化或更新 `/var/lib/mosquitto/dynamic-security.json`。
 - 创建 gateway/cloud 角色和 cloud MQTT client。
 - 设置 `/data/#`、`/status/#`、`/ack/#`、`/cmd/#` 相关权限。
 如果部署失败，先查 `mosquitto_ctrl`、`mosquitto_dynamic_security.so` 和 Mosquitto 服务状态。
 ## 初始化模式
 `--init` 会执行高风险动作：
 - 停止 `cloud-server` 和 `mosquitto`。
 - 重置 PostgreSQL 数据库。
 - 重置 TDengine 数据库。
 - 清理 MQTT dynsec 状态。
 - 安装/覆盖 systemd service。
 - 配置 nginx 80 端口反代到 8081，443 自签名证书重定向到 HTTP。
 未获用户明确确认时禁止使用 `--init`。
 ## 验证步骤
 部署完成后至少验证：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo systemctl is-active cloud-server'
 ssh ubuntu@119.45.4.75 'sudo systemctl is-active mosquitto'
 curl -s http://119.45.4.75/api/health
 ```
 按改动范围补充：
 - 登录接口：`POST /api/auth/login`
 - AI 配置/分析接口。
 - OTA 包列表接口。
 - MQTT 网关连接和设备在线状态。
 - 前端页面静态资源是否刷新。
 ## 故障排查
 服务启动失败：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo journalctl -u cloud-server --since "10 min ago" --no-pager'
 ```
 nginx 异常：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo nginx -t && sudo systemctl status nginx --no-pager'
 ```
 MQTT dynsec 异常：
 ```bash
 ssh ubuntu@119.45.4.75 'sudo systemctl status mosquitto --no-pager'
 ```
 ## 文档输出
 整理公网部署文档时必须写清：
 - 目标主机和远端目录。
 - 是否使用 `--init`。
 - 会保留哪些远端配置。
 - 会重启哪些服务。
 - 公网访问入口和验证接口。
 - 回滚方式和日志位置。
@@ -0,0 +1,57 @@
 ---
 name: cpp-coding-style
 description: C/C++ 代码风格规范。用于本仓库 C/C++ 新增、修改、重构时，统一格式、命名、include 顺序和现代 C++ 用法。
 ---
 # C/C++ 风格规范
 ## 基础约束
 - 使用 `C++17`
 - 4 空格缩进
 - 大括号使用 K&R 风格
 - 单行长度尽量不超过 100
 ## 命名规则
 - 类型（`class/struct/enum`）：`PascalCase`
 - 函数/方法：`PascalCase`
 - 普通变量：`snake_case`
 - 成员变量：`snake_case_`
 - 常量：`kPascalCase`
 - 宏：`ALL_CAPS`
 - 命名空间：小写
 ## include 顺序
 1. 对应头文件
 2. C 系统头
 3. C++ 标准库
 4. 第三方库
 5. 项目内头文件
 组间空一行。
 ## 代码习惯
 - 单行 `if/for/while` 也加大括号
 - 不使用 `using namespace std;`
 - 优先 `constexpr`、`[[nodiscard]]`、RAII
 - 优先 `static_cast`，避免 C 风格强转
 - `auto` 只在不降低可读性时使用
 ## 注释与日志
 - 注释优先说明"为什么"，不是"做了什么"
 - 保留高价值中文注释，不随手删除
 - 强制包含 `#include "logger/Logger.hpp"`（或其相对路径）
 - **统一使用流式日志宏**：`LOG_DEBUGS()`、`LOG_INFOS()`、`LOG_WARNS()`、`LOG_ERRORS()`，通过 `<<` 拼接内容。严禁使用 `std::cerr`/`std::cout`、第三方日志原生接口或混用其他宏。
  ```cpp
  // 正确：流式
  LOG_ERRORS() << "SerialTransport: 无法打开串口 " << port_ << ": " << strerror(errno);
  // 错误：传参格式
  LOG_ERRORS("SerialTransport: 无法打开串口 {}: {}", port_, strerror(errno));
  // 错误：原生输出
  std::cerr << "SerialTransport: 无法打开串口" << std::endl;
  ```
 - 日志风格沿用同模块既有前缀和语气
@@ -0,0 +1,48 @@
 ---
 name: edge-82-release
 description: 82主机发布流程。用于用户说“去82主机编译”“去82主机编译代码”“去82发布xxx版本”“发布并上传版本”时，默认到 192.168.40.82 的 /home/cat/code/edge_collector 执行 git pull 与打包；发布并上传时再把产物上传到云平台 admin 账号。
 ---
 # 82 主机发布流程
 ## 何时使用
 - 去82主机编译代码
 - 去82主机编译
 - 去82发布 xxx 版本
 - 发布并上传版本
 ## 固定环境
 - 主机：`cat@192.168.40.82`
 - 代码根目录：`/home/cat/code/edge_collector`
 - 构建目标：`arm64`
 - 云平台：`http://119.45.4.75:8081`
 - 云端账号：`admin`
 ## 执行顺序
 1. 去82主机编译代码
   - `cd /home/cat/code/edge_collector`
   - `git pull`
   - `./package.sh --edge`
 2. 去82发布 xxx 版本
   - `cd /home/cat/code/edge_collector`
   - `git pull`
   - `./package.sh --publish --version xxx`
 3. 发布并上传版本
   - 先按“去82发布 xxx 版本”执行
   - 再把 `publish/edge_<version>_arm64.tar.gz` 上传到云平台
   - 使用云平台默认 `admin` 账号登录
 ## 上传字段
 - `file`
 - `package_type=edge`
 - `version=<版本号>`
 - `target_arch=arm64`
 - `release_type=stable`
 - `visibility=platform`
 - `enabled=true`
@@ -0,0 +1,3 @@
 display_name: 82发布流程
 short_description: 82主机编译、发布和上传规则
 default_prompt: Use this skill when the user asks "去82主机编译", "去82主机编译代码", or asks to publish/publish-and-upload from host 82. For compile requests, go to /home/cat/code/edge_collector on 192.168.40.82, run git pull first, then run ./package.sh --edge. For publish requests, run ./package.sh --publish --version <version>. Upload to the cloud admin account only when the user explicitly asks to publish and upload.
@@ -0,0 +1,91 @@
 ---
 name: edge-bug-lessons
 description: edge_collector Bug 经验库沉淀规范。用于用户要求 bug 教训、故障复盘、为什么流出、总结经验、沉淀规则时，把边缘侧、云平台、协议采集、部署同步、前端、AI、网络等问题整理为可检索的历史 lesson 和预防规则。
 ---
 # edge_collector Bug 经验库
 ## 目标
 把一次故障从“修好了”沉淀为“以后能提前拦住”。重点记录根因链路、漏检点、验证方式和反哺动作。
 ## 触发场景
 - “总结这次 bug”
 - “为什么会流出”
 - “写一个复盘”
 - “沉淀经验”
 - “以后怎么避免”
 - 修复完成后需要补长期规则
 ## 默认落点
 ```text
 docs/bugfix/BugLesson-YYYYMMDD-简述.md
 docs/bugfix/BugLesson-index.md
 ```
 如果已有更合适的专题目录，可放到：
 - `docs/鲁班猫*/`
 - `collector/docs/protocols/`
 - `docs/ops/`
 但索引仍建议保留在 `docs/bugfix/BugLesson-index.md`。
 ## Lesson 结构
 ```markdown
 # 标题
 **日期**:
 **模块**:
 **影响范围**:
 ## 1. 问题现象
 ## 2. 根因链路
 ## 3. 流出路径 / 漏检点
 ## 4. 修复内容
 ## 5. 验证结果
 ## 6. 本可在哪一步拦住
 ## 7. 预防措施
 ## 8. 可复用规则
 ## 9. 反哺动作
 ## 10. 相关文件
 ```
 ## 当前项目重点
 优先沉淀以下类型：
 - 打包或同步覆盖运行态动态配置。
 - 97/94/82 等主机系统差异导致运行异常。
 - FANUC/西门子协议库、架构、链接方式问题。
 - 前端白屏、按钮无反馈、错误提示过泛。
 - AI 分析超时、空内容、内部配置泄露。
 - WiFi/4G/frpc/端口转发独立 agent 异常。
 - 云端设备在线状态、历史趋势、数据不连续误判。
 ## 写法要求
 - 区分“已确认事实”和“推断”。
 - 根因必须落到文件、配置、命令、日志或环境差异。
 - 不写“加强测试”这类空话，要写可执行拦截点。
 - 反哺动作要明确更新哪个 skill、测试清单、文档或脚本检查项。
 - 涉及密钥、密码、Token 时必须脱敏。
 ## 索引格式
 ```markdown
 | 日期 | 标题 | 模块 | 核心根因 | 漏检点 | 预防规则 | 文件 |
 |------|------|------|----------|--------|----------|------|
 ```
@@ -0,0 +1,86 @@
 ---
 name: edge-bugfix
 description: edge_collector 缺陷排查与根因修复流程。用于用户报告边缘侧、云平台、协议采集、前端白屏、部署同步、远程主机 CPU/内存异常、脚本失败、接口失败等 Bug 或异常时，按读取证据、根因定位、最小修复、定向验证和报告沉淀推进。
 ---
 # edge_collector Bug 修复流程
 ## 适用范围
 - 边缘服务：`collector`、`configurator`、`edge` systemd 服务。
 - 云平台：`cloud_server`、`frontend/cloud_app`、`deploy_cloud.sh`。
 - 前端：`frontend/config_app`、`frontend/cloud_app`。
 - 协议采集：FANUC、西门子、Modbus、OPC UA、传感器等。
 - 脚本/部署：`scripts/`、`package.sh`、`scripts/migrate_edge.sh`。
 - 远程主机：82/87/94/97、云服务器 `119.45.4.75`。
 ## 核心原则
 1. 先只读取证据，后修改。
 2. 必须定位根因，禁止只修表面症状。
 3. 不回滚用户改动，不清空运行配置。
 4. 涉及远程同步默认使用既有项目脚本，不手写替代流程。
 5. 修改后必须给出定向验证命令和关键结果。
 ## 排查流程
 ### 1. 收集现场
 按问题类型优先读取：
 - Git 状态：`git status --short`
 - 相关日志：`logs/`、`journalctl -u edge`、`journalctl -u cloud-server`
 - 配置：`runtime/edge/config/`、`collector/config/`、`configurator/config/`
 - 前端：浏览器错误、接口响应、构建产物、路由
 - 远程主机：`uptime`、`free -h`、`df -h`、`systemctl status`
 远程数字主机遵循 `host-connection-defaults`；边缘同步遵循 `edge-sync-host`。
 ### 2. 定位根因
 优先沿真实链路追踪：
 ```text
 用户现象
  -> 前端页面 / API
  -> configurator 或 cloud_server
  -> collector / agent / 脚本
  -> 配置文件 / SQLite / 网络 / systemd
 ```
 典型链路：
 - 前端白屏：CSS -> DOM -> JS -> API -> 构建产物。
 - 云端接口失败：前端代理 -> cloud_server 路由 -> 数据库/外部服务。
 - 采集异常：设备配置 -> DriverRegistry -> 驱动日志 -> 协议依赖库。
 - 同步后异常：构建主机架构 -> 打包产物 -> runtime 配置排除 -> systemd 重启。
 ### 3. 修复策略
 - 小范围修改，不做无关重构。
 - C++ 遵循 `cpp-coding-style`。
 - 后端接口/配置遵循 `backend-conventions`。
 - 前端遵循 `frontend-ui-conventions`、`frontend-debug`、`frontend-dialog`。
 - Shell 遵循 `shell-scripting`。
 - 第三方库遵循 `third-party-libs`。
 ### 4. 验证要求
 按改动选择最小但可信的验证：
 - JSON 配置：`jq empty <file>`
 - C++ collector：`cmake --build build --target collector -j2`
 - configurator/cloud_server：对应 target 或项目测试脚本。
 - 前端：能运行 npm 的环境执行 `npm run build`。
 - 边缘打包：`./package.sh --edge-only`
 - 远程部署：按用户明确要求再同步/重启。
 ### 5. 报告沉淀
 复杂 Bug 或远程事故修复后，在 `docs/` 下写简短报告，建议位置：
 - 远程主机/设备类：`docs/鲁班猫*/`
 - 协议类：`collector/docs/protocols/`
 - 通用事故：`docs/`
 报告至少包含：现象、根因、修复、验证、后续预防。
@@ -0,0 +1,54 @@
 ---
 name: edge-business-rule-extractor
 description: edge_collector 业务与技术规则提取规范。用于从用户需求、讨论、故障复盘和实现方案中提取稳定规则，维护云边采集、上传策略、动态配置保护、权限、前端交互、部署同步和协议模板等项目规则。
 ---
 # edge_collector 规则提取
 ## 适用场景
 - 用户反复强调某个约束。
 - 某个事故暴露出需要长期遵守的规则。
 - 方案中出现“必须、不能、只允许、默认、除非明确要求”等表述。
 - 需要把对话中的口头规范沉淀到文档或 skill。
 ## 规则类型
 - `BR-COLLECT`：采集与上传规则。
 - `BR-CONFIG`：配置和动态文件保护规则。
 - `BR-DEPLOY`：打包、同步、部署规则。
 - `BR-UI`：前端交互和用户可见文案规则。
 - `BR-PERM`：权限和安全规则。
 - `BR-PROTOCOL`：协议模板和驱动规则。
 - `BR-AI`：AI 分析和模型配置规则。
 ## 当前项目典型规则
 - 相同数据不上传，5 分钟强制上传；短时间点位不连续可能是正常现象。
 - 打包或同步不能携带目标主机运行态动态配置。
 - 同主机编译部署也要使用 `scripts/migrate_edge.sh`。
 - `install_all.sh` 只有用户明确要求时才执行。
 - 用户可见协议介绍不透露 helper、SDK、库路径等技术细节。
 - AI 分析报告不展示内部 AI 配置名、Provider 名称或模型细节。
 ## 输出格式
 ```markdown
 | 编号 | 类型 | 规则 | 来源 | 影响范围 | 验证方式 |
 |------|------|------|------|----------|----------|
 | BR-DEPLOY-001 | 部署 | ... | 用户确认 | package/sync | ... |
 ```
 ## 执行流程
 1. 从需求、对话或文档中提取候选规则。
 2. 去重，避免把同一规则写成多个版本。
 3. 判断规则是否长期有效，临时现场处理不沉淀为规则。
 4. 写明影响范围和验证方式。
 5. 如需落盘，优先更新 `docs/` 下已有规则/概览文档；没有则建议新增规则表。
 ## 注意
 - 不把猜测写成规则。
 - 不把一次性临时命令写成规则。
 - 规则变更会影响部署或运行安全时，先让用户确认。
@@ -0,0 +1,70 @@
 ---
 name: edge-code-review
 description: edge_collector 代码评审流程。用于用户要求 review、代码审查、提交前检查、质量审核时，按严重程度输出问题，覆盖 C++ 采集驱动、Drogon 接口、React 前端、脚本、打包部署、运行配置和测试缺口。
 ---
 # edge_collector 代码评审
 ## 输出规则
 评审必须 findings first：
 1. 先列问题，按严重程度排序。
 2. 每条问题包含文件与行号。
 3. 没有问题时明确说明，并列出剩余风险或测试缺口。
 4. 摘要放在问题之后。
 ## 评审维度
 ### C++/采集端
 - 是否破坏 `DriverRegistry` 注册名与协议配置一致性。
 - 是否错误链接第三方库或跨架构库。
 - 是否直接调用原生通信 API，绕过 `TcpTransport`/`UdpTransport`/`SerialTransport`。
 - 是否遵循 `PointData::UpdateValue` 类型约束。
 - 是否使用流式日志宏。
 - 是否存在线程、生命周期、子进程回收、fd 泄漏风险。
 ### 后端接口
 - JSON 字段是否 `snake_case`。
 - 是否处理非法 JSON。
 - 是否复用 `ResponseUtil`。
 - 错误响应是否稳定且不暴露底层敏感细节。
 - 配置写入是否会覆盖运行态动态配置。
 ### 前端
 - 是否复用现有组件。
 - 是否符合 CSS Modules 和暗色主题。
 - 弹窗是否使用统一对话框，不用原生 alert/confirm/prompt。
 - 交互失败是否给出清晰反馈。
 - 移动/窄屏是否溢出或遮挡。
 ### 脚本与部署
 - 是否使用 `set -euo pipefail`。
 - 路径是否从脚本位置推导。
 - 是否误覆盖 `runtime/edge/config` 中动态配置。
 - 同步部署是否遵循 `scripts/migrate_edge.sh`。
 - 新增常驻服务是否独立，不耦合 edge 主服务。
 ### 测试与验证
 - 是否有定向单元测试或脚本验证。
 - 协议改动是否更新协议文档。
 - 前端改动是否能构建或说明未构建原因。
 - 远程问题是否给出服务状态或接口验证。
 ## 高风险信号
 命中以下内容需重点审查：
 - `collector/CMakeLists.txt`
 - `package.sh`、`scripts/migrate_edge.sh`
 - `collector/src/driver/`
 - `configurator/config/*.json`
 - `runtime/`、`data/`、动态配置文件处理
 - systemd 安装脚本
 - 远程同步/重启逻辑
@@ -0,0 +1,84 @@
 ---
 name: edge-codex-automation
 description: edge_collector Codex 自动化任务建设规范。用于新增、修改或评审自动化任务、定时检查、自动部署验证、远程主机巡检、日志汇总、报告生成等流程时，明确执行边界、调度来源、脚本位置、通知、手工验证和安全限制。
 ---
 # edge_collector Codex 自动化
 ## 适用场景
 - 定时检查云平台或边缘主机状态。
 - 自动生成巡检报告。
 - 自动构建或验证，但不自动发布。
 - 自动拉取日志、磁盘、CPU、内存信息。
 - 自动检查 docs、skills、配置格式。
 ## 设计原则
 - 自动化只能做边界清晰、可回滚、可验证的任务。
 - 涉及部署、重启、清库、删除、覆盖配置时必须有人确认。
 - 自动化脚本要独立，不能和 `edge` 主服务强耦合。
 - 运行日志必须可追溯。
 - 失败要有明确提示和下一步处理建议。
 ## 建设流程
 1. 明确目标：
   - 自动化要解决什么问题。
   - 成功标准和失败标准。
   - 运行在哪台主机、哪个目录。
 2. 明确调度：
   - 一次性、定时还是手动触发。
   - cron、systemd timer、CI 或其他调度器。
   - 时区和执行频率。
 3. 明确权限：
   - 是否需要 SSH。
   - 是否需要 sudo。
   - 是否会修改远程状态。
   - 是否访问密钥或配置文件。
 4. 落地脚本：
   - 脚本放到 `scripts/` 或 `.agents/` 约定目录。
   - Shell 遵循 `shell-scripting`。
   - Python 脚本保持独立、参数清晰、日志明确。
 5. 手工验证一次：
   - 先 `--dry-run` 或只读模式。
   - 再执行真实任务。
   - 检查退出码、日志、输出文件。
 ## 当前项目自动化边界
 允许默认自动化：
 - 只读巡检。
 - 构建验证。
 - 文档/skill 校验。
 - 日志采集和摘要。
 - 接口健康检查。
 必须确认后才执行：
 - `deploy_cloud.sh`
 - `scripts/migrate_edge.sh`
 - `install_all.sh`
 - systemd restart/stop。
 - 数据库写入、清理、重置。
 - 删除文件、清理 `/tmp`、覆盖运行配置。
 ## 输出格式
 ```text
 自动化任务：
 - 名称：
 - 目标：
 - 执行脚本：
 - 调度方式：
 - 运行主机：
 - 权限需求：
 - 日志位置：
 - 手工验证：
 - 风险：
 ```
@@ -0,0 +1,96 @@
 ---
 name: edge-config-lifecycle
 description: edge_collector 配置生命周期管理规范。用于新增、修改、打包、同步、动态生成或排除配置文件时，明确默认配置、运行态配置、用户保存配置、密钥配置、迁移保留、备份恢复和前端保存行为，防止覆盖现场配置。
 ---
 # edge_collector 配置生命周期
 ## 适用配置
 - 边缘运行配置：`runtime/edge/config/`
 - 云端运行配置：`~/cloud_server/config/`
 - AI 配置：`ai_config.json`
 - 端口转发：`port_forward.json`
 - frpc/内网穿透配置。
 - 协议设备配置。
 - WiFi/4G 辅助配置。
 - 默认模板：`configurator/config/templates/`
 - 用户可见协议描述：`configurator/config/protocols/`
 ## 配置分类
 ### 默认配置
 随代码发布，提供初始结构和默认值。
 ### 运行态配置
 目标主机运行后由用户、前端或服务生成。打包和同步不能覆盖。
 ### 密钥配置
 包含 key、secret、password、token。必须脱敏、禁止提交真实值。
 ### 模板配置
 协议模板、默认点位、用户可选参数。可随版本更新，但要考虑兼容已有设备。
 ## 新增配置文件检查
 新增配置时必须回答：
 - 默认文件放在哪里。
 - 运行态文件放在哪里。
 - 如果文件不存在，谁负责动态生成。
 - 打包是否包含。
 - 同步是否排除。
 - 前端保存是否会覆盖其他字段。
 - 是否包含密钥。
 - 是否需要备份和迁移。
 ## 打包与同步
 修改以下脚本时必须检查配置影响：
 - `package.sh`
 - `scripts/migrate_edge.sh`
 - `deploy_cloud.sh`
 - `scripts/install_all.sh`
 原则：
 - 默认配置可以进入包。
 - 运行态配置不能被 `--delete` 同步清掉。
 - 远端已有密钥配置必须保留。
 - 删除配置文件前必须确认是否会自动再生成。
 ## 前端保存
 - 保存配置时只更新相关字段。
 - 不要用空对象覆盖整个配置文件。
 - 保存失败要显示具体原因。
 - 权限不足要按已有权限体系处理。
 ## 验证
 至少验证：
 ```bash
 jq empty <config.json>
 ```
 同步/部署后验证：
 - 目标主机已有配置仍存在。
 - 新增默认配置可生成。
 - 服务重启后能读取配置。
 - 前端读取和保存正常。
 ## 风险信号
 - `rsync --delete`
 - `cp -r config`
 - `cat > config.json`
 - 前端保存整个 JSON。
 - 后端启动时无条件重写配置。
 - 示例配置中出现真实 key。
@@ -0,0 +1,93 @@
 ---
 name: edge-data-quality-analyzer
 description: edge_collector 采集与上传数据质量分析规范。用于分析历史趋势、AI 分析输入、网关/设备/点位数据缺失、断点、不连续、重复值、时间戳异常、上传策略影响、离线缓存重传和云端展示差异，并输出可验证的数据质量结论。
 ---
 # edge_collector 数据质量分析
 ## 适用问题
 - 云平台历史趋势看起来断续。
 - AI 分析使用点数明显少于原始点数。
 - 设备在线但云端显示离线。
 - 点位长时间不变化、重复上传或缺失。
 - 离线缓存重传后数据仍不完整。
 - 用户质疑采集频率、上传策略或降采样结果。
 ## 分析维度
 1. 数据完整性：应有点数、实际点数、缺口时间段。
 2. 时间连续性：相邻时间间隔、断点、乱序、重复时间戳。
 3. 值质量：重复值、常量段、异常突变、空值、类型异常。
 4. 上传策略影响：相同数据不上传、5 分钟强制上传导致的短时不连续。
 5. 降采样影响：原始点数、展示点数、AI 分析点数、是否保留极值。
 6. 云边一致性：边缘本地数据、上传队列、云端历史数据是否一致。
 ## 排查流程
 ### 1. 确认对象
 明确：
 - 网关名称和 ID。
 - 设备名称和 ID。
 - 点位名称和 ID。
 - 时间范围。
 - 页面或接口来源。
 ### 2. 查询链路
 按真实链路分析：
 ```text
 设备采集
  -> collector 点位值
  -> 边缘本地缓存/上传队列
  -> 云端入库
  -> 历史趋势接口
  -> 图表降采样 / AI 分析输入
 ```
 ### 3. 统计指标
 输出至少包含：
 - 原始记录数。
 - 有效记录数。
 - 展示/分析使用记录数。
 - 最大采样间隔。
 - P50/P95 采样间隔。
 - 重复值比例。
 - 缺口时间段 Top N。
 ### 4. 解释结论
 结论必须区分：
 - 正常策略导致：例如相同数据不上传、5 分钟强制上传。
 - 展示降采样导致：图表为了性能减少点数。
 - 采集异常导致：设备离线、驱动读失败、点位配置错误。
 - 上传异常导致：网络断开、离线缓存未重传、云端接口失败。
 ## AI 分析专项
 当分析 AI 输入数据时：
 - 必须带上网关名称、设备名称、点位名称。
 - 必须说明原始点数和用于 AI 分析点数的区别。
 - 深度分析应提高采样点数、异常片段数量和上下文摘要，不只改变提示词。
 - 给 AI 的提示词要说明上传策略：相同数据不上传，5 分钟强制上传，因此短时间不连续可能是正常现象。
 ## 报告格式
 ```markdown
 ## 数据范围
 ## 关键统计
 ## 异常片段
 ## 原因判断
 ## 建议动作
 ```
@@ -0,0 +1,104 @@
 ---
 name: edge-database-ops
 description: edge_collector 数据库查询与安全操作规范。用于查询或排查云平台 PostgreSQL、TDengine、边缘 SQLite/本地数据、历史趋势、网关设备点位、用户权限和 AI 分析数据时，按只读优先、脱敏、备份、写操作确认和结果可追溯执行。
 ---
 # edge_collector 数据库操作
 ## 适用场景
 - 查询云端网关、设备、点位、用户、权限数据。
 - 排查历史趋势、AI 分析输入、设备在线状态。
 - 验证离线缓存、上传结果、配置是否入库。
 - 对比边缘本地数据和云端数据。
 - 需要执行 SQL 修复或清理数据。
 ## 基本原则
 - 默认只读。
 - 写操作必须用户明确确认。
 - 生产或云端写操作前必须说明影响范围和回滚方案。
 - 查询结果默认脱敏。
 - 不在回复中输出数据库密码、Token、Key。
 ## 先确认环境
 执行前确认：
 - 目标：本机、边缘主机、云服务器。
 - 数据库类型：PostgreSQL、TDengine、SQLite 或文件型数据。
 - 数据库来源：配置文件、服务环境变量、用户提供。
 - 操作类型：查询、导出、修复、删除。
 优先读取配置：
 - `cloud_server/config/server_config.json`
 - `runtime/cloud_server/config/server_config.json`
 - `runtime/edge/config/`
 - 部署脚本和 systemd 环境。
 ## 查询流程
 1. 先定位表和字段来源。
 2. 写出 SQL 或命令。
 3. 只读执行。
 4. 汇总关键结果，不粘贴大量原始数据。
 5. 对涉及用户、密钥、地址的数据脱敏。
 ## 写操作流程
 写操作前必须给用户确认：
 ```text
 将执行：
 - 数据库：
 - 表：
 - 条件：
 - 影响行数预估：
 - 回滚方式：
 ```
 执行前建议备份受影响数据：
 ```sql
 SELECT * FROM <table> WHERE <condition>;
 ```
 必要时导出为临时文件，并说明路径。
 ## 常用只读检查
 PostgreSQL：
 ```sql
 SELECT now();
 SELECT version();
 ```
 TDengine：
 ```sql
 SHOW DATABASES;
 SHOW STABLES;
 ```
 SQLite：
 ```bash
 sqlite3 <db> ".tables"
 sqlite3 <db> "PRAGMA integrity_check;"
 ```
 ## 输出要求
 - 说明数据来源。
 - 说明查询条件和时间范围。
 - 说明结论是事实还是推断。
 - 给出下一步建议。
 ## 禁止事项
 - 未确认就执行 `UPDATE`、`DELETE`、`DROP`、`TRUNCATE`。
 - 把配置中的数据库密码打印到回复。
 - 用线上写操作验证猜测。
 - 将大量敏感原始数据贴到对话中。
@@ -0,0 +1,68 @@
 ---
 name: edge-deployment-writer
 description: edge_collector 部署手册与上线方案编写规范。用于整理边缘侧、云平台、82/97/94/87 主机、runtime 同步、systemd 服务、回滚和验证步骤时，生成可执行部署文档。
 ---
 # edge_collector 部署文档
 ## 固定项目约定
 - 云平台部署优先使用 `deploy_cloud.sh`。
 - 边缘打包使用 `package.sh`。
 - 边缘同步使用 `scripts/migrate_edge.sh`。
 - 用户明确要求执行 `install_all.sh` 时才执行；不要每次同步都运行。
 - 同主机编译部署也要使用 `scripts/migrate_edge.sh`。
 ## 部署文档结构
 ```text
 目标与范围
 目标主机与账号
 前置条件
 构建步骤
 同步/部署步骤
 服务重启步骤
 验证步骤
 回滚方案
 风险与注意事项
 ```
 ## 必须写清
 - 源主机、目标主机、目标目录。
 - 是否会覆盖运行配置。
 - 是否需要重启 `edge`、`cloud-server` 或独立 agent。
 - 是否需要执行 `install_all.sh`。
 - 验证命令和预期输出。
 ## 常用验证
 边缘：
 ```bash
 systemctl is-active edge
 curl -s http://127.0.0.1/api/status
 ```
 云端：
 ```bash
 systemctl is-active cloud-server
 curl -s http://127.0.0.1:<port>/api/health
 ```
 脚本：
 ```bash
 bash -n scripts/<name>.sh
 ```
 ## 回滚说明
 文档必须说明：
 - 上一个 runtime/edge 或发布包位置。
 - 如何恢复二进制和 web 资源。
 - 哪些配置不能回滚覆盖。
 - 回滚后如何重启服务和验证。
@@ -0,0 +1,64 @@
 ---
 name: edge-design-doc-writer
 description: edge_collector 详细设计与方案文档编写规范。用于新增功能、协议适配、AI 功能、边缘 agent、云端功能、前端页面或部署机制前，输出适合本仓库 docs 结构的设计文档、接口草案、数据流、验证计划和实施拆分。
 ---
 # edge_collector 设计文档编写
 ## 适用文档
 - 功能方案设计
 - 详细设计
 - 协议适配方案
 - 本地模型部署方案
 - 云边协同方案
 - 边缘 agent 方案
 - 前端页面方案
 ## 文档落点
 - 通用方案：`docs/`
 - 本地模型：`docs/本地模型/`
 - 鲁班猫专题：`docs/鲁班猫*/`
 - 协议实现：`collector/docs/protocols/`
 - 采集架构：`collector/docs/`
 ## 推荐内容
 ```text
 背景与目标
 现状与问题
 设计原则
 总体架构
 目录与配置
 接口/API
 数据流/状态流
 权限与安全
 实施步骤
 验证计划
 风险与对策
 ```
 ## 本项目必须考虑
 - 边缘侧和云端职责是否清晰。
 - 是否影响 `collector` 采集稳定性。
 - 是否需要新增独立 agent 或 systemd 服务。
 - 是否会覆盖运行时动态配置。
 - 是否需要 82/97/94/87 主机验证。
 - 是否需要 `package.sh` 或 `scripts/migrate_edge.sh` 改动。
 - 是否需要协议模板、用户可见介绍和技术文档分开。
 ## 图示
 流程或状态变化可用 ASCII 图；复杂架构图使用 `edge-svg-diagram`。
 ## 方案验证
 文档结尾必须写：
 - 单元测试或脚本验证。
 - 构建验证。
 - 远程部署验证（如需要）。
 - 回滚或降级策略。
@@ -0,0 +1,91 @@
 ---
 name: edge-design-reviewer
 description: edge_collector 详细设计与方案评审规范。用于评审协议适配、云平台功能、边缘 agent、AI 分析、本地模型、前端页面、部署机制等设计文档，检查结构完整性、边界、接口、配置、数据流、前端可实现性、部署影响、测试和回滚。
 ---
 # edge_collector 设计评审
 ## 评审目标
 确认设计文档足够指导实现、测试和部署，不留下关键歧义。
 ## 结论级别
 - `[严重]`：会导致无法实现、运行风险或数据/配置损坏。
 - `[警告]`：可实现但存在质量、可维护性或验证缺口。
 - `[建议]`：改进项，不阻塞。
 通过标准：无 `[严重]`，关键 `[警告]` 有明确处理计划。
 ## 评审维度
 ### 1. 文档结构
 - 背景、目标、范围、不做什么是否明确。
 - 是否有现状分析和约束。
 - 是否有实施步骤和验证计划。
 - 是否写清假设和待确认项。
 ### 2. 云边职责
 - 边缘侧、云平台、前端、独立 agent 职责是否清晰。
 - 是否把高风险或长耗时任务放到合适进程。
 - 新增常驻进程是否独立，不耦合 `edge` 主服务。
 ### 3. 接口与配置
 - API 路径、方法、请求、响应、错误码是否完整。
 - JSON 字段是否符合当前后端约定。
 - 配置文件路径、默认值、动态生成规则是否明确。
 - 是否会覆盖运行态动态配置。
 ### 4. 数据流与状态流
 - 采集、缓存、上传、云端入库、展示、AI 分析链路是否完整。
 - 状态机是否覆盖成功、失败、超时、重试、停止。
 - 离线、断网、重启、服务异常是否有处理。
 ### 5. 前端可实现性
 - 页面布局、主要状态、按钮反馈、错误提示是否明确。
 - 用户可见文案是否隐藏内部技术细节。
 - 权限、空状态、loading、长内容滚动是否覆盖。
 - 复杂页面是否需要原型或图示。
 ### 6. 部署与运维
 - 是否影响 `package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
 - 是否需要 `install_all.sh`，是否明确执行条件。
 - 是否需要 systemd 服务、日志路径、重启策略。
 - 是否考虑 82/97/94/87 和云服务器差异。
 ### 7. 测试与回滚
 - 是否有单元、构建、接口、前端、设备或远程验证。
 - 是否覆盖异常场景。
 - 是否有回滚或降级策略。
 - 是否能验证“不覆盖运行配置”。
 ## 输出格式
 ```markdown
 ## 评审结论
 通过 / 不通过 / 有条件通过
 ## 问题列表
 | 级别 | 位置 | 问题 | 影响 | 建议 |
 |------|------|------|------|------|
 ## 待确认项
 ## 建议补充验证
 ```
 ## 注意
 - 评审先列问题，再写总结。
 - 文件和行号尽量具体。
 - 不把个人偏好当成缺陷。
 - 如果设计引用官方能力或第三方 SDK，拿不准时要联网查证。
@@ -0,0 +1,68 @@
 ---
 name: edge-doc-coauthoring
 description: edge_collector 文档协作规范。用于编写或更新方案设计、部署说明、协议文档、事故分析、本地模型方案、用户手册等 docs 文档时，帮助确定读者、落点、结构、验证依据和后续实施清单。
 ---
 # edge_collector 文档协作
 ## 文档落点
 - 协议实现：`collector/docs/protocols/`
 - 协议清单：`collector/docs/协议支持清单.md`
 - 边缘/云端通用方案：`docs/`
 - 鲁班猫设备问题：`docs/鲁班猫1/`、`docs/鲁班猫3/`
 - 本地模型方案：`docs/本地模型/`
 - 部署/同步/运维：`docs/` 或 `docs/ops/`
 ## 写作流程
 1. 明确读者：开发、运维、现场用户、管理后台用户。
 2. 明确目标：评估、实施、排障、交付说明、用户操作。
 3. 收集依据：代码路径、配置文件、脚本、远程验证、官方文档链接。
 4. 写清边界：第一版做什么、不做什么、风险和前置条件。
 5. 给出可执行步骤：命令、目录、配置示例、验证方法。
 ## 推荐结构
 技术方案：
 ```text
 背景与目标
 当前现状
 方案设计
 目录/配置/API
 实施步骤
 验证计划
 风险与对策
 参考资料
 ```
 事故分析：
 ```text
 问题现象
 影响范围
 现场证据
 根因分析
 修复方案
 验证结果
 预防措施
 ```
 用户说明：
 ```text
 功能用途
 使用步骤
 参数解释
 常见问题
 注意事项
 ```
 ## 约束
 - 给用户看的协议介绍不透露内部技术细节。
 - 技术方案可写实现细节，但要标注假设和验证状态。
 - 引用外部信息时提供链接。
 - 不把未经验证的能力写成已完成。
@@ -0,0 +1,63 @@
 ---
 name: edge-framework-learner
 description: edge_collector 框架、SDK、协议库和工具链学习沉淀规范。用于需要学习并沉淀 ONNX Runtime、RKNN、FOCAS SDK、Snap7、Drogon、React/Vite、Playwright、交叉编译工具链、AI Provider SDK 等新技术，并生成适合本仓库使用的 skill 或技术笔记。
 ---
 # edge_collector 技术学习沉淀
 ## 适用场景
 - 用户要求“学习某框架并生成 skill”。
 - 新接入第三方 SDK、协议库、AI Provider 或模型推理框架。
 - 当前知识可能过期，需要联网查官方文档。
 - 需要把一次调研变成后续可复用的项目规则。
 ## 信息来源
 优先级：
 1. 官方文档、官方仓库、官方示例。
 2. 当前仓库已有实现和构建脚本。
 3. 设备或 SDK 随包文档。
 4. 社区资料，仅用于补充，并标注来源。
 涉及外部技术版本、接口或模型能力时必须联网确认，避免凭记忆。
 ## 学习输出
 ```text
 技术定位
 适用版本
 当前项目使用场景
 安装与依赖
 最小可用示例
 项目集成方式
 构建/部署注意事项
 常见错误
 验证命令
 是否需要新增 skill
 ```
 ## 生成 skill 时
 - 名称使用小写短横线。
 - 放到 `.agents/skills/<name>/SKILL.md`。
 - frontmatter 只保留 `name` 和 `description`。
 - 内容必须面向 `edge_collector`，不要生成通用教程。
 - 复杂资料可放 `references/`，但优先保持 SKILL.md 简洁。
 - 用 `skill-creator` 的 `quick_validate.py` 校验。
 ## 本项目集成检查
 新增技术必须检查：
 - 是否影响 `collector` 稳定性。
 - 是否需要新增第三方库目录和架构分层。
 - 是否需要修改 `package.sh` 或 `scripts/migrate_edge.sh`。
 - 是否会引入运行配置覆盖风险。
 - 是否需要 82/97/94/87 或云平台验证。
 - 是否需要文档区分用户说明和技术细节。
 ## 输出语气
 给用户的是选型和落地建议，不堆砌官方概念；每条建议都要说明对当前工程的影响。
@@ -0,0 +1,84 @@
 ---
 name: edge-frontend-design
 description: edge_collector 前端页面设计与 UI 落地规范。用于设计或优化边缘侧 frontend/config_app、云平台 frontend/cloud_app 页面、组件、布局、交互、按钮状态、弹窗、图表、AI 分析、WiFi、端口转发、内网穿透等用户界面时，结合当前 React/Vite/CSS Modules 暗色主题输出可落地设计。
 ---
 # edge_collector 前端设计
 ## 适用前端
 - 边缘侧：`frontend/config_app`
 - 云平台：`frontend/cloud_app`
 ## 设计原则
 - 先阅读相邻页面和 CSS Modules，沿用当前视觉语言。
 - 首屏直接呈现可用工具，不做营销式 landing page。
 - 工业/运维页面要安静、清晰、密集但不拥挤。
 - 不引入新的 UI 框架。
 - 不把内部技术细节展示给最终用户。
 - 卡片、按钮、启停、危险操作样式要与已有模块一致。
 ## 视觉基线
 后续前端设计按以下口径走：
 - 暗色底。
 - 细边框。
 - 蓝紫作为主操作色。
 - 状态色克制使用，只用于表达成功、警告、错误、运行中等明确状态。
 - 避免营销页式大渐变。
 - 避免装饰感过强的科技视觉，如大面积霓虹、发光线框、玻璃拟态、纯装饰光效。
 - 页面应像工业网关/运维工具，而不是宣传页或展示大屏。
 现有颜色基线：
 ```text
 背景：#0d0d14 / #14141e
 面板：#1e1e2e
 边框：#2a2a3a
 主文字：#e0e0e0
 标题文字：#ffffff
 主操作色：#6366f1
 ```
 ## 工作流
 1. 明确目标用户：现场用户、运维、管理员、开发。
 2. 梳理核心任务：用户进页面后最需要完成什么。
 3. 阅读现有页面，提取布局、按钮、表格、弹窗和状态样式。
 4. 先给信息架构，再给具体组件布局。
 5. 覆盖加载、空状态、错误、保存中、权限不足、操作成功。
 6. 实现时遵循 `frontend-ui-conventions`、`frontend-conventions`、`frontend-dialog`。
 ## 当前项目常见布局
 - 高级功能：模块标签页 + 左右均分列表/配置区 + 底部操作区靠右。
 - 数据查看/AI 分析：图表区域与报告区域独立，报告内容向下延展，不向上挤占图表。
 - 配置页：表单和列表并排，避免单列垂直堆叠导致右侧空白。
 - 规则列表：单条启用/停用放操作列，不使用复选框表达启停。
 ## 交互要求
 - 点击连接、扫描、保存、分析、启停等耗时操作，按钮必须出现 loading 或局部状态反馈。
 - 危险操作必须二次确认。
 - 失败提示要说明可执行下一步，不只显示接口失败。
 - 普通按钮、危险按钮、启停按钮风格要统一。
 - 长文本和长报告必须支持滚动查看，不能遮挡上方关键内容。
 ## 文案规则
 - 用户可见文案使用业务语言。
 - 不展示 AI Provider 名称、内部模型名、helper、SDK 路径、接口路径、堆栈、SQL。
 - 参数说明写影响和建议值。
 - 空状态告诉用户下一步操作。
 ## 设计检查
 - 是否有大片空白。
 - 文本是否溢出。
 - 窄屏是否可用。
 - 操作后是否有反馈。
 - 图表、表格、报告是否互相遮挡。
 - 权限不足是否有清晰状态。
 - 与相邻模块按钮和标签风格是否一致。
@@ -0,0 +1,104 @@
 ---
 name: edge-frontend-testing
 description: edge_collector 前端测试与浏览器验证规范。用于边缘侧或云平台 React/Vite 页面白屏、布局错乱、按钮无反馈、弹窗异常、图表遮挡、接口失败、构建后验证时，使用 npm build、浏览器控制台、Network、Playwright 截图和交互脚本进行验证。
 ---
 # edge_collector 前端测试
 ## 适用范围
 - `frontend/config_app`
 - `frontend/cloud_app`
 - 云平台公网页面 `http://119.45.4.75`
 - 边缘网关页面，如 `http://192.168.40.<host>/`
 ## 验证顺序
 1. 构建验证。
 2. 页面加载验证。
 3. 控制台错误检查。
 4. Network 接口响应检查。
 5. 关键交互点击。
 6. 布局截图和窄屏检查。
 7. 状态反馈检查。
 ## 构建命令
 按实际目录执行：
 ```bash
 npm run build
 ```
 如果不能构建，最终说明原因，例如缺少依赖、Node 版本不对或远程主机不可用。
 ## Playwright 验证流程
 使用浏览器验证时：
 ```text
 打开目标 URL
  -> wait networkidle
  -> 收集 console error
  -> 截图
  -> 定位关键按钮/输入框
  -> 执行操作
  -> 检查 loading/toast/dialog/network
  -> 再截图
 ```
 优先使用稳定选择器：
 - 可见文本。
 - button role/name。
 - 表单 label。
 - 现有 data 属性。
 - 必要时再用 CSS selector。
 ## 重点页面检查
 - 高级功能：WiFi、内网穿透、端口转发、硬件控制。
 - 数据查看：历史趋势、AI 分析弹窗、AI 分析报告。
 - 离线缓存：参数默认值、保存反馈、状态展示。
 - OTA：包列表、升级确认、进度和失败提示。
 - 管理后台：AI 配置、权限、启用配置唯一性。
 ## 失败提示检查
 前端不能只显示：
 ```text
 failed to request cloud config
 AI 服务请求失败
 操作失败
 ```
 应尽量展示后端或 agent 给出的具体原因，并转成用户可理解文案：
 - 连接失败。
 - 请求超时。
 - 权限不足。
 - 配置缺失。
 - 服务未运行。
 - 返回格式异常。
 ## 截图要求
 复杂 UI 改动至少检查：
 - 桌面宽度。
 - 窄屏或移动宽度。
 - 长内容状态。
 - 操作中状态。
 - 错误状态。
 最终说明截图路径或验证 URL。
 ## 回归重点
 - 页面不白屏。
 - 无严重 console error。
 - 按钮 loading 不导致布局抖动。
 - 报告和表格区域可滚动。
 - 文案不泄露内部实现。
 - 动态配置不会因为前端保存被清空。
@@ -0,0 +1,94 @@
 ---
 name: edge-local-dev-services
 description: edge_collector 本地开发与联调服务管理规范。用于在本机或远程开发主机启动、检查、停止 edge/cloud 前后端开发服务和依赖服务，包含 collector、configurator、cloud_server、React/Vite 前端、PostgreSQL、TDengine、Mosquitto、端口占用和日志验证。
 ---
 # edge_collector 本地开发服务
 ## 适用场景
 - 本机启动边缘侧或云平台开发环境。
 - 前端页面需要 dev server 联调。
 - 后端接口需要本地验证。
 - E2E 前需要确认依赖服务。
 - 端口冲突、服务没起来、接口连接失败。
 ## 先读配置
 不要假设服务和端口，优先读取：
 - `docs/project-overview.md`
 - `cloud_server/config/server_config.json`
 - `configurator/config/`
 - `frontend/*/package.json`
 - `package.sh`
 - `deploy_cloud.sh`
 - `scripts/install_all.sh`
 - systemd service 安装脚本
 ## 常见服务
 - 边缘：`collector`、`configurator`、`edge` systemd 服务。
 - 云端：`cloud_server`、`cloud-server` systemd 服务。
 - 前端：`frontend/config_app`、`frontend/cloud_app`。
 - 依赖：PostgreSQL、TDengine、Mosquitto。
 - 独立 agent：frpc agent、port forward agent、4G/WiFi 相关脚本。
 ## 检查流程
 1. 查看端口占用：
 ```bash
 ss -lntp
 ```
 2. 查看服务状态：
 ```bash
 systemctl status edge --no-pager
 systemctl status cloud-server --no-pager
 ```
 3. 查看最近日志：
 ```bash
 journalctl -u edge --since "10 min ago" --no-pager
 journalctl -u cloud-server --since "10 min ago" --no-pager
 ```
 4. 验证接口：
 ```bash
 curl -s http://127.0.0.1/api/status
 curl -s http://127.0.0.1:8081/api/health
 ```
 ## 前端开发
 进入对应目录后：
 ```bash
 npm install
 npm run dev
 npm run build
 ```
 如果 Node 环境在 97/ARM64 主机异常，优先参考 `scripts/set_env/install_nvm_npm.sh` 和本地 nvm 离线安装规则。
 ## 禁止事项
 - 不要直接连接生产库做写操作。
 - 不要随意 kill 非本次启动的进程。
 - 不要删除用户已有容器、数据库或运行配置。
 - 不要把本地端口和临时密码写死进代码。
 - 不要每次同步后都执行 `install_all.sh`，除非用户明确要求。
 ## 输出
 最终说明：
 - 启动或检查了哪些服务。
 - 使用了哪些端口。
 - 哪些接口验证通过。
 - 日志里是否有错误。
 - 如何停止本次启动的临时服务。
@@ -0,0 +1,91 @@
 ---
 name: edge-markdown-docs
 description: edge_collector Markdown 文档编写与处理规范。用于创建、更新、拆分、合并、校对 docs、collector/docs、协议文档、部署说明、测试报告、故障报告、本地模型方案等 Markdown 文档，并维护目录、链接、图片引用和读者边界。
 ---
 # edge_collector Markdown 文档处理
 ## 适用范围
 - `docs/`
 - `collector/docs/`
 - `collector/docs/protocols/`
 - `docs/本地模型/`
 - `docs/鲁班猫*/`
 - `.agents/skills/`
 ## 工作流
 1. 先确认读者：用户、运维、开发、客户交付。
 2. 选择落点：优先更新已有文档，避免重复文档。
 3. 读取相邻文档，保持标题层级和术语一致。
 4. 写完后检查链接、图片路径、代码块语言和表格可读性。
 5. 技术文档标注假设和验证状态，用户文档隐藏内部实现细节。
 ## 推荐结构
 技术方案：
 ```text
 背景与目标
 现状与问题
 方案设计
 接口/配置/目录
 实施步骤
 验证计划
 风险与回滚
 ```
 操作说明：
 ```text
 功能用途
 使用前准备
 操作步骤
 参数说明
 常见问题
 注意事项
 ```
 故障报告：
 ```text
 问题现象
 影响范围
 证据
 根因
 修复
 验证
 预防措施
 ```
 ## 格式规则
 - 标题层级从 `#` 开始，不跳级。
 - 命令使用 `bash` 代码块。
 - JSON 使用 `json` 代码块。
 - 表格列不要过宽，必要时拆成列表。
 - 图片放到文档同级 `assets/` 或专题目录下，并用相对路径引用。
 - 引用外部资料时给链接。
 ## 当前项目特别规则
 - 协议用户介绍不要透露 helper、SDK、库路径、内部进程。
 - 部署文档要写清是否会覆盖运行配置。
 - 云平台 AI 文档不要展示真实 key。
 - 远程主机文档不要写明密码。
 - 同主机编译部署仍要使用 `scripts/migrate_edge.sh`。
 ## 校验
 至少执行：
 ```bash
 rg -n "TODO|待确认|change_me|password|secret" docs collector/docs .agents/skills
 ```
 按文档类型补充：
 - JSON 示例：`jq empty`
 - Shell 示例：`bash -n`
 - SVG 引用：浏览器或图片查看器打开检查
@@ -0,0 +1,182 @@
 ---
 name: edge-mcp-tools
 description: edge_collector 边缘侧本地模型与 MCP 工具接入规范。用于在鲁班猫/RK3566/RK3576/RK3588 等边缘设备部署本地模型后，设计或实现 MCP 工具服务，让模型安全调用网关状态、设备点位、历史数据、诊断、配置查询和运维只读能力。
 ---
 # edge_collector MCP 工具接入
 ## 目标
 让边缘侧本地模型可以通过受控工具访问网关能力，而不是直接读取任意文件、执行任意命令或绕过现有服务。
 典型链路：
 ```text
 本地模型
  -> MCP Client
  -> edge MCP tools
  -> configurator / collector / 本地数据库 / 只读诊断命令
 ```
 ## 适用场景
 - 在 RK3566/RK3576/RK3588 鲁班猫上部署 Qwen 等本地模型。
 - 给本地模型增加“查询设备状态”“分析点位趋势”“解释报警”“读取网关状态”等工具。
 - 把边缘侧诊断能力封装成 AI 可调用工具。
 - 设计 MCP 工具权限、输入输出和安全边界。
 ## 设计原则
 - 默认只读。
 - 工具服务独立运行，不耦合 `edge` 主服务。
 - 本地模型不直接访问数据库文件、配置文件和 shell。
 - 所有工具必须有明确输入 schema、输出 schema 和错误语义。
 - 写配置、重启服务、删除数据等高风险动作第一版不开放。
 - 工具返回用户可理解信息，不泄露密钥、路径、Token、内部模型配置。
 ## 推荐第一版工具
 优先做只读工具：
 - `edge_get_gateway_status`：读取网关状态、版本、运行时间。
 - `edge_list_devices`：列出设备名称、协议、在线状态。
 - `edge_list_points`：列出某设备点位名称、类型、单位。
 - `edge_read_latest_values`：读取指定设备/点位最新值。
 - `edge_query_history_summary`：查询历史数据摘要，不返回超大原始数据。
 - `edge_get_alarm_summary`：读取报警或异常摘要。
 - `edge_get_network_status`：读取网络、WiFi、4G、端口转发只读状态。
 - `edge_get_service_health`：读取 `edge`、独立 agent 状态。
 暂不开放：
 - 修改协议配置。
 - 保存 AI Key。
 - 重启服务。
 - 删除缓存或历史数据。
 - 执行任意 shell。
 - 读取任意文件。
 ## 工具命名
 - 使用 `edge_` 前缀。
 - 动词清晰：`get`、`list`、`query`、`analyze`。
 - 避免泛化工具名，例如 `run_command`、`read_file`。
 ## 输入输出
 输入必须限制范围：
 ```text
 gateway_id
 device_id 或 device_name
 point_id 或 point_name
 time_range
 limit
 ```
 输出建议结构：
 ```json
 {
  "ok": true,
  "data": {},
  "warnings": [],
  "source": "configurator",
  "timestamp": "2026-06-16T00:00:00+08:00"
 }
 ```
 错误要可行动：
 ```json
 {
  "ok": false,
  "error_code": "DEVICE_NOT_FOUND",
  "message": "未找到指定设备，请确认设备名称或 ID",
  "suggestion": "可先调用 edge_list_devices 查看可用设备"
 }
 ```
 ## 与现有服务集成
 优先通过现有 API 或受控本地接口访问：
 - `configurator` API。
 - `collector` 状态接口或已有数据接口。
 - 本地只读数据库查询。
 - systemd 只读状态命令。
 不要绕过业务逻辑直接修改配置文件。
 ## 本地模型注意
 参考已有本地模型文档：
 - `docs/本地模型/Qwen2.5-0.6B-Instruct在RK3566本地部署方案.md`
 - `docs/本地模型/Qwen2.5-VL-3B-Instruct在RK3576鲁班猫3边缘图文模型部署方案.md`
 - `docs/本地模型/Qwen2.5-14B-Instruct在16G_RK3588鲁班猫5部署方案.md`
 设计工具时必须考虑：
 - 模型上下文有限，工具返回要摘要化。
 - RK3566/RK3576 资源有限，工具查询要分页、限流。
 - 大历史数据先聚合摘要，再按需返回异常片段。
 - 离线运行时不要依赖云端 AI Provider。
 ## 安全边界
 结合 `edge-security-secrets`：
 - 不返回 API Key、JWT、MQTT 密码、SSH 密码。
 - 不暴露真实配置文件完整内容。
 - 不开放任意命令执行。
 - 日志中记录工具名、参数摘要、耗时、结果状态，不记录敏感值。
 - 对外接口只监听本机或受控内网，默认不暴露公网。
 ## 部署方式
 第一版建议使用 Python 独立 agent：
 - 遵循 `edge-python-agent`。
 - 使用 systemd 独立托管。
 - 配置文件动态生成但不覆盖已有配置。
 - 打包和同步遵循 `edge-config-lifecycle`。
 服务名建议：
 ```text
 edge-mcp-tools
 ```
 ## 验证计划
 至少验证：
 - 工具列表可发现。
 - 每个工具 schema 正确。
 - 正常查询返回结构化数据。
 - 设备不存在、点位不存在、时间范围过大时错误可理解。
 - 返回内容脱敏。
 - 大数据查询有 limit 或摘要。
 - 服务重启后配置保留。
 - 本地模型能完成一个端到端问题，例如“分析最近 1 小时某设备是否异常”。
 ## 文档输出
 设计 MCP 工具时输出：
 ```markdown
 ## 工具清单
 ## 权限边界
 ## 输入输出 schema
 ## 数据来源
 ## 部署方式
 ## 安全与脱敏
 ## 验证计划
 ```
@@ -0,0 +1,116 @@
 ---
 name: edge-observability
 description: edge_collector 运行观测与资源诊断规范。用于排查边缘主机或云服务器 CPU 高、内存占用、磁盘空间、/tmp 清理、进程数量、jq/python/agent 异常、服务日志、端口监听和系统负载时，按只读证据链输出分析结论。
 ---
 # edge_collector 运行观测
 ## 适用场景
 - CPU 占用高。
 - 内存比其他主机高。
 - `/tmp` 或工程目录占用大。
 - `jq`、Python、agent 进程很多。
 - 服务频繁重启。
 - 网关在线状态异常。
 - 前端或云端接口偶发失败。
 ## 排查顺序
 1. 系统概况。
 2. CPU 和进程。
 3. 内存。
 4. 磁盘。
 5. systemd 服务。
 6. 应用日志。
 7. 网络端口。
 8. 与对照主机比较。
 ## 常用命令
 系统：
 ```bash
 uptime
 free -h
 df -h
 uname -a
 date
 ```
 CPU/进程：
 ```bash
 ps -eo pid,ppid,user,stat,pcpu,pmem,rss,etime,cmd --sort=-pcpu | head -30
 ps -eo pid,ppid,user,stat,pcpu,pmem,rss,etime,cmd --sort=-rss | head -30
 ```
 进程树：
 ```bash
 pstree -ap
 ```
 磁盘：
 ```bash
 du -h --max-depth=1 /home/cat 2>/dev/null | sort -h
 du -h --max-depth=1 /tmp 2>/dev/null | sort -h
 ```
 服务：
 ```bash
 systemctl status edge --no-pager
 journalctl -u edge --since "30 min ago" --no-pager
 systemctl list-units --type=service --state=running
 ```
 端口：
 ```bash
 ss -lntp
 ```
 ## 分析规则
 - 短时尖峰和持续高占用分开判断。
 - 先找父进程，再判断是脚本循环、服务重启还是用户命令。
 - 内存分析区分 RSS、缓存和可用内存。
 - 磁盘清理只给建议，删除必须等用户确认。
 - 与 119.45.4.75 或其他主机对比时，列出相同指标。
 ## 高风险操作
 以下操作必须用户明确同意：
 - 删除文件或目录。
 - kill 进程。
 - 重启服务。
 - 清理日志。
 - apt 安装诊断工具。
 ## 报告格式
 ```text
 结论：
 证据：
 - CPU:
 - 内存:
 - 磁盘:
 - 进程:
 - 日志:
 判断：
 建议：
 ```
 ## 当前项目常见根因
 - shell + `jq` 高频轮询导致短时 CPU 尖峰。
 - 未插 SIM/设备缺失导致 4G 脚本重复探测。
 - 前端构建产物或代码仓库占用较大。
 - `/tmp` 离线安装包、构建缓存未清理。
 - 独立 agent 异常退出后被 systemd 频繁拉起。
@@ -0,0 +1,76 @@
 ---
 name: edge-pdf-docs
 description: edge_collector PDF 文档读取、提取、转换和交付检查规范。用于处理客户 PDF、导出报告、部署手册、测试报告、扫描件、表格提取、PDF 转图片预览，以及从 DOCX/Markdown 生成 PDF 交付件。
 ---
 # edge_collector PDF 处理
 ## 适用场景
 - 阅读客户 PDF 需求、手册、协议资料。
 - 从 PDF 提取文字或表格。
 - 把 Word/Markdown 报告转 PDF。
 - 将 PDF 页面转图片用于视觉检查。
 - 合并、拆分或旋转 PDF。
 ## 文本提取
 优先使用：
 ```bash
 pdftotext -layout input.pdf output.txt
 ```
 需要表格时使用 `pdfplumber`：
 ```python
 import pdfplumber
 with pdfplumber.open("input.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())
        print(page.extract_tables())
 ```
 扫描件需要 OCR 时，先说明 OCR 可能有识别误差，并保留人工复核步骤。
 ## PDF 转图片
 用于检查版式、截图或报告附件：
 ```bash
 pdftoppm -png -r 150 input.pdf page
 ```
 只转指定页：
 ```bash
 pdftoppm -png -r 150 -f 1 -l 3 input.pdf page
 ```
 ## 合并与拆分
 优先使用 `qpdf`：
 ```bash
 qpdf --empty --pages a.pdf b.pdf -- merged.pdf
 qpdf input.pdf --pages . 1-5 -- part.pdf
 ```
 ## 交付检查
 生成 PDF 后检查：
 - 页面是否缺失。
 - 中文是否乱码。
 - 表格是否截断。
 - 图片是否模糊。
 - 页眉页脚和页码是否正确。
 - 是否包含未脱敏的密钥、账号、密码、内网地址。
 ## 当前项目注意
 - 用户手册 PDF 不写内部技术细节。
 - 故障报告 PDF 要保留证据截图和验证命令摘要。
 - 部署报告 PDF 要写清目标主机但隐藏敏感凭据。
 - AI 分析报告 PDF 不展示内部 AI Provider 和模型配置。
@@ -0,0 +1,70 @@
 ---
 name: edge-presentation-docs
 description: edge_collector PPT/汇报材料编写与处理规范。用于把方案设计、部署方案、测试结果、故障复盘、AI/本地模型方案、协议适配方案整理成汇报型 PPT 或演示大纲，并可读取、检查、转换已有 .pptx。
 ---
 # edge_collector 汇报材料处理
 ## 适用场景
 - 方案汇报。
 - 项目进展汇报。
 - 故障复盘汇报。
 - 部署上线说明。
 - 本地模型或 AI 功能方案展示。
 - 协议适配方案展示。
 ## 默认结构
 ```text
 1. 背景与目标
 2. 当前现状/问题
 3. 方案总览
 4. 核心设计或流程
 5. 实施计划
 6. 验证结果
 7. 风险与对策
 8. 下一步
 ```
 ## 设计口径
 - 面向工业网关和云边协同场景，风格稳重、清晰、克制。
 - 优先用流程图、架构图、对比表，而不是大段文字。
 - 一页只表达一个核心结论。
 - 保留必要证据：截图、日志摘要、测试结果、关键指标。
 - 不展示密钥、密码、真实 Token。
 ## 内容转换
 从 Markdown 方案转 PPT 时：
 - 每个二级标题通常对应 1 页或 1 组页。
 - 长表格改成摘要表 + 附录。
 - 命令行只保留关键命令和结果，不放完整日志。
 - 复杂架构图优先使用 `edge-svg-diagram` 生成 SVG 后嵌入。
 ## 读取 PPTX
 提取文本：
 ```bash
 python3 -m markitdown input.pptx > output.md
 ```
 没有 `markitdown` 时，先说明无法直接提取，改用 LibreOffice 或解包 XML。
 检查结构：
 ```bash
 unzip -l input.pptx | rg "ppt/slides/slide|ppt/media|ppt/theme"
 ```
 ## 交付检查
 - 标题是否能单独表达结论。
 - 字体和颜色是否统一。
 - 截图是否清晰。
 - 图表文字是否不截断。
 - 每页是否有明确层级。
 - 是否隐藏内部 AI 配置、密钥和调试信息。
@@ -0,0 +1,72 @@
 ---
 name: edge-project-overview
 description: edge_collector 项目概览维护规范。用于读取、生成或更新本仓库项目总览，沉淀边缘侧、云平台、前端、协议采集、脚本部署、远程主机、运行目录、动态配置保护和常用验证命令，帮助新任务快速建立上下文。
 ---
 # edge_collector 项目概览
 ## 何时使用
 - 用户要求“整理项目概览”“说明当前工程结构”。
 - 新增较大功能前需要建立上下文。
 - 部署、协议、前端、云端多模块同时涉及。
 - 文档或 skill 需要引用项目约定。
 ## 建议落点
 默认维护：
 ```text
 docs/project-overview.md
 ```
 如果已有同类文档，优先更新已有文档，不新增重复总览。
 ## 必须覆盖
 ```text
 项目定位
 模块结构
 边缘侧服务
 云平台服务
 前端应用
 协议采集架构
 运行目录 runtime/edge
 配置文件与动态配置保护
 构建与打包脚本
 部署与同步脚本
 常用远程主机
 常用验证命令
 风险与注意事项
 推荐阅读路径
 ```
 ## 事实来源
 生成或更新概览时优先读取：
 - `CMakeLists.txt`、`collector/CMakeLists.txt`
 - `package.sh`
 - `deploy_cloud.sh`
 - `scripts/migrate_edge.sh`
 - `scripts/install_all.sh`
 - `frontend/*/package.json`
 - `configurator/config/`
 - `collector/docs/`
 - `.agents/skills/`
 ## 环境与主机
 概览可记录常用主机，但不要写敏感密钥：
 - 82：常用 arm64 发布构建主机。
 - 97：arm64 编译/同步验证主机。
 - 94、87：边缘运行验证主机。
 - 云平台：`119.45.4.75`。
 ## 输出要求
 - 明确“已确认事实”和“从文件推断”。
 - 不把历史临时问题写成永久事实。
 - 动态配置保护规则要写清楚，避免打包/同步覆盖运行配置。
 - 同主机编译部署也要使用 `scripts/migrate_edge.sh` 的规范需要写入。
@@ -0,0 +1,80 @@
 ---
 name: edge-project-plan-writer
 description: edge_collector 项目计划与实施拆分编写规范。用于为协议适配、云平台功能、边缘 agent、AI 分析、本地模型、前端页面、部署机制、故障治理等工作编写项目计划、里程碑、任务拆分、风险清单和验证排期。
 ---
 # edge_collector 项目计划编写
 ## 适用场景
 - 新协议适配计划。
 - 云平台功能迭代计划。
 - 边缘独立 agent 实施计划。
 - AI 分析或本地模型接入计划。
 - 前端复杂页面改造计划。
 - 部署/打包/同步机制优化计划。
 - 故障治理和稳定性专项计划。
 ## 推荐结构
 ```text
 目标与范围
 现状与约束
 阶段划分
 里程碑
 任务拆分
 依赖关系
 验证计划
 部署计划
 风险与缓解
 交付物
 ```
 ## 阶段模板
 ```text
 阶段 1：调研与方案
 阶段 2：最小可用实现
 阶段 3：联调与异常场景
 阶段 4：部署验证
 阶段 5：文档与交付
 ```
 按任务实际裁剪，不要机械套用。
 ## 任务拆分要求
 每个任务写清：
 - 目标。
 - 涉及目录。
 - 负责人或执行对象。
 - 前置依赖。
 - 验收标准。
 - 验证命令或验证页面。
 ## 当前项目必须考虑
 - 是否影响 `collector` 稳定性。
 - 是否影响 `runtime/edge` 或 `runtime/cloud_server` 动态配置。
 - 是否需要 82/97/94/87 或云服务器验证。
 - 是否需要修改 `package.sh`、`deploy_cloud.sh`、`scripts/migrate_edge.sh`。
 - 是否需要新增 systemd 服务或独立 agent。
 - 是否需要用户文档和技术文档分开。
 ## 风险清单
 常见风险：
 - 跨架构第三方库不可用。
 - 目标主机系统版本差异。
 - 前端构建环境不一致。
 - 配置同步覆盖运行态文件。
 - AI Provider 超时、费用或响应格式差异。
 - 真实设备不可用导致只能 mock 验证。
 ## 输出要求
 - 计划要能直接转成执行清单。
 - 不确定项标为“待确认”，不要伪装成已完成。
 - 时间排期必须留出联调、回归和远程部署验证。
@@ -0,0 +1,81 @@
 ---
 name: edge-protocol-research
 description: edge_collector 协议调研与适配评估规范。用于调研 FANUC、西门子 CNC、PLC、传感器、第三方 SDK 或参考仓实现时，按当前协议模板、驱动代码、参考实现、官方资料和验证计划输出适配差异、点位补充和实现建议。
 ---
 # edge_collector 协议调研
 ## 适用场景
 - 新增协议驱动。
 - 完善 FANUC/西门子 CNC 点位。
 - 参考外部仓采集程序。
 - 判断第三方 SDK 架构和库是否可用。
 - 协议模板是否合理、是否缺常用点位。
 ## 调研顺序
 1. 读取当前协议模板和用户可见描述。
 2. 读取当前驱动实现和文档。
 3. 对比参考仓或历史实现。
 4. 拿不准的协议语义联网查官方资料或 SDK 文档。
 5. 输出差异、风险、实施建议和验证计划。
 ## 当前项目路径
 优先查看：
 - `configurator/config/templates/`
 - `configurator/config/protocols/`
 - `collector/src/driver/`
 - `collector/docs/protocols/`
 - `third_party/`
 - `collector/CMakeLists.txt`
 ## 对比重点
 - 连接参数是否够用。
 - 点位名称、类型、单位、默认采集周期是否合理。
 - 模板点位和驱动读取逻辑是否一致。
 - 是否保留现有 `PointData::UpdateValue` 行为。
 - 用户可见协议介绍是否隐藏内部技术细节。
 - 第三方库是否按架构分层放置。
 - ARM64/ARM32/x64 构建模式是否明确。
 ## 联网规则
 遇到以下情况必须联网查证：
 - 协议函数含义不确定。
 - SDK 架构、库名、系统依赖不确定。
 - 西门子/FANUC 指标语义不确定。
 - 第三方资料可能过期。
 优先官方文档、SDK 手册、厂商资料；社区资料只能作为补充。
 ## 输出格式
 ```markdown
 ## 当前现状
 ## 参考实现差异
 ## 点位/参数建议
 ## 驱动实现建议
 ## 构建与第三方库影响
 ## 用户文档影响
 ## 验证计划
 ## 风险与待确认
 ```
 ## 禁止事项
 - 不凭猜测写协议语义。
 - 不提交未知来源二进制库。
 - 不把参考仓问题照搬进当前工程。
 - 不在用户可见协议介绍中写 helper、SDK 路径、库文件细节。
@@ -0,0 +1,50 @@
 ---
 name: edge-prototype-design
 description: edge_collector 高保真原型设计规范。用于设计边缘侧或云平台前端页面、复杂交互、管理后台页面、AI 分析、WiFi、端口转发、OTA、数据趋势等功能原型时，先分析现有 React/CSS Modules 风格，再输出适合当前项目落地的原型和实现建议。
 ---
 # edge_collector 原型设计
 ## 适用范围
 - `frontend/config_app` 边缘侧页面。
 - `frontend/cloud_app` 云平台页面。
 - AI 分析、WiFi 管理、端口转发、内网穿透、OTA、离线缓存、数据趋势等复杂页面。
 ## 工作流
 1. 阅读现有页面和 CSS Modules，提取当前视觉语言。
 2. 明确目标用户和核心任务。
 3. 先画信息架构和布局，不急着写代码。
 4. 给出关键状态：加载、空状态、失败、保存中、禁用、权限不足。
 5. 再进入实现，遵循 `frontend-ui-conventions`。
 ## 原型输出形式
 按任务选择：
 - 文档内 ASCII 线框：适合接口/流程方案。
 - HTML 静态原型：适合复杂页面评估。
 - React 组件草案：适合直接落地到现有前端。
 - SVG 交互说明图：适合文档配图。
 ## 本项目 UI 约束
 - 使用 React + Vite + CSS Modules。
 - 保持现有暗色主题。
 - 暗色底、细边框、蓝紫主操作色、状态色克制使用。
 - 避免营销页式大渐变和装饰感过强的科技视觉。
 - 原型应呈现工业网关/运维工具气质，优先清晰、稳定、可操作。
 - 不引入 Ant Design、Tailwind 或新的 UI 框架。
 - 按 `frontend-dialog` 使用统一弹窗。
 - 普通操作按钮、危险按钮、启停按钮样式要与现有模块一致。
 - 页面首屏应是可用工具，不做营销式 landing page。
 ## 设计检查
 - 右侧是否有大片空白。
 - 文本是否溢出或遮挡。
 - 操作后是否有 loading/反馈。
 - 是否支持窄屏。
 - 危险操作是否二次确认。
 - 用户可见文案是否隐藏内部实现细节。
@@ -0,0 +1,88 @@
 ---
 name: edge-python-agent
 description: edge_collector Python 独立 agent 开发规范。用于新增或修改 frpc agent、port forward agent、WiFi/4G 辅助进程、巡检脚本、数据分析脚本等 Python3 常驻或命令行工具时，统一配置、日志、systemd、资源占用、退出码和与 edge 主服务解耦要求。
 ---
 # edge_collector Python Agent
 ## 适用范围
 - `scripts/frp/start_*.py`
 - `scripts/port_forward/start_*.py`
 - WiFi/4G 辅助脚本。
 - 远程巡检和数据分析脚本。
 - 需要 systemd 托管的 Python 常驻进程。
 ## 命名与位置
 - 常驻启动脚本使用 `start_` 前缀，保持现有风格。
 - 按功能放到独立目录，例如 `scripts/frp/`、`scripts/port_forward/`。
 - 不要把独立 agent 代码塞进 `collector` 或 `configurator`。
 ## 配置
 - 配置文件放到运行目录的 `config/` 或功能子目录。
 - 支持配置缺失时生成默认文件，但不得覆盖已有配置。
 - 动态配置必须被打包和同步规则排除，避免目标主机运行配置被覆盖。
 - 密钥、Token、URL 不写死在代码中。
 ## 日志
 - 使用 Python `logging`。
 - 日志包含时间、级别、模块、关键状态。
 - 不打印密钥、密码、Token。
 - 高频循环日志要限流，避免 CPU/磁盘压力。
 - 错误日志要保留具体原因，供前端展示更明确错误。
 ## 常驻进程要求
 - 支持优雅退出 `SIGTERM`/`SIGINT`。
 - 主循环有固定 sleep 或事件等待，禁止无休眠空转。
 - 外部命令调用设置 timeout。
 - 子进程必须回收。
 - 网络请求必须设置连接和读取超时。
 - 异常后退避重试，不要短时间无限重启。
 ## systemd
 服务文件应明确：
 ```text
 WorkingDirectory
 ExecStart
 Restart=on-failure
 RestartSec
 User
 Environment
 ```
 新增服务应独立，不替代已有 `edge`、`frpc_agent` 或其他服务，除非用户明确要求迁移。
 ## CLI
 建议支持：
 ```bash
 --config <path>
 --log-level <level>
 --once
 --dry-run
 ```
 `--once` 适合调试和安装后验证。
 ## 验证
 至少验证：
 ```bash
 python3 -m py_compile scripts/<dir>/<file>.py
 python3 scripts/<dir>/<file>.py --help
 ```
 常驻服务验证：
 ```bash
 systemctl status <service> --no-pager
 journalctl -u <service> --since "5 min ago" --no-pager
 ```
@@ -0,0 +1,90 @@
 ---
 name: edge-release-notes
 description: edge_collector 版本说明与变更日志编写规范。用于提交、push、边缘包发布、云平台部署、OTA 发布、阶段交付时，生成面向用户、运维和开发的 release notes，区分用户可见变化、部署影响、配置影响、验证结果和回滚说明。
 ---
 # edge_collector 版本说明
 ## 适用场景
 - 提交前整理变更。
 - push 后总结。
 - 边缘版本发布。
 - 云平台部署。
 - OTA 包说明。
 - 阶段交付说明。
 ## 读者分层
 - 用户可见：功能变化、操作入口、体验优化。
 - 运维可见：部署步骤、配置变化、服务重启、回滚。
 - 开发可见：代码结构、接口、测试、技术债。
 不要把内部 helper、SDK 路径、密钥、模型配置写进用户可见说明。
 ## 推荐结构
 ```markdown
 ## 版本信息
 - 版本：
 - 日期：
 - 范围：
 ## 用户可见变化
 ## 运维与部署影响
 ## 配置变化
 ## 修复问题
 ## 验证结果
 ## 已知风险
 ## 回滚说明
 ```
 ## 从 Git 生成摘要
 可参考：
 ```bash
 git log --oneline -10
 git diff --stat HEAD~1..HEAD
 git status --short
 ```
 只总结和本次发布相关内容，不把无关工作区改动写进版本说明。
 ## 边缘发布说明
 必须说明：
 - 目标架构。
 - 是否需要执行 `install_all.sh`。
 - 是否需要重启 `edge` 或独立 agent。
 - 是否影响运行态动态配置。
 - 是否通过目标主机验证。
 ## 云平台发布说明
 必须说明：
 - 是否执行 `deploy_cloud.sh`。
 - 是否使用 `--init`。
 - 是否影响 `ai_config.json`、`server_config.json`。
 - 是否重启 `cloud-server`、Mosquitto、nginx。
 - 公网接口验证结果。
 ## OTA 包说明
 面向用户时写：
 - 新增能力。
 - 修复问题。
 - 升级注意事项。
 - 回滚建议。
 避免写内部提交号、代码路径和密钥。
--- a/Show More
+++ b/Show More