@easytwin/devkit 0.1.3 → 0.1.4

package/README.md

@@ -1,76 +1,78 @@
-# @easytwin/devkit
-
-EasyTwin 第三方应用开发工具集的核心包:lib(函数库)与 bin(`easytwin` 命令)双导出,供人类与 AI agent(如 Cursor / Claude Code / Codex)共同使用。设计蓝图见仓库根 `AGENTS.md`。
-
-## 安装
-
-```bash
-npm i -g @easytwin/devkit   # 全局安装 CLI
-```
-
-也可作为库安装:`npm i @easytwin/devkit`。
-
-## 命令
-
-| 命令 | 行为 |
-| --- | --- |
-| `easytwin init` | 交互式生成 `easytwin.config.json`,并追加进 `.gitignore`(无则创建) |
-| `easytwin scene list` | 列出凭据可见的场景,并把摘要写入 `easytwin.config.json.scenes` |
-| `easytwin scene pull <id> [--out <path>]` | 拉取场景 JSON 到本地 |
-| `easytwin upload [dir]` | 对照远端全量对齐工作区(缺省 cwd;跳过插件产物) |
-| `easytwin skills sync [--target cursor\|claude\|codex\|all]` | 同步 skills 到用户项目,缺省 all |
-
-## 配置
-
-项目根 `easytwin.config.json`:
-
-```json
-{
-  "appId": "必填",
-  "appSecret": "必填",
-  "env": "可选,prod=正式 / test=测试,缺省 prod",
-  "baseUrl": "可选,缺省按 env 选官方域名",
-  "ossUrl": "可选,缺省官方 OSS",
-  "scenes": "可选,由 scene list 写入的场景摘要"
-}
-```
-
-环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` / `EASYTWIN_ENV` / `EASYTWIN_OSS_URL` 优先于文件。请求带 `x-app-id`(App ID)与 `x-app-secret`(App Secret),不走 OP 网关。官方 API:正式 `http://saas-twin.k8s.dtstack.cn/`、测试 `http://172.16.125.3:10100/`,缺省按 env 选择。官方 OSS:`https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/`,供 twin runtime 加载 webp/draco/组件脚本。文件含密钥,永不入库(`init` 会处理 gitignore)。
-
-## skills
-
-六件套(`easytwin-render` / `-core` / `-develop` / `-bootstrap` / `-scene` / `-upload`)随包分发,通过 `easytwin skills sync` 显式写入 Cursor(`.cursor/skills/`)、Claude Code(`.claude/skills/`)与 Codex(`AGENTS.md` 标记段),重复执行幂等。
-
-## 发布到 npm
-
-```bash
-# 1. 登录(写入 ~/.npmrc 的 npmjs token;CI 用 NPM_TOKEN 环境变量)
-npm login --registry https://registry.npmjs.org/
-
-# 2. 确认发布产物应包含 dist/ 与 skills/
-npm pack --dry-run
-
-# 3. 升版本
-npm version patch|minor|major
-
-# 4. 发布(必须先升版本:同版本已在 npm 上会被跳过,提示 There are no new packages that should be published)
-# 在仓库根目录用 run,不要直接 pnpm publish(那是工作区递归发布内置命令)
-pnpm run publish
-```
-
-- scoped 包需 publishConfig.access 为 public,已配置;
-- 本机默认 registry 是 npmmirror,publishConfig.registry 已固定为官方 npmjs;
-- 包名是否被占用可用 npm view @easytwin/devkit 确认;
-- repository 目前指向内网 GitLab,公网发布前建议改为公开地址(可选)。
-
-## 开发
-
-```bash
-pnpm install
-pnpm -r build
-pnpm -r test
-```
-
-## 已知外部输入(TODO)
-
-渲染 API 文档与 d.ts 仍未到位,skills 中以 `TODO(外部输入)` 标记,不臆造。场景列表/拉取与工作区代码上传已按内部 swagger(SDK 应用场景 / SDK 应用代码)落地;官方 API 域名、官方 OSS 与场景 JSON 格式已定(见上)。
+# @easytwin/devkit
+
+EasyTwin 第三方应用开发工具集的核心包:lib(函数库)与 bin(`easytwin` 命令)双导出,供人类与 AI agent(如 Cursor / Claude Code / Codex)共同使用。设计蓝图见仓库根 `AGENTS.md`。
+
+## 安装
+
+```bash
+npm i -g @easytwin/devkit   # 全局安装 CLI
+```
+
+也可作为库安装:`npm i @easytwin/devkit`。
+
+## 命令
+
+| 命令 | 行为 |
+| --- | --- |
+| `easytwin init` | 交互式生成 `.easytwin/easytwin.config.json`,并将凭据与 `.easytwin/scenes/` 追加进 `.gitignore`(无则创建) |
+| `easytwin scene list` | 列出凭据可见的场景,并把摘要写入 `.easytwin/easytwin.config.json.scenes` |
+| `easytwin scene pull <id> [--out <path>]` | 拉取场景 JSON:写入 `.easytwin/scenes/<id>.scene.json`;`--out` 再额外写一份 |
+| `easytwin scene inspect <id> [--name] [--type]` | 只读本地快照,打印对象树(id/name/type);超过 200 节点截断 |
+| `easytwin upload [dir]` | 对照远端全量对齐工作区(缺省 cwd;跳过插件产物) |
+| `easytwin skills sync [--target cursor\|claude\|codex\|all]` | 同步 skills 到用户项目,缺省 all |
+
+## 配置
+
+`.easytwin/easytwin.config.json`(项目级):
+
+```json
+{
+  "appId": "必填",
+  "appSecret": "必填",
+  "env": "可选,prod=正式 / test=测试,缺省 prod",
+  "baseUrl": "可选,缺省按 env 选官方域名",
+  "ossUrl": "可选,缺省官方 OSS",
+  "scenes": "可选,由 scene list 写入的场景摘要"
+}
+```
+
+环境变量 `EASYTWIN_APP_ID` / `EASYTWIN_APP_SECRET` / `EASYTWIN_BASE_URL` / `EASYTWIN_ENV` / `EASYTWIN_OSS_URL` 优先于文件。请求带 `x-app-id`(App ID)与 `x-app-secret`(App Secret),不走 OP 网关。官方 API:正式 `http://saas-twin.k8s.dtstack.cn/`、测试 `http://172.16.125.3:10100/`,缺省按 env 选择。官方 OSS 资产根:`https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/`,供 twin runtime 加载 webp/draco/组件脚本。runtime 类型:`env=prod` 用正式桶 `https://dt-easyv-prod.oss-cn-hangzhou.aliyuncs.com/easytwin/system/libs/runtime/types/`,其余用测试桶同路径。文件含密钥,永不入库(`init` 会处理 gitignore)。
+
+## skills
+
+六件套(`easytwin-render` / `-core` / `-develop` / `-bootstrap` / `-scene` / `-upload`)随包分发,通过 `easytwin skills sync` 显式写入 Cursor(`.cursor/skills/`)、Claude Code(`.claude/skills/`)与 Codex(`AGENTS.md` 标记段),重复执行幂等。
+
+## 发布到 npm
+
+```bash
+# 1. 登录(写入 ~/.npmrc 的 npmjs token;CI 用 NPM_TOKEN 环境变量)
+npm login --registry https://registry.npmjs.org/
+
+# 2. 确认发布产物应包含 dist/ 与 skills/
+npm pack --dry-run
+
+# 3. 升版本
+npm version patch|minor|major
+
+# 4. 发布(必须先升版本:同版本已在 npm 上会被跳过,提示 There are no new packages that should be published)
+# 在仓库根目录用 run,不要直接 pnpm publish(那是工作区递归发布内置命令)
+pnpm run publish
+```
+
+- scoped 包需 publishConfig.access 为 public,已配置;
+- 本机默认 registry 是 npmmirror,publishConfig.registry 已固定为官方 npmjs;
+- `pnpm run publish` 只在本次进程清掉 `proxy` / `HTTP_PROXY`,不改 `~/.npmrc`;Clash 日常代理可保持 `http://127.0.0.1:7890`;
+- 包名是否被占用可用 npm view @easytwin/devkit 确认;
+- repository 目前指向内网 GitLab,公网发布前建议改为公开地址(可选)。
+
+## 开发
+
+```bash
+pnpm install
+pnpm -r build
+pnpm -r test
+```
+
+## 已知外部输入(TODO)
+
+渲染 API 文档与 d.ts 仍未到位,skills 中以 `TODO(外部输入)` 标记,不臆造。场景列表/拉取与工作区代码上传已按内部 swagger(SDK 应用场景 / SDK 应用代码)落地;官方 API 域名、官方 OSS 与场景 JSON 格式已定(见上)。

