@easytwin/devkit 0.1.1 → 0.1.3

package/dist/bin.js

@@ -7,14 +7,14 @@ import { readFile } from "fs/promises";
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
 import { pathToFileURL } from "url";
-import path6 from "path";
+import path10 from "path";
 
 // src/config.ts
 import { promises as fs } from "fs";
 import path from "path";
 var CONFIG_FILE_NAME = "easytwin.config.json";
 var DEFAULT_BASE_URL = "http://saas-twin.k8s.dtstack.cn/";
-var TEST_BASE_URL = "http://saas-twin-test.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 MOCK_APP_ID = "test";
 var MOCK_APP_SECRET = "test";
@@ -63,8 +63,40 @@ function validateConfigShape(value) {
   if (v.env === "prod" || v.env === "test") config.env = v.env;
   if (typeof v.baseUrl === "string") config.baseUrl = v.baseUrl;
   if (typeof v.ossUrl === "string") config.ossUrl = v.ossUrl;
+  const scenes = parseConfigScenes(v.scenes);
+  if (scenes) config.scenes = scenes;
   return config;
 }
+function parseConfigScenes(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new ConfigError("scenes \u5FC5\u987B\u662F\u6570\u7EC4");
+  return value.map((item, i) => {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      throw new ConfigError(`scenes[${i}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+    }
+    const it = item;
+    if (typeof it.id !== "string" || it.id.length === 0) {
+      throw new ConfigError(`scenes[${i}] \u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5 id`);
+    }
+    if (typeof it.name !== "string" || it.name.length === 0) {
+      throw new ConfigError(`scenes[${i}] \u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5 name`);
+    }
+    const scene = { id: it.id, name: it.name };
+    if (it.linkedSceneId !== void 0) {
+      if (typeof it.linkedSceneId !== "string") throw new ConfigError(`scenes[${i}].linkedSceneId \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
+      if (it.linkedSceneId.length > 0) scene.linkedSceneId = it.linkedSceneId;
+    }
+    if (it.snapshotUrl !== void 0) {
+      if (typeof it.snapshotUrl !== "string") throw new ConfigError(`scenes[${i}].snapshotUrl \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
+      if (it.snapshotUrl.length > 0) scene.snapshotUrl = it.snapshotUrl;
+    }
+    if (it.defaultLoading !== void 0) {
+      if (typeof it.defaultLoading !== "boolean") throw new ConfigError(`scenes[${i}].defaultLoading \u5FC5\u987B\u662F\u5E03\u5C14\u503C`);
+      scene.defaultLoading = it.defaultLoading;
+    }
+    return scene;
+  });
+}
 async function readConfigFile(cwd) {
   const file = configFilePath(cwd);
   let raw;
@@ -87,7 +119,8 @@ function resolveConfig(file, env = process.env) {
   return { appId, appSecret, baseUrl, ossUrl, mock: isMockCredentials(appId, appSecret), source };
 }
 async function loadConfig(cwd, env = process.env) {
-  return resolveConfig(await readConfigFile(cwd), env);
+  const file = await readConfigFile(cwd);
+  return resolveConfig(file, env);
 }
 async function writeConfigFile(cwd, config) {
   const file = configFilePath(cwd);
@@ -95,6 +128,7 @@ async function writeConfigFile(cwd, config) {
   if (config.env) body.env = config.env;
   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.writeFile(file, JSON.stringify(body, null, 2) + "\n", "utf8");
   return file;
@@ -122,18 +156,29 @@ async function initConfig(input, cwd) {
   const gitignore = await appendGitignore(cwd);
   return { configFile, gitignore };
 }
+async function writeConfigScenes(cwd, scenes) {
+  const file = await readConfigFile(cwd);
+  await writeConfigFile(cwd, { ...file, scenes });
+}
 
 // src/client.ts
 import http from "http";
 import https from "https";
 import { URL as URL2 } from "url";
-var AUTH_HEADER = "Authorization";
-var BEARER_PREFIX = "Bearer";
-var APP_ID_HEADER = "X-Easytwin-App-Id";
+var APP_ID_HEADER = "x-app-id";
+var AUTH_HEADER = "x-app-secret";
+function enc(id) {
+  return encodeURIComponent(id);
+}
 var ENDPOINTS = {
-  scenes: "/api/scenes",
-  scene: (id) => `/api/scenes/${encodeURIComponent(id)}`,
-  upload: "/api/upload"
+  /** POST 已关联场景列表(分享路径,空 body)。 */
+  linkedScenes: () => `/api/twin/v1/share/sdk-application-code/scenes`,
+  /** POST 拉取工作区全部代码文件(分享路径,空 body)。 */
+  workspaceCodePull: () => `/api/twin/v1/share/sdk-application-code/pull`,
+  /** POST 一次推送 create/update/delete(分享路径)。 */
+  workspaceCodePush: () => `/api/twin/v1/share/sdk-application-code/push`,
+  /** GET 工作区文件约束(仍带 applicationId,走 OP 网关;上传不调用,拉取失败则降级)。 */
+  workspaceConfig: (applicationId) => `/api/twin/v1/sdk-application-code/${enc(applicationId)}/workspace-config`
 };
 var EasyTwinApiError = class extends Error {
   status;
@@ -161,28 +206,40 @@ function parseResponseBody(buffer) {
     return text;
   }
 }
+function isEnvelope(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && "success" in value;
+}
+function unwrapBody(parsed, status) {
+  if (!isEnvelope(parsed)) return parsed;
+  if (parsed.success === false) {
+    throw new EasyTwinApiError(status, messageFromBody(parsed) ?? "\u8BF7\u6C42\u5931\u8D25", parsed);
+  }
+  if (parsed.success === true && "data" in parsed) return parsed.data;
+  return parsed;
+}
 var EasyTwinClient = class {
   baseUrl;
-  /** 本地测试模式:true 时 scene/upload 走本地 mock,不发网络请求(见 config.ts)。 */
-  mock;
+  /** twin runtime / 场景快照资产根(baseOSSUrl)。 */
+  ossUrl;
+  /** 接入凭证 App ID;写入 `x-app-id`,workspace-config 路径仍可用。 */
   appId;
+  /** 本地测试模式:true 时 scene/upload/pull 走本地 mock,不发网络请求(见 config.ts)。 */
+  mock;
   appSecret;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.ossUrl = config.ossUrl.replace(/\/+$/, "");
     this.mock = config.mock;
     this.appId = config.appId;
     this.appSecret = config.appSecret;
   }
   /** 全仓唯一认证头注入点。 */
   authHeaders() {
-    return {
-      [AUTH_HEADER]: `${BEARER_PREFIX} ${this.appSecret}`,
-      [APP_ID_HEADER]: this.appId
-    };
+    return { [APP_ID_HEADER]: this.appId, [AUTH_HEADER]: this.appSecret };
   }
   /** JSON 请求(原生 fetch)。 */
-  async request(path7, options = {}) {
-    const url = `${this.baseUrl}${path7}`;
+  async request(path11, options = {}) {
+    const url = `${this.baseUrl}${path11}`;
     const headers = { ...this.authHeaders(), ...options.headers };
     if (options.body !== void 0 && options.body !== null && !("Content-Type" in headers)) {
       headers["Content-Type"] = "application/json";
@@ -204,8 +261,8 @@ var EasyTwinClient = class {
    * multipart 流式上传(手写 http 请求以支持逐字节进度回调)。
    * 这是 fetch 上传的替代路径:原生 fetch 无法上报上传进度。
    */
-  async upload(path7, options) {
-    const url = new URL2(`${this.baseUrl}${path7}`);
+  async upload(path11, options) {
+    const url = new URL2(`${this.baseUrl}${path11}`);
     const mod = url.protocol === "https:" ? https : http;
     const headers = {
       ...this.authHeaders(),
@@ -238,8 +295,8 @@ var EasyTwinClient = class {
     return this.handleStatus(raw.status, raw.body);
   }
   handleStatus(status, body) {
-    if (status >= 200 && status < 300) return parseResponseBody(body);
     const parsed = parseResponseBody(body);
+    if (status >= 200 && status < 300) return unwrapBody(parsed, status);
     throw new EasyTwinApiError(status, messageFromBody(parsed) ?? `HTTP ${status}`, parsed);
   }
 };
@@ -248,17 +305,89 @@ var EasyTwinClient = class {
 import { promises as fs2 } from "fs";
 import path2 from "path";
 import { fileURLToPath } from "url";
-function normalizeSceneList(data) {
-  const list = Array.isArray(data) ? data : data?.list;
-  if (!Array.isArray(list)) throw new Error("scene list \u54CD\u5E94\u7ED3\u6784\u65E0\u6CD5\u8BC6\u522B");
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function asString(value) {
+  return typeof value === "string" ? value : "";
+}
+function asBoolean(value) {
+  return value === true;
+}
+function extractSceneArray(data) {
+  if (Array.isArray(data)) return data;
+  const root = asRecord(data);
+  if (Array.isArray(root.data)) return root.data;
+  if (Array.isArray(root.list)) return root.list;
+  if (Array.isArray(root.scenes)) return root.scenes;
+  const nested = asRecord(root.data);
+  if (Array.isArray(nested.scenes)) return nested.scenes;
+  if (Array.isArray(nested.list)) return nested.list;
+  throw new Error("scene list \u54CD\u5E94\u7ED3\u6784\u65E0\u6CD5\u8BC6\u522B");
+}
+function normalizeLinkedScenes(data) {
+  const list = extractSceneArray(data);
   return list.map((item) => {
-    const it = item ?? {};
-    return { id: String(it.id ?? ""), name: String(it.name ?? it.id ?? "") };
+    const it = asRecord(item);
+    const sceneKey = asString(it.sceneKey);
+    const sourceProjectName = asString(it.sourceProjectName);
+    const sourceSceneName = asString(it.sourceSceneName);
+    return {
+      id: asString(it.id),
+      sceneKey,
+      name: sourceProjectName || sourceSceneName || sceneKey,
+      defaultLoading: asBoolean(it.defaultLoading),
+      sourceSceneId: asString(it.sourceSceneId),
+      sourceProjectId: asString(it.sourceProjectId),
+      sourceSceneName,
+      sourceProjectName,
+      sourceLost: asBoolean(it.sourceLost),
+      snapshotUrl: asString(it.snapshotUrl),
+      snapshotUpdatedAt: asString(it.snapshotUpdatedAt)
+    };
   });
 }
-function normalizeSceneDetail(data) {
-  const it = data ?? {};
-  return { id: String(it.id ?? ""), name: String(it.name ?? ""), payload: data };
+function normalizeSceneList(data) {
+  return normalizeLinkedScenes(data).map((s) => ({
+    id: s.sceneKey,
+    name: s.name,
+    linkedSceneId: s.id,
+    snapshotUrl: s.snapshotUrl,
+    defaultLoading: s.defaultLoading
+  }));
+}
+function toConfigScenes(scenes) {
+  return scenes.map((s) => {
+    const item = { id: s.id, name: s.name };
+    if (s.linkedSceneId) item.linkedSceneId = s.linkedSceneId;
+    if (s.snapshotUrl) item.snapshotUrl = s.snapshotUrl;
+    if (s.defaultLoading !== void 0) item.defaultLoading = s.defaultLoading;
+    return item;
+  });
+}
+function resolveSnapshotUrl(ossUrl, snapshotUrl) {
+  if (/^https?:\/\//i.test(snapshotUrl)) return snapshotUrl;
+  const base = ossUrl.replace(/\/+$/, "");
+  const rel = snapshotUrl.replace(/^\/+/, "");
+  return `${base}/${rel}`;
+}
+async function fetchSnapshotJson(ossUrl, snapshotUrl) {
+  if (snapshotUrl.length === 0) throw new Error("\u573A\u666F\u5FEB\u7167\u5730\u5740\u4E3A\u7A7A");
+  const url = resolveSnapshotUrl(ossUrl, snapshotUrl);
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    throw new EasyTwinApiError(0, `\u62C9\u53D6\u573A\u666F\u5FEB\u7167\u5931\u8D25:${url}:${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!res.ok) {
+    throw new EasyTwinApiError(res.status, `\u62C9\u53D6\u573A\u666F\u5FEB\u7167\u5931\u8D25:HTTP ${res.status} ${url}`);
+  }
+  try {
+    return await res.json();
+  } catch {
+    throw new Error(`\u573A\u666F\u5FEB\u7167\u4E0D\u662F\u5408\u6CD5 JSON:${url}`);
+  }
 }
 var EXAMPLE_SCENE_FILE = "scene.example.json";
 var MOCK_SCENE_NAME = "\u672C\u5730\u793A\u4F8B\u573A\u666F";
@@ -290,22 +419,34 @@ function deriveExampleSceneId(payload) {
 async function exampleSceneSummary(exampleFile) {
   return { id: deriveExampleSceneId(await loadExampleScene(exampleFile)), name: MOCK_SCENE_NAME };
 }
+async function fetchLinkedScenes(client) {
+  return client.request(ENDPOINTS.linkedScenes(), { method: "POST" });
+}
 async function listScenes(client, options = {}) {
-  if (client.mock) return [await exampleSceneSummary(options.exampleFile)];
-  const data = await client.request(ENDPOINTS.scenes, { method: "GET" });
-  return normalizeSceneList(data);
+  const scenes = client.mock ? [await exampleSceneSummary(options.exampleFile)] : normalizeSceneList(await fetchLinkedScenes(client));
+  if (options.cwd) await writeConfigScenes(options.cwd, toConfigScenes(scenes));
+  return scenes;
 }
 async function pullScene(client, id, options = {}) {
   if (client.mock) {
-    const payload = await loadExampleScene(options.exampleFile);
-    const sceneId = deriveExampleSceneId(payload);
+    const payload2 = await loadExampleScene(options.exampleFile);
+    const sceneId = deriveExampleSceneId(payload2);
     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 };
+    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}`
+    );
   }
-  const data = await client.request(ENDPOINTS.scene(id), { method: "GET" });
-  return normalizeSceneDetail(data);
+  const payload = await fetchSnapshotJson(client.ossUrl, hit.snapshotUrl);
+  return { id: hit.sceneKey, name: hit.name, payload };
 }
 async function saveSceneJson(scene, out) {
   await fs2.mkdir(path2.dirname(out), { recursive: true });
@@ -316,7 +457,43 @@ async function saveSceneJson(scene, out) {
 // src/upload.ts
 import { promises as fs3 } from "fs";
 import path3 from "path";
-var DEFAULT_IGNORED_DIRS = /* @__PURE__ */ new Set([".git"]);
+var WORKSPACE_IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  ".easytwin",
+  ".cursor",
+  ".claude",
+  ".qoder",
+  ".vscode"
+]);
+var WORKSPACE_IGNORED_FILES = /* @__PURE__ */ new Set([CONFIG_FILE_NAME, GITIGNORE_FILE_NAME]);
+function isTsconfigFile(base) {
+  return /^tsconfig(\..+)?\.json$/i.test(base);
+}
+var WORKSPACE_CODE_EXTENSIONS = [".ts", ".tsx", ".js", ".json"];
+function isWorkspaceSpecFile(relPath) {
+  const base = normalizePath(relPath).split("/").pop() ?? "";
+  return /\.spec\.ts$/i.test(base);
+}
+function isIgnoredWorkspacePath(relPath) {
+  const parts = normalizePath(relPath).split("/").filter((p) => p.length > 0);
+  if (parts.some((p) => WORKSPACE_IGNORED_DIRS.has(p))) return true;
+  const base = parts[parts.length - 1];
+  if (base === void 0) return false;
+  if (WORKSPACE_IGNORED_FILES.has(base)) return true;
+  if (isTsconfigFile(base)) return true;
+  return base.toLowerCase().endsWith(".scene.json");
+}
+function defaultWorkspaceIgnore(relPath) {
+  return isIgnoredWorkspacePath(relPath) || isWorkspaceSpecFile(relPath);
+}
+function combineUploadIgnore(extra) {
+  return (relPath) => defaultWorkspaceIgnore(relPath) || (extra?.(relPath) ?? false);
+}
+async function collectWorkspaceCodeFiles(dir, ignore) {
+  return (await collectFiles(dir, ignore)).filter((f) => isWorkspaceCodeFile(f.relPath));
+}
 async function collectFiles(dir, ignore = () => false) {
   const files = [];
   async function walk(current, rel) {
@@ -325,7 +502,7 @@ async function collectFiles(dir, ignore = () => false) {
       const relPath = path3.posix.join(rel, entry.name);
       if (ignore(relPath)) continue;
       if (entry.isDirectory()) {
-        if (DEFAULT_IGNORED_DIRS.has(entry.name)) continue;
+        if (entry.name === ".git") continue;
         await walk(path3.join(current, entry.name), relPath);
       } else if (entry.isFile()) {
         const absPath = path3.join(current, entry.name);
@@ -338,67 +515,344 @@ async function collectFiles(dir, ignore = () => false) {
   files.sort((a, b) => a.relPath.localeCompare(b.relPath));
   return files;
 }
-function buildMultipartBody(boundary, fields, file) {
-  const parts = [];
-  for (const [key, value] of Object.entries(fields)) {
-    parts.push(
-      Buffer.from(`--${boundary}\r
-Content-Disposition: form-data; name="${key}"\r
-\r
-${value}\r
-`, "utf8")
-    );
+function asRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function asString2(value) {
+  return typeof value === "string" ? value : "";
+}
+function normalizePath(relPath) {
+  return relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function normalizeWorkspaceFiles(data) {
+  if (!Array.isArray(data)) throw new Error("workspace code \u54CD\u5E94\u7ED3\u6784\u65E0\u6CD5\u8BC6\u522B");
+  return data.map((item) => {
+    const it = asRecord2(item);
+    return { id: asString2(it.id), filePath: asString2(it.filePath), content: asString2(it.content) };
+  });
+}
+function extensionOf(relPath) {
+  const base = relPath.split("/").pop() ?? "";
+  const i = base.lastIndexOf(".");
+  if (i <= 0) return "";
+  return base.slice(i).toLowerCase();
+}
+function allowedExtensionSet(list) {
+  return new Set(list.map((e) => e.startsWith(".") ? e.toLowerCase() : `.${e.toLowerCase()}`));
+}
+var WORKSPACE_CODE_EXTENSION_SET = allowedExtensionSet(WORKSPACE_CODE_EXTENSIONS);
+function isWorkspaceCodeFile(relPath) {
+  return WORKSPACE_CODE_EXTENSION_SET.has(extensionOf(relPath));
+}
+function countsFromPlan(plan) {
+  return {
+    created: plan.creates.length,
+    updated: plan.updates.length,
+    deleted: plan.deletes.length,
+    unchanged: plan.unchanged.length
+  };
+}
+function planWorkspaceUpload(local, remote) {
+  const remoteByPath = new Map(remote.map((f) => [normalizePath(f.filePath), f]));
+  const localPaths = new Set(local.map((item) => normalizePath(item.file.relPath)));
+  const deletes = remote.filter((f) => !localPaths.has(normalizePath(f.filePath))).map((f) => ({ id: f.id, filePath: normalizePath(f.filePath) }));
+  const creates = [];
+  const updates = [];
+  const unchanged = [];
+  for (const item of local) {
+    const remoteFile = remoteByPath.get(normalizePath(item.file.relPath));
+    if (!remoteFile) creates.push(item);
+    else if (remoteFile.content !== item.content) {
+      updates.push({ file: item.file, id: remoteFile.id, content: item.content });
+    } else {
+      unchanged.push(item.file);
+    }
   }
-  parts.push(
-    Buffer.from(
-      `--${boundary}\r
-Content-Disposition: form-data; name="file"; filename="${file.name}"\r
-Content-Type: application/octet-stream\r
-\r
-`,
-      "utf8"
-    )
-  );
-  parts.push(file.content);
-  parts.push(Buffer.from(`\r
---${boundary}--\r
-`, "utf8"));
-  return Buffer.concat(parts);
+  return { creates, updates, deletes, unchanged };
+}
+function formatUploadResult(result) {
+  const prefix = result.mock ? "[\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F] \u672A\u771F\u6B63\u4E0A\u4F20; " : "";
+  return `${prefix}\u672C\u5730 ${result.fileCount} \u4E2A\u6587\u4EF6,\u5171 ${result.byteCount} bytes;\u65B0\u589E ${result.created},\u66F4\u65B0 ${result.updated},\u5220\u9664 ${result.deleted},\u672A\u53D8 ${result.unchanged}`;
 }
 async function mockUpload(dir, options) {
-  const ignore = options.ignore ?? (() => false);
-  const files = await collectFiles(dir, ignore);
+  const ignore = combineUploadIgnore(options.ignore);
+  const files = await collectWorkspaceCodeFiles(dir, ignore);
   const total = files.reduce((sum, f) => sum + f.size, 0);
   options.onProgress?.({ phase: "collect", current: total, total });
   options.onProgress?.({ phase: "upload", current: total, total });
-  return { fileCount: files.length, byteCount: total, mock: true };
+  return { fileCount: files.length, byteCount: total, created: 0, updated: 0, deleted: 0, unchanged: files.length, mock: true };
+}
+function buildWorkspacePushBody(plan) {
+  const body = {};
+  if (plan.creates.length > 0) {
+    body.create = plan.creates.map((c) => ({
+      filePath: normalizePath(c.file.relPath),
+      content: c.content
+    }));
+  }
+  if (plan.updates.length > 0) {
+    body.update = plan.updates.map((p) => ({
+      id: p.id,
+      content: p.content,
+      filePath: normalizePath(p.file.relPath)
+    }));
+  }
+  if (plan.deletes.length > 0) {
+    body.delete = plan.deletes.map((d) => d.id);
+  }
+  return Object.keys(body).length > 0 ? body : null;
 }
 async function uploadDirectory(client, dir, options = {}) {
   if (client.mock) return mockUpload(dir, options);
-  const ignore = options.ignore ?? (() => false);
-  const files = await collectFiles(dir, ignore);
+  const ignore = combineUploadIgnore(options.ignore);
+  const files = await collectWorkspaceCodeFiles(dir, ignore);
   const total = files.reduce((sum, f) => sum + f.size, 0);
   options.onProgress?.({ phase: "collect", current: total, total });
-  let sent = 0;
+  const remote = normalizeWorkspaceFiles(await client.request(ENDPOINTS.workspaceCodePull(), { method: "POST" }));
+  const local = [];
   for (const file of files) {
-    const content = await fs3.readFile(file.absPath);
-    const boundary = `----easytwin${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
-    const body = buildMultipartBody(
-      boundary,
-      // TODO(swagger): multipart 字段名/结构待定,当前为占位约定。
-      { path: file.relPath },
-      { name: path3.basename(file.relPath), content }
-    );
-    await client.upload(ENDPOINTS.upload, { boundary, body });
+    local.push({ file, content: await fs3.readFile(file.absPath, "utf8") });
+  }
+  const plan = planWorkspaceUpload(local, remote);
+  const counts = countsFromPlan(plan);
+  const pushBody = buildWorkspacePushBody(plan);
+  if (pushBody) {
+    await client.request(ENDPOINTS.workspaceCodePush(), {
+      method: "POST",
+      body: JSON.stringify(pushBody)
+    });
+  }
+  let sent = 0;
+  const bump = (file) => {
     sent += file.size;
     options.onProgress?.({ phase: "upload", current: sent, total, file: file.relPath });
+  };
+  for (const c of plan.creates) bump(c.file);
+  for (const p of plan.updates) bump(p.file);
+  for (const u of plan.unchanged) bump(u);
+  if (files.length === 0) options.onProgress?.({ phase: "upload", current: 0, total: 0 });
+  return { fileCount: files.length, byteCount: total, ...counts };
+}
+
+// src/workspace.ts
+import { promises as fs4 } from "fs";
+import path5 from "path";
+
+// src/assetsPath.ts
+import path4 from "path";
+function resolveWorkspaceAssetPath(cwd, relPath) {
+  const root = path4.resolve(cwd);
+  const input = relPath.trim();
+  if (!input) throw new Error("assets \u8DEF\u5F84\u4E3A\u7A7A");
+  if (path4.isAbsolute(input)) throw new Error(`assets \u53EA\u63A5\u53D7\u5DE5\u4F5C\u533A\u76F8\u5BF9\u8DEF\u5F84,\u62D2\u7EDD\u7EDD\u5BF9\u8DEF\u5F84: ${relPath}`);
+  const resolved = path4.resolve(root, input);
+  const rel = path4.relative(root, resolved);
+  if (rel.startsWith("..") || path4.isAbsolute(rel)) {
+    throw new Error(`assets \u8DEF\u5F84\u9003\u9038\u5DE5\u4F5C\u533A: ${relPath}`);
+  }
+  return resolved;
+}
+
+// src/workspace.ts
+var DEFAULT_ENTRY_PATH = "src/main.ts";
+var DEFAULT_MAIN_TS = `import { TwinApp, type TwinAppContext } from "@easytwin/apps";
+
+export default class App extends TwinApp {
+  async init(ctx: TwinAppContext) {
+    // engine / container \u5DF2\u6709;scene / camera \u4E3A null
+    void ctx;
+  }
+
+  async onSceneLoaded(ctx: TwinAppContext) {
+    // \u573A\u666F\u5B57\u6BB5\u6709\u503C;\u5728\u6B64\u52A0\u7269\u4F53 / \u7ED1\u4E8B\u4EF6,\u5E76\u7528 ctx.sceneCleanup \u5BF9\u79F0\u62C6\u9664
+    void ctx;
+  }
+
+  onUpdate(ctx: TwinAppContext, delta: number, elapsed: number) {
+    void ctx;
+    void delta;
+    void elapsed;
+  }
+
+  onDispose(ctx: TwinAppContext) {
+    void ctx;
+  }
+}
+`;
+function defaultPullIgnore(relPath) {
+  return defaultWorkspaceIgnore(relPath);
+}
+function isSafeRelPath(relPath) {
+  const n = normalizePath(relPath);
+  if (!n) return false;
+  if (n.toLowerCase() === "easytwin.config.json") 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;
+  const parts = n.split("/");
+  if (parts.some((p) => p === ".." || p === "." || p === "")) return false;
+  return true;
+}
+function normalizeEol(text) {
+  return text.replace(/\r\n/g, "\n");
+}
+function combineIgnore(extra) {
+  return (relPath) => defaultPullIgnore(relPath) || (extra?.(relPath) ?? false);
+}
+async function readLocalText(absPath) {
+  try {
+    return await fs4.readFile(absPath, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") return void 0;
+    throw err;
   }
-  return { fileCount: files.length, byteCount: sent };
+}
+async function fetchRemoteFiles(client) {
+  if (client.mock) return [];
+  return normalizeWorkspaceFiles(await client.request(ENDPOINTS.workspaceCodePull(), { method: "POST" }));
+}
+async function planWorkspacePull(client, dir, options = {}) {
+  const ignore = combineIgnore(options.ignore);
+  const remoteRaw = await fetchRemoteFiles(client);
+  const skippedRemotePaths = [];
+  const remoteByPath = /* @__PURE__ */ new Map();
+  for (const file of remoteRaw) {
+    const rel = normalizePath(file.filePath);
+    if (!isSafeRelPath(rel) || ignore(rel) || !isWorkspaceCodeFile(rel)) {
+      skippedRemotePaths.push(rel || file.filePath);
+      continue;
+    }
+    remoteByPath.set(rel, file.content);
+  }
+  let localFiles = [];
+  try {
+    localFiles = await collectFiles(dir, ignore);
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") throw err;
+  }
+  const localByPath = /* @__PURE__ */ new Map();
+  for (const file of localFiles) {
+    const rel = normalizePath(file.relPath);
+    if (!isWorkspaceCodeFile(rel)) continue;
+    const content = await readLocalText(file.absPath);
+    if (content !== void 0) localByPath.set(rel, content);
+  }
+  const changes = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [rel, remoteContent] of remoteByPath) {
+    seen.add(rel);
+    const localContent = localByPath.get(rel);
+    if (localContent === void 0) {
+      changes.push({ path: rel, kind: "remote-only", remoteContent });
+    } else if (normalizeEol(localContent) === normalizeEol(remoteContent)) {
+      changes.push({ path: rel, kind: "identical", localContent, remoteContent });
+    } else {
+      changes.push({ path: rel, kind: "modified", localContent, remoteContent });
+    }
+  }
+  for (const [rel, localContent] of localByPath) {
+    if (seen.has(rel)) continue;
+    changes.push({ path: rel, kind: "local-only", localContent });
+  }
+  const remoteEmpty = remoteByPath.size === 0;
+  let seededDefaults = false;
+  if (remoteEmpty) {
+    const localMain = localByPath.get(DEFAULT_ENTRY_PATH);
+    if (localMain === void 0) {
+      changes.push({ path: DEFAULT_ENTRY_PATH, kind: "seed", remoteContent: DEFAULT_MAIN_TS });
+      seededDefaults = true;
+    }
+  }
+  changes.sort((a, b) => a.path.localeCompare(b.path));
+  return {
+    remoteEmpty,
+    seededDefaults,
+    mock: client.mock || void 0,
+    skippedRemotePaths,
+    changes
+  };
+}
+async function applyWorkspacePull(dir, plan, options = {}) {
+  const written = [];
+  const skippedConflicts = [];
+  for (const change of plan.changes) {
+    if (change.kind === "identical" || change.kind === "local-only") continue;
+    if (change.kind === "modified" && !options.force) {
+      skippedConflicts.push(change.path);
+      continue;
+    }
+    const content = change.remoteContent ?? "";
+    const abs = resolveWorkspaceAssetPath(dir, change.path);
+    await fs4.mkdir(path5.dirname(abs), { recursive: true });
+    await fs4.writeFile(abs, content, "utf8");
+    written.push(change.path);
+  }
+  return { written, skippedConflicts };
+}
+async function pullWorkspace(client, dir, options = {}) {
+  const plan = await planWorkspacePull(client, dir, { ignore: options.ignore });
+  if (options.dryRun) {
+    const skippedConflicts = plan.changes.filter((c) => c.kind === "modified" && !options.force).map((c) => c.path);
+    return { plan, written: [], skippedConflicts, dryRun: true, mock: plan.mock };
+  }
+  const applied = await applyWorkspacePull(dir, plan, { force: options.force });
+  return { plan, ...applied, mock: plan.mock };
+}
+var KIND_LABEL = {
+  identical: "same  ",
+  "remote-only": "create",
+  "local-only": "keep  ",
+  modified: "modify",
+  seed: "seed  "
+};
+function formatWorkspacePullPlan(plan) {
+  const lines = [];
+  if (plan.mock) lines.push("[\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F] \u6309\u8FDC\u7AEF\u4E3A\u7A7A\u5904\u7406");
+  const remoteCount = plan.changes.filter((c) => c.kind !== "local-only" && c.kind !== "seed").length;
+  if (plan.remoteEmpty) {
+    lines.push(
+      plan.seededDefaults ? `\u8FDC\u7AEF 0 \u4E2A\u6587\u4EF6,\u5C06\u5199\u5165\u9ED8\u8BA4 ${DEFAULT_ENTRY_PATH}` : "\u8FDC\u7AEF 0 \u4E2A\u6587\u4EF6,\u672C\u5730\u5DF2\u6709\u5165\u53E3,\u672A\u6539\u52A8\u9ED8\u8BA4\u6A21\u677F"
+    );
+  } else {
+    lines.push(`\u8FDC\u7AEF ${remoteCount} \u4E2A\u6587\u4EF6`);
+  }
+  for (const change of plan.changes) {
+    let extra = "";
+    if (change.kind === "modified") extra = " (\u51B2\u7A81,\u9ED8\u8BA4\u4E0D\u8986\u76D6)";
+    if (change.kind === "local-only") extra = " (\u4EC5\u672C\u5730)";
+    if (change.kind === "seed") extra = " (\u9ED8\u8BA4 TwinApp)";
+    lines.push(`  ${KIND_LABEL[change.kind]}  ${change.path}${extra}`);
+  }
+  if (plan.skippedRemotePaths.length > 0) {
+    lines.push(`\u8DF3\u8FC7\u975E\u6CD5/\u51ED\u636E\u8DEF\u5F84: ${plan.skippedRemotePaths.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function formatWorkspacePullResult(result) {
+  const lines = [formatWorkspacePullPlan(result.plan)];
+  if (result.dryRun) {
+    lines.push("dry-run:\u672A\u5199\u76D8");
+    if (result.skippedConflicts.length > 0) {
+      lines.push(`${result.skippedConflicts.length} \u4E2A\u51B2\u7A81\u672A\u8986\u76D6(\u52A0 --force)`);
+    }
+    return lines.join("\n");
+  }
+  if (result.written.length > 0) {
+    lines.push(`\u5DF2\u5199\u5165 ${result.written.length} \u4E2A\u6587\u4EF6: ${result.written.join(", ")}`);
+  } else {
+    lines.push("\u672A\u5199\u5165\u6587\u4EF6");
+  }
+  if (result.skippedConflicts.length > 0) {
+    lines.push(`${result.skippedConflicts.length} \u4E2A\u51B2\u7A81\u672A\u8986\u76D6(\u52A0 --force): ${result.skippedConflicts.join(", ")}`);
+  }
+  return lines.join("\n");
 }
 
 // src/skills.ts
-import { existsSync, promises as fs4 } from "fs";
-import path4 from "path";
+import { existsSync, promises as fs5 } from "fs";
+import path6 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var SKILL_NAMES = [
   "easytwin-render",
@@ -406,7 +860,8 @@ var SKILL_NAMES = [
   "easytwin-develop",
   "easytwin-bootstrap",
   "easytwin-scene",
-  "easytwin-upload"
+  "easytwin-upload",
+  "easytwin-test"
 ];
 var CODEX_MARKER_BEGIN = "<!-- EASYTWIN-SKILLS:BEGIN -->";
 var CODEX_MARKER_END = "<!-- EASYTWIN-SKILLS:END -->";
@@ -421,7 +876,8 @@ var MINIMAL_TSCONFIG = `${JSON.stringify(
       skipLibCheck: true,
       noEmit: true,
       paths: {
-        "@easytwin/runtime": [".easytwin/types"]
+        "@easytwin/runtime": [".easytwin/types"],
+        "@easytwin/apps": [".easytwin/types/apps"]
       }
     },
     include: ["src/**/*.ts"]
@@ -433,22 +889,55 @@ var MINIMAL_TSCONFIG = `${JSON.stringify(
 var TSCONFIG_PATHS_HINT = `\u5DF2\u6709 tsconfig.json,\u672A\u6539\u52A8\u3002\u8BF7\u5728 compilerOptions \u4E2D\u52A0\u5165:
   "skipLibCheck": true,
   "paths": {
-    "@easytwin/runtime": [".easytwin/types"]
+    "@easytwin/runtime": [".easytwin/types"],
+    "@easytwin/apps": [".easytwin/types/apps"]
   }`;
-var RUN_CONTEXT_DECL = `
-/** \u9884\u89C8\u9875 Run \u6309\u94AE\u6CE8\u5165\u7684\u8FD0\u884C\u4E0A\u4E0B\u6587(\u89C1 D12)\u3002 */
-export interface EasyTwinRunContext {
+var APPS_TYPES_FILE = "apps.d.ts";
+var APPS_DTS = `import type { RuntimeEngine, RuntimeScene, SceneManager } from "@easytwin/runtime";
+
+export type TwinAppContext = {
+    app: {
+        id: string;
+        mode: "preview" | "publish";
+    };
     engine: RuntimeEngine;
-    runtime: typeof import("@easytwin/runtime");
-    sceneJson: SceneJson;
+    container: HTMLElement;
+    runtimeScene: RuntimeScene | null;
+    scene: RuntimeScene["sceneObject"] | null;
+    camera: RuntimeScene["camera"]["main"] | null;
+    sceneManager: {
+        currentSceneId: string;
+        runtime: SceneManager | 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;
+};
+
+export 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;
 }
+
+export declare function defineApp<T>(app: T): T;
 `;
 function buildRuntimeTypesContent(sourceDts) {
-  const trimmed = sourceDts.replace(/\s+$/, "");
-  if (trimmed.includes("export interface EasyTwinRunContext")) return `${trimmed}
+  return `${sourceDts.replace(/\s+$/, "")}
 `;
-  return `${trimmed}
-${RUN_CONTEXT_DECL}`;
 }
 function normalizeTargets(target = "all") {
   if (target === "all") return ["cursor", "claude", "codex", "qoder"];
@@ -459,69 +948,69 @@ function resolveSkillsSourceDir() {
   if (typeof import.meta.url !== "string" || import.meta.url.length === 0) {
     throw new Error("\u65E0\u6CD5\u5B9A\u4F4D skills \u6E90\u76EE\u5F55:\u63D2\u4EF6(bundle/CJS)\u573A\u666F\u5FC5\u987B\u663E\u5F0F\u4F20\u5165 sourceDir");
   }
-  const here = path4.dirname(fileURLToPath2(import.meta.url));
-  return path4.resolve(here, "..", "skills");
+  const here = path6.dirname(fileURLToPath2(import.meta.url));
+  return path6.resolve(here, "..", "skills");
 }
 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");
   }
-  const here = path4.dirname(fileURLToPath2(import.meta.url));
-  const fromDist = path4.join(here, "runtime-types", "index.d.ts");
-  const fromSrc = path4.resolve(here, "lib", "index.d.ts");
+  const here = path6.dirname(fileURLToPath2(import.meta.url));
+  const fromDist = path6.join(here, "runtime-types", "index.d.ts");
+  const fromSrc = path6.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}`);
 }
 async function readJson(file) {
-  return JSON.parse(await fs4.readFile(file, "utf8"));
+  return JSON.parse(await fs5.readFile(file, "utf8"));
 }
 async function readDevkitVersion(skillsDir = resolveSkillsSourceDir()) {
-  const marker = path4.join(skillsDir, ".easytwin-source.json");
+  const marker = path6.join(skillsDir, ".easytwin-source.json");
   try {
     const meta = await readJson(marker);
     if (typeof meta.version === "string") return meta.version;
   } catch {
   }
   try {
-    const pkg = await readJson(path4.resolve(skillsDir, "..", "package.json"));
+    const pkg = await readJson(path6.resolve(skillsDir, "..", "package.json"));
     return pkg.version;
   } catch {
     return "0.0.0";
   }
 }
 async function copyDir(src, dest) {
-  await fs4.mkdir(dest, { recursive: true });
-  const entries = await fs4.readdir(src, { withFileTypes: true });
+  await fs5.mkdir(dest, { recursive: true });
+  const entries = await fs5.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
-    const s = path4.join(src, entry.name);
-    const d = path4.join(dest, entry.name);
+    const s = path6.join(src, entry.name);
+    const d = path6.join(dest, entry.name);
     if (entry.isDirectory()) await copyDir(s, d);
-    else if (entry.isFile()) await fs4.copyFile(s, d);
+    else if (entry.isFile()) await fs5.copyFile(s, d);
   }
 }
 async function dirMatches(src, dest) {
   let sourceEntries;
   try {
-    sourceEntries = await fs4.readdir(src);
+    sourceEntries = await fs5.readdir(src);
   } catch {
     return false;
   }
   for (const name of sourceEntries) {
-    const s = path4.join(src, name);
-    const d = path4.join(dest, name);
-    const sStat = await fs4.stat(s);
+    const s = path6.join(src, name);
+    const d = path6.join(dest, name);
+    const sStat = await fs5.stat(s);
     if (sStat.isDirectory()) {
       if (!await dirMatches(s, d)) return false;
     } else {
       let dStat;
       try {
-        dStat = await fs4.stat(d);
+        dStat = await fs5.stat(d);
       } catch {
         return false;
       }
       if (!sStat.isFile() || !dStat.isFile() || sStat.size !== dStat.size) return false;
-      if (!(await fs4.readFile(s)).equals(await fs4.readFile(d))) return false;
+      if (!(await fs5.readFile(s)).equals(await fs5.readFile(d))) return false;
     }
   }
   return true;
@@ -532,18 +1021,18 @@ function actionFor(exists, matches) {
 }
 async function writeMeta(destDir, version) {
   const meta = { name: "@easytwin/devkit", version };
-  await fs4.writeFile(path4.join(destDir, META_FILE_NAME), JSON.stringify(meta, null, 2) + "\n", "utf8");
+  await fs5.writeFile(path6.join(destDir, META_FILE_NAME), JSON.stringify(meta, null, 2) + "\n", "utf8");
 }
 async function syncToDir(target, sourceRoot, targetRoot, version) {
   const entries = [];
   for (const name of SKILL_NAMES) {
-    const src = path4.join(sourceRoot, name);
-    const dest = path4.join(targetRoot, name);
-    const exists = await fs4.stat(dest).then(() => true).catch(() => false);
+    const src = path6.join(sourceRoot, name);
+    const dest = path6.join(targetRoot, name);
+    const exists = await fs5.stat(dest).then(() => true).catch(() => false);
     const matches = await dirMatches(src, dest);
     const action = actionFor(exists, matches);
     if (action !== "unchanged") {
-      await fs4.rm(dest, { recursive: true, force: true });
+      await fs5.rm(dest, { recursive: true, force: true });
       await copyDir(src, dest);
     }
     entries.push({ name, action });
@@ -562,19 +1051,20 @@ function buildCodexSegment(version) {
     "- `easytwin-scene`:\u5217\u51FA\u573A\u666F\u3001\u62C9\u53D6\u573A\u666F JSON\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`:\u5168\u91CF\u4E0A\u4F20\u5F00\u53D1\u4EA7\u7269\u76EE\u5F55(\u8986\u76D6\u4E0D\u53EF\u9006)\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",
+    "- `easytwin-test`:\u5199\u5DE5\u4F5C\u533A `*.spec.ts`,\u9884\u89C8\u9875\u6309\u94AE/\u8F93\u5165\u6846\u8C03\u7528\u5BFC\u51FA\u51FD\u6570(\u4E0D\u540C\u6B65;CLI `easytwin preview` \u6216\u63D2\u4EF6)\u3002",
     "",
     "\u8BE6\u7EC6\u7528\u6CD5\u89C1\u5404\u6280\u80FD;\u91CD\u65B0\u540C\u6B65\u8FD0\u884C `easytwin skills sync --target codex`\u3002",
     CODEX_MARKER_END
   ].join("\n");
 }
 async function syncToCodex(sourceRoot, cwd, version) {
-  const agentsFile = path4.join(cwd, "AGENTS.md");
+  const agentsFile = path6.join(cwd, "AGENTS.md");
   const segment = buildCodexSegment(version);
   let content = "";
   let exists = true;
   try {
-    content = await fs4.readFile(agentsFile, "utf8");
+    content = await fs5.readFile(agentsFile, "utf8");
   } catch {
     exists = false;
   }
@@ -592,39 +1082,50 @@ async function syncToCodex(sourceRoot, cwd, version) {
     next = content.slice(0, start) + segment + content.slice(end + CODEX_MARKER_END.length);
   }
   if (action !== "unchanged") {
-    await fs4.mkdir(cwd, { recursive: true });
-    await fs4.writeFile(agentsFile, next, "utf8");
+    await fs5.mkdir(cwd, { recursive: true });
+    await fs5.writeFile(agentsFile, next, "utf8");
   }
   return { target: "codex", entries: [], codex: { name: "AGENTS.md", action } };
 }
 async function syncRuntimeTypes(cwd, typesSourceFile) {
-  const destDir = path4.join(cwd, ".easytwin", "types");
-  const destFile = path4.join(destDir, "index.d.ts");
-  const content = buildRuntimeTypesContent(await fs4.readFile(typesSourceFile, "utf8"));
-  let exists = true;
-  let current = "";
+  const destDir = path6.join(cwd, ".easytwin", "types");
+  const destFile = path6.join(destDir, "index.d.ts");
+  const appsFile = path6.join(destDir, APPS_TYPES_FILE);
+  const content = buildRuntimeTypesContent(await fs5.readFile(typesSourceFile, "utf8"));
+  let runtimeCurrent = "";
+  let appsCurrent = "";
+  let runtimeExists = true;
+  let appsExists = true;
   try {
-    current = await fs4.readFile(destFile, "utf8");
+    runtimeCurrent = await fs5.readFile(destFile, "utf8");
   } catch {
-    exists = false;
+    runtimeExists = false;
   }
-  const action = actionFor(exists, current === content);
-  if (action !== "unchanged") {
-    await fs4.mkdir(destDir, { recursive: true });
-    await fs4.writeFile(destFile, content, "utf8");
+  try {
+    appsCurrent = await fs5.readFile(appsFile, "utf8");
+  } catch {
+    appsExists = false;
+  }
+  const runtimeAction = actionFor(runtimeExists, runtimeCurrent === content);
+  const appsAction = actionFor(appsExists, appsCurrent === APPS_DTS);
+  const action = runtimeAction === "unchanged" && appsAction === "unchanged" ? "unchanged" : !runtimeExists && !appsExists ? "created" : "updated";
+  if (runtimeAction !== "unchanged" || appsAction !== "unchanged") {
+    await fs5.mkdir(destDir, { recursive: true });
+    if (runtimeAction !== "unchanged") await fs5.writeFile(destFile, content, "utf8");
+    if (appsAction !== "unchanged") await fs5.writeFile(appsFile, APPS_DTS, "utf8");
   }
-  const tsconfigPath = path4.join(cwd, "tsconfig.json");
+  const tsconfigPath = path6.join(cwd, "tsconfig.json");
   let tsconfig;
   let pathsHint;
   try {
-    const existing = await fs4.readFile(tsconfigPath, "utf8");
+    const existing = await fs5.readFile(tsconfigPath, "utf8");
     if (existing === MINIMAL_TSCONFIG) tsconfig = "unchanged";
     else {
       tsconfig = "manual-paths";
       pathsHint = TSCONFIG_PATHS_HINT;
     }
   } catch {
-    await fs4.writeFile(tsconfigPath, MINIMAL_TSCONFIG, "utf8");
+    await fs5.writeFile(tsconfigPath, MINIMAL_TSCONFIG, "utf8");
     tsconfig = "created";
   }
   return { action, tsconfig, pathsHint };
@@ -635,9 +1136,9 @@ async function syncSkills(options) {
   const version = options.version ?? await readDevkitVersion(sourceRoot);
   const summaries = [];
   for (const target of targets) {
-    if (target === "cursor") summaries.push(await syncToDir("cursor", sourceRoot, path4.join(options.cwd, ".cursor", "skills"), version));
-    else if (target === "claude") summaries.push(await syncToDir("claude", sourceRoot, path4.join(options.cwd, ".claude", "skills"), version));
-    else if (target === "qoder") summaries.push(await syncToDir("qoder", sourceRoot, path4.join(options.cwd, ".qoder", "skills"), version));
+    if (target === "cursor") summaries.push(await syncToDir("cursor", sourceRoot, path6.join(options.cwd, ".cursor", "skills"), version));
+    else if (target === "claude") summaries.push(await syncToDir("claude", sourceRoot, path6.join(options.cwd, ".claude", "skills"), version));
+    else if (target === "qoder") summaries.push(await syncToDir("qoder", sourceRoot, path6.join(options.cwd, ".qoder", "skills"), version));
     else summaries.push(await syncToCodex(sourceRoot, options.cwd, version));
   }
   const types = await syncRuntimeTypes(options.cwd, options.typesSourceFile ?? resolveRuntimeTypesSourceFile());
@@ -646,11 +1147,33 @@ async function syncSkills(options) {
 
 // src/bundle.ts
 import * as esbuild from "esbuild-wasm";
-import { promises as fs5 } from "fs";
-import path5 from "path";
+import { promises as fs6 } from "fs";
+import path7 from "path";
+
+// src/apps.ts
+var PORTABLE_RUNTIME_EXPORTS = [
+  "THREE",
+  "RuntimeEngine",
+  "SceneManager",
+  "LoadSceneMode",
+  "convertObjToComponentJson"
+];
+function portableRuntimeWarning(names) {
+  const extra = [...new Set(names)].filter(
+    (n) => n !== "*" && !PORTABLE_RUNTIME_EXPORTS.includes(n)
+  );
+  const ns = [...names].includes("*");
+  if (!ns && extra.length === 0) return void 0;
+  const detail = ns ? "namespace import *" : extra.sort().join(", ");
+  return `\u68C0\u6D4B\u5230 @easytwin/runtime \u5BFC\u51FA ${detail} \u4E0D\u5728\u5728\u7EBF\u7F16\u8BD1\u767D\u540D\u5355(${PORTABLE_RUNTIME_EXPORTS.join(", ")})\u5185\u3002\u672C\u5730\u9884\u89C8\u53EF\u7528,\u4E0A\u4F20\u5230\u5728\u7EBF TwinApp \u53EF\u80FD\u7F16\u4E0D\u8FC7\u3002`;
+}
+
+// src/bundle.ts
 var USER_ENTRY = "src/main.ts";
 var DEFAULT_BUNDLE_OUT = "dist/main.js";
 var RUNTIME_MODULE = "@easytwin/runtime";
+var APPS_MODULE = "@easytwin/apps";
+var ALLOWED_BARE_MODULES = /* @__PURE__ */ new Set([RUNTIME_MODULE, APPS_MODULE]);
 var BundleError = class extends Error {
   constructor(message) {
     super(message);
@@ -658,7 +1181,7 @@ var BundleError = class extends Error {
   }
 };
 function isRelativeOrAbsolute(spec) {
-  return spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || path5.isAbsolute(spec);
+  return spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || path7.isAbsolute(spec);
 }
 function whitelistPlugin() {
   return {
@@ -667,11 +1190,11 @@ function whitelistPlugin() {
       build2.onResolve({ filter: /.*/ }, (args) => {
         if (args.kind === "entry-point") return void 0;
         if (isRelativeOrAbsolute(args.path)) return void 0;
-        if (args.path === RUNTIME_MODULE) return { path: args.path, external: true };
+        if (ALLOWED_BARE_MODULES.has(args.path)) return { path: args.path, external: true };
         return {
           errors: [
             {
-              text: `\u68C0\u6D4B\u5230\u5916\u90E8\u4F9D\u8D56 ${args.path},\u7528\u6237\u4EE3\u7801\u53EA\u80FD\u4F9D\u8D56 @easytwin/runtime\u3002\u4E0D\u8981 npm install,\u7C7B\u578B\u7531 easytwin skills sync \u5206\u53D1,\u8FD0\u884C\u8D70\u9884\u89C8\u9875 Run \u6216 easytwin bundle\u3002`
+              text: `\u68C0\u6D4B\u5230\u5916\u90E8\u4F9D\u8D56 ${args.path},\u7528\u6237\u4EE3\u7801\u53EA\u80FD\u4F9D\u8D56 @easytwin/runtime \u4E0E @easytwin/apps\u3002\u4E0D\u8981 npm install,\u7C7B\u578B\u7531 easytwin skills sync \u5206\u53D1,\u8FD0\u884C\u8D70\u9884\u89C8\u9875 Run \u6216 easytwin bundle\u3002`
             }
           ]
         };
@@ -685,14 +1208,29 @@ function formatEsbuildMessages(messages) {
     return `${loc}${m.text}`;
   }).join("\n");
 }
-async function bundleUserCode(options) {
-  const cwd = path5.resolve(options.cwd);
-  const entry = path5.join(cwd, USER_ENTRY);
+function collectBundledRuntimeExports(code) {
+  const names = [];
+  if (/import\s+\*\s+as\s+[\w$]+\s+from\s*["']@easytwin\/runtime["']/.test(code)) names.push("*");
+  const named = /import\s*\{([^}]+)\}\s*from\s*["']@easytwin\/runtime["']/g;
+  for (const match of code.matchAll(named)) {
+    const body = match[1] ?? "";
+    for (const part of body.split(",")) {
+      const token = part.replace(/\btype\b/g, "").trim();
+      if (!token) continue;
+      const id = token.split(/\s+as\s+/)[0]?.trim();
+      if (id) names.push(id);
+    }
+  }
+  return names;
+}
+async function bundleWorkspaceModule(options) {
+  const cwd = path7.resolve(options.cwd);
+  const entry = path7.isAbsolute(options.entry) ? options.entry : path7.join(cwd, options.entry);
   try {
-    await fs5.access(entry);
+    await fs6.access(entry);
   } catch {
     throw new BundleError(
-      `\u672A\u627E\u5230\u5165\u53E3\u6587\u4EF6 ${entry}\u3002\u8BF7\u5728\u5DE5\u4F5C\u533A\u521B\u5EFA src/main.ts,\u5E76 \`export default async function main(ctx)\`\u3002`
+      options.missingEntryMessage ?? `\u672A\u627E\u5230\u5165\u53E3\u6587\u4EF6 ${entry}\u3002`
     );
   }
   let result;
@@ -723,21 +1261,1167 @@ async function bundleUserCode(options) {
   if (!file) throw new BundleError("\u6253\u5305\u672A\u4EA7\u51FA\u6587\u4EF6");
   const code = file.text;
   const warnings = result.warnings.map((w) => formatEsbuildMessages([w]));
+  const portable = portableRuntimeWarning(collectBundledRuntimeExports(code));
+  if (portable) warnings.push(portable);
   if (options.outFile) {
-    const outFile = path5.isAbsolute(options.outFile) ? options.outFile : path5.join(cwd, options.outFile);
-    await fs5.mkdir(path5.dirname(outFile), { recursive: true });
-    await fs5.writeFile(outFile, code, "utf8");
+    const outFile = path7.isAbsolute(options.outFile) ? options.outFile : path7.join(cwd, options.outFile);
+    await fs6.mkdir(path7.dirname(outFile), { recursive: true });
+    await fs6.writeFile(outFile, code, "utf8");
   }
   return { code, warnings };
 }
+async function bundleUserCode(options) {
+  const cwd = path7.resolve(options.cwd);
+  const entry = path7.join(cwd, USER_ENTRY);
+  return bundleWorkspaceModule({
+    cwd: options.cwd,
+    entry: USER_ENTRY,
+    outFile: options.outFile,
+    missingEntryMessage: `\u672A\u627E\u5230\u5165\u53E3\u6587\u4EF6 ${entry}\u3002\u8BF7\u5728\u5DE5\u4F5C\u533A\u521B\u5EFA src/main.ts,\u5E76 \`export default\` TwinApp \u5B50\u7C7B\u6216 defineApp({...})\u3002`
+  });
+}
 async function typesMissingHint(cwd) {
   try {
-    await fs5.access(path5.join(cwd, ".easytwin", "types", "index.d.ts"));
+    await fs6.access(path7.join(cwd, ".easytwin", "types", "index.d.ts"));
     return void 0;
   } catch {
     return "\u672A\u627E\u5230 .easytwin/types,\u8FD0\u884C `easytwin skills sync` \u4EE5\u5206\u53D1 @easytwin/runtime \u7C7B\u578B\u58F0\u660E\u3002";
   }
 }
+var SOURCEMAP_RE = /sourceMappingURL=data:application\/json(?:;charset=[^;]+)?;base64,([A-Za-z0-9+/]+=*)/;
+var VLQ_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function decodeVLQValues(str) {
+  const values = [];
+  let i = 0;
+  while (i < str.length) {
+    let result = 0;
+    let shift = 0;
+    let continuation = true;
+    while (continuation) {
+      if (i >= str.length) return values;
+      const digit = VLQ_CHARS.indexOf(str[i++] ?? "");
+      if (digit < 0) return values;
+      continuation = (digit & 32) !== 0;
+      result += (digit & 31) << shift;
+      shift += 5;
+    }
+    values.push(result & 1 ? -(result >> 1) : result >> 1);
+  }
+  return values;
+}
+function decodeMappings(map) {
+  const sources = map.sources ?? [];
+  const lines = (map.mappings ?? "").split(";");
+  let sourceIndex = 0;
+  let originalLine = 0;
+  let originalColumn = 0;
+  const decoded = [];
+  for (const line of lines) {
+    let generatedColumn = 0;
+    const segs = [];
+    if (line) {
+      for (const raw of line.split(",")) {
+        if (!raw) continue;
+        const nums = decodeVLQValues(raw);
+        if (nums[0] === void 0) continue;
+        generatedColumn += nums[0];
+        if (nums.length >= 4) {
+          sourceIndex += nums[1] ?? 0;
+          originalLine += nums[2] ?? 0;
+          originalColumn += nums[3] ?? 0;
+          segs.push({
+            generatedColumn,
+            source: sources[sourceIndex] ?? USER_ENTRY,
+            originalLine,
+            originalColumn
+          });
+        }
+      }
+    }
+    decoded.push(segs);
+  }
+  return decoded;
+}
+function originalPositionFor(map, line, column) {
+  const decoded = decodeMappings(map);
+  for (let i = line - 1; i >= 0; i--) {
+    const segs = decoded[i];
+    if (!segs || segs.length === 0) continue;
+    const col = i === line - 1 ? column - 1 : Number.POSITIVE_INFINITY;
+    let best = segs[0];
+    for (const seg of segs) {
+      if (seg.generatedColumn <= col) best = seg;
+      else break;
+    }
+    if (!best) continue;
+    return { source: best.source, line: best.originalLine + 1, column: best.originalColumn };
+  }
+  return void 0;
+}
+function extractInlineSourceMap(code) {
+  const m = code.match(SOURCEMAP_RE);
+  if (!m?.[1]) return void 0;
+  try {
+    return JSON.parse(Buffer.from(m[1], "base64").toString("utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function remapErrorStack(stack, bundledCode) {
+  const map = extractInlineSourceMap(bundledCode);
+  if (!map?.mappings) return stack;
+  return stack.replace(/(blob:[^\s)]+?):(\d+):(\d+)/g, (full, _url, line, col) => {
+    const orig = originalPositionFor(map, Number(line), Number(col));
+    if (!orig) return full;
+    return `${orig.source}:${orig.line}:${orig.column}`;
+  });
+}
+
+// src/previewServer.ts
+import { existsSync as existsSync2 } from "fs";
+import { promises as fs8 } from "fs";
+import http2 from "http";
+import path9 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+
+// src/previewHtml.ts
+function escapeJsonForScript(json) {
+  return json.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+var PREVIEW_STYLE = `
+  html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; background: #111; }
+  body { display: flex; flex-direction: column; font: 13px/1.5 -apple-system, "Segoe UI", sans-serif; color: #f3f3f3; }
+  #stage { position: relative; flex: 1; min-height: 0; }
+  #twin-root { position: relative; width: 100%; height: 100%; overflow: hidden; background: #111; }
+  #twin-root canvas { display: block; }
+  #status {
+    position: absolute; inset: 0; z-index: 1; display: flex; align-items: center; justify-content: center;
+    padding: 24px; text-align: center; pointer-events: none; white-space: pre-wrap; word-break: break-word;
+  }
+  #status.error { pointer-events: auto; color: #ffb4b4; background: rgba(17,17,17,.85); }
+  /* \u4F5C\u8005\u6837\u5F0F display:flex \u4F1A\u8986\u76D6 UA \u7684 [hidden]{display:none},\u5FC5\u987B\u663E\u5F0F\u58F0\u660E\u624D\u80FD\u9690\u85CF\u52A0\u8F7D\u6587\u6848 */
+  #status[hidden] { display: none; }
+  #mock-banner {
+    position: absolute; top: 0; left: 0; right: 0; z-index: 2;
+    padding: 6px 12px; background: rgba(255,248,225,.92); color: #1f1f1f;
+    border-bottom: 1px solid #f0c36d; pointer-events: none;
+  }
+  #debug-log {
+    display: none; position: absolute; left: 8px; right: 8px; bottom: 8px; z-index: 4;
+    max-height: 42%; overflow: auto; padding: 8px 10px; border-radius: 6px;
+    background: rgba(0,0,0,.88); color: #c8e1c8; font: 11px/1.45 ui-monospace, Consolas, monospace;
+    white-space: pre-wrap; word-break: break-all; pointer-events: auto;
+  }
+  #debug-log.open { display: block; }
+  #run-bar {
+    flex: 0 0 auto; display: flex; align-items: center; gap: 8px;
+    padding: 6px 10px; background: rgba(20,20,20,.94); border-top: 1px solid #333; z-index: 5;
+  }
+  #run-bar button {
+    cursor: pointer; border: 1px solid #555; background: #222; color: #eee;
+    padding: 4px 10px; border-radius: 4px; font: 12px/1.3 inherit;
+  }
+  #run-bar button:disabled { opacity: .55; cursor: default; }
+  #btn-run { background: #0e639c; border-color: #1177bb; font-weight: 600; }
+  #run-status { color: #bbb; min-width: 4em; }
+  #run-bar .spacer { flex: 1; }
+  #test-panel {
+    flex: 0 0 auto; display: flex; align-items: flex-start; gap: 8px; flex-wrap: wrap;
+    padding: 6px 10px; background: rgba(18,18,18,.96); border-top: 1px solid #333; z-index: 5;
+    max-height: 30%; overflow: auto;
+  }
+  #test-panel .test-label { color: #888; padding-top: 4px; flex: 0 0 auto; }
+  #test-list { display: flex; flex-wrap: wrap; gap: 6px 8px; align-items: center; flex: 1; min-width: 0; }
+  #test-panel .test-file { width: 100%; color: #8a8a8a; font-size: 11px; }
+  #test-panel .test-empty { color: #777; }
+  #test-panel .test-item { display: inline-flex; align-items: center; gap: 4px; }
+  #test-panel input.test-input {
+    width: 9em; background: #1a1a1a; border: 1px solid #555; color: #eee;
+    padding: 3px 6px; border-radius: 4px; font: 12px inherit;
+  }
+  #test-panel button {
+    cursor: pointer; border: 1px solid #555; background: #222; color: #eee;
+    padding: 4px 10px; border-radius: 4px; font: 12px/1.3 inherit;
+  }
+  #test-panel button:disabled { opacity: .55; cursor: default; }
+`;
+var RENDER_SCRIPT = `
+  var statusEl = document.getElementById("status");
+  var logEl = document.getElementById("debug-log");
+  var engine = null;
+  var runtime = null;
+  var sceneJson = null;
+  var host = null;
+  var running = false;
+  var runningTest = false;
+  var testsReady = false;
+  var hostKind = __HOST_KIND__;
+  var vscodeApi = null;
+  if (hostKind === "vscode") {
+    try { vscodeApi = acquireVsCodeApi(); } catch (e) { /* \u975E vscode \u5BBF\u4E3B */ }
+  }
+  var pending = {};
+  var seq = 0;
+  var origFetch = window.fetch.bind(window);
+  function now() { return new Date().toISOString().slice(11, 23); }
+  function log(line) {
+    var text = "[" + now() + "] " + line;
+    if (logEl) {
+      logEl.textContent = (logEl.textContent ? logEl.textContent + "\\n" : "") + text;
+      logEl.scrollTop = logEl.scrollHeight;
+    }
+    if (vscodeApi) vscodeApi.postMessage({ type: "log", line: text });
+    console.log("[EasyTwin]", line);
+  }
+  function nextId() { return String(++seq); }
+  function handleHostMessage(msg) {
+    if (!msg) return;
+    if (msg.type === "proxy-fetch-result") {
+      var p = pending[msg.id];
+      if (!p) return;
+      delete pending[msg.id];
+      if (msg.error) p.reject(new Error(msg.error));
+      else p.resolve(msg);
+      return;
+    }
+    if (msg.type === "bundle-result") {
+      if (!msg.ok) {
+        log("\u7F16\u8BD1\u5931\u8D25 " + (msg.error || ""));
+        setRunStatus("\u7F16\u8BD1\u5931\u8D25");
+        setRunBusy(false);
+        if (logEl) logEl.classList.add("open");
+        return;
+      }
+      for (var i = 0; i < (msg.warnings || []).length; i++) log("\u7F16\u8BD1\u8B66\u544A " + msg.warnings[i]);
+      runUserCode(msg.code);
+      return;
+    }
+    if (msg.type === "read-asset-result") {
+      var ap = pending[msg.id];
+      if (!ap) return;
+      delete pending[msg.id];
+      if (msg.error) ap.reject(new Error(msg.error));
+      else ap.resolve(msg.text);
+      return;
+    }
+    if (msg.type === "run-error-mapped") {
+      log("\u6E90\u7801\u6620\u5C04\\n" + (msg.stack || ""));
+      return;
+    }
+    if (msg.type === "tests") {
+      renderTests(msg.tests || []);
+      return;
+    }
+    if (msg.type === "test-bundle") {
+      if (!msg.ok) {
+        log("\u6D4B\u8BD5\u7F16\u8BD1\u5931\u8D25 " + (msg.error || ""));
+        setRunStatus("\u6D4B\u8BD5\u5931\u8D25");
+        runningTest = false;
+        setRunBusy(running);
+        if (logEl) logEl.classList.add("open");
+        return;
+      }
+      for (var ti = 0; ti < (msg.warnings || []).length; ti++) log("\u6D4B\u8BD5\u8B66\u544A " + msg.warnings[ti]);
+      runExportedTest(msg.code, msg.exportName, msg.input, msg.hasInput).then(function () {
+        log("\u6D4B\u8BD5\u5B8C\u6210 " + msg.exportName);
+        setRunStatus("\u6D4B\u8BD5\u5B8C\u6210");
+      }).catch(function (err) {
+        log("\u6D4B\u8BD5\u5931\u8D25 " + formatError(err));
+        setRunStatus("\u6D4B\u8BD5\u5931\u8D25");
+        if (logEl) logEl.classList.add("open");
+        postToHost({ type: "run-error", stack: err && err.stack ? err.stack : String(err) });
+      }).then(function () {
+        runningTest = false;
+        setRunBusy(running);
+      });
+    }
+  }
+  function httpJson(url, init) {
+    return origFetch(url, init).then(function (res) {
+      return res.json().then(function (body) {
+        if (!res.ok) throw new Error((body && body.error) || ("HTTP " + res.status));
+        return body;
+      });
+    });
+  }
+  function postToHost(msg) {
+    if (vscodeApi) {
+      vscodeApi.postMessage(msg);
+      return;
+    }
+    if (msg.type === "log" || msg.type === "open-devtools" || msg.type === "show-output") return;
+    if (msg.type === "run") {
+      httpJson("/api/bundle", { method: "POST" }).then(function (body) {
+        handleHostMessage({ type: "bundle-result", ok: body.ok !== false, code: body.code, warnings: body.warnings, error: body.error });
+      }).catch(function (err) {
+        handleHostMessage({ type: "bundle-result", ok: false, error: formatError(err) });
+      });
+      return;
+    }
+    if (msg.type === "run-error") {
+      httpJson("/api/remap-error", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ stack: msg.stack }) }).then(function (body) {
+        handleHostMessage({ type: "run-error-mapped", stack: body.stack || msg.stack });
+      }).catch(function (err) {
+        log("\u6E90\u7801\u6620\u5C04\u5931\u8D25 " + formatError(err));
+      });
+      return;
+    }
+    if (msg.type === "read-asset") {
+      httpJson("/api/assets?path=" + encodeURIComponent(msg.path)).then(function (body) {
+        handleHostMessage({ type: "read-asset-result", id: msg.id, text: body.text, error: body.error });
+      }).catch(function (err) {
+        handleHostMessage({ type: "read-asset-result", id: msg.id, error: formatError(err) });
+      });
+      return;
+    }
+    if (msg.type === "list-tests") {
+      httpJson("/api/tests").then(function (body) {
+        handleHostMessage({ type: "tests", tests: body.tests || [] });
+      }).catch(function (err) {
+        log("\u5237\u65B0\u6D4B\u8BD5\u5931\u8D25 " + formatError(err));
+      });
+      return;
+    }
+    if (msg.type === "run-test") {
+      httpJson("/api/test-bundle", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id: msg.id, input: msg.input }) }).then(function (body) {
+        handleHostMessage(Object.assign({ type: "test-bundle" }, body));
+      }).catch(function (err) {
+        handleHostMessage({ type: "test-bundle", ok: false, error: formatError(err) });
+      });
+    }
+  }
+  function showStatus(text, isError) {
+    if (!statusEl) return;
+    statusEl.textContent = text;
+    statusEl.className = isError ? "error" : "";
+    statusEl.hidden = false;
+    if (isError && logEl) logEl.classList.add("open");
+  }
+  function hideStatus() { if (statusEl) statusEl.hidden = true; }
+  function formatError(err) {
+    var msg = err && err.message ? err.message : String(err);
+    var stack = err && err.stack ? "\\n" + err.stack : "";
+    return msg + stack;
+  }
+  window.addEventListener("message", function (ev) {
+    handleHostMessage(ev.data);
+  });
+  function b64ToBuf(b64) {
+    var bin = atob(b64);
+    var bytes = new Uint8Array(bin.length);
+    for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return bytes.buffer;
+  }
+  function proxyFetch(url, method) {
+    return new Promise(function (resolve, reject) {
+      if (!vscodeApi) {
+        reject(new Error("\u65E0 vscode API,\u65E0\u6CD5\u4EE3\u7406 " + url));
+        return;
+      }
+      var id = nextId();
+      pending[id] = { resolve: resolve, reject: reject };
+      vscodeApi.postMessage({ type: "proxy-fetch", id: id, url: url, method: method || "GET" });
+    }).then(function (msg) {
+      var buf = msg.bodyBase64 ? b64ToBuf(msg.bodyBase64) : new ArrayBuffer(0);
+      return new Response(buf, {
+        status: msg.status || 0,
+        statusText: msg.statusText || "",
+        headers: msg.headers || {}
+      });
+    });
+  }
+  function isHttpUrl(url) {
+    return typeof url === "string" && (url.indexOf("http://") === 0 || url.indexOf("https://") === 0);
+  }
+  function isPlainHttp(url) {
+    return typeof url === "string" && url.indexOf("http://") === 0;
+  }
+  if (hostKind === "vscode") {
+    window.fetch = function (input, init) {
+      var url = typeof input === "string" ? input : (input && input.url);
+      log("fetch " + url);
+      if (isPlainHttp(url)) {
+        return proxyFetch(url, init && init.method).then(function (res) {
+          log("proxy " + res.status + " " + url + " type=" + (res.headers.get("content-type") || ""));
+          return res;
+        });
+      }
+      return origFetch(input, init).catch(function (err) {
+        log("direct fetch \u5931\u8D25,\u6539\u8D70\u4EE3\u7406: " + url + " :: " + formatError(err));
+        if (!isHttpUrl(url)) throw err;
+        return proxyFetch(url, init && init.method).then(function (res) {
+          log("proxy " + res.status + " " + url + " type=" + (res.headers.get("content-type") || ""));
+          return res;
+        });
+      });
+    };
+    var origOpen = XMLHttpRequest.prototype.open;
+    var origSend = XMLHttpRequest.prototype.send;
+    XMLHttpRequest.prototype.open = function (method, url) {
+      this.__etMethod = method;
+      this.__etUrl = String(url);
+      return origOpen.apply(this, arguments);
+    };
+    XMLHttpRequest.prototype.send = function (body) {
+      var xhr = this;
+      var url = xhr.__etUrl;
+      if (!isPlainHttp(url)) return origSend.call(this, body);
+      log("xhr proxy " + xhr.__etMethod + " " + url);
+      proxyFetch(url, xhr.__etMethod).then(function (res) {
+        return res.arrayBuffer().then(function (buf) {
+          var text = "";
+          try { text = new TextDecoder().decode(buf); } catch (e) { /* binary */ }
+          Object.defineProperty(xhr, "status", { configurable: true, value: res.status });
+          Object.defineProperty(xhr, "statusText", { configurable: true, value: res.statusText });
+          Object.defineProperty(xhr, "responseURL", { configurable: true, value: url });
+          Object.defineProperty(xhr, "readyState", { configurable: true, value: 4 });
+          var rt = xhr.responseType;
+          var response = buf;
+          if (rt === "" || rt === "text") response = text;
+          else if (rt === "json") { try { response = JSON.parse(text); } catch (e) { response = null; } }
+          Object.defineProperty(xhr, "response", { configurable: true, value: response });
+          Object.defineProperty(xhr, "responseText", { configurable: true, value: text });
+          if (typeof xhr.onload === "function") xhr.onload(new ProgressEvent("load"));
+          xhr.dispatchEvent(new Event("load"));
+          xhr.dispatchEvent(new Event("loadend"));
+        });
+      }).catch(function (err) {
+        log("xhr \u5931\u8D25 " + url + " :: " + formatError(err));
+        if (typeof xhr.onerror === "function") xhr.onerror(new ProgressEvent("error"));
+        xhr.dispatchEvent(new Event("error"));
+        xhr.dispatchEvent(new Event("loadend"));
+      });
+    };
+    function patchHttpSrc(proto, prop) {
+      var desc = Object.getOwnPropertyDescriptor(proto, prop);
+      if (!desc || typeof desc.set !== "function") return;
+      Object.defineProperty(proto, prop, {
+        configurable: true,
+        enumerable: desc.enumerable,
+        get: function () { return desc.get.call(this); },
+        set: function (value) {
+          var el = this;
+          var url = String(value);
+          if (!isPlainHttp(url)) { desc.set.call(el, value); return; }
+          log("media proxy " + url);
+          proxyFetch(url).then(function (res) { return res.blob(); }).then(function (blob) {
+            desc.set.call(el, URL.createObjectURL(blob));
+          }).catch(function (err) {
+            log("media proxy \u5931\u8D25 " + url + " :: " + formatError(err));
+            try { el.dispatchEvent(new Event("error")); } catch (e) { /* \u65E0\u76D1\u542C\u65F6\u5FFD\u7565 */ }
+          });
+        }
+      });
+    }
+    patchHttpSrc(HTMLImageElement.prototype, "src");
+    patchHttpSrc(HTMLMediaElement.prototype, "src");
+  }
+  document.getElementById("btn-debug").addEventListener("click", function () {
+    if (logEl) logEl.classList.toggle("open");
+  });
+  var btnDevtools = document.getElementById("btn-devtools");
+  var btnOutput = document.getElementById("btn-output");
+  if (hostKind === "http") {
+    if (btnDevtools) btnDevtools.hidden = true;
+    if (btnOutput) btnOutput.hidden = true;
+  }
+  if (btnDevtools) btnDevtools.addEventListener("click", function () {
+    postToHost({ type: "open-devtools" });
+  });
+  if (btnOutput) btnOutput.addEventListener("click", function () {
+    postToHost({ type: "show-output" });
+  });
+  function setRunStatus(text) {
+    var el = document.getElementById("run-status");
+    if (el) el.textContent = text;
+  }
+  function setRunBusy(busy) {
+    running = busy;
+    var btn = document.getElementById("btn-run");
+    if (btn) btn.disabled = !!busy || runningTest;
+    syncTestControls();
+  }
+  function syncTestControls() {
+    var panel = document.getElementById("test-panel");
+    if (!panel) return;
+    var disabled = !testsReady || running || runningTest;
+    var nodes = panel.querySelectorAll("button.test-run, input.test-input");
+    for (var i = 0; i < nodes.length; i++) nodes[i].disabled = disabled;
+  }
+  function renderTests(tests) {
+    var list = document.getElementById("test-list");
+    if (!list) return;
+    list.textContent = "";
+    if (!tests || !tests.length) {
+      var empty = document.createElement("span");
+      empty.className = "test-empty";
+      empty.textContent = "\u6CA1\u6709 *.spec.ts \u5BFC\u51FA";
+      list.appendChild(empty);
+      return;
+    }
+    var groups = {};
+    var order = [];
+    for (var i = 0; i < tests.length; i++) {
+      var t = tests[i];
+      if (!groups[t.file]) { groups[t.file] = []; order.push(t.file); }
+      groups[t.file].push(t);
+    }
+    for (var g = 0; g < order.length; g++) {
+      var file = order[g];
+      var heading = document.createElement("span");
+      heading.className = "test-file";
+      heading.textContent = file;
+      list.appendChild(heading);
+      var items = groups[file];
+      for (var j = 0; j < items.length; j++) list.appendChild(makeTestControl(items[j]));
+    }
+    syncTestControls();
+  }
+  function makeTestControl(t) {
+    var wrap = document.createElement("span");
+    wrap.className = "test-item";
+    if (t.hasInput) {
+      var input = document.createElement("input");
+      input.type = "text";
+      input.className = "test-input";
+      input.placeholder = t.inputName || "input";
+      var btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "test-run";
+      btn.textContent = t.name;
+      btn.addEventListener("click", function () { requestRunTest(t.id, input.value); });
+      input.addEventListener("keydown", function (ev) {
+        if (ev.key === "Enter") requestRunTest(t.id, input.value);
+      });
+      wrap.appendChild(input);
+      wrap.appendChild(btn);
+    } else {
+      var only = document.createElement("button");
+      only.type = "button";
+      only.className = "test-run";
+      only.textContent = t.name;
+      only.addEventListener("click", function () { requestRunTest(t.id); });
+      wrap.appendChild(only);
+    }
+    return wrap;
+  }
+  function requestRunTest(id, input) {
+    if (!testsReady || running || runningTest) return;
+    if (!host) { log("\u573A\u666F\u5C1A\u672A\u52A0\u8F7D\u5B8C\u6210,\u65E0\u6CD5\u8FD0\u884C\u6D4B\u8BD5"); return; }
+    runningTest = true;
+    setRunBusy(running);
+    setRunStatus("\u6D4B\u8BD5\u7F16\u8BD1\u4E2D\u2026");
+    log("\u6D4B\u8BD5:\u7F16\u8BD1 " + id);
+    postToHost({ type: "run-test", id: id, input: input });
+  }
+  async function runExportedTest(code, exportName, input, hasInput) {
+    var blob = new Blob([code], { type: "text/javascript" });
+    var url = URL.createObjectURL(blob);
+    try {
+      var mod = await import(url);
+      var fn = mod[exportName];
+      if (typeof fn !== "function") throw new Error("\u5BFC\u51FA " + exportName + " \u4E0D\u662F\u51FD\u6570");
+      if (!host) throw new Error("\u573A\u666F\u5C1A\u672A\u52A0\u8F7D\u5B8C\u6210,\u65E0\u6CD5\u8FD0\u884C\u6D4B\u8BD5");
+      var ctx = host.getTestContext();
+      var result = hasInput ? fn(ctx, input == null ? "" : input) : fn(ctx);
+      await Promise.resolve(result);
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  }
+  function applyRenderPatch() {
+    // runtime \u6E32\u67D3\u5206\u652F:\u7248\u672C <= 0.0.31 \u8D70\u666E\u901A/\u540E\u5904\u7406\u6E32\u67D3,\u7248\u672C > 0.0.31 \u8981\u6C42\u5B58\u5728 postprocessingComponent,
+    // \u5426\u5219\u6240\u6709\u5206\u652F\u90FD\u88AB\u8DF3\u8FC7(renderer.info.render.frame \u6052\u4E3A 0)\u5BFC\u81F4\u9ED1\u5C4F\u3002\u6B64\u5904\u6309 runtime \u8BED\u4E49\u515C\u5E95\u3002
+    var scene = engine && engine.mainScene;
+    if (
+      scene && scene.rootComponent && scene.rootComponent.version &&
+      !scene.postprocessingComponent &&
+      runtime.compareVersion && runtime.compareVersion(scene.rootComponent.version, "0.0.31") > 0
+    ) {
+      log("\u8865\u6E32\u67D3:\u573A\u666F\u7248\u672C " + scene.rootComponent.version + " \u65E0\u540E\u5904\u7406\u7EC4\u4EF6,runtime \u9AD8\u7248\u672C\u6E32\u67D3\u5206\u652F\u4E3A\u7A7A,\u6CE8\u518C\u6BCF\u5E27\u6E32\u67D3\u56DE\u8C03");
+      scene.registerRenderCallback(function () {
+        scene.renderer.render(scene.sceneObject, scene.camera.main);
+      });
+    }
+  }
+  async function loadHostScene(nextEngine, nextJson) {
+    engine = nextEngine;
+    var sceneManager = engine.getManager(runtime.SceneManager);
+    await sceneManager.loadScene(nextJson, runtime.RuntimeSceneMode.Publish, runtime.LoadSceneMode.Single);
+    applyRenderPatch();
+  }
+  function readAsset(relPath) {
+    return new Promise(function (resolve, reject) {
+      var id = nextId();
+      pending[id] = { resolve: resolve, reject: reject };
+      postToHost({ type: "read-asset", id: id, path: relPath });
+    });
+  }
+  async function runUserCode(code) {
+    setRunStatus("\u8FD0\u884C\u4E2D\u2026");
+    try {
+      if (!host) throw new Error("\u573A\u666F\u5C1A\u672A\u52A0\u8F7D\u5B8C\u6210,\u65E0\u6CD5 Run");
+      await host.run(code);
+      log("Run \u5B8C\u6210");
+      setRunStatus("\u8FD0\u884C\u4E2D");
+    } catch (err) {
+      log("Run \u5931\u8D25 " + formatError(err));
+      setRunStatus("\u5931\u8D25");
+      if (logEl) logEl.classList.add("open");
+      postToHost({ type: "run-error", stack: err && err.stack ? err.stack : String(err) });
+    } finally {
+      setRunBusy(false);
+    }
+  }
+  document.getElementById("btn-run").addEventListener("click", function () {
+    if (running || runningTest) return;
+    if (!engine) {
+      log("\u573A\u666F\u5C1A\u672A\u52A0\u8F7D\u5B8C\u6210,\u65E0\u6CD5 Run");
+      return;
+    }
+    setRunBusy(true);
+    setRunStatus("\u7F16\u8BD1\u4E2D\u2026");
+    log("Run:\u8BF7\u6C42\u7F16\u8BD1 src/main.ts");
+    postToHost({ type: "run" });
+  });
+  document.getElementById("btn-refresh-tests").addEventListener("click", function () {
+    log("\u5237\u65B0\u6D4B\u8BD5\u5217\u8868");
+    postToHost({ type: "list-tests" });
+  });
+  function readEmbeddedTests() {
+    var el = document.getElementById("workspace-tests");
+    if (!el || !el.textContent) return [];
+    try { return JSON.parse(el.textContent); } catch (e) { return []; }
+  }
+  renderTests(readEmbeddedTests());
+  function normalizeHierarchyConfig(vo) {
+    var objs = vo && vo.objs ? vo.objs : [];
+    for (var i = 0; i < objs.length; i++) {
+      var hc = objs[i].hierarchyConfig || {};
+      if (typeof hc.active !== "boolean") {
+        hc.active = hc.inActive === true ? false : hc.visible !== false;
+      }
+      if (typeof hc.lock !== "boolean") hc.lock = false;
+      if (typeof hc.collapsed !== "boolean") hc.collapsed = !!hc.isCollapsed;
+      objs[i].hierarchyConfig = hc;
+    }
+    return vo;
+  }
+  function toSceneJson(runtime, raw) {
+    var vo = raw && raw.payload && (raw.payload.objs || raw.payload.sceneComponent) ? raw.payload : raw;
+    if (vo && vo.sceneComponent) {
+      return {
+        id: vo.id || "preview",
+        name: vo.name || "\u573A\u666F\u9884\u89C8",
+        sceneComponent: vo.sceneComponent
+      };
+    }
+    vo = normalizeHierarchyConfig(vo);
+    var sceneEntity = (vo.objs || []).find(function (o) { return o && o.type === "Scene"; });
+    var rootObj = sceneEntity || (vo.objs && vo.objs[0] ? vo.objs[0] : null);
+    return {
+      id: rootObj && rootObj.sceneId ? rootObj.sceneId : "preview",
+      name: rootObj && rootObj.name ? rootObj.name : "\u573A\u666F\u9884\u89C8",
+      sceneComponent: runtime.convertObjToComponentJson(vo)
+    };
+  }
+  try {
+    showStatus("\u6B63\u5728\u52A0\u8F7D\u4E09\u7EF4\u573A\u666F\u2026");
+    log("runtimeUri=" + __RUNTIME_URI__);
+    log("ossUrl(\u8D44\u4EA7\u6839)=" + __BASE_OSS_URL__ + " (\u7F3A\u7701\u5B98\u65B9 OSS,HTTP \u8D70\u6269\u5C55\u5BBF\u4E3B\u4EE3\u7406)");
+    log("1/4 import twin-runtime / TwinApp host");
+    runtime = await import("@easytwin/runtime");
+    var hostMod = await import(__HOST_URI__);
+    log("2/4 parse scene JSON");
+    var sceneVo = JSON.parse(document.getElementById("scene-data").textContent);
+    sceneJson = toSceneJson(runtime, sceneVo);
+    log("scene id=" + sceneJson.id + " name=" + sceneJson.name);
+    log("3/4 RuntimeEngine.create (webp/draco/basis/component script \u6309 ossUrl/easytwin/system/libs/ \u4E0E components/custom/ \u52A0\u8F7D)");
+    host = new hostMod.TwinAppPreviewHost({
+      runtime: runtime,
+      containerId: "twin-root",
+      ossUrl: __BASE_OSS_URL__,
+      appId: __APP_ID__,
+      sceneId: sceneJson.id,
+      sceneJson: sceneJson,
+      customComponentDeps: {
+        "@easytwin/runtime": runtime,
+        "@easytwin/runtime-frontend": { EasyVIcon: {}, MobxReactLite: { observer: function (c) { return c; } } },
+        react: { createElement: function () { return null; }, Fragment: "div" }
+      },
+      loadScene: loadHostScene,
+      readAsset: readAsset,
+      log: log
+    });
+    await host.boot();
+    engine = host.getEngine();
+    log("4/4 loadScene");
+    log("\u5B8C\u6210");
+    hideStatus();
+    testsReady = true;
+    setRunBusy(false);
+  } catch (err) {
+    log("\u5931\u8D25 " + formatError(err));
+    showStatus("\u573A\u666F\u6E32\u67D3\u5931\u8D25: " + (err && err.message ? err.message : String(err)) + "\\n(\u70B9\u53F3\u4E0B\u89D2\u300C\u8C03\u8BD5\u65E5\u5FD7\u300D\u67E5\u770B\u6B65\u9AA4\u4E0E\u8BF7\u6C42 URL;\u300C\u5F00\u53D1\u8005\u5DE5\u5177\u300D\u6253\u5F00 webview DevTools)", true);
+  }
+  window.addEventListener("pagehide", function () {
+    if (host) { try { host.dispose(); } catch (e) { /* webview \u9500\u6BC1\u9636\u6BB5\u5BB9\u9519 */ } }
+  });
+`;
+function originOf(url) {
+  return new URL(url).origin;
+}
+function buildPreviewHtml(options) {
+  const { baseUrl, ossUrl, sceneJson, mock, runtimeUri, cspSource } = options;
+  const appsUri = options.appsUri ?? runtimeUri.replace(/twin-runtime\.js$/, "twin-apps.js");
+  const hostUri = options.hostUri ?? runtimeUri.replace(/twin-runtime\.js$/, "twin-app-host.js");
+  const appId = options.appId ?? "preview";
+  const hostKind = options.host ?? "vscode";
+  const apiOrigin = originOf(baseUrl);
+  const ossOrigin = originOf(ossUrl);
+  const runtimeOrigin = originOf(runtimeUri);
+  const resourceSrc = cspSource && cspSource.length > 0 ? cspSource : runtimeOrigin;
+  const renderScript = RENDER_SCRIPT.replaceAll("__RUNTIME_URI__", JSON.stringify(runtimeUri)).replaceAll("__HOST_URI__", JSON.stringify(hostUri)).replaceAll("__BASE_OSS_URL__", JSON.stringify(ossUrl)).replaceAll("__APP_ID__", JSON.stringify(appId)).replaceAll("__HOST_KIND__", JSON.stringify(hostKind));
+  const importMap = JSON.stringify({
+    imports: {
+      "@easytwin/runtime": runtimeUri,
+      "@easytwin/apps": appsUri
+    }
+  });
+  const testsJson = JSON.stringify(options.tests ?? []);
+  const mockBanner = mock ? `<div id="mock-banner"><b>\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F</b>:\u573A\u666F\u6570\u636E\u6765\u81EA\u672C\u5730 <code>scene.example.json</code>,\u672A\u8BF7\u6C42\u573A\u666F\u63A5\u53E3;\u4E09\u7EF4\u9884\u89C8\u8D70\u6253\u5305\u7684 twin runtime,\u7CFB\u7EDF\u5E93\u6309\u5B98\u65B9 OSS \u5728\u7EBF\u52A0\u8F7D\u3002</div>` : "";
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' blob: 'self' ${apiOrigin} ${ossOrigin} ${resourceSrc}; worker-src blob: data: 'self' ${apiOrigin} ${ossOrigin} ${resourceSrc}; child-src blob: data:; img-src ${apiOrigin} ${ossOrigin} ${resourceSrc} https: http: data: blob:; media-src ${apiOrigin} ${ossOrigin} https: http: data: blob:; connect-src 'self' ${apiOrigin} ${ossOrigin} ${resourceSrc} https: http: data: blob:; font-src ${apiOrigin} ${ossOrigin} https: data:;">
+<title>EasyTwin \u573A\u666F\u9884\u89C8${mock ? "(\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F)" : ""}</title>
+<style>${PREVIEW_STYLE}</style>
+<script type="importmap">${importMap}</script>
+</head>
+<body>
+<div id="stage">
+<div id="twin-root"></div>
+${mockBanner}
+<div id="status">\u6B63\u5728\u52A0\u8F7D\u4E09\u7EF4\u573A\u666F\u2026</div>
+<pre id="debug-log"></pre>
+</div>
+<div id="test-panel">
+  <span class="test-label">\u6D4B\u8BD5</span>
+  <div id="test-list"></div>
+  <button type="button" id="btn-refresh-tests">\u5237\u65B0\u6D4B\u8BD5</button>
+</div>
+<div id="run-bar">
+  <button type="button" id="btn-run">Run</button>
+  <span id="run-status">\u5C31\u7EEA</span>
+  <span class="spacer"></span>
+  <button type="button" id="btn-debug">\u8C03\u8BD5\u65E5\u5FD7</button>
+  <button type="button" id="btn-devtools">\u5F00\u53D1\u8005\u5DE5\u5177</button>
+  <button type="button" id="btn-output">\u8F93\u51FA\u901A\u9053</button>
+</div>
+<script id="scene-data" type="application/json">${escapeJsonForScript(sceneJson)}</script>
+<script id="workspace-tests" type="application/json">${escapeJsonForScript(testsJson)}</script>
+<script type="module">
+${renderScript}
+</script>
+</body>
+</html>`;
+}
+
+// src/workspaceTests.ts
+import { promises as fs7 } from "fs";
+import path8 from "path";
+var IDENT = "[A-Za-z_$][\\w$]*";
+var FUNCTION_EXPORT = new RegExp(
+  `export\\s+(?:async\\s+)?function\\s+(${IDENT})\\s*(?:<[^>]*>)?\\s*\\(`,
+  "g"
+);
+var CONST_EXPORT = new RegExp(
+  `export\\s+const\\s+(${IDENT})\\s*=\\s*(?:async\\s+)?(?:function\\s*)?(?:<[^>]*>)?\\s*\\(`,
+  "g"
+);
+function stripTsCommentsAndStringsKeepCode(source) {
+  let out = "";
+  let i = 0;
+  const n = source.length;
+  while (i < n) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < n && source[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i = Math.min(n, i + 2);
+      out += " ";
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") {
+      const quote = c;
+      out += " ";
+      i++;
+      while (i < n) {
+        const ch = source[i];
+        if (ch === "\\") {
+          i += 2;
+          continue;
+        }
+        if (ch === quote) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+function matchingClose(src, openIndex, open, close) {
+  let depth = 0;
+  let angle = 0;
+  let brace = 0;
+  for (let i = openIndex; i < src.length; i++) {
+    const c = src[i];
+    if (c === open) depth++;
+    else if (c === close) {
+      depth--;
+      if (depth === 0 && angle <= 0 && brace <= 0) return i;
+    } else if (c === "<") angle++;
+    else if (c === ">" && angle > 0) angle--;
+    else if (c === "{") brace++;
+    else if (c === "}" && brace > 0) brace--;
+  }
+  return -1;
+}
+function splitTopLevelParams(list) {
+  const params = [];
+  let current = "";
+  let paren = 0;
+  let angle = 0;
+  let brace = 0;
+  let bracket = 0;
+  for (const c of list) {
+    if (c === "(") paren++;
+    else if (c === ")") paren--;
+    else if (c === "<") angle++;
+    else if (c === ">" && angle > 0) angle--;
+    else if (c === "{") brace++;
+    else if (c === "}" && brace > 0) brace--;
+    else if (c === "[") bracket++;
+    else if (c === "]" && bracket > 0) bracket--;
+    if (c === "," && paren === 0 && angle === 0 && brace === 0 && bracket === 0) {
+      if (current.trim()) params.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += c;
+  }
+  if (current.trim()) params.push(current.trim());
+  return params;
+}
+function paramName(raw) {
+  let s = raw.trim();
+  if (!s || s === "this") return void 0;
+  if (s.startsWith("{") || s.startsWith("[")) return "input";
+  s = s.replace(/^\.\.\./, "");
+  const token = s.split(/[?:]/)[0]?.trim().split(/\s+/)[0];
+  if (!token || !new RegExp(`^${IDENT}$`).test(token)) return "input";
+  return token;
+}
+function collectFromPattern(source, pattern) {
+  const found = [];
+  pattern.lastIndex = 0;
+  let match;
+  while (match = pattern.exec(source)) {
+    const name = match[1];
+    if (!name) continue;
+    const openIndex = match.index + match[0].length - 1;
+    const closeIndex = matchingClose(source, openIndex, "(", ")");
+    if (closeIndex < 0) continue;
+    const params = splitTopLevelParams(source.slice(openIndex + 1, closeIndex));
+    const hasInput = params.length >= 2;
+    const second = hasInput ? paramName(params[1] ?? "") : void 0;
+    found.push({
+      id: name,
+      file: "",
+      name,
+      hasInput,
+      inputName: hasInput ? second : void 0
+    });
+  }
+  return found;
+}
+function parseExportedTestFunctions(source) {
+  const text = stripTsCommentsAndStringsKeepCode(source);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of [...collectFromPattern(text, FUNCTION_EXPORT), ...collectFromPattern(text, CONST_EXPORT)]) {
+    if (seen.has(item.name)) continue;
+    seen.add(item.name);
+    out.push({ name: item.name, hasInput: item.hasInput, inputName: item.inputName });
+  }
+  return out;
+}
+function workspaceTestId(file, name) {
+  return `${normalizePath(file)}:${name}`;
+}
+async function listWorkspaceTests(cwd) {
+  const root = path8.resolve(cwd);
+  let files;
+  try {
+    files = await collectFiles(root, isIgnoredWorkspacePath);
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") return [];
+    throw err;
+  }
+  const tests = [];
+  for (const file of files) {
+    if (!isWorkspaceSpecFile(file.relPath)) continue;
+    const posix = normalizePath(file.relPath);
+    const source = await fs7.readFile(file.absPath, "utf8");
+    for (const fn of parseExportedTestFunctions(source)) {
+      tests.push({
+        id: workspaceTestId(posix, fn.name),
+        file: posix,
+        name: fn.name,
+        hasInput: fn.hasInput,
+        inputName: fn.inputName
+      });
+    }
+  }
+  tests.sort((a, b) => a.id.localeCompare(b.id));
+  return tests;
+}
+async function bundleWorkspaceTestFile(options) {
+  const file = normalizePath(options.file);
+  return bundleWorkspaceModule({
+    cwd: options.cwd,
+    entry: file,
+    missingEntryMessage: `\u672A\u627E\u5230\u6D4B\u8BD5\u6587\u4EF6 ${file}\u3002`
+  });
+}
+
+// src/previewServer.ts
+var DEFAULT_PREVIEW_PORT = 4173;
+var DEFAULT_PREVIEW_HOST = "127.0.0.1";
+var RUNTIME_FILES = /* @__PURE__ */ new Set(["twin-runtime.js", "twin-apps.js", "twin-app-host.js"]);
+function formatPreviewReadyMessage(info) {
+  const lines = [
+    `EasyTwin \u9884\u89C8: ${info.url}`,
+    `\u573A\u666F: ${info.sceneId}`,
+    "\u7528\u6D4F\u89C8\u5668\u6253\u5F00\u4E0A\u8FF0\u5730\u5740\u3002\u70B9 Run \u8FD0\u884C TwinApp;\u6D4B\u8BD5\u6309\u94AE\u5728 Run \u680F\u4E0A\u65B9\u3002Ctrl+C \u505C\u6B62\u3002"
+  ];
+  if (info.mock) lines.unshift("[\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F] appId/appSecret \u5747\u4E3A test:\u573A\u666F\u6570\u636E\u6765\u81EA\u672C\u5730\u793A\u4F8B,\u672A\u8BF7\u6C42\u573A\u666F\u63A5\u53E3");
+  return lines.join("\n");
+}
+function resolvePreviewSceneId(scenes, requested) {
+  const id = requested?.trim() ?? "";
+  if (id.length > 0) return id;
+  const list = scenes ?? [];
+  const preferred = list.find((s) => s.defaultLoading === true) ?? list[0];
+  if (preferred) return preferred.id;
+  throw new Error("\u672A\u6307\u5B9A\u573A\u666F\u3002\u8BF7\u4F20\u5165 Scene Key,\u6216\u5148\u8FD0\u884C easytwin scene list");
+}
+function resolvePreviewRuntimeDir() {
+  if (typeof import.meta.url !== "string" || import.meta.url.length === 0) {
+    throw new Error("\u65E0\u6CD5\u5B9A\u4F4D\u9884\u89C8 runtime:\u63D2\u4EF6/CJS \u573A\u666F\u5FC5\u987B\u663E\u5F0F\u4F20\u5165 runtimeDir");
+  }
+  const here = path9.dirname(fileURLToPath3(import.meta.url));
+  const candidates = [
+    path9.join(here, "runtime"),
+    path9.resolve(here, "..", "dist", "runtime"),
+    path9.resolve(here, "runtime")
+  ];
+  for (const dir of candidates) {
+    if (existsSync2(path9.join(dir, "twin-runtime.js"))) return dir;
+  }
+  throw new Error(
+    `\u672A\u627E\u5230\u9884\u89C8 runtime(twin-runtime.js)\u3002\u5DF2\u5C1D\u8BD5:${candidates.join(", ")}\u3002\u8BF7\u5148\u6784\u5EFA @easytwin/devkit\u3002`
+  );
+}
+function mimeFor(file) {
+  if (file.endsWith(".js")) return "text/javascript; charset=utf-8";
+  return "application/octet-stream";
+}
+function sendJson(res, body, status = 200) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.setHeader("cache-control", "no-store");
+  res.end(JSON.stringify(body));
+}
+function sendText(res, body, status, contentType) {
+  res.statusCode = status;
+  res.setHeader("content-type", contentType);
+  res.end(body);
+}
+async function readJsonBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  if (chunks.length === 0) return {};
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (raw.length === 0) return {};
+  return JSON.parse(raw);
+}
+function asRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+async function startPreviewServer(options) {
+  const cwd = path9.resolve(options.cwd);
+  const config = await loadConfig(cwd);
+  const fileConfig = await readConfigFile(cwd);
+  const runtimeDir = options.runtimeDir ?? resolvePreviewRuntimeDir();
+  if (!existsSync2(path9.join(runtimeDir, "twin-runtime.js"))) {
+    throw new Error(`\u9884\u89C8 runtime \u76EE\u5F55\u7F3A\u5C11 twin-runtime.js:${runtimeDir}`);
+  }
+  let sceneId;
+  try {
+    sceneId = resolvePreviewSceneId(fileConfig.scenes, options.sceneId);
+  } catch (err) {
+    if (config.mock) {
+      sceneId = deriveExampleSceneId(await loadExampleScene());
+    } else {
+      throw err;
+    }
+  }
+  const client = new EasyTwinClient(config);
+  const scene = await pullScene(client, sceneId);
+  const tests = await listWorkspaceTests(cwd);
+  const hostname = options.hostname ?? DEFAULT_PREVIEW_HOST;
+  const log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
+  let lastBundledCode;
+  const originRef = { url: "" };
+  const html = () => buildPreviewHtml({
+    baseUrl: config.baseUrl,
+    ossUrl: config.ossUrl,
+    sceneJson: JSON.stringify(scene.payload ?? scene, null, 2),
+    mock: config.mock,
+    runtimeUri: `${originRef.url}/runtime/twin-runtime.js`,
+    appsUri: `${originRef.url}/runtime/twin-apps.js`,
+    hostUri: `${originRef.url}/runtime/twin-app-host.js`,
+    appId: config.appId,
+    host: "http",
+    tests
+  });
+  const server = http2.createServer((req, res) => {
+    void handle(req, res);
+  });
+  async function handle(req, res) {
+    try {
+      const url = new URL(req.url ?? "/", originRef.url || `http://${hostname}`);
+      const method = req.method ?? "GET";
+      if (method === "GET" && url.pathname === "/") {
+        sendText(res, html(), 200, "text/html; charset=utf-8");
+        return;
+      }
+      if (method === "GET" && url.pathname.startsWith("/runtime/")) {
+        const name = path9.posix.basename(url.pathname);
+        if (!RUNTIME_FILES.has(name)) {
+          sendText(res, "not found", 404, "text/plain; charset=utf-8");
+          return;
+        }
+        const file = path9.join(runtimeDir, name);
+        const buf = await fs8.readFile(file);
+        res.statusCode = 200;
+        res.setHeader("content-type", mimeFor(name));
+        res.setHeader("cache-control", "no-store");
+        res.end(buf);
+        return;
+      }
+      if (method === "POST" && url.pathname === "/api/bundle") {
+        try {
+          const result = await bundleUserCode({ cwd });
+          lastBundledCode = result.code;
+          for (const warning of result.warnings) log(`[run] \u8B66\u544A ${warning}`);
+          sendJson(res, { ok: true, code: result.code, warnings: result.warnings });
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          log(`[run] \u7F16\u8BD1\u5931\u8D25 ${error}`);
+          sendJson(res, { ok: false, error });
+        }
+        return;
+      }
+      if (method === "GET" && url.pathname === "/api/tests") {
+        sendJson(res, { tests: await listWorkspaceTests(cwd) });
+        return;
+      }
+      if (method === "POST" && url.pathname === "/api/test-bundle") {
+        const body = asRecord3(await readJsonBody(req));
+        const id = typeof body.id === "string" ? body.id : "";
+        const input = typeof body.input === "string" ? body.input : void 0;
+        try {
+          const listed = await listWorkspaceTests(cwd);
+          const item = listed.find((t) => t.id === id);
+          if (!item) throw new Error(`\u672A\u627E\u5230\u6D4B\u8BD5 ${id}`);
+          log(`[test] bundle ${item.file} :: ${item.name}`);
+          const result = await bundleWorkspaceTestFile({ cwd, file: item.file });
+          lastBundledCode = result.code;
+          for (const warning of result.warnings) log(`[test] \u8B66\u544A ${warning}`);
+          sendJson(res, {
+            ok: true,
+            code: result.code,
+            exportName: item.name,
+            input,
+            hasInput: item.hasInput,
+            warnings: result.warnings
+          });
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          log(`[test] \u7F16\u8BD1\u5931\u8D25 ${error}`);
+          sendJson(res, { ok: false, error });
+        }
+        return;
+      }
+      if (method === "GET" && url.pathname === "/api/assets") {
+        const rel = url.searchParams.get("path") ?? "";
+        try {
+          const file = resolveWorkspaceAssetPath(cwd, rel);
+          sendJson(res, { text: await fs8.readFile(file, "utf8") });
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          log(`[assets] FAIL ${rel} ${error}`);
+          sendJson(res, { error });
+        }
+        return;
+      }
+      if (method === "POST" && url.pathname === "/api/remap-error") {
+        const body = asRecord3(await readJsonBody(req));
+        const stack = typeof body.stack === "string" ? body.stack : "";
+        sendJson(res, { stack: lastBundledCode ? remapErrorStack(stack, lastBundledCode) : stack });
+        return;
+      }
+      sendText(res, "not found", 404, "text/plain; charset=utf-8");
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      log(`[preview] ${error}`);
+      if (!res.headersSent) sendJson(res, { error }, 500);
+    }
+  }
+  const port = options.port ?? DEFAULT_PREVIEW_PORT;
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, hostname, () => resolve());
+  });
+  const address = server.address();
+  const bound = typeof address === "object" && address !== null ? address.port : port;
+  originRef.url = `http://${hostname}:${bound}`;
+  return {
+    url: originRef.url,
+    port: bound,
+    sceneId,
+    mock: config.mock,
+    close: () => new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    })
+  };
+}
 
 // src/bin.ts
 async function readVersion() {
@@ -748,7 +2432,7 @@ async function readVersion() {
     return "0.0.0";
   }
 }
-var MOCK_MODE_HINT = "[\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F] appId/appSecret \u5747\u4E3A test:\u672A\u8BF7\u6C42\u670D\u52A1\u7AEF,\u573A\u666F/\u4E0A\u4F20\u8D70\u672C\u5730 mock";
+var MOCK_MODE_HINT = "[\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F] appId/appSecret \u5747\u4E3A test:\u672A\u8BF7\u6C42\u670D\u52A1\u7AEF,\u573A\u666F/\u4E0A\u4F20/\u5DE5\u4F5C\u533A\u62C9\u53D6\u8D70\u672C\u5730 mock";
 async function prompt(question) {
   const rl = createInterface({ input: stdin, output: stdout });
   try {
@@ -783,31 +2467,41 @@ function buildProgram(cwd, version = "0.0.0") {
   program.name("easytwin").description("EasyTwin DevKit \u547D\u4EE4\u884C\u5DE5\u5177").version(version, "-V, --version");
   program.command("init").description("\u4EA4\u4E92\u5F0F\u751F\u6210 easytwin.config.json,\u5E76\u8FFD\u52A0\u8FDB .gitignore").option("--app-id <id>", "App ID(\u8DF3\u8FC7\u4EA4\u4E92)").option("--app-secret <secret>", "App Secret(\u8DF3\u8FC7\u4EA4\u4E92)").option("--env <prod|test>", "\u670D\u52A1\u73AF\u5883(\u8DF3\u8FC7\u4EA4\u4E92)").option("--base-url <url>", "Base URL(\u8DF3\u8FC7\u4EA4\u4E92)").action((opts) => runInit(cwd, opts));
   const scene = program.command("scene").description("\u573A\u666F\u7BA1\u7406");
-  scene.command("list").description("\u5217\u51FA\u51ED\u636E\u53EF\u89C1\u7684\u573A\u666F").action(async () => {
+  scene.command("list").description("\u5217\u51FA\u51ED\u636E\u53EF\u89C1\u7684\u573A\u666F,\u5E76\u540C\u6B65\u6458\u8981\u5230 easytwin.config.json").action(async () => {
     const config = await loadConfig(cwd);
     if (config.mock) console.log(MOCK_MODE_HINT);
     const client = new EasyTwinClient(config);
-    const scenes = await listScenes(client);
+    const scenes = await listScenes(client, { cwd });
     if (scenes.length === 0) {
       console.log("(\u65E0\u573A\u666F)");
-      return;
+    } else {
+      for (const s of scenes) console.log(`${s.id}	${s.name}`);
     }
-    for (const s of scenes) console.log(`${s.id}	${s.name}`);
+    console.log(`\u5DF2\u540C\u6B65 ${scenes.length} \u4E2A\u573A\u666F\u5230 ${CONFIG_FILE_NAME}`);
   });
   scene.command("pull <id>").description("\u62C9\u53D6\u573A\u666F JSON \u5230\u672C\u5730").option("-o, --out <path>", "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84(\u7F3A\u7701 ./<id>.scene.json)").action(async (id, opts) => {
     const config = await loadConfig(cwd);
     if (config.mock) console.log(MOCK_MODE_HINT);
     const client = new EasyTwinClient(config);
     const scene2 = await pullScene(client, id);
-    const out = opts.out ?? path6.join(cwd, `${id}.scene.json`);
+    const out = opts.out ?? path10.join(cwd, `${id}.scene.json`);
     const file = await saveSceneJson(scene2, out);
     console.log(`\u5DF2\u4FDD\u5B58\u5230 ${file}`);
   });
-  program.command("upload <dir>").description("\u5168\u91CF\u8986\u76D6\u4E0A\u4F20\u76EE\u5F55(\u4E0D\u53EF\u9006)").action(async (dir) => {
+  program.command("pull").description("\u62C9\u53D6\u5DE5\u4F5C\u533A\u4EE3\u7801(\u8FDC\u7AEF\u4E3A\u7A7A\u5219\u5199\u5165\u9ED8\u8BA4 src/main.ts;\u51B2\u7A81\u9ED8\u8BA4\u4E0D\u8986\u76D6)").argument("[dir]", "\u5DE5\u4F5C\u533A\u76EE\u5F55(\u7F3A\u7701\u5F53\u524D\u76EE\u5F55)").option("--force", "\u7528\u8FDC\u7AEF\u5185\u5BB9\u8986\u76D6\u672C\u5730\u51B2\u7A81\u6587\u4EF6").option("--dry-run", "\u53EA\u6253\u5370 diff,\u4E0D\u5199\u76D8").action(async (dirArg, opts) => {
+    const config = await loadConfig(cwd);
+    if (config.mock) console.log(MOCK_MODE_HINT);
+    const client = new EasyTwinClient(config);
+    const target = dirArg ? path10.resolve(cwd, dirArg) : cwd;
+    const result = await pullWorkspace(client, target, { force: opts.force, dryRun: opts.dryRun });
+    console.log(formatWorkspacePullResult(result));
+  });
+  program.command("upload").description("\u5BF9\u7167\u8FDC\u7AEF\u5168\u91CF\u5BF9\u9F50\u5DE5\u4F5C\u533A(\u8DF3\u8FC7\u63D2\u4EF6\u4EA7\u7269,\u4E0D\u53EF\u9006)").argument("[dir]", "\u5DE5\u4F5C\u533A\u76EE\u5F55(\u7F3A\u7701\u5F53\u524D\u76EE\u5F55)").action(async (dirArg) => {
     const config = await loadConfig(cwd);
     if (config.mock) console.log(MOCK_MODE_HINT);
     const client = new EasyTwinClient(config);
-    await uploadDirectory(client, dir, {
+    const target = dirArg ? path10.resolve(cwd, dirArg) : cwd;
+    const result = await uploadDirectory(client, target, {
       onProgress: (p) => {
         if (p.phase === "upload") {
           process.stderr.write(`\r\u5DF2\u4E0A\u4F20 ${p.current}/${p.total} bytes${p.file ? ` (${p.file})` : ""}`);
@@ -815,14 +2509,29 @@ function buildProgram(cwd, version = "0.0.0") {
       }
     });
     process.stderr.write("\n");
+    console.log(formatUploadResult(result));
   });
-  program.command("bundle").description("\u6253\u5305\u5DE5\u4F5C\u533A src/main.ts(\u4EC5\u5141\u8BB8\u4F9D\u8D56 @easytwin/runtime)").option("-o, --out <path>", `\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84(\u7F3A\u7701 ${DEFAULT_BUNDLE_OUT})`).action(async (opts) => {
+  program.command("bundle").description("\u6253\u5305\u5DE5\u4F5C\u533A src/main.ts(\u4EC5\u5141\u8BB8 @easytwin/runtime \u4E0E @easytwin/apps)").option("-o, --out <path>", `\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84(\u7F3A\u7701 ${DEFAULT_BUNDLE_OUT})`).action(async (opts) => {
     const hint = await typesMissingHint(cwd);
     if (hint) console.warn(hint);
-    const outFile = path6.resolve(cwd, opts.out ?? DEFAULT_BUNDLE_OUT);
-    await bundleUserCode({ cwd, outFile });
+    const outFile = path10.resolve(cwd, opts.out ?? DEFAULT_BUNDLE_OUT);
+    const result = await bundleUserCode({ cwd, outFile });
+    for (const warning of result.warnings) console.warn(warning);
     console.log(`\u5DF2\u6253\u5305\u5230 ${outFile}`);
   });
+  program.command("preview").description("\u542F\u52A8\u672C\u5730\u9884\u89C8\u9875(\u4E09\u7EF4\u573A\u666F + Run + \u6D4B\u8BD5\u63A7\u4EF6),\u6253\u5370 URL \u4F9B\u6D4F\u89C8\u5668\u6253\u5F00").argument("[sceneId]", "\u573A\u666F Scene Key(\u7F3A\u7701\u914D\u7F6E scenes \u4E2D defaultLoading \u6216\u9996\u9879)").option("-p, --port <port>", "\u7AEF\u53E3(\u7F3A\u7701 4173,\u53EA\u7ED1 127.0.0.1)", "4173").action(async (sceneId, opts) => {
+    const port = Number.parseInt(opts.port, 10);
+    if (!Number.isFinite(port) || port < 0) throw new Error(`\u65E0\u6548\u7AEF\u53E3:${opts.port}`);
+    const server = await startPreviewServer({ cwd, sceneId, port });
+    console.log(formatPreviewReadyMessage(server));
+    await new Promise((resolve, reject) => {
+      const stop = () => {
+        server.close().then(resolve, reject);
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    });
+  });
   const skills = program.command("skills").description("skills \u540C\u6B65\u5230\u7528\u6237\u9879\u76EE");
   skills.command("sync").description("\u540C\u6B65 skills \u5230\u7528\u6237\u9879\u76EE(cursor/claude/codex/qoder),\u7F3A\u7701 all").option("--target <target>", "cursor|claude|codex|qoder|all", "all").action(async (opts) => {
     const { summaries, types } = await syncSkills({ cwd, targets: opts.target });
@@ -856,4 +2565,3 @@ export {
   main,
   runInit
 };
-//# sourceMappingURL=bin.js.map