笔记审查报告（Review Report）

审查对象：01-Index.md ~ 08-Comparison-with-Bevy-ECS.md（8 篇，约 250 KB） 对照基准：E:/code/_Codex/unity-project/Magic Game Harness，main 分支 1fe2010，工作区干净 审查方式：逐文件通读全部产品源码（2 803 行）+ 测试源码（3 306 行）+ 15 个 .asmdef + Packages/manifest.json + docs/superpowers/specs/2026-08-19-modular-game-harness-design.md（1 487 行）+ VContainer 1.19.0 包内源码 审查日期：2026-08-21

0. 总评#

先说结论，避免被下面一长串 issue 带偏印象：

这套笔记的骨架是对的，深度也在线。 03/04/05 三篇对 Session 状态机、ModApi 契约边界、架构守门测试的解读，绝大部分是直接读源码得出的，引用的代码片段与真实代码逐字一致，推理链条也站得住。特别是：

• 03 §4.4 对 “superseded start” 竞态的复原（scopeFactory.Create 之后必须 re-check state == Starting），与 SessionLifecycleConcurrencyTests.Stop_requested_while_starting_reaches_one_terminal_state_without_leaking_a_scope 的意图完全吻合；
• 04 §2 对 ModApiShapeTests 的引用逐字准确；
• 05 全篇对两个架构测试文件的解读几乎无误，是 8 篇里事实密度最高、错误最少的一篇。

问题集中在三类，且有明确的模式：

其中 B 类必须修正：06 §1.4 里那段 context.RegisterCapability<IGameRules>(rules) 示例，恰好被 PublicApiSurfaceTests.Module_context_is_not_an_unrestricted_service_locator 明确禁止（该测试断言 IModuleContext 上不得存在任何泛型方法）。如果照着笔记去实现 Context Runtime，第一件事就是把自己的架构测试搞红。

下面逐条给出证据与修正。已在原笔记中就地修改的条目标注 ✅；仅在本报告中记录、原文保留的标注 📝。

1. A 类：统计口径失真#

1.1 全项目真实统计（本报告的基准数据）#

15 个 .asmdef：Assets/GameFramework 下 10 个产品程序集，Assets/Tests 下 3 个测试程序集，Packages/com.mimizh.game-mod-sdk 下 2 个 SDK 程序集。

测试规模（属性标注点，Assets/Tests 下 grep 精确统计）：

1
[Test]            88
2
[UnityTest]       10
3
[TestCase(...)]   47   ← 参数化，实际用例数更多
4
[TestCaseSource]   4
5
                 ---
6
                 149

复现命令：

1
find Assets/GameFramework/Core/Primitives -name "*.cs" | wc -l
2
find Assets/GameFramework/Core/Primitives -name "*.cs" -exec cat {} + | wc -l
3
grep -rho "\[Test\]\|\[UnityTest\]\|\[TestCaseSource" --include=*.cs Assets/Tests | sort | uniq -c

1.2 逐条差异#

1.3 A-3 单独说明：Diagnostics 不是”部分实现”#

这是影响最大的一条统计错误。Game.Core.Diagnostics 是当前唯一一个已经被 Bootstrap 全链路用起来的 Core 子系统：

1
AppLifetimeScope.Configure
2
  → new UnityConsoleDiagnosticSink()
3
  → new DiagnosticRouter(new[]{ consoleSink })
4
  → new DiagnosticEventFactory()
5
  → builder.RegisterInstance(router / eventFactory)
6
        ↓
7
  ApplicationLifecycleCoordinator.Emit / Session.Emit / EntryPointFailureReporter.Report
8
        ↓
9
  DiagnosticRouter.Emit → 每个 sink（sink 抛异常被隔离）

它还有一个笔记完全没提的结构性特征：Game.Core.Diagnostics 只引用 Game.Core.Primitives，不引用 Game.ModApi（Game.Core.Diagnostics.asmdef 的 references 只有一项，AssemblyDependencyTests.cs:18 也把这条钉死了）。

