fix(AOT): restore sidecar delivery and narrow linked fallbacks

2026-10-29 07:16:33 +08:00 · 2026-08-17 23:07:14 +08:00
parent 9593bf1537
commit 0d3d9727c6
24 changed files with 314 additions and 46 deletions
@@ -156,8 +156,10 @@ dynamic、reflection、Loose AXAML 和插件输入触发 Package fallback。
 | 静态 Control/AXAML 可确定 | 选择对应 Unit closure |
 | 默认 Package 粒度 | 选择完整 Package Unit |
 | Unit cycle | SCC 全选，每个 leaf fragment 调用一次 |
-| dynamic/reflection/Loose AXAML | 对应 Package full registrar |
+| Loose AXAML / 动态主题 | 对应 Package full registrar |
+| 无法静态解析的 C# 动态创建（`Activator.CreateInstance(Type)` 等） | 不扩大保留范围，报告 `ATOMUILINK010` 警告，由显式 root 覆盖 |
 | Sidecar 缺失、陈旧或无法验证 | 对应 Package full registrar |
+| ProjectReference Sidecar 由 consumer 从普通构建的 assembly metadata 提取（`ExtractedManifest`） | 对应 Package full registrar，不产生诊断 |
 | 分析预算超限 | 对应 Package full registrar |
 | 未知 protocol major | 构建 Error |
 | Fragment symbol 不存在 | 构建 Error |
@@ -236,6 +238,7 @@ ordinary Generator、linked-publish Generator、Build Tasks、Sidecar、PDB 和
 | `ATOMUILINK007` | Loose AXAML 或动态主题导致 Package fallback | Warning |
 | `ATOMUILINK008` | 检测到 Package 使用但缺少 registration entry | Error |
 | `ATOMUILINK009` | Registration entry Attribute 或签名无效 | Error |
+| `ATOMUILINK010` | C# 动态创建无法静态解析，不扩大保留范围，需显式 root 覆盖 | Warning |

 诊断必须包含 Package/Unit identity、稳定 reason 和可定位输入，不能只写“可能不兼容 AOT”。Fallback Warning 只在 linked publish
 或显式 strict 验证中产生；strict 模式可以提升为 Error，但不改变保留范围。
@@ -110,6 +110,12 @@ Sidecar 是纯编译资产：
 - Package 自己的 `<PackageId>.targets` 只在 linked build 中把它加入 `AdditionalFiles`。
 - linked ProjectReference 在程序集复制到 `TargetPath` 后生成 `<TargetPath>.atomui-link.json`；消费项目从已解析
  `ReferencePath` 的 companion 路径收集它，不递归调用 ProjectReference target。
+- companion Sidecar 缺失时（引用库是普通构建，例如 `PublishAot`/`PublishTrimmed` 只在应用项目局部设置），消费项目直接从
+  引用 assembly 的 metadata 记录提取 Sidecar 到自身 `obj`。普通库构建始终包含 Package/Unit/ControlMap/Axaml UnitEdge
+  记录，但 C# UnitEdge 只由 linked 库构建计算，所以提取的 Sidecar 对每个 Package 附加 `ExtractedManifest` fallback：
+  Application Plan 对该 Package 保持 full fallback，且不产生诊断。publish 时以全局属性传入
+  `-p:PublishAot=true` / `-p:PublishTrimmed=true` / `-p:AtomUILinkedPublish=true`，引用库即自行产出完整 Sidecar，
+  提取路径自动旁路。
 - `CopyToOutputDirectory`、`CopyToPublishDirectory` 均为 `Never`。
 - 不作为 EmbeddedResource，不进入运行时程序集、应用输出或 publish 目录。

@@ -259,7 +265,8 @@ Sidecar 不进入运行时。`UseXxxControls()` 仍拥有 Package Core、Provide
 | --- | --- |
 | 精确静态 usage | 选择 Unit closure |
 | 默认 Package 粒度 | 选择单一完整 Package Unit |
-| dynamic/reflection/loose AXAML | 当前 Package full registrar |
+| loose AXAML / 动态主题 | 当前 Package full registrar |
+| 无法静态解析的 C# 动态创建 | 不扩大保留范围，报告 `ATOMUILINK010` 警告，由显式 root 覆盖 |
 | sidecar 缺失、陈旧或无法绑定 | 当前相关 Package full registrar |
 | 未知 protocol major | 构建 Error |
 | fragment symbol 不存在 | 构建 Error |
@@ -292,9 +292,14 @@ Package、Unit、ControlMap 或 full fragment metadata。
 Attribute，不要为了让 Common 参与应用计划而复制 `UseDesktopControls()` 的方法 identity，也不要引入跨 Package Unit 闭包。

 类库只在被 linked 应用作为 ProjectReference 构建或执行 NuGet Pack 时生成 Usage Sidecar。普通 Debug/Release 必须跳过 usage
