@easytwin/devkit 0.1.0

package/skills/easytwin-render/references/lifecycle-events.md

@@ -0,0 +1,79 @@
+# 组件生命周期与事件
+
+自定义组件继承 `Component`(或 `VirtualRootComponent` / `VirtualChildComponent`,见文末)。本节按源码 `Component.ts` 与 `docs/组件声明周期.md` 整理。
+
+## 生命周期总序
+
+1. **反序列化** `deserialize(json, ignoreChildren?)`:校验 `json.type === this.type` 否则抛错;恢复 id/componentId/name/active/lock/collapsed/states/data → `await afterDeserialize()` → 递归反序列化 children → `isInited = true`。
+2. **初始化** `_processInitialize()`(一次性):`initialize()` = 先 `renderState(curState)`(可 await)→ `renderData(data)` → `await onInitialize()` → 递归 children。
+3. **激活** `_processActive()`:置 `_activeInScene = true` → 首次 `awake()`(`onAwake()` 仅一次)→ `enable()`(注册到 ComponentManager 更新队列 + `onEnable()`;仅当覆写了 `onUpdate`/`onLateUpdate`/`onFixedUpdate` 才入对应队列;未 start 时入 onStart 队列)→ 递归 children(子 active 才激活)。
+4. **onStart**:由 ComponentManager 单独调度,`callScriptOnStart()` 一次性,每组件仅一次。
+5. **每帧**:`onFixedUpdate()` → `onUpdate(dt)` → `onLateUpdate(dt)`(三个队列都要求已 `_isStarted`)。
+6. **销毁** `destroy()`:正在编辑先 `endEdit()`;若 `_activeInScene` 先 `disable()`(移除队列 + `onDisable()`);**递归子 destroy → 移除 easyv 监听 → `onDestroy()` → children 清空**。
+
+## 钩子访问级别与触发
+
+| 钩子 | 级别 | 触发 |
+| --- | --- | --- |
+| `onInitialize()` | protected | 帧循环前,无论 active,`renderState`/`renderData` 之后,可 `void \| Promise<void>` |
+| `onAwake()` | protected | 首次激活时,仅一次 |
+| `onEnable()` / `onDisable()` | protected | `_activeInScene` 置 true/false 时 |
+| `onDestroy()` | protected | 销毁时 |
+| `onStart()` | public | 帧循环最开始,仅一次 |
+| `onUpdate(dt)` / `onLateUpdate(dt)` | public | 每帧;late 在 update 后 |
+| `onFixedUpdate()` | public | 每固定间隔 |
+
+**覆写判据(易踩坑)**:`enable()` 用 `this.onUpdate !== Component.prototype.onUpdate` 与原型比较——**不覆写就不会进入更新队列**,写组件时必须覆写 `onUpdate`/`onLateUpdate`/`onFixedUpdate` 才会被调用。
+
+## 抽象成员(必须实现)
+
+`isRoot`(getter)、`readonly type` / `readonly version`、`getInitState()`、`onRenderState(state)`、`onRenderData(data)`、`onTransformControlUpdate(control, offsetMatrix)`、`onTransformControlDragEnd(control)`、`afterDeserialize()`。
+
+## 状态 API
+
+- 成员:`states`(`StateJson<SC>[]`)、`curState`(getter:有 `selectedStateId` 取之;否则取 `using` 的,再否则 `rank` 最小的)、`selectedStateId`。
+- `async addState(newState?, index?)`:新建时用 `getInitState()` 并自动编号;同步后端。
+- `async removeState(id)`;`updateState(id, config, sync, skipRender = false)`(sync 同步后端);`selectState(id)`(渲染);`renameState(id, name)`。
+- 编辑器专用:`async sortState_setRank(stateId, rank)`(直接 EntityAPI)、`setDefaultState(id)`。
+- `renderState(state)` → `onRenderState`。
+
+## 数据 API
+
+- `data`(getter `_data`)、`updateData(data, sync, skipRender? = false)`(sync 同步后端)、`renderData(data)` → `onRenderData`。
+- `VirtualRootComponent.renderData` 会先 `syncChildren(data)` 再 `onRenderData`(见文末)。
+
+## 其他成员
+
+- `active` / `lock` / `collapsed` 与 `rename(name)` / `setActive(v)` / `setLock(v)` / `setCollapsed(v)`(带 SaveManager 后端同步)。
+- `children` / `parent`(设 parent 自动 addChild/removeChild 与激活处理)、`addChild` / `removeChild`。
+- 查找:`findBy(cond)`、`findById`、`findByName`、`findByType`、`findByPath(path)`(斜杠分隔)、`findRuntimeComponentById`(含 VirtualChild)、`traverse(cb)`。
+- `serialize(ignoreChildren = false)` / `deserialize`;`destroy()`。
+- 编辑/预览:`async startPreview()/endPreview()`、`handlePreview(value)`、protected `_startPreview()/_endPreview()`;`startEdit(id?)/endEdit()`、protected `_startEdit(id?)/_endEdit()`;`editMode: "polygon" | "create" | "none"`、`isPreviewing`、`isEditing`。
+- 版本升级:`onUpgradeVersion(oldComponent)`(返回 `{ stateJson?, data? }` 可选)。
+
+## 指针与物理回调
+
+- 指针(`Pointer`):`onPointerUp/Down/Enter/Exit/Click/Drag(pointer)`。注意 README 注明**碰撞与射线检测(暂未支持)**,旧 `userData._target` 方案已在 README 划线;示例组件仍手动设置 `sceneObject.userData._target = this`——**不建议依赖**。
+- 物理:`onCollisionEnter/Stay/Exit(other: ColliderObj, self: ColliderObj)`、`onTriggerEnter/Stay/Exit(other, self)`;绑定碰撞体才能收到。
+
+## 蓝图 / easyv 事件
+
+- `addEasyvEventListener(name, func)`:非 editor 模式才注册;`destroy` 时自动移除。
+- `emitEasyvFunc(eventName, data)`:调 `this.engine.emitFunc?.(eventName, data, this.id)`;需先 `engine.registerEngineEmitFunc(func)`,`EngineEmitFunc = (type, data, sourceId) => void`。
+- `easyvSwitchState(param)`:`param = { id, stateId, type, toChild?, animation? }`,有 `stateId` 时 `selectState`。
+- `VirtualRootComponent` 构造器还会经 `getDefaultEasyvEventListener` 注册默认动作:`setState` / `show` / `hide` / `show/hide` / `updateCustomAttributes`。
+
+## 信号 / 事件 / 工具包
+
+- `Signal<T = []>`:`on / off / once / emit / removeAllListeners`。
+- `EventEmitter<E, ARGS>`(SceneObject 基类继承;`engine.emit(name, ...)` 可发 `saveError` / `component-editing` / `component-previewing` 等)。
+- 现成信号:`Component.signals.componentUpdated`、`SceneManager.signals.sceneUpdated`、`ComponentManager.signals.componentsUpdated`。
+- `Blackboard`:`setValue / getValue / removeValue / clear`。
+- `Fsm<T>(owner, stateList)`:`isRunning / isDestroyed / curStateRunningTime / fsmStatesCount`;`getData / setData / removeData / hasState / getState / start(stateType) / update(dt) / switchState(stateType) / destroy`;`FsmState<T>` 钩子 `onInit / onEnter / onUpdate / onLeave / onDestroy`,含 `blackboard` getter。
+
+## VirtualRootComponent / VirtualChildComponent
+
+完整 API、序列化结构、数据同步与开发示例见 `easytwin-core` 的 `references/virtual-components.md`。这里只保留最关键的差异点:
+
+- `VirtualRootComponent`(数字要素模板、模型):`virtualChildren`;`_processActive`/`_processInActive` 同时递归子 `virtualChildren`;`shownChildren = [...virtualChildren, ...children]`;`renderData` 先 `syncChildren(data)` 再 `onRenderData(data)`。
+- `VirtualChildComponent extends SceneObject`(非 `Component`):无 `onAwake`,激活只调 `onEnable`/`onDisable`;`config` setter 会 `updateData(serialize(), true)`;抽象 `render()` / `destroy()`;`virtualChildren` 支持嵌套。

