《host-code-quality.md》修订附录 2026-10-19

原报告 · 核对基线 commit eac3717 · 总评审：DCU_DesktopController_专家评审_2026-10-19.html

原报告：上位机代码质量评估（冗余 / 复杂度 / 屎山风险）
时间线：status: delivered，2026-09-23（27a8fc1 → 83a035c）
原结论概要：综合约 3.5/5；P0 服务端风险已落地，电机前端回滚后只外提 scope/seq/ota；R4~R7 部分/未实施。

原文件保持不变；本附录逐条记录其结论在当前代码中的状态。

逐条结论跟踪

编号	原结论 / 建议	当前状态	证据（文件:行号）	备注
HQ-R1	非幂等不自动重发	部分修复	`ecat_client.py:58-62, 290-299, 418-436`	HTTP 代理已遵守；ESF1 快发重试违反同一原则（P-2）
HQ-R2	网卡默认 I210	已修复	`ecat_proc.py:28`
HQ-R3	跨进程互斥/复用	部分修复	`ecat_proc.py:67-94, 125-140`	锁超时/CreateMutexW 失败仍继续执行（P-4）
HQ-R4	拆 main.js	部分修复	`js/motor/main.js（3254 行）`	仍为上帝文件（M-18）
HQ-R5	版本/参数下沉	仍未实施	`—`
HQ-R6	ECAT bootstrap 单点	部分修复	`js/motor/transport-ecat.js:418-441; js/common/ecat-bus.js:65-75`	电机侧仍自算周期并绕过预算（M-6）
HQ-R7	toast/quiet 去重	仍未实施	`js/can/send.js:17`	CAN 侧还出现 toast 双实例（C-9）
HQ-R8~R14	服务端拆分与卫生	已修复（大部分）	`ecat_client.py; ecat_proc.py; docs/reports/`	但 .qoder/.zcode 入库（H-1）
HQ-R15	README	部分修复	`README.md:3, 190, 449`	个人路径与默认周期描述过时（H-2、H-4）

相关新问题（详见总评审）

致命 [P-2] ESF1 快发在 sendall 成功后出错仍整包重发

模块: 主机服务/安全
位置: ecat_client.py:247-279
现象: _tcp_once 持锁 sendall(body) 后读 8 字节 FSOK；recv 超时/断连抛异常时 attempt 0 会 continue，attempt 1 再发同一 body。与同文件非幂等不重发原则（_ECAT_IDEMPOTENT_TAILS）矛盾。
风险: 同一帧运动指令被 native 入队两次，电机执行两次增量/相对命令。
修改建议: 仅当 connect 阶段失败时重试；sendall 之后的任何异常直接返回 ok:false（可附 maybe_sent 标记）。

严重 [H-1] AI 工具目录被提交

模块: 仓库卫生/文档
位置: .qoder/repowiki/（约 75 个文件）; .zcode/plans/plan-sess_*.md; .gitignore
现象: .qoder 自动生成的知识库与 .zcode 个人调试计划（含 G:\ 路径与固件计划）入库，且未列入 .gitignore。
风险: 仓库噪声、信息泄露、与真实代码不同步误导读者。
修改建议: 移出仓库（需用户决定，本次评审不删除任何文件）并加入 .gitignore。

严重 [M-6] 「谁可以动总线」红线被多处绕过

模块: 电机控制/故障保护
位置: js/motor/transport-ecat.js:394-459, 668; js/common/device-link.js:250-287, 322-327
现象: transport-ecat.ensureStarted 在 isBusHealthy 为 false（含 unknown）时调用 motor/start，不带 reason、不走 ensureEcatLoopRepair 预算，并重复实现 ecat-bus.resolveEcatStartBody 的周期/DC 逻辑；Owner bootstrapEcatBus 同样无 reason 且把 unknown 当需要启动；repairEcatDc 无间隔/次数预算，pollEcat 每 2 s 与 healthCheck 都可触发。
风险: 健康总线被误重启、OTA/刷写期间总线被抢、DC 修复风暴。
修改建议: 所有 start/repair 统一经 ecat-bus 单入口（带 reason、预算与 OTA 闸）；unknown 状态不得触发启动；删除 transport-ecat 内重复的周期计算（与 host-code-quality R6 同源）。

严重 [P-4] 跨进程锁超时或 CreateMutexW 失败仍继续执行

模块: 主机服务/安全
位置: ecat_proc.py:67-94（尤其 72-81）
现象: _EcatProcXLock 未拿到锁（_owned=False）时不中止，后续 kill/拉起照常进行。
风险: 多实例并发 kill/start，串行保护失效。
修改建议: 未拿到锁时返回失败（503）或只读复用，不做 kill/start。

一般 [C-9] toast 模块被加载成两个实例

模块: CAN/公共层
位置: js/can/send.js:17; js/can.js:19-20, 47
现象: send.js 以 ?v= 查询串导入 toast.js，违反 can.js 自身规则，产生两个模块实例，去重与隐藏计时不共享。
风险: 重复提示。
修改建议: JS 间 import 去掉 ?v=。

一般 [H-2] 受版本控制文件含个人绝对路径

模块: 仓库卫生/文档
位置: scripts/build_mem.bat:21; README.md:3, 449; docs/compose/spec/host-code-quality.md:67
现象: G:\Robot_v2\... 等路径。
风险: 换机即失效。
修改建议: 改为相对路径或环境变量。

一般 [H-4] 注释/文档与代码不符（默认周期等）

模块: 仓库卫生/文档
位置: js/motor/transport-ecat.js:37, 166, 416-417, 607; README.md:190
现象: 注释写 supportsOta=false，实际 :607 为 true；注释与 README 写『默认 4 ms 由后端决定/删键跟随后端』，实际回落 0.25 ms。
风险: 误导调参与维护。
修改建议: 统一以 ecat-bus.js 常量为准并修正文档。

建议 [M-18] main.js 约 3250 行，流控逻辑重复

模块: 电机控制/故障保护
位置: js/motor/main.js:807-948
现象: 单文件过大、依赖函数提升的闭包顺序；sendBatch 与 sendBurst 流控代码复制。
风险: 改动易引入回归。
修改建议: 拆分 cmd 编码、流控、UI 绑定、持久化模块；抽公共流控。

结论

共 9 条：已修复 2、部分修复 5、仍存在/存疑 2、已过时 0、无法在本仓库核实 0。