fix: ensure only string type ids are registered to metaHashMap

docs/changelog/v2.7-upgrade-guide.md

@@ -361,6 +361,95 @@ const register = {
 }
 ```
 
+#### 3.3 仅支持在第一层声明（子层声明不会生效）
+
+自 v2.7 起，我们只读取注册表对象的“第一层”。只有第一层的键会被注册进 `metaHashMap`。
+
+也就是说：把插件/配置项写在子层（无论是把唯一 ID 放到某个插件的子属性里，还是通过 `metas` 往里塞）都不会被注册，`getMergeMeta`/`getMergeMetaByType`/`getAllMergeMeta` 也就找不到它们。
+
+简而言之：请把所有需要生效的插件/配置项，都放到注册表的第一层来声明。
+
+错误示例（不会生效）：
+```javascript
+import { META_APP } from '@opentiny/tiny-engine'
+import testMeta from './testMeta'
+
+export default {
+  // 1) 在子层直接再次声明插件/配置项（无效，不会注册到 metaHashMap）
+  [META_APP.Materials]: {
+    'engine.plugins.test': testMeta
+  },
+
+  // 2) 通过 metas 在子层注入（无效，不会注册到 metaHashMap）
+  [META_APP.Materials]: {
+    options: {
+      displayComponentIds: ['engine.plugins.test'],
+      metas: [testMeta]
+    }
+  }
+}
+```
+
+正确示例（第一层声明 + 通过 ID 引用）：
+```javascript
+import { META_APP } from '@opentiny/tiny-engine'
+import testMeta from './testMeta' // testMeta.id = 'engine.plugins.test'
+
+export default {
+  // 作为第一层键单独注册
+  [testMeta.id]: testMeta,
+
+  // 在需要的插件或布局中通过 ID 引用
+  [META_APP.Materials]: {
+    options: {
+      displayComponentIds: ['engine.plugins.test']
+    }
+  }
+}
+```
+
+适用范围：所有插件与配置项都遵循该规则。用户注册表只支持：
+- 把已有的插件/配置项设为 `false`（删除默认）；
+- 在第一层新增插件/配置项；
+- 在第一层用相同 ID 覆盖默认配置。
+
+##### 物料插件（Materials 插件）迁移建议
+
+如果你旧版本是在 `Materials` 插件内部（例如 `Materials.metas` 或把自定义 ID 放到 `Materials` 的子属性里）扩展物料插件，请按下面方式迁移：
+
+错误示例（不会生效）：
+```javascript
+import { META_APP } from '@opentiny/tiny-engine'
+import MyMaterial from './MyMaterial' // MyMaterial.id = 'engine.plugins.myMaterial'
+
+export default {
+  [META_APP.Materials]: {
+    // 通过 metas 向物料插件塞入物料项（无效）
+    options: {
+      metas: [MyMaterial]
+    }
+  }
+}
+```
+
+正确示例（第一层声明 + 在物料插件中引用）：
+```javascript
+import { META_APP } from '@opentiny/tiny-engine'
+import MyMaterial from './MyMaterial' // MyMaterial.id = 'engine.plugins.myMaterial'
+
+export default {
+  // 1) 物料项作为第一层键单独注册
+  [MyMaterial.id]: MyMaterial,
+
+  // 2) 在 Materials 插件中通过 ID Tab 组件显示
+  [META_APP.Materials]: {
+    options: {
+      displayComponentIds: ['engine.plugins.myMaterial']
+    }
+  }
+}
+```
+
 ### 4. 注册表热修复功能
 
 v2.7 版本新增了注册表热修复（hotfix）功能，可以通过覆盖官方插件的特定函数或模板，实现紧急 bug 修复，而不需要等待官方版本发布。

packages/register/src/common.ts

@@ -90,7 +90,7 @@ const genDefaultHashMap = (registry: any) => {
     if (typeof value === 'object' && value && !isRef(value)) {
       const { id } = value
       // 如果匹配到了id，说明是元服务配置，对元服务配置做读取和写入
-      if (id && key !== 'metaData') {
+      if (typeof id === 'string' && id && key !== 'metaData') {
         registryApiAndOptionsMap(id, value)
         metaHashMap.set(id, value)
       }