Consolidate agent guidance, remove legacy compatibility APIs, add generator validate mode, and update templates/tests

AGENTS.md

@@ -158,19 +158,6 @@ dotnet run --project sandbox/Benchmark/Benchmark.csproj -c Release
 dotnet run --project sandbox/ConsoleApp/ConsoleApp.csproj
 ```
 
-## Compatibility APIs
-
-Legacy callback and alias APIs remain for compatibility, but new code and docs should not prefer them:
-
-```csharp
-DataTableManagerExtension.Preload(() => Console.WriteLine("All loaded"));
-var table = DataTableManager.GetDataTable<DTScene>();
-DataTableManager.CreateDataTable<DTScene>(() => Console.WriteLine("DTScene loaded"));
-DataTableManager.EnableMemoryManagement(50);
-```
-
-When touching compatibility behavior, preserve existing tests or add migration-focused tests.
-
 ## Hard constraints
 
 - Do not put try/catch blocks around imports.

README.md

@@ -156,7 +156,7 @@ var cachedShard = DataTableManager.GetCached<DTScene>("x001");
 var shardIsLoaded = DataTableManager.IsLoaded<DTScene>("x001");
 ```
 
-旧的回调加载、`CreateDataTable*`、`GetDataTable*` 和 `HasDataTable*` 仅作为兼容 API 保留；新代码不要依赖这些别名。
+旧的回调加载、`CreateDataTable*`、`GetDataTable*`、`HasDataTable*`、`EnableMemoryManagement` 等兼容别名已在破坏性清理中移除；代码应直接使用 `LoadAsync` / `GetCached` / `IsLoaded` / `EnableEstimatedMemoryBudget`。
 
 ### 独立上下文
 

docs/designs/kv-table-design.md

@@ -55,7 +55,7 @@ var rewards = DTGameConfig.DefaultRewards;
 当前实现还会生成动态访问 API：
 
 ```csharp
-var table = DataTableManager.GetDataTable<DTGameConfig>();
+var table = DataTableManager.GetCached<DTGameConfig>();
 table?.TryGetValue("MaxLevel", out int? value);
 table?.GetValue<int>("MaxLevel");
 ```
@@ -114,7 +114,7 @@ table?.GetValue<int>("MaxLevel");
 2. 每个条目写出 key、类型签名和 value payload。
 3. 结构化 header 继续使用 v3 header、schema hash、generator version、table full name 和 flags。
 
-如果后续引入独立 kv payload，可保留 key 到 value 的元数据，方便调试工具和兼容 API 查询。
+如果后续引入独立 kv payload，可保留 key 到 value 的元数据，方便调试工具和调试查询。
 
 ## 与索引和预热的关系
 

docs/guides/table-types.md

@@ -52,8 +52,8 @@
 ```csharp
 DTGameConfig.MaxLevel
 DTGameConfig.EnablePvp
-DataTableManager.GetDataTable<DTGameConfig>()?.GetValue<int>("MaxLevel")
-DataTableManager.GetDataTable<DTGameConfig>()?.TryGetValue("EnablePvp", out bool? enablePvp)
+DataTableManager.GetCached<DTGameConfig>()?.GetValue<int>("MaxLevel")
+DataTableManager.GetCached<DTGameConfig>()?.TryGetValue("EnablePvp", out bool? enablePvp)
 ```
 
 当前校验与生成规则：

docs/planning/agent-engineering-review-2026-07.md

@@ -29,17 +29,17 @@
 
 ### 2.1 合理之处
 
-1. **覆盖面较完整**：当前 Agent 指令包含项目定位、核心组件、生成器结构、常用命令、Unity 说明、测试命令和兼容 API，对新 Agent 有较好的启动帮助。
+1. **覆盖面较完整**：当前 Agent 指令包含项目定位、核心组件、生成器结构、常用命令、Unity 说明、测试命令和历史兼容 API，对新 Agent 有较好的启动帮助。
 2. **核心方向与代码基本一致**：异步加载、`GetCached`、LRU 估算缓存、`IDataSource`、`PreheatAsync`、Hook、并发安全等能力在测试与 README 中均能找到对应证据。
 3. **面向生成器和运行时双域**：文档同时描述 Excel 生成链路与运行时加载链路，符合 DataTables 既是生成器又是运行时库的项目特点。
