@easytwin/devkit 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,22 +1,75 @@
 /** 配置文件名(项目根)。 */
 declare const CONFIG_FILE_NAME = "easytwin.config.json";
 /**
- * 官方缺省域名。
- * TODO(外部输入): 域名值待定。该常量是全仓唯一收口点,只允许写在这里。
+ * 官方缺省域名(正式环境)。该常量是全仓唯一收口点,只允许写在这里。
  */
-declare const DEFAULT_BASE_URL = "https://api.easytwin.example.com";
+declare const DEFAULT_BASE_URL = "http://saas-twin.k8s.dtstack.cn/";
+/** 官方测试环境域名。 */
+declare const TEST_BASE_URL = "http://172.16.125.3:10100/";
+/**
+ * 当前测试 OP 网关缺省头(与编辑器 curl 一致)。配置/环境变量可覆盖。
+ * 免网关接口到位后删除(D13)。
+ */
+declare const TEST_OP_ACCOUNT_ID = "25";
+declare const TEST_OP_USER_ID = "25";
+declare const TEST_SPACE_ID = "54";
+/**
+ * 官方 OSS(twin runtime baseOSSUrl)。系统资产由此拼出:
+ * `{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 DEFAULT_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+/** 服务环境,决定缺省 baseUrl。 */
+type EasyTwinEnv = "prod" | "test";
+/** 本地测试模式哨兵凭据:appId 与 appSecret 均为该值时,场景/上传走本地 mock,不发网络请求(见 AGENTS.md 4.4)。 */
+declare const MOCK_APP_ID = "test";
+declare const MOCK_APP_SECRET = "test";
+/** appId/appSecret 是否命中本地测试模式哨兵值。 */
+declare function isMockCredentials(appId: string, appSecret: string): boolean;
 /** 磁盘上的配置结构(4.3 配置契约)。 */
 interface EasyTwinConfig {
     appId: string;
     appSecret: string;
+    /** 服务环境,缺省 prod。 */
+    env?: EasyTwinEnv;
     baseUrl?: string;
+    /** twin runtime 资产根(baseOSSUrl);缺省官方 OSS,可覆盖为 CDN/自建存储。 */
+    ossUrl?: string;
+    /** 过渡期 OP 网关头;免网关接口到位后删除(D13)。 */
+    opAccountId?: string;
+    opUserId?: string;
+    spaceId?: string;
+    /**
+     * 关联场景摘要,由 scene list / 场景树刷新写入(D17)。
+     * 不含场景 JSON 本体;下次 list 全量覆盖。
+     */
+    scenes?: ConfigScene[];
+}
+/** 写入 easytwin.config.json 的关联场景摘要(对应 listScenes 的可序列化子集)。 */
+interface ConfigScene {
+    /** Scene Key,与 `easytwin scene pull <id>` 对应。 */
+    id: string;
+    name: string;
+    linkedSceneId?: string;
+    snapshotUrl?: string;
+    defaultLoading?: boolean;
 }
 /** 解析 + 环境变量覆盖后的最终配置。 */
 interface ResolvedConfig {
     appId: string;
     appSecret: string;
     baseUrl: string;
+    /** twin runtime baseOSSUrl(系统库 draco/basis/webp、custom script 与相对路径资产);缺省官方 OSS。 */
+    ossUrl: string;
+    /** 本地测试模式:appId/appSecret 均为 "test" 时启用,scene/upload/pull 走本地 mock 不发请求。 */
+    mock: boolean;
     source: "file" | "env";
+    /** 过渡期 OP 网关头;env=test 时缺省 25/25/54。免网关接口到位后删除(D13)。 */
+    opAccountId?: string;
+    opUserId?: string;
+    spaceId?: string;
 }
 declare class ConfigError extends Error {
     constructor(message: string);
@@ -43,19 +96,29 @@ interface InitResult {
 }
 /** init 的 lib 实现:生成配置文件 + 追加 gitignore(与插件配置向导共用同一实现)。 */
 declare function initConfig(input: EasyTwinConfig, cwd: string): Promise<InitResult>;
+/** 把场景摘要写入配置 `scenes`(全量覆盖该数组,保留其余字段)。 */
+declare function writeConfigScenes(cwd: string, scenes: ConfigScene[]): Promise<void>;
 
 /**
- * TODO(swagger): 认证头名称、endpoint 路径、请求/响应结构一律以内部 swagger 为准。
- * 以下常量为占位约定;swagger 到位后在 client.ts / scene.ts / upload.ts 集中修订,不扩散到其它文件。
+ * 认证与路径以内部 swagger 为准(标签:SDK 应用场景 / SDK 应用代码 / SDK Runtime)。
+ * 全仓唯一认证头注入点:`x-app-secret` = App Secret。
+ * 过渡期另注入 OP 网关头 op-account-id / op-user-id / space-id(D13,免网关接口到位后删除)。
+ * 场景/代码路径参数名为 applicationId;DevKit 传入配置里的 App ID。
  */
-declare const AUTH_HEADER = "Authorization";
-declare const BEARER_PREFIX = "Bearer";
-/** TODO(swagger): 应用标识头名待定(上传目标空间由 App ID 决定)。 */
-declare const APP_ID_HEADER = "X-Easytwin-App-Id";
+declare const AUTH_HEADER = "x-app-secret";
+/** 过渡期 OP 网关头;免网关接口到位后删除(D13)。 */
+declare const OP_ACCOUNT_ID_HEADER = "op-account-id";
+declare const OP_USER_ID_HEADER = "op-user-id";
+declare const SPACE_ID_HEADER = "space-id";
 declare const ENDPOINTS: {
-    readonly scenes: "/api/scenes";
-    readonly scene: (id: string) => string;
-    readonly upload: "/api/upload";
+    /** GET 已关联场景列表。 */
+    readonly linkedScenes: (applicationId: string) => string;
+    /** GET 工作区全部代码文件。 */
+    readonly workspaceCode: (applicationId: string) => string;
+    /** GET 工作区文件约束。 */
+    readonly workspaceConfig: (applicationId: string) => string;
+    /** POST 新建 / PATCH 批量更新 / DELETE 批量删除。 */
+    readonly workspaceCodeFiles: (applicationId: string) => string;
 };
 declare class EasyTwinApiError extends Error {
     readonly status: number;
@@ -63,15 +126,23 @@ declare class EasyTwinApiError extends Error {
     constructor(status: number, message: string, body?: unknown);
 }
 interface RequestOptions {
-    method?: "GET" | "POST" | "PUT" | "DELETE";
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     headers?: Record<string, string>;
     body?: string | null;
     signal?: AbortSignal;
 }
 declare class EasyTwinClient {
     readonly baseUrl: string;
-    private readonly appId;
+    /** twin runtime / 场景快照资产根(baseOSSUrl)。 */
+    readonly ossUrl: string;
+    /** 接入凭证 App ID;同时作为场景/代码 API 的 applicationId 路径参数。 */
+    readonly appId: string;
+    /** 本地测试模式:true 时 scene/upload/pull 走本地 mock,不发网络请求(见 config.ts)。 */
+    readonly mock: boolean;
     private readonly appSecret;
+    private readonly opAccountId?;
+    private readonly opUserId?;
+    private readonly spaceId?;
     constructor(config: ResolvedConfig);
     /** 全仓唯一认证头注入点。 */
     private authHeaders;
@@ -89,21 +160,86 @@ declare class EasyTwinClient {
     private handleStatus;
 }
 
+/** swagger `SdkApplicationLinkedSceneVo`。 */
+interface LinkedScene {
+    /** 关联记录 ID。 */
+    id: string;
+    /** SDK 业务标识 Scene Key(list/pull 的主键)。 */
+    sceneKey: string;
+    name: string;
+    defaultLoading: boolean;
+    sourceSceneId: string;
+    sourceProjectId: string;
+    sourceSceneName: string;
+    sourceProjectName: string;
+    sourceLost: boolean;
+    /** 场景快照 JSON 的 OSS 相对路径(或绝对 URL)。 */
+    snapshotUrl: string;
+    snapshotUpdatedAt: string;
+}
 interface SceneSummary {
+    /** Scene Key,与 `easytwin scene pull <id>` 对应。 */
     id: string;
     name: string;
+    linkedSceneId?: string;
+    snapshotUrl?: string;
+    defaultLoading?: boolean;
 }
 interface SceneDetail {
     id: string;
     name: string;
-    /** 服务端返回的场景 JSON 原始内容。 */
+    /**
+     * 场景快照 JSON 原始内容。
+     * 结构以 easytwin-runtime 的 SceneJson 为准(见 skills/easytwin-scene)。
+     */
     payload: unknown;
 }
+/** 从信封/Runtime VO/数组中取出场景列表。 */
+declare function extractSceneArray(data: unknown): unknown[];
+/** 把 swagger 关联场景 / Runtime scenes 规范为 LinkedScene[]。 */
+declare function normalizeLinkedScenes(data: unknown): LinkedScene[];
 declare function normalizeSceneList(data: unknown): SceneSummary[];
-declare function normalizeSceneDetail(data: unknown): SceneDetail;
-declare function listScenes(client: EasyTwinClient): Promise<SceneSummary[]>;
-declare function pullScene(client: EasyTwinClient, id: string): Promise<SceneDetail>;
+/** 把 list 结果收成配置里的 scenes 摘要(省略空可选字段)。 */
+declare function toConfigScenes(scenes: SceneSummary[]): ConfigScene[];
+/** 拼接场景快照地址:绝对 URL 原样使用,否则挂到 ossUrl 下。 */
+declare function resolveSnapshotUrl(ossUrl: string, snapshotUrl: string): string;
+/** devkit 包内本地测试场景文件名(4.4 本地测试模式)。 */
+declare const EXAMPLE_SCENE_FILE = "scene.example.json";
+/** 本地测试模式下场景列表展示的名字(示例文件本身不含场景级 name)。 */
+declare const MOCK_SCENE_NAME = "\u672C\u5730\u793A\u4F8B\u573A\u666F";
+/**
+ * 示例场景文件默认路径:devkit 包内 scene.example.json(CLI/源码)。
+ * 插件 bundle 到 CJS 后 import.meta.url 为空,必须经 listScenes/pullScene 的 exampleFile 显式传入(与 skills 的 sourceDir 同理)。
+ */
+declare function resolveExampleScenePath(): string;
+/** 读取并解析本地示例场景(本地测试模式专用,不发网络请求)。 */
+declare function loadExampleScene(exampleFile?: string): Promise<unknown>;
+/** 从示例场景提取场景 id:取 objs[].sceneId 首个非空值;无则回退 "local"。 */
+declare function deriveExampleSceneId(payload: unknown): string;
+/** 本地测试模式下的场景列表(单条)。 */
+declare function exampleSceneSummary(exampleFile?: string): Promise<SceneSummary>;
+declare function listScenes(client: EasyTwinClient, options?: {
+    exampleFile?: string;
+    cwd?: string;
+}): Promise<SceneSummary[]>;
+declare function pullScene(client: EasyTwinClient, id: string, options?: {
+    exampleFile?: string;
+}): Promise<SceneDetail>;
 declare function saveSceneJson(scene: SceneDetail, out: string): Promise<string>;
+/** 场景对象树节点:由场景 JSON 的 objs/hierarchy 按 parentObjId 组装(侧边栏场景结构树等复用)。 */
+interface SceneTreeNode {
+    id: string;
+    name: string;
+    type?: string;
+    children: SceneTreeNode[];
+}
+/**
+ * 解析场景对象层级树:优先读 `objs`(含 type),缺失或为空时回退 `hierarchy`。
+ * - `parentObjId` 为空 / 指向不存在的 id / 自引用时,该节点视为根;
+ * - 节点顺序保持场景数组顺序;非法输入或无可解析结构时返回空数组。
+ * scene 可为已解析对象或 JSON 字符串。
+ */
+declare function parseSceneStructure(scene: unknown): SceneTreeNode[];
 
 interface UploadProgress {
     phase: "collect" | "upload";
@@ -121,22 +257,98 @@ interface UploadOptions {
 interface UploadResult {
     fileCount: number;
     byteCount: number;
+    /** 本地测试模式(dry-run)时置 true:未真正上传。 */
+    mock?: boolean;
 }
 interface CollectedFile {
     relPath: string;
     absPath: string;
     size: number;
 }
+/** swagger `SdkApplicationWorkspaceCodeConfigVo`。 */
+interface WorkspaceCodeConfig {
+    allowedFileExtensions: string[];
+    maxCodeFiles: number;
+    maxCodeDirectoryDepth: number;
+}
+/** swagger `SdkApplicationWorkspaceCodeFileVo`。 */
+interface WorkspaceCodeFile {
+    id: string;
+    filePath: string;
+    content: string;
+}
 /** 递归收集目录下全部文件(默认跳过 .git),按相对路径升序排列,保证顺序稳定。 */
 declare function collectFiles(dir: string, ignore?: (relPath: string) => boolean): Promise<CollectedFile[]>;
 declare function buildMultipartBody(boundary: string, fields: Record<string, string>, file: {
     name: string;
     content: Buffer;
 }): Buffer;
-/** 全量覆盖上传目录:逐文件 multipart 上传,带进度回调(供插件进度条)。 */
+declare function normalizePath(relPath: string): string;
+declare function normalizeWorkspaceConfig(data: unknown): WorkspaceCodeConfig;
+declare function normalizeWorkspaceFiles(data: unknown): WorkspaceCodeFile[];
+/** 目录深度:根文件为 0,`src/a.ts` 为 1,`src/utils/a.ts` 为 2。 */
+declare function directoryDepth(relPath: string): number;
+declare function assertUploadable(files: CollectedFile[], config: WorkspaceCodeConfig): void;
+/**
+ * 全量覆盖上传目录:对照工作区代码文件(GET/POST/PATCH/DELETE)使远端与本地一致。
+ * 本地测试模式(mock)时退化为 dry-run。
+ */
 declare function uploadDirectory(client: EasyTwinClient, dir: string, options?: UploadOptions): Promise<UploadResult>;
 
-type SyncTarget = "cursor" | "claude" | "codex";
+declare const DEFAULT_ENTRY_PATH = "src/main.ts";
+/** 与 easytwin-render 可上传子集示例对齐的默认 TwinApp 子类入口。 */
+declare const DEFAULT_MAIN_TS = "import { TwinApp, type TwinAppContext } from \"@easytwin/apps\";\n\nexport default class App extends TwinApp {\n  async init(ctx: TwinAppContext) {\n    // engine / container \u5DF2\u6709;scene / camera \u4E3A null\n    void ctx;\n  }\n\n  async onSceneLoaded(ctx: TwinAppContext) {\n    // \u573A\u666F\u5B57\u6BB5\u6709\u503C;\u5728\u6B64\u52A0\u7269\u4F53 / \u7ED1\u4E8B\u4EF6,\u5E76\u7528 ctx.sceneCleanup \u5BF9\u79F0\u62C6\u9664\n    void ctx;\n  }\n\n  onUpdate(ctx: TwinAppContext, delta: number, elapsed: number) {\n    void ctx;\n    void delta;\n    void elapsed;\n  }\n\n  onDispose(ctx: TwinAppContext) {\n    void ctx;\n  }\n}\n";
+type WorkspaceChangeKind = "identical" | "remote-only" | "local-only" | "modified" | "seed";
+interface WorkspaceFileChange {
+    path: string;
+    kind: WorkspaceChangeKind;
+    localContent?: string;
+    remoteContent?: string;
+}
+interface WorkspacePullPlan {
+    remoteEmpty: boolean;
+    seededDefaults: boolean;
+    mock?: boolean;
+    skippedRemotePaths: string[];
+    changes: WorkspaceFileChange[];
+}
+interface WorkspacePullOptions {
+    /** 用远端内容覆盖内容冲突的本地文件;仅本地文件仍不删除。 */
+    force?: boolean;
+    /** 只算计划,不写盘。 */
+    dryRun?: boolean;
+    ignore?: (relPath: string) => boolean;
+}
+interface WorkspacePullResult {
+    plan: WorkspacePullPlan;
+    written: string[];
+    skippedConflicts: string[];
+    dryRun?: boolean;
+    mock?: boolean;
+}
+declare function defaultPullIgnore(relPath: string): boolean;
+/** 拒绝逃逸、空路径与凭据文件,避免远端路径写到工作区外。 */
+declare function isSafeRelPath(relPath: string): boolean;
+/**
+ * 对照远端工作区代码与本地目录,算出 diff 计划。
+ * mock 或远端无有效文件时,本地缺省入口视为 seed。
+ */
+declare function planWorkspacePull(client: EasyTwinClient, dir: string, options?: Pick<WorkspacePullOptions, "ignore">): Promise<WorkspacePullPlan>;
+interface WorkspacePullApplyResult {
+    written: string[];
+    skippedConflicts: string[];
+}
+/** 按计划写盘:seed 与 remote-only 始终写入;modified 仅 force 时覆盖;不删 local-only。 */
+declare function applyWorkspacePull(dir: string, plan: WorkspacePullPlan, options?: {
+    force?: boolean;
+}): Promise<WorkspacePullApplyResult>;
+declare function pullWorkspace(client: EasyTwinClient, dir: string, options?: WorkspacePullOptions): Promise<WorkspacePullResult>;
+declare function formatWorkspacePullPlan(plan: WorkspacePullPlan): string;
+declare function formatWorkspacePullResult(result: WorkspacePullResult): string;
+declare function workspacePullHasConflicts(plan: WorkspacePullPlan): boolean;
+declare function workspacePullPendingWrites(plan: WorkspacePullPlan, force?: boolean): string[];
+
+type SyncTarget = "cursor" | "claude" | "codex" | "qoder";
 type SyncTargetArg = SyncTarget | "all";
 /** 六件套清单(5.1),顺序即输出顺序。 */
 declare const SKILL_NAMES: readonly ["easytwin-render", "easytwin-core", "easytwin-develop", "easytwin-bootstrap", "easytwin-scene", "easytwin-upload"];
@@ -156,16 +368,36 @@ interface SyncOptions {
     version?: string;
     /** skills 源目录;缺省按 devkit 包内 skills/ 解析(CLI)。插件 bundle 场景显式传入插件内目录。 */
     sourceDir?: string;
+    /** runtime index.d.ts 源文件;缺省按包内 src/lib 或 dist/runtime-types 解析。插件必须显式传入。 */
+    typesSourceFile?: string;
 }
 declare const CODEX_MARKER_BEGIN = "<!-- EASYTWIN-SKILLS:BEGIN -->";
 declare const CODEX_MARKER_END = "<!-- EASYTWIN-SKILLS:END -->";
 declare const META_FILE_NAME = ".easytwin-meta.json";
+/** 用户项目内 runtime 类型落地目录(posix)。 */
+declare const EASYTWIN_TYPES_DIR = ".easytwin/types";
+declare const MINIMAL_TSCONFIG: string;
+declare const TSCONFIG_PATHS_HINT = "\u5DF2\u6709 tsconfig.json,\u672A\u6539\u52A8\u3002\u8BF7\u5728 compilerOptions \u4E2D\u52A0\u5165:\n  \"skipLibCheck\": true,\n  \"paths\": {\n    \"@easytwin/runtime\": [\".easytwin/types\"],\n    \"@easytwin/apps\": [\".easytwin/types/apps\"]\n  }";
+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 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。 */
+declare function resolveRuntimeTypesSourceFile(): string;
 declare function readDevkitVersion(skillsDir?: string): Promise<string>;
-declare function syncSkills(options: SyncOptions): Promise<SyncSummary[]>;
+interface TypesSyncSummary {
+    action: SyncAction;
+    tsconfig: "created" | "unchanged" | "manual-paths";
+    pathsHint?: string;
+}
+interface SyncSkillsResult {
+    summaries: SyncSummary[];
+    types: TypesSyncSummary;
+}
+declare function syncSkills(options: SyncOptions): Promise<SyncSkillsResult>;
 interface SkillsTargetStatus {
     target: SyncTarget;
     synced: boolean;
@@ -174,8 +406,181 @@ interface SkillsTargetStatus {
 interface SkillsStatus {
     cwd: string;
     targets: SkillsTargetStatus[];
+    typesSynced: boolean;
 }
 /** 供插件"缺失/过期时提示一次"使用:检测各目标当前同步状态。 */
 declare function detectSkillsStatus(cwd: string, sourceDir?: string): Promise<SkillsStatus>;
 
-export { APP_ID_HEADER, AUTH_HEADER, BEARER_PREFIX, CODEX_MARKER_BEGIN, CODEX_MARKER_END, CONFIG_FILE_NAME, type CollectedFile, ConfigError, DEFAULT_BASE_URL, ENDPOINTS, EasyTwinApiError, EasyTwinClient, type EasyTwinConfig, GITIGNORE_ENTRY, GITIGNORE_FILE_NAME, type GitignoreResult, type InitResult, META_FILE_NAME, type RequestOptions, type ResolvedConfig, SKILL_NAMES, type SceneDetail, type SceneSummary, type SkillsStatus, type SkillsTargetStatus, type SyncAction, type SyncEntrySummary, type SyncOptions, type SyncSummary, type SyncTarget, type SyncTargetArg, type UploadOptions, type UploadProgress, type UploadResult, appendGitignore, buildMultipartBody, collectFiles, configFilePath, detectSkillsStatus, initConfig, listScenes, loadConfig, normalizeSceneDetail, normalizeSceneList, normalizeTargets, parseConfig, pullScene, readConfigFile, readDevkitVersion, resolveConfig, resolveSkillsSourceDir, saveSceneJson, syncSkills, uploadDirectory, validateConfigShape, writeConfigFile };
+/** 用户代码固定入口(相对工作区根)。 */
+declare const USER_ENTRY = "src/main.ts";
+/** CLI 缺省输出路径(相对工作区根)。 */
+declare const DEFAULT_BUNDLE_OUT = "dist/main.js";
+/** 白名单允许的裸模块。 */
+declare const RUNTIME_MODULE = "@easytwin/runtime";
+declare const APPS_MODULE = "@easytwin/apps";
+declare class BundleError extends Error {
+    constructor(message: string);
+}
+interface BundleUserCodeOptions {
+    cwd: string;
+    /** 缺省不落盘,只返回产物字符串(插件内存编译);CLI 传入绝对/相对路径。 */
+    outFile?: string;
+}
+interface BundleResult {
+    code: string;
+    warnings: string[];
+}
+/** 打包工作区 src/main.ts。产物标准 ESM + inline sourcemap;仅允许 @easytwin/runtime 与 @easytwin/apps。 */
+declare function bundleUserCode(options: BundleUserCodeOptions): Promise<BundleResult>;
+/** 若工作区尚未同步 runtime 类型,返回提示文案;已同步则返回 undefined。 */
+declare function typesMissingHint(cwd: string): Promise<string | undefined>;
+interface SourceMapJson {
+    sources?: string[];
+    mappings?: string;
+}
+declare function extractInlineSourceMap(code: string): SourceMapJson | undefined;
+/**
+ * 把 bundled JS 的 stack(blob: 行号)映射回 TS 源码行号。
+ * 映射失败时原样返回。
+ */
+declare function remapErrorStack(stack: string, bundledCode: string): string;
+
+/** 在线 TwinApp 编译 stub 露出的 `@easytwin/runtime` 导出名。本地整包 external,超出此集合只 warning。 */
+declare const PORTABLE_RUNTIME_EXPORTS: readonly ["THREE", "RuntimeEngine", "SceneManager", "LoadSceneMode", "convertObjToComponentJson"];
+type PortableRuntimeExport = (typeof PORTABLE_RUNTIME_EXPORTS)[number];
+type TwinAppEngine = {
+    container: HTMLElement;
+    time: {
+        deltaTime: number;
+        elapsedTime: number;
+    };
+    mainScene?: TwinAppRuntimeScene | null;
+    getManager(ctor: unknown): TwinAppSceneManager | null;
+    destroy(): void;
+};
+type TwinAppRuntimeScene = {
+    sceneObject?: {
+        add(object: unknown): void;
+        remove(object: unknown): void;
+    } | null;
+    camera?: {
+        main?: unknown;
+    } | null;
+};
+type TwinAppSceneManager = {
+    loadScene(...args: unknown[]): Promise<unknown>;
+};
+type TwinAppContext = {
+    app: {
+        id: string;
+        mode: "preview" | "publish";
+    };
+    engine: TwinAppEngine;
+    container: HTMLElement;
+    runtimeScene: TwinAppRuntimeScene | null;
+    scene: TwinAppRuntimeScene["sceneObject"] | null;
+    camera: unknown | null;
+    sceneManager: {
+        currentSceneId: string;
+        runtime: TwinAppSceneManager | null;
+        loadScene(sceneId: string): Promise<void>;
+    };
+    logger: {
+        log(...args: unknown[]): void;
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+        error(...args: unknown[]): void;
+    };
+    assets: {
+        text(path: string): Promise<string>;
+        json<T = unknown>(path: string): Promise<T>;
+    };
+    cleanup(fn: () => void | Promise<void>): void;
+    sceneCleanup(fn: () => void | Promise<void>): void;
+};
+declare abstract class TwinApp {
+    init?(ctx: TwinAppContext): void | Promise<void>;
+    onUpdate?(ctx: TwinAppContext, delta: number, elapsed: number): void;
+    onBeforeSceneUnload?(ctx: TwinAppContext): void | Promise<void>;
+    onSceneLoaded?(ctx: TwinAppContext): void | Promise<void>;
+    onDispose?(ctx: TwinAppContext): void | Promise<void>;
+    onError?(ctx: TwinAppContext, error: unknown): boolean | void;
+}
+declare function defineApp<T>(app: T): T;
+/** 把用户模块 default 导出收成 TwinApp 实例。函数式 `main` 不认。 */
+declare function createAppInstance(appExport: unknown): TwinApp;
+declare function portableRuntimeWarning(names: Iterable<string>): string | undefined;
+
+/**
+ * 把 ctx.assets 的相对路径落到工作区磁盘。规范化后必须仍在 cwd 内。
+ */
+declare function resolveWorkspaceAssetPath(cwd: string, relPath: string): string;
+
+declare const LOCAL_LOAD_SCENE_ERROR = "\u672C\u5730\u9884\u89C8\u5355\u573A\u666F,\u4E0D\u80FD\u8C03\u7528 sceneManager.loadScene";
+declare const MISSING_TICK_ERROR = "\u5F53\u524D runtime \u4E0D\u652F\u6301\u5F15\u64CE\u65F6\u949F(\u7F3A\u5C11 registerEngineTickListener)\u3002\u65E0\u6CD5\u8FD0\u884C onUpdate\u3002";
+type TwinAppTickListener = (engine: TwinAppEngine) => void;
+type TwinAppRuntimeModule = {
+    RuntimeEngine: {
+        create(config: Record<string, unknown>): Promise<TwinAppEngine>;
+    };
+    SceneManager: unknown;
+    LoadSceneMode: {
+        Single: unknown;
+    };
+    RuntimeSceneMode: {
+        Publish: unknown;
+    };
+    registerEngineTickListener?: (engine: TwinAppEngine, listener: TwinAppTickListener) => void;
+    unregisterEngineTickListener?: (engine: TwinAppEngine, listener: TwinAppTickListener) => void;
+};
+type TwinAppPreviewHostOptions = {
+    runtime: TwinAppRuntimeModule;
+    containerId: string;
+    ossUrl: string;
+    appId: string;
+    sceneId: string;
+    sceneJson: unknown;
+    customComponentDeps: Record<string, unknown>;
+    loadScene(engine: TwinAppEngine, sceneJson: unknown): Promise<void>;
+    readAsset(path: string): Promise<string>;
+    importUserModule?(code: string): Promise<{
+        default: unknown;
+    }>;
+    log?: (line: string) => void;
+};
+declare class TwinAppPreviewHost {
+    private readonly options;
+    private app;
+    private engine;
+    private disposed;
+    /** 用户应用已经成功 onSceneLoaded。 */
+    private scenePresented;
+    private tickAttached;
+    private sceneLoadTask;
+    private ctx;
+    private cleanups;
+    private sceneCleanups;
+    private warnedAsyncUpdate;
+    private userBlobUrl;
+    private currentSceneId;
+    private readonly onEngineTick;
+    constructor(options: TwinAppPreviewHostOptions);
+    getEngine(): TwinAppEngine | null;
+    boot(): Promise<void>;
+    run(code: string): Promise<void>;
+    dispose(): Promise<void>;
+    private assertTickApi;
+    private importUser;
+    private loadCurrentScene;
+    private handleTick;
+    private handleUpdateError;
+    private failRun;
+    private attachTick;
+    private detachTick;
+    private teardownApp;
+    private unloadUserScene;
+    private runHooks;
+    private getContext;
+}
+
+export { APPS_DTS, APPS_MODULE, APPS_TYPES_FILE, AUTH_HEADER, BundleError, type BundleResult, type BundleUserCodeOptions, 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, OP_ACCOUNT_ID_HEADER, OP_USER_ID_HEADER, PORTABLE_RUNTIME_EXPORTS, type PortableRuntimeExport, RUNTIME_MODULE, type RequestOptions, type ResolvedConfig, SKILL_NAMES, SPACE_ID_HEADER, 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, TEST_OP_ACCOUNT_ID, TEST_OP_USER_ID, TEST_SPACE_ID, TSCONFIG_PATHS_HINT, TwinApp, type TwinAppContext, type TwinAppEngine, TwinAppPreviewHost, type TwinAppPreviewHostOptions, type TwinAppRuntimeModule, type TwinAppRuntimeScene, type TwinAppSceneManager, type TwinAppTickListener, type TypesSyncSummary, USER_ENTRY, type UploadOptions, type UploadProgress, type UploadResult, type WorkspaceChangeKind, type WorkspaceCodeConfig, type WorkspaceCodeFile, type WorkspaceFileChange, type WorkspacePullApplyResult, type WorkspacePullOptions, type WorkspacePullPlan, type WorkspacePullResult, appendGitignore, applyWorkspacePull, assertUploadable, buildMultipartBody, buildRuntimeTypesContent, bundleUserCode, collectFiles, configFilePath, createAppInstance, defaultPullIgnore, defineApp, deriveExampleSceneId, detectSkillsStatus, directoryDepth, exampleSceneSummary, extractInlineSourceMap, extractSceneArray, formatWorkspacePullPlan, formatWorkspacePullResult, initConfig, isMockCredentials, isSafeRelPath, listScenes, loadConfig, loadExampleScene, normalizeLinkedScenes, normalizePath, normalizeSceneList, normalizeTargets, normalizeWorkspaceConfig, normalizeWorkspaceFiles, parseConfig, parseSceneStructure, planWorkspacePull, portableRuntimeWarning, pullScene, pullWorkspace, readConfigFile, readDevkitVersion, remapErrorStack, resolveConfig, resolveExampleScenePath, resolveRuntimeTypesSourceFile, resolveSkillsSourceDir, resolveSnapshotUrl, resolveWorkspaceAssetPath, saveSceneJson, syncSkills, toConfigScenes, typesMissingHint, uploadDirectory, validateConfigShape, workspacePullHasConflicts, workspacePullPendingWrites, writeConfigFile, writeConfigScenes };