@easytwin/devkit 0.1.2 → 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,20 +11,19 @@ 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`、
+ * 官方测试 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)。 */
@@ -37,10 +40,6 @@ interface EasyTwinConfig {
     baseUrl?: string;
     /** twin runtime 资产根(baseOSSUrl);缺省官方 OSS,可覆盖为 CDN/自建存储。 */
     ossUrl?: string;
-    /** 过渡期 OP 网关头;免网关接口到位后删除(D13)。 */
-    opAccountId?: string;
-    opUserId?: string;
-    spaceId?: string;
     /**
      * 关联场景摘要,由 scene list / 场景树刷新写入(D17)。
      * 不含场景 JSON 本体;下次 list 全量覆盖。
@@ -66,15 +65,30 @@ interface ResolvedConfig {
     /** 本地测试模式: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);
 }
 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>;
@@ -83,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;
@@ -100,25 +117,21 @@ declare function initConfig(input: EasyTwinConfig, cwd: string): Promise<InitRes
 declare function writeConfigScenes(cwd: string, scenes: ConfigScene[]): Promise<void>;
 
 /**
- * 认证与路径以内部 swagger 为准(标签:SDK 应用场景 / SDK 应用代码 / SDK Runtime)。
- * 全仓唯一认证头注入点:`x-app-secret` = App Secret。
- * 过渡期另注入 OP 网关头 op-account-id / op-user-id / space-id(D13,免网关接口到位后删除)。
- * 场景/代码路径参数名为 applicationId;DevKit 传入配置里的 App ID。
+ * 认证与路径以内部 swagger 为准(标签:SDK 应用场景 / 分享相关 / SDK 应用代码)。
+ * 全仓唯一认证头注入点:`x-app-id` = App ID,`x-app-secret` = App Secret(D20)。
+ * share 代码与场景列表接口无路径参数(D21 / D22);上传不请求仍走 OP 网关的 workspace-config(D24)。
  */
+declare const APP_ID_HEADER = "x-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: {
-    /** GET 已关联场景列表。 */
-    readonly linkedScenes: (applicationId: string) => string;
-    /** GET 工作区全部代码文件。 */
-    readonly workspaceCode: (applicationId: string) => string;
-    /** GET 工作区文件约束。 */
+    /** POST 已关联场景列表(分享路径,空 body)。 */
+    readonly linkedScenes: () => string;
+    /** POST 拉取工作区全部代码文件(分享路径,空 body)。 */
+    readonly workspaceCodePull: () => string;
+    /** POST 一次推送 create/update/delete(分享路径)。 */
+    readonly workspaceCodePush: () => string;
+    /** GET 工作区文件约束(仍带 applicationId,走 OP 网关;上传不调用,拉取失败则降级)。 */
     readonly workspaceConfig: (applicationId: string) => string;
-    /** POST 新建 / PATCH 批量更新 / DELETE 批量删除。 */
-    readonly workspaceCodeFiles: (applicationId: string) => string;
 };
 declare class EasyTwinApiError extends Error {
     readonly status: number;
@@ -135,14 +148,11 @@ declare class EasyTwinClient {
     readonly baseUrl: string;
     /** twin runtime / 场景快照资产根(baseOSSUrl)。 */
     readonly ossUrl: string;
-    /** 接入凭证 App ID;同时作为场景/代码 API 的 applicationId 路径参数。 */
+    /** 接入凭证 App ID;写入 `x-app-id`,workspace-config 路径仍可用。 */
     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;
@@ -224,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 组装(侧边栏场景结构树等复用)。 */
@@ -240,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";
@@ -251,20 +293,58 @@ interface UploadProgress {
 }
 interface UploadOptions {
     onProgress?: (progress: UploadProgress) => void;
-    /** 自定义忽略规则,默认只跳过 .git。 */
+    /** 额外忽略规则;默认已跳过插件产物与相关文件(D23)。 */
     ignore?: (relPath: string) => boolean;
 }
+interface CollectedFile {
+    relPath: string;
+    absPath: string;
+    size: number;
+}
 interface UploadResult {
     fileCount: number;
     byteCount: number;
+    created: number;
+    updated: number;
+    deleted: number;
+    unchanged: number;
     /** 本地测试模式(dry-run)时置 true:未真正上传。 */
     mock?: boolean;
 }
-interface CollectedFile {
-    relPath: string;
-    absPath: string;
-    size: number;
+interface UploadCreate {
+    file: CollectedFile;
+    content: string;
+}
+interface UploadUpdate {
+    file: CollectedFile;
+    id: string;
+    content: string;
+}
+interface UploadDelete {
+    id: string;
+    filePath: string;
 }
+/** 对照远端文件,本地区分新增 / 更新 / 删除(D21,一次 push)。 */
+interface WorkspaceUploadPlan {
+    creates: UploadCreate[];
+    updates: UploadUpdate[];
+    deletes: UploadDelete[];
+    unchanged: CollectedFile[];
+}
+/** 上传/拉取共同跳过:插件产物、agent 目录、构建产物与凭据。 */
+declare const WORKSPACE_IGNORED_DIRS: Set<string>;
+declare const WORKSPACE_IGNORED_FILES: Set<string>;
+/** 与 push 服务端一致的工作区代码扩展名(D25)。 */
+declare const WORKSPACE_CODE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".json"];
+/** 工作区本地预览测试文件:不参与 pull/upload(D27)。 */
+declare function isWorkspaceSpecFile(relPath: string): boolean;
+/**
+ * 插件产物、凭据、构建目录与场景快照。
+ * 不含 `*.spec.ts`(预览测试扫描需要读这些文件)。
+ */
+declare function isIgnoredWorkspacePath(relPath: string): boolean;
+/** 跳过插件产物/凭据/场景快照,以及本地预览测试文件 `*.spec.ts`(D23 / D26 / D27)。 */
+declare function defaultWorkspaceIgnore(relPath: string): boolean;
 /** swagger `SdkApplicationWorkspaceCodeConfigVo`。 */
 interface WorkspaceCodeConfig {
     allowedFileExtensions: string[];
@@ -286,12 +366,25 @@ declare function buildMultipartBody(boundary: string, fields: Record<string, str
 declare function normalizePath(relPath: string): string;
 declare function normalizeWorkspaceConfig(data: unknown): WorkspaceCodeConfig;
 declare function normalizeWorkspaceFiles(data: unknown): WorkspaceCodeFile[];
+/** 是否为可同步的工作区代码文件(`.ts` / `.tsx` / `.js` / `.json`)。 */
+declare function isWorkspaceCodeFile(relPath: string): boolean;
 /** 目录深度:根文件为 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。
+ * 对照远端工作区文件,把本地文件分成新增 / 更新 / 删除 / 未变。
+ * 不做本地清单:每次上传以本次 GET 的远端列表为准。
+ */
+declare function planWorkspaceUpload(local: {
+    file: CollectedFile;
+    content: string;
+}[], remote: WorkspaceCodeFile[]): WorkspaceUploadPlan;
+declare function formatUploadResult(result: UploadResult): string;
+/** swagger `PushSdkApplicationWorkspaceCodeDto`:字段均可选,有变更才带上。 */
+declare function buildWorkspacePushBody(plan: WorkspaceUploadPlan): Record<string, unknown> | null;
+/**
+ * 全量对齐上传目录:对照远端工作区,本地 diff 后一次 push(create/update/delete)。
+ * 不请求仍走 OP 网关的 workspace-config(D24);只收集 `.ts`/`.tsx`/`.js`/`.json`(D25)。本地测试模式(mock)时退化为 dry-run。
  */
 declare function uploadDirectory(client: EasyTwinClient, dir: string, options?: UploadOptions): Promise<UploadResult>;
 
@@ -348,10 +441,73 @@ declare function formatWorkspacePullResult(result: WorkspacePullResult): string;
 declare function workspacePullHasConflicts(plan: WorkspacePullPlan): boolean;
 declare function workspacePullPendingWrites(plan: WorkspacePullPlan, force?: boolean): string[];
 
+/** 用户代码固定入口(相对工作区根)。 */
+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 BundleWorkspaceModuleOptions extends BundleUserCodeOptions {
+    /** 相对 cwd 的入口文件(posix 或当前平台分隔符均可)。 */
+    entry: string;
+    /** 入口缺失时的报错文案;缺省按路径拼一条。 */
+    missingEntryMessage?: string;
+}
+interface BundleResult {
+    code: string;
+    warnings: string[];
+}
+/** 打包工作区任意入口。产物标准 ESM + inline sourcemap;仅允许 @easytwin/runtime 与 @easytwin/apps。 */
+declare function bundleWorkspaceModule(options: BundleWorkspaceModuleOptions): Promise<BundleResult>;
+/** 打包工作区 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;
+
+interface WorkspaceTestCase {
+    /** `${file}:${name}`,文件内唯一。 */
+    id: string;
+    /** 相对工作区根的 posix 路径。 */
+    file: string;
+    name: string;
+    /** 除 ctx 外还有参数时,预览显示输入框。 */
+    hasInput: boolean;
+    /** 第二个参数名,作输入框占位。 */
+    inputName?: string;
+}
+/** 从 spec 源码解析命名导出的函数(跳过 default / type / class / 再导出)。 */
+declare function parseExportedTestFunctions(source: string): Omit<WorkspaceTestCase, "id" | "file">[];
+declare function workspaceTestId(file: string, name: string): string;
+/** 扫描工作区 `*.spec.ts` 的命名导出函数。跳过插件产物目录,不跳过 spec 本身。 */
+declare function listWorkspaceTests(cwd: string): Promise<WorkspaceTestCase[]>;
+declare function bundleWorkspaceTestFile(options: {
+    cwd: string;
+    file: string;
+}): Promise<BundleResult>;
+
 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"];
+/** 七件套清单(5.1),顺序即输出顺序。 */
+declare const SKILL_NAMES: readonly ["easytwin-render", "easytwin-core", "easytwin-develop", "easytwin-bootstrap", "easytwin-scene", "easytwin-upload", "easytwin-test"];
 type SyncAction = "created" | "updated" | "unchanged";
 interface SyncEntrySummary {
     name: string;
@@ -368,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 -->";
@@ -381,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 {
@@ -411,40 +577,6 @@ interface SkillsStatus {
 /** 供插件"缺失/过期时提示一次"使用:检测各目标当前同步状态。 */
 declare function detectSkillsStatus(cwd: string, sourceDir?: string): Promise<SkillsStatus>;
 
-/** 用户代码固定入口(相对工作区根)。 */
-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];
@@ -566,6 +698,9 @@ declare class TwinAppPreviewHost {
     private readonly onEngineTick;
     constructor(options: TwinAppPreviewHostOptions);
     getEngine(): TwinAppEngine | null;
+    /** 给 spec 调用:场景字段取当前引擎主场景(不要求已 Run TwinApp)。 */
+    getTestContext(): TwinAppContext;
+    invokeTest(fn: (ctx: TwinAppContext, input?: string) => unknown, input?: string): Promise<unknown>;
     boot(): Promise<void>;
     run(code: string): Promise<void>;
     dispose(): Promise<void>;
@@ -583,4 +718,40 @@ declare class TwinAppPreviewHost {
     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 };
+type PreviewHostKind = "vscode" | "http";
+/**
+ * 纯函数:构造场景预览页 HTML(插件 webview 与 CLI localhost HTTP 共用,D28)。
+ * 单栏三维场景页:module script 动态 import twin runtime,
+ * 用场景数据经 convertObjToComponentJson + RuntimeEngine.create + loadScene 真实渲染。
+ * baseOSSUrl 必须是 ossUrl(缺省官方 OSS),不是 API baseUrl。
+ * host=vscode 且页面为 HTTPS 时,HTTP 资源经扩展宿主代理,规避 mixed content。
+ * host=http(CLI preview)时直连 API 与 OSS,走同源 `/api/*` 做 bundle/tests/assets。
+ * 底部 Run 走 TwinAppPreviewHost(D14):import map 注入 @easytwin/runtime 与 @easytwin/apps。
+ * 工作区 *.spec.ts 命名导出在 Run 栏上方列出(D27)。
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * 把 JSON 文本安全嵌入 `<script type="application/json">`。
+ * script 元素的内容是 raw text,HTML 实体不会解码,因此不能使用 escapeHtml;
+ * 只需把 `<`/`>` 与 U+2028/U+2029 转成 JSON 字面转义。
+ */
+declare function escapeJsonForScript(json: string): string;
+/** 纯状态页:预览加载中 / 加载失败时的兜底内容,避免空白 webview。 */
+declare function buildStatusHtml(message: string): string;
+declare function buildPreviewHtml(options: {
+    baseUrl: string;
+    ossUrl: string;
+    sceneJson: string;
+    mock?: boolean;
+    runtimeUri: string;
+    appsUri?: string;
+    hostUri?: string;
+    appId?: string;
+    /** vscode=webview postMessage+混合内容代理;http=CLI 同源 /api/*。缺省 vscode。 */
+    host?: PreviewHostKind;
+    /** VSCode webview.cspSource;缺省回退 runtimeUri 的 origin(单测用)。 */
+    cspSource?: string;
+    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_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 };