核心开发指南
概述 / Overview
本页是 MDCS 核心平台开发的总入口，面向 修改 MDCS 本身的开发者（添加新的 SLAM 后端、扩展 LadderLogic、修改 DPS 调度算法等）。完整离线副本见 `D:\src\cookbook\HOW_TO_DEV_CORE.md`。
This is the hub for MDCS core platform development — for developers modifying MDCS itself (adding a new SLAM backend, extending LadderLogic, modifying DPS scheduling, etc.). Offline mirror: `D:\src\cookbook\HOW_TO_DEV_CORE.md`.
1. 仓库布局 / Repo layout
7 个并列仓库，按依赖自底向上构建： 7 sibling repositories, built bottom-up by dependency:
| 仓库 / Repo | 产物 / Output | 作用 / Role |
|---|---|---|
| `D:\src\Fundamentals\` | `FundamentalLib.dll`, `FundamentalLib2.dll`, `LessokajiProtect.dll` | 通用类型 + IPC + 日志 + 许可 |
| `D:\src\LessokajiWeaver\` | `LessokajiWeaver.Fody.dll` | 编译期 IL 注入 |
| `D:\src\CycleGUI\` | `CycleGUI.dll`, `libVRender.dll`（C++） | 懒协程 UI 框架 |
| `D:\src\M2\` | `MedullaCore.dll`, `OfficialPlugins/*.dll` | 硬件抽象内核 + 一方插件 |
| `D:\src\Detour\` | `Detour.exe`, `DetourLite.exe`, `DetourCore.dll` | 定位系统 |
| `D:\src\Clumsy\` | `ClumsyCore.dll`, `ClumsyDance.dll` | 车载自动驾驶 |
| `D:\src\Simple\` | `SimpleCore.dll`, `SimpleComposer.exe` | 车队管理 |
详细的内核子页： Per-subsystem deep-dive pages:
- MDCS仓库布局与构建链
- DObject共享内存协议 — Fundamentals 内核
- CycleGUI — UI 框架
- Medulla软件架构 — 加载器 + 脚本引擎
- LadderLogic框架 — 周期循环
- Detour软件架构 — 定位流水线
- DriveTask调度循环 — Movement 宿主
- SimpleAgvInterface Queue机制 — 任务流水线
- Simple软件架构 — 调度内核
- 调度内核运行原理 — DPS + 包络 + 可达性
- DPS调度算法详解 — 死锁规避算法
- LessokajiWeaver编译后处理工具 — Fody 织入
- MDCS跨切面约定 — 命名 / 线程 / 错误处理 / 版本
- MDCS平台发布流程 — Release 流程
2. 构建工具链 / Build chain
顺序 / Order
1. LessokajiWeaver — 构建时依赖 / build-time dep 2. Fundamentals — 用 Weaver / uses Weaver 3. CycleGUI — 用 Fundamentals + 需要 `libVRender` C++ 先构建 4. M2 / MedullaCore — 用 Fundamentals + CycleGUI 5. M2 / OfficialPlugins/* — 用 MedullaCore 6. Detour / DetourCore 7. Clumsy / ClumsyCore，然后 ClumsyDance 8. Simple / SimpleCore，然后 SimpleComposer
引用程序集分发 / Reference-assembly distribution
每个核心 DLL 都同时产生一个 引用程序集（`Ref<Name>.dll`），通过 [refasmer](https://github.com/JetBrains/Refasmer) 生成。插件 csproj 引用 `Ref<Name>.dll`，不引用 impl，所以： Each core DLL also emits a reference-only assembly (`Ref<Name>.dll`) via [refasmer]. Plugins reference the `Ref` assembly, not the impl. Therefore:
- 插件构建不会拉入 Costura 织入的传递依赖。
- 公共 API 由 `Ref` assembly 固定 —— `internal` 成员对插件不可见。
【注意】 改动 `MedullaCore` 公共面后必须重新构建 impl + ref；插件用旧 `Ref` 构建后会静默缺失新成员。
After any change to a `MedullaCore` public surface, rebuild both impl and ref assemblies; plugins built against the old ref will silently miss new members.
Costura.Fody 胖 DLL
插件输出是单 `.dll`（所有依赖嵌入为 base64 资源）。核心 DLL 自身 不要加 Costura.Fody，因为多个插件都要共载它们。
Plugin outputs are fat DLLs (all deps embedded). Core DLLs themselves should not use Costura.Fody since multiple plugins co-load them.
LessokajiWeaver IL 注入
- `[AsInitParam] / [AsUpperIO] / [AsLowerIO]` → 字段重写为同步到 DObject 的 property
- `[ReplaceWithCompileInfo]` → 编译时戳 + git 哈希
- `[Translatable] / [T(zh=, en=)]` → getter 按 `CultureInfo.CurrentUICulture` 分派
详见 LessokajiWeaver编译后处理工具 与 如何使用LessokajiWeaver的多语言功能。
3. 跨切面约定 / Cross-cutting conventions
命名 / Naming
- 插件入口类: `MainIOObject`（精确匹配）。
- 引用程序集: `Ref<Name>.dll`。
- DObject 槽名: `<Producer><Tag>`（如 `MedullaCartLowerIO<tag>`）。
线程 / Threading
- `LadderLogic` 每个 `[UseLadderLogic]` 类自己的线程。
- `DriveTask` 每个 Movement 自己的线程。
- DObject `Wait()` 阻塞；要并行多个就用 worker 线程。
- CycleGUI `Draw*` 调用从任意线程都安全。
错误处理三层 / 3-layer error model
- 插件级 `[UseLadderLogic(resume=true)]` —— 捕获并重启循环（默认）。
- 进程级 `Hedingben.ToastText` —— UI 弹窗。
- 看门狗级（Wawa）—— 进程崩了由 Wawa 重启。
不要同时做三层；选合适的级别。
Don't do all three — pick the right level.
版本助记词 / Version mnemonics
每次修改编译产物，AssemblyInformationalVersion 加一个单词（如 `1.4.0+kindling`）。便于在调试时区分两个数字相同的二进制。
Each modification adds a single mnemonic word (e.g. `1.4.0+kindling`) to AssemblyInformationalVersion. Lets you disambiguate two binaries with the same number in the field.
4. 测试 / Tests
- 单元测试稀疏；机器人代码本质上靠 集成测试。
- `D:\src\Fundamentals\Test\` 覆盖 DObject + DLog（最关键）。
- 多数"测试"通过 `[MovementTest]` / `[IOObjectUtility]` 在 UI 上点按钮跑。
- 修改 `DObject` 后必跑 Fundamentals 单元测试 —— IPC bug 是灾难性的。
- 修改任一 `*Core` 后跑模拟车 SimpleComposer 集成测试。
5. 发布 / Release
见 MDCS平台发布流程。