Update embedded app debugging workflow

references/validation-and-diagnostics.md

@@ -4,22 +4,55 @@
 
 ## 串口准备
 
-1. 每次串口任务先请用户确认当前 COM 口；可以枚举 Windows 串口及描述帮助确认，但不要沿用上一次的端口或自行挑选。
+1. 新设备调试先取得本次用户确认的 COM 口，可以枚举 Windows 串口及描述帮助确认，但不自行挑选。同一调试任务、设备和参数未变时沿用已确认的端口，不因执行下一条命令或恢复页面而反复询问；更换设备、端口或目标不明确时重新确认，不从其他任务或历史记忆猜测端口。
 2. 默认 `115200`、8 数据位、1 停止位、无校验、无流控，允许覆盖。
-3. 打开失败、打开后没有输出、乱码或访问拒绝时立即停手，请用户核对 COM 口、波特率/校验/数据位/停止位/流控、端口是否已释放，必要时重新插拔或更换转接器。不要强制结束 SecureCRT、串口工具或其他进程。
-4. 只读采集使用 `scripts/serial_monitor.ps1`；需要网页实时显示或网页命令输入时，使用 `scripts/serial_web_console.ps1`。确认 COM 口已打开并开始记录后，才传输 ROM。
+3. 页面异常、打开失败、无输出或乱码时，先按下文“异常时的本地只读诊断”定位层次；确认端口打不开、占用或参数可疑后停手，请用户核对 COM 口和参数。不要强制结束 SecureCRT、串口工具或其他进程，不反复重连或自行重启设备。
+4. 默认使用 `scripts/serial_web_console.ps1` 打开可见网页，即使只读查看也使用该控制台；需要用户明确选择的终端只读采集时可使用 `scripts/serial_monitor.ps1`。确认 COM 口已打开并开始记录后，才传输 ROM。
 5. 串口网页控制台必须由同一个进程独占 COM 口并完成收、发和日志写入，不能再启动第二个采集或发送进程。服务只绑定 `127.0.0.1`，同时写本任务自己的文本日志和原始字节文件。调试信息不脱敏。
 6. 不主动读取、复制或上传 SecureCRT 的历史日志。只有本 skill 在本次任务生成的文本和原始字节日志可以默认使用；其他工具日志需用户明确授权。
 
+## 打开与复用
+
+1. 先确认当前任务已有的服务地址、目标 COM 口和日志归档；读取已有服务的 `/api/status`，核对 `port`、`isOpen`、`lastError`，不因为 PowerShell 进程或浏览器标签存在就认定串口可用。启动脚本本身不负责发现与复用旧服务，助手必须先检查再决定是否启动。
+2. 服务正常且端口匹配时继续使用同一个页面、服务和日志，不重复运行启动脚本，不另起发送/采集进程。需要显示已有页面时优先展示原标签，不每执行一条命令就新开窗口；服务属于其他任务或端口不匹配时不能直接接管。
+3. 确认没有可复用的服务后，检查 `serial_web_console.ps1` 参数说明，以 `powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File <脚本绝对路径> -Port <已确认COM口> -LogPath <本任务日志绝对路径> -WebPort <本地端口>` 启动。使用 Windows PowerShell 5.1，不使用 `pwsh.exe`；不修改系统执行策略，后台辅助进程隐藏窗口。COM 口、网页端口和日志目录取当前任务配置，不固化本次设备的值。
+4. 由助手将服务实际地址打开为可见网页，向用户给出地址和日志路径；已有标签指向该服务时复用原标签。只读检查 `/api/status` 的 `activeWebClients`、`liveWebClients`，再在设备有输出时观察 `receivedBytes`、`lastReceiveUtc` 和日志增长。`activeWebClients` 是已登记页面租约数，`liveWebClients` 是持续连接数，均不能证明用户正在看着窗口。
+5. 自动化读取 `/api/status`、`/api/log` 时不附加 `client` 参数，不伪造页面持续连接或额外心跳。页面负责自己的在线登记，后台调试脚本不能阻止最后页面关闭后退出。网页持续连接只用于页面在线判断，不代表日志完全通过该连接推送。
+6. 服务正常时不为验证而重启。服务确已退出且用户仍要求继续当前串口任务时，可按已确认参数重新启动并在原标签刷新，明确说明采集中断；不能在用户关闭最后页面后擅自重启或循环重连。重新启动使用新的日志文件，保留旧文本与原始字节文件。服务会在启动时读取 HTML 模板，只有已重启服务后刷新页面才会取得新模板和会话令牌；仅修改磁盘 HTML 后刷新旧服务不能加载更新。
+
+## 实时输入与页面生命周期
+
 只读串口脚本只负责监测。网页控制台允许用户直接输入命令，页面按 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 文本日志。
