LessokajiWeaver编译后处理工具

概述 / Overview

LessokajiWeaver 是 MDCS 用到的 编译后处理工具链（基于 Fody）。它在 C# 程序集编译完成后做 IL 注入，自动生成 字段代理类、属性序列化代码、反射加速等基础设施代码，让插件作者只需写少量声明性属性，剩下的"管道"由 Weaver 自动织入。

LessokajiWeaver is MDCS's post-compile IL-weaving toolchain (Fody-based). It runs after C# assembly compilation and injects IL to generate field-proxy classes, property serialisation, reflection accelerators, etc. Plugin authors write a few declarative attributes; the plumbing is woven in automatically.

主要场景 / Main scenarios

场景 / Scenario	Weaver 做的 / What Weaver does
Medulla `[AsUpperIO]` / `[AsLowerIO]` 字段	生成代理 setter / getter，自动同步到 DObject
Medulla `[AsInitParam]`	生成 JSON 序列化代码，绑定到启动配置加载
Medulla `[IOObjectMonitor]`	注册到监控面板 + Web API
CycleGUI `[Cyclic]` 协程方法	自动包装为 IEnumerable<Cycle> 安全宿主
Clumsy `[MovementTest]`	注册到测试 UI 面板
多语言（i18n）字符串字段	生成查表逻辑（见自动 I18N）

工作流程 / Pipeline

 开发者 .cs → csc 编译 → .dll
                             │
                             ▼
               LessokajiWeaver.Fody (post-build)
                             │
                             ▼
                        织入后的 .dll
                             │
                             ▼
                  Medulla / Clumsy 运行时加载

工程引用方式（已由 MDCS-plugin-helper 模板自动配置）：

In a plugin's .csproj (auto-configured by the plugin-helper template):

<ItemGroup>
  <PackageReference Include="Fody" Version="6.x" />
  <Reference Include="LessokajiWeaver.Fody">
    <HintPath>..\tools\LessokajiWeaver.Fody.dll</HintPath>
  </Reference>
  <Reference Include="LessokajiWeaverUtilities">
    <HintPath>..\tools\LessokajiWeaverUtilities.dll</HintPath>
  </Reference>
</ItemGroup>

`FodyWeavers.xml` 在工程根目录：

<Weavers>
  <LessokajiWeaver/>
</Weavers>

为什么用 Weaver / Why weave

不用 Weaver 也能用反射做同样的事，但每次访问字段都付反射开销（~100x getter）。Weaver 在编译期把反射调用 变成普通 IL，运行时零开销：

Without Weaver you'd use reflection at runtime, paying ~100× cost per access. Weaver moves the reflection to compile-time, generating direct IL with zero runtime overhead:

// 开发者写：
[AsUpperIO]
public float vCmd;

// 编译后 Weaver 注入相当于：
private float _vCmd;
public float vCmd
{
    get => _vCmd;
    set
    {
        _vCmd = value;
        IOSync.PostToDObject(this, "vCmd", value);  // 自动 IPC
    }
}

调试 / Debugging

织入失败：检查 `bin\<config>\` 下是否有 `FodyWeavers.xml` 编译报错；通常是属性用法错误（如把 `[AsUpperIO]` 加在 readonly 字段上）。
织入产物可视化：用 ILSpy / dnSpy 打开织入后的 dll，查看 setter / getter 注入逻辑。
性能 / Performance: Weaver 不引入额外运行时依赖；增加的体积通常 < 5%。

兼容性 / Compatibility

.NET Framework 4.6.2+ / .NET 6+
必须用 Release 模式发布插件（Weaver 在 Debug 也运行，但 Debug 会保留更多调试符号导致体积偏大）。
与 AOT 编译不兼容（IL 注入依赖 JIT）。

与 LessokajiWeaverUtilities 的关系 / Utilities

`LessokajiWeaverUtilities.dll` 是 Weaver 注入代码运行时依赖的小库（attribute 定义 + 工具方法）。插件 csproj 必须引用，但开发者一般不直接调用。

`LessokajiWeaverUtilities.dll` is the runtime support library (attribute definitions + helpers). Plugin csproj must reference it but developers rarely call into it directly.