package/skills/easytwin-render/references/rendering-apis.md

@@ -0,0 +1,116 @@
+# 渲染 API 各域
+
+场景对象 `scene` 即 `RuntimeScene`(加载后从 `SceneManager.mainScene` 或 `engine.mainScene` 取得)。
+
+## 相机与场景视图
+
+- `scene.camera.main`(当前主相机);`scene.camera.switchTo(camera)` 切到自定义相机(标记 `_isControlled`);`scene.camera.switchToScene()` 切回场景相机。
+- `SceneCamera`:`sceneCameraMode: "perspective" | "orthographic"`(setter 同步透视/正交参数并触发 `onCameraModeChanged`);`perspectiveCamera` / `orthographicCamera` / `nativeCamera`。
+- `scene.control`(`CameraControls`);`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`)。
+- 坐标转换(直接传 clientX/clientY 即可):
+
+| 方法 | 说明 |
+| --- | --- |
+| `ndcToScreenPos(ndcPos, out)` | NDC → 屏幕像素 |
+| `screenToNdcPos(screenPos, out)` | 屏幕 → NDC |
+| `worldToScreenPos(worldPos, out)` | 世界 → 屏幕像素 |
+| `screenToWorldPos(screenPos, out)` | 屏幕 → 世界 |
+| `getMouseCoords(x, y)` | clientX/clientY → NDC `Vector2` |
+
+- 2D CSS:`EngineCSSRenderObject extends THREE.Object3D { element: HTMLDivElement; autoResize = true; faceToCamera = true }`;`scene.cssRenderer`(CSSRenderer)每帧把含 element 的 3D 对象同步到 CSS 位置/缩放。
+- 深度:`scene.getDepthTexture()`;渲染回调:`scene.registerRenderCallback(cb)`(返回取消函数)。
+
+## 动画
+
+- `EasyTwinTween`:`createNumberAnimate(option)`、`createTweenHandler<T>(option)`、`removeTweenHandler(tween)`。
+
+```ts
+type TweenOption<T> = {
+  source: T; target: T;
+  duration?: number;        // 默认 1000
+  delay?: number;           // 默认 0
+  mode?: AnimationModeType; // 默认 "Quadratic.InOut"
+  repeat?: number;          // 默认 0
+  execute?(source, elapsed);
+  complete?(source, duration);
+};
+```
+
+- `AnimationModeType` 完整枚举:族 `Linear`(仅 None)、`Quadratic`、`Cubic`、`Quartic`、`Quintic`、`Sinusoidal`、`Exponential`、`Circular`、`Elastic`、`Back`、`Bounce`;每族含 `In/Out/InOut`(如 `"Quadratic.InOut"`),映射 `@tweenjs/tween.js` Easing。
+- `TwinAnimationMixer extends EventEmitter`(`@easytwin/runtime` 导出,示例组件作成员字段使用):
+  - 属性:`actions`、`isPlaying` / `isPause`、`timeScale`、`unit: "percent" | "time"`。
+  - 方法:`play(name?)`、`pause()`、`stop(reset = true)`、`reset(name?)`、`replay()`、`preview(time, name?, unit = "time")`、`setTimeUnit(type)`、`getDuration()`、`setTime` / `setEndTime` / `getTime`、`addAction(name, force?)`、`getActionByName`、`removeByName` / `removeAll`、`setRepeat`、`tick()`。
+  - 事件:`start` / `stop` / `pause` / `preview(time, unit)` / `reset` / `update(time)`。
+  - 注意:源码**没有 `resume` 方法**,不要写。
+
+## 物理
+
+- 组件:`DynamicRigidbodyComponent`、`StaticRigidbodyComponent`、`CharacterControllerComponent`(均相关于 `RigidbodyComponent`);碰撞体 `ColliderObj` 与 `BoxColliderObj` / `CapsuleColliderObj` / `SphereColliderObj` / `CharacterColliderObj`;`PhysicsMaterial`(摩擦/弹性/混合规则;Rapier 版无原生对象,destroy 空操作)。
+- `scene.physicsScene.gravity` / `scene.physicsScene.fixedDeltaTime`(getter/setter)。
+- 物理开关:`scene.physicsEnabled`(第一人称相机预览用)与 `scene.physicsEnabled2`(全局开关);实际生效条件 = 两者**或**(源码 `_internalPhysicsEnabled` 注释)。
+- 回调(需绑定碰撞体):`onCollisionEnter/Stay/Exit(other, self)`、`onTriggerEnter/Stay/Exit(other, self)`,参数为 `ColliderObj`。
+
+## 地理
+
+- `scene.geoTransform`(`GeographicModule`);`gisMode: "referencePoints" | "tileSet" | "tileMap" | "tileSetAndTileMap" | "none"`。
+- `geoToScene(geoLocation): IVector3` / `sceneToGeo(position): GeoLocation`。
+- `GeoTransformForReferencePoints(options)`:
+
+```ts
+options = {
+  point1: { position, geoLocation, wgs84GeoLocation },
+  point2: { position, geoLocation, wgs84GeoLocation },
+  geographicCRS?: string,  // 默认 "WGS84"
+  projectedCRS?: string,   // 默认 "EPSG:3857"
+  northDir: "-Z" | "+Z" | "+X" | "-X",
+};
+```
+
+  - 另有 `geoToSceneLinear`、`updateReferencePoints`、`getReferencePoints`。
+- `GeoLocation = { latitude, longitude, altitude }`。
+
+## 命名空间与直接导出(根导出)
+
+- 命名空间:`THREE`、`Mobx`(mobx)、`TweenJs`(@tweenjs/tween.js)、`Semver`(semver)。
+- `export *` 十大命名空间:`manager` / `core` / `loader` / `utils` / `packages` / `server` / `type` / `three-extension` / `constants` / `module`。
+- 直接导出:`OrbitControls`、`CSM`、`ConvexHull`、`VertexList`、`UnrealBloomPass`、`GTAOPass`、`OutlinePass`、`DragControls`、`RectAreaLightHelper`。
+
+## 工具函数与类型
+
+- `SRGB2Linear(r, g, b)` 返回 `[number, number, number]`(0~1 sRGB → linear);`Linear2SRGB` 反向。示例组件:`new THREE.Color(...SRGB2Linear(...state.config.color.rgb))`。
+- `genUUID(prefix = "")`、`deepClone(obj)`、`getTypeVersionKey(type, version)`(返回 `type@version`)、`getTypeVersionClassNameKey(type, version, className)`。
+- 常量:`GROUP_COMPONENT_TYPE = "EngineGroup"`、`MODEL_COMPONENT_TYPE = "Model"`、`SCENE_COMPONENT_TYPE = "Scene"`。
+- 类型:`Color = { rgb: [r,g,b]; alpha? }`(sRGB 空间);`IVector3 = { x, y, z }`(含命名空间方法 `scale/scaleVector/clamp/clampVector3/copy`);`IVector2 = { x, y }`;`EngineEmitFunc = (type: string, data: any, sourceId: string) => void`。
+
+## 自定义组件模块(CustomComponentManager)
+
+```ts
+type CustomComponentModule = {
+  Settings: ComponentSettings;
+  ComponentClass: ComponentCtor;
+  Init: (engine: RuntimeEngine) => void;
+  GetInitState: (scene: RuntimeScene) => InitStateDto | InitStateDto[];
+  GetInitData?: (scene: RuntimeScene) => any | Promise<any>;
+};
+
+type ComponentSettings = {
+  type: string;
+  category: "CustomComponent" | "FunctionalComponent" | "EffectComposer" | "Scene";
+  version: string;
+  name: string;
+};
+```
+
+- `ComponentUI` 四种:`ComponentUI_Scene`(type `"Scene"`,editor)、`ComponentUI_Custom`(`"CustomComponent"`,editors `{ Entity/Data/Material/FunctionalComponent/EffectComposer? }`)、`ComponentUI_Function`(`FunctionalComponent`,editor)、`ComponentUI_Effect`(`EffectComposer`,editors);均可带 `icon/contextMenu/previewMode/editMode`。
+- 方法:`getOrLoad(type, version?)`(加载远程 script 并 `module.Init(engine)`)、`registerUI(type, version, className, ui)`、`getUI(...)`、`getComponentLastVersion(type)`、`getComponentVersionList(type, isLatest?)`、`isComponentStale(comp)`、`externalDeps`。
+- 脚本加载地址见 scene-and-assets.md 的 `loadCustomComponentScript`。
+
+### 真实示例结构(`packages/easytwin-components-example`)
+
+- `settings.ts` 导出 `Settings`(`ComponentSettings`);`index.ts` 导出 `customModule: CustomComponentModule`(default);`init.tsx` 注册 UI。
+- `ExampleComponent extends VirtualRootComponent<SC, ChildCfg, Data>`:覆写 `onAwake/onEnable/onUpdate/onStart/onDisable`、指针事件、`onTransformControlDragEnd` 内 `updateState(this._selectedStateId, newState, true)`;`onRenderState` 用 `SRGB2Linear`;`onRenderData` 遍历 virtualChildren 调 `render()`;`syncChildren` 按 id 复用/销毁。
+- `ExampleChildComponent extends VirtualChildComponent<ChildCfg>`:构造器 `super(scene, attachComponent)` 后建 cube 挂 `this.sceneObject` 与 `attachComponent.sceneObject`;`render()` 应用 `config.position`;`destroy()` 移除。
+
+> TODO(外部输入): 渲染 API 官方文档与 d.ts 到位后,如需与本节逐条核对,以官方为准。