+网页输入区保持在日志下方，只保留快捷填入、命令框和发送按钮，不显示行尾选择、独立空回车、历史下拉、清空、密码开关、U-Boot 连续发送按钮及交互状态栏。页面首次打开时默认定位到最新日志；启用自动滚动后持续跟随最新输出，用户手动向上查看旧日志时不抢回位置，无日志选区时再次勾选自动滚动立即回到底部。Enter 发送、Shift+Enter 输入多行、上下方向键浏览当前页面的隐式历史、Esc 清空输入；处理中文输入法组合状态，确认候选时不能误发串口命令，并阻止长按 Enter 连续发送空回车。发送请求未完成时阻止重复提交，成功后在选区保护允许时刷新 TX 日志并保持输入焦点。页面识别 `Password:` 阶段并自动遮挡输入，而且密码不加入页面命令历史。按用户要求，实际发送内容仍会写入 TX 文本日志。
 
-每个网页标签维护独立客户端心跳。最后一个页面正常发送关闭通知后等待约 `2` 秒，若没有刷新后的新页面接管，则服务自动结束日志采集、写入结束标记并释放 COM 口；多个标签同时打开时，关闭其中一个不能停止其他页面。页面异常退出或内置浏览器不触发离页通知时，心跳超过 `3` 秒后清理失联页面，再进入 `2` 秒宽限期，因此最后页面关闭后最迟约 `5` 秒退出。此规则同样适用于升级期间：需要全程监测时必须保持至少一个页面打开。服务启动后尚未打开过网页时不要自动退出。
+### 日志文本选择与复制
+
+- 日志区允许浏览器原生拖选、双击选择和 `Ctrl+C` 复制，不拦截复制快捷键，也不因复制触发串口发送。
+- 拖选从鼠标按下开始保护，即使此时选区仍为空；拖选结束后，只要非空选区与日志区相交，就不替换日志文本节点或执行自动滚动。选择其他区域不应暂停日志。鼠标释放、取消或窗口失焦时清除拖选状态，但仍保留非空选区的保护。
+- 定时读取不能无条件重建整段正文：内容相同不改 DOM，存在选区时延后绘制。网络响应返回后、延迟布局帧执行前均重新检查选区，读取失败提示也不能覆盖选中的正文。否则用户在等待请求或布局期间开始选择，仍会被下一次更新打断。
+- 选择期间只暂停日志区域绘制与自动滚动，状态读取、串口采集、文本/原始字节落盘及页面存活连接继续。取消选择后，下次刷新展示最新数据，并按原自动滚动与手动查看位置规则处理，不用关闭串口来冻结页面。
+
+### 页面存活与关闭
+
+每个网页标签维护独立的 EventSource 持续连接，服务端每秒写入一次探测；页面进入后台、定时轮询被节流时，不因缺少轮询而误停串口。最后一个页面正常发送关闭通知后等待约 `2` 秒，若没有刷新后的新页面接管，则服务自动结束日志采集、写入结束标记并释放 COM 口；多个标签同时打开时，关闭其中一个不能停止其他页面。页面异常退出或内置浏览器不触发离页通知时，由持续连接的写失败清理该页面，再进入 `2` 秒宽限期，实测验收仍要求最后页面关闭后约 `5` 秒内退出。不支持 EventSource 的页面退回原有 `3` 秒轮询心跳超时，日志必须明确写为心跳超时，不能直接断言用户关闭了页面。此规则同样适用于升级期间：需要全程监测时必须保持至少一个页面打开。服务启动后尚未打开过网页时不要自动退出。
 
 关闭后的文本日志和原始字节文件保留在原路径，不自动移动、删除或截断。服务退出后原网址不可用，不部署常驻管理服务，也不在再次访问时自动打开串口；需要继续查看时重新运行启动脚本。关闭通知只接受回环地址请求，并校验本次随机会话令牌。
 