package/dist/bin.js

@@ -12,10 +12,15 @@ import path10 from "path";
 // src/config.ts
 import { promises as fs } from "fs";
 import path from "path";
+var EASYTWIN_DIR = ".easytwin";
 var CONFIG_FILE_NAME = "easytwin.config.json";
+var EASYTWIN_SCENES_DIRNAME = "scenes";
 var DEFAULT_BASE_URL = "http://saas-twin.k8s.dtstack.cn/";
 var TEST_BASE_URL = "http://172.16.125.3:10100/";
-var DEFAULT_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+var TEST_OSS_URL = "https://dt-easyv-test.oss-cn-hangzhou.aliyuncs.com/";
+var PROD_OSS_URL = "https://dt-easyv-prod.oss-cn-hangzhou.aliyuncs.com/";
+var DEFAULT_OSS_URL = TEST_OSS_URL;
+var RUNTIME_TYPES_RELPATH = "easytwin/system/libs/runtime/types/index.d.ts";
 var MOCK_APP_ID = "test";
 var MOCK_APP_SECRET = "test";
 function isMockCredentials(appId, appSecret) {
@@ -28,8 +33,31 @@ var ConfigError = class extends Error {
   }
 };
 function configFilePath(cwd) {
+  return path.join(cwd, EASYTWIN_DIR, CONFIG_FILE_NAME);
+}
+function joinOssPath(ossUrl, relPath) {
+  return `${ossUrl.replace(/\/+$/, "")}/${relPath.replace(/^\/+/, "")}`;
+}
+function resolveRuntimeTypesUrl(options = {}) {
+  const root = options.ossUrl ?? (options.env === "prod" ? PROD_OSS_URL : TEST_OSS_URL);
+  return joinOssPath(root, RUNTIME_TYPES_RELPATH);
+}
+async function resolveRuntimeTypesUrlForCwd(cwd, env = process.env) {
+  let file;
+  try {
+    file = await readConfigFile(cwd);
+  } catch {
+  }
+  const easyEnv = env.EASYTWIN_ENV === "test" || env.EASYTWIN_ENV === "prod" ? env.EASYTWIN_ENV : file?.env;
+  const ossUrl = env.EASYTWIN_OSS_URL ?? file?.ossUrl;
+  return resolveRuntimeTypesUrl({ env: easyEnv, ossUrl });
+}
+function legacyConfigFilePath(cwd) {
   return path.join(cwd, CONFIG_FILE_NAME);
 }