这解释了一个否则会显得多余的类型：ModuleDiagnosticsAdapter 为什么住在 Game.Bootstrap 而不是 Game.Core.Diagnostics？因为它要同时看见 Game.ModApi.Diagnostics.IModuleDiagnostics（公共契约侧）和 Game.Core.Diagnostics.DiagnosticRouter（私有实现侧），而整个依赖图里只有 Bootstrap 一个程序集同时引用了这两边。适配器只能落在组合根。这是”依赖方向决定了代码物理位置”的一个干净例子，值得写进笔记（已补入 03 新增的 §9.1）。

2. B 类：不存在的测试名与不可编译的示例#

这一类是本次审查最需要处理的部分。

2.1 03-Bootstrap-Architecture.md §10：7 个测试名全部不存在#

笔记 03:960-986 给出一张 SessionStateMachineTests 的测试表：

1
New_session_is_in_Created_state
2
Start_transitions_to_Running_and_registers_scope
3
Stop_transitions_to_Stopped_and_disposes_scope
4
Failed_start_emits_start_failed_event
5
Cancel_during_start_transitions_to_Stopped
6
Restart_after_stop_is_rejected
7
State_is_immutable_after_terminal_transition

这 7 个名字在仓库里一个都不存在。 SessionStateMachineTests.cs（239 行）的真实内容是 7 个测试，但名字完全不同：

1
Session_factory_enforces_one_active_session_and_allows_recreation_after_stop
2
Stop_disposes_scope_and_clears_factory_before_final_event
3
Canceled_startup_fails_releases_factory_and_does_not_poison_next_session
4
Scope_creation_failure_is_normalized_and_releases_factory
5
Use_after_dispose_is_explicit_and_repeated_dispose_is_safe
6
Application_and_bound_module_diagnostics_are_attributed
7
Entry_point_failure_is_routed_as_normalized_application_diagnostic

顺带纠正一个由假测试名推出的假结论。笔记说”最微妙的一个：Cancel during start → Stopped 不是 Failed”。真实代码恰好相反——Session.StartAsync 的 catch 分支无条件调用 FailStart(exception)，而 FailStart 的 finally 里写死 state = SessionState.Failed：

1
// Session.cs:314-368
2
void FailStart(Exception primary)
3
{
4
    ...
5
    finally
6
    {
7
        lock (sync)
8
        {
9
            state = SessionState.Failed;   // ← 取消也走这里
10
            isDisposed = true;
11
            ...
12
        }
13
    }
14
}

真实测试名 Canceled_startup_fails_releases_factory_and_does_not_poison_next_session 里的 fails 就是这个意思。取消与失败在 SessionState 上被合并成同一个终态 Failed；区分只体现在返回的 Task 上（取消返回 Task.FromCanceled，其它失败返回 Task.FromException）：

1
// Session.cs:176-185
2
catch (Exception exception)
3
{
4
    FailStart(exception);
5
    if (exception is OperationCanceledException)
6
    {
7
        var token = cancellationToken.IsCancellationRequested ? cancellationToken : new CancellationToken(true);
8
        return Task.FromCanceled(token);   // ← 差别只在这里
9
    }
10
    return Task.FromException(exception);
11
}

这其实比笔记编的那个说法更有意思：状态机粒度和 Task 结果粒度是两套独立的信号，前者只关心”这个 Session 还能不能用”，后者才承载”为什么不能用”。已重写为 03 §10。

✅ 已整节重写。

2.2 03-Bootstrap-Architecture.md §11：测试名 + API 双重不存在#

笔记 03:1005-1008 的示例：

