HWE_harness/DESIGN.md
qinyusen 4b2b6ff8f2 v0.2.0 — 第一性原理重构 + 5000 case 采集方案
设计决策更新:
- 决策 #10: RDK = ARM aarch64 Linux + BPU + ROS2,砍掉 MCU 移植
- 决策 #11: 评测目标明确为 A/B 对比(我们的 Agent+模型 vs 地瓜的)
- 决策 #12: 硬件依赖最小化,L0+L1+L2 全在 QEMU/Docker,L3 后续补
- 决策 #13: 5000 case 三条线拆分

BENCHMARK.md v2 重构:
- 线 1: ARM Linux 系统编程 (2000 case)
- 线 2: ROS2 节点开发 (1500 case)
- 线 3: BPU/AI 部署 (1000 case)
- 变异注入 (500 case)
- 7 阶段构建路线,L3 HIL 后续补充

新增:
- tools/case_generator/ARCHITECTURE.md — 自动化 case 生成框架架构
- DESIGN.md §6 第一性原理落盘
2026-07-31 00:27:55 +08:00

20 KiB
Raw Permalink Blame History

ebd_harness 设计文档

生成时间:2026-07-30 | 状态:设计阶段


一、项目定位

嵌入式开发 LLM 能力评测 harness。类似 lm-eval-harness,但专门测试模型在嵌入式开发全链条上的能力。结合 DGAgent(地瓜机器人 RDK 平台 Agent)提供真实板卡执行环境。

一句话定位: 嵌入式开发能力的多轮 Agentic 评测框架——编译、部署、调试、验证,全链条自动化评分。


二、评测原则(已确认)

原则 1:分层渐进验证

借鉴 EmbedEval L0→L4 架构。任一层失败即停止,后续标记 skipped。

L0 静态分析 (CI, 秒级)   → MISRA/CERT/CWE 规则检查 + 隐式知识检查 + 代码质量 metrics
L1 交叉编译 (CI, 分钟级)  → OE/aarch64-gcc 工具链 + Docker 隔离
L2 仿真运行 (CI/本地)     → QEMU + Gazebo + BPU 仿真器
L3 HIL 部署 (真实板卡)    → RDK X3/X5/S100/S600 真实部署 + 传感器/执行器行为验证
L4 变异测试 (元验证)      → 验证 L0/L3 检查本身可靠性

CI 跑 L0+L1 全量,仿真跑 L2 抽样,HIL 跑 L3 关键 case,L4 定期跑。

原则 2:隐式知识测试

Prompt 只描述功能需求,不透露安全模式。测量 Embed Gap(显式 vs 隐式通过率差距)作为独立指标。

嵌入式隐式知识清单:

  • volatile 关键字(ISR 共享变量)
  • Cache 一致性(DMA 前后 flush/invalidate)
  • DMA 缓冲区对齐
  • ISR 安全(无阻塞调用、无动态分配)
  • 中断优先级配置
  • BPU 内存对齐和量化配置
  • 初始化顺序依赖
  • 电源管理(sleep/wake 正确性)

原则 3:终态验证优先

不信任 agent 文本声明。验证由 harness 执行,非 agent 自报。

验证方式:

  • 编译是否通过(exit code)
  • 单元测试是否通过(assert)
  • ROS2 topic 是否有数据(ros2 topic echo + 行为断言)
  • 传感器读数是否正确(预期值对比)
  • BPU 推理结果是否匹配(golden output 对比)
  • 硬件行为是否正确(GPIO 状态、通信协议响应)

原则 4:硬件在环反馈闭环

多轮 agentic 模式:生成→编译→部署→运行→观察→修改。

EmbeddedArena 证明:无 HIL 反馈时前沿模型部署成功率 0%,有 HIL 反馈后 7 次迭代超越人类专家。

反馈来源:

  • 编译错误日志
  • 运行时日志(dmesg、串口、ros2 topic echo)
  • 物理测量(功耗、温度、延迟)
  • 行为断言(传感器读数、GPIO 状态)

原则 5:确定性优先

