# 基于 OpenHarmony 的异常感知、安全决策与可信恢复组件

作品简介

OH-Resilience 是一个基于 OpenHarmony 的异常感知、安全决策与可信恢复组件。项目面向无真实硬件条件下的开发与验证，使用 OpenHarmony ArkTS 应用作为端侧 Resilience Agent，使用 FastAPI 构建主机侧韧性决策引擎，并通过 WSL2 Ubuntu 中的 ROS 2 / Gazebo / Nav2 仿真环境模拟机器人任务执行、环境异常、恢复动作与运行时反馈。

项目目标是帮助机器人或具身智能系统在面对开放环境异常、任务执行失败、通信异常或安全风险时，具备以下能力：

环境异常可感知
执行失败可恢复
安全风险可约束
恢复过程可追踪
错误经验可沉淀
无硬件条件下可验证

当前工程已经打通了以下闭环：

OpenHarmony ResilienceClient
        ↕ HTTP
FastAPI 韧性决策引擎
        ↕ ROS 2 Topic / Action / Service
Gazebo / Nav2 / TurtleBot3 仿真环境

核心功能

• OpenHarmony ArkTS 端侧 Dashboard

  • 展示系统状态、异常类型、异常等级、推荐恢复动作和恢复阶段。
  • 支持手动模拟导航超时、传感器延迟、安全风险等异常。
  • 支持端侧状态机：NORMAL / DEGRADED / RECOVERY / SAFE_MODE。
  • 支持端侧 Evidence Chain，记录异常上报、策略选择、状态变化和恢复结果。

• FastAPI 韧性决策引擎

  • 提供 /health、/api/resilience/state、/api/client/event、/api/recovery/action、/api/recovery/result 等接口。
  • 实现规则异常检测、策略选择、安全约束、恢复结果记录。
  • 扩展了环境感知、任务结果验证、安全约束、错误归因和经验复用相关 API。

• ROS 2 / Gazebo 仿真接入

  • 使用 TurtleBot3、Gazebo 和 Nav2 构建无硬件机器人运行场景。
  • 提供 ros_bridge_node、ros_state_collector、fault_injector、open_environment_scenario_runner、ros_recovery_executor 等节点。
  • 支持复杂开放环境故障场景，如动态障碍、传感器漂移、通信与资源压力、安全风险导航场景。
  • 支持真实 Nav2 恢复动作：安全停止、清理 costmap、重新发送目标、全局重规划、组合导航恢复。

技术栈

模块	技术栈	语言
OpenHarmony 端侧应用	DevEco Studio, ArkTS, ArkUI, Stage Model	ArkTS
韧性决策引擎	FastAPI, Pydantic, Uvicorn	Python
仿真与机器人中间件	ROS 2 Jazzy, Gazebo, TurtleBot3, Nav2	Python
数据与经验	SQLite, 本地经验库接口	Python
测试	pytest, ROS 2 launch/script 验证	Python / Bash

目录结构

Windows 端工程：

E:\Project\ResilienceClient2
├── AppScope/                         # OpenHarmony 应用级配置
├── entry/                            # OpenHarmony entry 模块
│   └── src/main/ets/pages/Index.ets  # ResilienceClient 主页面
├── resilience_engine/                # FastAPI 韧性决策引擎
│   ├── anomaly/                      # 规则异常检测
│   ├── api/                          # HTTP API 路由
│   ├── attribution/                  # 错误归因
│   ├── experience/                   # 经验沉淀与复用
│   ├── models/                       # Pydantic 数据模型
│   ├── perception/                   # 外部环境感知接口
│   ├── policy/                       # 策略选择与安全校验
│   ├── recovery/                     # 任务结果验证与恢复记录
│   ├── safety/                       # 运行时安全约束
│   └── storage/                      # 内存/SQLite 存储
├── tests/                            # 后端 API 与模块测试
├── docs/                             # 阶段设计、接口和执行文档
├── resilience_server.py              # FastAPI app 导出入口
├── run_server.py                     # 后端启动脚本
└── requirements.txt                  # Python 依赖

WSL2 ROS 2 工作空间：

/home/ojs/ResilienceClient2/ros2_ws
└── src/oh_resilience_sim
    ├── oh_resilience_sim/
    │   ├── fault_injection/          # 故障注入与开放环境场景
    │   ├── recovery_execution/       # ROS/Nav2 恢复执行
    │   ├── ros_bridge/               # ROS 2 与 FastAPI 桥接
    │   └── state_collector/          # 仿真状态采集
    ├── config/                       # ROS 2 参数配置
    ├── launch/                       # ROS 2 launch 文件
    ├── scripts/                      # 验证与启动脚本
    └── docs/                         # ROS 2 阶段文档

