KunAutoDrive

面向自动驾驶与机器人的仿真优先中间件：C11 核心、C++20/FlowCoro 节点、 配置驱动插件管线，以及可观测、可回放、可评估的数据闭环。

体量速览：C 核心与节点 ~4 万行 · C++ ADAS 节点 ~2.8 万行 · Python 工具链/ 评估器/门禁 ~4 万行 · 手写前端（3D 仪表盘，无框架 ES modules）~2.2 万行； 默认管线 17 节点、L3 sensor 编排 16 节点；9 条静态门禁 + 6 组前端门禁 + 40 项 ctest + 16 场景回归基线；配套 5 部 26 章技术专著 （docs/BOOK.md）。

演示截图

先看这里

KunAutoDrive 当前是仿真优先、可复现的实验与集成平台：感知、融合、规划、 控制和学习算法应先在仿真中运行、观察、评分和回放，再逐步迁移到实车。项目 提供 RC 小车部署 profile；乘用车量产认证并非当前承诺范围。

你想做什么	从这里开始
运行 3D 自动驾驶演示	快速开始
用键盘接管车辆、检查轮向/车身方向	游戏诊断模式
了解 L3 安全能力（ODD/TOR/MRM/故障注入/EDR/R157）	L3 安全闭环
部署到 RC 小车	车辆部署
记录并分析 PEM 车端数据	PEM 数据闭环
修改算法并做回归	验证与 CI
了解系统组成	架构 与 文档导航

快速开始

git clone https://github.com/caixuf/kunautodrive.git
cd kunautodrive

# 构建并运行默认仿真；浏览器打开 http://localhost:8800
bash scripts/demo.sh

# CI/无图形环境常用形式
bash scripts/demo.sh --no-browser 15

默认管线是 config/pipeline.json，由 flow_launcher 加载各个 .so 节点。 它用于仿真和仪表盘开发，不会写 PEM。

常用选项：

bash scripts/demo.sh --scenario scenarios/curve_road.json --no-browser 30
bash scripts/demo.sh --record
bash scripts/demo.sh --multi

游戏诊断模式

运行 demo 后，打开 FlowBoard 左上角的接管车辆：

• 使用 WASD 或方向键直接控制车辆；再次退出即可恢复自动驾驶。
• 游戏 HUD 内的「灯光测试」按钮可切换近光、左/右转向灯和双闪；也可用 L/Q/E/H 操作，S/↓ 或空格测试刹车灯。
• HUD 同时展示转向输入、车身航向、实际移动方向和它们的偏差，用于定位车轮、 死推和物理积分不一致的问题。
• 偏离道路时按 R 或点击回到车道，将车辆安全放回最近车道中心。

仿真约定 steer > 0 为左转（ENU heading/y 增大），steer < 0 为右转； 游戏模式是诊断工具，不改变规划、控制和安全模块的职责边界。

架构

flowsim -> sensor_model -> perception -> fusion -> planning -> control
   -> safety_control -> monitor -> flowmond -> FlowBoard / PEM / evaluator
                         |
                         +-> data_recorder -> train -> inference -> OTA

层	关键能力
核心	Pub/Sub 消息总线、local/IPC/TCP transport、调度器、时钟、参数、注册表
节点	FlowCoro 协程节点、插件加载、健康检查、服务发现、状态机
ADAS	FlowSim、传感器模型、感知/融合、行为、轨迹与速度规划、控制、安全闸门
可视化	flowmond、FlowBoard 3D/2D、拓扑 JSON、IPC 与文件桥接回退
数据闭环	Bag/MCAP、评估器、训练/影子推理、PEM 车端遥测、模型 OTA

详细模块职责和数据流见 可视化架构、 监控架构和 数据闭环。

L3 安全闭环

在核心中间件之上，项目实现了一条完整的 SAE L3 安全闭环，全部由带牙的 CI 门禁锁定（门禁抓不住已知故障 = 它的 PASS 不可信）：

能力	内容	验证
ODD / TOR / MRM	运行设计域监控 → 脱离请求 → 最小风险机动，MRM 真停（遥测缺失=INCONCLUSIVE≠PASS）	ctest -R tor_mrm_sim + l3_odd_exit_* 场景
故障注入	6 类故障（定位丢失/感知丢失/规划丢失/原始指令超时/GPS 冗余/全源丢失），每类都有可观测的降级路径	ci/gates/fault_inject_gate.py（6/6）
降级阶梯 + 看门狗	L1/L2/L3 单调降级、8 节点心跳覆盖、心跳表满静默丢弃已修复	ctest -R safety_fault_evidence
定位冗余	GPS/航位推算交叉校验，单源丢失不误判为定位丢失	tools/localization_integrity_sim.py --run-all
毫米波雷达模型	量程/FOV/方位基准/径向速度符号的观测模型，IDL 线格式与 C 结构体逐字节对齐	ctest -R "adas_nodes_logic|new_module"
EDR 事件记录	L3 法规事件（激活/退出/TOR/MRM/ODD 退出/碰撞）落 PEM，关键事件 fsync	ci/gates/l3_edr_gate.py
UN R157 法规场景	ALKS 切入/切出/急刹/施工区/传感器失效五类场景，场景可声明故障注入	scenario_regression --baseline（16 场景基线门禁）

排查此类问题的方法论沉淀在故障模式表（67 行现象 → 根因 → 位置，6 类分节），Roadmap 见 docs/ROADMAP_L3.md。

车辆部署

当前可实际部署的 profile：

Profile	配置	用途
simulation	config/pipeline.json	默认仿真、算法开发和可视化
rc_car	config/pipeline_car.json	GPS/IMU/激光雷达/执行器的 RC 小车模板

生成部署包：

bash scripts/deploy.sh --package