所有自动化检查确定性,无 LLM-as-judge。

  • 代码质量 → MISRA/CERT C 静态分析(cppcheck/QAC)
  • 行为正确性 → 断言/输出对比/golden output
  • 编译结果 → exit code
  • 例外:调试诊断的"问题定位"可接受半自动(失败分类标注),但通过/不通过判定仍确定性

原则 6:能力 vs 回归分离

  • 能力评测(Capability Evals):难,初始通过率低,目标攀登
  • 回归评测(Regression Evals):通过率应接近 100%,防倒退
  • 评估饱和时引入更难任务

原则 7:污染防护

  • 私有 held-out set(~17%)
  • 定期更新任务来源
  • 时间截断(任务来源晚于模型训练截止)

原则 8:成本控制

  • smoke test 门控(10 条, < 5min)→ 通过才跑完整套件
  • CI 全量(L0+L1),仿真抽样(L2),HIL 关键 case(L3)
  • 并行化 + Docker 容器化
  • 编译产物缓存

原则 9:参考解必需

每个 case 有:

  • 验证过的参考解(golden solution)
  • 难度标签(easy/medium/hard)
  • 预期行为规格(expected behavior spec)
  • 失败分类标签(编译失败/运行时错误/行为不正确/超时)

三、评测维度矩阵(已确认)

3.1 能力域 × 评测层

能力域 L0 静态 L1 编译 L2 仿真 L3 HIL
代码生成 MISRA合规 + 隐式知识 + HIS metrics 交叉编译通过率 QEMU 运行正确性 —
编译部署 — OE 编译成功率 — 烧录+启动成功率
调试诊断 bug 定位准确性 修复后编译通过 — 日志分析正确性
硬件配置 DTS/Kconfig 正确性 — — 外设行为验证
ROS2 节点 lint + 架构检查 colcon build Gazebo 节点交互 真实 topic 验证
AI 模型部署 — ONNX→.bin 编译 推理仿真 BPU 推理基准(延迟/吞吐/精度)

3.2 跨层维度(所有能力域通用)

维度 说明 来源
完成轮次 任务完成所需迭代次数 EmbeddedArena
Token 消耗 input/output token 总量 IoT-SkillsBench
成本 API 费用 SWE-bench at scale
稳定性 pass^k(k 次全通过率) AgentBench
Embed Gap 显式 vs 隐式 prompt 通过率差 EmbedEval
错误恢复率 自纠错成功率 EmbedEval feedback mode

3.3 嵌入式特有维度

维度 测量方式 适用能力域
中断安全(ISR 无阻塞调用) 静态分析 L0 代码生成、ROS2 节点
DMA 对齐(cache-line 对齐) 静态检查 L0 代码生成
Cache 一致性(DMA flush/invalidate) 静态检查 L0 代码生成
实时性(WCET、jitter) 运行时测量 L3 ROS2 节点、AI 模型部署
资源泄漏(内存/FD/锁) 静态+运行时 全部
内存占用(Flash/SRAM) 编译报告 L1 全部
功耗(峰值电流/总能耗) 物理仪器 L3 AI 模型部署
BPU 利用率 板载工具 L3 AI 模型部署

四、架构设计

4.1 核心决策:方案 C — 混合编排

harness 是 agent loop 的驱动者,模型是被评测对象,DGAgent 工具是被调用的能力。

  • 评测的是模型本身的嵌入式开发 agentic 能力,不是 DGAgent 框架的能力
  • 模型通过 Pi Tool 接口自主调用 DGAgent 工具(agentic mode)
  • harness 控制循环、记录轨迹、执行终态验证
  • 借鉴 SWE-bench/AgentBench/τ-bench:模型自主决定何时编译、部署、查知识库

4.2 架构总览

