# dx40 ver1 技术笔记

> 笔记版本：1.0
>
> 源码快照：2026-09-02
>
> 适用范围：`version/ver1` 及其直接使用的根目录 `assets/`、`mylib/`、`third/` 与根 `makefile`
>
> 行星专项推进与视觉验收见 [dx40 行星模型收敛控制台](https://vinesea.uk/clip/api/notes/note-md-mdpepBkKPxIGlUjE)

## 1. 先建立正确的项目模型

`ver1` 是 dx40 当前的 Windows 原生实验引擎，不是一个单文件 DirectX 示例。它由 44 个正式 Service Slot、ECS 事实、显式帧阶段、资源 Handle、逐 View 渲染提取以及 D3D12 后端组成。当前源码规模约为 113 个 `.cpp`、241 个 `.h`，并有 138 个 PowerShell 契约探针。

理解本版本时，以以下证据顺序为准：

1. `main.cpp`：构造、启动、帧序和关闭的最终事实。
2. `sub/*/I*Service.h`：跨子系统可见的窄接口。
3. `sub/*/*Components.h` 与实现文件：ECS 事实及其唯一写入者。
4. `RenderPacketTypes.h` 与 `D3D12Renderer.cpp`：CPU 到 GPU 的真实边界和 Pass 顺序。
5. 各子系统 `README.md`：设计约束与维护说明；若与上述源码冲突，以源码为准。

`SUBSYSTEMS.md` 中的“资源、世界、编排、后端”等域只是阅读导航，不是编译层级，也不是 include 白名单。当前自动架构契约只禁止直接的双向服务依赖，不能证明不存在更长的依赖环。

## 2. 构建、运行与产物

根 `makefile` 根据位置参数选择 `version/<name>`。`ver1` 没有 `package.json`，因此走 C++17/MinGW-w64 路径：递归发现本版本所有 `.cpp`，生成依赖文件 `.d`，链接为 `build/ver1/main.exe`。

常用命令：

```powershell
make ver1
make run ver1
$env:DX40_TEST_FRAMES='8'; make -j8 run ver1
make clean ver1
make thirdlibs
```

固定帧模式由 `main.cpp` 读取 `DX40_TEST_FRAMES` 后交给 `Win::setFrame`；它适合证明构建、启动和有限帧关闭，不证明交互和视觉正确。

`libs.mk` 指定四个动态库：

| 依赖 | 主要用途 |
| --- | --- |
| `ext3` | 本地网格和数学辅助库 |
| `freetype` | 字体栅格化与字形图集 |
| `assimp` | DAE 等外部模型导入，类型不进入公共头文件 |
| `lua` | Script 运行时 |

系统链接包含 Win32、IME、计时/音频、网络以及 D3D12/DXGI/D3DCompiler。根 `dll/` 是运行时 DLL 汇集目录。工作目录必须能解析根 `assets/`，因为 Assets 和 ShaderLibrary 使用 `assets/json/...`、`assets/shader/...` 等相对路径。

## 3. 总体依赖方向

项目希望保持的主方向是：

```text
App / main.cpp
    → 公共 Service 协议与 ECS mutation / intent queue
    → RenderSubmit 提取
    → RenderQueue / immutable RenderPacket
    → D3D12 Backend
    → Win32 / D3D12 原生对象
```

关键约束如下：

- `main.cpp` 是唯一顶层生命周期调度者；子系统不能推进另一个子系统的 `staframe/runframe/endframe`。
- Native D3D 对象只存在于 `sub/backend/d3d12`；游戏、Scene、UI、Camera、资源系统只提交 Handle、快照或命令。
- ECS Component 是运行事实源；各种 `Ref` 只是非拥有句柄，不建立第二份状态。
- 跨帧领域操作优先进入拥有者队列，并携带 `DomainActionId`、状态和作者来源，而不是由调用者直接改组件。
- `GetService<T>()` 是全局原子 Service Slot，适合组合和窄协议定位；不能借此形成隐藏的“万能服务”依赖网。
- `LeonardoController`、Inventory 私有交互 runtime、Narrative 私有 PixelFight runtime、Animator adapters 都不是 Service Slot。它们由拥有者或 App 显式注入和推进。

## 4. 44 个正式服务槽

`subsys<IService>` 构造时将实现写入 `ServiceSlot<IService>::slot`，关闭时仅在槽仍指向自身时注销。`GetService`/`SetService` 使用 acquire/release 原子语义，但这不等于系统支持多线程更新；当前主循环仍由单线程显式排序。

| 域 | 正式服务槽 | 核心责任 |
| --- | --- | --- |
| 基础设施 | Time、Ecs、Event、Input、File、Win、Web | 时间、实体存储、事件与输入、文件、窗口消息泵、退出/本地 Web 集成 |
| 渲染边界 | RenderQueue、RenderSubmit、D3D12Backend | 命令所有权、逐 View 提取、GPU 资源与提交 |
| 资源 | Mesh、Texture、Sprite、Material、Animation、Assets、Skeletal2D、Icon、Font | 不可变资源、稳定 Handle、导入、字体与图标目录 |
| 世界/表现 | Transform2D、Transform3D、Camera、Light、Entity2D、Entity3D、Effects、Vegetation、Particle、Vfx、Area、Pick、Physics、Indicator、Scene、Planet、UI | ECS 世界事实、空间、视图、环境、效果、交互和表现提取 |
| 编排 | Trigger2D、Audio、Script、Animator、Inventory、Sequence、Narrative、SceneTransition | 触发、播放状态、脚本、状态机、物品、时间线、叙事与场景事务 |

这 44 个槽的保留理由通常至少满足两项：拥有持久事实、拥有独立帧生命周期、被多个消费者通过稳定协议使用。目录数量不是合并服务的依据。

## 5. 启动与默认内容装配

所有子系统先作为 `main()` 栈对象按声明顺序构造，随后执行四个显式启动接缝：

1. `SpriteSys::initializeCatalog(Assets&)`：Assets 给出只读 Sprite 请求计划，Sprite 加载并生成 Handle，Assets 安装索引；Assets 不反向定位 Sprite。
2. `SceneSys::initializeDefaultContent(...)`：建立 78/22 Area 分屏、左侧 3D Scene、右侧九宫 2D Scene，以及默认相机、实体、环境、Planet、VFX 施法者等世界事实。
3. `UISys::initializeDefaultContent(...)` 与 `InventorySys::initializeInteraction(...)`：分别建立 Inspector/FPS 和私有背包/拾取投影。
4. `NarrativeSys::initializeDefaultContent(...)`：把已装配 Scene 的稳定语义表绑定到 Chapter、Flow、Sequence 和 Inventory 等协议。

任一关键初始化失败都会打印 PLT 日志并以返回值 1 结束，不进入消息循环。

默认内容的所有权不能混淆：Scene 创建 Scene/Area 绑定和普通世界实体；Narrative 拥有 Chapter/Flow 实例；Inventory 拥有数量与拾取 mutation；Vfx 拥有池和技能阶段；UI 拥有 retained tree；Planet 是唯一行星尺度和地形快照作者。

## 6. 一帧的六个阶段

主循环条件是 `win.processMessages() && !web.exitRequested()`。以下顺序来自 `main.cpp`，是行为的一部分。

| 阶段 | 调用顺序 | 主要产物 |
| --- | --- | --- |
| Frame Import | `time → ecs → input → events → renderQueue.staframe` | 新时钟、清理后的帧状态、Raw Input 应用、空 RenderPacket |
| World | `scene → area → LeonardoController → trigger2d → sceneTransition → indicator.prepareTransformWrites` | Scene/Area/焦点事实、玩家意图、触发与迁移、变换写入租约 |
| Orchestration | `vfx → particles → audio → script → narrative.staframe → sequence → inventory → narrative.runframe → animator → skeletal2d → entity2d playback → animation` | 模拟、作者状态机、播放游标和 owner mutation |
| Presentation | `ui → camera → planet → vfx.processInteractiveInput → entity2d.staframe` | 布局/输入后的 UI、最终相机、行星选择、施法目标、2D 索引 |
| Extraction / Backend | Area contexts → RenderSubmit → Indicator → D3D start → 通用 runframe → transition overlay → `finalizeFrame` → `d3d.render(packet)` | 每 View 命令、晚期覆盖、冻结包和 GPU 命令 |
| End | `d3d → particles → renderQueue → events → input → camera → lights → transform2d → transform3d → entity3d → ecs → time` | 释放帧临时资源、提交排队写、最终删除实体 |

几个容易误读的点：

- `staframe/runframe/endframe` 不是统一语义的 ECS System 三遍循环；每个 owner 在自己需要的阶段覆写其中一部分。
- Camera 在 Planet 和 RenderSubmit 前完成，因此地形选择和 View 矩阵读取的是当帧最终相机。
- Indicator 的 Transform 写入发生在前，Indicator 可视命令发生在 RenderSubmit 后；这样 Gizmo/技能覆盖能进入同一 RenderPacket，又不会倒逼 Scene 或 Camera。
- `RenderQueue::finalizeFrame()` 每帧只调用一次，之后不允许继续附加 2D 命令；Debug 构建会检查 `commands2DDirty`。
- ECS 的物理删除位于 End 阶段靠后，避免生产者当帧留下悬空实体引用。

## 7. 输入、仲裁与组件写入

输入只有一条导入路径：

```text
Win32 WndProc
  → IEventService::pushRawInput
  → EventSys::staframe
  → IInputService::applyRawInput
  → 按优先级排序的 handler / channel claim
```

UI、Modal、Area、Camera、Indicator、VFX 和 Fallback Gameplay 通过 Event 的通道所有权仲裁键盘、指针、滚轮和文本输入。禁止重新引入 `GetAsyncKeyState` 绕开这条路径。失去焦点时，持有状态在后续 handler 读取前清空。

Transform2D、Transform3D 和 Light 等共享组件使用“读 → 意图 → 仲裁 → 提交”模型。`ComponentWriteOrder` 先比较 Layer，再比较 weight，最后比较单调 order：

`System < Constraint < Scene < Inspector < Interaction < Override`

`ComponentSlotLockTable` 为特定 writer 提供可重入 token 租约；不同 writer 在锁持有期间不能写同一 slot。租约只表达临时写权，不拥有 Entity。详细协议见 `read2write.md`。

当前重要按键：Camera 用 `C` 切 Scene 相机、`F`（兼容 `M`）切 Orbit/Fly、Home 重置；VFX 用 `Q/E/R/T/V/X` 选六种技能，左键确认、右键或 Esc 取消；右侧 Leonardo 用方向键移动、`A/B/A+B` 触发动作；Inventory 用 `B` 打开背包、Esc 关闭。最终是否生效仍取决于 Area 焦点和 Event 仲裁。

## 8. ECS、Scene、Area 与 View

ECS 提供分段实体身份和类型化 Component 存储。各领域子系统是 Component 的事实所有者，工厂函数和 `Ref` 只能通过 owner 协议创建缺失组件或排队 mutation。

Scene 持有 `SceneTag`、层级、Area binding、暂停状态、活动相机和 selection revision。`contentMode` 为 TwoD、ThreeD 或 Mixed，实体挂接时校验内容域。Area 持有树、leaf viewport、焦点和 Scene 绑定，不拥有 Scene Component。

渲染前，`AreaSys::collectRenderContexts` 生成活动叶节点的不可变 `RenderSubmitContext`。每个 context 明确携带 scene/view/area key、viewport、scissor、camera、content domain 和 deferred 开关，因此多视图不是后端猜测出来的全局状态。

Camera3D 的位置/朝向与同实体 Transform3D 绑定；RenderSubmit 优先解析 context 指定相机，只有允许时才回退 active camera，并按该 View 的宽高比计算 view/projection。Camera2D 是 Scene-owned 的 2D 世界视图，不复用 Transform2D。

UI 是 retained ECS tree。其固定内部顺序为：清帧状态 → 收集 roots → dirty measure/layout/resolve → 输入与文本 → tooltip/overlay 状态 → 第二次 dirty layout → visual sync。布局、裁剪必须先于命中，输入必须先于视觉同步。UI 最终只生成 Entity2D 视觉事实，不把 Widget 对象交给后端。

## 9. 资源与作者数据

根 `assets/json` 当前包含 19 份 JSON。核心目录由 `Assets.cpp` 固定声明：Model、Mesh、Material、Texture、Animation、Particle、VFX、Chapter、Narrative、Sequence、Item、Prefab、Scene，以及三个 Sprite catalog 和 Animator sidecar。

资源路径是：

```text
严格 JSON descriptor
  → Assets 候选快照解析、类型/引用/环/范围校验
  → owner service 注册真实资源
  → 稳定 Handle / shared immutable payload
  → ECS instance 保存 Handle 与实例游标
  → RenderSubmit 复制必要快照到 RenderPacket
  → Backend 按 Handle + revision 缓存 GPU 对象
```

关键区分：

- Assets 拥有 catalog、短名索引和解析缓存，不拥有 MeshData、TextureData、Animator instance 或 GPU 对象。
- Mesh、Texture、Material、Sprite、Animation、Skeletal2D 各自保留资源语义，不能为了减少目录把它们塞进 `IAssetService`。
- Sprite 的 Frame 只保存空间，Sequence Step/Composite Track Key 保存时间；实例播放游标属于 ECS。
- Animator 只决定状态迁移并调用 target adapter，不推进 Sprite Step、不采样骨骼、不写 Transform。
- `reloadAuthoredContent` 对 Narrative、Sequence、Chapter 先完整交叉校验，再原子换代；失败保留旧 snapshot。它不会回写已经实例化的 Scene 或正在运行的 Narrative instance。
- 外部 GLB/OBJ 有内置导入路径；DAE 通过 Assimp。Backend 永远不负责解析作者文件。

## 10. 编排、动画与游戏运行时

Animator 是 Sprite2D、Skeletal2D、Skeletal3D 共用的状态机核心。machine 是不可变资源；`AnimatorComponent` 保存实体自己的 state、参数、Trigger 和 completion revision。每实体每帧最多迁移一次，按 priority 降序和声明顺序稳定决胜。播放器本帧产生的完成边沿在下一帧被 Animator 消费。

Narrative 将作者节点编译为十类 Flow core node 和字符串 Command Action。Chapter 连接 Flow 入口、Sequence 资源槽及 Scene/Actor/Signal 语义要求；运行时先事务性解析 `ChapterBindingTable`，再附加实例。Inventory、SceneTransition 等跨帧副作用通过各 owner 的 Action Queue 完成，Narrative 不直接改对方组件。

Sequence 拥有固定步进时间线、Slot binding、Key 和 Marker；Script 执行 Lua 实例；Trigger2D 产生接触事件；SceneTransition 管理迁移/淡入淡出事务。它们是并列 owner，不是 Narrative 的内部模块。

VFX 的正常纵切是 `Assets VfxHandle → VfxSys 固定池 → Mesh/Particle/Light/Transform owner facts + VfxPrimitiveCommand → RenderPacket → Backend`。施法期间不创建资源，不解析 preset，不把 D3D 对象放进 VfxSys。六个默认技能共享有界池与 Travel/Impact/Fade/Done 生命周期，但保留各自强类型空间 recipe。

## 11. CPU 渲染提取

RenderSubmit 对每个 `RenderSubmitContext` 执行：

1. `beginView(scope)`，建立明确 viewport/scissor/content domain。
2. 解析 Camera3D，写 view、projection、camera position，并保存只读 View snapshot。
3. 依次要求 producer 通过 `IRenderCommandWriter` 提交：Light → Entity2D；若含 ThreeD，再提交 Entity3D → Particle → Effects → Planet → Vegetation → VFX。
4. `endView()`，进入下一个 Area/View。

Planet 在 Effects 之后提交，是为了让 RenderQueue 为该 View 选择最后且唯一的物理行星事实，而不是让 Effects 发布第二颗行星。

`RenderViewPacket` 同时承载 2D primitives、Mesh/Material/Skin、Light、Particle、VFX primitive、Environment、Planet/Terrain、Atmosphere、Ground、Water、Vegetation、Cloud 等值或共享不可变快照。Backend 不再查询 ECS 或各 producer。

`RenderQueue::finalizeFrame` 完成三类工作：

- 根据最终 Planet 与 Camera 派生 `PlanetViewState`，并把 Atmosphere 兼容半径收敛到同一 Planet。
- 对 3D Mesh 建 material/skin snapshot、分类 opaque/transparent/overlay/shadow，并执行需要的排序与裁剪数据整理。
- 对 2D `commands2D` 按 layer、sort weight、paint key 和稳定提交序统一排序，使晚期 Indicator/Transition overlay 仍只排序一次。

## 12. D3D12 后端与 Pass 顺序

`D3D12Backend` 拥有 Device、ResourceManager、ShaderLibrary、PipelineStateLibrary、GPU profiler 和 Renderer。ShaderLibrary 从 `assets/shader/d3d12/*.hlsl` 找源文件，并复用 `assets/shaderPre/d3d12/*.cso`；当前约有 55 个 HLSL/HLSLI 源文件和 69 个预编译 CSO。PipelineStateLibrary 在创建原生 PSO 前核对 IA、VS 输入以及 VS/PS 的 CBV/SRV/UAV/Sampler register/space/count/visibility。

每个 3D View 的主要顺序为：

1. 获取 View-local HDR/color/depth 资源并清理。
2. 更新 Ocean simulation 和 Water ripple。
3. 生成 Cloud shadow/environment capture，再准备 Atmosphere。
4. 绘制 Skybox，解析 IBL。
5. 构建 `D3D12PreparedView3D`，解析 Mesh/Material/Skin；执行 GPU skinning。
6. 若存在 Water，生成平面反射辅助 View。
7. 渲染 Shadow depth，并把只读 Shadow/IBL/Cloud 环境绑定给后续 pass。
8. 绘制 Planet Ground/Terrain；按条件选择 Deferred G-buffer + lighting，或 Forward opaque。
9. 绘制 Water 后方透明对象、Vegetation、Water、Cloud composite、其余 transparent/overlay。
10. 绘制 Alpha Particle、VFX、Additive Particle。
11. 执行 Volumetric Light、Light Shaft 和 ViewPost；最后把 View 结果合成到 back buffer。
12. 使用全窗口像素坐标但按当前 Area scissor 绘制 2D/UI。

纯 2D View 跳过 3D 链，直接走 Mesh2DPass。3D View 的 deferred 只有在配置允许且当前资源/透明/环境条件满足时启用；代码保留回退到 forward 的路径。Ground 与 Water 共存时会选择共享深度事实的兼容路径，而不是强制 deferred。

Planet 地形使用 CPU Cube-Sphere 选择和不可变 tile-local geometry，D3D12PlanetTileCache 按 Planet revision、Morton tile 和 grid 驻留 VB；Ground 与 Water 共享拓扑和 GPU buffer。相机移动及 morph 不应导致逐帧重建顶点。

## 13. 行星与环境链

`PlanetSys` 是 WGS84 椭球、ECEF/ENU、相机高度阶段、Cube-Sphere LOD 和 terrain snapshot 的唯一作者。CPU 椭球运算使用 double；普通 ECS 实体位于局部 ENU。程序地表以绝对海平面高度生成，Water 的 0 m 始终是海平面椭球，不是局部地面原点。

六个 cube face 始终保持完整覆盖；父节点只有在四个孩子都可用时才整体替换。跨面邻接用于共享 morph；同级边不生成 skirt，真正跨级边才使用有界向内 skirt。Backend 对球背面执行剔除，而不是让 CPU 选择留下孔洞。

Effects 仍拥有 Environment、Atmosphere、Ground、Water、Cloud 的 ECS 表现事实；Vegetation、Particle、VFX 是独立 owner。它们共同消费 Planet/Camera/Light 形成的只读 View 状态，但不能各自推导第二套半径、地平线或太阳事实。

## 14. GPU 与资源生命周期

CPU 资源身份使用 Handle 和 revision。ResourceManager 把 Handle 解析为缓存的 D3D12 Buffer/Texture/SRV；PreparedView 避免在 Shadow、Forward/Deferred 等 pass 重复解析同一 View 的 Mesh/Material。Skin、Particle、Ocean、Cloud、ViewPost 和 Planet tile 都有独立的持久资源或帧资源管理器。

关闭时 `main.cpp` 显式逆向释放：先 D3D/Win/Input 与表现层，再场景、编排和资源，最后 Transform/File/Event/ECS/Time。特别是 Animator 要先停止实例求值，Assets 再释放索引，Audio 仍应在 Assets 卸载登记音频时可用。不要依赖 C++ 栈析构偶然形成正确 GPU/服务顺序。

## 15. 调试开关

| 环境变量 | 作用 |
| --- | --- |
| `DX40_TEST_FRAMES` | 固定帧启动/关闭 smoke |
| `DX40_D3D12_DEBUG` | 请求 D3D12 debug layer |
| `DX40_CBUFFER_CONTRACT` | 反射检查 C++/HLSL cbuffer 布局 |
| `DX40_SHADER_STARTUP_TEST` | 启动阶段 Shader 检查 |
| `DX40_RESIZE_PROBE` | Render target resize 状态机探针 |
| `DX40_SCREENSHOT=<path>` | 捕获首帧截图 |
| `DX40_VSYNC=0` | 使用 immediate Present |
| `DX40_3D_PERF_TRACE` | 输出 3D prepare/finalize/draw 统计 |
| `DX40_UI_PERF_TRACE` | 输出 UI layout/hit/visual/2D finalize P50/P95 |
| `DX40_3D_ABLATE` | 后端按实现支持的项目旁路部分 3D pass |
| `DX40_UI_INPUT_TRACE` | UI 输入路径诊断 |

`PLT(category, ...)` 支持 LogHook；frame/time/input/event/win/d3d/ecs/assets 等高频分类默认按 60 帧限流。性能和契约日志应作为诊断证据，不应改变事实所有权。

## 16. 测试与验收

`version/ver1/tests` 以源码契约和 focused probes 为主。修改某个域时，应先运行该域探针，再执行真实构建/启动。例如：

```powershell
powershell -ExecutionPolicy Bypass -File version/ver1/tests/subsystem_enclosure_contract.ps1
powershell -ExecutionPolicy Bypass -File version/ver1/tests/d3d12_pipeline_binding_contract.ps1
powershell -ExecutionPolicy Bypass -File version/ver1/tests/planet_foundation_contract.ps1
$env:DX40_TEST_FRAMES='8'; make -j8 run ver1
```

证据边界必须明确：

- 静态探针通过：只证明指定源码契约仍成立。
- Shader 编译/反射通过：证明语法、入口和寄存器布局，不证明画面正确。
- 固定 8 帧通过：证明构建、初始化、有限帧提交和关闭，不证明交互或视觉等价。
- 相机、输入、VFX、UI、行星高度切换等视觉/交互能力，仍需真实窗口操作和可比较截图。

## 17. 修改功能时从哪里进入

| 目标 | 首要入口 | 接着检查 |
| --- | --- | --- |
| 改帧序或启动装配 | `main.cpp` | 相关 owner README、shutdown 顺序、coordination contracts |
| 加新作者资源 | `assets/json/*.json`、Assets parser | 对应 owner 注册接口、引用交叉校验、资源 attribution |
| 加 2D/UI 表现 | UI/Entity2D 公共工厂 | RenderScope、clip、2D layer/paint key、Mesh2DPass |
| 加 3D 实体或材质 | Assets + Entity3D owner | RenderMaterialSnapshot、PreparedView、Mesh3DPass |
| 改相机/选择/Area | Camera、Scene、Area、Pick 协议 | Event claim、RenderSubmitContext、Transform write intent |
| 改行星/海洋/云 | Planet/Effects owner | RenderPacket facts、Ground/Water/Cloud/Atmosphere pass 顺序 |
| 加技能效果 | VFX recipe/catalog | 固定池、owner intents、VfxPrimitiveCommand、VfxPass |
| 改叙事或时间线 | Chapter/Narrative/Sequence catalog | Flow compiler、binding transaction、owner Action Queue |
| 改 Shader binding | HLSL + ShaderLibrary/PipelineStateLibrary | cbuffer contract、register visibility、预编译 CSO |

一次改动应沿真实调用链检查：创建/注册 → ECS 或资源事实 → mutation/模拟 → RenderSubmit → RenderPacket → Backend pass → endframe/shutdown。只改入口或只改 Shader 都不能证明纵向能力完整。

## 18. 当前边界

- 本版本是持续演进的实验引擎，默认 Scene 同时承载 UI、九宫 2D、模型、Narrative、VFX、Planet、Water、Cloud、Vegetation 与测试探针，不等同于精简产品运行时。
- Service Slot 是方便的全局定位机制，不拥有服务；真实所有权仍由 `main.cpp` 栈对象和各领域数据结构决定。
- 资源热重载并非全域通用；当前明确支持的是作者内容候选快照的原子换代，已有运行实例不会自动迁移。
- Planet 已具程序地表、Cube-Sphere LOD 和 CPU/GPU 驻留缓存，但离线瓦片流、侵蚀和更完整的美术材质层仍是后续能力。
- Fixed-frame、契约和编译证据不能替代真实交互与视觉验收。

这份笔记用于建立整体心智模型；具体字段、默认值和局部不变量应继续从相应接口、Component、实现文件及子系统 README 中核对。