@easytwin/devkit 0.1.3 → 0.1.4

package/skills/easytwin-bootstrap/SKILL.md

@@ -1,33 +1,37 @@
----
-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": "必填",
-  "env": "可选,prod=正式 / test=测试,缺省 prod",
-  "baseUrl": "可选,缺省按 env 选官方域名",
-  "ossUrl": "可选,缺省官方 OSS",
-  "scenes": "可选,由 easytwin scene list 写入的场景摘要,不含 JSON 本体"
-}
-```
-
-- 环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` / `EASYTWIN_ENV` / `EASYTWIN_OSS_URL` 优先于文件(CI 与不落盘场景)。请求带 `x-app-id`(App ID)与 `x-app-secret`(App Secret),不走 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,不要把它提交进版本库。
-- `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` 能列出场景即凭据有效,并会把场景 id/名称写入 `easytwin.config.json.scenes`;报错则检查 appId / appSecret 或环境变量覆盖。
+---
+name: easytwin-bootstrap
+description: 当用户要开始使用 EasyTwin DevKit、配置应用级凭证(App ID / App Secret / Base URL)、运行 easytwin init、或校验 .easytwin/easytwin.config.json 是否存在/有效时使用。
+---
+
+# 初始化与凭据
+
+`easytwin init` 交互式生成项目级 `.easytwin/easytwin.config.json`,并把凭据路径与 `.easytwin/scenes/` 追加进 `.gitignore`(无则创建)。
+
+## 配置契约
+
+路径:`.easytwin/easytwin.config.json`
+
+```json
+{
+  "appId": "必填",
+  "appSecret": "必填",
+  "env": "可选,prod=正式 / test=测试,缺省 prod",
+  "baseUrl": "可选,缺省按 env 选官方域名",
+  "ossUrl": "可选,缺省官方 OSS",
+  "scenes": "可选,由 easytwin scene list 写入的场景摘要,不含 JSON 本体"
+}
+```
+
+- 环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` / `EASYTWIN_ENV` / `EASYTWIN_OSS_URL` 优先于文件(CI 与不落盘场景)。请求带 `x-app-id`(App ID)与 `x-app-secret`(App Secret),不走 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` 始终优先。
+- runtime 类型:`env=prod` 用 `https://dt-easyv-prod.oss-cn-hangzhou.aliyuncs.com/easytwin/system/libs/runtime/types/`,其余用测试桶同路径;`skills sync` 拉取 `index.d.ts`。
+- 该文件含密钥,**永不入库**:`init` 已负责 gitignore,不要把它提交进版本库。不忽略整个 `.easytwin/`,以便 `types/` 可入库。
+- `scenes` 由 `easytwin scene list`(或插件刷新场景树)写入,下次 list 会全量覆盖;`init` 重写配置时不会保留旧列表。
+- 若项目根仍有旧版 `easytwin.config.json`,读配置时会自动迁入 `.easytwin/` 并删除旧文件。
+- **本地测试**:`appId` 与 `appSecret` 都填 `test` 时进入本地测试模式,scene/upload/pull 走本地 mock、不发网络请求(见 easytwin-scene / easytwin-upload)。仅限本地联调,严禁用假凭据碰真实服务端。
+
+## 步骤
+
+1. 若项目还没有 `.easytwin/easytwin.config.json`,运行 `easytwin init` 并按提示输入。
+2. 校验:`easytwin scene list` 能列出场景即凭据有效,并会把场景 id/名称写入配置的 `scenes`;报错则检查 appId / appSecret 或环境变量覆盖。

package/skills/easytwin-develop/SKILL.md

