feat: 完善嵌入式应用 PC 端调试技能

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: embedded-app-pc-debug
-description: 用于 Windows 电脑端的嵌入式应用调试，包括固件远程打包、设备发现与身份核对、ROM 升级、串口实时监测、升级后验证和故障诊断。适用于 Eapil/CamTells 工作流，也允许覆盖主机、项目、设备、串口和输出路径；普通代码开发或仅查看已有日志时不要自动触发。
+description: 用于 Windows 电脑端的嵌入式应用调试，包括远程编译、NFS 模块部署、开机进程与加密参数调试，以及设备发现、ROM 升级、串口监测和故障诊断。适用于 Eapil/CamTells 工作流；普通代码开发或仅查看已有日志时不要自动触发。
 ---
 
 # Windows电脑端调试
@@ -10,6 +10,7 @@ description: 用于 Windows 电脑端的嵌入式应用调试，包括固件远
 ## 按需读取
 
 - 涉及远程编译、工程定位、软链接、下载产物时，读取 [references/build-workflow.md](references/build-workflow.md)。
+- 涉及 NFS 模块部署、`DxMain`、开机启动脚本、工厂模式或加密 param 时，读取 [references/application-debugging.md](references/application-debugging.md)。
 - 涉及广播搜索、基础信息、EPFP 文件传输或升级时，读取 [references/device-protocols.md](references/device-protocols.md)。
 - 涉及串口监测、升级成功判据或故障定位时，读取 [references/validation-and-diagnostics.md](references/validation-and-diagnostics.md)。
 - 涉及 Linux 打包任务与 Windows 设备任务之间交接时，读取 [references/cross-host-coordination.md](references/cross-host-coordination.md)。
@@ -19,7 +20,7 @@ description: 用于 Windows 电脑端的嵌入式应用调试，包括固件远
 ## 默认环境
 
 - SSH 配置主机：`emb.eapil.com`
-- 远程项目根目录：`/CamTells`
+- 远程工程搜索根：优先现有工作区、`~/work/develop/gitcode` 和实际挂载点；`/CamTells` 仅是兼容候选
 - 默认 Public 来源：`~/work/develop/gitcode/EMX2.1`
 - 本地归档根目录：`F:\tmp\embedded-app-pc-debug`
 - 串口默认值：`115200`、`8N1`、无流控
@@ -29,7 +30,7 @@ description: 用于 Windows 电脑端的嵌入式应用调试，包括固件远
 ## 工作方式
 
 1. 根据用户请求确定需要执行的阶段；不强迫每次都完成整条链路。
-2. 自己调查文件、脚本参数、网卡和设备响应等可查事实，只向用户询问真正需要选择的事项。串口调试必须先取得本次用户确认的 COM 口；Telnet 调试必须先取得完整 SN 和型号。
+2. 自己调查文件、脚本参数、网卡和设备响应等可查事实，只向用户询问真正需要选择的事项。新设备调试开始前先枚举串口并让用户选择串口或 Telnet；即使只有一个 USB 串口也不自动打开。串口必须取得本次用户确认的 COM 口；Telnet 必须先取得完整 SN 和型号。
 3. 将每次完整任务归档到 `<根目录>\<项目>\<YYYYMMDD-HHmmss>`，分别保存 `firmware` 和 `logs`。
 4. 搜索可以按型号、IP 或唯一响应列出候选，但这些条件都不能替代完整 SN。Telnet、升级及其他设备写操作必须以用户给出的完整 SN 精确匹配目标，并核对型号；多个候选或同一 SN 出现冲突时停止，不能默认第一台。
 5. 先启动串口监测，再执行设备升级；串口输出同时实时显示并保存日志。需要在网页中查看日志或向设备输入命令时，使用单进程串口网页控制台，避免采集进程和发送进程争用同一个 COM 口。网页首次打开显示最新日志，所有发送内容都写入文本日志，空输入也必须发送真实 `CR`。刷新网页不能中断采集；多个页面共用服务时仅关闭最后一个页面才触发停止。最后页面关闭后，即使处于升级期间，也要在约 `5` 秒内结束采集、保留日志并释放 COM 口；之后必须重新启动控制台才能再次连接。