+function defaultSceneOutPath(cwd, id) {
+  return path.join(cwd, EASYTWIN_DIR, EASYTWIN_SCENES_DIRNAME, `${path.basename(id)}.scene.json`);
+}
 function parseConfig(raw) {
   let parsed;
   try {
@@ -97,15 +125,39 @@ function parseConfigScenes(value) {
     return scene;
   });
 }
-async function readConfigFile(cwd) {
-  const file = configFilePath(cwd);
-  let raw;
+async function tryReadText(file) {
   try {
-    raw = await fs.readFile(file, "utf8");
+    return await fs.readFile(file, "utf8");
   } catch {
-    throw new ConfigError(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6 ${file},\u8BF7\u5148\u8FD0\u884C \`easytwin init\``);
+    return void 0;
   }
-  return parseConfig(raw);
+}
+async function removeLegacyConfigFile(cwd) {
+  try {
+    await fs.unlink(legacyConfigFilePath(cwd));
+  } catch {
+  }
+}
+async function migrateLegacyConfigIfPresent(cwd) {
+  const raw = await tryReadText(legacyConfigFilePath(cwd));
+  if (raw === void 0) return void 0;
+  const config = parseConfig(raw);
+  await writeConfigFile(cwd, config);
+  await removeLegacyConfigFile(cwd);
+  await appendGitignore(cwd);
+  return config;
+}
+async function readConfigFile(cwd) {
+  const file = configFilePath(cwd);
+  const raw = await tryReadText(file);
+  if (raw !== void 0) {
+    const config = parseConfig(raw);
+    await removeLegacyConfigFile(cwd);
+    return config;
+  }
+  const migrated = await migrateLegacyConfigIfPresent(cwd);
+  if (migrated) return migrated;
+  throw new ConfigError(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6 ${file},\u8BF7\u5148\u8FD0\u884C \`easytwin init\``);
 }
 function resolveConfig(file, env = process.env) {
   const appId = env.EASYTWIN_APP_ID ?? file.appId;
@@ -129,12 +181,14 @@ async function writeConfigFile(cwd, config) {
   if (config.baseUrl) body.baseUrl = config.baseUrl;
   if (config.ossUrl) body.ossUrl = config.ossUrl;
   if (config.scenes !== void 0) body.scenes = config.scenes;
-  await fs.mkdir(cwd, { recursive: true });
+  await fs.mkdir(path.dirname(file), { recursive: true });
   await fs.writeFile(file, JSON.stringify(body, null, 2) + "\n", "utf8");
+  await removeLegacyConfigFile(cwd);
   return file;
 }
 var GITIGNORE_FILE_NAME = ".gitignore";
-var GITIGNORE_ENTRY = "easytwin.config.json";
+var GITIGNORE_ENTRY = ".easytwin/easytwin.config.json";
+var GITIGNORE_ENTRIES = [GITIGNORE_ENTRY, ".easytwin/scenes/"];
 async function appendGitignore(cwd) {
   const file = path.join(cwd, GITIGNORE_FILE_NAME);
   let content = "";
@@ -145,9 +199,10 @@ async function appendGitignore(cwd) {
     created = true;
   }
   const lines = content.split(/\r?\n/);
-  if (lines.includes(GITIGNORE_ENTRY)) return { created, added: false };
+  const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) return { created, added: false };
   const prefix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
-  await fs.writeFile(file, content + prefix + GITIGNORE_ENTRY + "\n", "utf8");
+  await fs.writeFile(file, content + prefix + missing.join("\n") + "\n", "utf8");
   return { created, added: true };
 }
 async function initConfig(input, cwd) {
@@ -428,31 +483,165 @@ async function listScenes(client, options = {}) {
   return scenes;
 }
 async function pullScene(client, id, options = {}) {
+  let scene;
   if (client.mock) {
-    const payload2 = await loadExampleScene(options.exampleFile);
-    const sceneId = deriveExampleSceneId(payload2);
+    const payload = await loadExampleScene(options.exampleFile);
+    const sceneId = deriveExampleSceneId(payload);
     if (sceneId !== id) {
       throw new Error(`\u672C\u5730\u6D4B\u8BD5\u6A21\u5F0F:\u793A\u4F8B\u573A\u666F id \u4E3A ${sceneId},\u6536\u5230 ${id}(\u672C\u5730\u4EC5\u63D0\u4F9B ${EXAMPLE_SCENE_FILE} \u8FD9\u4E00\u4E2A\u573A\u666F)`);
     }
-    return { id: sceneId, name: MOCK_SCENE_NAME, payload: payload2 };
-  }
-  const data = await fetchLinkedScenes(client);
-  const scenes = normalizeLinkedScenes(data);
-  const hit = scenes.find((s) => s.sceneKey === id || s.id === id);
-  if (!hit) {
-    const available = scenes.map((s) => s.sceneKey).filter((k) => k.length > 0);
-    throw new Error(
-      available.length > 0 ? `\u672A\u627E\u5230\u573A\u666F ${id}(\u53EF\u7528 Scene Key:${available.join(", ")})` : `\u672A\u627E\u5230\u573A\u666F ${id}`
-    );
+    scene = { id: sceneId, name: MOCK_SCENE_NAME, payload };
+  } else {
+    const data = await fetchLinkedScenes(client);
+    const scenes = normalizeLinkedScenes(data);
+    const hit = scenes.find((s) => s.sceneKey === id || s.id === id);
+    if (!hit) {
+      const available = scenes.map((s) => s.sceneKey).filter((k) => k.length > 0);
+      throw new Error(
+        available.length > 0 ? `\u672A\u627E\u5230\u573A\u666F ${id}(\u53EF\u7528 Scene Key:${available.join(", ")})` : `\u672A\u627E\u5230\u573A\u666F ${id}`
+      );
+    }
+    const payload = await fetchSnapshotJson(client.ossUrl, hit.snapshotUrl);
+    scene = { id: hit.sceneKey, name: hit.name, payload };
   }
-  const payload = await fetchSnapshotJson(client.ossUrl, hit.snapshotUrl);
-  return { id: hit.sceneKey, name: hit.name, payload };
+  if (options.cwd) await saveSceneJson(scene, defaultSceneOutPath(options.cwd, scene.id));
+  return scene;
 }
 async function saveSceneJson(scene, out) {
   await fs2.mkdir(path2.dirname(out), { recursive: true });
   await fs2.writeFile(out, JSON.stringify(scene.payload ?? scene, null, 2) + "\n", "utf8");
   return out;
 }
+function parseSceneStructure(scene) {
+  let data = scene;
+  if (typeof data === "string") {
+    try {
+      data = JSON.parse(data);
+    } catch {
+      return [];
+    }
+  }
+  const root = data ?? {};
+  const objs = Array.isArray(root.objs) ? root.objs : [];
+  const hierarchy = Array.isArray(root.hierarchy) ? root.hierarchy : [];
+  const items = objs.length > 0 ? objs : hierarchy;
+  const typeById = /* @__PURE__ */ new Map();
+  for (const o of objs) {
+    if (typeof o.id === "string" && typeof o.type === "string") typeById.set(o.id, o.type);
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const item of items) {
+    const id = typeof item.id === "string" ? item.id : "";
+    if (id.length === 0 || nodes.has(id)) continue;
+    const name = typeof item.name === "string" && item.name.length > 0 ? item.name : id;
+    nodes.set(id, { id, name, type: typeById.get(id), children: [] });
+    order.push(id);
+  }
+  const childrenOf = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const id = typeof item.id === "string" ? item.id : "";
+    if (id.length === 0 || !nodes.has(id)) continue;
+    const parentId = typeof item.parentObjId === "string" && item.parentObjId.length > 0 ? item.parentObjId : "";
+    if (parentId.length === 0 || parentId === id || !nodes.has(parentId)) continue;
+    const kids = childrenOf.get(parentId) ?? [];
+    kids.push(id);
+    childrenOf.set(parentId, kids);
+  }
+  const isChild = /* @__PURE__ */ new Set();
+  for (const kids of childrenOf.values()) for (const k of kids) isChild.add(k);
+  const build2 = (id, seen) => {
+    const node = nodes.get(id);
+    const children = [];
+    if (!seen.has(id)) {
+      seen.add(id);
+      for (const kid of childrenOf.get(id) ?? []) children.push(build2(kid, seen));
+      seen.delete(id);
+    }
+    return { ...node, children };
+  };
+  return order.filter((id) => !isChild.has(id)).map((id) => build2(id, /* @__PURE__ */ new Set()));
+}
+var INSPECT_NODE_LIMIT = 200;
+var INSPECT_INDENT = "  ";
+function nodeMatchesInspect(node, filter) {
+  if (filter.name !== void 0 && filter.name.length > 0) {
+    if (!node.name.toLowerCase().includes(filter.name.toLowerCase())) return false;
+  }
+  if (filter.type !== void 0 && filter.type.length > 0) {
+    if (node.type !== filter.type) return false;
+  }
+  return true;
+}
+function filterSceneTree(roots, filter = {}) {
+  const hasName = filter.name !== void 0 && filter.name.length > 0;
+  const hasType = filter.type !== void 0 && filter.type.length > 0;
+  if (!hasName && !hasType) return roots;
+  const walk = (node) => {
+    const children = [];
+    for (const child of node.children) {
+      const kept = walk(child);
+      if (kept) children.push(kept);
+    }
+    if (nodeMatchesInspect(node, filter) || children.length > 0) {
+      return { ...node, children };
+    }
+    return void 0;
+  };
+  return roots.flatMap((node) => {
+    const kept = walk(node);
+    return kept ? [kept] : [];
+  });
+}
+function countSceneTreeNodes(roots) {
+  let n = 0;
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      n += 1;
+      walk(node.children);
+    }
+  };
+  walk(roots);
+  return n;
+}
+function formatSceneTree(roots, limit = INSPECT_NODE_LIMIT) {
+  const total = countSceneTreeNodes(roots);
+  if (total === 0) {
+    return { text: "(\u65E0\u5BF9\u8C61\u7ED3\u6784)\n", printed: 0, total: 0, truncated: false };
+  }
+  const lines = [];
+  let printed = 0;
+  const walk = (nodes, depth) => {
+    for (const node of nodes) {
+      if (printed >= limit) return;
+      lines.push(`${INSPECT_INDENT.repeat(depth)}${node.id}	${node.name}	${node.type ?? ""}`);
+      printed += 1;
+      walk(node.children, depth + 1);
+    }
+  };
+  walk(roots, 0);
+  const truncated = printed < total;
+  if (truncated) lines.push(`\u5176\u4F59 ${total - printed} \u4E2A,\u8BF7\u52A0 --name/--type`);
+  return { text: `${lines.join("\n")}
+`, printed, total, truncated };
+}
+async function inspectScene(options) {
+  const file = defaultSceneOutPath(options.cwd, options.id);
+  let raw;
+  try {
+    raw = await fs2.readFile(file, "utf8");
+  } catch {
+    throw new Error(`\u672A\u627E\u5230\u672C\u5730\u573A\u666F\u6587\u4EF6 ${file},\u8BF7\u5148\u8FD0\u884C \`easytwin scene pull ${options.id}\``);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new Error(`\u573A\u666F\u6587\u4EF6\u4E0D\u662F\u5408\u6CD5 JSON:${file}`);
+  }
+  const roots = filterSceneTree(parseSceneStructure(payload), { name: options.name, type: options.type });
+  return { file, roots, ...formatSceneTree(roots, options.limit ?? INSPECT_NODE_LIMIT) };
+}
 
 // src/upload.ts
 import { promises as fs3 } from "fs";
