From 3cb7684039c70d8c5f7cd292e2b5f4e5c948c294 Mon Sep 17 00:00:00 2001 From: cloud Date: Tue, 14 Jul 2026 17:50:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE=20skills?= =?UTF-8?q?=20=E5=B9=B6=E5=AE=8C=E5=96=84=E8=AE=BE=E8=AE=A1=E5=8A=9F?= =?UTF-8?q?=E7=8E=87=E6=9B=B2=E7=BA=BF=E5=89=8D=E7=AB=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - skills: 移除 edge_collector 专属技能(OTA/协议/边缘主机/collector 等)， 保留通用工程规范(analyze-questions/cpp-coding-style/git-commit/shell-scripting/ frontend-debug/frontend-dialog/frontend-ui-conventions)，新增 wind_power_cal 项目技能(wind-project-overview/build-run/deploy/backend-conventions/ frontend-conventions/third-party-libs)与元技能 skill-builder； .agents/skills 与 .claude/skills 保持同步 - 前端: HomePage/App.css 增加设计功率曲线录入与图表展示 Co-Authored-By: Claude --- .agents/skills/backend-conventions/SKILL.md | 84 ----- .agents/skills/cloud-deploy-verify/SKILL.md | 62 --- .../cloud-deploy-verify/agents/openai.yaml | 3 - .agents/skills/cloud-public-deploy/SKILL.md | 120 ------ .agents/skills/edge-82-release/SKILL.md | 48 --- .../skills/edge-82-release/agents/openai.yaml | 3 - .agents/skills/edge-bug-lessons/SKILL.md | 91 ----- .agents/skills/edge-bugfix/SKILL.md | 86 ----- .../edge-business-rule-extractor/SKILL.md | 54 --- .agents/skills/edge-code-review/SKILL.md | 70 ---- .agents/skills/edge-codex-automation/SKILL.md | 84 ----- .agents/skills/edge-config-lifecycle/SKILL.md | 96 ----- .../edge-data-quality-analyzer/SKILL.md | 93 ----- .agents/skills/edge-database-ops/SKILL.md | 104 ------ .../skills/edge-deployment-writer/SKILL.md | 68 ---- .../skills/edge-design-doc-writer/SKILL.md | 64 ---- .agents/skills/edge-design-reviewer/SKILL.md | 91 ----- .agents/skills/edge-doc-coauthoring/SKILL.md | 68 ---- .../skills/edge-framework-learner/SKILL.md | 63 ---- .agents/skills/edge-frontend-design/SKILL.md | 84 ----- .agents/skills/edge-frontend-testing/SKILL.md | 104 ------ .../skills/edge-local-dev-services/SKILL.md | 94 ----- .agents/skills/edge-markdown-docs/SKILL.md | 91 ----- .agents/skills/edge-mcp-tools/SKILL.md | 182 --------- .agents/skills/edge-observability/SKILL.md | 116 ------ .agents/skills/edge-pdf-docs/SKILL.md | 76 ---- .../skills/edge-presentation-docs/SKILL.md | 70 ---- .agents/skills/edge-project-overview/SKILL.md | 72 ---- .../skills/edge-project-plan-writer/SKILL.md | 80 ---- .../skills/edge-protocol-research/SKILL.md | 81 ---- .agents/skills/edge-prototype-design/SKILL.md | 50 --- .agents/skills/edge-python-agent/SKILL.md | 88 ----- .agents/skills/edge-release-notes/SKILL.md | 90 ----- .agents/skills/edge-release-prepare/SKILL.md | 67 ---- .../edge-release-prepare/agents/openai.yaml | 3 - .agents/skills/edge-remote-access/SKILL.md | 110 ------ .../edge-requirement-interview/SKILL.md | 60 --- .agents/skills/edge-security-secrets/SKILL.md | 96 ----- .agents/skills/edge-skill-builder/SKILL.md | 81 ---- .agents/skills/edge-spreadsheet-docs/SKILL.md | 83 ---- .agents/skills/edge-svg-diagram/SKILL.md | 59 --- .agents/skills/edge-sync-host/SKILL.md | 73 ---- .../skills/edge-sync-host/agents/openai.yaml | 3 - .../skills/edge-system-test-writer/SKILL.md | 89 ----- .../edge-technical-zeroing-report/SKILL.md | 80 ---- .../skills/edge-user-manual-writer/SKILL.md | 56 --- .../skills/edge-user-story-reviewer/SKILL.md | 108 ------ .../skills/edge-user-story-writer/SKILL.md | 151 -------- .agents/skills/edge-webapp-testing/SKILL.md | 48 --- .agents/skills/edge-word-docx/SKILL.md | 70 ---- .agents/skills/frontend-conventions/SKILL.md | 50 --- .../skills/host-connection-defaults/SKILL.md | 26 -- .agents/skills/ota-e2e-release/SKILL.md | 51 --- .../skills/ota-e2e-release/agents/openai.yaml | 3 - .agents/skills/project-structure/SKILL.md | 53 --- .agents/skills/protocol-e2e-testing/SKILL.md | 22 -- .agents/skills/skill-builder/SKILL.md | 31 ++ .agents/skills/third-party-libs/SKILL.md | 136 ------- .../skills/wind-backend-conventions/SKILL.md | 40 ++ .agents/skills/wind-build-run/SKILL.md | 33 ++ .agents/skills/wind-deploy/SKILL.md | 36 ++ .../skills/wind-frontend-conventions/SKILL.md | 40 ++ .agents/skills/wind-project-overview/SKILL.md | 46 +++ .agents/skills/wind-third-party-libs/SKILL.md | 35 ++ .claude/settings.json | 7 + .claude/skills/backend-conventions/SKILL.md | 84 ----- .claude/skills/cloud-deploy-verify/SKILL.md | 62 --- .../cloud-deploy-verify/agents/openai.yaml | 3 - .claude/skills/cloud-public-deploy/SKILL.md | 120 ------ .claude/skills/edge-82-release/SKILL.md | 48 --- .../skills/edge-82-release/agents/openai.yaml | 3 - .claude/skills/edge-bug-lessons/SKILL.md | 91 ----- .claude/skills/edge-bugfix/SKILL.md | 86 ----- .../edge-business-rule-extractor/SKILL.md | 54 --- .claude/skills/edge-code-review/SKILL.md | 70 ---- .claude/skills/edge-codex-automation/SKILL.md | 84 ----- .claude/skills/edge-config-lifecycle/SKILL.md | 96 ----- .../edge-data-quality-analyzer/SKILL.md | 93 ----- .claude/skills/edge-database-ops/SKILL.md | 104 ------ .../skills/edge-deployment-writer/SKILL.md | 68 ---- .../skills/edge-design-doc-writer/SKILL.md | 64 ---- .claude/skills/edge-design-reviewer/SKILL.md | 91 ----- .claude/skills/edge-doc-coauthoring/SKILL.md | 68 ---- .../skills/edge-framework-learner/SKILL.md | 63 ---- .claude/skills/edge-frontend-design/SKILL.md | 84 ----- .claude/skills/edge-frontend-testing/SKILL.md | 104 ------ .../skills/edge-local-dev-services/SKILL.md | 94 ----- .claude/skills/edge-markdown-docs/SKILL.md | 91 ----- .claude/skills/edge-mcp-tools/SKILL.md | 182 --------- .claude/skills/edge-observability/SKILL.md | 116 ------ .claude/skills/edge-pdf-docs/SKILL.md | 76 ---- .../skills/edge-presentation-docs/SKILL.md | 70 ---- .claude/skills/edge-project-overview/SKILL.md | 72 ---- .../skills/edge-project-plan-writer/SKILL.md | 80 ---- .../skills/edge-protocol-research/SKILL.md | 81 ---- .claude/skills/edge-prototype-design/SKILL.md | 50 --- .claude/skills/edge-python-agent/SKILL.md | 88 ----- .claude/skills/edge-release-notes/SKILL.md | 90 ----- .claude/skills/edge-release-prepare/SKILL.md | 67 ---- .../edge-release-prepare/agents/openai.yaml | 3 - .claude/skills/edge-remote-access/SKILL.md | 110 ------ .../edge-requirement-interview/SKILL.md | 60 --- .claude/skills/edge-security-secrets/SKILL.md | 96 ----- .claude/skills/edge-skill-builder/SKILL.md | 81 ---- .claude/skills/edge-spreadsheet-docs/SKILL.md | 83 ---- .claude/skills/edge-svg-diagram/SKILL.md | 59 --- .claude/skills/edge-sync-host/SKILL.md | 73 ---- .../skills/edge-sync-host/agents/openai.yaml | 3 - .../skills/edge-system-test-writer/SKILL.md | 89 ----- .../edge-technical-zeroing-report/SKILL.md | 80 ---- .../skills/edge-user-manual-writer/SKILL.md | 56 --- .../skills/edge-user-story-reviewer/SKILL.md | 108 ------ .../skills/edge-user-story-writer/SKILL.md | 151 -------- .claude/skills/edge-webapp-testing/SKILL.md | 48 --- .claude/skills/edge-word-docx/SKILL.md | 70 ---- .claude/skills/frontend-conventions/SKILL.md | 50 --- .../skills/host-connection-defaults/SKILL.md | 26 -- .claude/skills/ota-e2e-release/SKILL.md | 51 --- .../skills/ota-e2e-release/agents/openai.yaml | 3 - .claude/skills/project-structure/SKILL.md | 53 --- .claude/skills/protocol-e2e-testing/SKILL.md | 22 -- .claude/skills/skill-builder/SKILL.md | 31 ++ .claude/skills/third-party-libs/SKILL.md | 136 ------- .../skills/wind-backend-conventions/SKILL.md | 40 ++ .claude/skills/wind-build-run/SKILL.md | 33 ++ .claude/skills/wind-deploy/SKILL.md | 36 ++ .../skills/wind-frontend-conventions/SKILL.md | 40 ++ .claude/skills/wind-project-overview/SKILL.md | 46 +++ .claude/skills/wind-third-party-libs/SKILL.md | 35 ++ frontend/web_app/src/App.css | 169 ++++++++- frontend/web_app/src/pages/HomePage.jsx | 353 ++++++++++++++++-- 131 files changed, 1026 insertions(+), 8441 deletions(-) delete mode 100644 .agents/skills/backend-conventions/SKILL.md delete mode 100644 .agents/skills/cloud-deploy-verify/SKILL.md delete mode 100644 .agents/skills/cloud-deploy-verify/agents/openai.yaml delete mode 100644 .agents/skills/cloud-public-deploy/SKILL.md delete mode 100644 .agents/skills/edge-82-release/SKILL.md delete mode 100644 .agents/skills/edge-82-release/agents/openai.yaml delete mode 100644 .agents/skills/edge-bug-lessons/SKILL.md delete mode 100644 .agents/skills/edge-bugfix/SKILL.md delete mode 100644 .agents/skills/edge-business-rule-extractor/SKILL.md delete mode 100644 .agents/skills/edge-code-review/SKILL.md delete mode 100644 .agents/skills/edge-codex-automation/SKILL.md delete mode 100644 .agents/skills/edge-config-lifecycle/SKILL.md delete mode 100644 .agents/skills/edge-data-quality-analyzer/SKILL.md delete mode 100644 .agents/skills/edge-database-ops/SKILL.md delete mode 100644 .agents/skills/edge-deployment-writer/SKILL.md delete mode 100644 .agents/skills/edge-design-doc-writer/SKILL.md delete mode 100644 .agents/skills/edge-design-reviewer/SKILL.md delete mode 100644 .agents/skills/edge-doc-coauthoring/SKILL.md delete mode 100644 .agents/skills/edge-framework-learner/SKILL.md delete mode 100644 .agents/skills/edge-frontend-design/SKILL.md delete mode 100644 .agents/skills/edge-frontend-testing/SKILL.md delete mode 100644 .agents/skills/edge-local-dev-services/SKILL.md delete mode 100644 .agents/skills/edge-markdown-docs/SKILL.md delete mode 100644 .agents/skills/edge-mcp-tools/SKILL.md delete mode 100644 .agents/skills/edge-observability/SKILL.md delete mode 100644 .agents/skills/edge-pdf-docs/SKILL.md delete mode 100644 .agents/skills/edge-presentation-docs/SKILL.md delete mode 100644 .agents/skills/edge-project-overview/SKILL.md delete mode 100644 .agents/skills/edge-project-plan-writer/SKILL.md delete mode 100644 .agents/skills/edge-protocol-research/SKILL.md delete mode 100644 .agents/skills/edge-prototype-design/SKILL.md delete mode 100644 .agents/skills/edge-python-agent/SKILL.md delete mode 100644 .agents/skills/edge-release-notes/SKILL.md delete mode 100644 .agents/skills/edge-release-prepare/SKILL.md delete mode 100644 .agents/skills/edge-release-prepare/agents/openai.yaml delete mode 100644 .agents/skills/edge-remote-access/SKILL.md delete mode 100644 .agents/skills/edge-requirement-interview/SKILL.md delete mode 100644 .agents/skills/edge-security-secrets/SKILL.md delete mode 100644 .agents/skills/edge-skill-builder/SKILL.md delete mode 100644 .agents/skills/edge-spreadsheet-docs/SKILL.md delete mode 100644 .agents/skills/edge-svg-diagram/SKILL.md delete mode 100644 .agents/skills/edge-sync-host/SKILL.md delete mode 100644 .agents/skills/edge-sync-host/agents/openai.yaml delete mode 100644 .agents/skills/edge-system-test-writer/SKILL.md delete mode 100644 .agents/skills/edge-technical-zeroing-report/SKILL.md delete mode 100644 .agents/skills/edge-user-manual-writer/SKILL.md delete mode 100644 .agents/skills/edge-user-story-reviewer/SKILL.md delete mode 100644 .agents/skills/edge-user-story-writer/SKILL.md delete mode 100644 .agents/skills/edge-webapp-testing/SKILL.md delete mode 100644 .agents/skills/edge-word-docx/SKILL.md delete mode 100644 .agents/skills/frontend-conventions/SKILL.md delete mode 100644 .agents/skills/host-connection-defaults/SKILL.md delete mode 100644 .agents/skills/ota-e2e-release/SKILL.md delete mode 100644 .agents/skills/ota-e2e-release/agents/openai.yaml delete mode 100644 .agents/skills/project-structure/SKILL.md delete mode 100644 .agents/skills/protocol-e2e-testing/SKILL.md create mode 100644 .agents/skills/skill-builder/SKILL.md delete mode 100644 .agents/skills/third-party-libs/SKILL.md create mode 100644 .agents/skills/wind-backend-conventions/SKILL.md create mode 100644 .agents/skills/wind-build-run/SKILL.md create mode 100644 .agents/skills/wind-deploy/SKILL.md create mode 100644 .agents/skills/wind-frontend-conventions/SKILL.md create mode 100644 .agents/skills/wind-project-overview/SKILL.md create mode 100644 .agents/skills/wind-third-party-libs/SKILL.md create mode 100644 .claude/settings.json delete mode 100644 .claude/skills/backend-conventions/SKILL.md delete mode 100644 .claude/skills/cloud-deploy-verify/SKILL.md delete mode 100644 .claude/skills/cloud-deploy-verify/agents/openai.yaml delete mode 100644 .claude/skills/cloud-public-deploy/SKILL.md delete mode 100644 .claude/skills/edge-82-release/SKILL.md delete mode 100644 .claude/skills/edge-82-release/agents/openai.yaml delete mode 100644 .claude/skills/edge-bug-lessons/SKILL.md delete mode 100644 .claude/skills/edge-bugfix/SKILL.md delete mode 100644 .claude/skills/edge-business-rule-extractor/SKILL.md delete mode 100644 .claude/skills/edge-code-review/SKILL.md delete mode 100644 .claude/skills/edge-codex-automation/SKILL.md delete mode 100644 .claude/skills/edge-config-lifecycle/SKILL.md delete mode 100644 .claude/skills/edge-data-quality-analyzer/SKILL.md delete mode 100644 .claude/skills/edge-database-ops/SKILL.md delete mode 100644 .claude/skills/edge-deployment-writer/SKILL.md delete mode 100644 .claude/skills/edge-design-doc-writer/SKILL.md delete mode 100644 .claude/skills/edge-design-reviewer/SKILL.md delete mode 100644 .claude/skills/edge-doc-coauthoring/SKILL.md delete mode 100644 .claude/skills/edge-framework-learner/SKILL.md delete mode 100644 .claude/skills/edge-frontend-design/SKILL.md delete mode 100644 .claude/skills/edge-frontend-testing/SKILL.md delete mode 100644 .claude/skills/edge-local-dev-services/SKILL.md delete mode 100644 .claude/skills/edge-markdown-docs/SKILL.md delete mode 100644 .claude/skills/edge-mcp-tools/SKILL.md delete mode 100644 .claude/skills/edge-observability/SKILL.md delete mode 100644 .claude/skills/edge-pdf-docs/SKILL.md delete mode 100644 .claude/skills/edge-presentation-docs/SKILL.md delete mode 100644 .claude/skills/edge-project-overview/SKILL.md delete mode 100644 .claude/skills/edge-project-plan-writer/SKILL.md delete mode 100644 .claude/skills/edge-protocol-research/SKILL.md delete mode 100644 .claude/skills/edge-prototype-design/SKILL.md delete mode 100644 .claude/skills/edge-python-agent/SKILL.md delete mode 100644 .claude/skills/edge-release-notes/SKILL.md delete mode 100644 .claude/skills/edge-release-prepare/SKILL.md delete mode 100644 .claude/skills/edge-release-prepare/agents/openai.yaml delete mode 100644 .claude/skills/edge-remote-access/SKILL.md delete mode 100644 .claude/skills/edge-requirement-interview/SKILL.md delete mode 100644 .claude/skills/edge-security-secrets/SKILL.md delete mode 100644 .claude/skills/edge-skill-builder/SKILL.md delete mode 100644 .claude/skills/edge-spreadsheet-docs/SKILL.md delete mode 100644 .claude/skills/edge-svg-diagram/SKILL.md delete mode 100644 .claude/skills/edge-sync-host/SKILL.md delete mode 100644 .claude/skills/edge-sync-host/agents/openai.yaml delete mode 100644 .claude/skills/edge-system-test-writer/SKILL.md delete mode 100644 .claude/skills/edge-technical-zeroing-report/SKILL.md delete mode 100644 .claude/skills/edge-user-manual-writer/SKILL.md delete mode 100644 .claude/skills/edge-user-story-reviewer/SKILL.md delete mode 100644 .claude/skills/edge-user-story-writer/SKILL.md delete mode 100644 .claude/skills/edge-webapp-testing/SKILL.md delete mode 100644 .claude/skills/edge-word-docx/SKILL.md delete mode 100644 .claude/skills/frontend-conventions/SKILL.md delete mode 100644 .claude/skills/host-connection-defaults/SKILL.md delete mode 100644 .claude/skills/ota-e2e-release/SKILL.md delete mode 100644 .claude/skills/ota-e2e-release/agents/openai.yaml delete mode 100644 .claude/skills/project-structure/SKILL.md delete mode 100644 .claude/skills/protocol-e2e-testing/SKILL.md create mode 100644 .claude/skills/skill-builder/SKILL.md delete mode 100644 .claude/skills/third-party-libs/SKILL.md create mode 100644 .claude/skills/wind-backend-conventions/SKILL.md create mode 100644 .claude/skills/wind-build-run/SKILL.md create mode 100644 .claude/skills/wind-deploy/SKILL.md create mode 100644 .claude/skills/wind-frontend-conventions/SKILL.md create mode 100644 .claude/skills/wind-project-overview/SKILL.md create mode 100644 .claude/skills/wind-third-party-libs/SKILL.md diff --git a/.agents/skills/backend-conventions/SKILL.md b/.agents/skills/backend-conventions/SKILL.md deleted file mode 100644 index 64f1ade..0000000 --- a/.agents/skills/backend-conventions/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -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"`） -- 需要同时支持串口和以太网时，新增独立协议条目 diff --git a/.agents/skills/cloud-deploy-verify/SKILL.md b/.agents/skills/cloud-deploy-verify/SKILL.md deleted file mode 100644 index 4d45d92..0000000 --- a/.agents/skills/cloud-deploy-verify/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -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' -``` diff --git a/.agents/skills/cloud-deploy-verify/agents/openai.yaml b/.agents/skills/cloud-deploy-verify/agents/openai.yaml deleted file mode 100644 index fc739c3..0000000 --- a/.agents/skills/cloud-deploy-verify/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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. diff --git a/.agents/skills/cloud-public-deploy/SKILL.md b/.agents/skills/cloud-public-deploy/SKILL.md deleted file mode 100644 index 3cbd341..0000000 --- a/.agents/skills/cloud-public-deploy/SKILL.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -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`。 -- 会保留哪些远端配置。 -- 会重启哪些服务。 -- 公网访问入口和验证接口。 -- 回滚方式和日志位置。 diff --git a/.agents/skills/edge-82-release/SKILL.md b/.agents/skills/edge-82-release/SKILL.md deleted file mode 100644 index ff5126a..0000000 --- a/.agents/skills/edge-82-release/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -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__arm64.tar.gz` 上传到云平台 - - 使用云平台默认 `admin` 账号登录 - -## 上传字段 - -- `file` -- `package_type=edge` -- `version=<版本号>` -- `target_arch=arm64` -- `release_type=stable` -- `visibility=platform` -- `enabled=true` diff --git a/.agents/skills/edge-82-release/agents/openai.yaml b/.agents/skills/edge-82-release/agents/openai.yaml deleted file mode 100644 index 370ca71..0000000 --- a/.agents/skills/edge-82-release/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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 . Upload to the cloud admin account only when the user explicitly asks to publish and upload. diff --git a/.agents/skills/edge-bug-lessons/SKILL.md b/.agents/skills/edge-bug-lessons/SKILL.md deleted file mode 100644 index a638618..0000000 --- a/.agents/skills/edge-bug-lessons/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -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 -| 日期 | 标题 | 模块 | 核心根因 | 漏检点 | 预防规则 | 文件 | -|------|------|------|----------|--------|----------|------| -``` diff --git a/.agents/skills/edge-bugfix/SKILL.md b/.agents/skills/edge-bugfix/SKILL.md deleted file mode 100644 index f1db40f..0000000 --- a/.agents/skills/edge-bugfix/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -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 ` -- 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/` - -报告至少包含：现象、根因、修复、验证、后续预防。 diff --git a/.agents/skills/edge-business-rule-extractor/SKILL.md b/.agents/skills/edge-business-rule-extractor/SKILL.md deleted file mode 100644 index 976bef9..0000000 --- a/.agents/skills/edge-business-rule-extractor/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -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/` 下已有规则/概览文档；没有则建议新增规则表。 - -## 注意 - -- 不把猜测写成规则。 -- 不把一次性临时命令写成规则。 -- 规则变更会影响部署或运行安全时，先让用户确认。 diff --git a/.agents/skills/edge-code-review/SKILL.md b/.agents/skills/edge-code-review/SKILL.md deleted file mode 100644 index b6fcb7e..0000000 --- a/.agents/skills/edge-code-review/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 安装脚本 -- 远程同步/重启逻辑 - diff --git a/.agents/skills/edge-codex-automation/SKILL.md b/.agents/skills/edge-codex-automation/SKILL.md deleted file mode 100644 index 9cb402d..0000000 --- a/.agents/skills/edge-codex-automation/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -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 -自动化任务： -- 名称： -- 目标： -- 执行脚本： -- 调度方式： -- 运行主机： -- 权限需求： -- 日志位置： -- 手工验证： -- 风险： -``` diff --git a/.agents/skills/edge-config-lifecycle/SKILL.md b/.agents/skills/edge-config-lifecycle/SKILL.md deleted file mode 100644 index 12c3567..0000000 --- a/.agents/skills/edge-config-lifecycle/SKILL.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -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 -``` - -同步/部署后验证： - -- 目标主机已有配置仍存在。 -- 新增默认配置可生成。 -- 服务重启后能读取配置。 -- 前端读取和保存正常。 - -## 风险信号 - -- `rsync --delete` -- `cp -r config` -- `cat > config.json` -- 前端保存整个 JSON。 -- 后端启动时无条件重写配置。 -- 示例配置中出现真实 key。 diff --git a/.agents/skills/edge-data-quality-analyzer/SKILL.md b/.agents/skills/edge-data-quality-analyzer/SKILL.md deleted file mode 100644 index d83e6e7..0000000 --- a/.agents/skills/edge-data-quality-analyzer/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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 -## 数据范围 - -## 关键统计 - -## 异常片段 - -## 原因判断 - -## 建议动作 -``` diff --git a/.agents/skills/edge-database-ops/SKILL.md b/.agents/skills/edge-database-ops/SKILL.md deleted file mode 100644 index 0828443..0000000 --- a/.agents/skills/edge-database-ops/SKILL.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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 WHERE ; -``` - -必要时导出为临时文件，并说明路径。 - -## 常用只读检查 - -PostgreSQL： - -```sql -SELECT now(); -SELECT version(); -``` - -TDengine： - -```sql -SHOW DATABASES; -SHOW STABLES; -``` - -SQLite： - -```bash -sqlite3 ".tables" -sqlite3 "PRAGMA integrity_check;" -``` - -## 输出要求 - -- 说明数据来源。 -- 说明查询条件和时间范围。 -- 说明结论是事实还是推断。 -- 给出下一步建议。 - -## 禁止事项 - -- 未确认就执行 `UPDATE`、`DELETE`、`DROP`、`TRUNCATE`。 -- 把配置中的数据库密码打印到回复。 -- 用线上写操作验证猜测。 -- 将大量敏感原始数据贴到对话中。 diff --git a/.agents/skills/edge-deployment-writer/SKILL.md b/.agents/skills/edge-deployment-writer/SKILL.md deleted file mode 100644 index 3b1f860..0000000 --- a/.agents/skills/edge-deployment-writer/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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:/api/health -``` - -脚本： - -```bash -bash -n scripts/.sh -``` - -## 回滚说明 - -文档必须说明： - -- 上一个 runtime/edge 或发布包位置。 -- 如何恢复二进制和 web 资源。 -- 哪些配置不能回滚覆盖。 -- 回滚后如何重启服务和验证。 - diff --git a/.agents/skills/edge-design-doc-writer/SKILL.md b/.agents/skills/edge-design-doc-writer/SKILL.md deleted file mode 100644 index 526019a..0000000 --- a/.agents/skills/edge-design-doc-writer/SKILL.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -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`。 - -## 方案验证 - -文档结尾必须写： - -- 单元测试或脚本验证。 -- 构建验证。 -- 远程部署验证（如需要）。 -- 回滚或降级策略。 - diff --git a/.agents/skills/edge-design-reviewer/SKILL.md b/.agents/skills/edge-design-reviewer/SKILL.md deleted file mode 100644 index 7cf3d99..0000000 --- a/.agents/skills/edge-design-reviewer/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -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，拿不准时要联网查证。 diff --git a/.agents/skills/edge-doc-coauthoring/SKILL.md b/.agents/skills/edge-doc-coauthoring/SKILL.md deleted file mode 100644 index f45323d..0000000 --- a/.agents/skills/edge-doc-coauthoring/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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 -功能用途 -使用步骤 -参数解释 -常见问题 -注意事项 -``` - -## 约束 - -- 给用户看的协议介绍不透露内部技术细节。 -- 技术方案可写实现细节，但要标注假设和验证状态。 -- 引用外部信息时提供链接。 -- 不把未经验证的能力写成已完成。 - diff --git a/.agents/skills/edge-framework-learner/SKILL.md b/.agents/skills/edge-framework-learner/SKILL.md deleted file mode 100644 index 3944483..0000000 --- a/.agents/skills/edge-framework-learner/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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//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 或云平台验证。 -- 是否需要文档区分用户说明和技术细节。 - -## 输出语气 - -给用户的是选型和落地建议，不堆砌官方概念；每条建议都要说明对当前工程的影响。 diff --git a/.agents/skills/edge-frontend-design/SKILL.md b/.agents/skills/edge-frontend-design/SKILL.md deleted file mode 100644 index cc7861e..0000000 --- a/.agents/skills/edge-frontend-design/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -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。 -- 参数说明写影响和建议值。 -- 空状态告诉用户下一步操作。 - -## 设计检查 - -- 是否有大片空白。 -- 文本是否溢出。 -- 窄屏是否可用。 -- 操作后是否有反馈。 -- 图表、表格、报告是否互相遮挡。 -- 权限不足是否有清晰状态。 -- 与相邻模块按钮和标签风格是否一致。 diff --git a/.agents/skills/edge-frontend-testing/SKILL.md b/.agents/skills/edge-frontend-testing/SKILL.md deleted file mode 100644 index dd4a1c2..0000000 --- a/.agents/skills/edge-frontend-testing/SKILL.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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./` - -## 验证顺序 - -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 不导致布局抖动。 -- 报告和表格区域可滚动。 -- 文案不泄露内部实现。 -- 动态配置不会因为前端保存被清空。 diff --git a/.agents/skills/edge-local-dev-services/SKILL.md b/.agents/skills/edge-local-dev-services/SKILL.md deleted file mode 100644 index e132130..0000000 --- a/.agents/skills/edge-local-dev-services/SKILL.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -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`，除非用户明确要求。 - -## 输出 - -最终说明： - -- 启动或检查了哪些服务。 -- 使用了哪些端口。 -- 哪些接口验证通过。 -- 日志里是否有错误。 -- 如何停止本次启动的临时服务。 diff --git a/.agents/skills/edge-markdown-docs/SKILL.md b/.agents/skills/edge-markdown-docs/SKILL.md deleted file mode 100644 index 2fc0df1..0000000 --- a/.agents/skills/edge-markdown-docs/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -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 引用：浏览器或图片查看器打开检查 diff --git a/.agents/skills/edge-mcp-tools/SKILL.md b/.agents/skills/edge-mcp-tools/SKILL.md deleted file mode 100644 index 9883ff2..0000000 --- a/.agents/skills/edge-mcp-tools/SKILL.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -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 - -## 数据来源 - -## 部署方式 - -## 安全与脱敏 - -## 验证计划 -``` diff --git a/.agents/skills/edge-observability/SKILL.md b/.agents/skills/edge-observability/SKILL.md deleted file mode 100644 index 095ef08..0000000 --- a/.agents/skills/edge-observability/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -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 频繁拉起。 diff --git a/.agents/skills/edge-pdf-docs/SKILL.md b/.agents/skills/edge-pdf-docs/SKILL.md deleted file mode 100644 index d13c49a..0000000 --- a/.agents/skills/edge-pdf-docs/SKILL.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -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 和模型配置。 diff --git a/.agents/skills/edge-presentation-docs/SKILL.md b/.agents/skills/edge-presentation-docs/SKILL.md deleted file mode 100644 index bc12b62..0000000 --- a/.agents/skills/edge-presentation-docs/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 配置、密钥和调试信息。 diff --git a/.agents/skills/edge-project-overview/SKILL.md b/.agents/skills/edge-project-overview/SKILL.md deleted file mode 100644 index c3cc18d..0000000 --- a/.agents/skills/edge-project-overview/SKILL.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -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` 的规范需要写入。 diff --git a/.agents/skills/edge-project-plan-writer/SKILL.md b/.agents/skills/edge-project-plan-writer/SKILL.md deleted file mode 100644 index bb71831..0000000 --- a/.agents/skills/edge-project-plan-writer/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -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 验证。 - -## 输出要求 - -- 计划要能直接转成执行清单。 -- 不确定项标为“待确认”，不要伪装成已完成。 -- 时间排期必须留出联调、回归和远程部署验证。 diff --git a/.agents/skills/edge-protocol-research/SKILL.md b/.agents/skills/edge-protocol-research/SKILL.md deleted file mode 100644 index c98fa4e..0000000 --- a/.agents/skills/edge-protocol-research/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -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 路径、库文件细节。 diff --git a/.agents/skills/edge-prototype-design/SKILL.md b/.agents/skills/edge-prototype-design/SKILL.md deleted file mode 100644 index 5f81703..0000000 --- a/.agents/skills/edge-prototype-design/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -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/反馈。 -- 是否支持窄屏。 -- 危险操作是否二次确认。 -- 用户可见文案是否隐藏内部实现细节。 diff --git a/.agents/skills/edge-python-agent/SKILL.md b/.agents/skills/edge-python-agent/SKILL.md deleted file mode 100644 index f6a1aa7..0000000 --- a/.agents/skills/edge-python-agent/SKILL.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -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 ---log-level ---once ---dry-run -``` - -`--once` 适合调试和安装后验证。 - -## 验证 - -至少验证： - -```bash -python3 -m py_compile scripts//.py -python3 scripts//.py --help -``` - -常驻服务验证： - -```bash -systemctl status --no-pager -journalctl -u --since "5 min ago" --no-pager -``` diff --git a/.agents/skills/edge-release-notes/SKILL.md b/.agents/skills/edge-release-notes/SKILL.md deleted file mode 100644 index 444b019..0000000 --- a/.agents/skills/edge-release-notes/SKILL.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -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 包说明 - -面向用户时写： - -- 新增能力。 -- 修复问题。 -- 升级注意事项。 -- 回滚建议。 - -避免写内部提交号、代码路径和密钥。 diff --git a/.agents/skills/edge-release-prepare/SKILL.md b/.agents/skills/edge-release-prepare/SKILL.md deleted file mode 100644 index f2d5b05..0000000 --- a/.agents/skills/edge-release-prepare/SKILL.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -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__arm64.tar.gz` -- 版本信息：一句话概括本次发布 -- 版本说明：多行列点，来自用户说明、最近提交、已完成改动和验证结果 -- 后续动作预览：确认后将在 82 执行 `./package.sh --publish --version `，必要时上传云平台 - -## 确认边界 - -- 在用户明确确认前，禁止执行 `./package.sh --publish --version ...` -- 在用户明确确认前，禁止上传云平台 -- 用户确认后，再按 `edge-82-release` 的发布流程执行 - -## 建议输出格式 - -```text -发布草案： -- 版本号： -- 架构：arm64 -- 发布类型：release -- 产物：publish/edge__arm64.tar.gz - -版本信息： -<一句话说明> - -版本说明： -- <说明 1> -- <说明 2> - -确认后执行： -1. 82: ./package.sh --publish --version -2. 如需上传云平台，使用上述版本说明和发布类型 -``` diff --git a/.agents/skills/edge-release-prepare/agents/openai.yaml b/.agents/skills/edge-release-prepare/agents/openai.yaml deleted file mode 100644 index 46465f8..0000000 --- a/.agents/skills/edge-release-prepare/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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. diff --git a/.agents/skills/edge-remote-access/SKILL.md b/.agents/skills/edge-remote-access/SKILL.md deleted file mode 100644 index 3a6f9df..0000000 --- a/.agents/skills/edge-remote-access/SKILL.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -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 -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 -arp -an | grep -``` - -## 输出要求 - -最终说明： - -- 连接的主机。 -- 执行的关键只读检查。 -- 发现的异常证据。 -- 未执行的高风险动作。 -- 建议下一步。 diff --git a/.agents/skills/edge-requirement-interview/SKILL.md b/.agents/skills/edge-requirement-interview/SKILL.md deleted file mode 100644 index 78f5d0c..0000000 --- a/.agents/skills/edge-requirement-interview/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -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`。 diff --git a/.agents/skills/edge-security-secrets/SKILL.md b/.agents/skills/edge-security-secrets/SKILL.md deleted file mode 100644 index 576b284..0000000 --- a/.agents/skills/edge-security-secrets/SKILL.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -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 报告、导出报告不写内部技术细节和密钥。 -- 运维文档可以写配置路径和字段含义，但示例值必须使用占位符。 diff --git a/.agents/skills/edge-skill-builder/SKILL.md b/.agents/skills/edge-skill-builder/SKILL.md deleted file mode 100644 index e554a7f..0000000 --- a/.agents/skills/edge-skill-builder/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: edge-skill-builder -description: edge_collector 技能建设规范。用于从外部仓库、已有流程、项目经验、框架/SDK 学习结果中创建或改写 .agents/skills 下的 Codex skills，要求结合当前 C++/Drogon/React/Vite/云边部署/现场主机实际情况，避免原封不动照搬无关技术栈。 ---- - -# edge_collector 技能建设 - -## 目标 - -把项目中重复出现的流程和判断沉淀为 `.agents/skills//SKILL.md`，让后续任务能稳定复用。 - -## 适用来源 - -- 当前仓库脚本，如 `deploy_cloud.sh`、`package.sh`、`scripts/migrate_edge.sh`。 -- 已完成的故障排查和现场经验。 -- 外部仓库中的通用 skill。 -- 官方文档或 SDK 调研结果。 -- 用户明确确认的长期规则。 - -## 命名规则 - -- 使用小写短横线。 -- 本项目专用优先加 `edge-` 前缀。 -- 云平台专用可用 `cloud-` 前缀。 -- 名称要表达动作或场景，例如 `edge-frontend-testing`。 - -## frontmatter - -只写： - -```yaml ---- -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/ -``` - -同时检查： - -```bash -grep -R "Java\\|Spring\\|K3s\\|Ant Design\\|Umi\\|one_person" -n .agents/skills/ || true -``` - -如果出现这些词，要确认是项目真实需要，还是外部 skill 残留。 - -## 输出 - -最终向用户说明： - -- 新增或修改了哪些 skill。 -- 每个 skill 覆盖什么场景。 -- 是否通过校验。 -- 是否只改了 skill 文件，是否未提交。 diff --git a/.agents/skills/edge-spreadsheet-docs/SKILL.md b/.agents/skills/edge-spreadsheet-docs/SKILL.md deleted file mode 100644 index 98887a1..0000000 --- a/.agents/skills/edge-spreadsheet-docs/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -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?`。 -- 修改既有模板时保留原列顺序和样式，除非用户明确要求调整。 diff --git a/.agents/skills/edge-svg-diagram/SKILL.md b/.agents/skills/edge-svg-diagram/SKILL.md deleted file mode 100644 index 47e2c02..0000000 --- a/.agents/skills/edge-svg-diagram/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -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。 -- 确认文字不重叠、不截断。 -- 确认中文显示正常。 -- 确认风格与用途匹配：文档图可打印，前端原型图与项目暗色主题一致。 -- 文档引用路径有效。 diff --git a/.agents/skills/edge-sync-host/SKILL.md b/.agents/skills/edge-sync-host/SKILL.md deleted file mode 100644 index ad9d699..0000000 --- a/.agents/skills/edge-sync-host/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -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 -``` - -随后也要把重启命令中的目标地址替换为 `192.168.40.`，执行 `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` 服务；不要只同步文件就结束。 -- 如果用户明确指定源主机、目标用户、目标目录或密码，以用户本次明确值为准，并透传给脚本参数。 diff --git a/.agents/skills/edge-sync-host/agents/openai.yaml b/.agents/skills/edge-sync-host/agents/openai.yaml deleted file mode 100644 index 1595869..0000000 --- a/.agents/skills/edge-sync-host/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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 from the repo root. Treat 87 only as an example; other numbered hosts map to 192.168.40.. After sync succeeds, SSH to cat@192.168.40. 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. diff --git a/.agents/skills/edge-system-test-writer/SKILL.md b/.agents/skills/edge-system-test-writer/SKILL.md deleted file mode 100644 index f0af846..0000000 --- a/.agents/skills/edge-system-test-writer/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -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/.sh -jq empty -``` - -远程同步或重启必须等用户明确要求，并遵循对应部署 skill。 - -## 问题回溯 - -测试文档应保留问题回溯表： - -```markdown -| 问题 | 影响场景 | 根因位置 | 修复提交/文件 | 回归结果 | -|------|----------|----------|----------------|----------| -``` diff --git a/.agents/skills/edge-technical-zeroing-report/SKILL.md b/.agents/skills/edge-technical-zeroing-report/SKILL.md deleted file mode 100644 index da0efc2..0000000 --- a/.agents/skills/edge-technical-zeroing-report/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -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/` diff --git a/.agents/skills/edge-user-manual-writer/SKILL.md b/.agents/skills/edge-user-manual-writer/SKILL.md deleted file mode 100644 index f40c90d..0000000 --- a/.agents/skills/edge-user-manual-writer/SKILL.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: edge-user-manual-writer -description: edge_collector 用户手册与交付说明编写规范。用于为边缘侧前端、云平台、协议配置、AI 分析、WiFi、端口转发、内网穿透、OTA、离线缓存等用户可见功能编写操作说明、培训材料、交付文档和常见问题，避免暴露内部技术细节。 ---- - -# edge_collector 用户手册编写 - -## 读者 - -- 现场实施人员。 -- 运维人员。 -- 管理后台用户。 -- 客户侧使用人员。 - -## 文档落点 - -- 用户手册：`docs/` 或对应专题目录。 -- 协议用户说明：优先与协议文档分开，用户可见介绍不能写内部实现细节。 -- 鲁班猫设备操作：`docs/鲁班猫*/`。 - -## 推荐结构 - -```text -功能用途 -适用场景 -使用前准备 -操作步骤 -参数说明 -状态说明 -常见问题 -注意事项 -``` - -## 写作规则 - -- 面向用户目标写，不按代码模块写。 -- 只写用户能看到、能操作、能验证的内容。 -- 隐藏内部模型名、AI Provider 名称、helper、进程、库路径等技术细节，除非读者是运维人员且文档明确为运维手册。 -- 参数说明要写“影响和建议值”，不要只复述字段名。 -- 错误说明要写用户下一步可以怎么处理。 - -## 当前项目常见功能口径 - -- AI 分析：说明分析深度、提示词、数据不连续的业务原因，不显示内部 AI 配置。 -- WiFi 管理：说明扫描、刷新、加入隐藏网络、已保存网络连接、自动连接。 -- 内网穿透：说明映射启停、保存配置、云端配置失败提示。 -- 端口转发：说明规则启停、监听地址、目标地址、冲突端口。 -- 离线缓存：说明最大缓存、保留天数、重传批次、重传速率的影响。 - -## 检查清单 - -- 功能名称和界面文案一致。 -- 操作步骤能被现场用户照着完成。 -- 参数默认值和当前代码/配置一致。 -- 没有泄露内部接口、密钥、模型、库路径。 -- 有失败场景和恢复建议。 diff --git a/.agents/skills/edge-user-story-reviewer/SKILL.md b/.agents/skills/edge-user-story-reviewer/SKILL.md deleted file mode 100644 index a2d0d9b..0000000 --- a/.agents/skills/edge-user-story-reviewer/SKILL.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -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`。 diff --git a/.agents/skills/edge-user-story-writer/SKILL.md b/.agents/skills/edge-user-story-writer/SKILL.md deleted file mode 100644 index 3b0a325..0000000 --- a/.agents/skills/edge-user-story-writer/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -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--: <简短标题> - -**角色**: <现场用户/运维人员/平台管理员/开发人员> -**优先级**: 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---<简短标题>-业务场景图.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、内部模型配置写进用户可见故事。 -- 对部署类故事，必须写清是否会重启服务、是否影响运行配置。 diff --git a/.agents/skills/edge-webapp-testing/SKILL.md b/.agents/skills/edge-webapp-testing/SKILL.md deleted file mode 100644 index a6ebc9d..0000000 --- a/.agents/skills/edge-webapp-testing/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -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。 -- 构建命令结果。 -- 发现的问题和截图路径（如有）。 - diff --git a/.agents/skills/edge-word-docx/SKILL.md b/.agents/skills/edge-word-docx/SKILL.md deleted file mode 100644 index 533b758..0000000 --- a/.agents/skills/edge-word-docx/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 时，尽量保留原模板样式。 -- 涉及密钥、账号、内网地址时，交付版要脱敏。 diff --git a/.agents/skills/frontend-conventions/SKILL.md b/.agents/skills/frontend-conventions/SKILL.md deleted file mode 100644 index a97d986..0000000 --- a/.agents/skills/frontend-conventions/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: frontend-conventions -description: 前端 UI 组件使用规范。用于本仓库前端页面开发时，统一下拉组件、只读字段展示方式，避免原生控件导致交互和样式不一致。 ---- - -# 前端组件规范 - -## 下拉控件 - -- 必须使用 `CustomSelect` -- 禁止直接写原生 `` 或是手写带放大镜图标的输入框 -- `SearchInput` 组件需统一具备清除按钮和 `onChange` 的直接值映射 -- 已集成在 `src/components/common/` 目录下 - -## 组件复用优先级 - -- 页面开发前先检查现有组件：`frontend/config_app/src/components/common/`、`frontend/cloud_app/src/components/common/` -- 已有自定义组件必须优先复用，禁止在页面中重复实现同类 UI 逻辑 -- 仅当现有组件无法满足需求时才允许新增组件，并优先沉淀到各自工程的 `src/components/common/` -- 新增或改造组件时，保持 API 向后兼容，避免一次改动引发多页面回归 - -示例： - -```jsx - -``` - -## 只读字段 - -- 禁止使用 `` 伪装只读 -- 使用 `` 或 `
` + 只读样式类 - -## 设计目标 - -- 保持交互行为一致 -- 保持视觉样式一致 -- 降低页面间重复实现 diff --git a/.agents/skills/host-connection-defaults/SKILL.md b/.agents/skills/host-connection-defaults/SKILL.md deleted file mode 100644 index 8323542..0000000 --- a/.agents/skills/host-connection-defaults/SKILL.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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.<数字> ''`。 -- 如用户只要求连接或排查连接，优先执行无破坏的只读命令，如 `hostname`、`uptime`、`ip addr`。 -- 不要把“其他数字主机”固定成 99；数字以用户本次说出的主机号为准。 -- 如果用户明确给出不同用户名、IP 或密码，以用户本次明确值为准。 diff --git a/.agents/skills/ota-e2e-release/SKILL.md b/.agents/skills/ota-e2e-release/SKILL.md deleted file mode 100644 index d334aba..0000000 --- a/.agents/skills/ota-e2e-release/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -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 ` - -2. 上传到云平台 - - 使用云平台 `admin` 账号登录 - - 上传 `publish/edge__arm64.tar.gz` - - 确认版本号、架构、发布状态与产物一致 - -3. 87 主机 OTA 验证 - - 打开边缘侧前端 - - 查询云平台可用版本，确认 `` 可见 - - 通过前端接口触发 OTA 升级 - - 检查 `/api/ota/status`，确认当前版本已变成 `` - -## 失败时优先排查 - -- 云端字段或页面不生效：先确认已走 `deploy_cloud.sh`，再查 `cloud-server` 状态和云端接口响应 -- 87 上看不到版本：先确认 82 包已上传成功，再查 87 的 OTA 配置 -- 87 OTA 起不来：先执行 `sudo bash /home/cat/edge/scripts/ota/install_ota_service.sh` -- 前端升级失败：先看后端 OTA 接口返回，再看服务日志 diff --git a/.agents/skills/ota-e2e-release/agents/openai.yaml b/.agents/skills/ota-e2e-release/agents/openai.yaml deleted file mode 100644 index f831197..0000000 --- a/.agents/skills/ota-e2e-release/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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 , upload publish/edge__arm64.tar.gz to the cloud admin account, validate OTA from the 87-side frontend, and verify the current version becomes . diff --git a/.agents/skills/project-structure/SKILL.md b/.agents/skills/project-structure/SKILL.md deleted file mode 100644 index af9fa57..0000000 --- a/.agents/skills/project-structure/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -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/` 目录下 - diff --git a/.agents/skills/protocol-e2e-testing/SKILL.md b/.agents/skills/protocol-e2e-testing/SKILL.md deleted file mode 100644 index 8b9c99b..0000000 --- a/.agents/skills/protocol-e2e-testing/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 的原始报文。 diff --git a/.agents/skills/skill-builder/SKILL.md b/.agents/skills/skill-builder/SKILL.md new file mode 100644 index 0000000..b1f6dd9 --- /dev/null +++ b/.agents/skills/skill-builder/SKILL.md @@ -0,0 +1,31 @@ +--- +name: skill-builder +description: 技能建设规范。用于为 wind_power_cal 创建/改写 .agents/skills 与 .claude/skills 下的 skill，要求贴合当前 C++/Drogon/React/Vite 技术栈，避免照搬无关项目。 +--- + +# 技能建设规范 + +为本仓库创建或改写 skill（`.agents/skills/` 与 `.claude/skills/` 需保持同步）。 + +## 规则 +- 每个 skill 一个目录，内含 `SKILL.md`。 +- frontmatter：`name`（kebab-case）、`description`（一句话：**何时触发** + 做什么；用于检索匹配）。 +- 内容贴合 **wind_power_cal 实际**：C++ Drogon 后端（:8848）、React+Vite 前端、`package.sh / run.sh / deploy.sh`、`third_party` 源码编译 Drogon、响应信封 `{status,msg,data}`。 +- **禁止**原封照搬 edge_collector 等其它项目的 skill——其 OTA / 协议采集 / 边缘主机 / collector / configurator / cloud_server 等内容在本仓库不存在，会误导。 +- 用 `[[other-skill-name]]` 链接相关技能。 +- 通用工程规范（代码风格、git 提交、shell、前端调试）与项目专属规范（`wind-*`）分开维护。 + +## 命名 +- 项目专属：`wind-`（如 `wind-backend-conventions`、`wind-deploy`） +- 通用：直接 ``（如 `git-commit`、`cpp-coding-style`、`frontend-debug`） + +## 同步 +改完 `.claude/skills/` 后，同步到 `.agents/skills/`（两者结构必须一致）： +```bash +rsync -a --delete .claude/skills/ .agents/skills/ +``` + +## 当前 skill 集（参考） +- 项目专属：`wind-project-overview`、`wind-build-run`、`wind-deploy`、`wind-backend-conventions`、`wind-frontend-conventions`、`wind-third-party-libs` +- 通用：`analyze-questions`、`cpp-coding-style`、`git-commit`、`shell-scripting`、`frontend-debug`、`frontend-dialog`、`frontend-ui-conventions` +- 元：`skill-builder` diff --git a/.agents/skills/third-party-libs/SKILL.md b/.agents/skills/third-party-libs/SKILL.md deleted file mode 100644 index f7d176b..0000000 --- a/.agents/skills/third-party-libs/SKILL.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -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//` 子目录下，`` 取值： - -| 架构标识 | 对应处理器 | -|----------|-----------| -| `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//`，放入编译产物 -5. 在 CMakeLists.txt 中按上述规范引用 diff --git a/.agents/skills/wind-backend-conventions/SKILL.md b/.agents/skills/wind-backend-conventions/SKILL.md new file mode 100644 index 0000000..3f5a0e2 --- /dev/null +++ b/.agents/skills/wind-backend-conventions/SKILL.md @@ -0,0 +1,40 @@ +--- +name: wind-backend-conventions +description: wind_power_cal 后端 Drogon 规范。用于新增/修改后端 Controller、接口、响应、配置时，遵循 HttpController 模式与统一响应信封。 +--- + +# 后端 Drogon 规范 + +## 新增 Controller +1. `backend/src/controllers/XxxController.{h,cpp}`（CMake `GLOB_RECURSE src/*.cpp` 自动纳入，无需改 CMakeLists） +2. 头文件继承 `drogon::HttpController`，用 `METHOD_LIST_BEGIN / ADD_METHOD_TO / METHOD_LIST_END` 声明路由： + ```cpp + METHOD_LIST_BEGIN + ADD_METHOD_TO(XxxController::GetXxx, "/api/xxx", Get); + METHOD_LIST_END + ``` +3. handler 签名：`void GetXxx(const HttpRequestPtr&, std::function&& callback)` +4. `main.cpp` 注册：`app().registerController(std::make_shared());` + +## 响应信封（必须遵守） +统一 `{"status":0,"msg":"success","data":{...}}`，用 `backend/src/utils/ResponseUtil.h`（header-only，自 edge_collector 复制）： +```cpp +#include "utils/ResponseUtil.h" +json data; data["version"] = "0.1.0"; +SendSuccess(callback, data); // 成功带数据 +SendSuccess(callback); // 成功无数据 +SendError(callback, 1, "参数错误"); // 业务错误 +SendForbidden(callback); // 无权限（code 3, 403） +``` + +## include / 命名空间 +- `#include `（third_party/nlohmann 已在 include path） +- `main.cpp` 必须 `using namespace drogon;`，否则 `app()` / `HttpResponse` / `CT_TEXT_HTML` 未声明 + +## 配置 / SPA +- `backend/config/server_config.json`：listener（默认 :8848）、CORS、`document_root ./web` +- SPA 回退：`app().setCustom404Page(HttpResponse::newFileResponse("./web/index.html","",CT_TEXT_HTML), false)` + +## 现有 Controller +- `SystemController`：`/api/system/health`、`/api/system/version` +- `WindPowerController`：风电功率计算业务接口 diff --git a/.agents/skills/wind-build-run/SKILL.md b/.agents/skills/wind-build-run/SKILL.md new file mode 100644 index 0000000..edf8728 --- /dev/null +++ b/.agents/skills/wind-build-run/SKILL.md @@ -0,0 +1,33 @@ +--- +name: wind-build-run +description: wind_power_cal 本地构建与运行规范。用于编译后端、构建前端、打包 runtime、或本地运行前后端时，按正确脚本和顺序操作。 +--- + +# 本地构建与运行 + +## 首次 / Drogon 缺失 +`third_party/ensure_third_party.sh` 源码编译 Drogon+Trantor → `third_party/drogon/install//`。产物存在则秒过（幂等）。详见 [[wind-third-party-libs]]。 + +## 打包 +`bash package.sh --build-type Release` +→ `runtime/wind_power/`：`wind_server` + `config/` + `web/`（前端 dist）+ `libs/`（libdrogon/libtrantor .so）+ `logs/`。 +`--publish` 额外生成 `publish/wind_power-.tar.gz`。 + +## 运行 +- 一键（后端托管 SPA）：`./run.sh`，访问 http://localhost:8848/ +- 仅后端：`bash backend/run.sh`（先 build.sh 再启动，设 `LD_LIBRARY_PATH=libs`） +- 开发（前后端分离热更）： + - 后端 `bash backend/run.sh`（:8848） + - 前端 `cd frontend/web_app && npm install && npm run dev`（:5173，代理 `/api`→:8848） + +## 后端构建细节 +- `backend/CMakeLists.txt`：`find_package(Drogon CONFIG REQUIRED)`，`file(GLOB_RECURSE src/*.cpp)`，链 `Drogon::Drogon`，include `src` + `third_party`。 +- 架构检测 `x64/arm64/arm32`；自动注入 `DROGON_LOCAL_PREFIX`。 +- 运行期 .so 解析：RPATH `$ORIGIN/../lib` + run.sh 设 `LD_LIBRARY_PATH=/libs`。 +- Drogon 编译依赖（Ubuntu）：`libssl-dev libc-ares-dev uuid-dev libjsoncpp-dev zlib1g-dev libbrotli-dev`。 + +## 前端构建 +- `npm run build` → `frontend/web_app/dist/`；`package.sh` 会 rsync 到 `runtime/wind_power/web/`。 +- 入口 `src/main.jsx` → `App.jsx`（react-router）。 + +> 调用 `ensure_third_party.sh` 时**必须**显式传 `THIRD_PARTY=/third_party`（见 [[wind-third-party-libs]]），否则 `SCRIPT_DIR` 推导出错。 diff --git a/.agents/skills/wind-deploy/SKILL.md b/.agents/skills/wind-deploy/SKILL.md new file mode 100644 index 0000000..038e54c --- /dev/null +++ b/.agents/skills/wind-deploy/SKILL.md @@ -0,0 +1,36 @@ +--- +name: wind-deploy +description: wind_power_cal 远端部署规范。用于把服务部署到公网主机（默认 82.157.83.226）时，按 deploy.sh 流程操作并校验 :8848。 +--- + +# 远端部署（deploy.sh） + +当前 `deploy.sh` 只部署 wind_power 本身：**不**安装/配置 nginx，**不**修改 gitea。 + +## 流程 +1. 本地 `package.sh --build-type Release` 生成 `runtime/wind_power/` +2. rsync `runtime/wind_power/` → 远端 `~/wind_power/` +3. 安装/更新 systemd 服务 `wind_power.service` + - `User=ubuntu`，`ExecStart=~/wind_power/wind_server` + - `Environment=LD_LIBRARY_PATH=~/wind_power/libs` + - 日志 `logs/server.log`，`Restart=on-failure` +4. 重启 `wind_power`，校验 `localhost:8848` + +## 远端运行期依赖（最小化服务器常缺） +`sudo apt-get install -y libjsoncpp25 libc-ares2`（deploy.sh 已内置）。 +> wind_server 链 Drogon 的传递依赖；本地 `package.sh` 只打包了 drogon/trantor 的 .so，jsoncpp/c-ares 需远端 apt 提供。 + +## 用法 +- 默认主机：`./deploy.sh` +- 指定主机：`./deploy.sh ubuntu@1.2.3.4` +- 仅本地打包不执行远端变更：`./deploy.sh --dry-run` +- 认证：脚本内置 `SSH_PASSWORD`，用 `sshpass` 非交互登录（如需改用环境变量，自行调整为 `sshpass -e` + `SSHPASS`）。 + +## 校验 +``` +curl -s localhost:8848/api/system/health +# {"status":0,"msg":"success","data":{"status":"ok"}} +``` +查看服务：`ssh ubuntu@82.157.83.226 'systemctl status wind_power'` + +> 若需经 nginx 反代 / 与 gitea 共存 / 改端口，需另行配置（当前 deploy.sh 不涉及，避免与远端已有 gitea 冲突）。 diff --git a/.agents/skills/wind-frontend-conventions/SKILL.md b/.agents/skills/wind-frontend-conventions/SKILL.md new file mode 100644 index 0000000..23d1aec --- /dev/null +++ b/.agents/skills/wind-frontend-conventions/SKILL.md @@ -0,0 +1,40 @@ +--- +name: wind-frontend-conventions +description: wind_power_cal 前端 React+Vite 规范。用于前端页面/接口/路由开发时，遵循 api.js 信封封装、vite 代理与目录约定。 +--- + +# 前端 React+Vite 规范 + +## 目录 +`frontend/web_app/src/`：`main.jsx`（入口）→ `App.jsx`（react-router）→ `pages/` + `utils/api.js`。 + +## API 封装（必须遵守） +`src/utils/api.js`：`BASE_URL='/api'`，`request()` 统一处理信封： +- `fetch('/api'+url, {cache:'no-store'})` → 读 text→`JSON.parse` +- `status===0` 返回 `json.data`；否则 `throw new Error(json.msg)` +- 新增接口在此导出： + ```js + export function getXxx() { return request('/xxx'); } + export function postXxx(payload) { + return request('/xxx', { method: 'POST', body: JSON.stringify(payload) }); + } + ``` + +## 路由 / 主题 +- `react-router-dom` `BrowserRouter`，首页 `pages/HomePage.jsx` +- 暗色主题；样式用 **plain CSS**（`index.css` / `App.css` / `*.module.css`），非 Tailwind / 非 CSS-in-JS +- 后端经 `/api` 前缀；生产由后端托管 SPA（`document_root ./web`） + +## 构建配置 +`vite.config.js`：`base='/'`，dev server :5173，proxy `/api` → `http://localhost:8848`。 + +## 开发 +``` +cd frontend/web_app +npm install +npm run dev # http://localhost:5173 +npm run build # → dist/，由 package.sh 同步到后端 web/ +npm run lint +``` + +> 注意：若将来要把前端挂到子路径（如 nginx `/wind`），必须同步改 `base`、`BrowserRouter basename`、`api.js BASE_URL` 三处——单靠 nginx 无法搬移根路径 SPA（资源/路由是绝对/写死的）。 diff --git a/.agents/skills/wind-project-overview/SKILL.md b/.agents/skills/wind-project-overview/SKILL.md new file mode 100644 index 0000000..9f18e2d --- /dev/null +++ b/.agents/skills/wind-project-overview/SKILL.md @@ -0,0 +1,46 @@ +--- +name: wind-project-overview +description: wind_power_cal 项目概览。用于需要了解工程整体架构、技术栈、目录结构、端口与脚本入口时，先读取本技能获得全局上下文。 +--- + +# wind_power_cal 项目概览 + +风电功率计算平台，前后端单仓库。技术栈与参考工程 edge_collector 对齐（同 C++ Drogon + React）。 + +## 技术栈 +- 后端：C++17 + Drogon HTTP 框架（源码编译），可执行 `wind_server` +- 前端：React 19 + Vite 8 + react-router 7（`frontend/web_app`） +- 第三方：Drogon/Trantor 源码（vendored）、nlohmann/json 头文件库 + +## 目录结构 +``` +wind_power_cal/ +├── third_party/ +│ ├── ensure_third_party.sh # Drogon 源码编译（幂等） +│ ├── drogon_repo/ # Drogon + Trantor 源码 +│ ├── nlohmann/ # header-only json +│ └── drogon/install// # 编译产物（gitignored） +├── backend/ # C++ Drogon 服务 +│ ├── CMakeLists.txt build.sh run.sh +│ ├── config/server_config.json +│ └── src/ main.cpp + controllers/ + utils/ResponseUtil.h +├── frontend/web_app/ # React + Vite +├── package.sh run.sh deploy.sh # 根级 构建/运行/部署 +└── CMakeLists.txt # 顶层（arch 检测 + add_subdirectory(backend)） +``` + +## 端口 +| 服务 | 端口 | +| --- | --- | +| 后端 wind_server | 8848（监听地址见 server_config.json） | +| 前端 dev | 5173（vite proxy `/api` → :8848） | + +## 脚本入口 +- `./run.sh` 一键打包+前台运行（后端托管 SPA） +- `bash backend/run.sh` 仅后端；`cd frontend/web_app && npm run dev` 仅前端 +- `./deploy.sh` 部署到远端（见 [[wind-deploy]]） +- `bash package.sh [--publish]` 打包到 `runtime/wind_power/` + +## 约定 +- 响应统一信封 `{"status":0,"msg":"success","data":{...}}`（见 [[wind-backend-conventions]]） +- MVP 阶段无数据库 / MQTT / 鉴权；结构就位，可参照 edge_collector 扩展 diff --git a/.agents/skills/wind-third-party-libs/SKILL.md b/.agents/skills/wind-third-party-libs/SKILL.md new file mode 100644 index 0000000..fec19a5 --- /dev/null +++ b/.agents/skills/wind-third-party-libs/SKILL.md @@ -0,0 +1,35 @@ +--- +name: wind-third-party-libs +description: wind_power_cal 第三方库管理规范。用于新增/引用/重新编译 third_party 下的 Drogon、nlohmann 等库时，按 ensure_third_party.sh 的源码编译与调用约定操作。 +--- + +# 第三方库管理 + +## 现有 +| 目录 | 说明 | 是否入库 | +| --- | --- | --- | +| `third_party/drogon_repo/` | Drogon + Trantor 源码（vendored，无 .git/build） | ✅ 入库 | +| `third_party/nlohmann/` | header-only json（`json.hpp` + `json_fwd.hpp`） | ✅ 入库 | +| `third_party/drogon/install//` | 源码编译产物 | ❌ gitignored | + +## 源码编译 Drogon +`third_party/ensure_third_party.sh`： +- 架构检测 `x64 / arm64 / arm32` +- cmake flags：`BUILD_SHARED_LIBS=ON USE_SUBMODULE=ON BUILD_CTL=OFF BUILD_EXAMPLES=OFF BUILD_ORM=OFF BUILD_TESTING=OFF BUILD_BROTLI=ON BUILD_YAML_CONFIG=OFF`，`CMAKE_INSTALL_LIBDIR=libs` +- 安装到 `third_party/drogon/install//`；产物存在（`libs/cmake/Drogon/DrogonConfig.cmake`）则跳过 + +## 调用约定（重要，踩过坑） +- **被 source 时**显式传 `THIRD_PARTY=/third_party`：调用方（如 `package.sh`）可能已预设 `SCRIPT_DIR`，会让本脚本 `${SCRIPT_DIR:-}` 推导到错误目录。 + ```bash + THIRD_PARTY="${ROOT_DIR}/third_party" source "${ROOT_DIR}/third_party/ensure_third_party.sh" + ``` +- 脚本内**软失败用 `return`，不要用 `exit`**（被 source 时 `exit` 会杀掉父 shell）。本仓库写法：`return 0 2>/dev/null || exit 0`。 +- 导出 `TARGET_ARCH` 与 `DROGON_INSTALL` 供后续 cmake / run.sh 使用。 + +## 引用方式 +- 后端 CMake：`find_package(Drogon CONFIG REQUIRED)`，由顶层 `DROGON_LOCAL_PREFIX` 注入查找路径。 +- json：`#include `（third_parent 在 include path）。 + +## 新增第三方库 +- header-only（如 nlohmann）：直接放 `third_party//`，CMake 加 include path。 +- 需编译：仿照 `ensure_third_party.sh` 的 Drogon 块，源码放 `third_party/_repo/`，编译安装到 `third_party//install//`，产物 gitignore。 diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..c7746fe --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,7 @@ +{ + "permissions": { + "allow": [ + "Bash(grep -E \"node_modules|/build/|build_package|^runtime/|^publish/|third_party/drogon/install|\\\\.so$|\\\\.o$\")" + ] + } +} diff --git a/.claude/skills/backend-conventions/SKILL.md b/.claude/skills/backend-conventions/SKILL.md deleted file mode 100644 index 64f1ade..0000000 --- a/.claude/skills/backend-conventions/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -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"`） -- 需要同时支持串口和以太网时，新增独立协议条目 diff --git a/.claude/skills/cloud-deploy-verify/SKILL.md b/.claude/skills/cloud-deploy-verify/SKILL.md deleted file mode 100644 index 4d45d92..0000000 --- a/.claude/skills/cloud-deploy-verify/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -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' -``` diff --git a/.claude/skills/cloud-deploy-verify/agents/openai.yaml b/.claude/skills/cloud-deploy-verify/agents/openai.yaml deleted file mode 100644 index fc739c3..0000000 --- a/.claude/skills/cloud-deploy-verify/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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. diff --git a/.claude/skills/cloud-public-deploy/SKILL.md b/.claude/skills/cloud-public-deploy/SKILL.md deleted file mode 100644 index 3cbd341..0000000 --- a/.claude/skills/cloud-public-deploy/SKILL.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -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`。 -- 会保留哪些远端配置。 -- 会重启哪些服务。 -- 公网访问入口和验证接口。 -- 回滚方式和日志位置。 diff --git a/.claude/skills/edge-82-release/SKILL.md b/.claude/skills/edge-82-release/SKILL.md deleted file mode 100644 index ff5126a..0000000 --- a/.claude/skills/edge-82-release/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -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__arm64.tar.gz` 上传到云平台 - - 使用云平台默认 `admin` 账号登录 - -## 上传字段 - -- `file` -- `package_type=edge` -- `version=<版本号>` -- `target_arch=arm64` -- `release_type=stable` -- `visibility=platform` -- `enabled=true` diff --git a/.claude/skills/edge-82-release/agents/openai.yaml b/.claude/skills/edge-82-release/agents/openai.yaml deleted file mode 100644 index 370ca71..0000000 --- a/.claude/skills/edge-82-release/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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 . Upload to the cloud admin account only when the user explicitly asks to publish and upload. diff --git a/.claude/skills/edge-bug-lessons/SKILL.md b/.claude/skills/edge-bug-lessons/SKILL.md deleted file mode 100644 index a638618..0000000 --- a/.claude/skills/edge-bug-lessons/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -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 -| 日期 | 标题 | 模块 | 核心根因 | 漏检点 | 预防规则 | 文件 | -|------|------|------|----------|--------|----------|------| -``` diff --git a/.claude/skills/edge-bugfix/SKILL.md b/.claude/skills/edge-bugfix/SKILL.md deleted file mode 100644 index f1db40f..0000000 --- a/.claude/skills/edge-bugfix/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -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 ` -- 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/` - -报告至少包含：现象、根因、修复、验证、后续预防。 diff --git a/.claude/skills/edge-business-rule-extractor/SKILL.md b/.claude/skills/edge-business-rule-extractor/SKILL.md deleted file mode 100644 index 976bef9..0000000 --- a/.claude/skills/edge-business-rule-extractor/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -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/` 下已有规则/概览文档；没有则建议新增规则表。 - -## 注意 - -- 不把猜测写成规则。 -- 不把一次性临时命令写成规则。 -- 规则变更会影响部署或运行安全时，先让用户确认。 diff --git a/.claude/skills/edge-code-review/SKILL.md b/.claude/skills/edge-code-review/SKILL.md deleted file mode 100644 index b6fcb7e..0000000 --- a/.claude/skills/edge-code-review/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 安装脚本 -- 远程同步/重启逻辑 - diff --git a/.claude/skills/edge-codex-automation/SKILL.md b/.claude/skills/edge-codex-automation/SKILL.md deleted file mode 100644 index 9cb402d..0000000 --- a/.claude/skills/edge-codex-automation/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -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 -自动化任务： -- 名称： -- 目标： -- 执行脚本： -- 调度方式： -- 运行主机： -- 权限需求： -- 日志位置： -- 手工验证： -- 风险： -``` diff --git a/.claude/skills/edge-config-lifecycle/SKILL.md b/.claude/skills/edge-config-lifecycle/SKILL.md deleted file mode 100644 index 12c3567..0000000 --- a/.claude/skills/edge-config-lifecycle/SKILL.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -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 -``` - -同步/部署后验证： - -- 目标主机已有配置仍存在。 -- 新增默认配置可生成。 -- 服务重启后能读取配置。 -- 前端读取和保存正常。 - -## 风险信号 - -- `rsync --delete` -- `cp -r config` -- `cat > config.json` -- 前端保存整个 JSON。 -- 后端启动时无条件重写配置。 -- 示例配置中出现真实 key。 diff --git a/.claude/skills/edge-data-quality-analyzer/SKILL.md b/.claude/skills/edge-data-quality-analyzer/SKILL.md deleted file mode 100644 index d83e6e7..0000000 --- a/.claude/skills/edge-data-quality-analyzer/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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 -## 数据范围 - -## 关键统计 - -## 异常片段 - -## 原因判断 - -## 建议动作 -``` diff --git a/.claude/skills/edge-database-ops/SKILL.md b/.claude/skills/edge-database-ops/SKILL.md deleted file mode 100644 index 0828443..0000000 --- a/.claude/skills/edge-database-ops/SKILL.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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
WHERE ; -``` - -必要时导出为临时文件，并说明路径。 - -## 常用只读检查 - -PostgreSQL： - -```sql -SELECT now(); -SELECT version(); -``` - -TDengine： - -```sql -SHOW DATABASES; -SHOW STABLES; -``` - -SQLite： - -```bash -sqlite3 ".tables" -sqlite3 "PRAGMA integrity_check;" -``` - -## 输出要求 - -- 说明数据来源。 -- 说明查询条件和时间范围。 -- 说明结论是事实还是推断。 -- 给出下一步建议。 - -## 禁止事项 - -- 未确认就执行 `UPDATE`、`DELETE`、`DROP`、`TRUNCATE`。 -- 把配置中的数据库密码打印到回复。 -- 用线上写操作验证猜测。 -- 将大量敏感原始数据贴到对话中。 diff --git a/.claude/skills/edge-deployment-writer/SKILL.md b/.claude/skills/edge-deployment-writer/SKILL.md deleted file mode 100644 index 3b1f860..0000000 --- a/.claude/skills/edge-deployment-writer/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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:/api/health -``` - -脚本： - -```bash -bash -n scripts/.sh -``` - -## 回滚说明 - -文档必须说明： - -- 上一个 runtime/edge 或发布包位置。 -- 如何恢复二进制和 web 资源。 -- 哪些配置不能回滚覆盖。 -- 回滚后如何重启服务和验证。 - diff --git a/.claude/skills/edge-design-doc-writer/SKILL.md b/.claude/skills/edge-design-doc-writer/SKILL.md deleted file mode 100644 index 526019a..0000000 --- a/.claude/skills/edge-design-doc-writer/SKILL.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -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`。 - -## 方案验证 - -文档结尾必须写： - -- 单元测试或脚本验证。 -- 构建验证。 -- 远程部署验证（如需要）。 -- 回滚或降级策略。 - diff --git a/.claude/skills/edge-design-reviewer/SKILL.md b/.claude/skills/edge-design-reviewer/SKILL.md deleted file mode 100644 index 7cf3d99..0000000 --- a/.claude/skills/edge-design-reviewer/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -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，拿不准时要联网查证。 diff --git a/.claude/skills/edge-doc-coauthoring/SKILL.md b/.claude/skills/edge-doc-coauthoring/SKILL.md deleted file mode 100644 index f45323d..0000000 --- a/.claude/skills/edge-doc-coauthoring/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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 -功能用途 -使用步骤 -参数解释 -常见问题 -注意事项 -``` - -## 约束 - -- 给用户看的协议介绍不透露内部技术细节。 -- 技术方案可写实现细节，但要标注假设和验证状态。 -- 引用外部信息时提供链接。 -- 不把未经验证的能力写成已完成。 - diff --git a/.claude/skills/edge-framework-learner/SKILL.md b/.claude/skills/edge-framework-learner/SKILL.md deleted file mode 100644 index 3944483..0000000 --- a/.claude/skills/edge-framework-learner/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -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//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 或云平台验证。 -- 是否需要文档区分用户说明和技术细节。 - -## 输出语气 - -给用户的是选型和落地建议，不堆砌官方概念；每条建议都要说明对当前工程的影响。 diff --git a/.claude/skills/edge-frontend-design/SKILL.md b/.claude/skills/edge-frontend-design/SKILL.md deleted file mode 100644 index cc7861e..0000000 --- a/.claude/skills/edge-frontend-design/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -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。 -- 参数说明写影响和建议值。 -- 空状态告诉用户下一步操作。 - -## 设计检查 - -- 是否有大片空白。 -- 文本是否溢出。 -- 窄屏是否可用。 -- 操作后是否有反馈。 -- 图表、表格、报告是否互相遮挡。 -- 权限不足是否有清晰状态。 -- 与相邻模块按钮和标签风格是否一致。 diff --git a/.claude/skills/edge-frontend-testing/SKILL.md b/.claude/skills/edge-frontend-testing/SKILL.md deleted file mode 100644 index dd4a1c2..0000000 --- a/.claude/skills/edge-frontend-testing/SKILL.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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./` - -## 验证顺序 - -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 不导致布局抖动。 -- 报告和表格区域可滚动。 -- 文案不泄露内部实现。 -- 动态配置不会因为前端保存被清空。 diff --git a/.claude/skills/edge-local-dev-services/SKILL.md b/.claude/skills/edge-local-dev-services/SKILL.md deleted file mode 100644 index e132130..0000000 --- a/.claude/skills/edge-local-dev-services/SKILL.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -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`，除非用户明确要求。 - -## 输出 - -最终说明： - -- 启动或检查了哪些服务。 -- 使用了哪些端口。 -- 哪些接口验证通过。 -- 日志里是否有错误。 -- 如何停止本次启动的临时服务。 diff --git a/.claude/skills/edge-markdown-docs/SKILL.md b/.claude/skills/edge-markdown-docs/SKILL.md deleted file mode 100644 index 2fc0df1..0000000 --- a/.claude/skills/edge-markdown-docs/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -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 引用：浏览器或图片查看器打开检查 diff --git a/.claude/skills/edge-mcp-tools/SKILL.md b/.claude/skills/edge-mcp-tools/SKILL.md deleted file mode 100644 index 9883ff2..0000000 --- a/.claude/skills/edge-mcp-tools/SKILL.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -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 - -## 数据来源 - -## 部署方式 - -## 安全与脱敏 - -## 验证计划 -``` diff --git a/.claude/skills/edge-observability/SKILL.md b/.claude/skills/edge-observability/SKILL.md deleted file mode 100644 index 095ef08..0000000 --- a/.claude/skills/edge-observability/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -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 频繁拉起。 diff --git a/.claude/skills/edge-pdf-docs/SKILL.md b/.claude/skills/edge-pdf-docs/SKILL.md deleted file mode 100644 index d13c49a..0000000 --- a/.claude/skills/edge-pdf-docs/SKILL.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -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 和模型配置。 diff --git a/.claude/skills/edge-presentation-docs/SKILL.md b/.claude/skills/edge-presentation-docs/SKILL.md deleted file mode 100644 index bc12b62..0000000 --- a/.claude/skills/edge-presentation-docs/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 配置、密钥和调试信息。 diff --git a/.claude/skills/edge-project-overview/SKILL.md b/.claude/skills/edge-project-overview/SKILL.md deleted file mode 100644 index c3cc18d..0000000 --- a/.claude/skills/edge-project-overview/SKILL.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -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` 的规范需要写入。 diff --git a/.claude/skills/edge-project-plan-writer/SKILL.md b/.claude/skills/edge-project-plan-writer/SKILL.md deleted file mode 100644 index bb71831..0000000 --- a/.claude/skills/edge-project-plan-writer/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -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 验证。 - -## 输出要求 - -- 计划要能直接转成执行清单。 -- 不确定项标为“待确认”，不要伪装成已完成。 -- 时间排期必须留出联调、回归和远程部署验证。 diff --git a/.claude/skills/edge-protocol-research/SKILL.md b/.claude/skills/edge-protocol-research/SKILL.md deleted file mode 100644 index c98fa4e..0000000 --- a/.claude/skills/edge-protocol-research/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -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 路径、库文件细节。 diff --git a/.claude/skills/edge-prototype-design/SKILL.md b/.claude/skills/edge-prototype-design/SKILL.md deleted file mode 100644 index 5f81703..0000000 --- a/.claude/skills/edge-prototype-design/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -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/反馈。 -- 是否支持窄屏。 -- 危险操作是否二次确认。 -- 用户可见文案是否隐藏内部实现细节。 diff --git a/.claude/skills/edge-python-agent/SKILL.md b/.claude/skills/edge-python-agent/SKILL.md deleted file mode 100644 index f6a1aa7..0000000 --- a/.claude/skills/edge-python-agent/SKILL.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -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 ---log-level ---once ---dry-run -``` - -`--once` 适合调试和安装后验证。 - -## 验证 - -至少验证： - -```bash -python3 -m py_compile scripts//.py -python3 scripts//.py --help -``` - -常驻服务验证： - -```bash -systemctl status --no-pager -journalctl -u --since "5 min ago" --no-pager -``` diff --git a/.claude/skills/edge-release-notes/SKILL.md b/.claude/skills/edge-release-notes/SKILL.md deleted file mode 100644 index 444b019..0000000 --- a/.claude/skills/edge-release-notes/SKILL.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -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 包说明 - -面向用户时写： - -- 新增能力。 -- 修复问题。 -- 升级注意事项。 -- 回滚建议。 - -避免写内部提交号、代码路径和密钥。 diff --git a/.claude/skills/edge-release-prepare/SKILL.md b/.claude/skills/edge-release-prepare/SKILL.md deleted file mode 100644 index f2d5b05..0000000 --- a/.claude/skills/edge-release-prepare/SKILL.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -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__arm64.tar.gz` -- 版本信息：一句话概括本次发布 -- 版本说明：多行列点，来自用户说明、最近提交、已完成改动和验证结果 -- 后续动作预览：确认后将在 82 执行 `./package.sh --publish --version `，必要时上传云平台 - -## 确认边界 - -- 在用户明确确认前，禁止执行 `./package.sh --publish --version ...` -- 在用户明确确认前，禁止上传云平台 -- 用户确认后，再按 `edge-82-release` 的发布流程执行 - -## 建议输出格式 - -```text -发布草案： -- 版本号： -- 架构：arm64 -- 发布类型：release -- 产物：publish/edge__arm64.tar.gz - -版本信息： -<一句话说明> - -版本说明： -- <说明 1> -- <说明 2> - -确认后执行： -1. 82: ./package.sh --publish --version -2. 如需上传云平台，使用上述版本说明和发布类型 -``` diff --git a/.claude/skills/edge-release-prepare/agents/openai.yaml b/.claude/skills/edge-release-prepare/agents/openai.yaml deleted file mode 100644 index 46465f8..0000000 --- a/.claude/skills/edge-release-prepare/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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. diff --git a/.claude/skills/edge-remote-access/SKILL.md b/.claude/skills/edge-remote-access/SKILL.md deleted file mode 100644 index 3a6f9df..0000000 --- a/.claude/skills/edge-remote-access/SKILL.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -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 -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 -arp -an | grep -``` - -## 输出要求 - -最终说明： - -- 连接的主机。 -- 执行的关键只读检查。 -- 发现的异常证据。 -- 未执行的高风险动作。 -- 建议下一步。 diff --git a/.claude/skills/edge-requirement-interview/SKILL.md b/.claude/skills/edge-requirement-interview/SKILL.md deleted file mode 100644 index 78f5d0c..0000000 --- a/.claude/skills/edge-requirement-interview/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -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`。 diff --git a/.claude/skills/edge-security-secrets/SKILL.md b/.claude/skills/edge-security-secrets/SKILL.md deleted file mode 100644 index 576b284..0000000 --- a/.claude/skills/edge-security-secrets/SKILL.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -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 报告、导出报告不写内部技术细节和密钥。 -- 运维文档可以写配置路径和字段含义，但示例值必须使用占位符。 diff --git a/.claude/skills/edge-skill-builder/SKILL.md b/.claude/skills/edge-skill-builder/SKILL.md deleted file mode 100644 index e554a7f..0000000 --- a/.claude/skills/edge-skill-builder/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: edge-skill-builder -description: edge_collector 技能建设规范。用于从外部仓库、已有流程、项目经验、框架/SDK 学习结果中创建或改写 .agents/skills 下的 Codex skills，要求结合当前 C++/Drogon/React/Vite/云边部署/现场主机实际情况，避免原封不动照搬无关技术栈。 ---- - -# edge_collector 技能建设 - -## 目标 - -把项目中重复出现的流程和判断沉淀为 `.agents/skills//SKILL.md`，让后续任务能稳定复用。 - -## 适用来源 - -- 当前仓库脚本，如 `deploy_cloud.sh`、`package.sh`、`scripts/migrate_edge.sh`。 -- 已完成的故障排查和现场经验。 -- 外部仓库中的通用 skill。 -- 官方文档或 SDK 调研结果。 -- 用户明确确认的长期规则。 - -## 命名规则 - -- 使用小写短横线。 -- 本项目专用优先加 `edge-` 前缀。 -- 云平台专用可用 `cloud-` 前缀。 -- 名称要表达动作或场景，例如 `edge-frontend-testing`。 - -## frontmatter - -只写： - -```yaml ---- -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/ -``` - -同时检查： - -```bash -grep -R "Java\\|Spring\\|K3s\\|Ant Design\\|Umi\\|one_person" -n .agents/skills/ || true -``` - -如果出现这些词，要确认是项目真实需要，还是外部 skill 残留。 - -## 输出 - -最终向用户说明： - -- 新增或修改了哪些 skill。 -- 每个 skill 覆盖什么场景。 -- 是否通过校验。 -- 是否只改了 skill 文件，是否未提交。 diff --git a/.claude/skills/edge-spreadsheet-docs/SKILL.md b/.claude/skills/edge-spreadsheet-docs/SKILL.md deleted file mode 100644 index 98887a1..0000000 --- a/.claude/skills/edge-spreadsheet-docs/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -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?`。 -- 修改既有模板时保留原列顺序和样式，除非用户明确要求调整。 diff --git a/.claude/skills/edge-svg-diagram/SKILL.md b/.claude/skills/edge-svg-diagram/SKILL.md deleted file mode 100644 index 47e2c02..0000000 --- a/.claude/skills/edge-svg-diagram/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -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。 -- 确认文字不重叠、不截断。 -- 确认中文显示正常。 -- 确认风格与用途匹配：文档图可打印，前端原型图与项目暗色主题一致。 -- 文档引用路径有效。 diff --git a/.claude/skills/edge-sync-host/SKILL.md b/.claude/skills/edge-sync-host/SKILL.md deleted file mode 100644 index ad9d699..0000000 --- a/.claude/skills/edge-sync-host/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -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 -``` - -随后也要把重启命令中的目标地址替换为 `192.168.40.`，执行 `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` 服务；不要只同步文件就结束。 -- 如果用户明确指定源主机、目标用户、目标目录或密码，以用户本次明确值为准，并透传给脚本参数。 diff --git a/.claude/skills/edge-sync-host/agents/openai.yaml b/.claude/skills/edge-sync-host/agents/openai.yaml deleted file mode 100644 index 1595869..0000000 --- a/.claude/skills/edge-sync-host/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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 from the repo root. Treat 87 only as an example; other numbered hosts map to 192.168.40.. After sync succeeds, SSH to cat@192.168.40. 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. diff --git a/.claude/skills/edge-system-test-writer/SKILL.md b/.claude/skills/edge-system-test-writer/SKILL.md deleted file mode 100644 index f0af846..0000000 --- a/.claude/skills/edge-system-test-writer/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -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/.sh -jq empty -``` - -远程同步或重启必须等用户明确要求，并遵循对应部署 skill。 - -## 问题回溯 - -测试文档应保留问题回溯表： - -```markdown -| 问题 | 影响场景 | 根因位置 | 修复提交/文件 | 回归结果 | -|------|----------|----------|----------------|----------| -``` diff --git a/.claude/skills/edge-technical-zeroing-report/SKILL.md b/.claude/skills/edge-technical-zeroing-report/SKILL.md deleted file mode 100644 index da0efc2..0000000 --- a/.claude/skills/edge-technical-zeroing-report/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -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/` diff --git a/.claude/skills/edge-user-manual-writer/SKILL.md b/.claude/skills/edge-user-manual-writer/SKILL.md deleted file mode 100644 index f40c90d..0000000 --- a/.claude/skills/edge-user-manual-writer/SKILL.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: edge-user-manual-writer -description: edge_collector 用户手册与交付说明编写规范。用于为边缘侧前端、云平台、协议配置、AI 分析、WiFi、端口转发、内网穿透、OTA、离线缓存等用户可见功能编写操作说明、培训材料、交付文档和常见问题，避免暴露内部技术细节。 ---- - -# edge_collector 用户手册编写 - -## 读者 - -- 现场实施人员。 -- 运维人员。 -- 管理后台用户。 -- 客户侧使用人员。 - -## 文档落点 - -- 用户手册：`docs/` 或对应专题目录。 -- 协议用户说明：优先与协议文档分开，用户可见介绍不能写内部实现细节。 -- 鲁班猫设备操作：`docs/鲁班猫*/`。 - -## 推荐结构 - -```text -功能用途 -适用场景 -使用前准备 -操作步骤 -参数说明 -状态说明 -常见问题 -注意事项 -``` - -## 写作规则 - -- 面向用户目标写，不按代码模块写。 -- 只写用户能看到、能操作、能验证的内容。 -- 隐藏内部模型名、AI Provider 名称、helper、进程、库路径等技术细节，除非读者是运维人员且文档明确为运维手册。 -- 参数说明要写“影响和建议值”，不要只复述字段名。 -- 错误说明要写用户下一步可以怎么处理。 - -## 当前项目常见功能口径 - -- AI 分析：说明分析深度、提示词、数据不连续的业务原因，不显示内部 AI 配置。 -- WiFi 管理：说明扫描、刷新、加入隐藏网络、已保存网络连接、自动连接。 -- 内网穿透：说明映射启停、保存配置、云端配置失败提示。 -- 端口转发：说明规则启停、监听地址、目标地址、冲突端口。 -- 离线缓存：说明最大缓存、保留天数、重传批次、重传速率的影响。 - -## 检查清单 - -- 功能名称和界面文案一致。 -- 操作步骤能被现场用户照着完成。 -- 参数默认值和当前代码/配置一致。 -- 没有泄露内部接口、密钥、模型、库路径。 -- 有失败场景和恢复建议。 diff --git a/.claude/skills/edge-user-story-reviewer/SKILL.md b/.claude/skills/edge-user-story-reviewer/SKILL.md deleted file mode 100644 index a2d0d9b..0000000 --- a/.claude/skills/edge-user-story-reviewer/SKILL.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -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`。 diff --git a/.claude/skills/edge-user-story-writer/SKILL.md b/.claude/skills/edge-user-story-writer/SKILL.md deleted file mode 100644 index 3b0a325..0000000 --- a/.claude/skills/edge-user-story-writer/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -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--: <简短标题> - -**角色**: <现场用户/运维人员/平台管理员/开发人员> -**优先级**: 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---<简短标题>-业务场景图.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、内部模型配置写进用户可见故事。 -- 对部署类故事，必须写清是否会重启服务、是否影响运行配置。 diff --git a/.claude/skills/edge-webapp-testing/SKILL.md b/.claude/skills/edge-webapp-testing/SKILL.md deleted file mode 100644 index a6ebc9d..0000000 --- a/.claude/skills/edge-webapp-testing/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -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。 -- 构建命令结果。 -- 发现的问题和截图路径（如有）。 - diff --git a/.claude/skills/edge-word-docx/SKILL.md b/.claude/skills/edge-word-docx/SKILL.md deleted file mode 100644 index 533b758..0000000 --- a/.claude/skills/edge-word-docx/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 时，尽量保留原模板样式。 -- 涉及密钥、账号、内网地址时，交付版要脱敏。 diff --git a/.claude/skills/frontend-conventions/SKILL.md b/.claude/skills/frontend-conventions/SKILL.md deleted file mode 100644 index a97d986..0000000 --- a/.claude/skills/frontend-conventions/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: frontend-conventions -description: 前端 UI 组件使用规范。用于本仓库前端页面开发时，统一下拉组件、只读字段展示方式，避免原生控件导致交互和样式不一致。 ---- - -# 前端组件规范 - -## 下拉控件 - -- 必须使用 `CustomSelect` -- 禁止直接写原生 `` 或是手写带放大镜图标的输入框 -- `SearchInput` 组件需统一具备清除按钮和 `onChange` 的直接值映射 -- 已集成在 `src/components/common/` 目录下 - -## 组件复用优先级 - -- 页面开发前先检查现有组件：`frontend/config_app/src/components/common/`、`frontend/cloud_app/src/components/common/` -- 已有自定义组件必须优先复用，禁止在页面中重复实现同类 UI 逻辑 -- 仅当现有组件无法满足需求时才允许新增组件，并优先沉淀到各自工程的 `src/components/common/` -- 新增或改造组件时，保持 API 向后兼容，避免一次改动引发多页面回归 - -示例： - -```jsx - -``` - -## 只读字段 - -- 禁止使用 `` 伪装只读 -- 使用 `` 或 `
` + 只读样式类 - -## 设计目标 - -- 保持交互行为一致 -- 保持视觉样式一致 -- 降低页面间重复实现 diff --git a/.claude/skills/host-connection-defaults/SKILL.md b/.claude/skills/host-connection-defaults/SKILL.md deleted file mode 100644 index 8323542..0000000 --- a/.claude/skills/host-connection-defaults/SKILL.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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.<数字> ''`。 -- 如用户只要求连接或排查连接，优先执行无破坏的只读命令，如 `hostname`、`uptime`、`ip addr`。 -- 不要把“其他数字主机”固定成 99；数字以用户本次说出的主机号为准。 -- 如果用户明确给出不同用户名、IP 或密码，以用户本次明确值为准。 diff --git a/.claude/skills/ota-e2e-release/SKILL.md b/.claude/skills/ota-e2e-release/SKILL.md deleted file mode 100644 index d334aba..0000000 --- a/.claude/skills/ota-e2e-release/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -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 ` - -2. 上传到云平台 - - 使用云平台 `admin` 账号登录 - - 上传 `publish/edge__arm64.tar.gz` - - 确认版本号、架构、发布状态与产物一致 - -3. 87 主机 OTA 验证 - - 打开边缘侧前端 - - 查询云平台可用版本，确认 `` 可见 - - 通过前端接口触发 OTA 升级 - - 检查 `/api/ota/status`，确认当前版本已变成 `` - -## 失败时优先排查 - -- 云端字段或页面不生效：先确认已走 `deploy_cloud.sh`，再查 `cloud-server` 状态和云端接口响应 -- 87 上看不到版本：先确认 82 包已上传成功，再查 87 的 OTA 配置 -- 87 OTA 起不来：先执行 `sudo bash /home/cat/edge/scripts/ota/install_ota_service.sh` -- 前端升级失败：先看后端 OTA 接口返回，再看服务日志 diff --git a/.claude/skills/ota-e2e-release/agents/openai.yaml b/.claude/skills/ota-e2e-release/agents/openai.yaml deleted file mode 100644 index f831197..0000000 --- a/.claude/skills/ota-e2e-release/agents/openai.yaml +++ /dev/null @@ -1,3 +0,0 @@ -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 , upload publish/edge__arm64.tar.gz to the cloud admin account, validate OTA from the 87-side frontend, and verify the current version becomes . diff --git a/.claude/skills/project-structure/SKILL.md b/.claude/skills/project-structure/SKILL.md deleted file mode 100644 index af9fa57..0000000 --- a/.claude/skills/project-structure/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -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/` 目录下 - diff --git a/.claude/skills/protocol-e2e-testing/SKILL.md b/.claude/skills/protocol-e2e-testing/SKILL.md deleted file mode 100644 index 8b9c99b..0000000 --- a/.claude/skills/protocol-e2e-testing/SKILL.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 的原始报文。 diff --git a/.claude/skills/skill-builder/SKILL.md b/.claude/skills/skill-builder/SKILL.md new file mode 100644 index 0000000..b1f6dd9 --- /dev/null +++ b/.claude/skills/skill-builder/SKILL.md @@ -0,0 +1,31 @@ +--- +name: skill-builder +description: 技能建设规范。用于为 wind_power_cal 创建/改写 .agents/skills 与 .claude/skills 下的 skill，要求贴合当前 C++/Drogon/React/Vite 技术栈，避免照搬无关项目。 +--- + +# 技能建设规范 + +为本仓库创建或改写 skill（`.agents/skills/` 与 `.claude/skills/` 需保持同步）。 + +## 规则 +- 每个 skill 一个目录，内含 `SKILL.md`。 +- frontmatter：`name`（kebab-case）、`description`（一句话：**何时触发** + 做什么；用于检索匹配）。 +- 内容贴合 **wind_power_cal 实际**：C++ Drogon 后端（:8848）、React+Vite 前端、`package.sh / run.sh / deploy.sh`、`third_party` 源码编译 Drogon、响应信封 `{status,msg,data}`。 +- **禁止**原封照搬 edge_collector 等其它项目的 skill——其 OTA / 协议采集 / 边缘主机 / collector / configurator / cloud_server 等内容在本仓库不存在，会误导。 +- 用 `[[other-skill-name]]` 链接相关技能。 +- 通用工程规范（代码风格、git 提交、shell、前端调试）与项目专属规范（`wind-*`）分开维护。 + +## 命名 +- 项目专属：`wind-`（如 `wind-backend-conventions`、`wind-deploy`） +- 通用：直接 ``（如 `git-commit`、`cpp-coding-style`、`frontend-debug`） + +## 同步 +改完 `.claude/skills/` 后，同步到 `.agents/skills/`（两者结构必须一致）： +```bash +rsync -a --delete .claude/skills/ .agents/skills/ +``` + +## 当前 skill 集（参考） +- 项目专属：`wind-project-overview`、`wind-build-run`、`wind-deploy`、`wind-backend-conventions`、`wind-frontend-conventions`、`wind-third-party-libs` +- 通用：`analyze-questions`、`cpp-coding-style`、`git-commit`、`shell-scripting`、`frontend-debug`、`frontend-dialog`、`frontend-ui-conventions` +- 元：`skill-builder` diff --git a/.claude/skills/third-party-libs/SKILL.md b/.claude/skills/third-party-libs/SKILL.md deleted file mode 100644 index f7d176b..0000000 --- a/.claude/skills/third-party-libs/SKILL.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -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//` 子目录下，`` 取值： - -| 架构标识 | 对应处理器 | -|----------|-----------| -| `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//`，放入编译产物 -5. 在 CMakeLists.txt 中按上述规范引用 diff --git a/.claude/skills/wind-backend-conventions/SKILL.md b/.claude/skills/wind-backend-conventions/SKILL.md new file mode 100644 index 0000000..3f5a0e2 --- /dev/null +++ b/.claude/skills/wind-backend-conventions/SKILL.md @@ -0,0 +1,40 @@ +--- +name: wind-backend-conventions +description: wind_power_cal 后端 Drogon 规范。用于新增/修改后端 Controller、接口、响应、配置时，遵循 HttpController 模式与统一响应信封。 +--- + +# 后端 Drogon 规范 + +## 新增 Controller +1. `backend/src/controllers/XxxController.{h,cpp}`（CMake `GLOB_RECURSE src/*.cpp` 自动纳入，无需改 CMakeLists） +2. 头文件继承 `drogon::HttpController`，用 `METHOD_LIST_BEGIN / ADD_METHOD_TO / METHOD_LIST_END` 声明路由： + ```cpp + METHOD_LIST_BEGIN + ADD_METHOD_TO(XxxController::GetXxx, "/api/xxx", Get); + METHOD_LIST_END + ``` +3. handler 签名：`void GetXxx(const HttpRequestPtr&, std::function&& callback)` +4. `main.cpp` 注册：`app().registerController(std::make_shared());` + +## 响应信封（必须遵守） +统一 `{"status":0,"msg":"success","data":{...}}`，用 `backend/src/utils/ResponseUtil.h`（header-only，自 edge_collector 复制）： +```cpp +#include "utils/ResponseUtil.h" +json data; data["version"] = "0.1.0"; +SendSuccess(callback, data); // 成功带数据 +SendSuccess(callback); // 成功无数据 +SendError(callback, 1, "参数错误"); // 业务错误 +SendForbidden(callback); // 无权限（code 3, 403） +``` + +## include / 命名空间 +- `#include `（third_party/nlohmann 已在 include path） +- `main.cpp` 必须 `using namespace drogon;`，否则 `app()` / `HttpResponse` / `CT_TEXT_HTML` 未声明 + +## 配置 / SPA +- `backend/config/server_config.json`：listener（默认 :8848）、CORS、`document_root ./web` +- SPA 回退：`app().setCustom404Page(HttpResponse::newFileResponse("./web/index.html","",CT_TEXT_HTML), false)` + +## 现有 Controller +- `SystemController`：`/api/system/health`、`/api/system/version` +- `WindPowerController`：风电功率计算业务接口 diff --git a/.claude/skills/wind-build-run/SKILL.md b/.claude/skills/wind-build-run/SKILL.md new file mode 100644 index 0000000..edf8728 --- /dev/null +++ b/.claude/skills/wind-build-run/SKILL.md @@ -0,0 +1,33 @@ +--- +name: wind-build-run +description: wind_power_cal 本地构建与运行规范。用于编译后端、构建前端、打包 runtime、或本地运行前后端时，按正确脚本和顺序操作。 +--- + +# 本地构建与运行 + +## 首次 / Drogon 缺失 +`third_party/ensure_third_party.sh` 源码编译 Drogon+Trantor → `third_party/drogon/install//`。产物存在则秒过（幂等）。详见 [[wind-third-party-libs]]。 + +## 打包 +`bash package.sh --build-type Release` +→ `runtime/wind_power/`：`wind_server` + `config/` + `web/`（前端 dist）+ `libs/`（libdrogon/libtrantor .so）+ `logs/`。 +`--publish` 额外生成 `publish/wind_power-.tar.gz`。 + +## 运行 +- 一键（后端托管 SPA）：`./run.sh`，访问 http://localhost:8848/ +- 仅后端：`bash backend/run.sh`（先 build.sh 再启动，设 `LD_LIBRARY_PATH=libs`） +- 开发（前后端分离热更）： + - 后端 `bash backend/run.sh`（:8848） + - 前端 `cd frontend/web_app && npm install && npm run dev`（:5173，代理 `/api`→:8848） + +## 后端构建细节 +- `backend/CMakeLists.txt`：`find_package(Drogon CONFIG REQUIRED)`，`file(GLOB_RECURSE src/*.cpp)`，链 `Drogon::Drogon`，include `src` + `third_party`。 +- 架构检测 `x64/arm64/arm32`；自动注入 `DROGON_LOCAL_PREFIX`。 +- 运行期 .so 解析：RPATH `$ORIGIN/../lib` + run.sh 设 `LD_LIBRARY_PATH=/libs`。 +- Drogon 编译依赖（Ubuntu）：`libssl-dev libc-ares-dev uuid-dev libjsoncpp-dev zlib1g-dev libbrotli-dev`。 + +## 前端构建 +- `npm run build` → `frontend/web_app/dist/`；`package.sh` 会 rsync 到 `runtime/wind_power/web/`。 +- 入口 `src/main.jsx` → `App.jsx`（react-router）。 + +> 调用 `ensure_third_party.sh` 时**必须**显式传 `THIRD_PARTY=/third_party`（见 [[wind-third-party-libs]]），否则 `SCRIPT_DIR` 推导出错。 diff --git a/.claude/skills/wind-deploy/SKILL.md b/.claude/skills/wind-deploy/SKILL.md new file mode 100644 index 0000000..038e54c --- /dev/null +++ b/.claude/skills/wind-deploy/SKILL.md @@ -0,0 +1,36 @@ +--- +name: wind-deploy +description: wind_power_cal 远端部署规范。用于把服务部署到公网主机（默认 82.157.83.226）时，按 deploy.sh 流程操作并校验 :8848。 +--- + +# 远端部署（deploy.sh） + +当前 `deploy.sh` 只部署 wind_power 本身：**不**安装/配置 nginx，**不**修改 gitea。 + +## 流程 +1. 本地 `package.sh --build-type Release` 生成 `runtime/wind_power/` +2. rsync `runtime/wind_power/` → 远端 `~/wind_power/` +3. 安装/更新 systemd 服务 `wind_power.service` + - `User=ubuntu`，`ExecStart=~/wind_power/wind_server` + - `Environment=LD_LIBRARY_PATH=~/wind_power/libs` + - 日志 `logs/server.log`，`Restart=on-failure` +4. 重启 `wind_power`，校验 `localhost:8848` + +## 远端运行期依赖（最小化服务器常缺） +`sudo apt-get install -y libjsoncpp25 libc-ares2`（deploy.sh 已内置）。 +> wind_server 链 Drogon 的传递依赖；本地 `package.sh` 只打包了 drogon/trantor 的 .so，jsoncpp/c-ares 需远端 apt 提供。 + +## 用法 +- 默认主机：`./deploy.sh` +- 指定主机：`./deploy.sh ubuntu@1.2.3.4` +- 仅本地打包不执行远端变更：`./deploy.sh --dry-run` +- 认证：脚本内置 `SSH_PASSWORD`，用 `sshpass` 非交互登录（如需改用环境变量，自行调整为 `sshpass -e` + `SSHPASS`）。 + +## 校验 +``` +curl -s localhost:8848/api/system/health +# {"status":0,"msg":"success","data":{"status":"ok"}} +``` +查看服务：`ssh ubuntu@82.157.83.226 'systemctl status wind_power'` + +> 若需经 nginx 反代 / 与 gitea 共存 / 改端口，需另行配置（当前 deploy.sh 不涉及，避免与远端已有 gitea 冲突）。 diff --git a/.claude/skills/wind-frontend-conventions/SKILL.md b/.claude/skills/wind-frontend-conventions/SKILL.md new file mode 100644 index 0000000..23d1aec --- /dev/null +++ b/.claude/skills/wind-frontend-conventions/SKILL.md @@ -0,0 +1,40 @@ +--- +name: wind-frontend-conventions +description: wind_power_cal 前端 React+Vite 规范。用于前端页面/接口/路由开发时，遵循 api.js 信封封装、vite 代理与目录约定。 +--- + +# 前端 React+Vite 规范 + +## 目录 +`frontend/web_app/src/`：`main.jsx`（入口）→ `App.jsx`（react-router）→ `pages/` + `utils/api.js`。 + +## API 封装（必须遵守） +`src/utils/api.js`：`BASE_URL='/api'`，`request()` 统一处理信封： +- `fetch('/api'+url, {cache:'no-store'})` → 读 text→`JSON.parse` +- `status===0` 返回 `json.data`；否则 `throw new Error(json.msg)` +- 新增接口在此导出： + ```js + export function getXxx() { return request('/xxx'); } + export function postXxx(payload) { + return request('/xxx', { method: 'POST', body: JSON.stringify(payload) }); + } + ``` + +## 路由 / 主题 +- `react-router-dom` `BrowserRouter`，首页 `pages/HomePage.jsx` +- 暗色主题；样式用 **plain CSS**（`index.css` / `App.css` / `*.module.css`），非 Tailwind / 非 CSS-in-JS +- 后端经 `/api` 前缀；生产由后端托管 SPA（`document_root ./web`） + +## 构建配置 +`vite.config.js`：`base='/'`，dev server :5173，proxy `/api` → `http://localhost:8848`。 + +## 开发 +``` +cd frontend/web_app +npm install +npm run dev # http://localhost:5173 +npm run build # → dist/，由 package.sh 同步到后端 web/ +npm run lint +``` + +> 注意：若将来要把前端挂到子路径（如 nginx `/wind`），必须同步改 `base`、`BrowserRouter basename`、`api.js BASE_URL` 三处——单靠 nginx 无法搬移根路径 SPA（资源/路由是绝对/写死的）。 diff --git a/.claude/skills/wind-project-overview/SKILL.md b/.claude/skills/wind-project-overview/SKILL.md new file mode 100644 index 0000000..9f18e2d --- /dev/null +++ b/.claude/skills/wind-project-overview/SKILL.md @@ -0,0 +1,46 @@ +--- +name: wind-project-overview +description: wind_power_cal 项目概览。用于需要了解工程整体架构、技术栈、目录结构、端口与脚本入口时，先读取本技能获得全局上下文。 +--- + +# wind_power_cal 项目概览 + +风电功率计算平台，前后端单仓库。技术栈与参考工程 edge_collector 对齐（同 C++ Drogon + React）。 + +## 技术栈 +- 后端：C++17 + Drogon HTTP 框架（源码编译），可执行 `wind_server` +- 前端：React 19 + Vite 8 + react-router 7（`frontend/web_app`） +- 第三方：Drogon/Trantor 源码（vendored）、nlohmann/json 头文件库 + +## 目录结构 +``` +wind_power_cal/ +├── third_party/ +│ ├── ensure_third_party.sh # Drogon 源码编译（幂等） +│ ├── drogon_repo/ # Drogon + Trantor 源码 +│ ├── nlohmann/ # header-only json +│ └── drogon/install// # 编译产物（gitignored） +├── backend/ # C++ Drogon 服务 +│ ├── CMakeLists.txt build.sh run.sh +│ ├── config/server_config.json +│ └── src/ main.cpp + controllers/ + utils/ResponseUtil.h +├── frontend/web_app/ # React + Vite +├── package.sh run.sh deploy.sh # 根级 构建/运行/部署 +└── CMakeLists.txt # 顶层（arch 检测 + add_subdirectory(backend)） +``` + +## 端口 +| 服务 | 端口 | +| --- | --- | +| 后端 wind_server | 8848（监听地址见 server_config.json） | +| 前端 dev | 5173（vite proxy `/api` → :8848） | + +## 脚本入口 +- `./run.sh` 一键打包+前台运行（后端托管 SPA） +- `bash backend/run.sh` 仅后端；`cd frontend/web_app && npm run dev` 仅前端 +- `./deploy.sh` 部署到远端（见 [[wind-deploy]]） +- `bash package.sh [--publish]` 打包到 `runtime/wind_power/` + +## 约定 +- 响应统一信封 `{"status":0,"msg":"success","data":{...}}`（见 [[wind-backend-conventions]]） +- MVP 阶段无数据库 / MQTT / 鉴权；结构就位，可参照 edge_collector 扩展 diff --git a/.claude/skills/wind-third-party-libs/SKILL.md b/.claude/skills/wind-third-party-libs/SKILL.md new file mode 100644 index 0000000..fec19a5 --- /dev/null +++ b/.claude/skills/wind-third-party-libs/SKILL.md @@ -0,0 +1,35 @@ +--- +name: wind-third-party-libs +description: wind_power_cal 第三方库管理规范。用于新增/引用/重新编译 third_party 下的 Drogon、nlohmann 等库时，按 ensure_third_party.sh 的源码编译与调用约定操作。 +--- + +# 第三方库管理 + +## 现有 +| 目录 | 说明 | 是否入库 | +| --- | --- | --- | +| `third_party/drogon_repo/` | Drogon + Trantor 源码（vendored，无 .git/build） | ✅ 入库 | +| `third_party/nlohmann/` | header-only json（`json.hpp` + `json_fwd.hpp`） | ✅ 入库 | +| `third_party/drogon/install//` | 源码编译产物 | ❌ gitignored | + +## 源码编译 Drogon +`third_party/ensure_third_party.sh`： +- 架构检测 `x64 / arm64 / arm32` +- cmake flags：`BUILD_SHARED_LIBS=ON USE_SUBMODULE=ON BUILD_CTL=OFF BUILD_EXAMPLES=OFF BUILD_ORM=OFF BUILD_TESTING=OFF BUILD_BROTLI=ON BUILD_YAML_CONFIG=OFF`，`CMAKE_INSTALL_LIBDIR=libs` +- 安装到 `third_party/drogon/install//`；产物存在（`libs/cmake/Drogon/DrogonConfig.cmake`）则跳过 + +## 调用约定（重要，踩过坑） +- **被 source 时**显式传 `THIRD_PARTY=/third_party`：调用方（如 `package.sh`）可能已预设 `SCRIPT_DIR`，会让本脚本 `${SCRIPT_DIR:-}` 推导到错误目录。 + ```bash + THIRD_PARTY="${ROOT_DIR}/third_party" source "${ROOT_DIR}/third_party/ensure_third_party.sh" + ``` +- 脚本内**软失败用 `return`，不要用 `exit`**（被 source 时 `exit` 会杀掉父 shell）。本仓库写法：`return 0 2>/dev/null || exit 0`。 +- 导出 `TARGET_ARCH` 与 `DROGON_INSTALL` 供后续 cmake / run.sh 使用。 + +## 引用方式 +- 后端 CMake：`find_package(Drogon CONFIG REQUIRED)`，由顶层 `DROGON_LOCAL_PREFIX` 注入查找路径。 +- json：`#include `（third_parent 在 include path）。 + +## 新增第三方库 +- header-only（如 nlohmann）：直接放 `third_party//`，CMake 加 include path。 +- 需编译：仿照 `ensure_third_party.sh` 的 Drogon 块，源码放 `third_party/_repo/`，编译安装到 `third_party//install//`，产物 gitignore。 diff --git a/frontend/web_app/src/App.css b/frontend/web_app/src/App.css index 921745f..c2d1710 100644 --- a/frontend/web_app/src/App.css +++ b/frontend/web_app/src/App.css @@ -12,6 +12,14 @@ margin-bottom: 22px; } +.headerActions { + display: flex; + align-items: center; + flex-wrap: wrap; + justify-content: flex-end; + gap: 10px; +} + .homeHeader h1 { color: #fff; font-size: 28px; @@ -65,7 +73,12 @@ display: none; } +.fileButton input { + display: none; +} + .uploadButton.disabled, +.fileButton.disabled, .primaryButton:disabled, .secondaryButton:disabled { cursor: not-allowed; @@ -105,6 +118,12 @@ font-weight: 620; } +.panelHint { + margin-top: 6px; + color: #8f96a3; + font-size: 13px; +} + .panelHeader span, .muted { color: #8f96a3; @@ -131,6 +150,95 @@ color: #c7d2fe; } +.designPowerPanel { + margin-bottom: 18px; +} + +.designActions { + display: flex; + align-items: center; + flex-wrap: wrap; + justify-content: flex-end; + gap: 10px; +} + +.designActions span { + color: #9ca3af; + font-size: 13px; + white-space: nowrap; +} + +.designMeta { + display: flex; + flex-wrap: wrap; + gap: 8px; + margin: -2px 0 12px; +} + +.designMeta span { + border: 1px solid #343449; + border-radius: 6px; + background: #1a1a27; + color: #cbd5e1; + padding: 5px 8px; + font-size: 12px; +} + +.designTableWrap { + max-height: 320px; + overflow: auto; + border: 1px solid #2a2a3a; + border-radius: 8px; +} + +.designTable th:nth-child(1), +.designTable th:nth-child(2), +.designTable td:nth-child(1), +.designTable td:nth-child(2) { + width: 42%; +} + +.designTable th:nth-child(3), +.designTable td:nth-child(3) { + width: 16%; + text-align: right; +} + +.tableInput { + width: 100%; + min-width: 0; + height: 34px; + border: 1px solid #343449; + border-radius: 7px; + background: #0f0f18; + color: #e5e7eb; + padding: 0 10px; + font-size: 13px; + font-variant-numeric: tabular-nums; +} + +.tableInput:focus { + border-color: #6366f1; + outline: none; +} + +.tableInput::placeholder { + color: #5f6673; +} + +.textButton { + border: 0; + background: transparent; + color: #93c5fd; + cursor: pointer; + font-size: 13px; + font-weight: 600; +} + +.textButton:hover { + color: #bfdbfe; +} + .emptyState, .emptyChart { display: flex; @@ -290,9 +398,14 @@ select:focus { width: 180px; } +.chartFrame { + position: relative; + min-height: 540px; +} + .uplotWrap { width: 100%; - min-height: 360px; + min-height: 540px; } .uplot { @@ -321,6 +434,56 @@ select:focus { padding: 2px 6px; } +.chartLegend { + position: absolute; + top: 20px; + left: clamp(88px, 6vw, 118px); + z-index: 2; + display: grid; + gap: 8px; + pointer-events: none; +} + +.chartLegend span { + display: inline-flex; + align-items: center; + gap: 8px; + color: #e5e7eb; + font-size: 13px; + text-shadow: 0 1px 2px rgba(0, 0, 0, 0.8); + white-space: nowrap; +} + +.legendDot, +.legendLine { + display: inline-block; + flex: 0 0 auto; +} + +.legendDot { + width: 5px; + height: 5px; + border-radius: 50%; +} + +.legendDot.scatter { + background: #fbbf24; +} + +.legendLine { + width: 32px; + height: 0; + border-top: 3px solid; +} + +.legendLine.actual { + border-color: #ef4444; +} + +.legendLine.design { + border-color: #22c55e; +} + .chartTools { display: flex; align-items: center; @@ -416,6 +579,10 @@ td { display: grid; } + .headerActions { + justify-content: flex-start; + } + .summaryGrid { grid-template-columns: repeat(2, minmax(0, 1fr)); } diff --git a/frontend/web_app/src/pages/HomePage.jsx b/frontend/web_app/src/pages/HomePage.jsx index c5a0bc3..0dfb49f 100644 --- a/frontend/web_app/src/pages/HomePage.jsx +++ b/frontend/web_app/src/pages/HomePage.jsx @@ -29,7 +29,27 @@ const FIELD_EXCLUDES = { active_power: ['限功率', '限电', '时间', '累计'], }; +const DESIGN_FIELDS = [ + { key: 'wind_speed', label: '风速' }, + { key: 'design_power', label: '设计功率' }, +]; + +const DESIGN_FIELD_HINTS = { + wind_speed: ['风速', 'wind speed', 'windspeed', 'm/s'], + design_power: ['设计功率', '理论功率', '标准功率', '功率', 'power', 'kw'], +}; + const CHUNK_SIZE = 4000; +const CHART_HEIGHT = 540; + +function createDesignRows(points) { + const source = points?.length ? points : [{ wind_speed: '', design_power: '' }]; + return source.map((point, index) => ({ + id: `${Date.now()}_${index}_${Math.random().toString(16).slice(2)}`, + wind_speed: point.wind_speed ?? '', + design_power: point.design_power ?? '', + })); +} function normalizeHeader(value) { return String(value ?? '') @@ -75,6 +95,41 @@ function inferMapping(headers) { return mapping; } +function inferDesignMapping(headers) { + const normalized = headers.map((header) => ({ + header, + normalized: normalizeHeader(header), + })); + const mapping = {}; + + for (const field of DESIGN_FIELDS) { + const hints = DESIGN_FIELD_HINTS[field.key].map(normalizeHeader); + let best = null; + for (const item of normalized) { + if (!item.normalized) { + continue; + } + let score = 0; + hints.forEach((hint, index) => { + const weight = hints.length - index; + if (item.normalized === hint) { + score = Math.max(score, 100 + weight); + } else if (item.normalized.includes(hint)) { + score = Math.max(score, 60 + weight); + } else if (hint.includes(item.normalized)) { + score = Math.max(score, 20 + weight); + } + }); + if (!best || score > best.score) { + best = { ...item, score }; + } + } + mapping[field.key] = best && best.score > 0 ? best.header : ''; + } + + return mapping; +} + function excelSerialToDate(value) { const days = Number(value); if (!Number.isFinite(days) || days <= 0) { @@ -168,6 +223,49 @@ async function readExcelFile(file) { }; } +async function readDesignPowerFile(file) { + const parsedFile = await readExcelFile(file); + const mapping = inferDesignMapping(parsedFile.headers); + const windSpeedIndex = parsedFile.headers.indexOf(mapping.wind_speed); + const designPowerIndex = parsedFile.headers.indexOf(mapping.design_power); + + if (windSpeedIndex < 0 || designPowerIndex < 0) { + throw new Error('设计功率文件未识别到风速列或设计功率列'); + } + + const grouped = new Map(); + for (const row of parsedFile.rows) { + const windSpeed = normalizeNumber(getCell(row, windSpeedIndex)); + const designPower = normalizeNumber(getCell(row, designPowerIndex)); + if (!Number.isFinite(windSpeed) || !Number.isFinite(designPower) || + windSpeed < 0 || designPower < 0) { + continue; + } + const key = windSpeed.toFixed(6); + const current = grouped.get(key) || { wind_speed: windSpeed, sum: 0, count: 0 }; + current.sum += designPower; + current.count += 1; + grouped.set(key, current); + } + + const points = Array.from(grouped.values()) + .map((item) => ({ + wind_speed: item.wind_speed, + design_power: item.sum / item.count, + })) + .sort((left, right) => left.wind_speed - right.wind_speed); + + if (!points.length) { + throw new Error('设计功率文件没有可用的风速-功率数据'); + } + + return { + file_name: parsedFile.file_name, + sheet_name: parsedFile.sheet_name, + points, + }; +} + function getCell(row, headerIndex) { if (headerIndex < 0) return ''; return row[headerIndex]; @@ -218,7 +316,13 @@ function SummaryCards({ summary }) { ); } -function PowerCurveChart({ points, scatterPoints, filteredPoints, showFiltered }) { +function PowerCurveChart({ + points, + scatterPoints, + filteredPoints, + showFiltered, + designPoints, +}) { const chartRef = useRef(null); const validPoints = useMemo( () => (points || []).filter((point) => point.sample_count > 0), @@ -234,13 +338,29 @@ function PowerCurveChart({ points, scatterPoints, filteredPoints, showFiltered } Number.isFinite(point.wind_speed) && Number.isFinite(point.active_power)), [filteredPoints], ); + const validDesign = useMemo( + () => (designPoints || []).filter((point) => + Number.isFinite(point.wind_speed) && Number.isFinite(point.design_power)), + [designPoints], + ); useEffect(() => { if (!chartRef.current || !validPoints.length) return undefined; const sortedCurve = [...validPoints].sort((left, right) => left.wind_speed - right.wind_speed); - const curveX = sortedCurve.map((point) => point.wind_speed); - const curveY = sortedCurve.map((point) => point.average_power); + const sortedDesign = [...validDesign].sort((left, right) => left.wind_speed - right.wind_speed); + const actualByWindSpeed = new Map( + sortedCurve.map((point) => [point.wind_speed.toFixed(6), point.average_power]), + ); + const designByWindSpeed = new Map( + sortedDesign.map((point) => [point.wind_speed.toFixed(6), point.design_power]), + ); + const curveX = Array.from(new Set([ + ...sortedCurve.map((point) => point.wind_speed), + ...sortedDesign.map((point) => point.wind_speed), + ])).sort((left, right) => left - right); + const actualY = curveX.map((windSpeed) => actualByWindSpeed.get(windSpeed.toFixed(6)) ?? null); + const designY = curveX.map((windSpeed) => designByWindSpeed.get(windSpeed.toFixed(6)) ?? null); const maxScatterPower = validScatter.reduce( (max, point) => Math.max(max, point.active_power), 0, @@ -248,14 +368,21 @@ function PowerCurveChart({ points, scatterPoints, filteredPoints, showFiltered } const maxFilteredPower = showFiltered ? validFiltered.reduce((max, point) => Math.max(max, point.active_power), 0) : 0; - const maxCurvePower = curveY.reduce((max, value) => Math.max(max, value), 0); - const maxPower = Math.max(maxCurvePower, maxScatterPower, maxFilteredPower, 1); + const maxCurvePower = sortedCurve.reduce( + (max, point) => Math.max(max, point.average_power), + 0, + ); + const maxDesignPower = sortedDesign.reduce( + (max, point) => Math.max(max, point.design_power), + 0, + ); + const maxPower = Math.max(maxCurvePower, maxDesignPower, maxScatterPower, maxFilteredPower, 1); const width = Math.max(chartRef.current.clientWidth || 760, 320); chartRef.current.innerHTML = ''; const chart = new uPlot({ width, - height: 360, + height: CHART_HEIGHT, cursor: { drag: { x: true, y: true }, }, @@ -278,14 +405,22 @@ function PowerCurveChart({ points, scatterPoints, filteredPoints, showFiltered } series: [ {}, { - label: '分箱平均功率', - stroke: '#60a5fa', - width: 2, - points: { show: true, size: 6, fill: '#93c5fd', stroke: '#0f172a' }, + label: '实际功率', + stroke: '#ef4444', + width: 2.5, + paths: uPlot.paths.spline(), + points: { show: false }, + }, + { + label: '设计功率', + stroke: '#22c55e', + width: 2.2, + paths: uPlot.paths.spline(), + points: { show: false }, }, ], hooks: { - draw: [ + drawAxes: [ (u) => { const { ctx } = u; ctx.save(); @@ -315,16 +450,25 @@ function PowerCurveChart({ points, scatterPoints, filteredPoints, showFiltered } }, ], }, - }, [curveX, curveY], chartRef.current); + }, [curveX, actualY, designY], chartRef.current); return () => chart.destroy(); - }, [validPoints, validScatter, validFiltered, showFiltered]); + }, [validPoints, validScatter, validFiltered, validDesign, showFiltered]); if (!validPoints.length) { return
暂无可绘制的曲线数据
; } - return
; + return ( +
+
+ 散点数据 + 实际功率 + {validDesign.length > 0 && 设计功率} +
+
+
+ ); } export default function HomePage() { @@ -337,6 +481,9 @@ export default function HomePage() { const [result, setResult] = useState(null); const [selectedFan, setSelectedFan] = useState(''); const [showFiltered, setShowFiltered] = useState(false); + const [readingDesign, setReadingDesign] = useState(false); + const [designRows, setDesignRows] = useState(() => createDesignRows()); + const [designMeta, setDesignMeta] = useState(null); const headers = files[0]?.headers || []; const missingFields = REQUIRED_FIELDS.filter((field) => !mapping[field.key]); @@ -356,6 +503,28 @@ export default function HomePage() { () => files.reduce((sum, file) => sum + file.row_count, 0), [files], ); + const designCurve = useMemo(() => { + const grouped = new Map(); + for (const row of designRows) { + const windSpeed = normalizeNumber(row.wind_speed); + const designPower = normalizeNumber(row.design_power); + if (!Number.isFinite(windSpeed) || !Number.isFinite(designPower) || + windSpeed < 0 || designPower < 0) { + continue; + } + const key = windSpeed.toFixed(6); + const current = grouped.get(key) || { wind_speed: windSpeed, sum: 0, count: 0 }; + current.sum += designPower; + current.count += 1; + grouped.set(key, current); + } + return Array.from(grouped.values()) + .map((item) => ({ + wind_speed: item.wind_speed, + design_power: item.sum / item.count, + })) + .sort((left, right) => left.wind_speed - right.wind_speed); + }, [designRows]); async function handleFilesChange(event) { const selectedFiles = Array.from(event.target.files || []); @@ -381,6 +550,56 @@ export default function HomePage() { } } + async function handleDesignFileChange(event) { + const [file] = Array.from(event.target.files || []); + if (!file) return; + + setReadingDesign(true); + setError(''); + try { + const design = await readDesignPowerFile(file); + setDesignRows(createDesignRows(design.points)); + setDesignMeta({ + file_name: design.file_name, + sheet_name: design.sheet_name, + point_count: design.points.length, + }); + } catch (err) { + setError(err.message || '读取设计功率失败'); + } finally { + setReadingDesign(false); + event.target.value = ''; + } + } + + function handleDesignRowChange(rowId, field, value) { + setDesignRows((prev) => prev.map((row) => ( + row.id === rowId ? { ...row, [field]: value } : row + ))); + setDesignMeta((prev) => prev ? { ...prev, edited: true } : { edited: true }); + } + + function handleAddDesignRow() { + setDesignRows((prev) => [ + ...prev, + ...createDesignRows([{ wind_speed: '', design_power: '' }]), + ]); + setDesignMeta((prev) => prev ? { ...prev, edited: true } : { edited: true }); + } + + function handleDeleteDesignRow(rowId) { + setDesignRows((prev) => { + const next = prev.filter((row) => row.id !== rowId); + return next.length ? next : createDesignRows(); + }); + setDesignMeta((prev) => prev ? { ...prev, edited: true } : { edited: true }); + } + + function handleClearDesignRows() { + setDesignRows(createDesignRows()); + setDesignMeta(null); + } + async function handleSubmit() { if (!files.length || missingFields.length) { setError('请先上传文件并完成所有字段映射'); @@ -455,21 +674,106 @@ export default function HomePage() {

风电功率计算平台

多 Excel 导入、字段映射、数据清洗与功率曲线计算

- +
+ +
{error &&
{error}
} {progress &&
{progress}
} +
+
+
+

设计功率曲线

+

可手动填写风速和设计功率，也可上传 Excel 自动加载后再修改。

+
+
+ {designCurve.length ? `${designCurve.length.toLocaleString()} 个有效点` : '未启用'} + + + +
+
+ {designMeta && ( +
+ {designMeta.file_name || '手动填写'} + {designMeta.sheet_name && {designMeta.sheet_name}} + {designMeta.point_count > 0 && 导入 {designMeta.point_count.toLocaleString()} 行} + {designMeta.edited && 已手动修改} +
+ )} +
+
+ + + + + + + + + {designRows.map((row) => ( + + + + + + ))} + +
风速 (m/s)设计功率 (kW)操作
+ handleDesignRowChange(row.id, 'wind_speed', event.target.value)} + /> + + handleDesignRowChange(row.id, 'design_power', event.target.value)} + /> + + +
+ + +
@@ -610,6 +914,7 @@ export default function HomePage() { scatterPoints={selectedScatter} filteredPoints={selectedFiltered} showFiltered={showFiltered} + designPoints={designCurve} />