package/skills/easytwin-render/references/scene-and-assets.md

@@ -0,0 +1,94 @@
+# 场景加载与资产
+
+> 说明:本节讲的是 **runtime 内部**的场景 JSON(组件树序列化结构,`SceneJson`)与资产加载;`easytwin scene pull` 拉的是**服务端场景 JSON**,两者出处不同。可用 `SceneManager.importScene` 或 `loadScene` 把本地 JSON 喂给 runtime。
+
+## 场景管理(SceneManager)
+
+`engine.getManager(SceneManager)` 取得管理器。
+
+- `LoadSceneMode = { Single, Additive }`:`Single` 加载前先销毁并清空旧场景、设为 `mainScene`;`Additive` 直接追加。
+- `mainScene`(getter/setter,setter 会 `signals.sceneUpdated.emit()`)。便捷入口:`engine.mainScene`。
+- `createScene(name, mode, preserveDrawingBuffer = false)`:new `RuntimeScene` → 生成 id → push → `scene.init()`。
+- `createSceneById(sceneId, name, mode, loadSceneMode)`:内部 `EntityAPI.getEntities(sceneId)` 拉组件 JSON,拼成 `SceneJson` 后 `loadScene`。
+- `loadScene(sceneJson, mode, loadSceneMode, preserveDrawingBuffer = false)`:new RuntimeScene → init → `scene.deserialize(sceneJson)`;`Single` 时逐个 `destroy()` 旧场景、clear、设 `mainScene`、push。
+- `exportScene(scene)` = `scene.serialize()`;`importScene(file, mode, loadSceneMode)` = `file.arrayBuffer()` → 字符串 → `JSON.parse` → `loadScene`。
+- `deleteScene(name)`:**主场景不可删**,否则抛 `"can not unload main scene"`。
+- `signals.sceneUpdated`(`Signal`)。
+
+`mode` 取值见 intro.md 的 `RuntimeSceneMode`。
+
+## 序列化与组件管理(RuntimeScene)
+
+- `serialize(): SceneJson` = `{ id, name, sceneComponent: rootComponent.serialize() }`;root 无效抛错。
+- `deserialize(data: SceneJson)`:要求 `data.sceneComponent.type === "Scene"` 否则抛错;`deserializeComponent` 出根组件 → 加入 `sceneObject` → 设 `rootComponent` → 激活/初始化。
+- `deserializeComponent(data: ComponentJson)`:按 `type/version` `getOrLoad` 组件模块 → `new module.ComponentClass(scene)` → `comp.deserialize(data)`。
+- `createComponent(params, sync?)`:
+
+```ts
+type CreateComponentParams = {
+  type: string;
+  version?: string;
+  name?: string;          // 缺省用 Settings.name
+  parent?: Component;
+  data?: any;
+  states?: StateJson<any>[];
+  hierarchyConfig?: HierarchyConfig;
+};
+```
+
+  - `sync=true`:走 SaveManager 创建(同步后端);`sync=false`:本地用 `GetInitState`/`GetInitData` 初始化。
+- `createModelComponent(name, url, sync?, onProgress?)`:type 为 `"Model"`,data 为 `{ url$R, animation, sceneGraph, materialSlots, modification: { objects, materials }, physicsConfig }`;`onProgress(cur: 0~1, state: LoadState)`。
+- `create3dgsComponent(name, url, sync?, onProgress?)`:type 为 `"Splat3d"`,data 为 `{ url$R }`。
+- `removeComponent(comps: Component[], sync)`;`findComponentById/ByName/ByType`(走 `rootComponent.findById` 等);`findRuntimeComponentById`(含 VirtualChild)。
+- `reflowScene(compJson?)`:场景重排(版本升级);`updateComponentVersion(updateInfos)`。
+
+## 序列化结构(`src/core/interface.ts`,逐字)
+
+```ts
+type StateJson<T = any> = { id: string; name: string; config: T; using: boolean; rank: number };
+
+type ComponentJson<S = any, D = any> = {
+  id: string;             // 实体 id,仅用于层级关系
+  active: boolean;        // 世界大纲 config 修改
+  lock: boolean;          // 仅编辑器生效(是否被选中)
+  collapsed: boolean;
+  componentId: string;    // 组件 id,兼容后端绑定关系
+  name: string;
+  type: string;
+  version: string;
+  states?: StateJson<S>[];
+  data?: D;
+  children: ComponentJson[];
+  parentId: string | null; // 引擎不直接存储 parentId
+};
+
+interface SceneJson { id: string; name: string; sceneComponent: ComponentJson; }
+```
+
+注意:`Component.serialize()` 输出的 `componentId` 即 `this.id`;`states`/`data` 直接引用实例成员。
+
+## 资源(ResourceManager)
+
+`engine.getManager(ResourceManager)`。
+
+- `loadModelAsync(address, onProgress?)` → `GLTFLoadResult`(带缓存;失败 fallback 默认模型)。
+- `getModelInitData(url, onProgress?)` → `{ animation, sceneGraph, materialSlots, materialMap }`;animation 项:`autoPlay / loop("repeat"|"once"|"pingpong") / stopAtEnd / timeScale / id / name`。
+- `loadTextureAsync(address, onProgress?)`;`loadVideoTextureAsync(address)`(自动建 video:`muted`、`loop`、`playsInline`、`crossOrigin: "anonymous"`,mp4 source);`loadHDRTextureAsync(address, onProgress?)`(`.exr` 走 EXRLoader,否则 RGBELoader,自动 `EquirectangularReflectionMapping`)。
+- `loadCustomComponentScript(type, version, externalDeps)`:localOSSUrl 非空优先读 `${localOSSUrl}/${type}@${version}.js`,否则 `${baseOSSUrl}/easytwin/system/components/custom/${type}/${version}/script.js`。
+- `cacheModelByFileAsync(file, address)`;`instantiateModel(model)`(同 url 共享 geometry/纹理源);`getResourceUrl(relativeUrl)`。
+
+**资源路径约定(README)**:data 和 state 中**以 `$R` 结尾的字段**会被判定为资源路径,要求 value 是 string,参与导入导出(如 `url$R`)。
+
+## LCC 大场景(RuntimeScene)
+
+- `scene.loadLCC(dataPath, options?) → Promise<string | null>`:
+
+```ts
+options = {
+  useEnv?, useIndexDB?, useLoadingEffect?, appKey?, modelMatrix?,
+  enableCollision?, onComplete?(lccObject), onProgress?(percent), onError?,
+};
+```
+
+  - 默认 `useEnv` / `useIndexDB` / `useLoadingEffect` 为 `true`,`enableCollision` 为 `false`;返回实例 id,失败 `null`。
+- `scene.unloadLCC(id)` / `scene.unloadAllLCC()`;`scene.clearLCC()` 只清实例,保留 `window.LCCRender` 便于复用。

