@easytwin/devkit 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@easytwin/devkit",
+  "version": "0.1.0",
+  "description": "EasyTwin DevKit 核心:lib(函数库)+ bin(easytwin 命令)双导出",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "easytwin": "./dist/bin.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "http://gitlab.prod.dtstack.cn/visdev/visApplication/easytwin-group/easytwin-sdk-plugin.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/easytwin-bootstrap/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: easytwin-bootstrap
+description: 当用户要开始使用 EasyTwin DevKit、配置应用级凭证(App ID / App Secret / Base URL)、运行 easytwin init、或校验 easytwin.config.json 是否存在/有效时使用。
+---
+
+# 初始化与凭据
+
+`easytwin init` 交互式生成项目级 `easytwin.config.json`,并把它追加进 `.gitignore`(无则创建)。
+
+## 配置契约
+
+```json
+{
+  "appId": "必填",
+  "appSecret": "必填",
+  "baseUrl": "可选,缺省官方固定域名"
+}
+```
+
+- 环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` 优先于文件(CI 与不落盘场景)。
+- 该文件含密钥,**永不入库**:`init` 已负责 gitignore,不要把它提交进版本库。
+
+## 步骤
+
+1. 若项目还没有 `easytwin.config.json`,运行 `easytwin init` 并按提示输入。
+2. 校验:`easytwin scene list` 能列出场景即凭据有效;报错则检查 appId / appSecret 或环境变量覆盖。

package/skills/easytwin-core/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: easytwin-core
+description: 当用户要理解 EasyTwin 引擎内核(类层级、RuntimeEngine 生命周期、Time/WebCanvas/相机/物理基础设施)、排查引擎级行为,或基于基类开发/扩展自定义组件时使用。对应 @easytwin/runtime 的 src/core/。
+---
+
+# 引擎内核(easytwin-runtime core)
+
+对应 npm 包 `@easytwin/runtime` 的 `src/core/` 目录:引擎本体、场景、组件基类与基础设施。写渲染功能的主流程见 `easytwin-render`;本技能是引擎核心的完整 API 参考。
+
+## 核心关系速览
+
+- `RuntimeEngine`(每 DOM 容器一个):持有 manager 注册表与 `Time`,驱动渲染循环;`engine.getManager(SceneManager)` 取 manager,`engine.mainScene` 取主场景。
+- `RuntimeScene`(一个场景):持有 THREE 场景(`sceneObject`)、相机(`camera`)、控制器(`control`)、CSS 渲染器(`cssRenderer`)、物理(`physicsScene`)、地理(`geoTransform`)。
+- manager:`ResourceManager` / `SceneManager` / `CustomComponentManager` / `EditorActionsManager` / `PhysicsManager`,均为 `AbstractManager` 子类。
+- 组件类层级:`EventEmitter` → `SceneObject` → `Component` → `VirtualRootComponent` / `VirtualChildComponent`;任意组件内 `this.scene` / `this.engine` 直达场景与引擎。
+
+## 何时读哪个 reference
+
+- 需要"RuntimeEngine 全量 API、Time、WebCanvas、SystemInfo/StatsTool"时读 `references/engine.md`
+- 需要"类层级与基类(EventEmitter/SceneObject)、如何访问 engine/scene"时读 `references/base-classes.md`
+- 需要"VirtualRootComponent / VirtualChildComponent 基类(虚拟子要素、data.children 同步、自定义属性/蓝图过滤、开发示例)"时读 `references/virtual-components.md`
+- 需要"相机体系(Camera/SceneCamera/CameraControls/focus)"时读 `references/camera.md`
+- 需要"物理体系(PhysicsManager/PhysicsScene/物理开关)"时读 `references/physics.md`
+
+组件生命周期钩子、状态/数据 API 与序列化结构分别在 `easytwin-render` 的 `references/lifecycle-events.md` 与 `references/scene-and-assets.md`,本技能不重复(虚拟子要素的序列化结构见本技能 `references/virtual-components.md`)。

package/skills/easytwin-core/references/base-classes.md

@@ -0,0 +1,32 @@
+# 类层级与基类
+
+## 类层级
+
+```
+EventEmitter(packages/eventemitter:on/off/once/emit/removeAllListeners)
+└─ SceneObject(core/base.ts:scene/engine getter,实现 ICanAccessEngine)
+   ├─ Component(core/Component.ts,抽象)
+   │  ├─ VirtualRootComponent(core/VirtualRootComponent.ts)
+   │  └─ 普通自定义组件(直接继承 Component)
+   └─ VirtualChildComponent(core/VirtualChildComponent.ts,extends SceneObject)
+```
+
+- `ICanAccessEngine`:`get/set engine`。
+- `Component` 的抽象成员与生命周期钩子(`onInitialize/onAwake/onEnable/onStart/onUpdate/onLateUpdate/onFixedUpdate/onDisable/onDestroy`)、状态/数据 API、指针/物理回调,以及 `VirtualRootComponent` / `VirtualChildComponent` 的完整说明在 `references/virtual-components.md`,本文件不重复。
+
+## 从任意位置访问引擎与场景
+
+- 组件内:`this.engine` / `this.scene`(SceneObject 提供)。
+- 场景内:`scene.engine`。
+- 引擎内:`engine.mainScene`、`engine.getManager(...)`、`engine.getManagerByName(...)`。
+- 组件查找:`scene.findRuntimeComponentById(id)` / `rootComponent.findById/ByName/ByType/ByPath`(见 easytwin-render/scene-and-assets.md)。
+
+## 组件通用成员(边界速查)
+
+- 层级:`children` / `parent`、`addChild` / `removeChild`、`traverse(cb)`。
+- 名称/可见性:`rename(name)`、`active` / `lock` / `collapsed`、`setActive/setLock/setCollapsed`(带后端同步)。
+- 查找:`findBy(cond)` / `findById` / `findByName` / `findByType` / `findByPath(path)`。
+- 编辑/预览:`startPreview/endPreview`、`startEdit/endEdit`、`editMode`、`isPreviewing` / `isEditing`。
+- 变换控制(编辑器):`onTransformControlUpdate(control, offsetMatrix)` / `onTransformControlDragEnd(control)`,由 `TwinTransformControls` 驱动(见 camera.md 末尾)。
+
+> 以上成员的逐条说明见 lifecycle-events.md;此处仅列边界便于快速定位。

package/skills/easytwin-core/references/camera.md

@@ -0,0 +1,33 @@
+# 相机体系
+
+## Camera(scene.camera)
+
+统一管理当前相机,方便做切换过渡:
+
+- `scene.camera.main`:当前生效相机(`OrthographicCamera | PerspectiveCamera`);被组件接管时指向组件自带相机。
+- `scene.camera.switchTo(camera)`:切到自定义相机(组件自带),置 `_isControlled = true`。
+- `scene.camera.switchToScene()`:切回场景相机(`SceneCamera.nativeCamera`),置 `_isControlled = false`。
+
+## SceneCamera(scene.camera._sceneCamera)
+
+- `sceneCameraMode: "perspective" | "orthographic"`:setter 同步另一模式的视口/矩阵参数,并触发 `onCameraModeChanged`。
+- `nativeCamera`(当前模式对应相机)/ `perspectiveCamera` / `orthographicCamera`。
+- `onCameraModeChanged`(`Signal`):Camera 内部监听;`_isControlled` 时忽略。
+
+## CameraControls(scene.control,readonly)
+
+- 默认相机控制器(模块 `@/control/camera_controls`,已 `install({ THREE })`),负责浏览/环绕/缩放。
+- `scene.focus(object, { distance?, duration?, focusCenter?: [number, number] })`:object 接受 `Object3D | Object3D[] | RuntimeComponent[]`(RuntimeComponent 走 `getSelectObject()`)。
+- `scene.getCameraInfo()` → `{ position, rotation, target }`(`CameraInfo`,IVector3)。
+
+## 视图与渲染
+
+- `scene.shotCanvas(): Promise<Blob | null>`(先 `update(0.1)` 再 `toBlob`);`scene.updatePixelRatio(pixelRatio?)`。
+- 坐标转换(NDC/屏幕/世界)与 2D CSS 见 easytwin-render/references/rendering-apis.md。
+
+## TwinTransformControls(编辑器变换控件)
+
+- 编辑器拖动组件时的 gizmo;`signals`:`objectChange` / `draggingChanged` / `draggingStart` / `draggingEnd` / `objectDragUpdate`。
+- `TransformPivotMode = "BoundingBoxCenter" | "IndividualOrigins"`。
+- 与组件联动:拖动中 `onTransformControlUpdate(control, offsetMatrix)`,拖动结束 `onTransformControlDragEnd(control)`(见 lifecycle-events.md)。
+- 拖动时自动 `scene.control.enabled = false`,结束后恢复。

package/skills/easytwin-core/references/engine.md

@@ -0,0 +1,88 @@
+# RuntimeEngine 与基础设施
+
+## 概览
+
+一个 `RuntimeEngine` 对应一个 DOM 容器(`engine.container`):
+
+- 注册并初始化五个 manager:`ResourceManager` / `SceneManager` / `CustomComponentManager` / `EditorActionsManager` / `PhysicsManager`;
+- 启动 `requestAnimationFrame` 渲染循环,每帧 `Time.update()` → `SceneManager.updateScene(deltaTime)`;
+- 统一提供场景切换、资源缓存、蓝图事件出口。
+
+## create 与 EngineConfiguration
+
+唯一入口 `RuntimeEngine.create(config)`(静态、异步):
+
+```ts
+const engine = await RuntimeEngine.create({
+  containerId: "twin-root",
+  baseOSSUrl: "https://assets.easyv.cloud",
+  customComponentDeps: { "@easytwin/runtime": Runtime, react: FakeReact },
+  sceneResources: [],
+  componentRels: [],
+});
+```
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `containerId` | 是 | 容器元素 id;找不到即抛 `cannot find dom with id '<id>'` |
+| `baseOSSUrl` | 是 | 服务端资产根地址;draco/ktx2/webp 等系统库 URL 由此拼出 |
+| `customComponentDeps` | 是 | 自定义组件脚本 import 的依赖表(键=模块名,值=实现) |
+| `localOSSUrl` | 否 | 本地资产根地址;非空时自定义组件脚本优先读本地 |
+| `sceneResources` | 否 | 场景资源清单 `ListSceneResourceVo[]`,默认 [] |
+| `componentRels` | 否 | 组件引用关系 `GetComponentRelVo[]`,默认 [] |
+| `enableResourcePersistence` | 否 | ResourceManager 是否用 localforage 持久化,默认 false |
+
+静态共享:`RuntimeEngine.sceneResources` / `RuntimeEngine.componentRels`(create 时从 config 写入)。
+
+## manager 访问
+
+- `engine.getManager(SceneManager)` — 按类;`engine.getManagerByName("SceneManager")` — 按名。
+- manager 基类 `AbstractManager`:`name` / `engine` / `init()` / `destroy()`。
+
+## 场景与组件便捷入口
+
+- `engine.mainScene` = `getManager(SceneManager).mainScene`(可能 undefined)。
+- `engine.createComponent(params, sync?)` / `engine.createModelComponent(name, url, sync?, onProgress?)`:转发到 mainScene,参数见 easytwin-render/references/scene-and-assets.md。
+
+## 时间(engine.time)
+
+`Time`:
+
+| 成员 | 说明 |
+| --- | --- |
+| `deltaTime` | 本帧增量(秒),受 `maximumDeltaTime` 与 `timeScale` 钳制 |
+| `actualDeltaTime` | 真实帧增量,不受钳制 |
+| `elapsedTime` / `actualElapsedTime` | 引擎启动以来累计(秒) |
+| `elapsedMilliTime` | `elapsedTime * 1000` |
+| `frameCount` | 累计帧数 |
+| `timeScale` | 时间缩放,默认 1.0 |
+| `maximumDeltaTime` | 单帧增量上限(秒),默认 0.333333 |
+| `reset()` | 重置基准系统时间 |
+
+另有 `engine.isPaused` / `engine.debugMode`。
+
+## 蓝图事件出口
+
+- `engine.registerEngineEmitFunc(func)` / `engine.emitFunc`:`EngineEmitFunc = (type, data, sourceId) => void`;组件内经 `emitEasyvFunc` 触发(见 easytwin-render/lifecycle-events.md)。
+
+## 事件(EventEmitter)
+
+- `engine.on(...)`:预置事件名 `saveError` / `component-editing` / `component-previewing` / `disableDelete` / `enableDelete` / `informationBar`(另接受任意字符串)。
+
+## 资源缓存
+
+- `engine.clearSceneSpecificResources()`:切场景时清理场景特定资源,保留通用缓存。
+- `engine.getResourceCacheStats()` / `engine.isResourceCached(address)` / `engine.clearAllResourceCache()`(完全重置)。
+
+## 销毁
+
+`engine.destroy()`:`cancelAnimationFrame` → 逆序销毁各 manager(启用持久化时跳过 ResourceManager)→ 清空注册表 → `emitFunc = undefined` → `THREE.Cache.clear()`。
+
+## WebCanvas
+
+`scene.canvas`(`WebCanvas`):`width` / `height`(setter 同步底层 canvas)、`resizeByClientSize(pixelRatio = window.devicePixelRatio)`(按 clientWidth/clientHeight × pixelRatio 重设)。
+
+## SystemInfo / StatsTool
+
+- `SystemInfo`(静态):`platform`(`Platform` 枚举:Android / IPhone / IPad / Mac / Unknown)、`operatingSystem`、`devicePixelRatio`。
+- `StatsTool`(场景性能统计):`triangleCount` / `textureRAM` / `textureVRAM` / `lightCount` / `componentCount` / `modelCount` / `materialCount` / `textureMap` / `geometryMap` / `materialMap`,`update()` 重算。

package/skills/easytwin-core/references/physics.md

@@ -0,0 +1,30 @@
+# 物理体系(Rapier)
+
+基于 `@dimforge/rapier3d-compat`。
+
+## PhysicsManager(引擎级)
+
+`engine.getManager(PhysicsManager)`(name `"PhysicsManager"`):
+
+- `enablePhysics()` / `disablePhysics()`:启停 `world.step()`。`disablePhysics` 保留 rapier 对象便于复用;另有重置系列做完整重建。
+- `gravity`(`RapierVec3 = { x, y, z }`,默认 `{ x: 0, y: -9.81, z: 0 }`)、`fixedDeltaTime`(默认 1/60;单帧最多 5 个物理子步)。
+
+## PhysicsScene(scene.physicsScene)
+
+- `gravity`(get/set → PhysicsManager)、`fixedDeltaTime`(get)。
+- 仅用于兼容旧版本代码(第三人称相机仍依赖该对象)。
+
+## 物理开关(scene)
+
+- `scene.physicsEnabled`:第一人称相机预览用。
+- `scene.physicsEnabled2`:全局物理开关。
+- 实际生效条件 = 两者**或**(源码 `_internalPhysicsEnabled` 注释)。
+
+## 刚体与碰撞体
+
+- 刚体组件:`DynamicRigidbodyComponent` / `StaticRigidbodyComponent` / `CharacterControllerComponent`。
+- `RigidbodyType = "static" | "dynamic" | "kinematicPosition" | "kinematicVelocity"`。
+- 碰撞体:`ColliderObj`(基类)与 `BoxColliderObj` / `CapsuleColliderObj` / `SphereColliderObj` / `CharacterColliderObj`;`PhysicsMaterial`(摩擦/弹性/混合规则)。
+- 回调(需绑定碰撞体):`onCollisionEnter/Stay/Exit(other, self)`、`onTriggerEnter/Stay/Exit(other, self)`,参数为 `ColliderObj`。
+
+> 注意 README:碰撞与射线检测(暂未支持);旧 `userData._target` 方案已划线,不建议依赖。

package/skills/easytwin-core/references/virtual-components.md

@@ -0,0 +1,169 @@
+# VirtualRootComponent / VirtualChildComponent(虚拟子要素基类)
+
+面向"数字要素模板""模型"等带内部结构的组件:根组件持有 `virtualChildren: VirtualChildComponent[]`,子要素数据序列化在根组件的 `data.children` 中,与常规实体父子关系(`Component.children` / `addChild`)分离。以下按 `easytwin-runtime/src/core/VirtualRootComponent.ts`、`VirtualChildComponent.ts` 整理。
+
+## 类层级与定位
+
+```
+EventEmitter → SceneObject → Component → VirtualRootComponent<SC, CD, D>
+EventEmitter → SceneObject → VirtualChildComponent<D>          (不继承 Component)
+```
+
+- `VirtualRootComponent`(core/VirtualRootComponent.ts):数字要素模板、模型等组件的基类;泛型 `SC`(状态配置)/ `CD`(子要素配置)/ `D extends VirtualRootData<CD>`(data 结构)。
+- `VirtualChildComponent`(core/VirtualChildComponent.ts):**直接继承 `SceneObject`**(不是 `Component`),实现 `IHierarchyNode` / `RuntimeComponent`。源码中没有任何类 `extends VirtualChildComponent`——子要素实例由根组件在 `syncChildren` 中 new 出来并放入 `virtualChildren` 持有(见文末示例)。
+- 两种关系并存:常规父子走 `children` / `addChild`;虚拟子要素走 `virtualChildren` / `addVirtualChild`。编辑器侧 `shownChildren = [...virtualChildren, ...children]`。
+
+## 序列化数据类型
+
+```ts
+interface VirtualChildData<D = any> {
+  id: string;
+  name: string;
+  active: boolean;
+  lock: boolean;
+  collapsed: boolean;
+  config: D;                          // 子要素自定义配置
+  customAttribute: Record<string, any>; // 自定义属性(蓝图过滤器依据)
+}
+
+interface VirtualRootData<D = any> {
+  children: VirtualChildData<D>[];
+  positionMode?: "xyz" | "lonLat";
+}
+```
+
+- 子要素持久化数据挂在根组件 `data.children`,由 `syncChildren` 同步到 `virtualChildren` 实例。
+- `VirtualChildComponent` 上 `config` / `customAttribute` 的 setter 会立即 `updateData(serialize(), true)` 写回后端(同步);根组件经 `updateVirtualChildByData` 转发。
+
+## VirtualRootComponent API
+
+### 生命周期与渲染
+
+| 成员 | 说明 |
+| --- | --- |
+| `_processActive()` / `_processInActive()` | 覆写:除自身激活/失活外,递归子 `virtualChildren`(子实体 `_active` 为 true 才跟随) |
+| `renderData(data)` | 覆写:先 `syncChildren(data)` 再 `onRenderData(data)`;`easyV` 模式下按反序列化时缓存的 `_initialActive` 重置自身激活,并对非 `Model` 组件强制"模板显示 + 子要素全隐藏"(保证子要素可经蓝图过滤器独立显隐) |
+| `abstract syncChildren(data)` | 必须实现:把 `data.children` 同步到 `virtualChildren` 实例(按 id 复用/销毁,见文末示例) |
+
+### data.children 数据操作(深拷贝改写 `_data` 后经 `updateData` 写回)
+
+| 成员 | 说明 |
+| --- | --- |
+| `setVirtualChildByData(children, sync)` | 整体替换 `data.children`(编辑器) |
+| `addVirtualChildByData(child, sync)` | 追加一条;`customAttribute` 缺省时自动复制第一个子要素的 key(值为 `""`) |
+| `updateVirtualChildByData(id, child, sync)` | 按 id 替换一条子要素数据 |
+| `removeVirtualChildByData(id, sync)` | 按 id 删除一条 |
+
+### 实例操作 / 遍历 / 查找
+
+| 成员 | 说明 |
+| --- | --- |
+| `addVirtualChild(child)` / `removeVirtualChild(child)` | 直接增删 `virtualChildren` 并同步 `sceneObject` 层级 |
+| `traverseVirtualChildren(cb)` | 深度遍历(含嵌套子要素) |
+| `findVirtualChildById(id)` | 深度查找(含嵌套) |
+| `filterByAttribute(attributes)` | 按 `customAttribute` 过滤,任一 key 相等即命中(Set 去重) |
+| `filterVirtualChildByParam(param)` | 蓝图过滤器统一入口:`EasyvFilterAttributeParam = { attributes; unionFlag? } \| { key; include }`;含 `key` 走 `filterVirtualChildByKey`,否则走 `filterVirtualChildByAttribute` |
+| `filterVirtualChildByKey(key, include)` | 子要素属性 `key` 为字符串且包含 `include` |
+| `filterVirtualChildByAttribute(param, unionFlag)` | `unionFlag=false`:所有 key 全等才命中;`true`:任一 key 相等即命中 |
+
+### 自定义属性(编辑/运行时)
+
+| 成员 | 说明 |
+| --- | --- |
+| `addCustomAttributeKey(key)` / `removeCustomAttributeKey(key)` / `renameCustomAttributeKey(oldKey, newKey)` | 编辑器专用,批量改所有子要素并同步后端 |
+| `updateCustomAttribute(childId, key, value)` | 编辑器专用,同步后端 |
+| `updateCustomAttributeRuntime(childId, key, value)` | 运行时专用,**不同步**后端 |
+| `setCustomAttribute(childId, customAttribute, sync)` | 整体替换某子要素的 `customAttribute` |
+
+### 蓝图 / easyv
+
+- `easyvSwitchState(param)`:有 `stateId` 且 `toChild` 时,对 `filterVirtualChildByParam(toChild)` 的结果逐个调 `child.easyvUpdateByStateConfig(state.config, param)`;否则 `selectState(stateId)`。
+- 构造器经 `getDefaultEasyvEventListener` 注册默认蓝图动作:`setState` / `show` / `hide` / `show/hide` / `updateCustomAttributes`(`updateCustomAttributes` 仅 VirtualRootComponent 注册,参数为单个或数组 `EasyvUpdateCustomAttributeParam = { id; key; value }`,转调 `updateCustomAttributeRuntime`)。
+- `show` / `hide` 对根组件操作的是**子要素的 `active`**:带 `attributes` 时按 `filterByAttribute` 过滤后设置,否则作用于全部 `virtualChildren`。
+
+### 选中 / 射线
+
+- `select()` / `unSelect()`:空实现,子类可覆写。
+- `intersectObject(raycaster, ev)`:对 `sceneObject.children` 中 visible 者做射线相交。
+
+## VirtualChildComponent API
+
+### 构造与关系
+
+```ts
+constructor(scene: RuntimeScene, attachComponent: VirtualRootComponent)
+```
+
+- `attachComponent: VirtualRootComponent | null`:所属根组件,所有数据同步经它转发。
+- `parent: VirtualRootComponent | VirtualChildComponent | null`:setter 会**自动维护 `attachComponent`**(父为根取父,父为子则取 `父.attachComponent`),同时增删父的 `virtualChildren` 并处理激活联动;跨场景移动会被拒绝。
+- `sceneObject: THREE.Object3D`:构造器内 `new Object3D()`,`userData._target = this`。
+- `shownChildren` = `virtualChildren`(嵌套子要素)。
+
+### 持久化数据成员
+
+| 成员 | 说明 |
+| --- | --- |
+| `id` / `name` / `active` / `lock` / `collapsed` / `config` / `customAttribute` | 与 `VirtualChildData` 对应;`config` / `customAttribute` 的 setter 触发 `updateData(serialize(), true)` 同步后端 |
+| `abstract readonly type` / `version` | 必须实现 |
+| `active` setter | 同步 `sceneObject.visible`,并按父级 `_activeInScene` 触发 `_processActive` / `_processInActive`(**不写后端**;持久化用 `setActive`) |
+| `activeInScene` | 只读:是否已在场景中全局激活 |
+| `showTransformControl` / `showBoundingBox` | 编辑器显隐控制(`RuntimeComponent` 契约成员) |
+
+### 数据同步
+
+| 成员 | 说明 |
+| --- | --- |
+| `serialize(): VirtualChildData<D>` | 组装当前数据 |
+| `updateData(data, sync)` | 经 `attachComponent.updateVirtualChildByData(id, data, sync)` 写回;同步 `sceneObject.visible` 并触发 `onEnable` / `onDisable`;`sync=false` 时首次调用缓存旧数据到 `_cachedOriginalData`(撤回用),`sync=true` 时清空 |
+| `syncData(data)` | **直接赋值** id/name/active/lock/config/customAttribute,供根组件 `syncChildren` 复用实例;注意源码中**不恢复 `collapsed`** |
+| `rename` / `setLock` / `setActive` / `setCollapsed` | 改字段并 `updateData(serialize(), true)` 同步后端;`setActive` 额外写 `sceneObjectVisibleWithLayout` |
+| `updateCustomAttribute(key, value, sync)` | 改单个 key 并 `updateData(serialize(), sync)` |
+
+### 生命周期 / 状态
+
+- 激活:`_processActive()` 置 `_activeInScene = true` 并调 **`onEnable()`**(无 `onAwake`),再递归子 `virtualChildren`;`_processInActive()` 对称。
+- 钩子:`protected onEnable()` / `protected onDisable()`(可覆写);`easyvUpdateByStateConfig(config, param)` / `easyvSwitchState(param)`(默认空实现,可覆写);`startEditor()` / `endEditor()`。
+
+### 抽象成员(必须实现)
+
+| 成员 | 说明 |
+| --- | --- |
+| `render()` | 根据 `this.config` 更新渲染对象 |
+| `destroy()` | 销毁自身(移除 sceneObject / 资源) |
+| `onTransformControlUpdate(control, offsetMatrix)` | 变换控制更新 |
+| `onTransformControlDragEnd(control)` | 变换控制拖拽结束 |
+
+### 指针 / 选中 / 射线
+
+- 指针回调:`onPointerUp` / `onPointerDown` / `onPointerEnter` / `onPointerExit` / `onPointerClick` / `onPointerDrag(pointer)`(默认空实现;注意 README 注明碰撞与射线检测暂未支持)。
+- `select()` / `unSelect()`;`canSelectInEditor()`(默认 true)、`getSelectObject()`(默认返回 `sceneObject`)。
+- `intersectObject(raycaster, ev)`:`raycaster.intersectObjects(sceneObject.children.filter(c => c.visible))`。
+- `findRuntimeComponentById(id)`:沿 `shownChildren` 深度查找(含自身)。
+
+## 开发示例(参考 easytwin-components-example/src/core)
+
+根组件 `ExampleComponent extends VirtualRootComponent<ExampleComponentStateConfig, ExampleChildConfig, ExampleComponentData>`,`syncChildren` 按 id 复用 / 销毁:
+
+```ts
+syncChildren(data: ExampleComponentData): void {
+  const oldChildren = this.virtualChildren;
+  const newChildren = [];
+  for (let i = 0; i < data.children.length; i++) {
+    const newChildData = data.children[i];
+    const reusedCompIndex = oldChildren.findIndex((a) => a.id === newChildData.id);
+    if (reusedCompIndex === -1) {
+      const c = new ExampleChildComponent(this.scene, this);
+      c.syncData(newChildData);          // 新实例,直接灌数据
+      newChildren.push(c);
+    } else {
+      const reusedComp = oldChildren.splice(reusedCompIndex, 1)[0];
+      reusedComp.syncData(newChildData); // 复用实例,覆盖数据
+      newChildren.push(reusedComp);
+    }
+  }
+  oldChildren.forEach((c) => c.destroy()); // 剩余未复用实例销毁
+  this.virtualChildren = newChildren;
+}
+```
+
+子要素 `ExampleChildComponent extends VirtualChildComponent<ExampleChildConfig>`:构造器接收 `(scene, attachComponent)`,把 mesh 挂到 `this.sceneObject`,`render()` 里按 `this.config` 更新,`destroy()` 移除自身资源;根组件 `onRenderData` 中对 `this.virtualChildren` 逐个调 `render()`。

package/skills/easytwin-develop/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: easytwin-develop
+description: 当用户开始 EasyTwin 第三方应用开发、需要了解整体开发工作流(配置凭证→拉场景→写渲染→上传)、或询问"接下来该做什么/从哪开始"时使用。其余 EasyTwin 技能的总纲。
+---
+
+# EasyTwin 开发工作流
+
+EasyTwin DevKit 是 EasyTwin 第三方应用开发工具集。典型工作流:
+
+1. **配置凭证**:运行 `easytwin init` 生成项目级 `easytwin.config.json`(App ID / App Secret)。详见 `easytwin-bootstrap`。
+2. **拉取场景**:`easytwin scene list` 列出场景,`easytwin scene pull <id>` 拉取场景 JSON 到本地,作为开发参考与预览输入。详见 `easytwin-scene`。
+3. **编写渲染功能**:用 twin runtime(npm 包 `@easytwin/runtime`)开发渲染代码;引擎内核(基类/Time/相机/物理)见 `easytwin-core`。详见 `easytwin-render`(主力技能)。
+4. **上传产物**:`easytwin upload <dir>` 全量覆盖上传到服务端,不可逆。详见 `easytwin-upload`。
+
+## 何时读哪个技能
+
+| 场景 | 技能 |
+| --- | --- |
+| 初始化 / 校验凭证 | easytwin-bootstrap |
+| 列场景、拉场景 JSON | easytwin-scene |
+| 用 twin runtime 写渲染 | easytwin-render |
+| 理解引擎内核 / 基类 / 相机 / 物理 | easytwin-core |
+| 上传开发产物 | easytwin-upload |
+
+> 场景 JSON 具体格式尚未定稿,相关说明在 easytwin-scene 中为占位。

package/skills/easytwin-render/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: easytwin-render
+description: 当用户要用 EasyTwin twin runtime 编写渲染功能(安装/引入 @easytwin/runtime、初始化引擎、加载场景、开发自定义组件、调用渲染 API)时使用。这是 EasyTwin 渲染开发的唯一入口技能。
+---
+
+# 用 twin runtime 开发渲染功能
+
+twin runtime 是 npm 包 `@easytwin/runtime`(ESM,peer 依赖 `three@0.183.0`):在已存在的 DOM 容器上创建 `RuntimeEngine`,加载场景 JSON,通过组件生命周期与渲染 API 开发功能。
+
+## 快速上手
+
+1. 安装:`npm i @easytwin/runtime`(项目需自装 peer 依赖 `three@0.183.0`)。
+2. 页面里先放好容器 `<div id="twin-root"></div>` ——容器必须已存在于 DOM,`RuntimeEngine.create` 找不到会抛错。
+3. 初始化并加载场景:
+
+```ts
+import { RuntimeEngine, SceneManager, LoadSceneMode } from "@easytwin/runtime";
+
+const engine = await RuntimeEngine.create({
+  containerId: "twin-root",
+  baseOSSUrl: "https://assets.easyv.cloud",
+  customComponentDeps: { "@easytwin/runtime": Runtime, react: FakeReact },
+  sceneResources: [],
+  componentRels: [],
+});
+await engine.getManager(SceneManager).loadScene(sceneJson, "publish", LoadSceneMode.Single);
+```
+
+4. 在组件生命周期/事件里写渲染逻辑;自定义组件继承 `Component` / `VirtualRootComponent`,见 `references/lifecycle-events.md`。
+
+> TODO(外部输入): 官方"script 引入全局对象"的加载方式尚未确认。当前以 npm 包 `@easytwin/runtime` + `RuntimeEngine.create` 为准;若官方后续给出 script 方式,在此补充并同步更新 references。
+
+## 参考(references/)
+
+API 细节按域拆分,按需加载,不要一次全读:
+
+- 需要"安装、初始化引擎、engine/scene/manager 关系、销毁"时读 `references/intro.md`
+- 需要"场景加载/序列化结构/资产加载"时读 `references/scene-and-assets.md`
+- 需要"组件生命周期、状态/数据、事件"时读 `references/lifecycle-events.md`
+- 需要"相机/坐标、2D、动画、物理、地理、工具函数"时读 `references/rendering-apis.md`
+
+> 引擎内核的完整 API(RuntimeEngine 全量、Time、WebCanvas、相机、物理)见 `easytwin-core`。

package/skills/easytwin-render/references/intro.md

@@ -0,0 +1,81 @@
+# 引入与初始化
+
+## 包信息
+
+- npm 包:`@easytwin/runtime`(ESM 模块)。
+- peer 依赖:`three@0.183.0`(需自行安装);内部依赖 rapier3d、@tweenjs/tween.js、mobx、localforage、proj4、stats-gl 等,由包自身携带。
+- 根导出:`manager`、`core`、`loader`、`utils`、`packages`、`server`、`type`、`three-extension`、`constants`、`module` 命名空间;另有 `THREE`、`Mobx`、`TweenJs`、`Semver` 命名空间与若干直接导出(详见 rendering-apis.md)。
+
+## 初始化 RuntimeEngine
+
+唯一入口:`RuntimeEngine.create(config)`(静态、异步)。
+
+```ts
+import { RuntimeEngine, SceneManager, LoadSceneMode } from "@easytwin/runtime";
+
+const engine = await RuntimeEngine.create({
+  containerId: "twin-root",                    // 必填:容器 id,须已存在于 DOM
+  baseOSSUrl: "https://assets.easyv.cloud",    // 必填:资产根地址
+  customComponentDeps: { /* 见下 */ },         // 必填:注入给自定义组件的依赖
+  sceneResources: [],                          // 可选:场景资源清单,默认 []
+  componentRels: [],                           // 可选:组件引用关系,默认 []
+  enableResourcePersistence: false,            // 可选:ResourceManager 是否持久化(localforage),默认 false
+  localOSSUrl: undefined,                      // 可选:本地资产根地址
+});
+```
+
+`EngineConfiguration` 字段:
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `containerId` | 是 | 容器元素 id;`document.getElementById(containerId)` 找不到即抛错 |
+| `baseOSSUrl` | 是 | 服务端资产根地址;draco / ktx2 / webp / LCC 等系统库 URL 由此拼出 |
+| `customComponentDeps` | 是 | 自定义组件脚本 import 的依赖表,键为模块名,值为实现 |
+| `localOSSUrl` | 否 | 本地资产根地址;非空时自定义组件脚本优先读 `${localOSSUrl}/${type}@${version}.js` |
+| `sceneResources` | 否 | 场景资源清单(ListSceneResourceVo[]) |
+| `componentRels` | 否 | 组件引用关系(GetComponentRelVo[]) |
+| `enableResourcePersistence` | 否 | 是否让 ResourceManager 用 localforage 持久化,默认 false |
+
+`create` 做的事:注册并初始化 ResourceManager / SceneManager / CustomComponentManager / EditorActionsManager / PhysicsManager,启动 `requestAnimationFrame` 渲染循环,返回 `Promise<RuntimeEngine>`。
+
+## customComponentDeps 注入
+
+自定义组件脚本里 `import` 的模块由引擎用此表解析(真实项目配置示例):
+
+```ts
+const customComponentDeps = {
+  "@easytwin/runtime": Runtime,                     // 组件里 import { ... } from "@easytwin/runtime"
+  "@easytwin/runtime-frontend": { EasyVIcon: {}, MobxReactLite: { observer: (c: any) => c } },
+  react: FakeReact,                                 // 无 React 环境时用最小 shim
+};
+```
+
+## engine / scene / manager 关系
+
+- 一个 `RuntimeEngine` 对应一个 DOM 容器,持有若干 manager 与若干 `RuntimeScene`。
+- 取 manager:`engine.getManager(SceneManager)`(按类)/ `engine.getManagerByName("SceneManager")`(按名)。
+- 主场景:`engine.mainScene`(即 `SceneManager.mainScene`)。
+- 便捷方法:`engine.createComponent(params, sync?)`、`engine.createModelComponent(name, url, sync?, onProgress?)` 转发到 mainScene(参数见 scene-and-assets.md)。
+- 引擎状态:`engine.time`(Time:`deltaTime` / `elapsedTime` / `frameCount` / `timeScale`)、`engine.isPaused`、`engine.debugMode`。
+- 蓝图事件出口:`engine.registerEngineEmitFunc(func)`,回调签名 `EngineEmitFunc = (type: string, data: any, sourceId: string) => void`;组件里经 `emitEasyvFunc` 触发(见 lifecycle-events.md)。
+- 资源缓存:`engine.clearSceneSpecificResources()`、`engine.getResourceCacheStats()`、`engine.isResourceCached(address)`、`engine.clearAllResourceCache()`。
+
+## RuntimeScene 与 mode
+
+`SceneManager.loadScene(sceneJson, mode, loadSceneMode)` 的 `mode` 来自 `RuntimeSceneMode`:
+
+```ts
+RuntimeSceneMode = { Editor: "editor", Preview: "preview", EasyV: "easyV", Publish: "publish" }
+```
+
+- `editor`:EasyTwin 编辑页;`preview`:预览页;`easyV`:EasyV 编辑页;`publish`:EasyV 发布页。
+- 部分能力(如 ViewHelper、TransformControls、编辑模式钩子)仅在 `editor` 模式注册。
+
+## 销毁
+
+- `engine.destroy()`:取消 RAF、逆序销毁各 manager(启用持久化时保留 ResourceManager)、清空 `THREE.Cache`;销毁后需重建 engine。
+- 单个场景 `scene.destroy()`:退出编辑/预览态、失活组件、递归销毁子组件、移除 easyv 监听、调用 onDestroy 并释放 DOM/资源。`LoadSceneMode.Single` 加载新场景时会先销毁旧场景。
+
+## 参考源码
+
+- `src/core/RuntimeEngine.ts`、`src/core/RuntimeScene.ts`、`src/core/Time.ts`。