@@ -1,32 +1,32 @@
----
-name: easytwin-develop
-description: 当用户开始 EasyTwin 第三方应用开发、需要了解整体开发工作流(配置凭证→拉工作区代码→拉场景→写 TwinApp 子类→预览测试→上传)、或询问"接下来该做什么/从哪开始"时使用。其余 EasyTwin 技能的总纲。
----
-
-# EasyTwin 开发工作流
-
-EasyTwin DevKit 是 EasyTwin 第三方应用开发工具集。典型工作流:
-
-1. **配置凭证**:运行 `easytwin init` 生成项目级 `easytwin.config.json`(App ID / App Secret)。详见 `easytwin-bootstrap`。
-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`,运行用 `easytwin preview`(浏览器打开打印的 URL,点 Run)或插件预览页底部 Run。可上传子集只用 runtime 五件套导出;整包 API 仅本地预览。引擎内核见 `easytwin-core`。详见 `easytwin-render`(主力技能)。
-5. **预览测试**:在 `*.spec.ts` 里导出函数,`easytwin preview` 或插件预览页为每个导出生成按钮或输入框。测试文件不同步到服务端。详见 `easytwin-test`。
-6. **上传产物**:`easytwin upload` 对照远端区分新增/更新/删除,使服务端与本地工作区一致(跳过插件产物与 `*.spec.ts`,不可逆)。详见 `easytwin-upload`。
-
-## 何时读哪个技能
-
-| 场景 | 技能 |
-| --- | --- |
-| 初始化 / 校验凭证 | easytwin-bootstrap |
-| 列场景、拉场景 JSON | easytwin-scene |
-| 用 twin runtime 写渲染 | easytwin-render |
-| 给预览加可点击测试 / 写 `.spec.ts` | easytwin-test |
-| 理解引擎内核 / 基类 / 相机 / 物理 | easytwin-core |
-| 上传 / 拉取工作区代码 | easytwin-upload |
-
-> 场景 JSON 格式以 easytwin-runtime 的 `SceneJson` 为准,详见 easytwin-scene。
-
-## 本地测试
-
-没有凭据或不想动服务端时,把 `appId` / `appSecret` 都设为 `test` 即进入本地测试模式:`scene list` / `scene pull` 读 devkit 包内的 `scene.example.json`,`upload` 只做本地空跑,`pull` 按远端为空写入默认 `src/main.ts`(已有则不覆盖),这三条不发服务端请求。`easytwin preview` 与插件预览仍是三维场景页(打包的 twin runtime + 本地示例 JSON),系统库(draco/basis/webp)与组件脚本按官方 OSS(=ossUrl)在线加载。预览页 Run 在 mock 下同样可用。
+---
+name: easytwin-develop
+description: 当用户开始 EasyTwin 第三方应用开发、需要了解整体开发工作流(配置凭证→拉工作区代码→拉场景→写 TwinApp 子类→预览测试→上传)、或询问"接下来该做什么/从哪开始"时使用。其余 EasyTwin 技能的总纲。
+---
+
+# EasyTwin 开发工作流
+
+EasyTwin DevKit 是 EasyTwin 第三方应用开发工具集。典型工作流:
+
+1. **配置凭证**:运行 `easytwin init` 生成项目级 `.easytwin/easytwin.config.json`(App ID / App Secret)。详见 `easytwin-bootstrap`。
+2. **拉取工作区代码**:`easytwin pull` 从服务端下载代码;远端为空则写入默认 TwinApp `src/main.ts`;本地已有文件时先 diff,默认只补缺失。详见 `easytwin-upload`。
+3. **拉取场景**:`easytwin scene list` 列出场景,`easytwin scene pull <id>` 拉取 JSON 到 `.easytwin/scenes/`。看物体用 `easytwin scene inspect <id>`(不要整文件读入)。详见 `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`,运行用 `easytwin preview`(浏览器打开打印的 URL,点 Run)或插件预览页底部 Run。可上传子集只用 runtime 五件套导出;整包 API 仅本地预览。引擎内核见 `easytwin-core`。详见 `easytwin-render`(主力技能)。
+5. **预览测试**:在 `*.spec.ts` 里导出函数,`easytwin preview` 或插件预览页为每个导出生成按钮或输入框。测试文件不同步到服务端。详见 `easytwin-test`。
+6. **上传产物**:`easytwin upload` 对照远端区分新增/更新/删除,使服务端与本地工作区一致(跳过插件产物与 `*.spec.ts`,不可逆)。详见 `easytwin-upload`。
+
+## 何时读哪个技能
+
+| 场景 | 技能 |
+| --- | --- |
+| 初始化 / 校验凭证 | easytwin-bootstrap |
+| 列场景、拉场景 JSON、inspect 本地对象树 | easytwin-scene |
+| 用 twin runtime 写渲染 | easytwin-render |
+| 给预览加可点击测试 / 写 `.spec.ts` | easytwin-test |
+| 理解引擎内核 / 基类 / 相机 / 物理 | easytwin-core |
+| 上传 / 拉取工作区代码 | easytwin-upload |
+
+> 场景 JSON 格式见 easytwin-render 的 `references/scene-and-assets.md`。查本地物体用 `easytwin scene inspect`。
+
+## 本地测试
+
+没有凭据或不想动服务端时,把 `appId` / `appSecret` 都设为 `test` 即进入本地测试模式:`scene list` / `scene pull` 读 devkit 包内的 `scene.example.json`,`upload` 只做本地空跑,`pull` 按远端为空写入默认 `src/main.ts`(已有则不覆盖),这三条不发服务端请求。`easytwin preview` 与插件预览仍是三维场景页(打包的 twin runtime + 本地示例 JSON),系统库(draco/basis/webp)与组件脚本按官方 OSS(=ossUrl)在线加载。预览页 Run 在 mock 下同样可用。

package/skills/easytwin-render/SKILL.md

@@ -5,7 +5,7 @@ description: 当用户要用 EasyTwin twin runtime 编写渲染功能(写 src/ma
 
 # 用 twin runtime 开发渲染功能
 
-`@easytwin/runtime` 是商业包,公网 npm 不存在,类型由 `easytwin skills sync` 写入 `.easytwin/types/`。`TwinApp` 从 `@easytwin/apps` 引入(同样由 sync 分发)。运行走 `easytwin preview` 打开的预览页底部 **Run**,或插件预览,或 `easytwin bundle` 做编译校验。
+`@easytwin/runtime` 是商业包,公网 npm 不存在,类型由 `easytwin skills sync` 从官方 OSS 拉取写入 `.easytwin/types/`(测试桶 `.../easytwin/system/libs/runtime/types/`,正式桶同路径)。`TwinApp` 从 `@easytwin/apps` 引入(同样由 sync 分发)。运行走 `easytwin preview` 打开的预览页底部 **Run**,或插件预览,或 `easytwin bundle` 做编译校验。
 
 ## 编写 TwinApp 子类(可上传子集)
 

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

@@ -6,7 +6,7 @@
 
 ## 包信息
 
-- npm 包名:`@easytwin/runtime`(商业包,公网不存在)。类型由 `easytwin skills sync` 写入 `.easytwin/types/`,运行走预览页 Run 或 `easytwin bundle`。
+- npm 包名:`@easytwin/runtime`(商业包,公网不存在)。类型由 `easytwin skills sync` 从 OSS `easytwin/system/libs/runtime/types/index.d.ts` 写入 `.easytwin/types/`,运行走预览页 Run 或 `easytwin bundle`。
 - `TwinApp` / `defineApp` / `TwinAppContext` 从 `@easytwin/apps` 引入(同样由 sync 分发)。
 
 ## RuntimeEngine.create(宿主调用)

package/skills/easytwin-scene/SKILL.md

@@ -1,57 +1,37 @@
 ---
 name: easytwin-scene
-description: 当用户要列出场景、查看有哪些场景、或把某个场景的 JSON 拉到本地作为开发参考/预览输入时使用。
+description: 当用户要列出场景、查看有哪些场景、把某个场景的 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`。
+- `easytwin scene list`:列出 SDK 应用已关联的场景(id 为 Scene Key),并把摘要写入 `.easytwin/easytwin.config.json` 的 `scenes` 数组(全量覆盖,不含 JSON 本体)。
+- `easytwin scene pull <id> [--out <path>]`:拉取场景快照。始终写入 `.easytwin/scenes/<id>.scene.json`;`--out` 再额外写一份。插件预览、场景树展开、`easytwin preview` 同样落盘。
+- `easytwin scene inspect <id> [--name <substr>] [--type <type>]`:只读本地快照,打印对象树(`id`/`name`/`type`)。**不要 Read 整份 `.scene.json`。**
 