RC 小车接口、接线、标定和上车前检查见 RC 小车硬件清单。量产 profile 中未实现的 车型仅是显式占位，部署工具会拒绝将它们作为可运行目标。

Windows

Windows 原生单进程插件管线受支持。安装 CMake、Ninja、WinLibs MinGW-w64 （POSIX + UCRT，GCC 11+）和 Python 后：

git clone https://github.com/caixuf/kunautodrive.git
cd kunautodrive
git submodule update --init --depth 1 third_party/esmini
powershell -ExecutionPolicy Bypass -File scripts\demo.ps1 -Duration 30

Windows 的完整运行时验收与部署说明见 硬件部署指南；Linux 到 Windows 的交叉编译 使用 cmake/mingw-w64-x86_64.cmake。

PEM 数据闭环

config/pipeline_car.json 的 production 模式会启动两条 PEM 流：

• monitor_node：系统、topic、health 和降级事件等基础设施记录。
• pem_collector_node：通过 FlowCoro 异步回调采集 GPS/定位里程、行驶时长、 地区迁移和降级事件。

两条流都具备 CRC、关键事件 fsync、按时间/大小轮转和目录配额保留。解析：

python3 tools/pem_dump.py /tmp/kunautodrive_pem_*.pem
python3 tools/pem_dump.py --jsonl --type business /tmp/kunautodrive_pem_business_*.pem

PEM 不是“配置了就相信”：pem_runtime_smoke 会启动仿真 production 管线，确认 实际写出并成功解析 trip:ci_simulation，且作为 integration CI 门禁运行：

env -u LD_LIBRARY_PATH ctest --test-dir build --output-on-failure -R pem_runtime_smoke

字段契约、扩展回调方式和保留策略见数据闭环。

验证与 CI

修改前先选择最小有效验证；算法、管线和前端分别有独立门禁。

# 秒级离线管线检查
python3 tools/pipeline_check.py

# 运行时行为回归
python3 ci/evaluators/demo_evaluator.py --duration 45 --interval 0.5

# 多场景矩阵
python3 ci/evaluators/scenario_regression.py --baseline

# 节点/PEM 定向测试
env -u LD_LIBRARY_PATH ctest --test-dir build/modules/adas_nodes --output-on-failure -R pem_log_protocol

# FlowBoard 改动必须执行
npm run vis:check:all

完整测试分层和算法验证模式见 算法验证模式；CI 定义见 .github/workflows/ci.yml。

开发入口

# 构建核心
bash build.sh release

# 启动配置驱动管线
./build/bin/flow_launcher config/pipeline.json --duration 30

# 查询运行中拓扑、参数和仪表盘
./build/bin/flowctl list
./build/bin/flowctl param list

新增节点应复用 clock_service.h、cJSON、node_pump() 和参数注册系统； 不要在节点中手写 JSON、裸用单调时钟或忙等执行器。代码入口和 API 速查见 代码索引与API 速查。

文档导航

完整的中文模块导航、权威文档归属和教程入口见 docs/README.md。 其中 flowrec 是配置化 topic 留存节点的独立说明。

技术专著与实战教程（book/）

《KunAutoDrive：从零构建高性能自动驾驶系统与仿真引擎》（中间件内核 FlowEngine 实战专著），完整 5 大卷索引见 docs/BOOK.md：

部分	主题	包含章节
第零部	先跑起来	00 前言 · 00b 构建、演示与 pipeline.json
第一部	框架骨架	01 用 C 造对象 · 02 可插拔 .so · 03 注册中心与参数 · 04 状态机
第二部	通信与时间	05 消息总线 · 06 序列化与 IDL · 07 共享内存 IPC · 08 服务发现 · 09 时钟服务
第三部	执行与调度	10 C++20 协程 · 11 调度器与绑核
第四部	录制与回放	12 Bag、MCAP 与 flowrec
第五部	ADAS 算法栈	13 点云聚类与跟踪 · 14 定位融合 EKF · 15 行为决策 · 16 Frenet 轨迹规划 · 17 跟踪控制与 MPC · 18 安全包络与降级 · 19 执行器 PWM / SocketCAN
第六部	仿真、可视化与学习闭环	20 FlowSim 场景设计 · 21 VLA 与世界模型前沿 · 22 flowmond 3D 监控 · 23 黑盒回归评估 · 24 端到端学习闭环

阅读顺序、每章讲什么和源码对照见 docs/BOOK.md。

---

核心技术文档

完整文档索引见 docs/README.md —— 按主题分组的全部文档 + 22 篇专著专章入口。

文档	主题
API Quick Reference	C API 参考
Simulation Guide	仿真测试指南（含 flowsim 仿真模式对照）
Pipeline Architecture	Pipeline 设计与管线拓扑
Algorithm Stack	算法总览（各模块真实算法 × 文件对照）
Algorithm Integration	算法集成指南
Planning Speed Upgrade	ST 图 + DP 速度规划设计
Visualization Architecture	flowmond + vis/ 模块树（Layer + ViewRegistry + Qt 对象树）
Vis Module Guide	vis/ 模块接口契约 + 设计 AI 提示词模板
Monitoring Architecture	flowmond + stats bridge
FlowBoard Contract	仪表盘数据契约
FlowBoard Scene Contract	scene 数据契约
Hardware Deployment	硬件部署
RC Car Hardware Checklist	RC 小车硬件落地清单
Learning Loop	仿真内学习闭环
Troubleshooting 3D Dashboard	3D 仪表盘故障排查

---

许可证

MIT License. 产品与仓库名称为 KunAutoDrive。FLOWENGINE_*、flowengine_core 和 libflowengine_* 等保留为 ABI/API 兼容名称，不应作为普通重命名目标。