┌──────────────────────────────────────────────────────────┐
│                       ebd_harness                          │
│                                                           │
│  ┌─────────────┐   ┌───────────────────┐   ┌───────────┐  │
│  │  Task Suite  │   │  Agent Loop       │   │ Evaluator  │  │
│  │              │──▶│  Controller       │──▶│ Pipeline  │  │
│  │ · task prompt│   │                   │   │           │  │
│  │ · expected   │   │  ┌─────────────┐  │   │ L0 Static │  │
│  │   behavior   │   │  │ Model       │  │   │ L1 Compile│  │
│  │ · golden sol │   │  │ Adapter     │  │   │ L2 Simulate│  │
│  │ · difficulty │   │  │             │  │   │ L3 HIL    │  │
│  │ · fail class │   │  └─────────────┘  │   │ L4 Mutation│  │
│  └─────────────┘   │         │          │   └───────────┘  │
│                    │         ▼          │                   │
│                    │  ┌─────────────┐   │   ┌───────────┐  │
│                    │  │ Tool Proxy   │   │   │  Scorer   │  │
│                    │  │ (Pi Tool    │   │   │           │  │
│                    │  │  桥接)      │   │   │ pass@k   │  │
│                    │  └──────┬──────┘   │   │ pass^k    │  │
│                    └─────────┼──────────┘   │ Embed Gap│  │
│                              │              │ 成本统计  │  │
│                              │              └───────────┘  │
│                              │                             │
└──────────────────────────────┼─────────────────────────────┘
                               │ Pi Tool 接口
                               ▼
┌──────────────────────────────────────────────────────────┐
│                       DGAgent                             │
│  dg_ssh_exec  dg_file_sync  dg_board_list                  │
│  dg_kb_search  dg_model_route  dg_dispatch_expert          │
│                              │                            │
│                              ▼ SSH/SFTP                    │
│                         RDK 板卡                           │
└──────────────────────────────────────────────────────────┘

4.3 组件设计

4.3.1 Task Suite(任务集)

每个 task case 的结构:

interface TaskCase {
  id: string;
  capability: Capability;           // 代码生成 | 编译部署 | 调试诊断 | 硬件配置 | ROS2节点 | AI模型部署
  difficulty: 'easy' | 'medium' | 'hard';

  // 任务定义
  prompt: string;                    // 功能需求描述(隐式——不透露安全模式)
  context?: string;                  // 上下文(规格说明 / 报错日志 / 原理图 / 引脚约束)
  platform: Platform;               // RDK X3 | X5 | S100 | S600 | Ultra

  // 验证规格
  expectedBehavior: BehaviorSpec;   // 终态行为规格(harness 据此做终态验证)
  goldenSolution: string;            // 参考解(验证过可编译可运行)

  // 评测配置
  maxIterations: number;             // 最大迭代轮次(默认 10)
  maxToolCallsPerIteration: number;  // 每轮最大工具调用数(默认 30)
  timeoutSeconds: number;            // 超时(默认 600s)

  // 标签
  implicitKnowledge: string[];       // 隐式知识点(volatile, DMA, ISR safety...)
  failureCategories: string[];       // 预期失败分类
  heldOut: boolean;                  // 是否私有 held-out
}

4.3.2 Model Adapter(模型适配层)

统一接口,适配不同模型 provider。模型通过 tool call 接口自主决定调用 DGAgent 工具。

interface ModelAdapter {
  // 配置
  model: string;                     // 模型 ID
  provider: string;                 // provider 名
  temperature: number;              // 默认 0(可复现)
  maxTokens: number;

  // 核心方法:输入 prompt + 工具定义 + 反馈历史,输出模型响应
  // 响应可能是:文本(代码/分析)或 tool call(请求执行 DGAgent 工具)
  generate(
    messages: Message[],
    tools: ToolDefinition[]
  ): Promise<ModelResponse>;

  // 统计
  getTokenUsage(): TokenUsage;
}

模型可调用的工具定义(通过 Tool Proxy 桥接到 DGAgent):

工具 用途 反馈内容
compile 交叉编译代码 完整编译输出(不截断)
deploy 部署到板卡 部署日志
ssh_exec 板卡执行命令 命令输出(完整,不截断)
file_sync 文件传输 传输结果
kb_search 知识库查询 查询结果
board_list 板卡发现 板卡列表+状态

模型自主决定何时调用哪个工具。harness 不干预决策,只执行和记录。

4.3.3 Tool Proxy(工具代理)

桥接 Model Adapter 的 tool call 到 DGAgent Pi Tool:

class ToolProxy {
  // 转发 tool call 到 DGAgent,返回结果
  // 同时记录完整轨迹(tool name, args, result, latency)
  async execute(
    toolName: string,
    args: Record<string, unknown>,
    trace: TraceRecorder
  ): Promise<ToolResult>;

  // 安全门:复用 DGAgent 的 SDB Gate
  // 高危命令(dd, flashcp, rm -rf)拦截或要求确认
  // harness 模式下 severe/warning 自动放行(非交互),但记录到审计日志
}

轨迹记录(借鉴 AgentBench + τ-bench):

interface TraceRecorder {
  // 完整记录 agent 的每一步
  records: TraceRecord[];
}

interface TraceRecord {
  iteration: number;
  step: number;
  timestamp: number;
  type: 'model_response' | 'tool_call' | 'tool_result' | 'compile_output' | 'deploy_output';
  content: unknown;
  tokenUsage?: TokenUsage;
  latencyMs?: number;
}

4.3.4 Agent Loop Controller(循环控制器)

状态机驱动 agent 的多轮迭代:

                    ┌─────────────┐
                    │   INIT      │  加载 task, reset 环境
                    └──────┬──────┘
                           ▼
                    ┌─────────────┐
              ┌─────│  GENERATE   │  模型生成响应(代码/工具调用)
              │     └──────┬──────┘
              │            │
              │     ┌──────▼──────┐
              │     │  EXECUTE    │  执行工具调用(编译/部署/SSH)
              │     └──────┬──────┘
              │            │
              │     ┌──────▼──────┐
              │     │  FEEDBACK   │  工具结果→模型(完整输出,不截断)
              │     └──────┬──────┘
              │            │
              │     ┌──────▼──────┐
              │     │  CHECK_DONE │  agent 声明完成?步数超限?超时?
              │     └──┬─────┬───┘
              │        │     │
              │     no │     │ yes
              └────────┘     ▼
                        ┌─────────────┐
                        │  EVALUATE   │  终态验证(L0→L1→L2→L3→L4)
                        └──────┬──────┘
                               ▼
                        ┌─────────────┐
                        │  SCORE      │  评分 + 生成报告
                        └─────────────┘

终止条件(借鉴 EmbeddedArena):

  • agent 声明完成(模型输出特定信号或不再调用工具)
  • 达到 maxIterations(默认 10)
  • 达到 maxToolCallsPerIteration(默认 30)
  • 超时(默认 600s)

4.3.5 Evaluator Pipeline(评测管道)

终态验证时分层执行,任一层失败即停止:

agent 完成或终止
       │
       ▼
  L0: 静态分析(秒级)
  · MISRA/CERT/CWE 规则检查
  · 隐式知识检查(volatile, ISR safety, DMA 对齐...)
  · HIS metrics(圈复杂度, 函数规模, 注释密度)
       │ pass?
       ▼
  L1: 交叉编译(分钟级)
  · OE/aarch64-gcc 工具链
  · Docker 隔离
       │ pass?
       ▼
  L2: 仿真运行(分钟级)
  · QEMU (aarch64)
  · Gazebo (ROS2)
  · BPU 仿真器
       │ pass?
       ▼
  L3: HIL 部署(小时级)
  · RDK 板卡真实部署
  · 传感器/执行器行为验证
  · ROS2 topic 端到端验证
  · BPU 推理基准(延迟/吞吐/精度/功耗)
       │ pass?
       ▼
  L4: 变异测试(元验证)
  · 验证 L0/L3 检查本身可靠性

中间步骤的快速反馈通过工具返回值自然传递给 agent——agent 调用 compile 工具时得到完整编译输出,自己决定下一步。终态验证在 agent 完成后由 harness 执行。

4.3.6 Scorer(评分器)

综合所有维度生成评分报告:

interface EvalResult {
  taskId: string;
  modelConfig: ModelConfig;

  // 核心结果
  passed: boolean;                   // 终态验证通过/不通过
  maxLayerPassed: EvalLayer;         // 通过的最高层级(L0-L4)