-用户只要求实时显示串口时，到此为止：打开终端面板并持续监测，不附带设备搜索、协议登录、文件上传或升级。
+日志和状态读取设置 `2500ms` 超时，包含读取响应体的等待；超时后页面可继续下一次刷新。这不是串口发送请求的统一超时，发送结果未知时不得直接重发命令。
+
+用户只要求实时显示串口时，到此为止：保持同一可见网页只读采集，不附带设备搜索、协议登录、文件上传或升级；不为证明可写而发送空回车或其他探测数据。
+
+## 异常时的本地只读诊断
+
+先检查以下已有证据，不向设备发送登录名、密码、Shell 命令、空回车、break 或 DTR/RTS 脉冲：
+
+- 服务层：检查状态接口是否可达、端口是否匹配且 `isOpen=true`、`lastError`、启动输出和本任务日志末尾的退出原因。接口不可达不能单独证明 COM 口故障；先区分服务未启动、已退出、监听端口冲突和启动命令错误。依据明确错误定位，不靠提升权限或重复执行碰运气。
+- 页面层：状态可达而页面异常时，检查 `activeWebClients`、`liveWebClients` 与实际服务版本；不要仅凭轮询超时声称用户关闭了页面。新版页面支持持续连接时应登记对应连接；旧模板或旧令牌需要刷新现有标签，不能通过后台伪造页面保活来补救。助手无法直接操作页面时，仅请用户完成必要的一次刷新并说明原因，不要求其重新执行设备命令。
+- 数据层：比较两个时点的 `receivedBytes`、`lastReceiveUtc`、文本和原始字节日志大小。设备静默且无错误时报告“端口已打开，尚未收到新数据”，不能断言故障或宣称收发均正常；数据增长而页面不更新时优先定位显示/请求层。
+- 端口层：已有错误明确指向端口不存在、拒绝访问、占用或数据乱码且参数可疑时，停止打开/发送重试，向用户给出具体证据，请其核对 COM 口、波特率、校验、数据位、停止位、流控、占用工具及连接。需要重新插拔、关闭用户工具或更换转接器时由用户处理，不能强制结束其他进程。
+
+保持问题发生时的日志，不为排查移动或截断原始证据。主动离页、持续连接断开和轮询超时是不同事件；只有时间与状态证据支持时才归因。恢复前不自动切换 Telnet、重启设备或重置串口硬件。
 
 ## U-Boot 与 A/B 分区手工操作
 
@@ -30,12 +63,36 @@
 
 ## Telnet 与交互命令
 
-1. 先让用户选择串口或 Telnet。串口需要本次确认的 COM 口；Telnet 需要设备完整 SN 和型号，然后广播发现并精确核对 IP，不能沿用历史 IP。
+1. 新设备调试且连接方式尚未明确时，让用户选择串口或 Telnet；已明确的选择不反复询问。串口需要本任务已确认的 COM 口；Telnet 需要设备完整 SN 和型号，然后广播发现并精确核对 IP，不能沿用历史 IP。
 2. Telnet 登录名和密码从当前 Linux 工程的准确配置读取，优先检查 `product.json` 中的用户配置。不要从截图 OCR、相似机型、旧固件或历史记忆猜测，也不要把凭据写入 skill。
 3. 当前配置认证失败或设备版本与配置不一致时再调查历史固件配置。限制失败登录次数；首次明确失败后先停手核实，不连续试猜密码。
 4. 串口与 Telnet 是否共用密码必须由工程配置或用户确认，不能推断。
 5. 用户明确要求 `ifconfig` 等命令时，若已有已验证且仍连接的会话，就只发送该命令并实时展示结果；登录验证只执行最少的只读命令，完成后退出。
 
