embedded-app-pc-debug/references/validation-and-diagnostics.md

串口监测、验证与故障诊断

仅在任务涉及串口、设备重启或升级结果判断时读取本文件。

串口准备

1. 每次串口任务先请用户确认当前 COM 口；可以枚举 Windows 串口及描述帮助确认，但不要沿用上一次的端口或自行挑选。
2. 默认 115200、8 数据位、1 停止位、无校验、无流控，允许覆盖。
3. 打开失败、打开后没有输出、乱码或访问拒绝时立即停手，请用户核对 COM 口、波特率/校验/数据位/停止位/流控、端口是否已释放，必要时重新插拔或更换转接器。不要强制结束 SecureCRT、串口工具或其他进程。
4. 只读采集使用 scripts/serial_monitor.ps1；需要网页实时显示或网页命令输入时，使用 scripts/serial_web_console.ps1。确认 COM 口已打开并开始记录后，才传输 ROM。
5. 串口网页控制台必须由同一个进程独占 COM 口并完成收、发和日志写入，不能再启动第二个采集或发送进程。服务只绑定 127.0.0.1，同时写本任务自己的文本日志和原始字节文件。调试信息不脱敏。
6. 不主动读取、复制或上传 SecureCRT 的历史日志。只有本 skill 在本次任务生成的文本和原始字节日志可以默认使用；其他工具日志需用户明确授权。

只读串口脚本只负责监测。网页控制台允许用户直接输入命令，页面按 Enter 后固定追加 CR 并立即发送，不做危险命令二次确认。命令框为空时也发送 CR，表现为真实回车。服务接口仍支持无结尾、CR、LF、CRLF，供明确的自动化流程调用。AI 仍只能在用户明确要求或确认具体命令后代为发送，不得自行发送登录名、密码、Shell 命令、break、DTR 或 RTS 脉冲。所有写入数据都在文本日志中记录为 [TX:来源]，不可见字符显示为 <CR>、<LF> 等；RX 文本日志和原始字节日志保持不变。

网页输入区保持在日志下方，只保留快捷填入、命令框和发送按钮，不显示行尾选择、独立空回车、历史下拉、清空、密码开关、U-Boot 连续发送按钮及交互状态栏。页面首次打开时默认定位到最新日志；启用自动滚动后持续跟随最新输出，用户手动向上查看旧日志时不抢回位置，再次勾选自动滚动立即回到底部。Enter 发送、Shift+Enter 输入多行、上下方向键浏览当前页面的隐式历史、Esc 清空输入；处理中文输入法组合状态，确认候选时不能误发串口命令，并阻止长按 Enter 连续发送空回车。发送请求未完成时阻止重复提交，成功后立即刷新 TX 日志并保持输入焦点。页面识别 Password: 阶段并自动遮挡输入，而且密码不加入页面命令历史。按用户要求，实际发送内容仍会写入 TX 文本日志。

每个网页标签维护独立客户端心跳。最后一个页面正常发送关闭通知后等待约 2 秒，若没有刷新后的新页面接管，则服务自动结束日志采集、写入结束标记并释放 COM 口；多个标签同时打开时，关闭其中一个不能停止其他页面。页面异常退出或内置浏览器不触发离页通知时，心跳超过 3 秒后清理失联页面，再进入 2 秒宽限期，因此最后页面关闭后最迟约 5 秒退出。此规则同样适用于升级期间：需要全程监测时必须保持至少一个页面打开。服务启动后尚未打开过网页时不要自动退出。

关闭后的文本日志和原始字节文件保留在原路径，不自动移动、删除或截断。服务退出后原网址不可用，不部署常驻管理服务，也不在再次访问时自动打开串口；需要继续查看时重新运行启动脚本。关闭通知只接受回环地址请求，并校验本次随机会话令牌。

用户只要求实时显示串口时，到此为止：打开终端面板并持续监测，不附带设备搜索、协议登录、文件上传或升级。

U-Boot 与 A/B 分区手工操作

1. 串口网页控制台不提供 U-Boot 持续按键、定时发送、提示符自动识别停止或一键切换 A/B 分区；不要通过隐藏接口或后台线程补回这些行为。
2. 需要在启动阶段输入 eapil_uboot_key_str 时，由用户在普通命令框中自行输入和发送；设备无法由电脑控制重启时，可以在控制台已经连接后请用户手动重启。
3. 进入 U-Boot 后仍由用户按需填入并主动发送命令。常见核对顺序为：printenv systemSelect、setenv systemSelect A 或 setenv systemSelect B、saveenv、再次 printenv systemSelect、reset。快捷按钮只能填入文本，不能自动发送或串联执行。
4. 分区恢复成功需要看到内核命令行中的 systemSelect=...、系统明确报告运行于目标 A/B 分区、核心应用恢复，并且没有 panic、看门狗或循环重启。网络恢复属于后续独立诊断，不作为这一步成功的必要条件。

Telnet 与交互命令

1. 先让用户选择串口或 Telnet。串口需要本次确认的 COM 口；Telnet 需要设备完整 SN 和型号，然后广播发现并精确核对 IP，不能沿用历史 IP。
2. Telnet 登录名和密码从当前 Linux 工程的准确配置读取，优先检查 product.json 中的用户配置。不要从截图 OCR、相似机型、旧固件或历史记忆猜测，也不要把凭据写入 skill。
3. 当前配置认证失败或设备版本与配置不一致时再调查历史固件配置。限制失败登录次数；首次明确失败后先停手核实，不连续试猜密码。
4. 串口与 Telnet 是否共用密码必须由工程配置或用户确认，不能推断。
5. 用户明确要求 ifconfig 等命令时，若已有已验证且仍连接的会话，就只发送该命令并实时展示结果；登录验证只执行最少的只读命令，完成后退出。