-## 场景 JSON 格式
+场景 JSON 的类型与加载语义见 `easytwin-render/references/scene-and-assets.md`(写渲染、对字段时再读)。
 
-场景 JSON 以 easytwin-runtime 的 `SceneJson` 为准(`packages/easytwin-runtime/src/core/interface.ts`),即组件树序列化结构:
+## 看本地场景(节约上下文)
 
-```ts
-type StateJson<T = any> = { id: string; name: string; config: T; using: boolean; rank: number };
+1. 没有 `.easytwin/scenes/<id>.scene.json` 时先 `easytwin scene pull <id>`。inspect 不自动 pull、不打网络。
+2. `easytwin scene inspect <id>` 看整棵树。超过 200 个节点会截断并提示加过滤。
+3. 缩小范围:`--name` 子串(不区分大小写)、`--type` 精确匹配,同时给是 AND。输出保留匹配节点与祖先。
+4. 要改某个物体的 `data` / `states` 时,用 Grep 搜该 **id**,不要整文件读入。
 
-type ComponentJson<S = any, D = any> = {
-  id: string;             // 实体 id,仅用于层级关系
-  active: boolean;        // 世界大纲 config 修改
-  lock: boolean;          // 仅编辑器生效(是否被选中)
-  collapsed: boolean;     // 世界大纲 config 修改
-  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; }
+```bash
+easytwin scene list
+easytwin scene pull scene-123
+easytwin scene inspect scene-123
+easytwin scene inspect scene-123 --type Model
+easytwin scene inspect scene-123 --name 球
 ```
 
-`easytwin scene pull` 按服务端原样保存;该结构可直接作为渲染开发参考与本地预览输入(runtime 的 `SceneManager.loadScene` / `importScene` 接受它,详见 easytwin-render 的 references/scene-and-assets.md)。
-
 ## 本地测试模式(mock)
 
 当 `appId` 与 `appSecret` 均为 `test` 时,`scene list` / `scene pull` 不再请求服务端,改读 devkit 包内 `scene.example.json`:
 
 - 场景 id 取 `objs[].sceneId` 首个非空值(当前示例为 `sceJTHH9yoqFyRyS9`),场景名固定为「本地示例场景」;
 - `scene pull` 的 id 必须与示例 id 一致,否则报错;
-- 命令输出会标注「本地测试模式」。该模式仅用于本地联调,不发网络请求。
-
-## 典型用法
-
-拉取参考场景,作为渲染开发与本地预览的输入:
-
-```bash
-easytwin scene list
-easytwin preview
-easytwin scene pull scene-123 --out ./scenes/scene-123.json
-```
-
-`easytwin preview [sceneId]` 起本地预览页(三维 + Run + 测试控件),用浏览器打开打印的 URL。缺省 sceneId 取配置 `scenes` 里 `defaultLoading` 否则首项。
+- 落盘后同样用 `easytwin scene inspect sceJTHH9yoqFyRyS9` 看树。
 
+`easytwin preview [sceneId]` 起本地预览页。缺省 sceneId 取配置 `scenes` 里 `defaultLoading` 否则首项。

package/skills/easytwin-upload/SKILL.md

@@ -25,7 +25,7 @@ description: 当用户要把本地工作区上传回 EasyTwin、从服务端拉
 
 > ⚠️ **覆盖不可逆**:远端多余文件会删除,同名内容会更新,没有本地清单与回滚机制。
 
-- 递归收集目录下文件,默认只处理 `.ts` / `.tsx` / `.js` / `.json`;并跳过插件产物与相关路径:`.git` / `node_modules` / `dist` / `.easytwin` / `.cursor` / `.claude` / `.qoder` / `.vscode`、`easytwin.config.json`、`.gitignore`、`tsconfig.json` / `tsconfig.*.json`、`*.scene.json`、`*.spec.ts`(预览测试,见 easytwin-test)。
+- 递归收集目录下文件,默认只处理 `.ts` / `.tsx` / `.js` / `.json`;并跳过插件产物与相关路径:`.git` / `node_modules` / `dist` / `.easytwin` / `.cursor` / `.claude` / `.qoder` / `.vscode`、根目录残留的 `easytwin.config.json`、`.gitignore`、`tsconfig.json` / `tsconfig.*.json`、`*.scene.json`、`*.spec.ts`(预览测试,见 easytwin-test)。
 - 先 `POST .../share/sdk-application-code/pull` 拉远端文件,本地 diff 后一次 `POST .../share/sdk-application-code/push`(`create`/`update`/`delete`);内容相同跳过、无变更不发 push。不请求仍走 OP 网关的 `workspace-config`。
 - 上传目标空间由凭据(`x-app-id` + `x-app-secret`)决定;场景 pull 与工作区 pull/upload 是独立能力,互不引用。
 - 认证头 `x-app-id` = App ID、`x-app-secret` = App Secret,不走 OP 网关。