d-robotics bd1f8e79b8 实现循环磁盘持久化 (ADR-0002 后续)
循环状态工具(add_evidence/update_hypothesis/record_manual_check/close + 3 只读 inspector)状态变更后 commit 到 FileDiagnosisStore;create 持久化 Target;跨进程 recoverDiagnosis 恢复 evidence/hypotheses/next_action/resolution

Core 零改动(保持持久化无关);package-smoke 隔离 create 落盘目录;新增跨进程恢复测试 + 无 id 跳过 completed 对称测试

typecheck 零错误 + vitest 190/190(31 文件)
2026-08-21 14:16:44 +08:00

RDK Diagnose

面向嵌入式外设 Bring-up 与故障定位的 只读诊断 Agent,以 Pi Package 形式交付,运行在开发者主机上,通过 SSH 对目标板执行受控的语义化检查。

当前 MVP(v0.3.0)的唯一真实纵向验收链路是:

RDK S100
+ Camera Expansion Board
+ GS130W / 双 SC132GS
+ Sensor detection 与 Camera 控制链路诊断

状态:v0.3.0 已实现并通过真机回归。 自动化:117 个测试全部通过;npm run typecheck / npm test / npm pack --dry-run 均通过。 真机:current / historical / physical pause-resume / launch_once / I2C 审批门 / post-change verification 全部验证通过。


1. 它解决什么问题

嵌入式系统出问题时,真正困难的不是“执行某条命令”,而是:

问题发生在哪一层?下一步最值得检查什么?

一个外设从硬件到应用经过多层堆栈:

Physical Hardware
→ Power / Reset / Clock
→ Bus / Interface
→ Device Tree / Kernel
→ Driver / Runtime Library
→ Linux Device
→ ROS2 / TROS
→ Package / Launch / Node
→ Application

RDK Diagnose 把分散的命令、日志、硬件知识和排查经验,组织成一条基于当前设备证据的诊断过程:执行一项检查 → 解析为 Observation → 解释为 Evidence → 更新 Hypothesis → 选择下一项检查,直到证据充分或到达安全/权限边界。


2. 当前能力总览

能力 说明
S100 摄像头高层 Journey rdk_diag_camera_diagnose 自动完成 Target/Diagnosis 创建、SSH 连接、身份识别、知识路由、日志诊断、失败运行回放、物理操作暂停恢复
17 个语义工具 不暴露任意 Shell;每个工具是带严格 schema 的受审合同
证据门控 EvidenceGate 校验引用完整性;physical_hardware 高置信度结论必须覆盖 6 类证据,否则 policy_blocked
持久化与跨进程恢复 FileDiagnosisStore 落盘全部诊断状态;recoverDiagnosis 按 diagnosis_id 恢复,多候选时显式要求用户选择
I2C 受控探测 逐次审批;审批只对原 Diagnosis、原 bus、原 address 有效;已 settle 的审批不可复用;审批持久化
验收闭环 完成的报告生成 verification_plan;post_change_verification 只复验计划内 Inspector,全部满足输出 ready
camera.launch_once 受控启动 默认关闭;仅在无可用日志且 Target Policy 明确允许时执行一次,不停止已有进程

3. 快速开始

3.1 安装

# 在 Pi 环境中安装本包
pi install ./

安装后 Pi Runtime 会加载:

  • Extension:extensions/rdk-diagnose.ts(注册 17 个工具)
  • Skill:skills/rdk-diagnose/SKILL.md(诊断思维框架与工具使用流程)
  • Knowledge:knowledge/ 下的通用模式、诊断规则、历史案例

3.2 开发环境

npm install

# 类型检查
npm run typecheck

# 运行全部测试
npm test

# 校验包内容(不发布)
npm pack --dry-run --cache /tmp/rdk-npm-cache

技术栈:TypeScript ESM(module: ESNext、moduleResolution: bundler、strict: true)、Vitest。

3.3 真机验证

项目提供真机验收脚本,目标板默认是 rdk-s100:

PI_CODING_AGENT_DIR=/tmp/pi-agent \
  npx tsx tests/helpers/verify-s100-camera.ts

可选地验证 camera.launch_once 受控启动路径:

