99 lines
14 KiB
Markdown
99 lines
14 KiB
Markdown
---
|
||
name: embedded-app-pc-debug
|
||
description: 用于 Windows 电脑端的 Eapil 嵌入式产品与平台调试，包括远程编译、NFS 模块部署、智能编码调试、设备发现、ROM 升级、串口监测和故障诊断；普通代码开发或仅查看已有日志时不要自动触发。
|
||
---
|
||
|
||
# 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)。
|
||
- 涉及 USB Wi-Fi、驱动加载、`wlan0`、关联、DHCP、PC 多网卡或网络恢复时，也读取 [references/validation-and-diagnostics.md](references/validation-and-diagnostics.md)；需要运行中恢复网络服务时再读取 [references/application-debugging.md](references/application-debugging.md)。
|
||
- 涉及 Linux 打包任务与 Windows 设备任务之间交接时，读取 [references/cross-host-coordination.md](references/cross-host-coordination.md)。
|
||
- 涉及简道云“研发组 -> 固件发布”记录填写、预填或核对时，读取 [references/firmware-release.md](references/firmware-release.md)。
|
||
- 涉及晶视智能编码、AVBR 静态场景码率、`vencSmart.json` 调参或压降测试时，读取 [智能编码调试知识](references/smart-encoding-debugging.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 文件。
|
||
|
||
## 工作方式
|
||
|
||
1. 根据用户请求确定需要执行的阶段；不强迫每次都完成整条链路。
|
||
2. 自己调查文件、脚本参数、网卡和设备响应等可查事实，只向用户询问真正需要选择的事项。新设备调试开始前先枚举串口并让用户选择串口或 Telnet；用户已明确选择串口时只确认尚缺的 COM 口，即使只有一个 USB 串口也不自行挑选。同一调试任务、目标和参数未变时复用已确认的 COM 口，不反复询问；更换设备、端口或目标不明确时重新确认。Telnet 必须先取得完整 SN 和型号。
|
||
3. 将每次完整任务归档到 `<根目录>\<项目>\<YYYYMMDD-HHmmss>`，分别保存 `firmware` 和 `logs`。
|
||
4. 搜索可以按型号、IP 或唯一响应列出候选，但这些条件都不能替代完整 SN。Telnet、升级及其他设备写操作必须以用户给出的完整 SN 精确匹配目标，并核对型号；多个候选或同一 SN 出现冲突时停止，不能默认第一台。
|
||
5. 先启动串口监测，再执行设备升级；串口输出同时实时显示并保存日志。默认使用可见的单进程串口网页控制台，先检查已有服务，正常则在同一页面复用，避免重复开窗口或启动第二个串口进程。网页首次打开显示最新日志，所有发送内容都写入文本日志，空输入也必须发送真实 `CR`。刷新网页不能中断采集；多个页面共用服务时仅关闭最后一个页面才触发停止。最后页面关闭后，即使处于升级期间，也要在约 `5` 秒内结束采集、保留日志并释放 COM 口；之后必须重新启动控制台才能再次连接。
|
||
6. 在 ROM 传输前集中显示目标 SN、型号、IP、当前版本、ROM 绝对路径、大小、SHA-256、可解析的目标版本、串口状态和所有无法验证的项目。
|
||
7. 只有用户在看到上述信息后明确确认升级，才能传输 ROM、烧录或触发重启。之前对搜索、编译或诊断的授权不能替代这次确认。
|
||
8. 升级失败后先诊断并保留证据，不自动重试；再次升级需要新的明确确认。
|
||
|
||
串口优先不等于自动选择。页面异常或无输出时，先按串口参考文档做本地只读诊断，设备静默不等于串口故障；确认端口打不开、占用或参数可疑后停手请用户核对，不反复重连。串口问题无法解决时可以建议 Telnet，但不能自动切换；切换前取得用户同意，Telnet 连接前重新广播核对完整 SN、型号和当前 IP。网络异常但串口可用时可以在用户确认 COM 口后做只读检查；设备写入、停止进程、修改启动项或重启前还需确认该串口对应的目标 SN 和型号。固件升级不得绕过协议身份核验。
|
||
|
||
用户如果只要求“打开串口”“显示串口”或“实时看日志”，默认由助手打开可见网页并只读采集，不把执行启动指令转交用户，不自动发送命令、搜索设备、登录、打包、传输文件或升级。用户明确选择终端或其他串口工具时尊重其选择。打开、复用、持续连接检查与异常诊断详见 [串口参考文档](references/validation-and-diagnostics.md)。
|
||
|
||
网页日志必须支持拖选和 `Ctrl+C` 复制。选择期间只暂停日志区域绘制与自动滚动，不中断串口采集、日志保存或页面存活连接；取消选择后恢复刷新。选区保护与真实浏览器验收要求见串口参考文档。
|
||
|
||
### 串口登录与凭据获取
|
||
|
||
- 只有用户明确要求登录设备或执行需要登录的诊断时才登录；仅要求查看串口输出时保持只读。
|
||
- 需要登录且当前任务可访问对应项目工程时，优先从该工程的 `product.json` 查找登录名和密码配置。先确认项目路径/版本与目标设备型号、固件版本相符；若存在多个可能配置，不能按相似型号或历史记忆猜测。只读取与当前设备匹配的必要字段，并仅在当前会话中使用。
|
||
- 若无法访问对应项目仓库，或 `product.json` 中没有可与目标设备和固件版本匹配的配置，则暂停登录并向用户说明缺少的来源或匹配信息；不得尝试默认密码、相似机型密码或从截图/历史聊天复制密码。
|
||
- 串口登录必须按当前可见提示逐步进行：只在 `login:` 提示发送用户名；收到 `Password:` 后才发送密码；密码无回显时等待登录结果；只有看到已登录 shell 提示符后才发送诊断命令。不得把用户名、密码和命令连成一串发送，也不得在提示阶段不明时盲发命令。
|
||
- 登录失败一次后停止尝试，先核对当前提示阶段、键盘输入字符、设备型号/固件与配置来源。若无法由现有证据解释，不连续试密码，向用户报告并等待新的凭据或指示。
|
||
- 不将真实密码、密钥或 Token 写入本 skill、脚本、示例、摘要或交付表格。按当前调试约定，原始串口日志保留发送记录；在复制、上传或转发日志前，先提醒用户检查其中是否含有凭据，并遵循该目的地的授权要求。不得为了分享而覆盖或改写原始证据日志。
|
||
|
||
## 远程项目持续调试与日志/源码排查
|
||
|
||
- 对所有产品线和平台工程的问题，默认沿用当前已建立的 SSH PTY 会话和远程工程目录；执行新命令前先检查既有会话是否仍有效。会话有效时直接在原会话操作，不要重复登录或新开终端。持续调试、修改或构建任务尚未完成时，保持该 SSH 会话存活，不主动退出、关闭终端或切换到新会话；如果工具或网络限制导致会话可能超时，优先采用该会话支持的保活方式，并在等待期间避免发送会改变设备状态的命令。若连接因外部原因失效，再按配置主机重新连接，并明确告知会话已重建。
|
||
- 用户指定远程工程时，以该工程作为源码修改和构建的权威位置；本地仅保存必要的辅助工具、产物与证据，不另建源码副本作为实际修改入口。确需本地中转补丁时说明用途，应用到远端并核对差异后才能构建，不能把本地修改当作远端已生效。此规则适用于不同产品、芯片平台和项目目录结构，不以 CamTells 目录布局作为前提。
|
||
- 远程排查前先确认用户给出的项目路径、分支/工作区和目标文件。先读取 `git status --short` 识别用户或前序任务已有修改；只触碰本次授权范围内的文件，保留其他未提交修改，不自动清理、还原或覆盖。
|
||
- 用户要求“分析/排查”时先只读查日志和代码，不顺手修复。日志结论区分三类：日志直接事实、代码明确行为、尚未证实的推断；不要把同一时间出现的事件直接说成因果。
|
||
- 先核验日志文件的修改时间、日志内部日期和用户指定时间是否相符。再截取事件前后上下文并过滤高频周期日志，避免截断或周期噪声掩盖真正事件。若证据文件日期/时间段不符，指出缺少对应证据，并只做可由现有源码支持的有限判断。
|
||
- 代码改动遵守最小化原则，尊重原实现和调用顺序。先对照相邻代码，沿用类成员函数组织、命名、缩进、括号及格式化风格；已有逻辑按 `类名::函数名` 在类外实现时，不无故将同类职责分散为自由函数。新增代码说明职责、参数来源、关键分支及失败处理，不只逐行翻译语法。改动前后只检查目标文件 diff；不触碰其他现有修改。除非用户要求编译/验证，不擅自引入额外测试或部署；若未编译或设备验证，明确说明验证边界。
|
||
- 面向最终报告列出关键时间点、原始日志现象、对应代码路径、判断可信度、仍缺失的证据，以及是否修改/编译/部署。不要把“代码路径可能导致”包装成“日志已证实”。
|
||
|
||
## Git 与构建边界
|
||
|
||
- 不执行编译前 `git status` 检查，不因未提交修改阻止打包。
|
||
- 不自动提交、推送、暂存、还原或清理任何仓库修改。
|
||
- 默认执行 `EmxGitInfo` 并保存输出作为版本凭证；失败时记录原因。临时验证包可继续，正式发布是否继续由用户决定。
|
||
- 不使用旧 ROM 冒充本次产物。构建脚本若明确宣告 ROM 目标成功并验证了本次 ROM，之后仅辅助全量镜像步骤失败时，可以交付“仅供局域网升级的 ROM”，但不能声称完整发布包成功。
|
||
|
||
仅编译指定模块时，使用当前工程已确认的交叉工具链和模块构建目标，不强制走完整 ROM 打包流程，详见 [构建参考文档](references/build-workflow.md)。NFS 联调需保留用户配置，并核对实际运行文件、启动参数和依赖，详见 [应用调试参考文档](references/application-debugging.md)；编译成功不能代替设备运行及功能验收。
|
||
|
||
## 工具脚本
|
||
|
||
- `scripts/device_upgrade.py`：V2 `30101` 身份预检与 `EPFP/4001` 升级。缺少 `--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 口。仅看到服务进程或空白网页不算验证通过。
|
||
|
||
上述串口行为验收适用于服务或页面实现变更；仅修改技能文档时检查结构、引用及规则一致性，不为文档校验打断现有采集。报告区分代码检查、替身单测、真实串口协议测试和实际浏览器操作验收；未执行的项明确标注，不以自动化结果代替完整界面验收。
|