1
public async Task Cleanup_failure_during_normal_stop_keeps_original_completion_and_reports_failure()
2
{
3
    harness.ScopeFactory.OnDispose = _ => throw new InvalidOperationException("cleanup boom");

两处都是假的：

1. 测试名不存在。SessionCleanupFailureTests.cs 的 5 个真实测试是： Scope_disposal_failure_during_normal_stop_still_releases_all_ownership、 Second_session_can_be_created_after_a_cleanup_failure、 Repeated_stop_and_dispose_after_a_cleanup_failure_are_deterministic、 Failed_start_preserves_the_primary_failure_when_cleanup_also_throws、 Failed_start_without_a_scope_still_releases_the_factory。

2. RecordingScopeFactory 没有 OnDispose 属性。 真实的注入点（SessionTestSupport.cs:16-37）是三个：

   1
   public Exception CreateFailure { get; set; }               // 从 Create 抛（模拟 scope 建不出来）
   2
   public Exception DisposeFailure { get; set; }              // 从 scope.Dispose 抛（模拟清理失败）
   3
   public Action<ISessionLifetime> OnCreating { get; set; }   // Create 之前的回调（用来注入重入）

   注意 DisposeFailure 是在构造 RecordingScope 时传进去的（Create 里 new RecordingScope(lifetime, DisposeFailure)），所以它必须在 CreateSession() → StartAsync() 之前设置——这个时序约束，笔记里那个假 API 完全表达不出来。

✅ 已整节重写为真实 API + 真实测试名。

2.3 03-Bootstrap-Architecture.md §12.1：数量错#

标题写”8 个守门测试”，LifecycleMainThreadTests.cs 实际有 10 个。表里列的 8 个名字都对，漏了：

1
Many_concurrent_worker_threads_are_all_rejected_without_disturbing_the_session
2
Main_thread_lifecycle_succeeds_and_repeated_stop_and_dispose_stay_idempotent

有意思的是笔记 §12.3 其实引用了第一个测试的代码体，只是没意识到它就是那个漏掉的测试。✅ 已补。

2.4 06-Mod-Distribution.md §1.4：示例代码违反项目自己的架构测试#

06:155：

1
context.RegisterCapability<IGameRules>(rules);

IModuleContext 的完整定义只有两个属性，没有任何方法：

1
public interface IModuleContext
2
{
3
    ModuleId ModuleId { get; }
4
    IModuleDiagnostics Diagnostics { get; }
5
}

而且这个”没有泛型方法”是被测试钉死的架构约束，不是暂未实现：

1
// PublicApiSurfaceTests.cs:62-68
2
[Test]
3
public void Module_context_is_not_an_unrestricted_service_locator()
4
{
5
    var methods = typeof(IModuleContext).GetMethods();
6
    Assert.That(methods.Any(m => m.Name.StartsWith("Resolve", StringComparison.Ordinal)), Is.False);
7
    Assert.That(methods.Any(m => m.IsGenericMethod), Is.False);   // ← 禁止一切泛型方法
8
}

RegisterCapability<T> 是泛型方法，加进去测试立刻红。这条约束的动机在 spec §11.3（“Public contracts shall not expose internal Unity scene objects unless represented by stable, restricted handles”）和 IModuleContext 自己的 doc comment 里：“It exposes no unrestricted service resolution and becomes invalid after deactivation completes.”

未来的能力注册 API 必然长成非泛型形态，比如：

1
// 一种符合现有约束的可能形状（仍属推测，当前代码库中不存在）
2
IDisposable RegisterCapability(CapabilityKey key, CapabilityVersion version, object provider);
3
bool TryGetCapability(CapabilityKey key, CapabilityVersion minimum, out object provider);

类型安全靠 CapabilityKey + 单独打包的契约程序集（spec §8.5 “Contract-Only Cross-Mod Assemblies”）来承担，而不是靠 IModuleContext 上的泛型参数。这正是 capability 模型与 DI 容器的分野：DI 容器用 Resolve<T>()，T 就是契约；capability 模型用 (key, version) 二元组，契约由独立版本化的第三方程序集承载，于是”谁提供、谁消费、版本合不合”全都能写进 manifest 被机器检查。

同一段还有两个小错：

• CapabilityVersion.Parse("1.x") — 会抛 FormatException。CapabilityVersion 包着 SemanticVersion，正则是 ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)...$，三段必填。当前代码库里根本没有版本区间（range）类型，CapabilityRequirement 存的是”精确版本”（doc comment 原文：Gets the exact capability contract version）。"1.x" 这种写法要等未来引入 VersionRange 才成立。
• 两个 async Task<...> 方法体里没有 await，会触发 CS1998。

✅ 已重写为可编译、且不违反架构测试的示例，并把”版本区间尚不存在”标注出来。

📝 07-Comparison-with-SMAPI.md:223 的 manifest 推测里同样用了 "version": "1.x"，但那一段明确标了”已推测”，且是 JSON 而非 C#，保留原样并加了一句脚注。

2.5 08-Comparison-with-Bevy-ECS.md §2：同一个 GetCapability<T> 问题#