PI_CODING_AGENT_DIR=/tmp/pi-agent \
  RDK_DIAG_VERIFY_LAUNCH_ONCE=1 \
  npx tsx tests/helpers/verify-s100-camera.ts

持久化数据写入 PI_CODING_AGENT_DIR/agent/rdk-diagnose,未设置时使用 ~/.pi/agent/rdk-diagnose。


4. 系统架构

4.1 分层与依赖方向

graph TD
  Runtime["Pi Runtime"] --> Ext["Pi Extension / Composition Root"]
  Ext --> Core["Diagnosis Core<br/>capability-agnostic"]
  Core --> Contracts["Core-owned stable contracts"]
  Profiles["Product / Peripheral Profiles<br/>declarative data"] -.->|implements| Contracts
  Caps["Capability Plugins<br/>Inspectors / Parsers"] -.->|implements| Contracts
  Infra["SSH Transport / Persistence / Knowledge"] -.->|implements| Contracts

核心规则:

  • Pi 类型止步于 Extension;Core 和 Diagnosis Report 不依赖 Pi 会话格式。
  • Core 不包含 S100、GS130W 或 Camera 的任何特判。
  • Profile 是声明式数据;Capability 拥有领域 Inspector/Parser;Infrastructure 实现端口,不产生诊断结论。
  • 共享代码只有一个明确所有者;跨模块协作通过稳定 ID 和经过校验的 schema。

4.2 能力插件体系(Capability Plugin Architecture)

诊断推理框架是通用的,但具体的检测能力以 Capability 插件形式接入。当前唯一完整插件是 Camera;Core 不包含任何产品/外设特判。

关注点 Core 负责 Capability 插件负责
状态机与实体 ✅ Diagnosis/Action/Observation/Evidence/Hypothesis ❌ 不拥有状态机
证据门与结论门槛 ✅ EvidenceGate 统一校验 ❌ 不能放宽
执行安全 ✅ 审批、Policy、fail-closed 守护链 ❌ 只能提供固定命令模板
领域检查 ❌ 不知道 S100/GS130W/Camera ✅ Inspector、Parser、领域知识

新增一个外设能力(以 WiFi 为例)的扩展路径:

1. src/profiles/              增加 WiFi 相关 Product/Peripheral Profile 声明
2. src/capabilities/wifi/     实现 Inspector + Transport + Parser
3. knowledge/                 增加 WiFi 诊断规则与历史案例
4. extensions/rdk-diagnose.ts 注册 rdk_diag_wifi_* 语义工具
5. src/journeys/              如需高层自动化,新增 wifi-diagnosis.ts

关键约束:插件只能决定“能查什么”,不能放宽“能下什么结论”或“能执行什么风险操作”。 所有插件都受同一套 EvidenceGate、审批和 fail-closed 守护链约束。

4.3 运行时主流程

Preparation Flow:
  用户症状 + SSH 目标
  → 创建 Target / Diagnosis
  → SSH 连接检查
  → 识别产品身份(Expected/Observed 冲突 fail-closed)
  → 路由领域知识

Diagnosis Flow:
  执行一个语义 Inspector
  → 原始输出存为 Artifact
  → Parser 生成确定性 Observation
  → 模型基于 Observation 提出 Evidence / Hypothesis
  → Core 校验引用、权限、结论门槛
  → 单步推进或进入下一轮
  → 完成时生成 DiagnosisReport(含 verification_plan)

Recovery Flow:
  Pi 进程/会话结束后,按 diagnosis_id 从 FileDiagnosisStore 恢复
  → 从当前暂停边界继续,不重复执行已完成 Action

4.4 目录结构

路径 职责
extensions/rdk-diagnose.ts Pi Extension 入口,注册工具,组装依赖,接入恢复与审批路径
skills/rdk-diagnose/SKILL.md 诊断思维模型、工具使用流程、安全约束
knowledge/ 分层硬件调试模式、Camera 诊断规则、S100+GS130W 案例
src/core/ Diagnosis Core:领域实体、状态转换、报告、EvidenceGate
src/targets/ Target Registry:连接引用、Expected Context、状态
src/profiles/ 声明式 Product Profile(当前:rdk-s100)
src/capabilities/camera/ Camera Capability:Inspector、Transport、Parser
src/journeys/camera-diagnosis.ts 高层 Journey:准备、诊断、暂停/恢复、post-change 复验
src/persistence/ FileDiagnosisStore 与 recoverDiagnosis
src/transports/ssh.ts SSH 执行边界:固定命令模板、超时/输出上限、错误分类
src/context/collector.ts Observed Device Context 采集
tests/ 单元、集成、Journey、恢复、package smoke 与真机验收脚本

