16 KiB
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,返回候选摘要,绝不默认挑一个。
- 0 个 →
- 恢复是幂等的,不重复执行已成功完成的 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,是跨功能切片的稳定决策默认值:
- Current-device evidence outranks prior knowledge —— 资料、规则、历史案例只能提供预期与假设,只有当前设备 Observation 能支持本次故障的 Evidence。
- Keep facts separate from interpretation —— Action / Observation / Evidence / Hypothesis 各司其职;模型推断不能改写 Observation。
- Constrain execution; preserve reasoning flexibility —— 模型可以自由推理,但只能通过语义 Inspector 执行。
- Make uncertainty explicit —— 未知、不支持、不确定都是合法结果;不把“可能”写成“已确认”。
- Keep Core product- and capability-agnostic —— Core 不包含任何 S100/GS130W/Camera 特判。
- Prefer one evidence-producing action over a checklist —— 一次执行一个能区分竞争假设的检查。
- Build vertical slices and verify external assumptions early —— 每个里程碑从 Pi 入口到可观察结果完整贯通。
- Fail closed on safety and evidence boundaries —— 安全、身份、审批、证据链无法确定时显式拒绝,绝不静默降级。
- Guards only deny; they never allow —— 守护链单调收紧,拒绝后不可能被后续守卫放行。
- 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