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,27 @@
+schema_version: 1
+module_path: python_server
+title: ESP32 调试控制台本地 Web 服务器与窗口外壳
+scope:
+    - esp32_server.py
+    - esp32_app.vbs
+    - esp32_web.vbs
+source_files: []
+depends_on: []
+related_to: []
+kk_module_id: e6df9393-2f7e-4478-8bd9-79e0f4f83b91
+kk_cards:
+    architecture_design:
+        id: f440bf26-cce8-4839-9f95-db46b9d180db
+        title: ESP32 调试控制台本地 Web 服务器与窗口外壳
+    coding_conventions:
+        id: e9f360b3-eb76-441e-9f4d-595c77cf8874
+        title: ESP32 调试控制台本地 Web 服务器与窗口外壳
+    overview:
+        id: 2871bc12-68a1-4218-ab17-febc24f79968
+        title: ESP32 调试控制台本地 Web 服务器与窗口外壳
+    tech_stack:
+        id: 6c6357bf-8885-499f-a9ab-ff7df848bde6
+        title: ESP32 调试控制台本地 Web 服务器与窗口外壳
+    unique_setup_and_commands:
+        id: e191608a-80b0-4a83-b47a-c14460f54b3a
+        title: ESP32 调试控制台本地 Web 服务器与窗口外壳
@@ -0,0 +1 @@
+Python `http.server` + `threading` 线程型 HTTP 服务器；pywebview (WebView2) 桌面容器；VBS (`CreateObject('WScript.Shell')`) 调用 `pythonw.exe`；Windows Job Object 管理 ecat_native.exe 生命周期；原生 C/SOEM 后端 `build_native/ecat_native.exe`。
@@ -0,0 +1,7 @@
+由单个 Python 进程构成，核心是 `http.server.ThreadingHTTPServer` + `SimpleHTTPRequestHandler` 派生类：
+- 路由层：根路径 302 到 `/tabs.html`，`/pages/*`、`/css/*`、`/js/*` 等走内置目录静态映射；`/ws/app-lease` 实现基于全局计数器的 app 窗口租约协议（全部断开自动停止 EtherCAT PDO 循环并从站退回 INIT）；`POST /api/shutdown` 终止本服务。
+- EtherCAT 反向代理：`/ecat/api/<路径>` 通过 TCP 转发到 `tools/ecat/build_native/ecat_native.exe` 的 8090–8095 端口，首次命中时按进程 ID 复用已有实例，否则以 `--parent-pid` 拉起子进程并由 Job Object 连带回收。
+- 单实例互斥：通过命名互斥量 + `/api/focus` HTTP 唤醒旧实例，避免双击重复弹出。
+- 前端注入：响应 HTML 时在 `</body>` 前注入 `_RELOAD_SNIPPET`，为 pywebview 提供刷新按钮、F5/Ctrl+R 键盘拦截和返回主页行为。
+- 启动外壳：`esp32_app.vbs` 使用 `pythonw.exe --window` 启动 pywebview 桌面窗口（无控制台），`esp32_web.vbs` 用相同入口但以隐藏方式启动并交由系统默认浏览器打开。
+依赖方向单向向下：VBScript → Python HTTP 服务 → 可选拉起的 ecat_native.exe；所有业务 API 实际由 ESP32 设备 (80 端口) 提供，本服务不直接读写硬件。
@@ -0,0 +1 @@
+提供 ESP32 调试 Web UI 的静态文件服务、EtherCAT 后端反向代理与 app 窗口租约管理，并通过 VBScript 启动 pywebview 桌面窗口或浏览器标签。
@@ -0,0 +1 @@
+两个 VBS 入口：双击 `esp32_app.vbs` 启动带地址栏的 pywebview 桌面窗口（`--window`），双击 `esp32_web.vbs` 以隐藏窗口模式在默认浏览器中打开；Windows 环境变量 `PYTHONUTF8=1` 由 VBS 预先设置。EtherCAT 模式会按需自动检测并拉起 `tools/ecat/build_native/ecat_native.exe`（端口 8090–8095 探测）。
@@ -0,0 +1,5 @@
+- 所有对外暴露能力集中在单一 Python 主进程内：路由处理、WebSocket 租约状态、子进程管理均以模块级全局变量（如 `g_mutex`、`g_httpd`、`g_ecat_child`、`g_win`）共享，不使用类实例或配置对象。
+- 子进程生命周期统一通过 Windows Job Object + `--parent-pid` 参数管理，确保父进程退出后子进程被内核连带回收。
+- 对外部资源访问（旧实例焦点、ECAT 端口探测、子进程启动）一律包裹 `try/except` 并用模块级锁串行化，避免因并发导致多实例或多线程竞争。
+- 响应内容增强采用注入模式：将 JS/CSS 片段作为常量字符串定义并在发送 HTML 前通过 `<meta>` 或 `</body>` 标记插入，而非生成独立中间页。
+- 跨组件通信约定保持一致：VBScript 通过 `pythonw.exe <脚本> [--window]` 命令行开关切换模式，HTTP 端点统一使用 JSON body + `application/json` content-type。
				`@@ -0,0 +1 @@`
				Python `http.server` + `threading` 线程型 HTTP 服务器；pywebview (WebView2) 桌面容器；VBS (`CreateObject('WScript.Shell')`) 调用 `pythonw.exe`；Windows Job Object 管理 ecat_native.exe 生命周期；原生 C/SOEM 后端 `build_native/ecat_native.exe`。
				`@@ -0,0 +1 @@`
				`提供 ESP32 调试 Web UI 的静态文件服务、EtherCAT 后端反向代理与 app 窗口租约管理，并通过 VBScript 启动 pywebview 桌面窗口或浏览器标签。`
				`@@ -0,0 +1 @@`
				两个 VBS 入口：双击 `esp32_app.vbs` 启动带地址栏的 pywebview 桌面窗口（`--window`），双击 `esp32_web.vbs` 以隐藏窗口模式在默认浏览器中打开；Windows 环境变量 `PYTHONUTF8=1` 由 VBS 预先设置。EtherCAT 模式会按需自动检测并拉起 `tools/ecat/build_native/ecat_native.exe`（端口 8090–8095 探测）。