5. 诊断领域模型

Diagnosis
 ├── Action          —— 执行了什么
 ├── Observation     —— 直接看到了什么(确定性或带原文引用)
 ├── Evidence        —— 该观察的有界含义
 ├── Hypothesis      —— 待验证的原因
 ├── Artifact        —— 原始输出存档
 └── DiagnosisReport —— 结论、最高置信度层级、下一步、验证计划

5.1 状态机

  • preparation:建立连接与身份,不计入正式诊断轮次。
  • diagnosis:正式诊断轮次,round 递增推进。
  • awaiting_user_action:暂停在历史运行选择、物理操作或审批边界。
  • 终态:completed / abandoned。

5.2 EvidenceGate

  • 所有 Observation/Evidence/Hypothesis 引用必须完整。
  • physical_hardware 层高置信度结论必须覆盖:
identity, software_runtime, device_tree_mapping,
power_clock_reset, repeatability, physical_cross_validation
  • 覆盖不足时返回 policy_blocked,不生成报告。
  • 决议类型 insufficient_evidence / unsupported / ready 是合法的非根因结论。

6. 工具集

所有远程操作都通过 rdk_diag_* 语义化工具完成,模型无法获得任意本地或远程 Shell。

分类 工具
Camera Journey rdk_diag_camera_diagnose
Core rdk_diag_create / rdk_diag_get / rdk_diag_finish_round / rdk_diag_close
Knowledge rdk_diag_get_knowledge
Transport / Identity rdk_diag_connection_check / rdk_diag_identify_target
Context rdk_diag_inspect_system
General rdk_diag_read_log / rdk_diag_inspect_device_tree / rdk_diag_inspect_device_nodes / rdk_diag_list_i2c_buses
Camera rdk_diag_camera_inspect_runtime / rdk_diag_camera_inspect_mapping / rdk_diag_camera_read_initialization_log / rdk_diag_camera_probe_i2c_target

工具设计遵循 Tools are contracts, not wrappers:一个工具一个概念、严格输入 schema、边界条件写入描述、结构化输出与展示分离、非法参数直接拒绝。


7. 持久化与恢复

FileDiagnosisStore 以文件系统为真相源:

<storeRoot>/
 ├── targets/<targetId>/target.json
 └── diagnoses/<diagnosisId>/
      ├── state.json          # 完整快照(含 report)
      ├── events.ndjson       # 追加式事件流
      └── artifacts/<id>.txt  # 原始输出

recoverDiagnosis(store, diagnosisId?) 的行为:

  • 给定 diagnosis_id:恢复 Target + Diagnosis 到内存,返回 recovered。
  • 不给定 ID:列出所有非终态 Diagnosis。
    • 0 个 → not_found;
    • 1 个 → 直接恢复;
    • 多个 → selection_required,返回候选摘要,绝不默认挑一个。
  • 恢复是幂等的,不重复执行已成功完成的 Action。
  • store 缺失、损坏、ID 不存在时 fail-closed,绝不静默新建 Diagnosis。

I2C 审批同样持久化在 <storeRoot>/approvals/ 下,pending 审批跨进程可恢复;已 settle 的审批不可复用。


8. 安全模型

边界 策略
任意 Shell 不暴露。远程命令由 Inspector 固定模板生成,spawn 使用参数数组、shell: false
主动探测 默认拒绝。唯一例外是 Target Policy 显式允许的 camera.launch_once 和逐次审批的 I2C 目标探测
身份冲突 Expected/Observed 不一致时阻止继续套用 Profile
证据门槛 高置信度硬件结论必须覆盖完整证据链,否则 policy_blocked
空扫描/缺失日志 只能表示“未观察到”,不能推出硬件损坏
用户审批 I2C 探测每次都要审批;审批只对原 Diagnosis、原 bus、原 address 有效;已 settle 审批不可复用