成功判据

完整成功需要组合证据：

1. EPFP 返回明确 status=2。
2. 串口出现正常校验、烧录、启动过程，没有明确失败终态；如果存在设备已知成功标记，例如 update successful，记录其时间。
3. 设备完成重启。
4. 广播重新发现同一个完整 SN。
5. 网络恢复，目标 IP 可达；IP 变化时以同一 SN 为准更新目标。
6. 30101 查询成功。
7. 应变化的 inner.version 或 outer.version 与目标构建一致。

缺少任一证据时不要补造“全部成功”。可以报告“协议升级完成，但尚未验证版本”或“设备已重启，但未收到协议终态”等部分结论。

失败分类

阶段	典型证据	后续检查
串口准备	端口不存在、拒绝访问、被占用	核对 COM 口和占用程序
设备发现	无响应、候选冲突	网卡、V1/V2、广播出口、防火墙、二层网络
身份预检	SN 或型号不匹配	停止，不传 ROM，重新选择目标/固件
TCP 连接	8942/8943 拒绝或超时	IP、服务状态、设备网络、端口监听
ROM 发送	连接断开、发送异常	最后发送量、串口错误、设备重启时点
下载阶段	downloaded 不增长	网络、设备缓存、服务负载
Flash 阶段	flashed 不增长、status=3	ROM 兼容性、分区、校验、Flash 错误
重启阶段	协议完成但串口无启动	启动加载器、内核、供电、看门狗
网络恢复	串口正常但未重发现	DHCP/Wi-Fi、网线、IP 变化、服务启动
版本回查	设备在线但版本未变	比较字段选错、升级分区未切换、回滚

日志中的 error、failed、timeout 字样不是自动失败判据。结合发生时间、是否重复、协议终态、设备功能、重启次数以及是否出现 panic、segfault、core dump 或看门狗循环判断。升级停止和启动阶段的一次性模块告警可以记录为警告；若同一 SN 已正常重启、网络恢复、版本正确并持续心跳，不应仅凭孤立字样推翻成功结论。

日志快照与远端协查

持续监测期间不要为了上传而关闭串口。复制本任务生成的活动文本日志和原始字节文件形成稳定快照，记录时间范围并计算 SHA-256，再上传到约定的远端临时目录，例如 /tmp/<项目>-windows-logs/<时间戳>。

请求 Linux 任务协查时附带：完整 SN、型号、IP、COM/波特率、升级前后版本、问题时间窗口、症状和复现步骤、远端日志路径及 SHA-256、希望对方回答的问题。不要在任务消息里粘贴整份大日志。

超时和重试

• 有进度就继续等待，连续 60 秒无下载或烧写变化才判定疑似停滞。
• status=3 立即失败。
• TCP 断开但未收到 status=2 时不能直接成功；结合串口和重启证据报告“协议终态缺失”。
• 保存最后状态、进度、串口末尾片段和错误时间线。
• 不自动再次刷机。分析后重新展示预检信息，并等待新的明确确认。

验证报告

verification.txt 按以下顺序记录：项目与 ROM、目标设备身份、升级前后版本、协议结果、串口关键事件、网络与身份复查、未完成检查、最终结论。包含 SHA-256、升级前后 IP 和日志路径，不用把全部串口内容复制进摘要。

串口网页控制台变更验收

更新串口服务或页面后至少完成以下检查：

1. 使用 serial_web_console.ps1 -ValidateOnly 验证 C# 服务能够编译且网页资源存在，再运行 Skill 的 quick_validate.py。
2. 启动前确认目标 COM 口没有被第二个串口工具占用；启动后核对状态接口报告端口已打开，不能只根据 PowerShell 进程存在作结论。
3. 设备有输出时核对接收字节数和文本日志文件大小确实增长；设备静默时明确报告“尚未收到数据”，不能把空白页面说成实时采集正常。
4. 发送普通文本后，核对设备响应及对应 [TX:命令]；命令框为空时发送 Enter，日志必须出现 [TX:命令] <CR>。
5. 首次打开或刷新页面时应显示最新日志；勾选自动滚动后立即回到底部并持续跟随，用户向上查看历史时页面不能强制抢回滚动位置。
6. 核对 Enter 发送、Shift+Enter 换行、上下键隐式历史、Esc 清空、输入法候选确认不误发、长按 Enter 不连续空发，以及请求进行中不重复提交。
7. 出现 Password: 后输入框应自动遮挡，密码不加入页面历史；按当前调试策略，TX 文本日志仍保存实际发送内容。
8. 打开两个页面时关闭其中一个，服务应继续运行；关闭最后一个页面后，正常离页约 2 秒、未触发离页事件时最迟约 5 秒，状态接口应离线、宿主进程应退出，日志应写入结束标记且 COM 口应释放。刷新页面不能误停服务。
9. 自动停止后核对文本日志和原始字节文件仍位于原路径且未被截断；再次启动服务并确认能够重新打开同一 COM 口。升级期间关闭最后页面也按相同规则停止，不能宣称仍在后台监测。