docs: 新增 .qoder Repowiki 知识库文档

2026-09-07 12:19:26 +08:00
parent 43d42ad891
commit ef9472334a
105 changed files with 1313322 additions and 263 deletions
@@ -0,0 +1,28 @@
+schema_version: 1
+module_path: scripts_and_tests
+title: ECAT 调试、固件刷写与端到端测试脚本集
+scope:
+    - scripts/
+source_files: []
+depends_on: []
+related_to:
+    - path: python_server
+      reason: 脚本 test_app_lease_e2e.mjs 等连接本地页面服务器的 /ws/app-lease 端点做端到端断言（端口探测与 POST 触发）。
+kk_module_id: adba262f-05b7-4a9b-ba4f-3edc007d80fb
+kk_ordinal: 3
+kk_cards:
+    architecture_design:
+        id: 51246f25-7864-40cd-812b-3af7b95b1e02
+        title: ECAT 调试、固件刷写与端到端测试脚本集
+    coding_conventions:
+        id: 86785324-6a18-4cc3-8952-47c808437f14
+        title: ECAT 调试、固件刷写与端到端测试脚本集
+    overview:
+        id: 13d0dd8e-2f0f-4d11-89de-5f07971aed07
+        title: ECAT 调试、固件刷写与端到端测试脚本集
+    tech_stack:
+        id: 70c89e3a-602b-425b-8570-86d077473604
+        title: ECAT 调试、固件刷写与端到端测试脚本集
+    unique_setup_and_commands:
+        id: f9104fb6-b2a4-4696-9135-8ed0b2ead005
+        title: ECAT 调试、固件刷写与端到端测试脚本集
@@ -0,0 +1 @@
+纯 Python + Node.js + PowerShell + Batch；通过 urllib/socket/raw HTTP 轮询 ESP32 服务的 `/ota/*`、`/api/motor/state`、`/motor/state?bin=1` 以及 WebSocket 接口；ECAT 撕裂检测采用“同 seq 多份 payload”不变量 + 字段跳变 p99 尺度的双判据。
@@ -0,0 +1,5 @@
+本模块为独立的辅助脚本集，按功能分为四层：
+- 固件与设备操作层：`flash_gd32.py` 通过 HTTP 把 Intel HEX 展平 BIN 并经由 ESP32 OTA 中继写入 GD32，轮询 `/system/status` 确认 `GD32_COMPLETE` 后写台账 `_last_gd32_sha.txt`；`build_mem.bat` / `cpu_sample.ps1` / `wv2_roles.ps1` 分别负责 IDF 构建与 Windows 进程采样。
+- ECAT 数据采集与诊断层：`rec_ecat_slots.py` 以固定频率轮询服务 `/api/motor/state`，去重落盘到 CSV（M/F/H 三类行），作为后续分析的唯一输入；`probe_ecat_slot_atomicity.py` 在此基础上做同一 seq 重复读的撕裂判定；`probe_ecat_vs_wifi.py` 将 ECAT 帧与 WiFi 二进制 `/motor/state?bin=1` 对照，逐字节验证一致性；`anal_ecat_jumps.py` 基于 p99 尺度+孤立尖峰形态检测撕裂，并提供 `--selftest` 注入混合帧的灵敏度自检。
+- 服务端行为验证层：`test_app_lease.py` 通过 `sys.path.insert` 直接 import `esp32_server`，用假 `_ecat_post/_ecat_find_port` 启动真实 HTTP 服务，模拟 WS 租约建立/Grace 重连/进程退出等场景断言 EtherCAT 循环启停；Python 版的浏览器 E2E 用例由对应 `.mjs` 借助 CDP (`ws://127.0.0.1:9333`) 操控 WebView 页面执行断言。
+- 依赖方向单向向外：所有脚本只读本地文件与服务 HTTP API，不反向修改业务代码；采集与分析脚本之间通过固定 CSV 格式（`ecat_slots_raw.csv`）解耦。
@@ -0,0 +1 @@
+面向 DCU/ESP32 平台的运行期工具与测试集合：含 GD32 固件刷写、ECAT 撕裂检测与分析、内存批化仿真、浏览器 E2E 用例及 Windows 性能采样。
@@ -0,0 +1,5 @@
+- 刷写 GD32：`python scripts/flash_gd32.py [期望版本]`，需先 `idf.py build` 产出 `DCU_APP/out/GD32E508_DCU_APP/GD32E508VE/Release/GD32E508_DCU_APP.hex`，并通过 `DCU_ESP_IP` 环境变量指定目标 IP
+- ECAT 撕裂检测：先跑 `python scripts/rec_ecat_slots.py [秒数] [端口] [输出csv]` 生成原始流，再 `python scripts/probe_ecat_slot_atomicity.py [端口] [秒数]` 或 `python scripts/anal_ecat_jumps.py ecat_slots_raw.csv [--k 8] [--selftest]`
+- ECAT vs WiFi 对比：`python scripts/probe_ecat_vs_wifi.py [秒数]`，要求本机同时提供 ECAT 状态 JSON 与 ESP32 WiFi 二进制接口
+- 浏览器 E2E：先起 `node --inspect-brk` + Chrome DevTools，再以 CDP 端口 9333 连接后执行各 `browser_check_*.mjs`；`test_app_lease.py` 可直接 `python scripts/test_app_lease.py`
+- Windows 性能：`scripts/cpu_sample.ps1` 统计 `msedgewebview2|ecat_native|pythonw|python` 进程 CPU/WorkingSet
@@ -0,0 +1,6 @@
+- 脚本入口统一为 `if __name__ == "__main__": main()` 模式，命令行参数通过 `sys.argv` 顺序解析（支持可选的端口、时长等）。
+- HTTP 客户端封装为顶层函数（如 `post/get` 或 `once()`），统一处理超时、`HTTPError` 与 UTF-8 解码替换，避免重复样板码。
+- ECAT 数据采集类脚本使用 TCP socket 直接拼接 HTTP 请求头并发出 POST，收到空字节流后再 `partition(b"\r\n\r\n")` 解析 JSON 体。
+- 长耗时运行通过 `while time.time() - t0 < DUR_S` 形式的时间窗口控制退出，错误路径一律 `except Exception: continue` 容错而非中断。
+- 大量去重/缓存场景采用 dict/set 并配合定期截断（如 `len(seen_m) > 400000` 时取尾部 200000 项），控制内存增长上限。
+- 断言式测试使用 `assert ... raise AssertionError(...)` 配合 PASS/INFO 日志串联用例，失败即非零退出码，便于 CI 集成。
				`@@ -0,0 +1 @@`
				纯 Python + Node.js + PowerShell + Batch；通过 urllib/socket/raw HTTP 轮询 ESP32 服务的 `/ota/*`、`/api/motor/state`、`/motor/state?bin=1` 以及 WebSocket 接口；ECAT 撕裂检测采用“同 seq 多份 payload”不变量 + 字段跳变 p99 尺度的双判据。
				`@@ -0,0 +1 @@`
				`面向 DCU/ESP32 平台的运行期工具与测试集合：含 GD32 固件刷写、ECAT 撕裂检测与分析、内存批化仿真、浏览器 E2E 用例及 Windows 性能采样。`