插件测试与发布

来自MDCS wiki2
跳到导航 跳到搜索


概述 / Overview

本页讲 MDCS 插件的 测试 + 打包 + 发布流程 —— 从 bench-test 单个插件，到把插件做成可分发的版本。

This page covers MDCS plugin testing + packaging + release — from bench-testing a single plugin to packaging a deliverable version.

1. Bench-test Medulla 插件

控制台测试 / Console testing

启动 Medulla 控制台后，可以直接 startup.iocmd 命令： After starting the Medulla console, use script commands: 

io load plugins/yourname.dll
your = io init <TypeName> <args>

# 读字段 / read field
your.<field>

# 写字段 / write field
your.<field> = 100

# 调方法 / invoke a [IOObjectUtility]
your <UtilityMethod>

雷达插件可视化 / Lidar visualisation

Medulla 的 `LidarTypes/MainIOObject` 暴露一个 `[IOObjectUtility]` 用于显示 2D 点云。加载完雷达后点这个按钮 ：

  • 确认 `frame` 单调递增。
  • 点云形状符合预期（前方、左右、距离合理）。
  • 反光强度归一化后（`ReflexRange`）反光板明显偏红。

Lidar plugin: confirm `frame` increments monotonically, geometry matches expectation, reflectors visibly red after `ReflexRange` normalisation.

Cart 插件验证 / Cart plugin validation

检查 / Check 方法 / Method
`Init()` 不抛 看 `Hedingben` 是否有红色 toast
LadderLogic 启动 `[IOObjectMonitor]` 看一个 iteration 计数器
`[AsUpperIO]` 设置生效 `your.vCmd = 100`，观察硬件电机
`[AsLowerIO]` 读取正常 `your.batteryPercent` 应给真实值
`[UseLadderLogic(resume=true)]` 验证 故意制造异常，看是否自动重启循环 + Hedingben toast

2. Bench-test Movement

`[MovementTest]` 属性在 Clumsy 测试 UI 自动注册一个按钮。要求 ：

  • 车在静止 / 仿真环境中
  • 没有 任何其它 Movement 在跑

`[MovementTest]` registers a button automatically. Requires the vehicle to be still / simulated, with no other Movement running.

按下按钮 → Movement 开始；UI 实时显示驱动指令；异常时显示 stack trace。 Pressing the button starts the Movement; UI shows live drive commands; exception → stack trace surfaced.

3. Bench-test SimpleComposer 插件

仿真车 / Virtual vehicle

SimpleComposer 内置 仿真车类型（不需要真硬件） ：

  • 添加 `DummyCar`，配置你的 `[CarType]` 关联。
  • 发派任务从 UI 派；运动学按理想模型计算。

A built-in virtual car type lets you test without real hardware. Configure a `DummyCar` bound to your `[CarType]`; missions dispatched from the UI; kinematics calculated ideally.

Trace 面板 / Trace panel

观察 ：

  • 每辆车的 `Queue` 行执行时间线
  • 锁的获取 / 释放序列
  • 任务 status 状态转换（`Programming → Forecasted → Queued → Running → Finished`）
  • 异常路径

Inspect: per-car Queue row timeline, lock acquire/release sequence, status transitions, exception paths.

HTTP API 测试 / API testing

SimpleComposer 的 Nancy API 可以用 curl / Postman 测试 ： 

curl -X POST http://localhost:9050/api/dispatch \
  -H "Content-Type: application/json" \
  -d '{"car": "TestCar", "target": "siteA", "mission_type": "Go"}'

4. 录制与回放 / Recording & replay

DObject 自动 录制（每槽可独立开关 `dobj.Recording = true`）写 `.dorec` 文件到 `medulla/recordings/`。

DObject auto-recording (per-slot `Recording = true` flag) writes `.dorec` files into `medulla/recordings/`.

回放工具用于：

  • 重现现场 bug（同一序列输入 → 相同输出）
  • 离线对比 SLAM 算法（同一传感器流跑多个版本）
  • 培训（不用真车）