@@ -37,6 +38,8 @@ description: 用于 Windows 电脑端的嵌入式应用调试，包括固件远
 7. 只有用户在看到上述信息后明确确认升级，才能传输 ROM、烧录或触发重启。之前对搜索、编译或诊断的授权不能替代这次确认。
 8. 升级失败后先诊断并保留证据，不自动重试；再次升级需要新的明确确认。
 
+串口优先不等于自动选择。用户选择串口后，只有端口打不开、无数据、乱码或无法登录时才建议回退 Telnet；切换前告知用户，Telnet 连接前重新广播核对完整 SN、型号和当前 IP。网络异常但串口可用时可以在用户确认 COM 口后做只读检查；设备写入、停止进程、修改启动项或重启前还需确认该串口对应的目标 SN 和型号。固件升级不得绕过协议身份核验。
+
 用户如果只要求“显示串口”或“实时看日志”，仅打开只读串口监测；用户希望在页面持续查看时可以使用本地串口网页控制台，但不自动发送命令、搜索设备、登录、打包、传输文件或升级。
 
 ## Git 与构建边界
@@ -52,6 +55,7 @@ description: 用于 Windows 电脑端的嵌入式应用调试，包括固件远
 - `scripts/serial_monitor.ps1`：无第三方依赖的 Windows 串口实时输出、原始字节保存和带时间戳文本日志。
 - `scripts/serial_web_console.ps1`：使用 Windows PowerShell 5.1 启动本地串口网页控制台；由单个进程独占 COM 口并同时负责接收、记录和发送，页面仅监听 `127.0.0.1`，写操作和关闭通知使用随机会话令牌。网页只提供用户主动输入和发送，不启动 U-Boot 持续按键或自动切换 A/B 分区。最后网页关闭后服务退出，不部署常驻管理进程或自动重连。必须用 `powershell.exe` 启动，不要改用 `pwsh.exe`。
 - `scripts/v2_discover.py`：枚举适合广播的 Windows IPv4 网卡，从每个接口的本地 `8951` 向设备 `8941` 发送 V2 广播，并严格筛选完整 SN/型号。
+- `scripts/module_debug.py`：应用模块部署预检和受保护执行；支持已打开的串口网页控制台或 Telnet，默认只读预检。`DxMain` 在线替换会检查 `daemon.sh`，关键系统服务默认拒绝替换。
 
 运行脚本前先查看 `--help` 或 PowerShell 参数说明。不得绕过脚本的完整 SN、ROM 路径、日志目录和执行开关保护。
 

agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Windows电脑端调试"
-  short_description: "完成 Windows 电脑端设备发现、固件升级、串口监测与验证"
+  short_description: "完成嵌入式模块部署、启动调试、参数诊断与固件升级"
-  default_prompt: "使用 $embedded-app-pc-debug 在 Windows 电脑端锁定目标设备，并完成固件升级、串口监测和结果验证。"
+  default_prompt: "使用 $embedded-app-pc-debug 在 Windows 电脑端选择目标设备，完成应用或固件调试并验证结果。"
 policy:
   allow_implicit_invocation: true

references/application-debugging.md

