查看“核心开发指南”的源代码

<languages/>

== 概述 / 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:

{| class="wikitable"
! 仓库 / 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:

* [[Special:MyLanguage/MDCS仓库布局与构建链|MDCS仓库布局与构建链]]
* [[Special:MyLanguage/DObject共享内存协议|DObject共享内存协议]] — Fundamentals 内核
* [[Special:MyLanguage/CycleGUI|CycleGUI]] — UI 框架
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]] — 加载器 + 脚本引擎
* [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]] — 周期循环
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]] — 定位流水线
* [[Special:MyLanguage/DriveTask调度循环|DriveTask调度循环]] — Movement 宿主
* [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]] — 任务流水线
* [[Special:MyLanguage/Simple软件架构|Simple软件架构]] — 调度内核
* [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]] — DPS + 包络 + 可达性
* [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]] — 死锁规避算法
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]] — Fody 织入
* [[Special:MyLanguage/MDCS跨切面约定|MDCS跨切面约定]] — 命名 / 线程 / 错误处理 / 版本
* [[Special:MyLanguage/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` 构建后会静默缺失新成员。<br>
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` 分派

详见 [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]] 与 [[Special:MyLanguage/如何使用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 重启。

不要同时做三层；选合适的级别。<br>
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 ==
见 [[Special:MyLanguage/MDCS平台发布流程|MDCS平台发布流程]]。

== 6. 关联文档 / See also ==
* [[Special:MyLanguage/操作指南|操作指南]] — 运维者视角
* [[Special:MyLanguage/插件开发指南|插件开发指南]] — 插件作者视角
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]] — 三层模型

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