@easytwin/devkit 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-/** 配置文件名(项目根)。 */
+/** 用户项目内工具目录(凭据 / 场景快照 / types)。 */
+declare const EASYTWIN_DIR = ".easytwin";
+/** 配置文件名(落在 `.easytwin/` 下,D29)。 */
 declare const CONFIG_FILE_NAME = "easytwin.config.json";
+/** scene pull 缺省目录(相对 `.easytwin/`)。 */
+declare const EASYTWIN_SCENES_DIRNAME = "scenes";
 /**
  * 官方缺省域名(正式环境)。该常量是全仓唯一收口点,只允许写在这里。
  */
@@ -7,13 +11,19 @@ declare const DEFAULT_BASE_URL = "http://saas-twin.k8s.dtstack.cn/";
 /** 官方测试环境域名。 */
 declare const TEST_BASE_URL = "http://172.16.125.3:10100/";
 /**
- * 官方 OSS(twin runtime baseOSSUrl)。系统资产由此拼出:
- * `{ossUrl}/easytwin/system/libs/webp-wasm.wasm`、
+ * 官方测试 OSS。twin runtime baseOSSUrl 缺省用此桶(D11)。
+ * 系统资产由此拼出:`{ossUrl}/easytwin/system/libs/webp-wasm.wasm`、
  * `{ossUrl}/easytwin/system/libs/draco/`、
  * `{ossUrl}/easytwin/system/components/custom/{type}/{version}/script.js`。
  * 不得用 API baseUrl 代替:场景/上传走 API,系统库与组件脚本走 OSS。
  */
+declare const TEST_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+/** 官方正式 OSS。runtime 类型在 env=prod 时用此桶(D31);资产根缺省仍为测试桶。 */
+declare const PROD_OSS_URL = "https://dt-easyv-prod.oss-cn-hangzhou.aliyuncs.com/";
+/** 资产根缺省 = 测试 OSS(D11)。 */
 declare const DEFAULT_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+/** runtime 类型声明相对 OSS 根的路径(D31)。 */
+declare const RUNTIME_TYPES_RELPATH = "easytwin/system/libs/runtime/types/index.d.ts";
 /** 服务环境,决定缺省 baseUrl。 */
 type EasyTwinEnv = "prod" | "test";
 /** 本地测试模式哨兵凭据:appId 与 appSecret 均为该值时,场景/上传走本地 mock,不发网络请求(见 AGENTS.md 4.4)。 */
@@ -60,6 +70,25 @@ declare class ConfigError extends Error {
     constructor(message: string);
 }
 declare function configFilePath(cwd: string): string;
+/** 拼接 OSS 根与相对路径,两端斜杠归一。 */
+declare function joinOssPath(ossUrl: string, relPath: string): string;
+/**
+ * `@easytwin/runtime` 类型 `index.d.ts` 的 OSS 地址(D31)。
+ * 显式 ossUrl 优先;否则 `env=prod` 用正式桶,其余(含缺省)用测试桶。
+ */
+declare function resolveRuntimeTypesUrl(options?: {
+    env?: EasyTwinEnv;
+    ossUrl?: string;
+}): string;
+/**
+ * 按工作区配置 / 环境变量解析类型 URL。无配置文件时仍可拉缺省测试桶。
+ * 只把文件或环境变量里显式给出的 ossUrl 当作覆盖,不把 DEFAULT_OSS_URL 当成显式值。
+ */
+declare function resolveRuntimeTypesUrlForCwd(cwd: string, env?: NodeJS.ProcessEnv): Promise<string>;
+/** D29 之前项目根的旧配置路径。 */
+declare function legacyConfigFilePath(cwd: string): string;
+/** `easytwin scene pull` 缺省输出:`.easytwin/scenes/<id>.scene.json`。 */
+declare function defaultSceneOutPath(cwd: string, id: string): string;
 declare function parseConfig(raw: string): EasyTwinConfig;
 declare function validateConfigShape(value: unknown): EasyTwinConfig;
 declare function readConfigFile(cwd: string): Promise<EasyTwinConfig>;
@@ -68,12 +97,15 @@ declare function resolveConfig(file: EasyTwinConfig, env?: NodeJS.ProcessEnv): R
 declare function loadConfig(cwd: string, env?: NodeJS.ProcessEnv): Promise<ResolvedConfig>;
 declare function writeConfigFile(cwd: string, config: EasyTwinConfig): Promise<string>;
 declare const GITIGNORE_FILE_NAME = ".gitignore";
-declare const GITIGNORE_ENTRY = "easytwin.config.json";
+/** 凭据文件 gitignore 条目(相对项目根)。 */
+declare const GITIGNORE_ENTRY = ".easytwin/easytwin.config.json";
+/** init 写入 .gitignore 的条目:凭据 + 场景快照目录。不忽略整个 `.easytwin/`,以便 types 可入库。 */
+declare const GITIGNORE_ENTRIES: readonly [".easytwin/easytwin.config.json", ".easytwin/scenes/"];
 interface GitignoreResult {
     created: boolean;
     added: boolean;
 }