-4. **保留兼容信息**：旧回调 API、`GetDataTable*`、`CreateDataTable*` 等兼容入口被提示为旧路径，能减少 Agent 破坏性重构风险。
+4. **保留兼容信息**：旧回调 API、`GetDataTable*`、`CreateDataTable*` 等兼容入口已经进入破坏性清理范围，后续 Agent 应避免恢复这些冗余入口。
 
 ### 2.2 不准确或容易误导的内容
 
 | 问题 | 现状 | 风险 | 建议 |
 | --- | --- | --- | --- |
 | 性能收益口径过强 | `30-50%内存优化`、`90%性能提升潜力`、`零延迟` 等表述缺少基准链接 | Agent 可能把目标当成已验证事实，继续扩写宣传性代码或文档 | 改成“目标/预期/需 benchmark 证明”，并链接 `docs/performance` 或 benchmark 命令 |
-| API 名称漂移 | Agent 文档示例使用 `EnableMemoryManagement(50)`，README 强调 `EnableEstimatedMemoryBudget(50)` | Agent 可能在新代码中偏向旧别名或不准确命名 | Agent 文档应以 README 当前推荐 API 为准，旧别名放兼容区 |
+| API 名称漂移 | Agent 文档示例使用 `EnableMemoryManagement(50)`，README 强调 `EnableEstimatedMemoryBudget(50)` | Agent 可能在新代码中偏向旧别名或不准确命名 | Agent 文档应以 README 当前推荐 API 为准，不再提供旧别名示例 |
 | 数据源抽象描述过时 | `IDataSource` 被描述为“文件系统、网络、自定义数据源”，但当前 README 已强调可组合装饰器与 payload 缓存边界 | Agent 对数据源管线的缓存/压缩/版本边界理解不足 | 增加“数据源管线任务必须先看 docs/guides/data-source-pipeline.md” |
 | 生成器架构描述偏粗 | 只描述 T4、并行 Excel、二进制序列化，缺少 v3 schema hash、结构化 header、注册式 parser 等当前重点 | Agent 修改生成器时容易绕开新分层 | 增加 Schema/Validation/Serialization/Diagnostics 任务路由 |
 | Unity 镜像风险不足 | README 明确 `src/DataTables` 是源，Unity 镜像由构建同步；Agent 文档只说 Unity 路径 | Agent 可能直接编辑 Unity 镜像 | 明确禁止直接编辑 Unity runtime 镜像，除非同步机制本身变更 |
@@ -106,7 +106,7 @@ Unity 与服务端双运行时的核心差异在于线程、I/O、平台文件
 
 3. **同步当前推荐 API**
    - 主示例使用 `EnableEstimatedMemoryBudget`。
-   - `EnableMemoryManagement`、旧回调 API、`GetDataTable*` 放在兼容章节。
+   - 删除 `EnableMemoryManagement`、旧回调 API、`GetDataTable*` 等兼容章节。
    - 验收：新代码示例不再优先展示旧别名。
 
 4. **补充 Unity 镜像与 T4 约束**

sandbox/ConsoleApp/Generated/DRDataTableSample.cs

@@ -154,7 +154,7 @@ protected override void OnDataRowsRemoved()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static DRDataTableSample? GetById(string dataTableName, int id)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index1.TryGetValue(id, out var result) == true ? result : null;
     }
 
@@ -164,7 +164,7 @@ protected override void OnDataRowsRemoved()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool TryGetById(string dataTableName, int id, out DRDataTableSample? result)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         result = null;
         return table != null && table.m_Index1.TryGetValue(id, out result);
     }
@@ -175,23 +175,18 @@ public static bool TryGetById(string dataTableName, int id, out DRDataTableSampl
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool ContainsId(string dataTableName, int id)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index1.ContainsKey(id) == true;
     }
 
-    [Obsolete("Use GetById instead.")]
-    [EditorBrowsable(EditorBrowsableState.Never)]
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public static DRDataTableSample? GetRowById(int id) => GetById(id);
-
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static DRDataTableSample? GetByColor(ConsoleApp.ColorT color) => GetByColor(string.Empty, color);
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static DRDataTableSample? GetByColor(string dataTableName, ConsoleApp.ColorT color)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index2.TryGetValue(color, out var result) == true ? result : null;
     }
 
