@easytwin/devkit 0.1.1 → 0.1.2

package/dist/bin.js

@@ -7,14 +7,17 @@ import { readFile } from "fs/promises";
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
 import { pathToFileURL } from "url";
-import path6 from "path";
+import path8 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 TEST_OP_ACCOUNT_ID = "25";
+var TEST_OP_USER_ID = "25";
+var TEST_SPACE_ID = "54";
 var DEFAULT_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
 var MOCK_APP_ID = "test";
 var MOCK_APP_SECRET = "test";
@@ -59,12 +62,59 @@ function validateConfigShape(value) {
   if (v.env !== void 0 && v.env !== "prod" && v.env !== "test") {
     throw new ConfigError("env \u5FC5\u987B\u662F prod \u6216 test");
   }
+  const opAccountId = optionalGatewayId(v.opAccountId);
+  const opUserId = optionalGatewayId(v.opUserId);
+  const spaceId = optionalGatewayId(v.spaceId);
   const config = { appId: v.appId, appSecret: v.appSecret };
   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;
+  if (opAccountId) config.opAccountId = opAccountId;
+  if (opUserId) config.opUserId = opUserId;
+  if (spaceId) config.spaceId = spaceId;
+  const scenes = parseConfigScenes(v.scenes);
+  if (scenes) config.scenes = scenes;
   return config;
 }
