9.8 KiB
name, description
| name | description |
|---|---|
| embedded-app-pc-debug | 用于 Windows 电脑端的嵌入式应用调试，包括远程编译、NFS 模块部署、开机进程与加密参数调试，以及设备发现、ROM 升级、串口监测和故障诊断。适用于 Eapil/CamTells 工作流；普通代码开发或仅查看已有日志时不要自动触发。 |
Windows电脑端调试
完成从远程工程构建到设备升级验证的闭环，并保留足够证据判断失败发生在哪个阶段。
按需读取
- 涉及远程编译、工程定位、软链接、下载产物时，读取 references/build-workflow.md。
- 涉及 NFS 模块部署、
DxMain、开机启动脚本、工厂模式或加密 param 时，读取 references/application-debugging.md。 - 涉及 V1/V2 广播搜索、工厂/产测命令、统一配置、EPFP 文件传输、音视频协议或升级时，读取 references/device-protocols.md。
- 涉及串口监测、升级成功判据或故障定位时，读取 references/validation-and-diagnostics.md。
- 涉及 Linux 打包任务与 Windows 设备任务之间交接时，读取 references/cross-host-coordination.md。
只读取当前任务需要的参考文件。不要因为用户仅要求串口查看而加载远程打包流程。
默认环境
- SSH 配置主机：
emb.eapil.com - 远程工程搜索根：优先现有工作区、
~/work/develop/gitcode和实际挂载点；/CamTells仅是兼容候选 - 默认 Public 来源：
~/work/develop/gitcode/EMX2.1 - 本地归档根目录：
F:\tmp\embedded-app-pc-debug - 串口默认值：
115200、8N1、无流控
这些都是可覆盖的默认值。不要硬编码项目、SN、IP、COM 口或 ROM 文件。
工作方式
- 根据用户请求确定需要执行的阶段；不强迫每次都完成整条链路。
- 自己调查文件、脚本参数、网卡和设备响应等可查事实，只向用户询问真正需要选择的事项。新设备调试开始前先枚举串口并让用户选择串口或 Telnet；即使只有一个 USB 串口也不自动打开。串口必须取得本次用户确认的 COM 口；Telnet 必须先取得完整 SN 和型号。
- 将每次完整任务归档到
<根目录>\<项目>\<YYYYMMDD-HHmmss>，分别保存firmware和logs。 - 搜索可以按型号、IP 或唯一响应列出候选，但这些条件都不能替代完整 SN。Telnet、升级及其他设备写操作必须以用户给出的完整 SN 精确匹配目标，并核对型号；多个候选或同一 SN 出现冲突时停止，不能默认第一台。
- 先启动串口监测，再执行设备升级；串口输出同时实时显示并保存日志。需要在网页中查看日志或向设备输入命令时，使用单进程串口网页控制台，避免采集进程和发送进程争用同一个 COM 口。网页首次打开显示最新日志，所有发送内容都写入文本日志，空输入也必须发送真实
CR。刷新网页不能中断采集；多个页面共用服务时仅关闭最后一个页面才触发停止。最后页面关闭后，即使处于升级期间，也要在约5秒内结束采集、保留日志并释放 COM 口；之后必须重新启动控制台才能再次连接。 - 在 ROM 传输前集中显示目标 SN、型号、IP、当前版本、ROM 绝对路径、大小、SHA-256、可解析的目标版本、串口状态和所有无法验证的项目。
- 只有用户在看到上述信息后明确确认升级，才能传输 ROM、烧录或触发重启。之前对搜索、编译或诊断的授权不能替代这次确认。
- 升级失败后先诊断并保留证据，不自动重试；再次升级需要新的明确确认。
串口优先不等于自动选择。用户选择串口后，只有端口打不开、无数据、乱码或无法登录时才建议回退 Telnet；切换前告知用户，Telnet 连接前重新广播核对完整 SN、型号和当前 IP。网络异常但串口可用时可以在用户确认 COM 口后做只读检查；设备写入、停止进程、修改启动项或重启前还需确认该串口对应的目标 SN 和型号。固件升级不得绕过协议身份核验。
用户如果只要求“显示串口”或“实时看日志”，仅打开只读串口监测；用户希望在页面持续查看时可以使用本地串口网页控制台，但不自动发送命令、搜索设备、登录、打包、传输文件或升级。
串口登录与凭据获取
- 只有用户明确要求登录设备或执行需要登录的诊断时才登录；仅要求查看串口输出时保持只读。
- 需要登录且当前任务可访问对应项目工程时，优先从该工程的
product.json查找登录名和密码配置。先确认项目路径/版本与目标设备型号、固件版本相符；若存在多个可能配置，不能按相似型号或历史记忆猜测。只读取与当前设备匹配的必要字段，并仅在当前会话中使用。 - 若无法访问对应项目仓库，或
product.json中没有可与目标设备和固件版本匹配的配置，则暂停登录并向用户说明缺少的来源或匹配信息；不得尝试默认密码、相似机型密码或从截图/历史聊天复制密码。 - 串口登录必须按当前可见提示逐步进行：只在
login:提示发送用户名；收到Password:后才发送密码；密码无回显时等待登录结果；只有看到已登录 shell 提示符后才发送诊断命令。不得把用户名、密码和命令连成一串发送，也不得在提示阶段不明时盲发命令。 - 登录失败一次后停止尝试，先核对当前提示阶段、键盘输入字符、设备型号/固件与配置来源。若无法由现有证据解释，不连续试密码，向用户报告并等待新的凭据或指示。
- 不将真实密码、密钥或 Token 写入本 skill、脚本、示例、摘要或交付表格。按当前调试约定，原始串口日志保留发送记录；在复制、上传或转发日志前，先提醒用户检查其中是否含有凭据，并遵循该目的地的授权要求。不得为了分享而覆盖或改写原始证据日志。
Git 与构建边界
- 不执行编译前
git status检查，不因未提交修改阻止打包。 - 不自动提交、推送、暂存、还原或清理任何仓库修改。
- 默认执行
EmxGitInfo并保存输出作为版本凭证；失败时记录原因。临时验证包可继续，正式发布是否继续由用户决定。 - 不使用旧 ROM 冒充本次产物。构建脚本若明确宣告 ROM 目标成功并验证了本次 ROM，之后仅辅助全量镜像步骤失败时，可以交付“仅供局域网升级的 ROM”，但不能声称完整发布包成功。
工具脚本
scripts/v1_discover.py：V1 UDP4942搜索（0x5A0EFF00/01）；可用--interface指定本机 IPv4。端口冲突时停止，不抢占进程。scripts/v1_command.py：V1 TCP4941通用 CMD/Data 请求器；默认仅预检，所有命令只有显式--execute才发送。它不解析每条命令的业务语义，副作用命令必须先查对应协议并核对设备身份。scripts/device_upgrade.py：默认使用 V230101身份预检；可用--protocol v1通过 V10x5A0E2104核验后执行 EPFP/4001。V1 与 EPFP 的兼容性须由目标固件资料确认。缺少--execute时绝不连接升级端口或发送 ROM。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 路径、日志目录和执行开关保护。
调试数据
这是设备调试 skill。用户已选择让终端和任务日志保留原始调试信息，不对 30102、串口或构建输出中的密码、密钥、Token 做自动脱敏；但不得把某台设备的真实凭据写入本 skill、脚本默认值或参考文档。
完成条件
不要把连接建立、ROM 发送结束、下载进度达到 100% 或 Flash 计数达到总量单独称为升级成功。至少需要明确的协议成功终态，并继续核对同一 SN 的重启、重发现、网络恢复和目标版本；无法取得某项证据时明确说明，不补造结论。
串口网页控制台发生变更时，还要验证服务代码能编译、Skill 结构有效、COM 口由单一进程占用、服务实际连接、接收字节或日志文件持续增长、普通发送与空回车都有 TX 记录，并确认页面首次打开定位到最新日志。还必须完成生命周期验收：刷新不中断、两个页面关闭一个仍运行、关闭最后页面后约 5 秒内进程退出且状态接口离线、日志具有结束标记、原日志与原始字节文件仍在原路径，并且下一次服务能重新打开同一 COM 口。仅看到服务进程或空白网页不算验证通过。