@@ -201,7 +196,7 @@ public static bool ContainsId(string dataTableName, int id)
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool TryGetByColor(string dataTableName, ConsoleApp.ColorT color, out DRDataTableSample? result)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         result = null;
         return table != null && table.m_Index2.TryGetValue(color, out result);
     }
@@ -212,23 +207,18 @@ public static bool TryGetByColor(string dataTableName, ConsoleApp.ColorT color,
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool ContainsColor(string dataTableName, ConsoleApp.ColorT color)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index2.ContainsKey(color) == true;
     }
 
-    [Obsolete("Use GetByColor instead.")]
-    [EditorBrowsable(EditorBrowsableState.Never)]
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public static DRDataTableSample? GetRowByColor(ConsoleApp.ColorT color) => GetByColor(color);
-
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static DRDataTableSample? GetByIdAndInt16Value(int id, short int16Value) => GetByIdAndInt16Value(string.Empty, id, int16Value);
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static DRDataTableSample? GetByIdAndInt16Value(string dataTableName, int id, short int16Value)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index3.TryGetValue((id, int16Value), out var result) == true ? result : null;
     }
 
@@ -238,7 +228,7 @@ public static bool ContainsColor(string dataTableName, ConsoleApp.ColorT color)
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool TryGetByIdAndInt16Value(string dataTableName, int id, short int16Value, out DRDataTableSample? result)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         result = null;
         return table != null && table.m_Index3.TryGetValue((id, int16Value), out result);
     }
@@ -249,23 +239,18 @@ public static bool TryGetByIdAndInt16Value(string dataTableName, int id, short i
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool ContainsIdAndInt16Value(string dataTableName, int id, short int16Value)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index3.ContainsKey((id, int16Value)) == true;
     }
 
-    [Obsolete("Use GetByIdAndInt16Value instead.")]
-    [EditorBrowsable(EditorBrowsableState.Never)]
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public static DRDataTableSample? GetRowByIdAndInt16Value(int id, short int16Value) => GetByIdAndInt16Value(id, int16Value);
-
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static IReadOnlyList<DRDataTableSample>? GetManyByNameAndBoolValue(string name, bool boolValue) => GetManyByNameAndBoolValue(string.Empty, name, boolValue);
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static IReadOnlyList<DRDataTableSample>? GetManyByNameAndBoolValue(string dataTableName, string name, bool boolValue)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index4.TryGetValue((name, boolValue), out var result) == true ? result : null;
     }
 
@@ -275,23 +260,18 @@ public static bool ContainsIdAndInt16Value(string dataTableName, int id, short i
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool ContainsNameAndBoolValue(string dataTableName, string name, bool boolValue)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index4.ContainsKey((name, boolValue)) == true;
     }
 
-    [Obsolete("Use GetManyByNameAndBoolValue instead.")]
-    [EditorBrowsable(EditorBrowsableState.Never)]
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public static List<DRDataTableSample>? GetRowsGroupByNameAndBoolValue(string name, bool boolValue) => GetManyByNameAndBoolValue(name, boolValue) as List<DRDataTableSample>;
-
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static IReadOnlyList<DRDataTableSample>? GetManyByName(string name) => GetManyByName(string.Empty, name);
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static IReadOnlyList<DRDataTableSample>? GetManyByName(string dataTableName, string name)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index5.TryGetValue(name, out var result) == true ? result : null;
     }
 
@@ -301,15 +281,10 @@ public static bool ContainsNameAndBoolValue(string dataTableName, string name, b
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static bool ContainsName(string dataTableName, string name)
     {
-        var table = DataTableManager.GetDataTableInternal<DTDataTableSample>(dataTableName);
+        var table = DataTableManager.GetCached<DTDataTableSample>(dataTableName);
         return table?.m_Index5.ContainsKey(name) == true;
     }
 
-    [Obsolete("Use GetManyByName instead.")]
-    [EditorBrowsable(EditorBrowsableState.Never)]
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public static List<DRDataTableSample>? GetRowsGroupByName(string name) => GetManyByName(name) as List<DRDataTableSample>;
-
     #endregion
 }