@wink-ai/unisim

Wink-AI 统一物理仿真引擎
面向嵌入式 Web / WASM 的全通道物理信号仿真、双模执行引擎与场景契约驱动基建。

English | 简体中文

🌟 核心主要功能 (Key Features)

@wink-ai/unisim 为嵌入式物联网、机器人与图形微应用提供无硬件依赖的高保真、可回放、毫秒级自动化仿真能力：

1. ⚡ 微秒级高保真虚拟时钟 (VirtualClock)

• 100% 确定性推演：彻底摆脱物理硬件时序波动和开发板依赖，保证任何环境下的测试结果绝对可复现。
• 微秒级时间游标：支持 deferUs、时钟步进与离散时间跳时（DES），实现高效的时间轴控制。

2. 🔌 全通道物理信号仿真 (Multi-Channel Simulation)

• GPIO 引脚：支持高低电平、高阻态（Hi-Z）、三态仲裁、硬件按键接触消抖（Bounce）与微秒级自定义数字波形（Waveform）。
• PWM 脉宽调制：高精度占空比捕获、频率计算与动态波形特征断言。
• 通信总线 (Bus)：
  • UART：全双工串口数据流收发、波特率匹配与协议帧解析。
  • I2C：主从机握手、寄存器读写状态机模拟。
  • SPI：高速同步总线时序与数据流传输。
• ADC 模拟信号：模拟电压/传感器输入转换，内置斜率曲线（Ramp）、周期波形（Wave）、随机噪声（Noise）等物理生成器。
• 显示屏与帧缓冲 (FrameBuffer)：支持单色 OLED（SSD1306）与彩色 LCD 实时帧提取、视觉有效像素统计与自动化断言。
• 闭环物理系统 (PLANT_LOOP)：支持热力学、动力学等一阶/二阶闭环物理模型实时仿真交互。

3. 🏎️ 统一双模执行引擎 (Dual Execution Engines)

• Headless 极速模式 (--mode=headless)：
  • 纯内存运行，单个场景仅需 5ms ~ 100ms，专为 CI/CD 自动化测试与固件协议门禁打造。
• Browser 真实回放与录屏模式 (--mode=browser)：
  • 挂载 2D 画布真实外观与 UI 覆盖层，支持交互调试，自动输出 WebM 录屏视频 与 Canvas 状态截图。

4. 📜 声明式场景描述语言 (Scenario DSL v2.0)

• 基于 JSON 声明激励注入、时序等待与断言，支持直观的相对时间算术（如 timeUs: "+100ms"）。
• 丰富的匹配器能力：严格等值、容差匹配（$near）、闭区间范围（$between）、正则匹配（$regex）与十六进制掩码（$hexMask）。
• 原生 VS Code 智能补全与实时红波浪线语法校验。

5. 🧩 开箱即用的丰富外设生态 (Builtin Peripherals)

• 内置按键（Button）、LED 指示灯、单色 OLED 屏幕（SSD1306）、SG90 舵机、HC-SR04 超声波雷达、电机驱动等常用外设插件。
• 完善的外设 SDK，支持轻松扩展私有传感器与执行器。

🚀 快速上手 (Quick Start)

安装

# 使用 npm / bun / pnpm 安装
npm install @wink-ai/unisim
# 或
bun add @wink-ai/unisim

CLI 命令行工具 (winksim)

安装后可直接使用 winksim 命令行工具调度与执行仿真：

# 1. 运行指定应用的仿真测试场景（Headless 极速模式）
winksim run --app=./my-app --scenarios=./tests/smoke.scenario.json

# 2. 浏览器回放并自动录制视频产物
winksim run --app=./my-app --mode=browser --record --artifacts=./artifacts

# 3. 过滤执行特定用例并输出详细日志
winksim run --filter=avoidance --verbose

# 4. 生成 CI 标准 JUnit 与 JSON 测试报告
winksim run --reporter=spec --reporter=junit --reporter=json

# 5. 快速生成一个新的测试场景模板
winksim init my_scenario.scenario.json

💡 场景用例示例 (*.scenario.json)

编写一个测试按键触发电机调速的仿真用例：

{
  "$schema": "https://wink-ai.org/schemas/unisim/scenario.schema.json",
  "header": {
    "version": "2.0",
    "name": "button_pwm_speed_control",
    "templateId": "tpl_fan_speed",
    "description": "按下按键后，风扇 PWM 占空比在 500ms 内提升至 75%",
    "accuracyMode": "timing",
    "timeoutUs": "5000ms"
  },
  "steps": [
    {
      "type": "INPUT_PIN",
      "mode": "level",
      "timeUs": "100ms",
      "pin": "gpio:0",
      "level": "LOW",
      "description": "按下按键（低电平有效）"
    },
    {
      "type": "ASSERT_POINT",
      "timeUs": "+500ms",
      "target": "pwm:0",
      "matcher": { "$near": { "target": 75, "tolerance": 5 } },
      "description": "断言 PWM 占空比稳定在 75% 左右"
    }
  ]
}

📄 License

MIT License © Wink-AI Team