环境要求

Windows 侧

• Windows 10/11
• Python 3.10+
• DevEco Studio
• OpenHarmony SDK
• OpenHarmony 模拟器或本地可运行设备

WSL2 / Ubuntu 侧

• WSL2 Ubuntu
• ROS 2 Jazzy
• Gazebo
• TurtleBot3 Gazebo / TurtleBot3 Navigation2
• Nav2

本项目当前在 WSL2 Ubuntu + ROS 2 Jazzy 环境下开发验证。

后端运行说明

在 Windows PowerShell 中进入工程目录：

cd E:\Project\ResilienceClient2

安装 Python 依赖：

pip install -r requirements.txt

启动 FastAPI 后端：

python run_server.py

默认监听：

http://127.0.0.1:8088

健康检查：

http://127.0.0.1:8088/health

状态接口：

http://127.0.0.1:8088/api/resilience/state

也可以使用 uvicorn 直接启动：

python -m uvicorn resilience_server:app --host 0.0.0.0 --port 8088 --reload

OpenHarmony App 运行说明

1. 使用 DevEco Studio 打开工程：

E:\Project\ResilienceClient2

2. 选择 entry 模块。

3. 选择 OpenHarmony 模拟器。

4. 执行：

Build -> Make Project
Run -> Run entry

5. App 启动后确认页面中的 Backend URL：

http://10.0.2.2:8088

说明：10.0.2.2 通常用于模拟器访问 Windows 主机。如果模拟器无法访问该地址，可改为 Windows 主机局域网 IP，例如：

http://192.168.x.x:8088

ROS 2 / Gazebo 仿真运行说明

进入 WSL2 Ubuntu：

wsl

进入 ROS 2 工作空间：

cd /home/ojs/ResilienceClient2/ros2_ws
source /opt/ros/jazzy/setup.bash

构建 ROS 2 包：

colcon build --symlink-install --packages-select oh_resilience_sim
source install/setup.bash

检查 TurtleBot3 / Nav2 依赖：

./src/oh_resilience_sim/scripts/check_stage03_step02_deps.sh
./src/oh_resilience_sim/scripts/check_stage03_step03_nav2.sh

启动 TurtleBot3 Gazebo：

./src/oh_resilience_sim/scripts/start_turtlebot3_gazebo.sh

启动 Nav2：

./src/oh_resilience_sim/scripts/start_turtlebot3_nav2.sh

发布初始位姿：

./src/oh_resilience_sim/scripts/publish_initial_pose.sh

发送导航目标：

./src/oh_resilience_sim/scripts/send_nav2_goal.sh 1.5 0.5 0.0 1.0

ROS 2 与 FastAPI 联动运行

启动 ROS-FastAPI 桥接节点：

ros2 launch oh_resilience_sim ros_bridge.launch.py

启动状态采集节点：

./src/oh_resilience_sim/scripts/start_state_collector.sh

启动恢复执行节点，默认 mock 模式：

./src/oh_resilience_sim/scripts/start_recovery_executor.sh

启动真实 Nav2 恢复模式：

./src/oh_resilience_sim/scripts/start_recovery_executor.sh mock_execution:=false

检查真实 Nav2 接口：

./src/oh_resilience_sim/scripts/check_real_nav2_interfaces.sh

故障注入与开放环境场景

单次故障注入：

./src/oh_resilience_sim/scripts/inject_navigation_timeout.sh
./src/oh_resilience_sim/scripts/inject_sensor_delay.sh
./src/oh_resilience_sim/scripts/inject_sensor_noise.sh

手动发布故障事件：

./src/oh_resilience_sim/scripts/inject_fault.sh NAVIGATION_TIMEOUT HIGH

查看内置开放环境场景：

./src/oh_resilience_sim/scripts/list_open_environment_scenarios.sh

运行动态障碍组合场景：

./src/oh_resilience_sim/scripts/run_dynamic_obstacle_scenario.sh 4.0

运行指定开放环境场景：

./src/oh_resilience_sim/scripts/run_open_environment_scenario.sh dynamic_obstacle_navigation 4.0
./src/oh_resilience_sim/scripts/run_open_environment_scenario.sh sensor_drift_navigation 3.0
./src/oh_resilience_sim/scripts/run_open_environment_scenario.sh communication_and_resource_pressure 3.0
./src/oh_resilience_sim/scripts/run_open_environment_scenario.sh safety_risk_navigation 3.0