+function optionalGatewayId(value) {
+  if (typeof value === "string") {
+    const t = value.trim();
+    return t.length > 0 ? t : void 0;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (value !== void 0) throw new ConfigError("opAccountId / opUserId / spaceId \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6216\u6570\u5B57");
+  return void 0;
+}
+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;
@@ -84,10 +134,30 @@ function resolveConfig(file, env = process.env) {
   if (!appId) throw new ConfigError("\u7F3A\u5C11 appId:\u914D\u7F6E\u6587\u4EF6\u4E2D\u672A\u63D0\u4F9B,\u4E14\u672A\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF EASYTWIN_APP_ID");
   if (!appSecret) throw new ConfigError("\u7F3A\u5C11 appSecret:\u914D\u7F6E\u6587\u4EF6\u4E2D\u672A\u63D0\u4F9B,\u4E14\u672A\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF EASYTWIN_APP_SECRET");
   const source = env.EASYTWIN_APP_ID !== void 0 || env.EASYTWIN_APP_SECRET !== void 0 ? "env" : "file";
-  return { appId, appSecret, baseUrl, ossUrl, mock: isMockCredentials(appId, appSecret), source };
+  const useTestGateway = easyEnv === "test";
+  const opAccountId = optionalGatewayId(env.EASYTWIN_OP_ACCOUNT_ID) ?? file.opAccountId ?? (useTestGateway ? TEST_OP_ACCOUNT_ID : void 0);
+  const opUserId = optionalGatewayId(env.EASYTWIN_OP_USER_ID) ?? file.opUserId ?? (useTestGateway ? TEST_OP_USER_ID : void 0);
+  const spaceId = optionalGatewayId(env.EASYTWIN_SPACE_ID) ?? file.spaceId ?? (useTestGateway ? TEST_SPACE_ID : void 0);
+  const resolved = { appId, appSecret, baseUrl, ossUrl, mock: isMockCredentials(appId, appSecret), source };
+  if (opAccountId) resolved.opAccountId = opAccountId;
+  if (opUserId) resolved.opUserId = opUserId;
+  if (spaceId) resolved.spaceId = spaceId;
+  return resolved;
 }
 async function loadConfig(cwd, env = process.env) {
-  return resolveConfig(await readConfigFile(cwd), env);
+  const file = await readConfigFile(cwd);
+  const resolved = resolveConfig(file, env);
+  if (file.env === "test" && env.EASYTWIN_OP_ACCOUNT_ID === void 0 && env.EASYTWIN_OP_USER_ID === void 0 && env.EASYTWIN_SPACE_ID === void 0) {
+    if (!file.opAccountId || !file.opUserId || !file.spaceId) {
+      await writeConfigFile(cwd, {
+        ...file,
+        opAccountId: file.opAccountId ?? TEST_OP_ACCOUNT_ID,
+        opUserId: file.opUserId ?? TEST_OP_USER_ID,
+        spaceId: file.spaceId ?? TEST_SPACE_ID
+      });
+    }
+  }
+  return resolved;
 }
 async function writeConfigFile(cwd, config) {
   const file = configFilePath(cwd);
@@ -95,6 +165,13 @@ 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;
+  const opAccountId = config.opAccountId ?? (config.env === "test" ? TEST_OP_ACCOUNT_ID : void 0);
+  const opUserId = config.opUserId ?? (config.env === "test" ? TEST_OP_USER_ID : void 0);
+  const spaceId = config.spaceId ?? (config.env === "test" ? TEST_SPACE_ID : void 0);
+  if (opAccountId) body.opAccountId = opAccountId;
+  if (opUserId) body.opUserId = opUserId;
+  if (spaceId) body.spaceId = spaceId;
+  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 +199,31 @@ 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 AUTH_HEADER = "x-app-secret";
+var OP_ACCOUNT_ID_HEADER = "op-account-id";
+var OP_USER_ID_HEADER = "op-user-id";
+var SPACE_ID_HEADER = "space-id";
+function enc(id) {
+  return encodeURIComponent(id);
+}
 var ENDPOINTS = {
-  scenes: "/api/scenes",
-  scene: (id) => `/api/scenes/${encodeURIComponent(id)}`,
-  upload: "/api/upload"
+  /** GET 已关联场景列表。 */
+  linkedScenes: (applicationId) => `/api/twin/v1/sdk-application-scenes/${enc(applicationId)}/scenes`,
+  /** GET 工作区全部代码文件。 */
+  workspaceCode: (applicationId) => `/api/twin/v1/sdk-application-code/${enc(applicationId)}`,
+  /** GET 工作区文件约束。 */
+  workspaceConfig: (applicationId) => `/api/twin/v1/sdk-application-code/${enc(applicationId)}/workspace-config`,
+  /** POST 新建 / PATCH 批量更新 / DELETE 批量删除。 */
+  workspaceCodeFiles: (applicationId) => `/api/twin/v1/sdk-application-code/${enc(applicationId)}/files`
 };
 var EasyTwinApiError = class extends Error {
   status;
@@ -161,28 +251,50 @@ 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;同时作为场景/代码 API 的 applicationId 路径参数。 */
   appId;
+  /** 本地测试模式:true 时 scene/upload/pull 走本地 mock,不发网络请求(见 config.ts)。 */
+  mock;
   appSecret;
+  opAccountId;
+  opUserId;
+  spaceId;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.ossUrl = config.ossUrl.replace(/\/+$/, "");
     this.mock = config.mock;
     this.appId = config.appId;
     this.appSecret = config.appSecret;
+    this.opAccountId = config.opAccountId;
+    this.opUserId = config.opUserId;
+    this.spaceId = config.spaceId;
   }
   /** 全仓唯一认证头注入点。 */
   authHeaders() {
-    return {
-      [AUTH_HEADER]: `${BEARER_PREFIX} ${this.appSecret}`,
-      [APP_ID_HEADER]: this.appId
-    };
+    const headers = { [AUTH_HEADER]: this.appSecret };
+    if (this.opAccountId) headers[OP_ACCOUNT_ID_HEADER] = this.opAccountId;
+    if (this.opUserId) headers[OP_USER_ID_HEADER] = this.opUserId;
+    if (this.spaceId) headers[SPACE_ID_HEADER] = this.spaceId;
+    return headers;
   }
   /** JSON 请求(原生 fetch)。 */
-  async request(path7, options = {}) {
-    const url = `${this.baseUrl}${path7}`;
+  async request(path9, options = {}) {
+    const url = `${this.baseUrl}${path9}`;
     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 +316,8 @@ var EasyTwinClient = class {
    * multipart 流式上传(手写 http 请求以支持逐字节进度回调)。
    * 这是 fetch 上传的替代路径:原生 fetch 无法上报上传进度。
    */
-  async upload(path7, options) {
-    const url = new URL2(`${this.baseUrl}${path7}`);
+  async upload(path9, options) {
+    const url = new URL2(`${this.baseUrl}${path9}`);
     const mod = url.protocol === "https:" ? https : http;
     const headers = {
       ...this.authHeaders(),
@@ -238,8 +350,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 +360,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";
@@ -291,21 +475,30 @@ async function exampleSceneSummary(exampleFile) {
   return { id: deriveExampleSceneId(await loadExampleScene(exampleFile)), name: MOCK_SCENE_NAME };
 }
 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 client.request(ENDPOINTS.linkedScenes(client.appId), { method: "GET" }));
+  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 client.request(ENDPOINTS.scene(id), { method: "GET" });
-  return normalizeSceneDetail(data);
+  const data = await client.request(ENDPOINTS.linkedScenes(client.appId), { method: "GET" });
+  const scenes = normalizeLinkedScenes(data);
+  const hit = scenes.find((s) => s.sceneKey === id || s.id === id);
+  if (!hit) {
+    const available = scenes.map((s) => s.sceneKey).filter((k) => k.length > 0);
+    throw new Error(
+      available.length > 0 ? `\u672A\u627E\u5230\u573A\u666F ${id}(\u53EF\u7528 Scene Key:${available.join(", ")})` : `\u672A\u627E\u5230\u573A\u666F ${id}`
+    );
+  }
+  const payload = await fetchSnapshotJson(client.ossUrl, hit.snapshotUrl);
+  return { id: hit.sceneKey, name: hit.name, payload };
 }
 async function saveSceneJson(scene, out) {
   await fs2.mkdir(path2.dirname(out), { recursive: true });
@@ -338,32 +531,73 @@ 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 asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : NaN;
+}
+function normalizePath(relPath) {
+  return relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function normalizeWorkspaceConfig(data) {
+  const it = asRecord2(data);
+  if (!Array.isArray(it.allowedFileExtensions)) throw new Error("workspace-config \u54CD\u5E94\u7ED3\u6784\u65E0\u6CD5\u8BC6\u522B");
+  const maxCodeFiles = asNumber(it.maxCodeFiles);
+  const maxCodeDirectoryDepth = asNumber(it.maxCodeDirectoryDepth);
+  if (!Number.isFinite(maxCodeFiles) || !Number.isFinite(maxCodeDirectoryDepth)) {
+    throw new Error("workspace-config \u54CD\u5E94\u7ED3\u6784\u65E0\u6CD5\u8BC6\u522B");
+  }
+  return {
+    allowedFileExtensions: it.allowedFileExtensions.filter((e) => typeof e === "string"),
+    maxCodeFiles,
+    maxCodeDirectoryDepth
+  };
+}
+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()}`));
+}
+function directoryDepth(relPath) {
+  const parts = normalizePath(relPath).split("/").filter((p) => p.length > 0);
+  return Math.max(0, parts.length - 1);
+}
+function assertUploadable(files, config) {
+  const errors = [];
+  if (files.length > config.maxCodeFiles) {
+    errors.push(`\u6587\u4EF6\u6570 ${files.length} \u8D85\u8FC7\u4E0A\u9650 ${config.maxCodeFiles}`);
+  }
+  const tooDeep = files.filter((f) => directoryDepth(f.relPath) > config.maxCodeDirectoryDepth);
+  if (tooDeep.length > 0) {
+    errors.push(
+      `\u76EE\u5F55\u6DF1\u5EA6\u8D85\u8FC7\u4E0A\u9650 ${config.maxCodeDirectoryDepth}:${tooDeep.map((f) => f.relPath).join(", ")}`
     );
   }
-  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);
+  if (config.allowedFileExtensions.length > 0) {
+    const allowed = allowedExtensionSet(config.allowedFileExtensions);
+    const bad = files.filter((f) => !allowed.has(extensionOf(f.relPath)));
+    if (bad.length > 0) {
+      errors.push(
+        `\u6269\u5C55\u540D\u4E0D\u5728\u5141\u8BB8\u5217\u8868(${config.allowedFileExtensions.join(", ")}):${bad.map((f) => f.relPath).join(", ")}`
+      );
+    }
+  }
+  if (errors.length > 0) throw new Error(`\u65E0\u6CD5\u4E0A\u4F20:${errors.join("; ")}`);
 }
 async function mockUpload(dir, options) {
   const ignore = options.ignore ?? (() => false);
@@ -379,26 +613,306 @@ async function uploadDirectory(client, dir, options = {}) {
   const files = await collectFiles(dir, ignore);
   const total = files.reduce((sum, f) => sum + f.size, 0);
   options.onProgress?.({ phase: "collect", current: total, total });
-  let sent = 0;
+  const appId = client.appId;
+  const wsConfig = normalizeWorkspaceConfig(await client.request(ENDPOINTS.workspaceConfig(appId), { method: "GET" }));
+  assertUploadable(files, wsConfig);
+  const remote = normalizeWorkspaceFiles(await client.request(ENDPOINTS.workspaceCode(appId), { method: "GET" }));
+  const remoteByPath = new Map(remote.map((f) => [normalizePath(f.filePath), f]));
+  const localPaths = new Set(files.map((f) => normalizePath(f.relPath)));
+  const toDelete = remote.filter((f) => !localPaths.has(normalizePath(f.filePath))).map((f) => f.id);
+  if (toDelete.length > 0) {
+    await client.request(ENDPOINTS.workspaceCodeFiles(appId), {
+      method: "DELETE",
+      body: JSON.stringify({ ids: toDelete })
+    });
+  }
+  const creates = [];
+  const patches = [];
+  const unchanged = [];
   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 });
+    const content = await fs3.readFile(file.absPath, "utf8");
+    const remoteFile = remoteByPath.get(normalizePath(file.relPath));
+    if (!remoteFile) creates.push({ file, content });
+    else if (remoteFile.content !== content) patches.push({ file, id: remoteFile.id, content });
+    else unchanged.push(file);
+  }
+  let sent = 0;
+  const bump = (file) => {
     sent += file.size;
     options.onProgress?.({ phase: "upload", current: sent, total, file: file.relPath });
+  };
+  if (patches.length > 0) {
+    await client.request(ENDPOINTS.workspaceCodeFiles(appId), {
+      method: "PATCH",
+      body: JSON.stringify({ files: patches.map((p) => ({ id: p.id, content: p.content })) })
+    });
+    for (const p of patches) bump(p.file);
   }
-  return { fileCount: files.length, byteCount: sent };
+  for (const c of creates) {
+    await client.request(ENDPOINTS.workspaceCodeFiles(appId), {
+      method: "POST",
+      body: JSON.stringify({ filePath: normalizePath(c.file.relPath), content: c.content })
+    });
+    bump(c.file);
+  }
+  for (const u of unchanged) bump(u);
+  if (files.length === 0) options.onProgress?.({ phase: "upload", current: 0, total: 0 });
+  return { fileCount: files.length, byteCount: total };
 }
 
-// src/skills.ts
-import { existsSync, promises as fs4 } from "fs";
+// 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;
+  }
+}
+`;
+var PULL_IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  ".easytwin",
+  ".cursor",
+  ".claude",
+  ".qoder",
+  ".vscode"
+]);
+var PULL_IGNORED_FILES = /* @__PURE__ */ new Set(["easytwin.config.json"]);
+var DEFAULT_PULL_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".json", ".css", ".html", ".md"];
+function defaultPullIgnore(relPath) {
+  const parts = normalizePath(relPath).split("/").filter((p) => p.length > 0);
+  if (parts.some((p) => PULL_IGNORED_DIRS.has(p))) return true;
+  const base = parts[parts.length - 1];
+  return base !== void 0 && PULL_IGNORED_FILES.has(base);
+}
+function isSafeRelPath(relPath) {
+  const n = normalizePath(relPath);
+  if (!n) return false;
+  if (n.toLowerCase() === "easytwin.config.json") 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 extensionOf2(relPath) {
+  const base = relPath.split("/").pop() ?? "";
+  const i = base.lastIndexOf(".");
+  if (i <= 0) return "";
+  return base.slice(i).toLowerCase();
+}
+function allowedExtensionSet2(list) {
+  return new Set(list.map((e) => e.startsWith(".") ? e.toLowerCase() : `.${e.toLowerCase()}`));
+}
+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;
+  }
+}
+async function loadAllowedExtensions(client) {
+  if (client.mock) return DEFAULT_PULL_EXTENSIONS;
+  try {
+    const cfg = normalizeWorkspaceConfig(
+      await client.request(ENDPOINTS.workspaceConfig(client.appId), { method: "GET" })
+    );
+    return cfg.allowedFileExtensions.length > 0 ? cfg.allowedFileExtensions : DEFAULT_PULL_EXTENSIONS;
+  } catch {
+    return DEFAULT_PULL_EXTENSIONS;
+  }
+}
+async function fetchRemoteFiles(client) {
+  if (client.mock) return [];
+  return normalizeWorkspaceFiles(await client.request(ENDPOINTS.workspaceCode(client.appId), { method: "GET" }));
+}
+async function planWorkspacePull(client, dir, options = {}) {
+  const ignore = combineIgnore(options.ignore);
+  const allowed = allowedExtensionSet2(await loadAllowedExtensions(client));
+  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)) {
+      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 (!allowed.has(extensionOf2(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 fs5 } from "fs";
+import path6 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var SKILL_NAMES = [
   "easytwin-render",
@@ -421,7 +935,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 +948,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 +1007,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 +1080,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 +1110,19 @@ 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",
     "",
     "\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 +1140,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 +1194,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 +1205,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 +1239,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 +1248,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 +1266,29 @@ function formatEsbuildMessages(messages) {
     return `${loc}${m.text}`;
   }).join("\n");
 }
+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 bundleUserCode(options) {
-  const cwd = path5.resolve(options.cwd);
-  const entry = path5.join(cwd, USER_ENTRY);
+  const cwd = path7.resolve(options.cwd);
+  const entry = path7.join(cwd, USER_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`
+      `\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`
     );
   }
   let result;
@@ -723,16 +1319,18 @@ 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 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";
@@ -748,7 +1346,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,26 +1381,35 @@ 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 ?? path8.join(cwd, `${id}.scene.json`);
     const file = await saveSceneJson(scene2, out);
     console.log(`\u5DF2\u4FDD\u5B58\u5230 ${file}`);
   });
+  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 ? path8.resolve(cwd, dirArg) : cwd;
+    const result = await pullWorkspace(client, target, { force: opts.force, dryRun: opts.dryRun });
+    console.log(formatWorkspacePullResult(result));
+  });
   program.command("upload <dir>").description("\u5168\u91CF\u8986\u76D6\u4E0A\u4F20\u76EE\u5F55(\u4E0D\u53EF\u9006)").action(async (dir) => {
     const config = await loadConfig(cwd);
     if (config.mock) console.log(MOCK_MODE_HINT);
@@ -816,11 +1423,12 @@ function buildProgram(cwd, version = "0.0.0") {
     });
     process.stderr.write("\n");
   });
-  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 = path8.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}`);
   });
   const skills = program.command("skills").description("skills \u540C\u6B65\u5230\u7528\u6237\u9879\u76EE");