  // 分维度分数
  dimensions: {
    compilePass: boolean;            // L1
    staticAnalysisScore: number;     // L0 MISRA 合规百分比
    runtimeCorrectness: boolean;     // L2/L3 行为验证
    implicitKnowledgeHits: string[]; // 命中的隐式知识点
    implicitKnowledgeMisses: string[]; // 遗漏的隐式知识点
    embedGap?: number;              // 显式 vs 隐式差距(配对测试时)
  };

  // 效率维度
  efficiency: {
    iterationsUsed: number;          // 实际迭代轮次
    toolCallsTotal: number;          // 总工具调用数
    tokenUsage: TokenUsage;          // input/output token
    costUsd: number;                 // API 费用
    durationSeconds: number;         // 总耗时
  };

  // 稳定性
  stability?: {
    passAtK: number;                 // pass@k
    passCaretK: number;               // pass^k(k 次全通过率)
  };

  // 失败分类
  failureClassification?: {
    layer: EvalLayer;                // 失败在哪一层
    category: string;                 // 编译失败/运行时错误/行为不正确/超时
    detail: string;                   // 具体错误信息
  };

  // 完整轨迹
  trace: TraceRecord[];
}

五、DGAgent 集成

harness 通过 Pi Tool 接口调用 DGAgent 工具:

DGAgent 工具 harness 用途 评测层
dg_ssh_exec 板卡命令执行(编译、部署、运行) L3
dg_file_sync 编译产物推送到板卡 L3
dg_board_list 板卡发现和状态检查 L3
dg_kb_search 知识库查询(模型可用) 全层
dg_model_route 模型路由(评测时可选) 全层
dg_dispatch_expert 专家调度(评测时可选) 全层

六、第一性原理:平台本质(关键设计决策 #10)

6.1 RDK 平台拆解

RDK 不是 MCU。不需要从 Zephyr/FreeRTOS/ESP-IDF/Arduino 的 RTOS 世界移植。

层 本质 具体实现
CPU ARM aarch64 与树莓派、Jetson 同架构
OS Linux Ubuntu 22.04 aarch64
加速器 BPU(地平线 NPU) 某一型号的 NPU 指令集架构
中间件 ROS2 Humble / TROS 标准 ROS2 + 硬件加速封装
工具链 aarch64-linux-gnu-gcc + OE 交叉编译 + 模型转换

结论:评测任务本质是 ARM Linux 嵌入式开发 + BPU 部署 + ROS2,不是 RTOS 编程。

6.2 评测目标:A/B 对比工具

harness 不是通用 benchmark,是 A/B 对比工具:

A: 我们的 Pi Agent + 自研大模型
B: 地瓜 Pi Agent (DGAgent) + 外部模型(如 GLM-5.2)

评测对比维度:

  • 嵌入式开发全链条任务完成率
  • 多轮 agentic 效率(轮次/工具调用/token)
  • 隐式知识掌握程度(Embed Gap)
  • 编译通过率、部署成功率、调试诊断能力

6.3 硬件依赖最小化

大部分 case 不需要真实板卡:

任务类型 能否脱离板卡 方式
Linux 系统编程(GPIO/I2C/SPI via sysfs) 大部分可以 QEMU aarch64
ROS2 节点开发 可以 Docker + ROS2 Humble
交叉编译 完全可以 Docker toolchain
代码质量/静态分析 完全可以 纯软件
BPU 模型转换 (OE) 可以 OE Docker(x86 上跑)
BPU 推理验证 需要板卡 只有这部分要 HIL
调试诊断 大部分可以 QEMU/Docker 注入 bug

真正需要板卡的只有 BPU 推理验证和传感器行为验证——约 10-15% 的 case。

6.4 采集策略调整

砍掉 MCU 移植(Zephyr/FreeRTOS/ESP-IDF/Arduino/Pico),聚焦三条线:

  1. ARM Linux 系统编程——GPIO/sysfs、I2C/SPI/UART、DMA、中断、多线程、内存管理
  2. ROS2 节点——ROS2 官方 tutorials + 示例,直接就是 ARM Linux 上跑的
  3. BPU/AI 部署——RDK Model Zoo 示例、OE 工具链转换流程

七、待讨论

  • 5000 case 的具体采集和生成方案(ARM Linux + ROS2 + BPU 三条线)
  • harness runtime 实现
  • A/B 对比评测的实验设计