@@ -0,0 +1,97 @@
+# 应用模块、启动流程与参数调试
+
+仅在任务涉及应用模块部署、NFS、`DxMain`、开机进程、工厂模式或 param 文件时读取本文件。所有主机、用户名、设备、路径和进程名都以当前任务实查为准，示例不能变成跨用户或跨型号默认值。
+
+## 连接与身份
+
+1. 新设备任务开始前枚举 Windows 串口，让用户选择串口或 Telnet；即使只有一个 USB 串口也不自动打开。串口默认 `115200 8N1`、无流控，但允许用户覆盖。
+2. 用户选择串口时复用 `serial_web_console.ps1` 的单进程收发服务。部署工具只能连接状态为 `isOpen=true` 且 COM 口与本次选择一致的网页控制台，不能再次直接打开串口。
+3. 串口打不开、无数据、乱码或无法登录时先报告事实，再建议 Telnet。不要静默切换；Telnet 前重新广播核对完整 SN、型号和当前 IP。
+4. 网络故障时，用户确认 COM 口后允许串口只读诊断。写文件、停止进程、修改启动脚本或重启前，还需用户确认这个 COM 口对应的完整 SN 和型号。固件升级始终需要协议身份核验。
+5. Telnet 登录名和密码从准确的当前工程 `product.json` 读取，并在可用时核对固件生成的 `/etc/passwd` 或 `/etc/shadow`。不要混用 Web、ONVIF、RTSP、Wi-Fi 或烧录平台密码；认证失败后停止，不连续猜测。
+
+## NFS 与存储
+
+NFS 服务器 IP 和用户名按用户或任务变化。当前任务尚未确认时询问；已经确认且仍可达时可以继续复用。常见形式仅用于帮助识别：
+
+```sh
+mount -t nfs <服务器IP>:/nfs/<用户名> /mnt/nfs -o nolock
+```
+
+挂载前确认服务器可达、导出路径正确、挂载点存在，并检查是否已有不同来源挂载。复制前记录源文件的绝对路径、大小、权限、`file` 结果和 SHA-256。
+
+只有 `/proc/mounts` 或 `findmnt` 明确显示为独立可写挂载时才把目录称为 SD 卡。存在 `/mnt/sdcard` 空目录不等于存在 SD 卡；真实 SD 卡可用时优先作为调试目录，否则选择具有足够空间的 eMMC 等可写分区。默认保留 NFS 挂载、调试文件、备份和日志，只有用户明确要求恢复或清理时才删除或卸载，并列出所有遗留文件。
+
+## 普通模块部署
+
+1. 确认源二进制与设备的 ELF 架构、ABI、动态加载器和动态库要求匹配。服务器本机 x86 编译成功不能作为设备可运行证据。
+2. 在目标文件同目录写入唯一临时文件，复制后校验 SHA-256 和权限，再用同文件系统内的原子重命名替换。覆盖现有文件前保存带时间戳的备份。
+3. 只停止任务明确指定的进程。部署后检查程序实际启动、观察期内没有立即退出或崩溃，并验证用户指定的功能或日志标记。普通一次性 demo 可以退出码 0 和预期输出为成功；常驻进程还需持续存活。
+4. `EmxCoreServer`、`EmxMediaServer`、`EmxModulesServer` 等可能触发设备强制重启的关键服务默认拒绝在线替换；必须由任务明确指定并单独确认。
+5. 使用 `scripts/module_debug.py` 时默认只预检。实际挂载、复制、停止或启动进程必须显式传入执行开关；脚本的开关不能替代用户授权。
+6. Telnet 模式会先调用同目录的 V2 搜索工具，从所有可用活动 IPv4 网卡重新广播（包含虚拟/VPN 网卡，排除回环和链路本地地址），完整 SN、型号和广播返回 IP 唯一匹配后才允许登录；已知 IP 的 30101 查询是第二道核验，不能替代广播。
+7. NFS 已挂载时必须与本次确认的服务器和导出路径完全一致。源程序必须通过 ELF 架构和解释器检查；设备缺少 `readelf` 时默认停止，只有人工看过有限检查结果后才可显式放行。
+8. 在线停止已有进程时必须提供从当前设备实查得到的失败恢复命令。脚本会在替换失败时尝试恢复原文件和原进程，并在设备 `/tmp/codex-module-<模块>-<动作>-<时间>.state` 记录事务阶段；出现命令超时、会话中断、掉电或 `ROLLBACK_FAILED` 时状态未知，禁止直接重试，必须重新核对设备身份后读取事务状态，检查进程、目标哈希和备份，不能宣称已自动恢复。
+
+## DxMain 与 daemon.sh
+
+不要在 `daemon.sh` 或其后台软件看门狗仍运行时停止 `DxMain`。守护逻辑可能重新启动 `DxMain`，关键服务丢失时还可能执行强制重启。
+
+在线替换顺序：
+
+1. 从当前设备脚本和进程表精确定位 `daemon.sh` 主进程及其后台 `SoftwareWatchdog` 子进程。
+2. 先发送 `TERM`，等待并检查；仍残留时记录 PID 后发送 `KILL`。父子守护进程全部消失前不能停止 `DxMain`。
+3. 对 `DxMain` 使用相同的 `TERM`、等待、必要时 `KILL` 顺序。发现设备重启、会话断开或守护/应用重新出现时立即停止部署并保留日志。
+4. 备份、原子部署并运行调试版本。调试结束后恢复原程序，重新启动正确参数的守护脚本，并确认 `DxMain` 与守护进程均恢复。
+
+使用部署脚本在线停止 `DxMain` 时，必须同时传入本次实查的 `daemon.sh` 绝对路径和完整恢复命令。脚本按绝对路径最多接受一个 daemon 匹配，并且最多接受一个 `SoftwareWatchdog`；看门狗必须以该 daemon 为父进程，父子关系不匹配或出现多个候选时都拒绝结束任何进程，先人工核对进程树。
+
+开机调试前读取当前设备的 `appinit.sh` 和 `allstart.sh`。部分工程会优先运行 `/root/configs/allstart.sh`、其次 `/mnt/emmc/allstart.sh`、最后固件默认脚本，也可能原生支持 `/mnt/emmc/DxMain`；这些都是按工程确认的实现，不是通用常量。两个启动覆盖文件同时存在时停止并报告遮蔽关系，不自行选择。
+
+## 开机进程与重启验证
+
+默认固件分区可能是只读 SquashFS。需要改变开机进程时，优先使用当前 `appinit.sh` 已支持的可写覆盖路径，并遵守：
+
+1. 记录默认脚本、现有覆盖文件、挂载属性、权限和 SHA-256。
+2. 修改现有覆盖文件前保存时间戳备份；从默认脚本创建覆盖时保留权限。
+3. 只修改目标启动项，新脚本先执行 `sh -n`，写入后校验 SHA-256。
+4. 如果两个候选覆盖文件会互相遮蔽，停止并让用户选择保留哪一个。
+5. 重启前串口必须已经打开并确实收到数据，同时给出可以通过串口执行的恢复命令。完成修改不等于取得重启授权；集中展示变更、备份和预期后等待明确的“确认重启”。
+6. 重启后通过串口观察完整启动过程，核对目标进程、守护进程、工厂程序、异常退出、panic、看门狗和循环重启；网络恢复后再使用协议或 Telnet 辅助验证。
+
+## 烧录状态与工厂模式
+
+未烧录设备可能自动进入产测流程；已烧录设备通常进入正常流程，只有强制工厂标志生效时才运行产测程序。具体判断可能使用 MAC/SN 文件、文件大小、加密烧录数据、环境变量或标志文件，必须从当前工程和设备的 `function.sh`、`appinit.sh`、`allstart.sh` 实查。
+
+不要把某个版本的文件名、大小阈值、返回码或产测程序写成所有设备的规则。检查到未定义变量、错误文件路径或判断反转时报告证据并给出补丁，不自动修改设备。只有用户明确要求进入或退出工厂模式时，才允许创建、修改或删除工厂标志、烧录信息或启动覆盖文件。
+
+## 加密 param 文件
+
+设备 param 所在分区可能可读写，但内容需要 `DevTools` 解密。先识别格式，不能根据 `.json` 后缀直接调用解密：
+
+- 文件以 `{` 或 `[` 开头且能解析为 JSON：已经是明文，直接读取。
+- 内容符合当前工程加密参数格式：使用当前固件匹配的 `DevTools`。
+- 格式未知：查找对应模块的专用工具和源码，不试错解密。
+
+部分实测版本的命令为：
+
+```text
+DevTools param dec <文件路径>
+DevTools param enc <文件路径>
+```
+
+命令必须从当前设备的帮助、二进制字符串或工程源码重新核实。不要只看退出码；某些版本对不支持的命令仍返回 0，输入格式错误时还可能段错误并把目标截断为空文件。
+
+只读检查默认流程：
+
+1. 记录原始加密文件的路径、权限、大小和 SHA-256。
+2. 复制到唯一的 `/tmp` 文件并用 `cmp` 确认副本一致。
+3. 只对副本执行解密。成功后验证文件非空且为合法 JSON，再读取内容。
+4. 原文件前后重新计算 SHA-256，必须一致。解密失败、段错误或产生空文件时立即停止，不用同一源文件连续重试。
+5. 明文副本默认保留到当前调试任务结束，随后删除并记录；用户明确要求保留时不删除。
+
+如果工具只能原地工作，解密读取后必须立即重新加密，并通过备份和哈希确认恢复；能使用 `/tmp` 副本时不要原地解密。
+
+修改 param 时全程操作临时副本：解密、只改指定字段、验证 JSON 和字段差异、重新加密，再复制一份加密结果解密复查。写回前展示设备身份、原路径、备份路径、字段差异和校验值，等待明确“确认写入”。确认后备份原始加密文件，在同目录写临时文件并原子替换，恢复权限、`sync`，再解密复查。失败时保留原文件，不继续服务重载或重启。
+
+同目录的 active、`.def` 和 `.bak` 文件作用不同。默认只操作任务明确的 active 文件；默认值与备份只用于比对，除非用户明确要求同步修改。参数写回、服务重载和整机重启是三个独立授权阶段。优先调查进程是否支持重新加载；必须重启时仍需单独确认。