-/** 把配置文件名追加进 .gitignore(无则创建),幂等:已存在条目时不重复追加。 */
+/** 把凭据与场景快照路径追加进 .gitignore(无则创建),幂等:已存在条目时不重复追加。 */
 declare function appendGitignore(cwd: string): Promise<GitignoreResult>;
 interface InitResult {
     configFile: string;
@@ -202,6 +234,7 @@ declare function listScenes(client: EasyTwinClient, options?: {
 }): Promise<SceneSummary[]>;
 declare function pullScene(client: EasyTwinClient, id: string, options?: {
     exampleFile?: string;
+    cwd?: string;
 }): Promise<SceneDetail>;
 declare function saveSceneJson(scene: SceneDetail, out: string): Promise<string>;
 /** 场景对象树节点:由场景 JSON 的 objs/hierarchy 按 parentObjId 组装(侧边栏场景结构树等复用)。 */
@@ -218,6 +251,37 @@ interface SceneTreeNode {
  * scene 可为已解析对象或 JSON 字符串。
  */
 declare function parseSceneStructure(scene: unknown): SceneTreeNode[];
+/** inspect 默认最多打印的节点数(D30)。 */
+declare const INSPECT_NODE_LIMIT = 200;
+interface InspectSceneFilter {
+    name?: string;
+    type?: string;
+}
+interface InspectSceneOptions extends InspectSceneFilter {
+    cwd: string;
+    id: string;
+    limit?: number;
+}
+interface InspectSceneResult {
+    file: string;
+    roots: SceneTreeNode[];
+    text: string;
+    printed: number;
+    total: number;
+    truncated: boolean;
+}
+declare function nodeMatchesInspect(node: SceneTreeNode, filter: InspectSceneFilter): boolean;
+/** 无过滤原样返回;有过滤时保留匹配节点与祖先,丢掉未匹配旁支与未匹配子孙。 */
+declare function filterSceneTree(roots: SceneTreeNode[], filter?: InspectSceneFilter): SceneTreeNode[];
+declare function countSceneTreeNodes(roots: SceneTreeNode[]): number;
+declare function formatSceneTree(roots: SceneTreeNode[], limit?: number): {
+    text: string;
+    printed: number;
+    total: number;
+    truncated: boolean;
+};
+/** 只读本地 `.easytwin/scenes/<id>.scene.json`,打印对象树。不拉网、不读凭据。 */
+declare function inspectScene(options: InspectSceneOptions): Promise<InspectSceneResult>;
 
 interface UploadProgress {
     phase: "collect" | "upload";
@@ -460,8 +524,15 @@ interface SyncOptions {
     version?: string;
     /** skills 源目录;缺省按 devkit 包内 skills/ 解析(CLI)。插件 bundle 场景显式传入插件内目录。 */
     sourceDir?: string;
-    /** runtime index.d.ts 源文件;缺省按包内 src/lib 或 dist/runtime-types 解析。插件必须显式传入。 */
+    /**
+     * 覆盖 runtime 类型源文件(跳过 OSS)。单测 / 离线用;
+     * 缺省按配置 env 从官方 OSS 拉 `easytwin/system/libs/runtime/types/index.d.ts`(D31)。
+     */
     typesSourceFile?: string;
+    /** 拉取类型用的 fetch;缺省 global fetch。单测注入。 */
+    fetch?: typeof fetch;
+    /** 解析类型 URL 时覆盖 process.env。 */
+    env?: NodeJS.ProcessEnv;
 }
 declare const CODEX_MARKER_BEGIN = "<!-- EASYTWIN-SKILLS:BEGIN -->";
 declare const CODEX_MARKER_END = "<!-- EASYTWIN-SKILLS:END -->";
@@ -473,11 +544,14 @@ declare const TSCONFIG_PATHS_HINT = "\u5DF2\u6709 tsconfig.json,\u672A\u6539\u52
 declare const APPS_TYPES_FILE = "apps.d.ts";
 declare const APPS_DTS = "import type { RuntimeEngine, RuntimeScene, SceneManager } from \"@easytwin/runtime\";\n\nexport type TwinAppContext = {\n    app: {\n        id: string;\n        mode: \"preview\" | \"publish\";\n    };\n    engine: RuntimeEngine;\n    container: HTMLElement;\n    runtimeScene: RuntimeScene | null;\n    scene: RuntimeScene[\"sceneObject\"] | null;\n    camera: RuntimeScene[\"camera\"][\"main\"] | null;\n    sceneManager: {\n        currentSceneId: string;\n        runtime: SceneManager | null;\n        loadScene(sceneId: string): Promise<void>;\n    };\n    logger: {\n        log(...args: unknown[]): void;\n        info(...args: unknown[]): void;\n        warn(...args: unknown[]): void;\n        error(...args: unknown[]): void;\n    };\n    assets: {\n        text(path: string): Promise<string>;\n        json<T = unknown>(path: string): Promise<T>;\n    };\n    cleanup(fn: () => void | Promise<void>): void;\n    sceneCleanup(fn: () => void | Promise<void>): void;\n};\n\nexport declare abstract class TwinApp {\n    init?(ctx: TwinAppContext): void | Promise<void>;\n    onUpdate?(ctx: TwinAppContext, delta: number, elapsed: number): void;\n    onBeforeSceneUnload?(ctx: TwinAppContext): void | Promise<void>;\n    onSceneLoaded?(ctx: TwinAppContext): void | Promise<void>;\n    onDispose?(ctx: TwinAppContext): void | Promise<void>;\n    onError?(ctx: TwinAppContext, error: unknown): boolean | void;\n}\n\nexport declare function defineApp<T>(app: T): T;\n";
 declare function buildRuntimeTypesContent(sourceDts: string): string;
+declare class SkillsError extends Error {
+    constructor(message: string);
+}
 declare function normalizeTargets(target?: SyncTargetArg | SyncTarget[]): SyncTarget[];
 /** skills 源目录默认解析:CLI 下为 devkit 包内 skills/。插件 bundle 到 CJS 后 import.meta.url 为空,
  * 必须通过 SyncOptions.sourceDir / detectSkillsStatus 的 sourceDir 显式传入(见 esbuild.config.mjs 注释)。 */
 declare function resolveSkillsSourceDir(): string;
-/** runtime 类型声明源:开发态 src/lib/index.d.ts,发布态 dist/runtime-types/index.d.ts。 */
+/** 开发态/单测:包内 src/lib/index.d.ts。正式 sync 默认走 OSS,不经过此函数。 */
 declare function resolveRuntimeTypesSourceFile(): string;
 declare function readDevkitVersion(skillsDir?: string): Promise<string>;
 interface TypesSyncSummary {
@@ -680,4 +754,4 @@ declare function buildPreviewHtml(options: {
     tests?: WorkspaceTestCase[];
 }): string;
 
-export { APPS_DTS, APPS_MODULE, APPS_TYPES_FILE, APP_ID_HEADER, AUTH_HEADER, BundleError, type BundleResult, type BundleUserCodeOptions, type BundleWorkspaceModuleOptions, CODEX_MARKER_BEGIN, CODEX_MARKER_END, CONFIG_FILE_NAME, type CollectedFile, ConfigError, type ConfigScene, DEFAULT_BASE_URL, DEFAULT_BUNDLE_OUT, DEFAULT_ENTRY_PATH, DEFAULT_MAIN_TS, DEFAULT_OSS_URL, EASYTWIN_TYPES_DIR, ENDPOINTS, EXAMPLE_SCENE_FILE, EasyTwinApiError, EasyTwinClient, type EasyTwinConfig, type EasyTwinEnv, GITIGNORE_ENTRY, GITIGNORE_FILE_NAME, type GitignoreResult, type InitResult, LOCAL_LOAD_SCENE_ERROR, type LinkedScene, META_FILE_NAME, MINIMAL_TSCONFIG, MISSING_TICK_ERROR, MOCK_APP_ID, MOCK_APP_SECRET, MOCK_SCENE_NAME, PORTABLE_RUNTIME_EXPORTS, type PortableRuntimeExport, type PreviewHostKind, RUNTIME_MODULE, type RequestOptions, type ResolvedConfig, SKILL_NAMES, type SceneDetail, type SceneSummary, type SceneTreeNode, type SkillsStatus, type SkillsTargetStatus, type SyncAction, type SyncEntrySummary, type SyncOptions, type SyncSkillsResult, type SyncSummary, type SyncTarget, type SyncTargetArg, TEST_BASE_URL, TSCONFIG_PATHS_HINT, TwinApp, type TwinAppContext, type TwinAppEngine, TwinAppPreviewHost, type TwinAppPreviewHostOptions, type TwinAppRuntimeModule, type TwinAppRuntimeScene, type TwinAppSceneManager, type TwinAppTickListener, type TypesSyncSummary, USER_ENTRY, type UploadCreate, type UploadDelete, type UploadOptions, type UploadProgress, type UploadResult, type UploadUpdate, WORKSPACE_CODE_EXTENSIONS, WORKSPACE_IGNORED_DIRS, WORKSPACE_IGNORED_FILES, type WorkspaceChangeKind, type WorkspaceCodeConfig, type WorkspaceCodeFile, type WorkspaceFileChange, type WorkspacePullApplyResult, type WorkspacePullOptions, type WorkspacePullPlan, type WorkspacePullResult, type WorkspaceTestCase, type WorkspaceUploadPlan, appendGitignore, applyWorkspacePull, assertUploadable, buildMultipartBody, buildPreviewHtml, buildRuntimeTypesContent, buildStatusHtml, buildWorkspacePushBody, bundleUserCode, bundleWorkspaceModule, bundleWorkspaceTestFile, collectFiles, configFilePath, createAppInstance, defaultPullIgnore, defaultWorkspaceIgnore, defineApp, deriveExampleSceneId, detectSkillsStatus, directoryDepth, escapeHtml, escapeJsonForScript, exampleSceneSummary, extractInlineSourceMap, extractSceneArray, formatUploadResult, formatWorkspacePullPlan, formatWorkspacePullResult, initConfig, isIgnoredWorkspacePath, isMockCredentials, isSafeRelPath, isWorkspaceCodeFile, isWorkspaceSpecFile, listScenes, listWorkspaceTests, loadConfig, loadExampleScene, normalizeLinkedScenes, normalizePath, normalizeSceneList, normalizeTargets, normalizeWorkspaceConfig, normalizeWorkspaceFiles, parseConfig, parseExportedTestFunctions, parseSceneStructure, planWorkspacePull, planWorkspaceUpload, portableRuntimeWarning, pullScene, pullWorkspace, readConfigFile, readDevkitVersion, remapErrorStack, resolveConfig, resolveExampleScenePath, resolveRuntimeTypesSourceFile, resolveSkillsSourceDir, resolveSnapshotUrl, resolveWorkspaceAssetPath, saveSceneJson, syncSkills, toConfigScenes, typesMissingHint, uploadDirectory, validateConfigShape, workspacePullHasConflicts, workspacePullPendingWrites, workspaceTestId, writeConfigFile, writeConfigScenes };
+export { APPS_DTS, APPS_MODULE, APPS_TYPES_FILE, APP_ID_HEADER, AUTH_HEADER, BundleError, type BundleResult, type BundleUserCodeOptions, type BundleWorkspaceModuleOptions, CODEX_MARKER_BEGIN, CODEX_MARKER_END, CONFIG_FILE_NAME, type CollectedFile, ConfigError, type ConfigScene, DEFAULT_BASE_URL, DEFAULT_BUNDLE_OUT, DEFAULT_ENTRY_PATH, DEFAULT_MAIN_TS, DEFAULT_OSS_URL, EASYTWIN_DIR, EASYTWIN_SCENES_DIRNAME, EASYTWIN_TYPES_DIR, ENDPOINTS, EXAMPLE_SCENE_FILE, EasyTwinApiError, EasyTwinClient, type EasyTwinConfig, type EasyTwinEnv, GITIGNORE_ENTRIES, GITIGNORE_ENTRY, GITIGNORE_FILE_NAME, type GitignoreResult, INSPECT_NODE_LIMIT, type InitResult, type InspectSceneFilter, type InspectSceneOptions, type InspectSceneResult, LOCAL_LOAD_SCENE_ERROR, type LinkedScene, META_FILE_NAME, MINIMAL_TSCONFIG, MISSING_TICK_ERROR, MOCK_APP_ID, MOCK_APP_SECRET, MOCK_SCENE_NAME, PORTABLE_RUNTIME_EXPORTS, PROD_OSS_URL, type PortableRuntimeExport, type PreviewHostKind, RUNTIME_MODULE, RUNTIME_TYPES_RELPATH, type RequestOptions, type ResolvedConfig, SKILL_NAMES, type SceneDetail, type SceneSummary, type SceneTreeNode, SkillsError, type SkillsStatus, type SkillsTargetStatus, type SyncAction, type SyncEntrySummary, type SyncOptions, type SyncSkillsResult, type SyncSummary, type SyncTarget, type SyncTargetArg, TEST_BASE_URL, TEST_OSS_URL, TSCONFIG_PATHS_HINT, TwinApp, type TwinAppContext, type TwinAppEngine, TwinAppPreviewHost, type TwinAppPreviewHostOptions, type TwinAppRuntimeModule, type TwinAppRuntimeScene, type TwinAppSceneManager, type TwinAppTickListener, type TypesSyncSummary, USER_ENTRY, type UploadCreate, type UploadDelete, type UploadOptions, type UploadProgress, type UploadResult, type UploadUpdate, WORKSPACE_CODE_EXTENSIONS, WORKSPACE_IGNORED_DIRS, WORKSPACE_IGNORED_FILES, type WorkspaceChangeKind, type WorkspaceCodeConfig, type WorkspaceCodeFile, type WorkspaceFileChange, type WorkspacePullApplyResult, type WorkspacePullOptions, type WorkspacePullPlan, type WorkspacePullResult, type WorkspaceTestCase, type WorkspaceUploadPlan, appendGitignore, applyWorkspacePull, assertUploadable, buildMultipartBody, buildPreviewHtml, buildRuntimeTypesContent, buildStatusHtml, buildWorkspacePushBody, bundleUserCode, bundleWorkspaceModule, bundleWorkspaceTestFile, collectFiles, configFilePath, countSceneTreeNodes, createAppInstance, defaultPullIgnore, defaultSceneOutPath, defaultWorkspaceIgnore, defineApp, deriveExampleSceneId, detectSkillsStatus, directoryDepth, escapeHtml, escapeJsonForScript, exampleSceneSummary, extractInlineSourceMap, extractSceneArray, filterSceneTree, formatSceneTree, formatUploadResult, formatWorkspacePullPlan, formatWorkspacePullResult, initConfig, inspectScene, isIgnoredWorkspacePath, isMockCredentials, isSafeRelPath, isWorkspaceCodeFile, isWorkspaceSpecFile, joinOssPath, legacyConfigFilePath, listScenes, listWorkspaceTests, loadConfig, loadExampleScene, nodeMatchesInspect, normalizeLinkedScenes, normalizePath, normalizeSceneList, normalizeTargets, normalizeWorkspaceConfig, normalizeWorkspaceFiles, parseConfig, parseExportedTestFunctions, parseSceneStructure, planWorkspacePull, planWorkspaceUpload, portableRuntimeWarning, pullScene, pullWorkspace, readConfigFile, readDevkitVersion, remapErrorStack, resolveConfig, resolveExampleScenePath, resolveRuntimeTypesSourceFile, resolveRuntimeTypesUrl, resolveRuntimeTypesUrlForCwd, resolveSkillsSourceDir, resolveSnapshotUrl, resolveWorkspaceAssetPath, saveSceneJson, syncSkills, toConfigScenes, typesMissingHint, uploadDirectory, validateConfigShape, workspacePullHasConflicts, workspacePullPendingWrites, workspaceTestId, writeConfigFile, writeConfigScenes };

package/dist/index.js

@@ -1,10 +1,15 @@
 // src/config.ts
 import { promises as fs } from "fs";
 import path from "path";
+var EASYTWIN_DIR = ".easytwin";
 var CONFIG_FILE_NAME = "easytwin.config.json";
+var EASYTWIN_SCENES_DIRNAME = "scenes";
 var DEFAULT_BASE_URL = "http://saas-twin.k8s.dtstack.cn/";
 var TEST_BASE_URL = "http://172.16.125.3:10100/";
-var DEFAULT_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+var TEST_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+var PROD_OSS_URL = "https://dt-easyv-prod.oss-cn-hangzhou.aliyuncs.com/";
+var DEFAULT_OSS_URL = TEST_OSS_URL;
+var RUNTIME_TYPES_RELPATH = "easytwin/system/libs/runtime/types/index.d.ts";
 var MOCK_APP_ID = "test";
 var MOCK_APP_SECRET = "test";
 function isMockCredentials(appId, appSecret) {
@@ -17,8 +22,31 @@ var ConfigError = class extends Error {
   }
 };
 function configFilePath(cwd) {
+  return path.join(cwd, EASYTWIN_DIR, CONFIG_FILE_NAME);
+}
+function joinOssPath(ossUrl, relPath) {
+  return `${ossUrl.replace(/\/+$/, "")}/${relPath.replace(/^\/+/, "")}`;
+}
+function resolveRuntimeTypesUrl(options = {}) {
+  const root = options.ossUrl ?? (options.env === "prod" ? PROD_OSS_URL : TEST_OSS_URL);
+  return joinOssPath(root, RUNTIME_TYPES_RELPATH);
+}
+async function resolveRuntimeTypesUrlForCwd(cwd, env = process.env) {
+  let file;
+  try {
+    file = await readConfigFile(cwd);
+  } catch {
+  }
+  const easyEnv = env.EASYTWIN_ENV === "test" || env.EASYTWIN_ENV === "prod" ? env.EASYTWIN_ENV : file?.env;
+  const ossUrl = env.EASYTWIN_OSS_URL ?? file?.ossUrl;
+  return resolveRuntimeTypesUrl({ env: easyEnv, ossUrl });
+}
+function legacyConfigFilePath(cwd) {
   return path.join(cwd, CONFIG_FILE_NAME);
 }
+function defaultSceneOutPath(cwd, id) {
+  return path.join(cwd, EASYTWIN_DIR, EASYTWIN_SCENES_DIRNAME, `${path.basename(id)}.scene.json`);
+}
 function parseConfig(raw) {
   let parsed;
   try {
@@ -86,15 +114,39 @@ function parseConfigScenes(value) {
     return scene;
   });
 }
-async function readConfigFile(cwd) {
-  const file = configFilePath(cwd);
-  let raw;
+async function tryReadText(file) {
+  try {
+    return await fs.readFile(file, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+async function removeLegacyConfigFile(cwd) {
   try {
-    raw = await fs.readFile(file, "utf8");
+    await fs.unlink(legacyConfigFilePath(cwd));
   } catch {
-    throw new ConfigError(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6 ${file},\u8BF7\u5148\u8FD0\u884C \`easytwin init\``);
   }
-  return parseConfig(raw);
+}
+async function migrateLegacyConfigIfPresent(cwd) {
+  const raw = await tryReadText(legacyConfigFilePath(cwd));
+  if (raw === void 0) return void 0;
+  const config = parseConfig(raw);
+  await writeConfigFile(cwd, config);
+  await removeLegacyConfigFile(cwd);
+  await appendGitignore(cwd);
+  return config;
+}
+async function readConfigFile(cwd) {
+  const file = configFilePath(cwd);
+  const raw = await tryReadText(file);
+  if (raw !== void 0) {
+    const config = parseConfig(raw);
+    await removeLegacyConfigFile(cwd);
+    return config;
+  }
+  const migrated = await migrateLegacyConfigIfPresent(cwd);
+  if (migrated) return migrated;
+  throw new ConfigError(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6 ${file},\u8BF7\u5148\u8FD0\u884C \`easytwin init\``);
 }
 function resolveConfig(file, env = process.env) {
   const appId = env.EASYTWIN_APP_ID ?? file.appId;
@@ -118,12 +170,14 @@ async function writeConfigFile(cwd, config) {
   if (config.baseUrl) body.baseUrl = config.baseUrl;
   if (config.ossUrl) body.ossUrl = config.ossUrl;
   if (config.scenes !== void 0) body.scenes = config.scenes;
-  await fs.mkdir(cwd, { recursive: true });
+  await fs.mkdir(path.dirname(file), { recursive: true });
   await fs.writeFile(file, JSON.stringify(body, null, 2) + "\n", "utf8");
+  await removeLegacyConfigFile(cwd);
   return file;
 }
 var GITIGNORE_FILE_NAME = ".gitignore";
-var GITIGNORE_ENTRY = "easytwin.config.json";
+var GITIGNORE_ENTRY = ".easytwin/easytwin.config.json";
+var GITIGNORE_ENTRIES = [GITIGNORE_ENTRY, ".easytwin/scenes/"];
 async function appendGitignore(cwd) {
   const file = path.join(cwd, GITIGNORE_FILE_NAME);
   let content = "";
@@ -134,9 +188,10 @@ async function appendGitignore(cwd) {
     created = true;
   }
   const lines = content.split(/\r?\n/);
-  if (lines.includes(GITIGNORE_ENTRY)) return { created, added: false };
+  const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) return { created, added: false };
   const prefix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
-  await fs.writeFile(file, content + prefix + GITIGNORE_ENTRY + "\n", "utf8");
+  await fs.writeFile(file, content + prefix + missing.join("\n") + "\n", "utf8");
   return { created, added: true };
 }
 async function initConfig(input, cwd) {
@@ -417,25 +472,29 @@ async function listScenes(client, options = {}) {
   return scenes;
 }
 async function pullScene(client, id, options = {}) {
+  let scene;
   if (client.mock) {
-    const payload2 = await loadExampleScene(options.exampleFile);
-    const sceneId = deriveExampleSceneId(payload2);
+    const payload = await loadExampleScene(options.exampleFile);
+    const sceneId = deriveExampleSceneId(payload);
     if (sceneId !== id) {
       throw new Error(`\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F:\u793A\u4F8B\u573A\u666F id \u4E3A ${sceneId},\u6536\u5230 ${id}(\u672C\u5730\u4EC5\u63D0\u4F9B ${EXAMPLE_SCENE_FILE} \u8FD9\u4E00\u4E2A\u573A\u666F)`);
     }
-    return { id: sceneId, name: MOCK_SCENE_NAME, payload: payload2 };
-  }
-  const data = await fetchLinkedScenes(client);
-  const scenes = normalizeLinkedScenes(data);
-  const hit = scenes.find((s) => s.sceneKey === id || s.id === id);
-  if (!hit) {
-    const available = scenes.map((s) => s.sceneKey).filter((k) => k.length > 0);
-    throw new Error(
-      available.length > 0 ? `\u672A\u627E\u5230\u573A\u666F ${id}(\u53EF\u7528 Scene Key:${available.join(", ")})` : `\u672A\u627E\u5230\u573A\u666F ${id}`
-    );
+    scene = { id: sceneId, name: MOCK_SCENE_NAME, payload };
+  } else {
+    const data = await fetchLinkedScenes(client);
+    const scenes = normalizeLinkedScenes(data);
+    const hit = scenes.find((s) => s.sceneKey === id || s.id === id);
+    if (!hit) {
+      const available = scenes.map((s) => s.sceneKey).filter((k) => k.length > 0);
+      throw new Error(
+        available.length > 0 ? `\u672A\u627E\u5230\u573A\u666F ${id}(\u53EF\u7528 Scene Key:${available.join(", ")})` : `\u672A\u627E\u5230\u573A\u666F ${id}`
+      );
+    }
+    const payload = await fetchSnapshotJson(client.ossUrl, hit.snapshotUrl);
+    scene = { id: hit.sceneKey, name: hit.name, payload };
   }
-  const payload = await fetchSnapshotJson(client.ossUrl, hit.snapshotUrl);
-  return { id: hit.sceneKey, name: hit.name, payload };
+  if (options.cwd) await saveSceneJson(scene, defaultSceneOutPath(options.cwd, scene.id));
+  return scene;
 }
 async function saveSceneJson(scene, out) {
   await fs2.mkdir(path2.dirname(out), { recursive: true });
@@ -492,6 +551,86 @@ function parseSceneStructure(scene) {
   };
   return order.filter((id) => !isChild.has(id)).map((id) => build2(id, /* @__PURE__ */ new Set()));
 }
+var INSPECT_NODE_LIMIT = 200;
+var INSPECT_INDENT = "  ";
+function nodeMatchesInspect(node, filter) {
+  if (filter.name !== void 0 && filter.name.length > 0) {
+    if (!node.name.toLowerCase().includes(filter.name.toLowerCase())) return false;
+  }
+  if (filter.type !== void 0 && filter.type.length > 0) {
+    if (node.type !== filter.type) return false;
+  }
+  return true;
+}
+function filterSceneTree(roots, filter = {}) {
+  const hasName = filter.name !== void 0 && filter.name.length > 0;
+  const hasType = filter.type !== void 0 && filter.type.length > 0;
+  if (!hasName && !hasType) return roots;
+  const walk = (node) => {
+    const children = [];
+    for (const child of node.children) {
+      const kept = walk(child);
+      if (kept) children.push(kept);
+    }
+    if (nodeMatchesInspect(node, filter) || children.length > 0) {
+      return { ...node, children };
+    }
+    return void 0;
+  };
+  return roots.flatMap((node) => {
+    const kept = walk(node);
+    return kept ? [kept] : [];
+  });
+}
+function countSceneTreeNodes(roots) {
+  let n = 0;
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      n += 1;
+      walk(node.children);
+    }
+  };
+  walk(roots);
+  return n;
+}
+function formatSceneTree(roots, limit = INSPECT_NODE_LIMIT) {
+  const total = countSceneTreeNodes(roots);
+  if (total === 0) {
+    return { text: "(\u65E0\u5BF9\u8C61\u7ED3\u6784)\n", printed: 0, total: 0, truncated: false };
+  }
+  const lines = [];
+  let printed = 0;
+  const walk = (nodes, depth) => {
+    for (const node of nodes) {
+      if (printed >= limit) return;
+      lines.push(`${INSPECT_INDENT.repeat(depth)}${node.id}	${node.name}	${node.type ?? ""}`);
+      printed += 1;
+      walk(node.children, depth + 1);
+    }
+  };
+  walk(roots, 0);
+  const truncated = printed < total;
+  if (truncated) lines.push(`\u5176\u4F59 ${total - printed} \u4E2A,\u8BF7\u52A0 --name/--type`);
+  return { text: `${lines.join("\n")}
+`, printed, total, truncated };
+}
+async function inspectScene(options) {
+  const file = defaultSceneOutPath(options.cwd, options.id);
+  let raw;
+  try {
+    raw = await fs2.readFile(file, "utf8");
+  } catch {
+    throw new Error(`\u672A\u627E\u5230\u672C\u5730\u573A\u666F\u6587\u4EF6 ${file},\u8BF7\u5148\u8FD0\u884C \`easytwin scene pull ${options.id}\``);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new Error(`\u573A\u666F\u6587\u4EF6\u4E0D\u662F\u5408\u6CD5 JSON:${file}`);
+  }
+  const roots = filterSceneTree(parseSceneStructure(payload), { name: options.name, type: options.type });
+  return { file, roots, ...formatSceneTree(roots, options.limit ?? INSPECT_NODE_LIMIT) };
+}
 
 // src/upload.ts
 import { promises as fs3 } from "fs";
@@ -794,7 +933,9 @@ function defaultPullIgnore(relPath) {
 function isSafeRelPath(relPath) {
   const n = normalizePath(relPath);
   if (!n) return false;
-  if (n.toLowerCase() === "easytwin.config.json") return false;
+  const lower = n.toLowerCase();
+  if (lower === "easytwin.config.json" || lower.endsWith("/easytwin.config.json")) return false;
+  if (lower.split("/")[0] === ".easytwin") return false;
   const base = n.split("/").pop() ?? "";
   if (/^tsconfig(\..+)?\.json$/i.test(base)) return false;
   if (path5.isAbsolute(n) || path5.win32.isAbsolute(n.replace(/\//g, "\\"))) return false;
@@ -1493,6 +1634,12 @@ function buildRuntimeTypesContent(sourceDts) {
   return `${sourceDts.replace(/\s+$/, "")}
 `;
 }
+var SkillsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SkillsError";
+  }
+};
 function normalizeTargets(target = "all") {
   if (target === "all") return ["cursor", "claude", "codex", "qoder"];
   if (Array.isArray(target)) return [...new Set(target)];
@@ -1507,14 +1654,30 @@ function resolveSkillsSourceDir() {
 }
 function resolveRuntimeTypesSourceFile() {
   if (typeof import.meta.url !== "string" || import.meta.url.length === 0) {
-    throw new Error("\u65E0\u6CD5\u5B9A\u4F4D runtime \u7C7B\u578B:\u63D2\u4EF6(bundle/CJS)\u573A\u666F\u5FC5\u987B\u663E\u5F0F\u4F20\u5165 typesSourceFile");
+    throw new Error("\u65E0\u6CD5\u5B9A\u4F4D runtime \u7C7B\u578B:\u63D2\u4EF6(bundle/CJS)\u573A\u666F\u8BF7\u8D70 OSS \u62C9\u53D6,\u4E0D\u8981\u89E3\u6790\u5305\u5185 d.ts");
   }
   const here = path8.dirname(fileURLToPath2(import.meta.url));
-  const fromDist = path8.join(here, "runtime-types", "index.d.ts");
   const fromSrc = path8.resolve(here, "lib", "index.d.ts");
-  if (existsSync(fromDist)) return fromDist;
   if (existsSync(fromSrc)) return fromSrc;
-  throw new Error(`\u65E0\u6CD5\u5B9A\u4F4D runtime \u7C7B\u578B\u58F0\u660E,\u5DF2\u5C1D\u8BD5:${fromDist}, ${fromSrc}`);
+  throw new Error(`\u65E0\u6CD5\u5B9A\u4F4D runtime \u7C7B\u578B\u58F0\u660E,\u5DF2\u5C1D\u8BD5:${fromSrc}`);
+}
+async function fetchRuntimeTypesDts(url, fetchImpl) {
+  let res;
+  try {
+    res = await fetchImpl(url);
+  } catch (err) {
+    throw new SkillsError(
+      `\u62C9\u53D6 @easytwin/runtime \u7C7B\u578B\u5931\u8D25:${url} (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  if (!res.ok) {
+    throw new SkillsError(`\u62C9\u53D6 @easytwin/runtime \u7C7B\u578B\u5931\u8D25:HTTP ${res.status} ${url}`);
+  }
+  const text = await res.text();
+  if (text.trim().length === 0) {
+    throw new SkillsError(`\u62C9\u53D6 @easytwin/runtime \u7C7B\u578B\u5931\u8D25:\u7A7A\u54CD\u5E94 ${url}`);
+  }
+  return text;
 }
 async function readJson(file) {
   return JSON.parse(await fs7.readFile(file, "utf8"));
@@ -1601,8 +1764,8 @@ function buildCodexSegment(version) {
     `EasyTwin \u5F00\u53D1\u6280\u80FD(\u7531 @easytwin/devkit v${version} \u540C\u6B65):`,
     "",
     "- `easytwin-develop`:\u5DE5\u4F5C\u6D41\u603B\u7EB2,\u5F00\u59CB EasyTwin \u5F00\u53D1\u524D\u5FC5\u8BFB\u3002",
-    "- `easytwin-bootstrap`:\u521D\u59CB\u5316\u5E94\u7528\u7EA7\u51ED\u8BC1(easytwin.config.json)\u3002",
-    "- `easytwin-scene`:\u5217\u51FA\u573A\u666F\u3001\u62C9\u53D6\u573A\u666F JSON\u3002",
+    "- `easytwin-bootstrap`:\u521D\u59CB\u5316\u5E94\u7528\u7EA7\u51ED\u8BC1(`.easytwin/easytwin.config.json`)\u3002",
+    "- `easytwin-scene`:\u5217\u51FA\u573A\u666F\u3001\u62C9\u53D6\u573A\u666F JSON\u3001inspect \u672C\u5730\u5BF9\u8C61\u6811\u3002",
     "- `easytwin-render`:\u7528 twin runtime \u5F00\u53D1\u6E32\u67D3\u529F\u80FD(\u4E3B\u529B)\u3002",
     "- `easytwin-core`:\u5F15\u64CE\u5185\u6838 API(RuntimeEngine/\u57FA\u7C7B/Time/\u76F8\u673A/\u7269\u7406)\u3002",
     "- `easytwin-upload`:\u62C9\u53D6/\u4E0A\u4F20\u5DE5\u4F5C\u533A\u4EE3\u7801(\u8FDC\u7AEF\u4E3A\u7A7A\u5199\u9ED8\u8BA4\u5165\u53E3;\u4E0A\u4F20\u5168\u91CF\u8986\u76D6\u4E0D\u53EF\u9006)\u3002",
@@ -1641,11 +1804,11 @@ async function syncToCodex(sourceRoot, cwd, version) {
   }
   return { target: "codex", entries: [], codex: { name: "AGENTS.md", action } };
 }
-async function syncRuntimeTypes(cwd, typesSourceFile) {
+async function syncRuntimeTypes(cwd, sourceDts) {
   const destDir = path8.join(cwd, ".easytwin", "types");
   const destFile = path8.join(destDir, "index.d.ts");
   const appsFile = path8.join(destDir, APPS_TYPES_FILE);
-  const content = buildRuntimeTypesContent(await fs7.readFile(typesSourceFile, "utf8"));
+  const content = buildRuntimeTypesContent(sourceDts);
   let runtimeCurrent = "";
   let appsCurrent = "";
   let runtimeExists = true;
@@ -1695,7 +1858,11 @@ async function syncSkills(options) {
     else if (target === "qoder") summaries.push(await syncToDir("qoder", sourceRoot, path8.join(options.cwd, ".qoder", "skills"), version));
     else summaries.push(await syncToCodex(sourceRoot, options.cwd, version));
   }
-  const types = await syncRuntimeTypes(options.cwd, options.typesSourceFile ?? resolveRuntimeTypesSourceFile());
+  const typesSource = options.typesSourceFile ? await fs7.readFile(options.typesSourceFile, "utf8") : await fetchRuntimeTypesDts(
+    await resolveRuntimeTypesUrlForCwd(options.cwd, options.env ?? process.env),
+    options.fetch ?? fetch
+  );
+  const types = await syncRuntimeTypes(options.cwd, typesSource);
   return { summaries, types };
 }
 async function detectSkillsStatus(cwd, sourceDir) {
@@ -2679,13 +2846,17 @@ export {
   DEFAULT_ENTRY_PATH,
   DEFAULT_MAIN_TS,
   DEFAULT_OSS_URL,
+  EASYTWIN_DIR,
+  EASYTWIN_SCENES_DIRNAME,
   EASYTWIN_TYPES_DIR,
   ENDPOINTS,
   EXAMPLE_SCENE_FILE,
   EasyTwinApiError,
   EasyTwinClient,
+  GITIGNORE_ENTRIES,
   GITIGNORE_ENTRY,
   GITIGNORE_FILE_NAME,
+  INSPECT_NODE_LIMIT,
   LOCAL_LOAD_SCENE_ERROR,
   META_FILE_NAME,
   MINIMAL_TSCONFIG,
@@ -2694,9 +2865,13 @@ export {
   MOCK_APP_SECRET,
   MOCK_SCENE_NAME,
   PORTABLE_RUNTIME_EXPORTS,
+  PROD_OSS_URL,
   RUNTIME_MODULE,
+  RUNTIME_TYPES_RELPATH,
   SKILL_NAMES,
+  SkillsError,
   TEST_BASE_URL,
+  TEST_OSS_URL,
   TSCONFIG_PATHS_HINT,
   TwinApp,
   TwinAppPreviewHost,
@@ -2717,8 +2892,10 @@ export {
   bundleWorkspaceTestFile,
   collectFiles,
   configFilePath,
+  countSceneTreeNodes,
   createAppInstance,
   defaultPullIgnore,
+  defaultSceneOutPath,
   defaultWorkspaceIgnore,
   defineApp,
   deriveExampleSceneId,
@@ -2729,19 +2906,25 @@ export {
   exampleSceneSummary,
   extractInlineSourceMap,
   extractSceneArray,
+  filterSceneTree,
+  formatSceneTree,
   formatUploadResult,
   formatWorkspacePullPlan,
   formatWorkspacePullResult,
   initConfig,
+  inspectScene,
   isIgnoredWorkspacePath,
   isMockCredentials,
   isSafeRelPath,
   isWorkspaceCodeFile,
   isWorkspaceSpecFile,
+  joinOssPath,
+  legacyConfigFilePath,
   listScenes,
   listWorkspaceTests,
   loadConfig,
   loadExampleScene,
+  nodeMatchesInspect,
   normalizeLinkedScenes,
   normalizePath,
   normalizeSceneList,
@@ -2762,6 +2945,8 @@ export {
   resolveConfig,
   resolveExampleScenePath,
   resolveRuntimeTypesSourceFile,
+  resolveRuntimeTypesUrl,
+  resolveRuntimeTypesUrlForCwd,
   resolveSkillsSourceDir,
   resolveSnapshotUrl,
   resolveWorkspaceAssetPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easytwin/devkit",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "EasyTwin DevKit 核心:lib(函数库)+ bin(easytwin 命令)双导出",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-runtime-types.mjs && node scripts/bundle-runtime.mjs",
+    "build": "tsup && node scripts/bundle-runtime.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }