跳到正文

故障证据与诊断闭环 ​

本流程用于 ROS 遥操的退出崩溃、反馈异常和验收失败。目标是让下一轮工作从可查询、可验证的证据开始, 不依靠某个对话记住历史。本页提供从症状选择证据、执行检查到保留结果的流程。

从当前问题选择证据 ​

接手故障、进入下一验收阶段或取得新的柜端日志时,先按下表复用已有检查,再决定是否需要新脚本。 已有有效复现直接沿用;缺失观测先记为未知,不为满足流程重做实机实验。

取得已收尾的 ROS run 后,默认先通过统一入口保存一份 inspect JSON, 从 execution、sdk、checks 和 analysis 查找已有事实。原件和分析版本相同的已有结果可直接引用, 不用为流程重复检查;缺少的观测再另做分析,并保留其输入、输出和边界。 三份真实归档的采用示例见实机与诊断状态;原件完整、归档失败和外部验收分别判断。

当前问题入口与所需证据能回答的范围
想通过网页验证可见运动?使用人工关节点动,先核对运行配置、实际起点、反馈和操作权用户操作六轴方向按钮;不要再把已删除的微脉冲用作可用性验收
历史阈值为什么误阻塞?查看实机与诊断状态,分别看停稳噪声、运动异常和停止计时旧保护下的轨迹不能证明放宽后的停止包络;历史候选不是当前运行配置
哪份记录对应这次失败?index 指定本机/工控机归档目录;对选中 run 执行 inspect哈希身份、原始状态和证据缺口;目录名不代表验收状态
实际卡在哪个阶段?查看 inspect 的 execution 阶段事实与源行号,结合 SDK 操作计数;需要时回到原始事件及过程记录零输入仍可能已经使能并发送保持目标;归档完成不等于过程验收通过,零计数也不证明未发生过未记录的动作
SDK 目标是否在柜端日志中出现?inspect 加显式 --cabinet-log,选择 cabinet.target_anchors;需要原始 SDK journal 和已取得的柜端 RPC 日志唯一目标及周期的逐项关联、源行号、覆盖和歧义;不证明重复保持命令全部送达或机械臂正确运动
两套日志的时间能直接相减吗?查看关联结果的两种原始时间、clock_relation 和时间线告警锚点跨度可比较;未校准时钟不能据此计算网络延迟,不能给柜端时间冒加时区
同一原件为什么重算出不同结果?比较 manifest 身份、source_sha256、analysis.identity_sha256 和具体指标的 criteria采集端源码与本次分析器身份分别记录;重算采用当前读取器,不能改写历史验收结论
退出故障复发了吗?ros.process_exit 与 sdk.journal_complete;执行级复现沿用RTDE 原生回归历史检查与新执行分别留证;回归通过不代替 B0/J6 运动验收

交接时留下所选检查、结果文件和仍缺的证据。若现有检查不覆盖问题,记录缺口和临时分析的输入/输出, 再决定是否纳入稳定接口;不为每个 shell 操作新增命令。产品设计取舍见实机与诊断状态。

当前能力 ​

pride diagnose 在根 Python 环境运行,不导入 SDK、ROS、CUDA 或网页服务,不连接设备。 实现位于 diagnostics.py(src/pride/diagnostics.py),复用 core 的归档、SDK 日志与时间线校验。

  • inspect:读取 ROS run 或证据包,输出带稳定检查 ID、证据位置、缺口和下一步提示的 JSON。 捕获 ROS 子进程死亡,即使 launch 自身退出码为零;保留 SDK 收尾不完整、控制柜时间缺失和时间线错误。 可选择单项症状检查,完整性始终是前置条件。
  • inspect.analysis:记录本次分析时间、Python 运行时和参与分析的 CLI/core 源文件位置与哈希, 与 run 中的采集端 source_sha256 分开。分析身份由运行时与源内容决定,不受安装目录和生成时间影响; 任一源码不可读时标记 partial、完整身份为空,不影响独立的原件完整性判据。 身份范围仅为列出的源码文件与 Python,不证明已加载的原生二进制身份;不自动恢复历史判据。
  • inspect.execution:从已校验的事件中分别列出使能/停用完成、切换失败、控制权获取/释放、停止、复位和运行时收尾记录, 保留事件源哈希、主机时间和行号。非零输入计数独立报告;请求必须具有对应成功结果才计入接受事实。 里程碑超过 100 条时保留首尾各 50 条并标记截断。未识别格式保留行号,不输出 lease、请求正文或自由文本错误。 这是事件事实摘要,acceptance=not_evaluated;静止轮询、被拒请求和外部验收结果可能未写入归档,不能由摘要补造。
  • inspect 的可选柜端关联由 cabinet.py(packages/core/src/pride_core/cabinet.py) 实现。只读取显式指定的本地 AUBO RPC 日志(轮转文件可重复传入,总计最多 128 MiB),保留各源 SHA-256、SDK sequence 和两侧行号。 六轴目标及周期必须完全相同,且两侧唯一、成功并保持顺序;重复、缺失、解析错误和顺序矛盾不能得到通过。 重复保持目标排除后单独计数。未提供柜端日志时不改变普通 inspect 的检查集合;显式选择此项但缺证据返回 2。 结果至多展示 100 个锚点并标记截断;解析错误只给源位置,不回显日志正文。
  • collect:复制原始 manifest 及其文件,保留已知但尚未登记的故障日志、显式附加文件,生成检查结果、 系统 core 元数据、诊断记录模板和文件哈希清单。已损坏或缺文件的记录也可保留;不补写原 manifest、 不把缺失文件变成合法输入。源文件复制中改变会报错,留下未封口目录,不能当作完成的证据包。
  • index:扫描显式指定的历史目录,或合并从其他机器复制来的 JSON 索引。以 manifest 哈希关联副本, 保留多个位置、失败状态、boot、配置哈希与已归档源码的身份。相同 manifest 的副本元数据不一致时显式报错。 索引只读取元数据,不验证全部原始载荷;选中一个 run 后再 inspect。

