@easytwin/devkit 0.1.1 → 0.1.2

package/skills/easytwin-bootstrap/SKILL.md

@@ -15,17 +15,22 @@ description: 当用户要开始使用 EasyTwin DevKit、配置应用级凭证(Ap
   "appSecret": "必填",
   "env": "可选,prod=正式 / test=测试,缺省 prod",
   "baseUrl": "可选,缺省按 env 选官方域名",
-  "ossUrl": "可选,缺省官方 OSS"
+  "ossUrl": "可选,缺省官方 OSS",
+  "opAccountId": "可选,过渡期网关头 op-account-id;env=test 缺省 25",
+  "opUserId": "可选,过渡期网关头 op-user-id;env=test 缺省 25",
+  "spaceId": "可选,过渡期网关头 space-id;env=test 缺省 54",
+  "scenes": "可选,由 easytwin scene list 写入的场景摘要,不含 JSON 本体"
 }
 ```
 
-- 环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` / `EASYTWIN_ENV` / `EASYTWIN_OSS_URL` 优先于文件(CI 与不落盘场景)。
-- 官方 API:正式 `http://saas-twin.k8s.dtstack.cn/`、测试 `http://saas-twin-test.k8s.dtstack.cn/`;缺省按 env 选择,`EASYTWIN_BASE_URL` 始终优先。
+- 环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` / `EASYTWIN_ENV` / `EASYTWIN_OSS_URL` 优先于文件(CI 与不落盘场景)。过渡期另有 `EASYTWIN_OP_ACCOUNT_ID` / `EASYTWIN_OP_USER_ID` / `EASYTWIN_SPACE_ID`(当前测试后端走 OP 网关,免网关接口到位后删除)。
+- 官方 API:正式 `http://saas-twin.k8s.dtstack.cn/`、测试 `http://172.16.125.3:10100/`;缺省按 env 选择,`EASYTWIN_BASE_URL` 始终优先。
 - 官方 OSS:`https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/`,供 twin runtime 加载 webp wasm / draco / 组件脚本;`EASYTWIN_OSS_URL` 始终优先。
 - 该文件含密钥,**永不入库**:`init` 已负责 gitignore,不要把它提交进版本库。
-- **本地测试**:`appId` 与 `appSecret` 都填 `test` 时进入本地测试模式,scene/upload 走本地 mock、不发网络请求(见 easytwin-scene / easytwin-upload)。仅限本地联调,严禁用假凭据碰真实服务端。
+- `scenes` 由 `easytwin scene list`(或插件刷新场景树)写入,下次 list 会全量覆盖;`init` 重写配置时不会保留旧列表。
+- **本地测试**:`appId` 与 `appSecret` 都填 `test` 时进入本地测试模式,scene/upload/pull 走本地 mock、不发网络请求(见 easytwin-scene / easytwin-upload)。仅限本地联调,严禁用假凭据碰真实服务端。
 
 ## 步骤
 
 1. 若项目还没有 `easytwin.config.json`,运行 `easytwin init` 并按提示输入。
-2. 校验:`easytwin scene list` 能列出场景即凭据有效;报错则检查 appId / appSecret 或环境变量覆盖。
+2. 校验:`easytwin scene list` 能列出场景即凭据有效,并会把场景 id/名称写入 `easytwin.config.json.scenes`;报错则检查 appId / appSecret 或环境变量覆盖。

package/skills/easytwin-core/SKILL.md

