docs: improve AssetFolderSpec and AddressablesLabelSpec standards

- AssetFolderSpec.md:
  - Add §12 Editor Tools Reference with all creation/scene/Addressables tools
  - Expand §10 workflows: add Weapon, Skill, Charm, Player Form, VFX (with editor tool refs)
  - Update §10.1 Enemy workflow to reference EnemyDataWindow
  - Update §11 forbidden list to include bypassing editor creation tools
  - Add §13 TOC entry
- AddressablesLabelSpec.md:
  - Bump version to 1.1
  - Reference AddressableRules.cs in header
  - Add §7 Tooling & Automation (Rule Sync workflow, batch workflow, tool table)
  - Update §6 new-label steps to include AddressableRules.cs update step

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
2026-05-20 11:31:21 +08:00
parent c88d2d0549
commit 442d4c9cfc
2 changed files with 186 additions and 16 deletions

View File

@@ -1,9 +1,9 @@
# Addressables Label标签命名与使用规范
> **版本**1.0
> **版本**1.1
> **创建日期**2026-05
> **适用范围**`Assets/_Game/` 目录下所有注册到 Addressables 的资产
> **关联文档**`Standards/AssetFolderSpec.md §8`、`Scripts/Core/Assets/AddressKeys.cs`
> **关联文档**`Standards/AssetFolderSpec.md §8`、`Scripts/Core/Assets/AddressKeys.cs`、`Scripts/Editor/Addressables/AddressableRules.cs`
---
@@ -15,6 +15,7 @@
4. [AddressKeys.cs 常量对照](#4-addresskeyscs-常量对照)
5. [使用规范与禁止行为](#5-使用规范与禁止行为)
6. [新增 Label 决策流程](#6-新增-label-决策流程)
7. [工具链与自动化](#7-工具链与自动化)
---
@@ -255,8 +256,62 @@ await Addressables.DownloadDependenciesAsync("Preload", false);
新增 Label 的执行步骤:
1. 在 AddressKeys.Labels 类中添加 public const string {Name} = "{Name}";
2. 在 Addressables Groups 窗口 → Label 列表中创建同名标签
3. 在本文档 §2 Label 清单中追加说明行
4. 在本文档 §3 对应资产类型的表格中标注
5. 运行 AddressKeyValidator 验证无遗漏
2. 在 AddressableRules.cs 的 PrefixLabelMap / ExactLabelMap 中添加对应映射规则
3. 在 Addressables Groups 窗口 → Label 列表中创建同名标签
4. 在本文档 §2 Label 清单中追加说明行
5. 在本文档 §3 对应资产类型的表格中标注
6. 运行 Rule Sync菜单 BaseGames → Addressables → Rule SyncScan 验证无遗漏
7. 运行 AddressKeyValidator菜单 BaseGames → Verification → Validate Address Keys确认
```
---
## 7. 工具链与自动化
### 7.1 规则权威来源
所有分组与标签的映射规则**集中定义**于:
```
Assets/_Game/Scripts/Editor/Addressables/AddressableRules.cs
```
- `PrefixGroupMap` — 地址前缀 → Group 名称
- `PrefixLabelMap` — 地址前缀 → Label 列表(更具体的前缀排在前面)
- `ExactLabelMap` — 精确地址 → Label 列表(覆盖前缀规则的特殊情况)
**修改规则时只改 `AddressableRules.cs` 一处**,两个工具(`AddressableBatchTool``AddressableRuleSyncWindow`)均从此处读取,保证一致性。
### 7.2 日常标签维护工作流
```
新建/更新资产后:
1. 打开 Rule Sync 窗口(菜单 BaseGames → Addressables → Rule Sync
2. 点击 [Scan All] — 扫描所有 Addressable 条目与期望规则的差异
3. 查看报告:
- Group Mismatch — 资产在错误的分组
- Label Missing — 缺少应有标签
- Label Extra — 存在不应有的标签
4. 点击 [Fix All] 或逐条点击 [Fix] 自动修复
5. 可选:点击 [Export CSV] 导出差异报告存档
6. 运行 Validate Address Keys 做最终验证
```
### 7.3 批量注册工作流(新增大量资产)
```
1. 将资产按命名前缀放置到正确目录(见 AssetFolderSpec.md §2§4
2. 打开 Addressable Batch Tool菜单 BaseGames → Tools → Addressable Batch Tool
3. 切换到 "② 文件夹批量" 标签,选择目标文件夹,点击 [Register Folder]
4. 切换到 "① 同步 AddressKeys" 标签,点击 [Scan],为新注册的资产补充 AddressKeys.cs 常量
5. 返回 Rule Sync 窗口执行 Scan → Fix All 统一校正 Group / Label
6. 运行 Validate Address Keys 验证
```
### 7.4 工具一览
| 工具 | 菜单路径 | 核心功能 |
|------|---------|---------|
| **Rule Sync** | `BaseGames → Addressables → Rule Sync` | 扫描 + 修复分组/标签不合规条目;导出 CSV |
| **Addressable Batch Tool** | `BaseGames → Tools → Addressable Batch Tool` | 三标签AddressKeys 同步 / 文件夹批量注册 / Selection 注册 |
| **Validate Address Keys** | `BaseGames → Verification → Validate Address Keys` | 验证 AddressKeys.cs 所有常量均已在 Addressables 注册,构建前自动触发 |