真实 Nav2 恢复动作验证

启动恢复执行节点真实模式：

./src/oh_resilience_sim/scripts/start_recovery_executor.sh mock_execution:=false

手动触发安全停止：

./src/oh_resilience_sim/scripts/test_real_nav2_recovery.sh SAFE_STOP EVT-SAFE-STOP

手动触发 costmap 清理：

./src/oh_resilience_sim/scripts/test_real_nav2_recovery.sh CLEAR_COSTMAP EVT-CLEAR-COSTMAP

手动触发全局重规划：

./src/oh_resilience_sim/scripts/test_real_nav2_recovery.sh TRIGGER_GLOBAL_REPLAN EVT-REPLAN 1.5 0.5 0.0 1.0

查看恢复结果：

ros2 topic echo /recovery_result

典型验证流程

1. OpenHarmony 与后端通信闭环

1. 启动 FastAPI 后端。
2. 在 DevEco Studio 中运行 ResilienceClient。
3. 点击 Refresh State。
4. 点击 Simulate Navigation Timeout。
5. 页面应显示异常等级、推荐动作、恢复阶段和端侧状态机变化。
6. 点击 Report Recovery Success 或 Report Recovery Failed。
7. 页面 Evidence Chain 应记录 EVENT_SENT、POLICY_SELECTED、STATE_CHANGED、RECOVERY_REPORTED。

2. ROS 2 仿真闭环

1. 启动 FastAPI 后端。
2. 启动 ros_bridge。
3. 启动 ros_recovery_executor。
4. 运行开放环境故障场景。
5. 观察 /fault_event、/recovery_action、/recovery_result。
6. 确认后端状态和 OpenHarmony 页面同步变化。

3. 真实 Nav2 恢复动作闭环

1. 启动 Gazebo。
2. 启动 Nav2。
3. 发布初始位姿。
4. 启动 ros_recovery_executor mock_execution:=false。
5. 触发 TRIGGER_GLOBAL_REPLAN 或 RECOVER_NAVIGATION。
6. 检查 costmap 清理、目标重发和 /recovery_result。

常用 API

方法	路径	说明
GET	/health	后端健康检查
GET	/api/resilience/state	查询当前韧性状态
POST	/api/client/event	上报端侧异常事件
GET	/api/recovery/action	查询最新恢复动作
POST	/api/recovery/result	上报恢复执行结果
GET	/api/recovery/results	查询恢复结果历史

示例：上报导航超时事件。

Invoke-RestMethod `
  -Method POST `
  -Uri http://127.0.0.1:8088/api/client/event `
  -ContentType 'application/json' `
  -Body '{"source":"manual-test","eventType":"NAVIGATION_TIMEOUT","severity":"HIGH","message":"Navigation timeout in dynamic obstacle scenario."}'

测试

在 Windows PowerShell 中执行：

cd E:\Project\ResilienceClient2
pytest

如果只验证基础 API：

pytest tests/test_stage2_api_flow.py tests/test_recovery_result_api.py

已实现阶段

• 阶段 1：OpenHarmony Agent 与 FastAPI 通信。
• 阶段 2：规则异常检测与策略引擎。
• 阶段 3：ROS 2 / Gazebo / Nav2 仿真接入。
• 阶段 3.5：真实 Nav2 恢复动作、复杂开放环境场景、端侧状态机、端侧证据链。
• 扩展能力：任务结果验证、安全约束、错误归因与经验沉淀相关模块已开始纳入后端工程。

注意事项

• 当前项目采用无硬件仿真验证路线，不需要真实机器人设备。
• OpenHarmony 模拟器访问 Windows 后端时，通常使用 http://10.0.2.2:8088。
• data/*.db、__pycache__/、.venv/、oh_modules/、.hvigor/ 等本地运行产物不应提交到远端仓库。
• ROS 2 工作空间位于 WSL2 中，若需要上传到同一远端仓库，建议将 ros2_ws/src/oh_resilience_sim 同步到仓库目录后提交源码、配置、脚本和文档。

参考文档

更多设计和执行细节见：

docs/工程说明文档.md
docs/软件设计文档_SDD.md
docs/stage03_5_oh_client_state_machine_design.md
docs/stage03_5_oh_client_evidence_chain_design.md
docs/stage03_5_real_nav2_recovery_design.md
/home/ojs/ResilienceClient2/ros2_ws/src/oh_resilience_sim/docs/