## 一、使用的依赖管理体系
本仓库**没有传统的包管理器**：根目录与所有子目录下不存在 `package.json`、`go.mod`、`requirements.txt`、`Pipfile*`、`*.lock`、`.npmrc` 等任何依赖声明文件；前端侧使用浏览器原生 ES module（`type="module"`）通过相对路径直接引用 `../css/*`、`../js/common/*`，不经过 npm/yarn/pnpm 解析。

Python 后端 (`esp32_server.py`) 仅依赖 Python **标准库**（`http.server.SimpleHTTPRequestHandler` / `ThreadingHTTPServer`、`socket`、`subprocess`、`ctypes`、`urllib.request`、`threading`、`hashlib` 等），以及一个可选的桌面外壳依赖 `pywebview`。该可选依赖在运行时探测缺失时回退到普通浏览器模式：`print("pywebview 未安装: pip install pywebview —— 回退浏览器模式")`，并通过 `serve.bat` / `esp32_web.vbs` 走无 GUI 路径。

非 Python 二进制依赖以独立可执行形式存在：EtherCAT 后端为编译后的单文件 `build_native/ecat_native.exe`（由外部脚本 `build_native.bat` 构建），由主服务按需在 8090–8095 端口范围内发现并启动（带 `--parent-pid` 实现父进程退出时自我结束），不属于当前仓库的包依赖图。

## 二、关键文件
- `esp32_server.py`：唯一 Python 入口；通过 `import http.server`、`ctypes`、`subprocess` 等标准库提供服务、反向代理、窗口管理与 ecat 子进程编排。
- `README.md`：文档化的启动方式（`esp32_app.vbs` / `esp32_web.vbs` / `serve.bat`），明确了 pywebview 可选性以及 ecat_native 的外部依赖关系。
- `scripts/build_mem.bat`：调用 ESP-IDF 构建 DCU/ESP32_COMM 固件的辅助脚本，不引入 Python/JS 依赖。
- `js/`、`pages/`、`css/`：纯前端资源，无任何 `<script src="node_modules/...">`，全部以相对 URL 引用。

## 三、架构与约定
1. **零打包策略**：`esp32_server.py` 直接 serve 静态 HTML/CSS/JS，页面内用 `<script type="module" src="../js/app.js">` 等加载，依赖解决完全由浏览器原生 ES module 完成。
2. **可选桌面外壳**：pywebview 作为可选依赖——有则用 `pythonw` + pywebview 开 WebView2 桌面窗口（无控制台窗体）；缺则回退到系统默认浏览器标签页模式，由 `serve.bat` / `esp32_web.vbs` 启动。
3. **外置二进制子进程模式**：EtherCAT 能力不在 Python 进程中提供，而是通过子进程协议拉取 `tools/ecat/build_native/ecat_native.exe`，服务端做 `/ecat/api/*` 同源转发来绕过其无 CORS + 127.0.0.1 绑定问题。该二进制由另一个 Git 仓库产出，当前仓库只负责发现与生命周期管理。
4. **单实例互斥**：通过本地 API `/api/focus` 把新双击重定向到已有实例前台窗口，避免并发拉起多个服务端实例。

## 四、约定与约束
- **前端资源版本化**：修改 CSS/JS 后必须 bump 引用的 `?v=` 缓存参数（否则浏览器加载旧代码），这是 README 中明确记录的强制约定。
- **JS 模块内部引用须用 `import.meta.url`**：不能写文档相对路径（如 Worker 文件），页面层级变化会 404（见 `js/motor/main.js` 的 `TICK_WORKER_URL`）。
- **新增功能页必须在 `tabs.html` 的 `TABS` 数组登记**，实验性/一次性页面放 `lab/` 并保持自包含。
- **设备地址配置保存在 `localStorage.dcu_esp_ip`**（默认 `192.168.31.127`，见 `js/common/base-url.js`），本服务不持有设备 IP，业务 API 全部直连 ESP32 固件 80 端口。
- **Python 侧不得随意引入三方库**：当前仅依赖标准库与可选 `pywebview`；若需增加第三方包，应评估是否仍走“纯标准库 + 可选 GUI”的路径，因为仓库中没有 `requirements.txt` 或 `pip freeze` 产物，依赖变更无法通过 CI 锁定复现。
- **ECAT 子进程必须带 `--parent-pid`**：否则它会清理同端口段其他实例，且主服务退出后会留下孤儿进程占用 Npcap 适配器与端口（见注释阶段 4 迁移说明）。