inspect 的退出码为:0 表示所选证据检查通过;1 表示至少一个已知失败;2 表示无法判定、输入损坏或操作错误。 同时有失败和未知项时返回 1,JSON 保留所有缺口。显式选择不适用项返回 2,不能把 mock 的 SDK 缺省当成 SDK 通过。 collect 的 0 只表示收集完成,源 run 仍可 failed;清单文件缺失返回 2,并保留已收集部分。 index 的 0 只表示索引构建完成,读错的记录返回 2 且列出错误;筛选失败状态不会清除这些错误。

检查结果不是 B0/B1 的完整验收结论。sdk.calls 只描述已记录调用; 最大写入间隔包含不同启用区间之间的间隔,不能直接解释成 active 周期卡顿。 停稳窗口沿用既有 core 判据,不修改阈值,也不把首次观测静止等同于精确机械制动时刻。 控制柜时钟为空时只保留主机接收时间,不推算柜内延迟。 柜端关联通过只针对唯一锚点子集。source_status 和其他失败检查保持原值;单项退出码 0 不能被当作整个 run 通过。 柜端日志不自动进入证据包,需要保全时通过 collect 的显式附件连同关联结果收集;不编辑已封口的包。

SOP:每轮留下可接续的诊断状态 ​

1. 先登记问题和范围 ​

从本机及工控机索引中查找同源码、配置、设备版本的既有失败;先读原始结果,再决定要做什么。 不要用单个“latest”覆盖历史,也不要从目录名推断运行先后或成功。

每个问题单独保存诊断记录:SDK shutdown 崩溃、静止速度判据、J6 非零脉冲超速分别处理。 在本轮 artifacts 目录从证据包的 case-template.json 复制工作记录,填写症状、阶段、完成条件和已授权范围。 证据包封口后不编辑;工作记录的每轮快照、实验脚本和结果另存,下一次收集时显式附加。 稳定的复现与修复归入测试/源码,结论归入仓库报告,不能只留在聊天或机器私有目录。

2. 保存现场,再启动新一轮 ​

控制链按原有停止与归档流程完成后,先收集本次 run。控制程序退出不应关闭唯一遥测通道。 若发生 native crash,在重建或重启前保留 core、实际加载的二进制/共享库、符号与源码身份。 自动采集目前只查询 core 元数据,不复制大体积 core,也不替用户选择或下载调试符号。

core 查询使用已校验的 ROS 子进程 PID、可执行路径、boot ID 和启动时间下界,单次最多 15 秒。 只有运行记录的 boot 与本机一致才执行查询;从工控机复制到 Spark 的 run 不会查询 Spark 的同号 PID。 systemd 查询不可用时尝试 Ubuntu Apport:通过发行版 Python 的官方 ProblemReport 读取指定元数据字段, 不加载二进制 core;同时匹配 PID、可执行路径、信号、日期和归档 ROS namespace。原始命令行仅用于匹配, 不写入证据包。系统工具缺失、权限不足、boot 不同都记为 unavailable,不能推断“没有 core”。重启后应回源机依据 历史 boot 与故障时间手动检索。systemd 的元数据存在也不保证 core 文件仍可读。 GDB 调试前核对故障时间和二进制 build ID,先看所有线程,再检查故障对象的所有权与销毁顺序。