Replay flows are documented at 使用手册 - 数据录制与回放手册。

5. 版本与助记词 / Version + mnemonic

按项目惯例 ： Project convention: 

<AssemblyInformationalVersion>1.4.0+kindling</AssemblyInformationalVersion>

Major.Minor.Patch + 单词助记词。每次改动换助记词。 Bump a fresh single-word mnemonic on each modification.

或用 `[ReplaceWithCompileInfo]` —— LessokajiWeaver 注入时间戳 + git hash 到 static string 字段（详情）。 Alternative: `[ReplaceWithCompileInfo]` injects compile timestamp + git hash automatically.

6. 打包 / Packaging

Release 构建 / Release build

dotnet publish -c Release -f net6.0

输出在 `bin/Release/net6.0/publish/`。Costura.Fody 已经把依赖打到单 DLL，所以只需要 ``<plugin>.dll`。 Output at `bin/Release/net6.0/publish/`. Costura.Fody has embedded deps; only one DLL needed.

测试加载 / Test load

关键 ：在一个 干净的 Medulla 控制台（没有其它插件）加载新 DLL： 

io load plugins/yourname.dll
your = io init ...

如果你 忘了 Costura，其它插件可能 碰巧加载了你需要的 DLL，但生产环境干净启动时会出错。这个测试能立刻发现。

If you forgot Costura, other plugins may incidentally provide the dep, but a clean production install will fail. This test surfaces it instantly.

Release artefact / Release zip

your-plugin-1.4.0+kindling.zip
├── your-plugin.dll
├── README.md            # 简短说明
├── CHANGELOG.md         # 本版本变更
├── INSTALL.txt          # 部署 startup.iocmd 片段
└── (optional) docs/     # 详细使用文档

7. 发布 / Release

  • 内部分发 / Internal: 上传到 `https://dl.lessokaji.com`（按客户分目录）。
  • 授权门 / Auth gate: 通过 `auth.lessokaji.com` 控制谁能下载。
  • Wiki 发布说明 / Wiki release notes: 更新对应 wiki 页（如 `Detour版本发布记录`）。
  • DEV_LOG: 在仓库 `DEV_LOG.md` 加一条记录，含 助记词与变更摘要。

8. 兼容性矩阵 / Compatibility matrix

你的插件目标 / Your plugin's target 兼容 / Compatible with
RefMedullaCore 1.x Medulla 1.x runtime
RefMedullaCore 2.x Medulla 2.x runtime（即当前 M2，默认）
RefClumsyCore 1.x Clumsy 1.x
RefClumsyCore 2.x Clumsy 2.x（当前）

在 csproj 里 pin 一个主版本，在 CHANGELOG 里写清次版本要求。 Pin a major version in csproj; document minor-version requirements in CHANGELOG.

9. 持续集成 / CI

推荐流水线 ： Recommended pipeline:

  1. 拉源 → 单元测试（如果有）→ 构建 Debug 与 Release。
  2. Lint csproj：检查 都引用了 `Ref<Name>.dll` 而不是 impl DLL，避免误打包。
  3. 自动版本号注入（git tag → AssemblyInformationalVersion）。
  4. Release zip 自动生成 + 上传到内部仓库。

10. 常见错误清单 / Pre-release checklist

  • [ ] 测试加载 (干净环境)
  • [ ] `[AsUpperIO]` / `[AsLowerIO]` 字段不是 readonly
  • [ ] `Init()` 不抛异常
  • [ ] LadderLogic `resume = true` 时也手动捕异常 + 写 Lower IO `eStop = true`
  • [ ] Costura.Fody 在 FodyWeavers.xml
  • [ ] AssemblyInformationalVersion 含助记词
  • [ ] CHANGELOG.md 写了本版变更
  • [ ] startup.iocmd 示例片段在 INSTALL.txt
  • [ ] 在仿真车里跑过完整任务

相关页面 / See also

取自“https://wiki2.lessokaji.com/index.php?title=插件测试与发布&oldid=1049”