+## 网卡未启动的分层诊断
+
+不要看到“没有 IP”就直接归因于 Wi-Fi 密码、DHCP 或硬件。按证据层级定位，前一层成立后再进入下一层：
+
+1. **总线与硬件**：用 `lsusb`、sysfs 和 `dmesg` 确认设备枚举、VID/PID、接口和断连记录。USB 已枚举只能证明总线可见，不能证明驱动已绑定。
+2. **驱动兼容性**：确认目标 ROM 中存在对应 `.ko`，核对模块名、`vermagic`、依赖和 USB alias。手动 `insmod` 后观察是否创建 `phy`、`rfkill` 和 `wlan0`；加载失败时保留完整内核错误。
+3. **链路与射频**：执行 `ifconfig wlan0 up` 或等价命令，并用扫描结果区分“驱动可用但未关联”和“射频/硬件不可用”。能扫描到 AP 是驱动、设备绑定和基本射频链路成立的证据，不等于网络已连通。
+4. **开机加载链**：从当前设备的 `appinit.sh`、模块加载脚本和工程打包映射反向追踪权威源文件、生成文件与 ROM 内最终文件。不能只修改生成目录；重新打包后要从 ROM 提取或挂载验证最终 `loadko` 内容、加载顺序和驱动哈希。
+5. **关联与地址**：分别检查 wpa_supplicant、关联状态、DHCP 客户端、IPv4、默认路由和 DNS。不要把 DHCP 失败与驱动未加载混为一个故障。
+6. **应用服务**：确认依赖网络设备的服务是否在网卡出现后自动启动或重试，并检查设备端 `8942/8943` 等任务相关端口是否监听。端口监听与 PC 可达是两项不同证据。
+
+手动加载驱动、创建 `wlan0`、关联 AP 或取得临时 IP，只能作为诊断证据或为受控升级创造条件，不能判定开机问题已经修复。最终验收必须使用包含修复的新固件重启，并证明驱动、网卡、关联、DHCP、路由和目标服务无需人工干预即可恢复。
+
+设备端已有 IP 且目标端口正在监听，但 Windows 无法建立 ARP 或 TCP 时，继续检查 PC 侧：
+
+- 是否有多个物理或虚拟接口占用同一网段，实际选路是否使用预期源地址；
+- 相关网卡是否真实连接，旧的 DHCP 地址是否已进入 `Deprecated` 状态；
+- WLAN 软件无线电是否关闭、目标配置文件是否存在、AP 是否隔离有线与无线客户端；
+- 必要时显式绑定源地址做只读连接测试，以区分错误选路和设备拒绝；不要未经授权修改默认路由或提升权限。
+
+如果打开 WLAN、添加路由或改变接口状态需要管理员权限或用户交互，停止自动操作并请用户完成最小动作。不要通过不受控的键盘注入或高风险系统修改绕过权限。
+
+产品配置 MAC、协议返回 MAC 与无线模块原始 MAC 可能不同。恢复网络前先比较三者；只有当前产品配置和设备身份均已确认，且网络准入、DHCP 租约或设备服务确实依赖产品 MAC 时，才在关联和 DHCP 之前临时恢复产品 MAC。不得把任何实测 MAC、SSID 或 PSK 写入 skill。
+
 ## 成功判据
 
 完整成功需要组合证据：
@@ -67,6 +124,8 @@
 
 日志中的 `error`、`failed`、`timeout` 字样不是自动失败判据。结合发生时间、是否重复、协议终态、设备功能、重启次数以及是否出现 panic、segfault、core dump 或看门狗循环判断。升级停止和启动阶段的一次性模块告警可以记录为警告；若同一 SN 已正常重启、网络恢复、版本正确并持续心跳，不应仅凭孤立字样推翻成功结论。
 
+本地网卡、DHCP、路由、DNS、协议端口和 `30101` 都正常时，可以把“本地网络与升级闭环”判为通过。云平台激活、Token、绑定、网关发现或业务鉴权错误要单列为云业务警告或失败项；不能用它们推翻已取得的本地网络证据，也不能把本地网络通过扩张为整机云业务全部通过。
+
 ## 日志快照与远端协查
 
 持续监测期间不要为了上传而关闭串口。复制本任务生成的活动文本日志和原始字节文件形成稳定快照，记录时间范围并计算 SHA-256，再上传到约定的远端临时目录，例如 `/tmp/<项目>-windows-logs/<时间戳>`。