守护链原则:Guards only deny; they never allow. 任何一个守卫失败即拒绝;唯一的外部允许路径是用户显式、记录在案的审批。


9. 设计原则

来自 docs/design/core-beliefs.md,是跨功能切片的稳定决策默认值:

  1. Current-device evidence outranks prior knowledge —— 资料、规则、历史案例只能提供预期与假设,只有当前设备 Observation 能支持本次故障的 Evidence。
  2. Keep facts separate from interpretation —— Action / Observation / Evidence / Hypothesis 各司其职;模型推断不能改写 Observation。
  3. Constrain execution; preserve reasoning flexibility —— 模型可以自由推理,但只能通过语义 Inspector 执行。
  4. Make uncertainty explicit —— 未知、不支持、不确定都是合法结果;不把“可能”写成“已确认”。
  5. Keep Core product- and capability-agnostic —— Core 不包含任何 S100/GS130W/Camera 特判。
  6. Prefer one evidence-producing action over a checklist —— 一次执行一个能区分竞争假设的检查。
  7. Build vertical slices and verify external assumptions early —— 每个里程碑从 Pi 入口到可观察结果完整贯通。
  8. Fail closed on safety and evidence boundaries —— 安全、身份、审批、证据链无法确定时显式拒绝,绝不静默降级。
  9. Guards only deny; they never allow —— 守护链单调收紧,拒绝后不可能被后续守卫放行。
  10. Tools are contracts, not wrappers —— 工具是受审公共合同,不是底层命令的包装器。

10. 测试与验证

10.1 自动化测试

层级 覆盖
Core 证据门、状态转换、报告、verification_plan 构建
Persistence FileDiagnosisStore 读写、原子替换、恢复幂等
Capability I2C 审批与探测、Camera runtime/mapping/launch inspector、ROS 日志 parser
Journey 当前日志、历史失败运行回放、launch_once、物理操作暂停/恢复、post-change 复验
Package smoke 版本、入口、知识资产、工具注册与参数契约
总计 17 个测试文件,117 个测试

10.2 真机回归(RDK S100)

tests/helpers/verify-s100-camera.ts 覆盖:

  • current 路径:诊断当前启动周期 Camera 日志,且不得确认硬件损坏;
  • historical 路径:固定历史失败运行可被正确分类为 selected_failure_run;
  • physical pause-resume:暂停到物理操作边界,用户回报后从 round 1 恢复到 round 2;
  • camera.launch_once:Policy 允许且无当前日志时执行一次受控启动;
  • I2C 审批门:awaiting_approval → 持久化 pending → 批准 → probed → settled 不可复用;
  • post_change_verification:基于已完成 baseline 只复验 plan 内 Inspector,全部满足输出 ready。

11. 当前限制与非目标

当前实现明确不包含:

  • S100P / X5 或其他产品的真实诊断支持;
  • Wi-Fi / Storage / USB / CAN / UART 等 Capability;
  • 自动修复、自动修改配置、自动重启服务、写 GPIO、修改设备树或刷写固件;
  • 任意远程 Shell 或串口自动控制;
  • 多专家 Agent、RAG、远程知识库、运行时动态加载插件;
  • Coding / Fix / Build / Deploy(诊断结论与 verification_plan 为未来 Coding Agent 提供输入);
  • 通用主动故障重现(唯一例外是 Policy 允许的一次性 camera.launch_once);
  • MIPI 图像质量、ROS/TROS 业务代码级缺陷定位。

12. 延伸阅读

文档 内容
PROJECT_CONTEXT.md 项目起源、产品愿景、目标用户、经验教训
ARCHITECTURE.md 紧凑架构图:组件、依赖方向、状态所有权、公共合同、守护链
docs/MVP_DESIGN.md 完整设计冻结文档:范围、领域模型、工具集、安全策略、验收标准
docs/design/core-beliefs.md 十条跨切片设计原则与决策规则
docs/adr/ 架构决策记录(当前:受控 Camera 启动探测)
docs/superpowers/plans/ 各版本实施计划(v0.2.0 / v0.3.0)
knowledge/ 随包发布的按需诊断知识

13. 许可证

MIT

Description
No description provided
Readme 565 KiB
Languages
TypeScript 100%