08 的概念对照表里写 ctx.GetCapability<T>(key)。同上，泛型方法形态与 Module_context_is_not_an_unrestricted_service_locator 冲突。✅ 已改为非泛型形态并加注”推测形状”。

3. C 类：结论对但因果错#

这一类不影响”这个项目做了什么”的判断，但会让读者带走错误的通用知识。逐条给出正确的机制。

3.1 02:172 — string.GetHashCode 为什么不能用#

笔记原文：

⚠️ .NET runtime 在每个进程里随机化字符串的 hash seed（从 .NET Core 2.1 起）。

两点不准：

1. 时间线不对。 字符串哈希随机化在 .NET Framework 4.5 就以 UseRandomizedStringHashAlgorithm 配置项存在，.NET Core 从 1.0 起就是默认且不可关闭，不是 2.1 才引入。
2. 对 Unity 来说这个理由几乎不成立。 本项目跑在 Unity 6 的 Mono / IL2CPP 上，不是 CoreCLR。Unity 的 Mono 运行时里 string.GetHashCode() 不做 per-process 随机化，同一进程、同一 Unity 版本下它是确定的。

那 FNV-1a 到底买到了什么？三件更实在的事：

还有一个笔记完全没提、但很值得知道的实现细节：

1
// NamespacedIdentifiers.cs:132-133
2
for (var index = 0; index < value.Length; index++)
3
    hash = (hash ^ value[index]) * 16777619;

这里迭代的是 char（UTF-16 code unit），不是字节。教科书 FNV-1a 定义在字节序列上。对 ModuleId / CapabilityKey 无所谓——它们被 NamespacedIdentifier.IsValid 限死在 ASCII 子集（a-z、0-9、-、.），UTF-16 code unit 与 UTF-8 字节一一对应，结果与标准 FNV-1a 一致。但 DiagnosticAttribute.GetHashCode 也走这个函数，而 DiagnosticAttribute.Value 可以是任意字符串（包括中文、emoji）。此时算出来的值仍然是确定的（这才是真正的需求），只是不等于标准 FNV-1a 对该字符串 UTF-8 编码的结果。

结论没变（这个实现是对的），但理由要换成”确定性”而不是”标准 FNV-1a”。如果将来要把这个哈希写进跨语言协议（比如服务端用 Go 校验），就必须补一句规格说明：“哈希定义在 UTF-16 code unit 序列上”。

✅ 已重写 02 §1.4。

3.2 03:191 — RegisterEntryPointExceptionHandler 的顺序#

笔记原文：

RegisterEntryPointExceptionHandler 必须在 RegisterEntryPoint 之前——否则 entry-point 抛出的异常不会被 reporter 捕获。

“不会被捕获”是错的。 查 VContainer 1.19.0 源码：

1
public void Dispatch()
2
{
3
    PlayerLoopHelper.EnsureInitialized();
4
    var exceptionHandler = container.ResolveOrDefault<EntryPointExceptionHandler>();  // ← 容器建好之后才解析
5
    ...
6
}

handler 是在 Dispatch() 时从已建成的容器里解析的，跟注册先后没关系。而且 Registry.AddToBuildBuffer 里明写着 // Overwritten by the later registration——同类型多次注册，后注册的赢。所以就算顺序反过来，最终生效的仍然是框架自己的 failureReporter.Report。

但顺序确实有影响，只是影响的是另一件事。 RegisterEntryPoint<T>() 内部第一步是 EntryPointsBuilder.EnsureDispatcherRegistered(builder)：

1
// ContainerBuilderUnityExtensions.cs:13-26
2
public static void EnsureDispatcherRegistered(IContainerBuilder containerBuilder)
3
{
4
    if (containerBuilder.Exists(typeof(EntryPointDispatcher), false)) return;
5
    containerBuilder.Register<EntryPointDispatcher>(Lifetime.Scoped);
6

7
    if (!containerBuilder.Exists(typeof(EntryPointExceptionHandler)))       // ★
8
    {
9
        containerBuilder.RegisterEntryPointExceptionHandler(UnityEngine.Debug.LogException);  // ★ 默认 handler
10
    }
11
    ...
12
}