references/build-workflow.md

@@ -7,7 +7,7 @@
 | 项目 | 默认值 |
 |---|---|
 | SSH Host | `emb.eapil.com` |
-| 工程根目录 | `/CamTells` |
+| 工程搜索根 | 当前远程工作区、`~/work/develop/gitcode`、实际挂载点；`/CamTells` 仅作兼容候选 |
 | Public 来源 | `~/work/develop/gitcode/EMX2.1` |
 | 本地归档根目录 | `F:\tmp\embedded-app-pc-debug` |
 
@@ -16,9 +16,10 @@
 ## 工程定位
 
 1. 先用现有 SSH/VS Code 配置解析 Host，不猜测用户名、端口或私钥路径。
-2. 将用户给出的项目名视为 `/CamTells` 下的相对路径并精确匹配。
+2. 优先使用用户给出的绝对路径。只给项目名时，从 VS Code 最近工作区、`~/work/develop/gitcode`、`/CamTells` 和实际挂载点按目录名精确搜索；搜索深度至少覆盖从用户目录起 12 层，并为每个根设置独立合理超时。
-3. 如果有多个候选，列出远程绝对路径等待选择；不要凭目录修改时间挑选。
+3. PowerShell 调用远端 Shell 时，避免让本地提前展开远端 `$HOME` 等变量。记录每个搜索根的退出码并明确区分：没有匹配、无权访问、路径未挂载、命令不存在和搜索超时。超时不等于项目不存在。
-4. 确认工程目录包含待用脚本，再确定真实命令行参数。
+4. 如果有多个候选，列出远程绝对路径等待选择；不要凭目录修改时间挑选。
+5. 确认工程目录包含待用脚本，再确定真实命令行参数。类似 `product/CamTells/EPM21C` 的深层产品目录不能因浅层 `find -maxdepth` 被排除。
 
 ## 构建顺序