查看“插件测试与发布”的源代码

<languages/>

== 概述 / 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 控制台后，可以直接 [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd]] 命令：
After starting the Medulla console, use script commands:

<syntaxhighlight lang="text">
io load plugins/yourname.dll
your = io init <TypeName> <args>

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

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

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

=== 雷达插件可视化 / 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 ===
{| class="wikitable"
! 检查 / 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 测试 ：
<syntaxhighlight lang="bash">
curl -X POST http://localhost:9050/api/dispatch \
  -H "Content-Type: application/json" \
  -d '{"car": "TestCar", "target": "siteA", "mission_type": "Go"}'
</syntaxhighlight>

== 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 [[Special:MyLanguage/使用手册 - 数据录制与回放手册|使用手册 - 数据录制与回放手册]]。

== 5. 版本与助记词 / Version + mnemonic ==
按项目惯例 ：
Project convention:

<syntaxhighlight lang="xml">
<AssemblyInformationalVersion>1.4.0+kindling</AssemblyInformationalVersion>
</syntaxhighlight>

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

或用 `[ReplaceWithCompileInfo]` —— LessokajiWeaver 注入时间戳 + git hash 到 static string 字段（[[Special:MyLanguage/LessokajiWeaver编译后处理工具|详情]]）。
Alternative: `[ReplaceWithCompileInfo]` injects compile timestamp + git hash automatically.

== 6. 打包 / Packaging ==
=== Release 构建 / Release build ===
<syntaxhighlight lang="bash">
dotnet publish -c Release -f net6.0
</syntaxhighlight>

输出在 `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：

<syntaxhighlight lang="text">
io load plugins/yourname.dll
your = io init ...
</syntaxhighlight>

如果你 ''忘了 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 ===
<pre>
your-plugin-1.4.0+kindling.zip
├── your-plugin.dll
├── README.md            # 简短说明
├── CHANGELOG.md         # 本版本变更
├── INSTALL.txt          # 部署 startup.iocmd 片段
└── (optional) docs/     # 详细使用文档
</pre>

== 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 ==
{| class="wikitable"
! 你的插件目标 / 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:

# 拉源 → 单元测试（如果有）→ 构建 Debug 与 Release。
# Lint csproj：检查 ''都引用了 `Ref<Name>.dll`'' 而不是 impl DLL，避免误打包。
# 自动版本号注入（git tag → AssemblyInformationalVersion）。
# 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 ==
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/插件开发清单|插件开发清单]]
* [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd脚本语法]]
* [[Special:MyLanguage/使用手册 - 数据录制与回放手册|数据录制与回放手册]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]