★ 处：如果此刻还没有任何 handler，VContainer 会替你注册一个默认的 Debug.LogException。

于是：

正确的说法：这个顺序不是”能不能捕获”的问题，而是”要不要让 VContainer 塞一个你不想要的默认 handler 进来”的问题。写在前面是干净的做法，但不写在前面也不会漏掉异常。

✅ 已重写 03 §2.3，并补了 Dispatch() 的时机说明（见 §7 第 7 条）。

3.3 03:547 — CancellationTokenSource 重复 Dispose#

笔记原文：

多次 dispose CancellationTokenSource 会抛 ObjectDisposedException 的奇怪变种——用 latch 保证 dispose 恰好一次。

不会抛。 CancellationTokenSource.Dispose() 遵守 IDisposable 的标准契约，内部有 _disposed 检查，重复调用是 no-op。这是 BCL 的明文保证。

那 DisposeCancellationOnce 的 latch 为什么存在？看它的两个调用点就清楚了——RunStop 的 finally 和 FailStart 的 finally。latch 的价值是：

1. 表达单一所有权：这个 CancellationTokenSource 只有 Session 一个 owner，且只被释放一次——这是设计意图的代码化，跟 scope = null; owned?.Dispose(); 的”先清引用再释放”是同一个套路；
2. 让重复调用的开销恒定：不进 BCL 的 dispose 路径，只做一次 bool 判断；
3. 为将来换成非幂等的资源留位置：如果哪天 lifetimeCancellation 换成一个自定义的、Dispose 非幂等的对象，这里不用改。

真正必须小心的不是 Dispose 重入，而是另一件事，而项目已经处理了：CancellationTokenSource 被 Dispose 之后，再访问它的 .Token 属性会抛 ObjectDisposedException。所以 SessionLifetime 在构造时就把 token 拷了一份：

1
// Session.cs:86
2
lifetime = new SessionLifetime(id, lifetimeCancellation.Token);   // ← 构造时抓一次

CancellationToken 是 struct，持有对内部状态的引用；source 释放后，已经拿到手的 token 依然可以安全读 IsCancellationRequested。SessionLifetime 的 doc comment 把这条写死了：

The token is captured once at Session construction and stays stable for the whole Session lifetime, so observing it remains valid after the source has been disposed.

而这正是测试 RecordingScope.Dispose 里那行 TokenCancelledAtDispose = Lifetime.Token.IsCancellationRequested 能安全执行的原因。

✅ 已重写 03 §4.7，把重点从”重复 Dispose 会炸”改成”Dispose 之后 .Token 会炸，所以必须提前捕获”。

3.4 03:859 — TaskScheduler.Default 与 ContinueWith#

笔记原文：

为什么显式 TaskScheduler.Default？ 默认情况下，await continuation 会在调用者的 synchronization context 上跑……

把 await 和 ContinueWith 混为一谈了。代码里是 ContinueWith，不是 await：

1
// ApplicationLifecycleCoordinator.cs:208-212
2
stop.ContinueWith(
3
    completed => CompleteShutdown(completion, Failure(completed)),
4
    CancellationToken.None,
5
    TaskContinuationOptions.ExecuteSynchronously,
6
    TaskScheduler.Default);

正确的机制是 .NET 里一个非常经典的坑：

• await 的续体：捕获 SynchronizationContext；没有 SC 时回落到 TaskScheduler.Current。
• 不带 scheduler 参数的 ContinueWith：不看 SynchronizationContext，直接用 TaskScheduler.Current。

而 TaskScheduler.Current 是环境值——它等于”当前正在执行的 Task 所属的调度器”，只有在没有 Task 上下文时才是 Default。这意味着如果 ShutdownAsync 恰好被某个跑在自定义调度器（比如 ConcurrentExclusiveSchedulerPair、或某些测试框架的调度器）上的 Task 调用，续体就会被排到那个调度器上——一个取决于调用栈的、非确定的行为。这正是”永远显式传 TaskScheduler 给 ContinueWith”这条老规矩的由来。

再看 TaskContinuationOptions.ExecuteSynchronously：它的意思是”尽量在完成 antecedent 的那个线程上就地跑续体，省掉一次调度”。所以两个参数合起来的语义是：