@@ -5,7 +5,7 @@ description: 当用户要理解 EasyTwin 引擎内核(类层级、RuntimeEngine
 
 # 引擎内核(easytwin-runtime core)
 
-对应 npm 包 `@easytwin/runtime` 的 `src/core/` 目录:引擎本体、场景、组件基类与基础设施。写渲染功能的主流程见 `easytwin-render`;本技能是引擎核心的完整 API 参考。
+对应 `@easytwin/runtime` 的 `src/core/` 目录:引擎本体、场景、组件基类与基础设施。第三方应用入口是 TwinApp 子类,主流程见 `easytwin-render`;本技能是引擎内部 API 参考。
 
 ## 核心关系速览
 
@@ -22,4 +22,4 @@ description: 当用户要理解 EasyTwin 引擎内核(类层级、RuntimeEngine
 - 需要"相机体系(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`)。
+组件生命周期钩子、状态/数据 API 与序列化结构分别在 `easytwin-render` 的 `references/lifecycle-events.md` 与 `references/scene-and-assets.md`,本技能不重复(虚拟子要素的序列化结构见本技能 `references/virtual-components.md`)。

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

@@ -2,7 +2,7 @@
 
 ## 概览
 
-一个 `RuntimeEngine` 对应一个 DOM 容器(`engine.container`):
+TwinApp 从 `ctx.engine` 取用本对象。一个 `RuntimeEngine` 对应一个 DOM 容器(`engine.container`):
 
 - 注册并初始化五个 manager:`ResourceManager` / `SceneManager` / `CustomComponentManager` / `EditorActionsManager` / `PhysicsManager`;
 - 启动 `requestAnimationFrame` 渲染循环,每帧 `Time.update()` → `SceneManager.updateScene(deltaTime)`;
@@ -10,7 +10,7 @@
 
 ## create 与 EngineConfiguration
 
-唯一入口 `RuntimeEngine.create(config)`(静态、异步):
+宿主创建入口 `RuntimeEngine.create(config)`(静态、异步)。TwinApp 用 `ctx.engine`,不必再调:
 
 ```ts
 const engine = await RuntimeEngine.create({

package/skills/easytwin-develop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: easytwin-develop
-description: 当用户开始 EasyTwin 第三方应用开发、需要了解整体开发工作流(配置凭证→拉场景→写渲染→上传)、或询问"接下来该做什么/从哪开始"时使用。其余 EasyTwin 技能的总纲。
+description: 当用户开始 EasyTwin 第三方应用开发、需要了解整体开发工作流(配置凭证→拉工作区代码→拉场景→写 TwinApp 子类→上传)、或询问"接下来该做什么/从哪开始"时使用。其余 EasyTwin 技能的总纲。
 ---
 
 # EasyTwin 开发工作流
@@ -8,9 +8,10 @@ description: 当用户开始 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. **编写渲染功能**:在工作区 `src/main.ts` 写 `export default async function main(ctx)`(ctx = `{ engine, runtime, sceneJson }`),类型由 `easytwin skills sync` 分发,**不要** `npm install @easytwin/runtime`(公网不存在)。编译用 `easytwin bundle`,运行用插件预览页底部 Run。引擎内核见 `easytwin-core`。详见 `easytwin-render`(主力技能)。
-4. **上传产物**:`easytwin upload <dir>` 全量覆盖上传到服务端,不可逆。详见 `easytwin-upload`。
+2. **拉取工作区代码**:`easytwin pull` 从服务端下载代码;远端为空则写入默认 TwinApp `src/main.ts`;本地已有文件时先 diff,默认只补缺失。详见 `easytwin-upload`。
+3. **拉取场景**:`easytwin scene list` 列出场景,`easytwin scene pull <id>` 拉取场景 JSON 到本地,作为开发参考与预览输入。详见 `easytwin-scene`。
+4. **编写渲染功能**:在工作区 `src/main.ts` 写 TwinApp 子类(`import { TwinApp } from "@easytwin/apps"`,`export default class App extends TwinApp { init; onSceneLoaded; onUpdate; ... }`)。类型由 `easytwin skills sync` 分发。编译用 `easytwin bundle`,运行用插件预览页底部 Run。可上传子集只用 runtime 五件套导出;整包 API 仅本地预览。引擎内核见 `easytwin-core`。详见 `easytwin-render`(主力技能)。
+5. **上传产物**:`easytwin upload <dir>` 全量覆盖上传到服务端,不可逆。详见 `easytwin-upload`。
 
 ## 何时读哪个技能
 
@@ -20,10 +21,10 @@ EasyTwin DevKit 是 EasyTwin 第三方应用开发工具集。典型工作流:
 | 列场景、拉场景 JSON | easytwin-scene |
 | 用 twin runtime 写渲染 | easytwin-render |
 | 理解引擎内核 / 基类 / 相机 / 物理 | easytwin-core |
-| 上传开发产物 | easytwin-upload |
+| 上传 / 拉取工作区代码 | easytwin-upload |
 
 > 场景 JSON 格式以 easytwin-runtime 的 `SceneJson` 为准,详见 easytwin-scene。
 
 ## 本地测试
 
-没有凭据或不想动服务端时,把 `appId` / `appSecret` 都设为 `test` 即进入本地测试模式:`scene list` / `scene pull` 读 devkit 包内的 `scene.example.json`,`upload` 只做本地空跑,这两条不发服务端请求。插件里的场景预览仍是三维场景页(打包的 twin runtime + 本地示例 JSON),系统库(draco/basis/webp)与组件脚本按官方 OSS(=ossUrl)在线加载。预览页 Run 在 mock 下同样可用。
+没有凭据或不想动服务端时,把 `appId` / `appSecret` 都设为 `test` 即进入本地测试模式:`scene list` / `scene pull` 读 devkit 包内的 `scene.example.json`,`upload` 只做本地空跑,`pull` 按远端为空写入默认 `src/main.ts`(已有则不覆盖),这三条不发服务端请求。插件里的场景预览仍是三维场景页(打包的 twin runtime + 本地示例 JSON),系统库(draco/basis/webp)与组件脚本按官方 OSS(=ossUrl)在线加载。预览页 Run 在 mock 下同样可用。

package/skills/easytwin-render/SKILL.md

@@ -1,35 +1,74 @@
 ---
 name: easytwin-render
-description: 当用户要用 EasyTwin twin runtime 编写渲染功能(写 src/main.ts、预览页 Run、easytwin bundle、加载场景、开发自定义组件、调用渲染 API)时使用。这是 EasyTwin 渲染开发的唯一入口技能。
+description: 当用户要用 EasyTwin twin runtime 编写渲染功能(写 src/main.ts TwinApp 子类、class extends TwinApp、预览页 Run、easytwin bundle、加载场景、开发自定义组件、调用渲染 API)时使用。这是 EasyTwin 渲染开发的唯一入口技能。
 ---
 
 # 用 twin runtime 开发渲染功能
 
-`@easytwin/runtime` 是商业包,公网 npm 不存在,**严禁** `npm install @easytwin/runtime`。类型声明由 `easytwin skills sync` 写入项目 `.easytwin/types/`;运行走预览页底部 **Run** 按钮,或 `easytwin bundle` 做编译校验。
+`@easytwin/runtime` 是商业包,公网 npm 不存在,类型由 `easytwin skills sync` 写入 `.easytwin/types/`。`TwinApp` 从 `@easytwin/apps` 引入(同样由 sync 分发)。运行走预览页底部 **Run**,或 `easytwin bundle` 做编译校验。
 
-## 编写与运行 main.ts
+## 编写 TwinApp 子类(可上传子集)
 
-工作区固定入口 `src/main.ts`(缺失则编译报错)。只能依赖 `@easytwin/runtime`(相对路径的本地 TS 可以),禁止任何其他裸模块。
+工作区固定入口 `src/main.ts`。依赖只允许 `@easytwin/runtime` 与 `@easytwin/apps`(相对路径本地 TS 可以)。`export default` 必须是 `TwinApp` 子类:
 
 ```ts
-import type { EasyTwinRunContext } from "@easytwin/runtime";
-
-export default async function main(ctx: EasyTwinRunContext) {
-  const { engine, runtime, sceneJson } = ctx;
-  // 在已加载的场景上写渲染/交互逻辑
-  void engine;
-  void runtime;
-  void sceneJson;
+import { THREE } from "@easytwin/runtime";
+import { TwinApp, type TwinAppContext } from "@easytwin/apps";
+
+export default class App extends TwinApp {
+  async init(ctx: TwinAppContext) {
+    // engine / container 已有;scene / camera / runtimeScene 为 null
+    void ctx;
+  }
+
+  async onSceneLoaded(ctx: TwinAppContext) {
+    const mesh = new THREE.Mesh(
+      new THREE.BoxGeometry(1, 1, 1),
+      new THREE.MeshBasicMaterial({ color: 0x44aa88 }),
+    );
+    ctx.scene?.add(mesh);
+    ctx.sceneCleanup(() => {
+      ctx.scene?.remove(mesh);
+    });
+  }
+
+  onUpdate(ctx: TwinAppContext, delta: number, elapsed: number) {
+    void ctx;
+    void delta;
+    void elapsed;
+  }
+
+  onBeforeSceneUnload(ctx: TwinAppContext) {
+    void ctx;
+  }
+
+  onDispose(ctx: TwinAppContext) {
+    void ctx;
+  }
 }
 ```
 
-1. 若还没有类型:运行 `easytwin skills sync`(无 tsconfig 会生成最小配置;已有 tsconfig 时在输出里看 `paths` 片段,自行加上 `"@easytwin/runtime": [".easytwin/types"]` 并建议 `skipLibCheck: true`)。
-2. 编译校验:`easytwin bundle`(缺省写出 `dist/main.js`,ESM + inline sourcemap)。检测到 lodash 等外部依赖会给出人话报错,不要据此去 npm install。
-3. 运行:打开插件场景预览,点底部 **Run**。宿主内存编译(不落盘)→ blob URL + import map 把 `@easytwin/runtime` 指到页面已加载的同一 runtime 实例 → 先重新 `loadScene` 再调用 `export default main(ctx)`。编译失败不打断已渲染场景;mock 下同样可用。
+等价对象写法:`export default defineApp({ init, onSceneLoaded, onUpdate, ... })`。宿主只认这两种;函数导出(旧 `main`)会报错。
+
+可上传到在线 TwinApp 的 runtime 导出名只有:`THREE`、`RuntimeEngine`、`SceneManager`、`LoadSceneMode`、`convertObjToComponentJson`。超出这些名字本地能编过并 warning,在线会失败。
+
+生命周期由宿主驱动。引擎与场景已在预览页创建;`init` 里场景字段为 null,物体与事件写在 `onSceneLoaded`,用 `ctx.sceneCleanup` 对称拆除。
+
+| 钩子 | 时机 |
+| --- | --- |
+| `init` | 引擎 / 容器已有;场景字段为 null |
+| `onSceneLoaded` | 宿主 `loadScene` 之后 |
+| `onUpdate` | 引擎时钟每帧(加载中不调);仅此钩子 throw 走 `onError`(返回 `true` 继续) |
+| `onBeforeSceneUnload` | 再 Run / 卸场景前 |
+| `onDispose` | 应用拆除;引擎不 destroy,下次 Run 复用 |
+
+本地预览只有当前这一份场景,`ctx.sceneManager.loadScene` 会 reject。`ctx.assets.text/json` 读工作区相对路径。从 `ctx.engine` 取引擎,不要再 `RuntimeEngine.create`。
 
-`ctx`:`engine` 是现成 `RuntimeEngine`;`runtime` 是整个模块命名空间(枚举/类从此取);`sceneJson` 是当前场景数据。
+1. 若还没有类型:运行 `easytwin skills sync`(无 tsconfig 会生成最小配置,含 `@easytwin/runtime` 与 `@easytwin/apps` 的 paths;已有 tsconfig 时按输出片段自行添加)。
+2. 编译校验:`easytwin bundle`。lodash 等外部依赖会报错。超出在线 stub 的 runtime import 只 warning。
+3. 运行:打开插件场景预览(先看到三维场景),点底部 **Run**。再点 Run 会先 `onBeforeSceneUnload` / `onDispose`,复用同一台引擎。编译失败不打断已渲染场景;mock 下同样可用。
 
-完整「自己 create engine」的 API 细节见下方 references;预览页 Run 走注入式 ctx,不必在 main.ts 里再 `RuntimeEngine.create`。
+`Component` / `VirtualRootComponent` 等整包 API 本地预览可用,但**不是**可上传子集;需要组件生命周期细节时读 `references/lifecycle-events.md`。
 
 ## 参考(references/)
 

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

@@ -1,13 +1,17 @@
 # 引入与初始化
 
+## TwinApp 里如何拿到引擎
+
+用户代码入口是 `src/main.ts` 的 `export default class App extends TwinApp`。预览页 / 在线环境已经创建引擎并加载场景;钩子里用 `ctx.engine` / `ctx.container` / `ctx.scene`。可上传子集只用 `THREE` / `RuntimeEngine` / `SceneManager` / `LoadSceneMode` / `convertObjToComponentJson`。
+
 ## 包信息
 
-- npm 包名:`@easytwin/runtime`(商业包,公网不存在)。**不要** `npm install`;类型由 `easytwin skills sync` 写入 `.easytwin/types/`,运行走预览页 Run 或 `easytwin bundle`。
-- 用户代码入口:`src/main.ts` 的 `export default async function main(ctx)`,ctx 由预览页注入,一般不必自己 `RuntimeEngine.create`。
+- npm 包名:`@easytwin/runtime`(商业包,公网不存在)。类型由 `easytwin skills sync` 写入 `.easytwin/types/`,运行走预览页 Run 或 `easytwin bundle`。
+- `TwinApp` / `defineApp` / `TwinAppContext` 从 `@easytwin/apps` 引入(同样由 sync 分发)。
 
-## 初始化 RuntimeEngine
+## RuntimeEngine.create(宿主调用)
 
-唯一入口:`RuntimeEngine.create(config)`(静态、异步)。
+工厂方法:`RuntimeEngine.create(config)`(静态、异步)。TwinApp 从 `ctx.engine` 取用已创建的实例。
 
 ```ts
 import { RuntimeEngine, SceneManager, LoadSceneMode } from "@easytwin/runtime";

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

@@ -1,6 +1,6 @@
 # 场景加载与资产
 
-> 说明:本节讲的是 runtime 的场景 JSON(组件树序列化结构,`SceneJson`,定义见 `src/core/interface.ts`)与资产加载。`easytwin scene pull` 拉取的服务端场景 JSON 同样以该结构为准(见 easytwin-scene)。可用 `SceneManager.importScene` 或 `loadScene` 把本地 JSON 喂给 runtime。
+> 说明:本节讲的是 runtime 的场景 JSON(组件树序列化结构,`SceneJson`,定义见 `src/core/interface.ts`)与资产加载。`easytwin scene pull` 拉取的服务端场景 JSON 同样以该结构为准(见 easytwin-scene)。TwinApp 场景由宿主加载;本地预览里 `ctx.sceneManager.loadScene` 会 reject。下面是 SceneManager 内部 API。
 
 ## 场景管理(SceneManager)
 

package/skills/easytwin-scene/SKILL.md

@@ -5,8 +5,8 @@ description: 当用户要列出场景、查看有哪些场景、或把某个场
 
 # 场景管理
 
-- `easytwin scene list`:列出凭据可见的场景。
-- `easytwin scene pull <id> [--out <path>]`:拉取场景 JSON 到本地,缺省输出 `./<id>.scene.json`。
+- `easytwin scene list`:列出 SDK 应用已关联的场景(id 为 Scene Key),并把摘要(id / name / linkedSceneId / snapshotUrl / defaultLoading)写入项目 `easytwin.config.json` 的 `scenes` 数组(全量覆盖,不含场景 JSON)。
+- `easytwin scene pull <id> [--out <path>]`:按 Scene Key(或关联记录 id)拉取场景快照 JSON 到本地,缺省输出 `./<id>.scene.json`。
 
 ## 场景 JSON 格式
 

package/skills/easytwin-upload/SKILL.md

@@ -1,25 +1,38 @@
 ---
 name: easytwin-upload
-description: 当用户要把本地开发产物目录上传回 EasyTwin、全量覆盖服务端内容、或询问上传是否可逆/会覆盖什么时使用。
+description: 当用户要把本地开发产物目录上传回 EasyTwin、从服务端拉取工作区代码、远端没有代码时创建默认文件、或询问上传是否可逆/与本地 diff 如何同步时使用。
 ---
 
-# 全量上传(覆盖不可逆)
+# 工作区代码:拉取与全量上传
 
-`easytwin upload <dir>` 把 `<dir>` 下的全部文件上传,按 App ID 决定的目标空间**全量覆盖**。
+上传与拉取共用同一套工作区代码接口,方向相反。
 
-> ⚠️ **覆盖不可逆**:上传会覆盖服务端同名内容,没有本地清单与回滚机制。上传前务必确认目录内容与目标空间。
+## 拉取:`easytwin pull [dir]`
 
-## 行为
+从服务端下载 App ID 对应的工作区文件到 `[dir]`(缺省当前目录)。
 
-- 递归收集 `<dir>` 下所有文件(默认跳过 `.git`)。
-- 逐文件 multipart 上传,带进度输出。
-- 上传目标空间由凭据(App ID)决定;pull 场景与 upload 目录是两条独立能力,互不引用。
+- 远端为空:本地没有 `src/main.ts` 时写入默认 TwinApp 子类入口;本地已有入口则不覆盖。
+- 远端有文件:与本地做 diff。`identical` 跳过,`remote-only` 写入,`local-only` 保留,**内容冲突默认不覆盖**。
+- `--force` 才用远端内容覆盖冲突文件;即使 `--force` 也不删除仅本地文件。
+- `--dry-run` 只打印 diff,不写盘。
+- 本地测试模式(`appId`/`appSecret` 均为 `test`):不发请求,按远端为空处理。
+
+有冲突时先看摘要,确认要用远端覆盖再加 `--force`。插件里可对冲突文件打开「远程 ↔ 本地」diff。
+
+## 上传:`easytwin upload <dir>`
 
-## 本地测试模式(mock)
+把 `<dir>` 下的全部文件上传,按 App ID 决定的目标空间**全量覆盖**。
+
+> ⚠️ **覆盖不可逆**:上传会覆盖服务端同名内容,没有本地清单与回滚机制。上传前务必确认目录内容与目标空间。
+
+- 递归收集 `<dir>` 下所有文件(默认跳过 `.git`)。
+- 按工作区代码文件接口全量覆盖:先拉远端文件列表与约束(扩展名/数量/目录深度),再删除远端多余文件、批量更新变更、逐个新建缺失文件。
+- 上传目标空间由凭据(App ID)决定;场景 pull 与工作区 pull/upload 是独立能力,互不引用。
 
-当 `appId` 与 `appSecret` 均为 `test` 时,`easytwin upload <dir>` 退化为本地空跑(dry-run):只收集与统计文件、不上传,进度照常上报,输出标注「本地测试模式」。适合在无凭据/不想动服务端时演练上传流程。
+当 `appId` 与 `appSecret` 均为 `test` 时,`easytwin upload <dir>` 退化为本地空跑(dry-run):只收集与统计文件、不上传,进度照常上报,输出标注「本地测试模式」。
 
 ## 步骤
 
-1. 确认目标空间(App ID)与目录内容。
-2. `easytwin upload <dir>`,观察进度与完成摘要。
+1. 新项目或本地还没有代码:`easytwin pull`(远端空则得到默认 `src/main.ts`)。
+2. 本地已有改动且可能与远端不同:`easytwin pull --dry-run` 看 diff,再决定是否 `--force`。
+3. 确认目标空间(App ID)与目录内容后,`easytwin upload <dir>` 上传(不可逆)。