package/skills/easytwin-scene/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: easytwin-scene
+description: 当用户要列出场景、查看有哪些场景、或把某个场景的 JSON 拉到本地作为开发参考/预览输入时使用。
+---
+
+# 场景管理
+
+- `easytwin scene list`:列出凭据可见的场景。
+- `easytwin scene pull <id> [--out <path>]`:拉取场景 JSON 到本地,缺省输出 `./<id>.scene.json`。
+
+## 场景 JSON 格式
+
+<!-- TODO(外部输入): 场景 JSON 具体格式尚未定稿。格式到位后在此补充字段说明,并同步更新 scene/upload 实现与场景预览。 -->
+场景 JSON 的字段结构待定(向 EasyTwin 维护者索取)。当前拉取结果按服务端原样保存,字段以实际返回为准。
+
+> 注意:此处是**服务端场景 JSON**;runtime 内部用于 loadScene 的 SceneJson(组件树序列化结构)见 easytwin-render 的 references/scene-and-assets.md,两者出处不同。
+
+## 典型用法
+
+拉取参考场景,作为渲染开发与本地预览的输入:
+
+```bash
+easytwin scene list
+easytwin scene pull scene-123 --out ./scenes/scene-123.json
+```
+

package/skills/easytwin-upload/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: easytwin-upload
+description: 当用户要把本地开发产物目录上传回 EasyTwin、全量覆盖服务端内容、或询问上传是否可逆/会覆盖什么时使用。
+---
+
+# 全量上传(覆盖不可逆)
+
+`easytwin upload <dir>` 把 `<dir>` 下的全部文件上传,按 App ID 决定的目标空间**全量覆盖**。
+
+> ⚠️ **覆盖不可逆**:上传会覆盖服务端同名内容,没有本地清单与回滚机制。上传前务必确认目录内容与目标空间。
+
+## 行为
+
+- 递归收集 `<dir>` 下所有文件(默认跳过 `.git`)。
+- 逐文件 multipart 上传,带进度输出。
+- 上传目标空间由凭据(App ID)决定;pull 场景与 upload 目录是两条独立能力,互不引用。
+
+## 步骤
+
+1. 确认目标空间(App ID)与目录内容。
+2. `easytwin upload <dir>`,观察进度与完成摘要。