能就地跑就就地跑（省一次排队）；不能就地跑时，回落到线程池，而不是某个碰巧存在的环境调度器。

推论——也是代码注释真正在说的那件事——续体可能跑在任意线程上：

1
// A future Session with genuinely asynchronous cleanup: never block the caller, and never
2
// resume Unity or VContainer work off the main thread. The continuation only emits
3
// diagnostics and releases references.

所以 CompleteShutdown 的函数体被严格限制成”只改内存状态 + 发诊断”，一行 Unity API 都不碰。并且这反过来给诊断管线加了一条硬约束：所有 sink 必须线程安全。 项目确实满足：InMemoryDiagnosticSink 用 lock 保护 List，UnityConsoleDiagnosticSink 只调 Debug.Log（Unity 少数几个可跨线程调用的 API 之一）。

✅ 已重写 03 §8.3，并新增 §9.1 讲诊断管线的线程契约。

3.5 02:582-583 — Guid 格式示例字符串是错的#

1
"a1b2c3d4e5f6789012345678abcdef0"      ← 31 个字符，N format 应为 32
2
"a1b2c3d4-e5f6-7890-1234-5678abcdef0"  ← 末段 11 位，D format 应为 8-4-4-4-12

正确示例：

1
N: "a1b2c3d4e5f678901234567890abcdef"        (32 hex，无连字符)
2
D: "a1b2c3d4-e5f6-7890-1234-567890abcdef"    (8-4-4-4-12)

✅ 已修。

3.6 02:640 / 02:709-717 — 两个表述问题#

• 02:640 写”10 个字段”，紧接着的表列了 11 行。DiagnosticEvent 构造函数确实是 11 个参数。✅ 已改。

• 02:709-717 关于 ToArray() vs ToList() 的那段自问自答（“等等，source.ToList() 也拷贝了？“）逻辑绕了个圈才说清，而且落点错了——重点不是”数组 vs List”。真正的不可变性是三层，缺一不可：

  1. attributes?.ToArray() 对任意 IEnumerable 物化出一份私有拷贝——传进来的如果是 LINQ 惰性序列，这一步顺便消除了”延迟求值 + 外部改动”的风险；
  2. 私有数组字段 readonly DiagnosticAttribute[] items 从不外泄；
  3. 对外只暴露 IReadOnlyList<DiagnosticAttribute>，且 DiagnosticAttribute 是 readonly struct，所以索引器返回的是值拷贝，调用方拿到手也改不了集合里的那一份。

  只做第 1 层（改用 List<T> 存）也能挡住”外部改 source”，但挡不住”内部把 List 引用漏出去”。✅ 已重写。

  📝 顺带一个笔记没提的性能观察：GetEnumerator() 写的是 ((IEnumerable<DiagnosticAttribute>)items).GetEnumerator()，这会装箱数组的枚举器并产生堆分配。UnityConsoleDiagnosticSink.Format 里的 foreach (var attribute in diagnosticEvent.Attributes) 每发一条带属性的诊断就分配一次。对一个 Unity 框架来说这是真实的 GC 压力点，修起来也很便宜。已列入 09 的改进清单。

3.7 02:89 — “总长 ≤ 128（隐式）”#

不是隐式，是显式写在第一行的：

1
// NamespacedIdentifiers.cs:87
2
if (string.IsNullOrEmpty(value) || value.Length > 128 || value.IndexOf('.') < 0)
3
    return false;

同一行还有另外两个被笔记表格漏掉的前置门：IsNullOrEmpty 和 IndexOf('.') < 0（必须含点）。这三个条件放在循环之前，是刻意的快速失败排序。✅ 已修。

4. D 类：spec 引用错位#

笔记里大量使用”spec 第 X.Y 节”的引用，抽查后发现几处错位。spec §6「Architectural Principles」是一个 13 条的扁平编号列表，没有 6.1 / 6.3 / 6.5 这样的子小节。

01 §3.1–§3.5 的映射本身是对的：3.1→原则 1，3.2→原则 2，3.3→原则 3，3.4→原则 6，3.5→原则 7。

5. E 类：依赖图画错#

5.1 01-Index.md:31-45 的 ASCII 图#

笔记画的：

1
Game.ModApi
2
        ↓