@@ -89,12 +148,20 @@
 
 更新串口服务或页面后至少完成以下检查：
 
+此处指服务或页面实现变更；仅修改文档时校验技能结构、相对链接和规则一致性，不启动串口生命周期测试，不关闭或重启用户正在使用的控制台。实际设备发送、关闭最后页面等会影响调试的验收，需在用户授权范围内安排；未执行则列为待验收。
+
 1. 使用 `serial_web_console.ps1 -ValidateOnly` 验证 C# 服务能够编译且网页资源存在，再运行 Skill 的 `quick_validate.py`。
 2. 启动前确认目标 COM 口没有被第二个串口工具占用；启动后核对状态接口报告端口已打开，不能只根据 PowerShell 进程存在作结论。
 3. 设备有输出时核对接收字节数和文本日志文件大小确实增长；设备静默时明确报告“尚未收到数据”，不能把空白页面说成实时采集正常。
 4. 发送普通文本后，核对设备响应及对应 `[TX:命令]`；命令框为空时发送 Enter，日志必须出现 `[TX:命令] <CR>`。
-5. 首次打开或刷新页面时应显示最新日志；勾选自动滚动后立即回到底部并持续跟随，用户向上查看历史时页面不能强制抢回滚动位置。
+5. 首次打开或刷新页面时应显示最新日志；无日志选区时勾选自动滚动立即回到底部并持续跟随，用户向上查看历史时页面不能强制抢回滚动位置。有选区时以选区保护优先。
 6. 核对 Enter 发送、Shift+Enter 换行、上下键隐式历史、Esc 清空、输入法候选确认不误发、长按 Enter 不连续空发，以及请求进行中不重复提交。
 7. 出现 `Password:` 后输入框应自动遮挡，密码不加入页面历史；按当前调试策略，TX 文本日志仍保存实际发送内容。
 8. 打开两个页面时关闭其中一个，服务应继续运行；关闭最后一个页面后，正常离页约 `2` 秒、未触发离页事件时最迟约 `5` 秒，状态接口应离线、宿主进程应退出，日志应写入结束标记且 COM 口应释放。刷新页面不能误停服务。
 9. 自动停止后核对文本日志和原始字节文件仍位于原路径且未被截断；再次启动服务并确认能够重新打开同一 COM 口。升级期间关闭最后页面也按相同规则停止，不能宣称仍在后台监测。
+10. 单独测试页面持续连接：不发送轮询请求至少 `10` 秒，串口仍应连接并持续接收；断开连接但不发送离页通知，仍应在约 `5` 秒内退出。同一客户端新连接接管后关闭旧连接不能误删新连接。请求缺少会话令牌时不能登记持续连接。自动化协议测试不能代替真实页面的后台/刷新可见性验收，无法实测的项需明确报告。
+11. 在真实浏览器拖选或双击选中日志，跨越多轮刷新后确认选区和滚动位置保持；按 `Ctrl+C` 并核对复制内容与选区一致。同时确认后台接收字节数、文本及原始字节文件仍增长；取消选择后页面恢复更新。替身单测覆盖无变化不重建节点、拖选尚无选区、响应/布局帧竞态、错误分支保护及恢复绘制，但不能替代真实选择和剪贴板验收。此项不需要发送任何设备命令。
+
+验收记录分别列出代码/编译检查、DOM/网络替身单测、真实串口 HTTP 生命周期测试和实际浏览器交互。某一层通过不代表其余层通过，不把持续连接数当作窗口可见性证明，也不把未发设备数据的生命周期测试当作普通命令与空回车 TX 验收。
+
+维护时可运行 `node scripts/test_serial_console_page.cjs` 检查页面逻辑（DOM/网络替身，不是真实浏览器验收）。`python scripts/test_serial_web_console.py --execute --port <本次确认的COM口> --log-dir <新的测试日志目录>` 会在独立本机端口真实打开串口并测试生命周期，默认不发送任何设备数据；先停止本技能原控制台，其他工具占用时按串口准备规则停手，不能强制关闭。该测试会多次正常退出并重新打开自己的控制台，结束后释放串口，不维持生产页面保活。生产服务重新启动后需刷新现有页面加载新模板及新会话令牌。