收集目录仅本机用户可访问。原始日志、附件与 core 可能含凭据或内存数据;不自动上传、发布或脱敏改写原件。 分享时另做脱敏副本并注明处理范围,原始哈希对应原件。

3. 区分证据检查与故障复现 ​

离线检查能证明“这份归档的 SDK 日志没有排空”,不能重现“RTDE 接收线程与 shutdown 竞态”。 一个有效的复现命令必须执行相关故障路径,并断言本次症状;记录准确 argv、环境、失败签名、预算和输出。 偶发故障同时记录尝试数与命中数。简单连接/释放未命中,不等于经过启用与停用的生命周期已修复。

已有 core 是观察故障现场的依据,可先分析,不需要为满足形式而再次启用机械臂。 若只能做到离线证据检查,诊断记录保持“尚无执行级复现”,明确下一项能提高区分度的检查。 物理设备不能照搬软件竞态测试中的无限循环、并发压力或随机 sleep;设备范围遵循 现场联调,软件复现尽量通过非设备 seam/录制回放缩小。

4. 让实验淘汰假设 ​

列出有证据支持的候选原因,逐项写清预测、反证与所需观测。 每次实验记录:只改变哪个变量、为何能区分候选、预算、停止条件、结果,以及排除了什么。 若检查通过却无法排除任何候选,不把它计为根因进展;下一步补探针或调整复现条件。 同样的检查只有源码、输入、环境变化或需要衡量命中率时才重跑。

对退出崩溃,先利用 core 区分对象释放、订阅回调及 ROS 销毁顺序;对静止判据,先在同一原始窗口核对 位置、速度、柜内目标、采样相位和缺口。两类问题都不通过放宽阈值、吞异常或缺失证据默认通过来结束。 若同一脚本在使能前、获取控制权前分别检查静止,记录具体失败的那一次及其时间窗口; “没有非零输入”“无 Servo 调用”“未使能”是三个不同事实,分别用相应记录确认。

对静止等待超时,优先读取执行侧 commissioning_status 保存的窗口长度、速度最大值和 settled 返回值。 客户端稀疏 snapshot 不能代替执行侧窗口。脚本若还要求 settled 连续保持一段时间,单次为真也不表示该等待步骤通过; 区分执行侧判据、客户端等待条件和实际发出的下一条动作。源过程文件未纳入 run manifest 时显式记录其位置、哈希及边界。

5. 修复与回归使用同一症状 ​

能命中的最小复现进入回归测试:改前失败,改后通过,再检查原始完整场景。 离线旧记录仍应失败,不能通过修改诊断器把历史失败变绿。 修复后每个新 run 都使用相同检查 ID,保留其源码/配置身份;软件回归通过后才进入对应阶段的真机复验。 使用现有检查入口选择环境和超时,不额外建立通用 shell 执行器或旁路运动入口。

验收定义发生已授权的变更时,为新一轮冻结具体判据及实现身份;历史失败保留原判断。 离线重算同时注明原记录、所用分析代码与实际判据,不能把按新判据得到的派生结果当作旧轮次原本通过。 当前时间线中的停稳指标由当前读取器重算,需检查其 criteria 及 analysis;归档源码身份不等于本次分析器身份。 目前 CLI 没有从历史源码自动恢复门槛的能力,不能据此声称完成了按历史版本的重新验收。

停稳定义有三个实现消费者,变更时逐一核对并用同一组静止、持续漂移、速度越界场景验证:

消费者所在边界核对入口
Python Commissioning.settled启用、获取控制权与复位之前authority.py(backends/ros2/pride_control/pride_control/authority.py)及控制权回归
C++ Session::settled实际启用 SDK Servo 之前的原生硬件门控session.hpp(backends/ros2/pride_aubo_hardware/include/pride_aubo/session.hpp)及原生 session 回归,需要重新构建
Python stop_evidence离线报告中的停稳观测窗口telemetry.py(packages/core/src/pride_core/telemetry.py)及归档时间线回归

上层门控通过不证明原生门控也通过;mock 不经过真实硬件适配的启用判断。 另核对过程脚本的连续 true 等待条件、实际加载的二进制身份和本次归档的源码身份,再进入对应实机阶段。

6. 结束时同步证据身份 ​