3
   ┌────┴────┬─────────┬───────────┬────────────┐
4
Context    Rules    Networking  Persistence  HotUpdate       Diagnostics

把 Diagnostics 画在了 ModApi 下游。Game.Core.Diagnostics 不引用 Game.ModApi（见 §1.3）。而且 Rules / Networking / Persistence / HotUpdate 也不是 ModApi 的直接下游同级——它们还依赖 Context。真实的四层（逐字取自 15 个 asmdef 的 references）：

1
                    Game.Core.Primitives          references: []
2
                    ╱                    ╲
3
       Game.ModApi                        Game.Core.Diagnostics
4
      [Primitives]                        [Primitives]
5
            │                                      │
6
     Game.Core.Context                             │
7
   [Primitives, ModApi]                            │
8
            │                                      │
9
   ┌────────┼────────┬──────────────┐              │
10
 Rules  Networking  Persistence  HotUpdate         │
11
        [Primitives, ModApi, Context]              │
12
            └──────────────┬───────────────────────┘
13
                           │
14
                    Game.Bootstrap
15
        [上面 8 个 + VContainer]   autoReferenced: false

✅ 已替换 01 §2 的图。

5.2 04-ModApi-Contract-Surface.md:18 的注解方向反了#

1
Game.ModApi             (公共契约 — 只依赖 Primitives)
2
        ↓
3
[Context / Rules / Networking / Persistence / HotUpdate]    (不依赖 ModApi)   ← ❌

箭头方向是对的，注解是反的。Game.Core.Context.asmdef 的 references 明确含 "Game.ModApi"；spec §8.3 的表里 Context 的 “Permitted dependencies” 也写的是 “ModApi, Primitives”。

正确表述是单向的那一半：Game.ModApi 不依赖 Game.Core.Context（这才是”公共契约不泄漏内部实现”的那条不变量）；反过来 Context 必须依赖 ModApi，否则它没法实现 IModule 的加载与激活。✅ 已修。

6. F 类：外部事实（SMAPI / Bevy）#

这两篇是对比分析，对 harness 本身的描述没问题，但对外部项目的描述有若干不准。这类错误的危害在于：拿一个不存在的 SMAPI 特性去论证”我们比它强”，论证就是空的。

6.1 07-Comparison-with-SMAPI.md#

F-4 修正后反而强化了笔记的原论点：SMAPI 把”游戏版本兼容性”放在中心化数据库里，本质上是因为它是外挂框架、没法要求 mod 作者在 manifest 里声明一个它自己都不拥有的版本轴；而 harness 因为框架就是游戏本体，可以把 FrameworkCompatibility 的四个维度做成 manifest 的必填字段。这是”第三方注入 vs 一等公民”这个根本差异的一个具体后果——比原文含糊的”SMAPI 是半自由文本”有力得多。已改写。

6.2 08-Comparison-with-Bevy-ECS.md#

7. 笔记漏掉的关键实现思路#

以下都是读源码能读出来、但 8 篇笔记里一句没提的设计要点。它们不是”错误”，而是”这批笔记离吃透这份代码还差的那部分”。已单独展开成 09-Implementation-Deep-Dives.md。

8. 修订记录#

本次对原笔记做的就地修改：

9. 给后续笔记的三条建议#

1. 凡是引用测试名、API 名、字段名，先 grep 一次。 本次 B 类错误全部集中在”我记得测试大概是这么写的”这种地方。写成 `Xxx_yyy_zzz`（`path/File.cs:123`） 这种带行号的引用，既是给读者的，也是给自己的一道校验。
2. 区分”代码写了什么” / “spec 写了什么” / “我推断的”。 06 做得最好（开头就声明”基于 spec 推断”），但推断段落里混进了不可编译的 C#，反而比纯散文更容易被当成事实。建议推断代码一律加 // 推测形状，当前代码库中不存在 的行内注释。
3. 统计数字用命令生成，不要手数。 在笔记头部直接放上生成命令，下次更新时重跑一遍即可，也方便读者验证：

   1
   find Assets/GameFramework/Bootstrap -name '*.cs' | wc -l
   2
   find Assets/GameFramework/Bootstrap -name '*.cs' -exec cat {} + | wc -l