daoqi/erqiwang_youle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

二七王：精灵常量再优化为 View → group 容器 → 精灵

Browse Source 
group 与其名下精灵合并为 { id: 群组常量, 精灵键: id, ... }，
所属关系由结构表达而非注释；拿到 group 对象即可 showGroup 并遍历其精灵。

SpriteIndex 随之支持 groupIdOf：精灵与群组 ID 被结构绑定，
显隐走群组时可机械查出。校验增至 5 处显式失败（重复键、精灵值非数字、
View 下混入标量键、group 缺 id、查不到的键）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
joywayer
2026-08-26 20:51:18 +08:00
co-authored by Claude Opus 5
parent 5ac445d08d
commit 8b579896b2
2 changed files with 179 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-08-26-二七王前端A-地基与逻辑层.md
+151 -74
View File
@@ -1533,17 +1533,23 @@ EOF
```js
EQW_Sprites.<ViewName> = {
Layer: <图层常量>, // 该 View 用到的图层；用到多个时写 Layer1 / Layer2 …
Group: <群组常量>, // 该 View 用到的群组；用到多个时写 Group1 / Group2 …
Layer: <图层常量>, // 该 View 用到的图层；用到多个时写 Layer1 / Layer2 …
<精灵键名>: <精灵ID>, // 精灵只写 id；所属 Layer/Group 写在注释里
...
<GroupName>: { // 一个群组容器：群组 ID + 它名下的全部精灵
id: <群组常量>,
<精灵键名>: <精灵ID>,
...
},
<另一个GroupName>: { id: ..., ... }
};
```
- **保留键约定**（`SpriteIndex` 与守卫测试据此机械区分）：View 内键名为 `Layer` / `Group`，或以二者为前缀（`Layer1`、`Group2`…）的，是 **View 级声明**；**其余键一律是精灵 id**。
- 精灵条目**不重复写 Layer/Group**——它们扁平放在 View 定义下，精灵的所属关系在**注释**里说明。
- 键名与 ID 一律照抄清单 §5 各表，**不改名、不改号**（Task 11 的 `SpriteIndex` 与 Task 12 的布局配置都按键名引用）
- **结构约定**（`SpriteIndex` 与守卫测试据此机械区分）：
- View 内：键名 `Layer`（或 `Layer1`/`Layer2`…）是 **View 级声明**；**其余键的值必须是对象**，即一个 group 容器。View 内不允许出现别的标量键。
- group 容器内：键名 `id` 是**群组 ID**；**其余键一律是精灵 id（数字）**。
- **精灵的所属群组由结构本身表达**，注释里不必再重复写属于哪个 group；但仍要写类型（图片/文字）+ 用途 + 资源键 + 帧说明。
- group 容器名用大驼峰、体现它是哪一块（`TopInfo`、`LeftMark`、`Footer`、`HandCards`…），不必与群组常量同名。
- 键名与 ID 一律照抄清单 §5 各表，**不改名、不改号**（Task 11 的 `SpriteIndex` 与 Task 12 的布局配置都按键名引用）。**精灵键名全局唯一**——索引器会把整棵树展平成一张扁平表，重名照样报错。
- [ ] **Step 1: 写 `Sprites_Table.js`**
@@ -1562,30 +1568,39 @@ var EQW_Sprites = EQW_Sprites || {};
//顶部信息条：主 / 叫分 / 抓分 三列
EQW_Sprites.TopInfoView = {
Layer: EQW_Layers.TABLE_STATIC, //101
Group: EQW_Groups.TOP_INFO, //201
Layer: EQW_Layers.TABLE_STATIC, //101
TOP_INFO_BG: 1001, //图片：三列表格底，资源 PANEL_TOP_INFO
TOP_SUIT_ICON: 1002, //图片：「主」列花色，资源 SUIT_ICON_S，帧 = flower(1方块 2梅花 3红心 4黑桃)
TOP_CALL_TEXT: 1003, //文字：叫分数值
TOP_CALL_BADGE_BG: 1004, //图片：叫分角标底，资源 BADGE_MULTIPLE 帧1
TOP_CALL_BADGE_TEXT: 1005, //文字：「N子」
TOP_GRADE_TEXT: 1006, //文字：抓分数值
TOP_GRADE_BADGE_BG: 1007, //图片：抓分角标底，资源 BADGE_MULTIPLE 帧2
TOP_GRADE_BADGE_TEXT: 1008 //文字：「N倍」，取 Math.abs(curmultiple)（T-16/S-8）
TopInfo: {
id: EQW_Groups.TOP_INFO, //201
TOP_INFO_BG: 1001, //图片：三列表格底，资源 PANEL_TOP_INFO
TOP_SUIT_ICON: 1002, //图片：「主」列花色，资源 SUIT_ICON_S，帧 = flower(1方块 2梅花 3红心 4黑桃)
TOP_CALL_TEXT: 1003, //文字：叫分数值
TOP_CALL_BADGE_BG: 1004, //图片：叫分角标底，资源 BADGE_MULTIPLE 帧1
TOP_CALL_BADGE_TEXT: 1005, //文字：「N子」
TOP_GRADE_TEXT: 1006, //文字：抓分数值
TOP_GRADE_BADGE_BG: 1007, //图片：抓分角标底，资源 BADGE_MULTIPLE 帧2
TOP_GRADE_BADGE_TEXT: 1008 //文字：「N倍」，取 Math.abs(curmultiple)（T-16/S-8）
}
};
//三家玩家位附加标记：跨三个群组，故写 Group1/2/3
//三家玩家位附加标记：跨三个群组，就是三个 group 容器
EQW_Sprites.PlayerMarkView = {
Layer: EQW_Layers.TABLE_STATIC, //101
Group1: EQW_Groups.P_LEFT_MARK, //202 左上家
Group2: EQW_Groups.P_RIGHT_MARK, //203 右上家
Group3: EQW_Groups.P_SELF_MARK, //204 自己
Layer: EQW_Layers.TABLE_STATIC, //101
//—— Group1 左上家（群组 202）——
P_LEFT_BANKER: 1100, //图片：「庄」印章，资源 MARK_BANKER
P_LEFT_ZHU_BG: 1101, //图片：「主N」角标底，资源 BADGE_ZHU_PAIR 帧1
// ... 其余按清单 §5.1 续
LeftMark: {
id: EQW_Groups.P_LEFT_MARK, //202 左上家
P_LEFT_BANKER: 1100, //图片：「庄」印章，资源 MARK_BANKER
P_LEFT_ZHU_BG: 1101 //图片：「主N」角标底，资源 BADGE_ZHU_PAIR 帧1
// ... 其余按清单 §5.1 续
},
RightMark: {
id: EQW_Groups.P_RIGHT_MARK, //203 右上家
P_RIGHT_BANKER: 1110,
P_RIGHT_ZHU_BG: 1111
// ... 其余按清单 §5.1 续
}
// ... SelfMark（群组 204）同理
};
// ... 其余 View 按清单 §5.1 续：亮牌条（群组 206，1030–1031）、
@@ -1641,63 +1656,83 @@ EOF
**Interfaces:**
- Consumes: `EQW_Sprites`（Task 10）
- Produces: 全局 `EQW_SpriteIndex`，含 `build(spriteTree)` → `{ 键名: 精灵ID }`、`idOf(key)` → `number`（查不到抛错）、`init()`（用 `EQW_Sprites` 建好内部索引）
- Produces: 全局 `EQW_SpriteIndex`，含
- `build(spriteTree)` → `{ 键名: 精灵ID }`
- `buildGroupMap(spriteTree)` → `{ 键名: 群组ID }`
- `init(spriteTree)`（默认用 `EQW_Sprites` 建好两张内部索引）
- `idOf(key)` → `number`（查不到抛错）
- `groupIdOf(key)` → `number`（查不到抛错）
> 布局配置里 `attach.target` 写的是**键名**而非数字 ID（清单 §6.1：「`target` 一律写键名，ID 回填时只改一处映射表」），而精灵常量是按 View 组织的，故需要这张扁平索引。
> 布局配置里 `attach.target` 写的是**键名**而非数字 ID（清单 §6.1：「`target` 一律写键名，ID 回填时只改一处映射表」），而精灵常量是按 View → group 组织的，故需要这张扁平索引。
> `groupIdOf` 是新结构带来的收益：group 容器把精灵与它的群组 ID 绑在一起，于是「某个精灵属于哪个群组」可以机械查出——显隐走群组时（前端红线：显隐由组件的 `showXxx`/`hideXxx` 控制）不必再手工对照。
> **结构约定**：View 内 `Layer`（含 `Layer1`/`Layer2`…）是 View 级声明、跳过；其余键的值必须是**对象**（group 容器），否则报错。group 容器内 `id` 是群组 ID、跳过；其余键一律是精灵 id，**值必须是数字**，否则报错。
> **重复键必须报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。
> **保留键约定**：View 内键名为 `Layer` / `Group` 或带数字后缀（`Layer1`、`Group2`…）的是 View 级声明，跳过不进索引；其余键一律是精灵 id。
> **值必须是数字**：View 级声明与精灵条目在结构上同级、只靠键名区分，所以把「值不是数字」当作错误抓出来——否则写错前缀（如 `Grup: 201`）会静默变成一个假精灵。
- [ ] **Step 1: 写失败的测试 `client/tests/test_spriteindex.js`**
```js
// View 组织的精灵常量 → 扁平键名索引
// View → group → 精灵 的常量树 → 扁平键名索引
const { load, throws } = require('./_load');
const t = require('./_assert')();
load('client/js/01_SubGame/codes/core/SpriteIndex.js');
// ---- 展平：Layer/Group 声明跳过，精灵进索引 ----
// ---- 展平：Layer 与 group 的 id 都不进索引，精灵进 ----
const tree = {
TopInfoView: {
Layer: 101,
Group: 201,
BTN_A: 1001,
BTN_B: 1002
TopInfo: { id: 201, BTN_A: 1001, BTN_B: 1002 }
},
PlayerMarkView: {
Layer: 101,
Group1: 202,
Group2: 203,
P_LEFT_BANKER: 1100,
P_RIGHT_BANKER: 1110
Layer: 101,
LeftMark: { id: 202, P_LEFT_BANKER: 1100 },
RightMark: { id: 203, P_RIGHT_BANKER: 1110 }
}
};
t.eq('展平结果', EQW_SpriteIndex.build(tree),
{ BTN_A: 1001, BTN_B: 1002, P_LEFT_BANKER: 1100, P_RIGHT_BANKER: 1110 });
// ---- View 级声明不进索引（含带数字后缀的）----
// ---- Layer 与 group 的 id 不进索引 ----
const flat = EQW_SpriteIndex.build(tree);
t.eq('Layer 不进索引', flat.Layer, undefined);
t.eq('Group 不进索引', flat.Group, undefined);
t.eq('Group1 不进索引', flat.Group1, undefined);
t.eq('Group2 不进索引', flat.Group2, undefined);
t.eq('group 的 id 不进索引', flat.id, undefined);
// ---- 群组映射：精灵 → 它所属的群组 ID ----
t.eq('群组映射', EQW_SpriteIndex.buildGroupMap(tree),
{ BTN_A: 201, BTN_B: 201, P_LEFT_BANKER: 202, P_RIGHT_BANKER: 203 });
// ---- 多个 Layer 的 View（Layer1/Layer2）也正确跳过 ----
const multiLayer = {
OverlayView: { Layer1: 104, Layer2: 105, Bar: { id: 230, TIP_BG: 1750 } }
};
t.eq('多 Layer 声明跳过', EQW_SpriteIndex.build(multiLayer), { TIP_BG: 1750 });
// ---- 反面：重复键报错，不静默覆盖 ----
const dupTree = {
ViewA: { Layer: 101, Group: 201, SAME: 1001 },
ViewB: { Layer: 102, Group: 202, SAME: 1002 }
ViewA: { Layer: 101, G1: { id: 201, SAME: 1001 } },
ViewB: { Layer: 102, G2: { id: 202, SAME: 1002 } }
};
t.eq('重复键报错', throws(() => EQW_SpriteIndex.build(dupTree)), true);
// ---- 反面：精灵值不是数字要报错（防写错保留键前缀变成假精灵）----
const badTree = { ViewA: { Layer: 101, Group: 201, NESTED: { id: 1001 } } };
t.eq('值非数字报错', throws(() => EQW_SpriteIndex.build(badTree)), true);
// ---- 反面：精灵值不是数字要报错 ----
const badValue = { ViewA: { Layer: 101, G1: { id: 201, NESTED: { x: 1 } } } };
t.eq('精灵值非数字报错', throws(() => EQW_SpriteIndex.build(badValue)), true);
// ---- idOf：查得到 / 查不到抛错 ----
// ---- 反面：View 下混入标量键（不是 group 容器）要报错 ----
// 例如把群组 ID 误写成 View 级的 `Group: 201`，而不是包进 group 容器
const strayScalar = { ViewA: { Layer: 101, Group: 201, G1: { id: 202, BTN: 1001 } } };
t.eq('View 下混入标量键报错', throws(() => EQW_SpriteIndex.build(strayScalar)), true);
// ---- 反面：group 容器缺 id 要报错 ----
const noGroupId = { ViewA: { Layer: 101, G1: { BTN: 1001 } } };
t.eq('group 缺 id 报错', throws(() => EQW_SpriteIndex.build(noGroupId)), true);
// ---- idOf / groupIdOf：查得到 / 查不到抛错 ----
EQW_SpriteIndex.init(tree);
t.eq('idOf 查到', EQW_SpriteIndex.idOf('BTN_A'), 1001);
t.eq('groupIdOf 查到', EQW_SpriteIndex.groupIdOf('P_RIGHT_BANKER'), 203);
t.eq('idOf 查不到抛错', throws(() => EQW_SpriteIndex.idOf('NOT_EXIST')), true);
t.eq('groupIdOf 查不到抛错', throws(() => EQW_SpriteIndex.groupIdOf('NOT_EXIST')), true);
// ---- 空树 ----
t.eq('空树', EQW_SpriteIndex.build({}), {});
@@ -1731,47 +1766,80 @@ Expected: `EQW_SpriteIndex is not defined`。
///////////////////////////////////////////////////////////////
////////// EQW_SpriteIndex: 精灵键名 → ID 扁平索引 /////////////
///////////////////////////////////////////////////////////////
// 精灵常量以 UI View 为组织单位：Layer / Group 扁平声明在 View 下，
// 精灵只写 id（所属关系在注释里）。而布局配置里 attach.target 写的是
// 【键名】（清单 §6.1：ID 回填时只改一处映射表），故需把 View 结构
// 展平成 { 键名: 精灵ID } 供求解器查用。
// 【显式失败】重复键、值非数字、查不到的键一律抛错——静默覆盖会让某个
// 界面指向另一个界面的精灵，且极难排查（工程总则 §7）。
// 精灵常量以 UI View 为组织单位，View 下是一个个 group 容器：
// EQW_Sprites.XxxView = { Layer: 图层, GroupName: { id: 群组, 精灵键: id, ... } }
// 而布局配置里 attach.target 写的是【键名】（清单 §6.1：ID 回填时只改一处
// 映射表），故需把这棵树展平成 { 键名: 精灵ID } 供求解器查用；
// group 容器把精灵与群组 ID 绑在一起，顺带能给出 { 键名: 群组ID }。
// 【显式失败】重复键、值非数字、结构不合法、查不到的键一律抛错——静默覆盖
// 会让某个界面指向另一个界面的精灵，且极难排查（工程总则 §7）。
var EQW_SpriteIndex = EQW_SpriteIndex || {
_index: null,
_groupMap: null,
//View 级保留键：Layer / Group，可带数字后缀（Layer1、Group2…）
_isReserved: function (key) {
return (/^Layer\d*$/).test(key) || (/^Group\d*$/).test(key);
//View 级保留键：Layer，可带数字后缀（Layer1、Layer2…）
_isLayerKey: function (key) {
return (/^Layer\d*$/).test(key);
},
//展平：遍历 树 → View → 键
build: function (spriteTree) {
var index = {};
//遍历 树 → View → group → 精灵，对每个精灵回调 fn(key, spriteId, groupId)
_walk: function (spriteTree, fn) {
for (var viewName in spriteTree) {
if (!spriteTree.hasOwnProperty(viewName)) { continue; }
var view = spriteTree[viewName];
for (var key in view) {
if (!view.hasOwnProperty(key)) { continue; }
if (this._isReserved(key)) { continue; } //View 级 Layer/Group 声明
if (typeof view[key] !== 'number') {
throw new Error('[EQW_SpriteIndex] 精灵 ' + key + ' 的值不是数字（View ' +
viewName + '）——Layer/Group 声明请用保留键名 Layer* / Group*');
for (var groupName in view) {
if (!view.hasOwnProperty(groupName)) { continue; }
if (this._isLayerKey(groupName)) { continue; } //View 级图层声明
var group = view[groupName];
if (!group || typeof group !== 'object') {
throw new Error('[EQW_SpriteIndex] ' + viewName + '.' + groupName +
' 不是 group 容器（值应为对象）——图层声明请用保留键名 Layer*');
}
if (index.hasOwnProperty(key)) {
throw new Error('[EQW_SpriteIndex] 精灵键名重复: ' + key +
'（View ' + viewName + ' 与更早的定义冲突）');
if (typeof group.id !== 'number') {
throw new Error('[EQW_SpriteIndex] group 容器 ' + viewName + '.' + groupName +
' 缺少数字型的 id（群组 ID）');
}
for (var key in group) {
if (!group.hasOwnProperty(key)) { continue; }
if (key === 'id') { continue; } //群组 ID
if (typeof group[key] !== 'number') {
throw new Error('[EQW_SpriteIndex] 精灵 ' + key + ' 的值不是数字（' +
viewName + '.' + groupName + '）');
}
fn(key, group[key], group.id, viewName, groupName);
}
index[key] = view[key];
}
}
},
//展平成 { 键名: 精灵ID }
build: function (spriteTree) {
var index = {};
this._walk(spriteTree, function (key, spriteId, groupId, viewName, groupName) {
if (index.hasOwnProperty(key)) {
throw new Error('[EQW_SpriteIndex] 精灵键名重复: ' + key +
'（' + viewName + '.' + groupName + ' 与更早的定义冲突）');
}
index[key] = spriteId;
});
return index;
},
//用给定的树（默认 EQW_Sprites）建立内部索引
//展平成 { 键名: 群组ID }，供「显隐走群组」时查精灵属于哪个群组
buildGroupMap: function (spriteTree) {
var map = {};
this._walk(spriteTree, function (key, spriteId, groupId) {
map[key] = groupId;
});
return map;
},
//用给定的树（默认 EQW_Sprites）建立两张内部索引
init: function (spriteTree) {
this._index = this.build(spriteTree || EQW_Sprites);
var tree = spriteTree || EQW_Sprites;
this._index = this.build(tree);
this._groupMap = this.buildGroupMap(tree);
return this._index;
},
@@ -1782,6 +1850,15 @@ var EQW_SpriteIndex = EQW_SpriteIndex || {
throw new Error('[EQW_SpriteIndex] 未知精灵键名: ' + key);
}
return this._index[key];
},
//按键名取它所属的群组 ID
groupIdOf: function (key) {
if (!this._groupMap) { throw new Error('[EQW_SpriteIndex] 尚未 init()'); }
if (!this._groupMap.hasOwnProperty(key)) {
throw new Error('[EQW_SpriteIndex] 未知精灵键名: ' + key);
}
return this._groupMap[key];
}
};
```
docs/superpowers/specs/2026-08-26-二七王前端A-地基与逻辑层-design.md
+28 -8
View File
@@ -104,7 +104,7 @@ client/tests/
| `Groups.js` | `EQW_Groups` | 清单 §0.3 群组表 201–250 |
| `ImageResources.js` | `EQW_Images` | 清单 §3 图片资源总表，**每条按 ImageResources.template 的要求注明用途 / 帧数 / 每帧含义 / 尺寸** |
| `SoundResources.js` | `EQW_Sounds` | 清单 §4——**整节 T-20 未定**，本阶段只建文件骨架与说明注释，不臆造条目（见 §11） |
| `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8。**以 UI View 为组织单位**（一个 View 将来对应一个 `BaseComponent`）：`Layer` / `Group` 扁平声明在 View 下（用到多个时写 `Layer1`/`Group2`…），精灵只写 id、所属关系在注释里。每个精灵注明类型 / 用途 / 资源键 / 帧说明 / 所属群组 |
| `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8。**以 UI View 为组织单位**（一个 View 将来对应一个 `BaseComponent`），View 下是一个个 **group 容器**：`{ Layer: 图层, GroupName: { id: 群组, 精灵键: id, … } }`。用到多个图层时写 `Layer1`/`Layer2`。每个精灵注明类型 / 用途 / 资源键 / 帧说明 |
| `LayoutConstants.js` | `EQW_Layout` | 清单 §6.3 `textStyle` 预设、§6.4 `CARD_SIZE` 三档、座位键常量 `SELF/LEFT/RIGHT` |
| `Layout_Table.js` | `EQW_Layout` | 清单 §6.5 常驻区 + §6.6 玩家位（含气泡朝向 `arrowRight`） |
| `Layout_Cards.js` | `EQW_Layout` | 清单 §6.7 牌区（手牌单排/双排、底牌、埋牌底牌、已出牌 `bySeat`、冲关牌） |
@@ -189,20 +189,40 @@ EQW_SeatMap.toSeat(displayKey, mySeat) // → 服务端座位号
### 5.5 `SpriteIndex`
精灵常量以 UI View 为组织单位（`Layer`/`Group` 扁平声明在 View 下，精灵只写 id），而布局配置里 `attach.target` 写的是**键名**（清单 §6.1：「`target` 一律写键名而非数字 ID」）。故需一张扁平索引：
精灵常量的组织是 **View → group 容器 → 精灵**：
```js
EQW_SpriteIndex.build(spriteTree) // 遍历 树 → View → 键 → { 键名: 精灵ID }
EQW_SpriteIndex.idOf(key) // 查 ID；查不到显式抛错，不返回 undefined
EQW_Sprites.TopInfoView = {
Layer: EQW_Layers.TABLE_STATIC, // 用到多个图层时写 Layer1 / Layer2…
TopInfo: { // group 容器
id: EQW_Groups.TOP_INFO,
TOP_INFO_BG: 1001,
TOP_CALL_TEXT: 1003
}
};
```
**保留键约定**：View 内键名为 `Layer` / `Group` 或带数字后缀（`Layer1`、`Group2`…）的是 View 级声明，跳过不进索引；其余键一律是精灵 id。
而布局配置里 `attach.target` 写的是**键名**（清单 §6.1：「`target` 一律写键名而非数字 ID」），故需把这棵树展平：
**显式失败**三处（工程总则 §7）：
```js
EQW_SpriteIndex.build(spriteTree) // → { 键名: 精灵ID }
EQW_SpriteIndex.buildGroupMap(spriteTree) // → { 键名: 群组ID }
EQW_SpriteIndex.init(spriteTree) // 默认用 EQW_Sprites 建好两张索引
EQW_SpriteIndex.idOf(key) // 查精灵 ID；查不到显式抛错
EQW_SpriteIndex.groupIdOf(key) // 查它所属的群组 ID；查不到显式抛错
```
- 键名拼错时 `idOf` 立即报错，而不是把 `undefined` 传给 `SpriteManager` 静默无效；
`groupIdOf` 是这个结构带来的收益：group 容器把精灵与群组 ID 绑在一起，「某个精灵属于哪个群组」于是可以机械查出——显隐走群组时（前端红线：显隐由组件的 `showXxx`/`hideXxx` 控制）不必再手工对照。
**结构约定**：View 内 `Layer`（含 `Layer1`/`Layer2`…）是 View 级声明、跳过；其余键的值必须是**对象**（group 容器）。group 容器内 `id` 是群组 ID、跳过；其余键一律是精灵 id。
**显式失败**五处（工程总则 §7）：
- `idOf` / `groupIdOf` 键名拼错时立即报错，而不是把 `undefined` 传给 `SpriteManager` 静默无效；
- **重复键报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。同名键在不同 View 下重复由清单 §5 的键名设计避免（`PLAY_SELF_*` / `PLAY_LEFT_*` / `PLAY_RIGHT_*`）；
- **值非数字报错**——View 级声明与精灵条目在结构上同级、只靠键名区分，写错前缀（如 `Grup: 201`）会静默变成一个假精灵，故把「值不是数字」当作错误抓出来。
- **精灵值非数字报错**；
- **View 下混入标量键报错**（例如把群组 ID 误写成 View 级的 `Group: 201` 而没包进 group 容器）；
- **group 容器缺 `id` 报错**。
---