将索引、证据包、诊断记录与源码提交分开传递。源码按Git 回传, 运行原件保留在工控机;复制证据包后通过 inspect 验证内容哈希。 跨机器合并索引即可发现还没复制的历史失败,不必等所有 RRD 和模型传完才知道它们存在。 根因未解决时保留未解决状态、下一项实验及缺失证据,不以“已生成报告”代替问题完成。

采用的业界实践与边界 ​

  • Nominal Test Procedures:把步骤、带时戳的事件、运行数据和自动判据放在同一记录中。 本项目采用 run 身份、固定检查 ID 和可携带证据包;尚未接入 Nominal,也未实现其在线 procedure 编排。
  • Nominal Analyst:将工程问题、可复核分析和未解事项连在一起;这里采用问题分流和带原件定位的检查结果。
  • Foxglove 时间语义:区分时间来源;这里保留主机单调时间与柜端日志时间,明确关联不等于同步。
  • OpenAI Harness engineering:让日志、状态和验证工具可由 Agent 直接操作, 以仓库保存可检索知识。这里落地 JSON CLI、明确退出码、本地检查和短导航,沿用项目的本地 prek。
  • Google SRE:Effective Troubleshooting:用观测和可反驳实验逐步缩小原因, 结合系统工作方式解释指标。这里将预测、反证、实验结果与下一步放在同一诊断记录中。
  • systemd coredumpctl:复用系统 core 索引和调试入口, 不实现自有崩溃存储/调试器;明确“元数据可见”和“core 可读”的差别。
  • Ubuntu Apport:在工控机沿用现有崩溃服务, 只提取匹配元数据,不为安装 coredumpctl 替换 Apport,不把原始 core 自动纳入可携带证据包。

当前能力为离线 ROS 证据检查及执行级原生回归;未实现的自动化与未闭环故障统一见当前状态。

故障诊断 ​

流程与证据边界见诊断 SOP。以下入口不连接设备,使用根 workspace 环境; 支持 ROS 遥操归档,其他 run 类型继续走各自的 audit/回放入口。输出为 JSON。

sh
# 查看判据和退出码;0=所选证据检查通过,1=发现失败,2=证据缺失或输入/操作错误
uv run pride diagnose inspect --help
uv run pride diagnose inspect runs/teleop-telemetry-aubo-b0-0cb6c8ee

# 固定症状检查:旧失败记录应持续返回 1;这不是执行级竞态复现
uv run pride diagnose inspect runs/teleop-telemetry-aubo-b0-0cb6c8ee --check sdk.journal_complete

# 用已取得的柜端 RPC 原件核对唯一目标;轮转文件可重复传入,总计最多 128 MiB
# 输出目录需已存在,JSON 不覆盖;只校验本地证据,不连接控制柜
uv run pride diagnose inspect runs/teleop-pulse --cabinet-log artifacts/cabinet/aubo_control.1.log --cabinet-log artifacts/cabinet/aubo_control.log --check cabinet.target_anchors --output artifacts/pulse-cabinet.json

# 显式保全柜端原件与派生分析;原件可能含凭据,仅在本机私有目录保存
uv run pride diagnose collect runs/teleop-pulse --output artifacts/incidents/pulse-cabinet --attach artifacts/cabinet/aubo_control.1.log --attach artifacts/cabinet/aubo_control.log --attach artifacts/pulse-cabinet.json

# 在源机器收集;目录必须是新目录,默认总输入预算 512 MiB
# 自动查询本机同 boot 的匹配 core 元数据,不启用设备,不自动启动 GDB
uv run pride diagnose collect runs/teleop-telemetry-aubo-b0-0cb6c8ee --output artifacts/incidents/b0-exit

# 若有源码/二进制清单、复现脚本或实验记录,可重复 --attach 显式加入
# 证据包移动后从新位置读回,连同附件逐项校验;失败 run 仍然返回 1
uv run pride diagnose inspect artifacts/incidents/b0-exit

# 两台机器分别生成索引;路径由当前工作目录解释,可使用绝对路径
uv run pride diagnose index runs artifacts --output artifacts/local-run-index.json

# 将工控机索引复制到 Spark 后直接合并,无需先复制全量原始数据
uv run pride diagnose index artifacts/local-run-index.json artifacts/ipc-run-index.json --status failed --output artifacts/failed-run-index.json

索引是元数据目录,不是完整性或验收证明;保留不同位置和失败状态。同名输出不覆盖。 collect 返回 0 表示收集完成,原始失败状态在输出中单独保留;缺文件时返回 2 并留下已收集部分。 在故障包外复制 case-template.json 作为工作记录,填写症状、复现、假设、下一实验与反证; 不要在已封口包内编辑。原始产物和 core 不自动上传。