@@ -685,7 +874,9 @@ function defaultPullIgnore(relPath) {
 function isSafeRelPath(relPath) {
   const n = normalizePath(relPath);
   if (!n) return false;
-  if (n.toLowerCase() === "easytwin.config.json") return false;
+  const lower = n.toLowerCase();
+  if (lower === "easytwin.config.json" || lower.endsWith("/easytwin.config.json")) return false;
+  if (lower.split("/")[0] === ".easytwin") return false;
   const base = n.split("/").pop() ?? "";
   if (/^tsconfig(\..+)?\.json$/i.test(base)) return false;
   if (path5.isAbsolute(n) || path5.win32.isAbsolute(n.replace(/\//g, "\\"))) return false;
@@ -939,6 +1130,12 @@ function buildRuntimeTypesContent(sourceDts) {
   return `${sourceDts.replace(/\s+$/, "")}
 `;
 }
+var SkillsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SkillsError";
+  }
+};
 function normalizeTargets(target = "all") {
   if (target === "all") return ["cursor", "claude", "codex", "qoder"];
   if (Array.isArray(target)) return [...new Set(target)];
@@ -951,16 +1148,23 @@ function resolveSkillsSourceDir() {
   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");
+async function fetchRuntimeTypesDts(url, fetchImpl) {
+  let res;
+  try {
+    res = await fetchImpl(url);
+  } catch (err) {
+    throw new SkillsError(
+      `\u62C9\u53D6 @easytwin/runtime \u7C7B\u578B\u5931\u8D25:${url} (${err instanceof Error ? err.message : String(err)})`
+    );
   }
-  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}`);
+  if (!res.ok) {
+    throw new SkillsError(`\u62C9\u53D6 @easytwin/runtime \u7C7B\u578B\u5931\u8D25:HTTP ${res.status} ${url}`);
+  }
+  const text = await res.text();
+  if (text.trim().length === 0) {
+    throw new SkillsError(`\u62C9\u53D6 @easytwin/runtime \u7C7B\u578B\u5931\u8D25:\u7A7A\u54CD\u5E94 ${url}`);
+  }
+  return text;
 }
 async function readJson(file) {
   return JSON.parse(await fs5.readFile(file, "utf8"));
@@ -1047,8 +1251,8 @@ function buildCodexSegment(version) {
     `EasyTwin \u5F00\u53D1\u6280\u80FD(\u7531 @easytwin/devkit v${version} \u540C\u6B65):`,
     "",
     "- `easytwin-develop`:\u5DE5\u4F5C\u6D41\u603B\u7EB2,\u5F00\u59CB EasyTwin \u5F00\u53D1\u524D\u5FC5\u8BFB\u3002",
-    "- `easytwin-bootstrap`:\u521D\u59CB\u5316\u5E94\u7528\u7EA7\u51ED\u8BC1(easytwin.config.json)\u3002",
-    "- `easytwin-scene`:\u5217\u51FA\u573A\u666F\u3001\u62C9\u53D6\u573A\u666F JSON\u3002",
+    "- `easytwin-bootstrap`:\u521D\u59CB\u5316\u5E94\u7528\u7EA7\u51ED\u8BC1(`.easytwin/easytwin.config.json`)\u3002",
+    "- `easytwin-scene`:\u5217\u51FA\u573A\u666F\u3001\u62C9\u53D6\u573A\u666F JSON\u3001inspect \u672C\u5730\u5BF9\u8C61\u6811\u3002",
     "- `easytwin-render`:\u7528 twin runtime \u5F00\u53D1\u6E32\u67D3\u529F\u80FD(\u4E3B\u529B)\u3002",
     "- `easytwin-core`:\u5F15\u64CE\u5185\u6838 API(RuntimeEngine/\u57FA\u7C7B/Time/\u76F8\u673A/\u7269\u7406)\u3002",
     "- `easytwin-upload`:\u62C9\u53D6/\u4E0A\u4F20\u5DE5\u4F5C\u533A\u4EE3\u7801(\u8FDC\u7AEF\u4E3A\u7A7A\u5199\u9ED8\u8BA4\u5165\u53E3;\u4E0A\u4F20\u5168\u91CF\u8986\u76D6\u4E0D\u53EF\u9006)\u3002",
@@ -1087,11 +1291,11 @@ async function syncToCodex(sourceRoot, cwd, version) {
   }
   return { target: "codex", entries: [], codex: { name: "AGENTS.md", action } };
 }
-async function syncRuntimeTypes(cwd, typesSourceFile) {
+async function syncRuntimeTypes(cwd, sourceDts) {
   const destDir = 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"));
+  const content = buildRuntimeTypesContent(sourceDts);
   let runtimeCurrent = "";
   let appsCurrent = "";
   let runtimeExists = true;
@@ -1141,7 +1345,11 @@ async function syncSkills(options) {
     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());
+  const typesSource = options.typesSourceFile ? await fs5.readFile(options.typesSourceFile, "utf8") : await fetchRuntimeTypesDts(
+    await resolveRuntimeTypesUrlForCwd(options.cwd, options.env ?? process.env),
+    options.fetch ?? fetch
+  );
+  const types = await syncRuntimeTypes(options.cwd, typesSource);
   return { summaries, types };
 }
 
@@ -2291,7 +2499,7 @@ async function startPreviewServer(options) {
     }
   }
   const client = new EasyTwinClient(config);
-  const scene = await pullScene(client, sceneId);
+  const scene = await pullScene(client, sceneId, { cwd });
   const tests = await listWorkspaceTests(cwd);
   const hostname = options.hostname ?? DEFAULT_PREVIEW_HOST;
   const log = options.log ?? ((line) => process.stderr.write(`${line}
@@ -2458,16 +2666,17 @@ async function runInit(cwd, flags) {
   if (baseUrlInput.trim().length > 0) input.baseUrl = baseUrlInput.trim();
   const result = await initConfig(input, cwd);
   console.log(`\u5DF2\u751F\u6210 ${result.configFile}`);
+  const gitignoreHint = GITIGNORE_ENTRIES.join("\u3001");
   console.log(
-    result.gitignore.added ? `\u5DF2\u628A ${CONFIG_FILE_NAME} \u8FFD\u52A0\u8FDB .gitignore(\u9632\u6B62\u5BC6\u94A5\u5165\u5E93)` : `.gitignore \u5DF2\u5305\u542B ${CONFIG_FILE_NAME}`
+    result.gitignore.added ? `\u5DF2\u628A ${gitignoreHint} \u8FFD\u52A0\u8FDB .gitignore(\u9632\u6B62\u5BC6\u94A5\u5165\u5E93)` : `.gitignore \u5DF2\u5305\u542B ${gitignoreHint}`
   );
 }
 function buildProgram(cwd, version = "0.0.0") {
   const program = new Command();
   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));
+  program.command("init").description("\u4EA4\u4E92\u5F0F\u751F\u6210 .easytwin/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,\u5E76\u540C\u6B65\u6458\u8981\u5230 easytwin.config.json").action(async () => {
+  scene.command("list").description("\u5217\u51FA\u51ED\u636E\u53EF\u89C1\u7684\u573A\u666F,\u5E76\u540C\u6B65\u6458\u8981\u5230 .easytwin/easytwin.config.json").action(async () => {
     const config = await loadConfig(cwd);
     if (config.mock) console.log(MOCK_MODE_HINT);
     const client = new EasyTwinClient(config);
@@ -2477,17 +2686,21 @@ function buildProgram(cwd, version = "0.0.0") {
     } else {
       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}`);
+    console.log(`\u5DF2\u540C\u6B65 ${scenes.length} \u4E2A\u573A\u666F\u5230 ${EASYTWIN_DIR}/${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) => {
+  scene.command("pull <id>").description("\u62C9\u53D6\u573A\u666F JSON \u5230\u672C\u5730").option("-o, --out <path>", "\u989D\u5916\u8F93\u51FA\u8DEF\u5F84(\u4ECD\u4F1A\u5199\u5165 .easytwin/scenes/<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 ?? path10.join(cwd, `${id}.scene.json`);
-    const file = await saveSceneJson(scene2, out);
+    const scene2 = await pullScene(client, id, { cwd });
+    const out = opts.out;
+    const file = out ? await saveSceneJson(scene2, out) : defaultSceneOutPath(cwd, scene2.id);
     console.log(`\u5DF2\u4FDD\u5B58\u5230 ${file}`);
   });
+  scene.command("inspect <id>").description("\u6253\u5370\u672C\u5730\u573A\u666F\u5BF9\u8C61\u6811(id/name/type),\u4E0D\u8BFB\u5B8C\u6574 JSON").option("--name <substr>", "\u6309\u540D\u79F0\u5B50\u4E32\u8FC7\u6EE4(\u4E0D\u533A\u5206\u5927\u5C0F\u5199)").option("--type <type>", "\u6309\u7EC4\u4EF6 type \u7CBE\u786E\u8FC7\u6EE4").action(async (id, opts) => {
+    const result = await inspectScene({ cwd, id, name: opts.name, type: opts.type });
+    process.stdout.write(result.text);
+  });
   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);