设计决策更新: - 决策 #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 第一性原理落盘
20 KiB
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),聚焦三条线:
- ARM Linux 系统编程——GPIO/sysfs、I2C/SPI/UART、DMA、中断、多线程、内存管理
- ROS2 节点——ROS2 官方 tutorials + 示例,直接就是 ARM Linux 上跑的
- BPU/AI 部署——RDK Model Zoo 示例、OE 工具链转换流程
七、待讨论
- 5000 case 的具体采集和生成方案(ARM Linux + ROS2 + BPU 三条线)
- harness runtime 实现
- A/B 对比评测的实验设计