-分析和 Sidecar 生成。缺失或无法验证的 Sidecar 不能解释为没有 usage，只能让相关 Package full fallback。
-`ATOMUILINK002` 和 `ATOMUILINK007` 只在 linked publish 或显式 `AtomUIRegistrationStrict=true` 验证中显示；strict 模式用于
-CI 把自动 full fallback 提升为 error。
+分析和 Sidecar 生成。应用侧编译时如果 ProjectReference 旁路没有 Sidecar，consumer 直接从引用 assembly 的 metadata 记录提取
+（普通库构建始终包含 Package/Unit/ControlMap/Axaml UnitEdge 记录），用于诊断与入口校验；提取的 Sidecar 带
+`ExtractedManifest` fallback 标记，相关 Package 在 Application Plan 中保持 full fallback，不产生诊断。要获得 Unit 级裁剪，
+publish 时以全局属性传入 `-p:PublishAot=true` / `-p:PublishTrimmed=true`（命令行全局属性沿 ProjectReference 流动，引用库
+自行启用 linked 构建并产出含 C# UnitEdge 的完整 Sidecar）；如果应用在项目文件里局部设置这些属性，则 publish 时补传
+`-p:AtomUILinkedPublish=true`。缺失或无法验证的 Sidecar 不能解释为没有 usage，只能让相关 Package full fallback。
+`ATOMUILINK002`、`ATOMUILINK007` 和 `ATOMUILINK010` 只在 linked publish 或显式 `AtomUIRegistrationStrict=true` 验证中显示；strict 模式用于
+CI 把自动 full fallback 或未覆盖的动态创建提升为 error。`ATOMUILINK010` 不触发 full fallback，只提示用显式 root 覆盖。

 修改 Generator ABI、Sidecar schema、feature switch 或 Public fragment entry point 时，按 Public API 和协议 review，并运行
 普通构建零 linked-analysis、trimmed JIT、NativeAOT 和非裁剪兼容验证。系统契约见
@@ -161,7 +161,7 @@ writer 不生成 `AddDependencies`，不调用其他 Unit，也不调用 `TryEnt
 诊断必须使用稳定 reason code，并包含 Package 和可用 source identity。至少区分：

 - unresolved owner。
- dynamic/reflection usage。
+- dynamic/reflection usage（不扩大保留范围，报告 `ATOMUILINK010`，由显式 root 覆盖）。
 - loose or unresolved AXAML。
 - missing/stale sidecar。
 - unknown protocol major。
@@ -214,7 +214,7 @@ Package 与 entry 信息。SCC 发现和组件依赖排序必须使用显式栈

 - Debug/普通 Release 的 `Csc` Analyzer item 不含 linked analyzer。
 - linked AXAML target 在普通构建 skipped。
- ProjectReference sidecar 只在 linked build 传递。
+- ProjectReference sidecar 只在 linked build 传递；companion 缺失时 consumer 从引用 assembly metadata 提取，提取结果带 `ExtractedManifest` fallback（full fallback、无诊断）。
 - NuGet sidecar/consumer target 自动打包且不进入 runtime assets。
 - sidecar 缺失、损坏或无法验证时只触发 Package fallback。

@@ -9,6 +9,7 @@
 - 内容：单个 JSON object。
 - NuGet 位置：`buildTransitive/AtomUI.LinkedRegistration/`。
 - ProjectReference 位置：项目 `obj` 输出，由 MSBuild target item 传递。
+- ProjectReference 旁路缺失时，consumer 直接从引用 assembly 的 metadata 记录提取 Sidecar 到自身 `obj`（见 `ExtractedManifest`）。
 - 不作为 `EmbeddedResource`、`Content`、runtime asset 或 publish asset。

 Producer 必须使用结构化 JSON writer。Consumer 必须使用结构化 parser；不得用正则或字符串切割解析。
@@ -124,8 +125,16 @@ Fallback record 包含：
 - `MissingSidecar`
 - `StaleSidecar`
 - `AnalysisBudgetExceeded`
+- `ExtractedManifest`

-Fallback 只能扩大保留范围。Consumer 不得忽略未知必需 reason，也不得把 fallback 降级为 Exact。
+Fallback 只能扩大保留范围。Consumer 不得忽略未知必需 reason，也不得把 fallback 降级为 Exact。例外有两个：
+
+- `DynamicInvocation`：提示性记录，Consumer 不扩大保留范围，只报告 `ATOMUILINK010` 警告，由显式
+  `AtomUIRegistrationUnitRoot` / `AtomUIPackageRoot` 覆盖。
+- `ExtractedManifest`：consumer 从普通构建的 ProjectReference assembly metadata 提取的 Sidecar 标记。
+  Package/Unit 清单完整，但 C# UnitEdge 只由 linked 库构建计算，所以 Consumer 必须对相关 Package 扩大为
+  full fallback，且不产生任何诊断。要获得完整裁剪，发布时以全局属性传入 `-p:PublishAot=true` /
+  `-p:PublishTrimmed=true` / `-p:AtomUILinkedPublish=true`，让引用库自行产出完整 Sidecar。

 ## 确定性