@lingfan-engine/create 0.3.2 → 0.3.4

package/src/generate/project.ts

@@ -14,6 +14,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmSync,
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
@@ -34,6 +35,14 @@ import { restoreDotfile } from "./dotfiles.ts";
 /** 骨架目录名：占位符本身，也是模板里唯一随框架无关的目录 */
 export const SKELETON_DIR = "__PROJECT__";
 
+/**
+ * 目标目录已存在且非空时的处置方式。
+ *
+ * 三种都是使用者在生成前明确选过的，不可省略成「默认覆盖」：覆盖别人的工程
+ * 无法撤销，所以缺省仍是 `cancel`。
+ */
+export type ExistingTarget = "cancel" | "ignore" | "clear";
+
 /** 生成参数 */
 export interface GenerateOptions {
   /** 模板根目录（含 `template-meta.json` 与骨架目录） */
@@ -52,6 +61,8 @@ export interface GenerateOptions {
    * 可选是为了不破坏既有调用方——只关心框架与壳的代码不必为一个用不到的参数改签名。
    */
   readonly sources?: string;
+  /** 目标目录非空时怎么办；缺省 `cancel`（报错退出，不碰磁盘） */
+  readonly existing?: ExistingTarget;
   /** 引擎包的最新版本；缺席项沿用模板记录的值 */
   readonly resolved: ReadonlyMap<string, string>;
 }
@@ -81,19 +92,29 @@ export const DEFAULT_SOURCES = "ts";
 /**
  * 生成一个工程。
  *
- * 只会新建目录：目标已存在且非空时抛错，不做覆盖也不做增量合并——覆盖别人的工程
- * 无法撤销，宁可让使用者先自己删。
+ * 目标目录已存在且非空时按 `options.existing` 处置，缺省 `cancel`——覆盖别人的工程
+ * 无法撤销，所以静默覆盖不是可选项，必须由使用者先表态（见 `ExistingTarget`）。
  */
 export function generateProject(options: GenerateOptions): GenerateResult {
   const meta = readTemplateMeta(options.templateRoot);
-  const projectDir = join(options.targetBase, options.projectName);
-  if (isOccupied(projectDir)) {
+  const projectDir = projectDirOf(options);
+  const occupied = isOccupied(projectDir);
+  const existing = options.existing ?? "cancel";
+  if (occupied && existing === "cancel") {
     throw new Error(`目标目录已存在且非空：${projectDir}`);
   }
+  if (occupied && existing === "clear") {
+    // 清空的是「目录里的内容」而不是目录本身：调用方可能已经把 shell 的 cwd
+    // 放在里面，删掉目录本身会让它指向一个不存在的 inode。
+    for (const entry of readdirSync(projectDir)) {
+      rmSync(join(projectDir, entry), { recursive: true, force: true });
+    }
+  }
   const merged = mergeLayers(layerBases(options));
   const files = finalize(
     merged.files,
     merged.patch,
+    merged.pinned,
     options.resolved,
     meta.placeholder,
     options.projectName,
@@ -139,8 +160,15 @@ export function layerBases(options: GenerateOptions): string[] {
   return bases;
 }
 
+/** 产物目录：`<targetBase>/<projectName>`；单独抽出来供 CLI 在写盘前提示用 */
+export function projectDirOf(
+  options: Pick<GenerateOptions, "targetBase" | "projectName">,
+): string {
+  return join(options.targetBase, options.projectName);
+}
+
 /** 目标目录是否已被占用：存在且含有内容即算占用，空目录可以复用 */
-function isOccupied(dir: string): boolean {
+export function isOccupied(dir: string): boolean {
   if (!existsSync(dir)) return false;
   return readdirSync(dir).length > 0;
 }
@@ -181,10 +209,14 @@ export function collectDependencyNames(bases: readonly string[]): string[] {
  *
  * 点文件还原必须在这里发生：模板里存的是躲开 npm 改名的普通名（见 `dotfiles.ts`），
  * 产物路径要写回带点的形态，占位符替换才按产物路径判文本/二进制。
+ *
+ * `pinned` 由合并层给出而不是在这里从 `patch` 里再读一次：`pinned` 是数组，
+ * 深合并后只剩最后一层的名单，必须用逐层取并集的结果（见 `overlay` 域）。
  */
 export function finalize(
   files: readonly PendingFile[],
   patch: Readonly<Record<string, unknown>> | undefined,
+  pinned: readonly string[],
   resolved: ReadonlyMap<string, string>,
   placeholder: string,
   projectName: string,
@@ -193,7 +225,7 @@ export function finalize(
     const path = restoreDotfile(file.path);
     const content =
       file.path === "package.json"
-        ? renderManifest(file.content, patch, resolved)
+        ? renderManifest(file.content, patch, pinned, resolved)
         : file.content;
     return {
       path,
@@ -212,6 +244,7 @@ export function finalize(
 function renderManifest(
   content: Buffer,
   patch: Readonly<Record<string, unknown>> | undefined,
+  pinned: readonly string[],
   resolved: ReadonlyMap<string, string>,
 ): Buffer {
   const manifest = JSON.parse(content.toString("utf8")) as Record<
@@ -220,14 +253,15 @@ function renderManifest(
   >;
   const withPatch =
     patch === undefined ? manifest : mergeManifest(manifest, patch);
+  applyUnset(withPatch, patch);
   delete withPatch[CREATE_FIELD];
-  const pinned = new Set(pinnedNames(patch));
+  const pinnedSet = new Set(pinned);
   for (const field of ["dependencies", "devDependencies"] as const) {
     const table = withPatch[field];
     if (isStringMap(table)) {
       withPatch[field] = applyResolvedVersions(
         table,
-        withoutNames(resolved, pinned),
+        withoutNames(resolved, pinnedSet),
       );
     }
   }
@@ -272,21 +306,34 @@ function mergeManifest(
 const CREATE_FIELD = "create";
 
 /**
- * 读叠加层声明的「不要跟最新版」的依赖名。
+ * 把增量点名的清单键抹掉。
  *
- * 存在的理由：模板希望依赖尽量新，但上游并非都兼容——`vue-tsc` 在 `typescript` 7 上
- * 会因 `./lib/tsc` 不再导出而直接崩，这类约束只有模板作者知道。钉住的包保留模板
- * 记录的版本区间，其余照常解析到最新。
- */
-export function pinnedNames(
+ * `mergeManifest` 只合并键、不删键，所以 `scripts` 与 `devDependencies` 这类表
+ * 在叠加层里只能增不能减。可反向叠加层需要的正是减法：故事文件形态摘掉骨架的
+ * TS 创作链之后，配套的三条脚本与创作期依赖也应当一起消失，否则产物里留着
+ * 一个必然失败的命令。
+ *
+ * 形状与 `create.remove` 并列：外层是 `package.json` 的字段名，内层是要去掉的键名。
+ * 缺省项不必写它——缺省形态什么都不叠，本来就没有要减的东西。
+ */ function applyUnset(
+  manifest: Record<string, unknown>,
   patch: Readonly<Record<string, unknown>> | undefined,
-): string[] {
-  if (patch === undefined) return [];
+): void {
+  if (patch === undefined) return;
   const section = patch[CREATE_FIELD];
-  if (!isPlainRecord(section)) return [];
-  const pinned = section.pinned;
-  if (!Array.isArray(pinned)) return [];
-  return pinned.filter((item): item is string => typeof item === "string");
+  if (!isPlainRecord(section)) return;
+  const unset = section.unset;
+  if (!isPlainRecord(unset)) return;
+  for (const [field, keys] of Object.entries(unset)) {
+    if (!Array.isArray(keys)) continue;
+    const table = manifest[field];
+    if (!isPlainRecord(table)) continue;
+    const next: Record<string, unknown> = { ...table };
+    for (const key of keys) {
+      if (typeof key === "string") delete next[key];
+    }
+    manifest[field] = next;
+  }
 }
 
 /** 只认普通对象：数组与 null 不算 */

package/src/overlay/index.ts

@@ -3,6 +3,7 @@ export {
   deepMerge,
   listFiles,
   mergeLayers,
+  pinnedNames,
   readLayer,
   PATCH_SUFFIX,
   type MergedLayer,

package/src/overlay/merge.ts

@@ -132,10 +132,33 @@ function isRemoved(path: string, removes: readonly string[]): boolean {
   );
 }
 
-/** 合并结果：文件表（后写覆盖先写）+ 合并后的工程清单增量 */
+/** 合并结果：文件表（后写覆盖先写）+ 合并后的工程清单增量 + 各层钉住的依赖名并集 */
 export interface MergedLayer {
   readonly files: readonly PendingFile[];
   readonly patch: Readonly<Record<string, unknown>> | undefined;
+  readonly pinned: readonly string[];
+}
+
+/**
+ * 读本层 `create.pinned` 点名的依赖名。
+ *
+ * 与 `removeList` 同理，必须**每层各读一次**：`pinned` 是数组，深合并时由后者整体
+ * 取代，两层各钉各的包，合并后只剩最后一层的名单——`vue` 钉了 `typescript`、
+ * `tauri` 钉了 `@tauri-apps/*`，后者在后就把前者的钉法抹掉，于是 `vue-tsc` 拿到
+ * 了它不兼容的 typescript 大版本，`typecheck` 直接崩。
+ *
+ * 与 `remove` 不同的是，钉住是**累加声明**（每个层都在说「这几个包别跟最新」），
+ * 所以合并语义是并集而不是逐层施加的动作。
+ */
+export function pinnedNames(
+  patch: Readonly<Record<string, unknown>> | undefined,
+): readonly string[] {
+  if (patch === undefined) return [];
+  const section = patch[CREATE_FIELD];
+  if (!isPlainObject(section)) return [];
+  const raw = section.pinned;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((item): item is string => typeof item === "string");
 }
 
 /**
@@ -149,6 +172,7 @@ export function mergeLayers(bases: readonly string[]): MergedLayer {
   const byPath = new Map<string, PendingFile>();
   let patch: Record<string, unknown> = {};
   let hasPatch = false;
+  const pinned = new Set<string>();
   for (const base of bases) {
     if (!existsSync(base)) continue;
     const layer = readLayer(base);
@@ -158,6 +182,7 @@ export function mergeLayers(bases: readonly string[]): MergedLayer {
       }
     }
     for (const file of layer.files) byPath.set(file.path, file);
+    for (const name of pinnedNames(layer.patch)) pinned.add(name);
     if (layer.patch) {
       patch = deepMerge(patch, layer.patch);
       hasPatch = true;
@@ -166,6 +191,7 @@ export function mergeLayers(bases: readonly string[]): MergedLayer {
   return {
     files: [...byPath.values()],
     patch: hasPatch ? patch : undefined,
+    pinned: [...pinned],
   };
 }
 

package/src/shared/index.ts

@@ -1,10 +1,17 @@
-/** shared 域唯一出口：文案表、参数校验与版本运算。 */
+/** shared 域唯一出口：文案表、参数校验、包管理器识别与版本运算。 */
 export { defaultCreateTexts, type CreateTexts } from "./texts.ts";
 export {
   caretRange,
   isValidProjectName,
   suggestProjectName,
 } from "./guards.ts";
+export {
+  currentPackageManager,
+  detectPackageManager,
+  parsePackageManager,
+  type PackageManager,
+  type PackageManagerId,
+} from "./package-manager.ts";
 export {
   compareSemver,
   floorOfRange,

package/src/shared/package-manager.ts

@@ -0,0 +1,87 @@
+/**
+ * 包管理器识别。
+ *
+ * 为什么需要识别：生成器是给**别人**用的工具，不能假定对方用 pnpm。安装依赖与
+ * 打印后续步骤都要跟随调用方的包管理器——`npm create` 就该给出 npm 的命令，
+ * `pnpm create` 给出 pnpm 的。本仓内部开发固定 pnpm 是仓库约定，不是产物约定。
+ *
+ * 识别依据是 npm 生态的既定事实 `npm_config_user_agent`（`npm create` /
+ * `pnpm create` / `yarn create` / `bun create` 都会设置它）。拿不到时退回
+ * `npm_execpath` 的文件名，再拿不到按 npm 处理——这是最不会误导人的缺省，
+ * 因为 npm 的命令形式（`npm run dev`）在 pnpm/yarn 下也基本能跑。
+ */
+
+/** 生成器认得的包管理器；不认识的都按 npm 处理 */
+export type PackageManagerId = "npm" | "pnpm" | "yarn" | "bun";
+
+/** 一个包管理器的命令写法 */
+export interface PackageManager {
+  readonly id: PackageManagerId;
+  /** 跑一个 `package.json` 脚本的写法，如 `dev` / `run dev` */
+  readonly script: string;
+  /** 安装依赖的写法（四家都是 `install`，保留字段是为了日后出现例外时有落点） */
+  readonly install: string;
+}
+
+const MANAGERS: Readonly<Record<PackageManagerId, PackageManager>> = {
+  npm: { id: "npm", script: "run dev", install: "install" },
+  pnpm: { id: "pnpm", script: "dev", install: "install" },
+  yarn: { id: "yarn", script: "dev", install: "install" },
+  bun: { id: "bun", script: "run dev", install: "install" },
+};
+
+const KNOWN = ["npm", "pnpm", "yarn", "bun"] as const;
+
+/** 把一段文本折成包管理器名：去扩展名、去版本尾缀 */
+function normalize(segment: string): PackageManagerId | undefined {
+  const name = segment
+    .toLowerCase()
+    .replace(/\.(?:c|m)?js$|\.exe$/u, "")
+    .split("@")[0];
+  return KNOWN.find((id) => id === name);
+}
+
+/**
+ * 从 `user-agent` 或可执行路径里认出包管理器。
+ *
+ * 两种输入形态不同，故首段与末段都试：`user-agent` 是
+ * `pm/版本 平台/…`（首段有名），可执行路径是 `/usr/local/bin/pm.cjs`
+ * （末段有名，首段是空串或盘符）。取第一个认得出的。
+ */
+export function parsePackageManager(
+  hint: string | undefined,
+): PackageManagerId | undefined {
+  if (hint === undefined) return undefined;
+  const segments = hint.split(/[/\\]/u).filter((part) => part !== "");
+  for (const segment of [segments[0], segments[segments.length - 1]]) {
+    if (segment === undefined) continue;
+    const found = normalize(segment);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+/**
+ * 当前进程由哪个包管理器发起。
+ *
+ * 优先级：`npm_config_user_agent`（最权威，四家都会设）→ `npm_execpath`
+ * （垫片被直接 `node` 调用时的退路）→ npm（缺省）。
+ */
+export function detectPackageManager(env: {
+  readonly userAgent?: string | undefined;
+  readonly execPath?: string | undefined;
+}): PackageManager {
+  const id =
+    parsePackageManager(env.userAgent) ??
+    parsePackageManager(env.execPath) ??
+    "npm";
+  return MANAGERS[id];
+}
+
+/** 从真实进程环境里取一个 */
+export function currentPackageManager(): PackageManager {
+  return detectPackageManager({
+    userAgent: process.env.npm_config_user_agent,
+    execPath: process.env.npm_execpath,
+  });
+}

package/src/shared/texts.ts

@@ -13,47 +13,57 @@ export const defaultCreateTexts = {
     "用法：",
     "  npm create @lingfan-engine [工程名] [选项]",
     "  pnpm create @lingfan-engine [工程名] [选项]",
+    "  yarn create @lingfan-engine [工程名] [选项]",
     "",
+    "包管理器不限：生成后的安装命令与后续步骤按调用方自己的包管理器给出。",
     "选项：",
+    "  --template <id>       一次性指定形态，写作 框架[-壳[-故事源]]，如 vue-tauri",
     "  -f, --framework <id>  框架（缺省取模板声明的默认值）",
     "  -s, --shell <id>      壳（缺省取模板声明的默认值）",
-    "  -t, --sources <id>    故事源形态（缺省取模板声明的默认值）",
+    "  -t, --sources <id>    故事源形态（缺省 ts，一般不必指定）",
     "  -d, --dir <路径>      生成到哪个目录下（缺省 = 当前目录）",
-    "      --no-install      生成后不自动安装依赖",
+    "      --install         生成后立即安装依赖",
+    "      --overwrite       目标目录非空时清空后继续",
     "  -y, --yes             全部取缺省值，不进入交互问答",
     "  -h, --help            显示本说明",
     "",
     "示例：",
-    "  npm create @lingfan-engine my-story -- --framework vue --shell browser",
-    "  npm create @lingfan-engine my-story -- --sources ts",
+    "  npm create @lingfan-engine my-story -- --template vue-browser",
+    "  npm create @lingfan-engine my-story -- --template vue-tauri --install",
   ].join("\n"),
   /** 交互问答的提示语 */
   promptProjectName: "工程名",
   promptFramework: "框架",
   promptShell: "壳",
-  promptSources: "故事源形态",
-  promptInstall: "生成后立即安装依赖？",
+  promptExisting: "目标目录已存在且有内容，怎么处理",
   /** 参数校验失败 */
   nameRequired: "工程名不能为空",
   nameInvalid:
     "工程名只能包含小写字母、数字、连字符与下划线，且不能以点或连字符开头",
-  dirMissing: "目标目录不存在",
   frameworkUnknown: "未知框架",
   shellUnknown: "未知壳",
   sourcesUnknown: "未知故事源形态",
-  overlayMissing: "模板缺少该选项对应的叠加层",
-  targetExists: "目标目录已存在且非空",
+  templateMalformed: "形态写法不对，应为 框架[-壳[-故事源]]",
+  /** 目标目录已存在时的三种处置 */
+  existingIgnore: "保留现有文件，同名覆盖",
+  existingIgnoreHint: "只写本模板的文件，别的东西原地不动",
+  existingClear: "清空目录后生成",
+  existingClearHint: "删掉目录里的全部内容，不可撤销",
+  existingCancel: "取消",
+  existingCancelHint: "什么都不做，退出",
+  targetExists: "目标目录已存在且非空，未做任何改动",
   templateMissing: "找不到模板目录：本包未随附模板内容，或开发态仓库结构不完整",
   /** 生成过程 */
   stageResolve: "解析模板与版本…",
   stageCopy: "写入工程文件…",
   stageInstall: "安装依赖…",
   doneTitle: "工程已生成",
-  nextSteps: ["cd <name>", "pnpm install", "pnpm dev"].join("\n"),
+  /** 生成后的三步提示；`<install>` / `<dev>` 由调用方按包管理器替换 */
+  nextSteps: ["cd <name>", "<install>", "<dev>"].join("\n"),
   /** 非致命提示 */
   warnVersionOffline:
     "无法查询 npm registry 上的最新版本，已沿用模板记录的版本",
-  warnInstallFailed: "依赖安装失败，请在工程目录内手动执行 pnpm install",
+  warnInstallFailed: "依赖安装失败，请在工程目录内手动安装依赖",
 } as const;
 
 export type CreateTexts = typeof defaultCreateTexts;

package/template/README.md

@@ -41,27 +41,31 @@ npm create @lingfan-engine my-story
 pnpm create @lingfan-engine my-story
 ```
 
-生成器会问四件事：工程名、框架、故事源形态、壳。当前框架可选「原生（框架无关）」「Vue 3」「React」，
-故事源形态可选「故事文件（`.story`）」与「TypeScript 源（`Stories.src/`）」，
-壳可选「浏览器」「小程序（UniApp）」与「桌面（Tauri 2）」。全部取缺省值（原生 + 故事文件 + 浏览器）可以跳过问答：
+生成器会问三件事：工程名、框架、壳。当前框架可选「原生（框架无关）」「Vue 3」「React」，
+壳可选「浏览器」「小程序（UniApp）」与「桌面（Tauri 2）」。故事源形态不是问题——骨架自带整条 TS 创作链，
+它就是缺省形态；要手写 `.story` 文件用 `--sources story` 指定。全部取缺省值（原生 + TypeScript 源 + 浏览器）可以跳过问答：
 
 ```
 npm create @lingfan-engine my-story -- --yes
 ```
 
-生成后按提示 `cd my-story && pnpm install && pnpm dev`。选了 TypeScript 源形态的，
-`pnpm dev` 之前先跑一次 `pnpm stories:build`（模板已带产物，改过源之后才需要）。
+生成后按提示进目录、装依赖、跑起来。生成器不指定包管理器——它按启动自己的那个（npm / pnpm / yarn / bun）给出命令，用哪个都行。骨架自带编译好的故事产物，开箱即跑；
+改过 `src/Stories.src/` 之后才需要跑一次 `pnpm stories:build`（或在开发时挂 `pnpm stories:watch`）。
+生成器默认不装依赖，想一步到位加 `--install`。
 
-想不开交互问答、直接指定框架与壳：
+想不开交互问答、一次指定形态（写作 `框架[-壳[-故事源]]`）：
 
 ```
-npm create @lingfan-engine my-story -- --framework vue --shell browser
-npm create @lingfan-engine my-story -- --framework react --shell browser
-npm create @lingfan-engine my-story -- --shell miniprogram
-npm create @lingfan-engine my-story -- --framework vue --shell tauri
-npm create @lingfan-engine my-story -- --sources ts
+npm create @lingfan-engine my-story -- --template vue-browser
+npm create @lingfan-engine my-story -- --template react-browser
+npm create @lingfan-engine my-story -- --template none-miniprogram
+npm create @lingfan-engine my-story -- --template vue-tauri
+npm create @lingfan-engine my-story -- --template none-browser-story
 ```
 
+也可以逐项给：`--framework vue --shell browser`、`--shell miniprogram`、`--sources story`；两者冲突时逐项参数优先。
+目标目录非空时生成器会问怎么处置（保留现有文件 / 清空 / 取消），`--overwrite` 是「清空」的非交互写法。
+
 **框架层只换页面结构与入口，`src/host/**`（装配、订阅、帧循环、输入映射）一行不改，
 样式表仍是同一份 `src/styles/stage.css`**，所以换框架不影响游玩界面的外观口径，
 也不影响引擎与适配器——它们不认识任何 UI 框架。选 Vue 3 是 `index.html` 换成挂载点、
@@ -71,12 +75,15 @@ npm create @lingfan-engine my-story -- --sources ts
 壳层与框架层可以叠加（先框架后壳）：`--framework react --shell tauri` 得到 React 页面 + 桌面外壳。
 小程序是例外——它自带 Vue 页面层，不与其他框架层叠加。
 
-**故事源形态层与框架层、壳层正交**，只决定故事从哪来：缺省形态直接改 `Resources/Stories/**/*.story`；
-`ts` 形态改 `Stories.src/**/*.ts` 再跑构建，产物是 `Resources/Stories/**/*.json`。后者会删掉骨架那份
-手写故事（层里声明 `create.remove: ["Resources/Stories"]`），再补上开箱可跑的生成物与三条脚本
-（`stories:build` / `stories:watch` / `stories-typecheck`）。产物目录由构建**全量管理**——源里没有的列
-构建会当陈旧列删掉，所以别在产物目录里手改；类型检查走独立的 `tsconfig.stories.json`（故事源有 ambient
-全局，不该和页面 DOM 类型面混在一个工程里）。
+**故事源形态层与框架层、壳层正交**，只决定故事从哪来。缺省形态是 **TypeScript 源**，整条链在骨架里：
+改 `src/Stories.src/**/*.ts`，跑 `pnpm stories:build` 编译成 `Resources/Stories/**/*.json`。产物目录由构建
+**全量管理**——源里没有的列构建会当陈旧列删掉，所以别在产物目录里手改；类型检查走独立的
+`tsconfig.stories.json`（故事源有 ambient 全局，不该和页面 DOM 类型面混在一个工程里）。骨架自带三条脚本
+（`stories:build` / `stories:watch` / `stories-typecheck`）与开箱可跑的产物，`pnpm dev` 不必先构建。
+
+选「故事文件（`.story`）」则是**反向叠加**：`overlays/story/` 用 `create.remove` 摘掉骨架的整条 TS 创作链
+（`src/Stories.src`、`src/gen/*.gen.d.ts`、`tsconfig.stories.json`），换上一份手写的
+`Resources/Stories/title/title_main.story`，改完保存即生效。这条形态的产物目录里可以 `.story` 与 `.json` 混存。
 
 **壳层是换一整套页面与宿主**：小程序形态的页面结构由 `src/components/**` 承接，宿主装配在
 `src/mp/**`（`uni.*` 只在 `src/mp/platform.ts` 出现一处），内容不进包体、走工程接口按基址取。
@@ -94,8 +101,9 @@ npm create @lingfan-engine my-story -- --sources ts
 
 模板依赖三个引擎包：`@lingfan-engine/core`（核心）、`@lingfan-engine/adapters`（预设适配器）、`@lingfan-engine/ui`（参考展示层）。
 它们以 **TS 源码出口**（`exports: "./src/index.ts"`）发布——消费方由 Vite/TS 直接编译，**无中间构建步骤**，
-`pnpm install` 直接可用。选了 TypeScript 源形态的工程会多两个创作期依赖
-（`@lingfan-engine/stories-build` 与 `@lingfan-engine/editor`），由 `ts` 层自己声明。
+`pnpm install` 直接可用。骨架还声明两个创作期依赖（`@lingfan-engine/stories-build` 与
+`@lingfan-engine/editor`）——缺省故事源形态是 TS，这条链归骨架；选「故事文件」形态时
+`overlays/story/` 会把链上的文件、脚本与依赖条目一并摘掉（见下文叠加层说明）。
 
 ## 工程结构（单资源根）
 
@@ -106,6 +114,7 @@ __PROJECT__/
 ├── pnpm-workspace.yaml   # 只声明 allowBuilds：pnpm 12 起「未批准的构建脚本」是硬错误
 ├── tsconfig.json         # 浏览器侧：src/ 下的 ts 与 vue
 ├── tsconfig.node.json    # Node 侧：vite.config.ts 与 vite.plugins.ts（要 node:fs 与 @types/node）
+├── tsconfig.stories.json # 故事源独立工程：查 src/Stories.src/ 与 src/gen/ 的类型面（纯 tsc，不带页面 DOM 类型面）
 ├── vite.config.ts        # publicDir: "Resources" ← 资源根即静态根
 ├── vite.plugins.ts       # 构建期扫描：故事清单与字体清单（虚拟模块，层只换插件数组）
 ├── index.html            # RenderTargets 落地：stage/dialogue/choices/notifications/toolbar（+ 可选 #prefs / #mounts）
@@ -113,7 +122,8 @@ __PROJECT__/
 ├── src/stories/          # 故事清单出口（转发 virtual:story-list；清单本身来自磁盘扫描）
 ├── src/mounts.ts         # 挂载表出口 + mountStore（框架形态从这里订阅挂载值）
 ├── src/controls/         # 宿主控制面出口：挂载 UI 拿 pause/navigate/save/load 的地方
-├── src/gen/              # 构建生成物：清单、字体、守卫表、UI 注册表（手改会被覆盖）
+├── src/Stories.src/      # 故事源（TS 创作链）：config.ts 声明章节与入口，一函数 = 一列
+├── src/gen/              # 构建生成物：故事类型面、字体、守卫表、UI 注册表（手改会被覆盖）
 ├── src/ui/               # 可挂载界面（`<名>/<名>.<扩展名>`，可缺省：没有就不生成注册表）
 ├── src/host/             # 宿主：装配、订阅、帧循环、输入映射、挂载层与面板（不认识 UI 框架）
 │   ├── mount/            #   UI 挂载层（原生形态）：差量渲染器 + 工厂表契约
@@ -121,7 +131,7 @@ __PROJECT__/
 ├── src/styles/stage.css  # 页面与层样式（换框架不动这份：叠加层共用同一张表）
 └── Resources/            # 故事工程根（自包含、可整体搬运）
     ├── project.json      #   工程清单：id/name/entry/lang/formatVersion
-    ├── Stories/          #   故事（JSON v1 / .story 混存合法）
+    ├── Stories/          #   故事产物（构建全量管理；故事文件形态下可 .story 与 .json 混存）
     ├── Audio/  Images/  Video/
     ├── Lang/{lang}/      #   I18N overlay
     └── Saves/            #   运行期产物（不入 git）
@@ -175,8 +185,9 @@ pwsh -File pack-template.ps1 -SourceDir ./__PROJECT__ -OutputFile ./__PROJECT__.
 
 `template-meta.json` 的 `frameworks` / `sources` / `shells` 声明生成器会问哪些选项，每项的 `id` 对应
 `overlays/<id>/` 目录：同路径文件**覆盖**骨架，根目录的 `*.patch.json` **深合并**进 `package.json`，
-其中 `create.remove` 列出本层要删掉的骨架路径（换形态时清残留）。缺省项（`none` / `story` / `browser`）
-没有目录，表示「这一层什么都不加」，不是错误。合并顺序固定为「骨架 → 框架 → 故事源 → 壳」：
+其中 `create.remove` 列出本层要删掉的骨架路径（换形态时清残留）。缺省项（`none` / `ts` / `browser`）
+没有目录，表示「这一层什么都不加」，不是错误——缺省故事源 `ts` 正是如此：整条创作链在骨架里，
+没有叠加层可加。`story` 反过来是「摘掉骨架的 TS 链、换上手写故事」，所以它有目录。合并顺序固定为「骨架 → 框架 → 故事源 → 壳」：
 故事源要晚于框架层才能把各框架入口的故事表指向生成物；壳放最后，因为它对工程形态有最终发言权。
 
 骨架里的占位符有两种大小写形态：`__PROJECT__`（清单 id/name、页面标题、目录名）与

package/template/__PROJECT__/package.json

@@ -7,6 +7,9 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "stories:build": "lingfan-stories-build .",
+    "stories:watch": "lingfan-stories-watch .",
+    "stories-typecheck": "tsc --noEmit -p tsconfig.stories.json",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json"
   },
   "dependencies": {
@@ -14,9 +17,11 @@
     "@lingfan-engine/core": "^0.3.2",
     "@lingfan-engine/shell": "^0.3.2",
     "@lingfan-engine/stories-build": "^0.3.2",
-    "@lingfan-engine/ui": "^0.3.2"
+    "@lingfan-engine/ui": "^0.3.2",
+    "@tauri-apps/api": "^2"
   },
   "devDependencies": {
+    "@lingfan-engine/editor": "^0.3.2",
     "@types/node": "^26.6.3",
     "typescript": "~6.0.3",
     "vite": "^8.0.16"

package/template/__PROJECT__/package.patch.json

@@ -0,0 +1,5 @@
+{
+  "create": {
+    "pinned": ["typescript"]
+  }
+}

package/template/__PROJECT__/src/host/index.ts

@@ -39,6 +39,7 @@ export {
   type NativeUiTable,
 } from "./mount/index";
 export { wireEngine, type HostWiringOptions } from "./engine-wiring";
+export { createNativePorts, isTauriHosted } from "./native-ports";
 export { startHostFrameLoop, type HostFrameLoopOptions } from "./frame-loop";
 export { wireInput, type HostInputOptions } from "./input-map";
 export {

package/template/__PROJECT__/src/host/native-ports.ts

@@ -0,0 +1,56 @@
+/**
+ * 原生宿主端口：让同一份工程既能跑在浏览器里，也能被桌面壳加载。
+ *
+ * 为什么判定放在这里而不是壳层：`tauri` 叠加层只补 `src-tauri/` 与清单补丁，
+ * 页面结构与组合根永远归属框架层。若壳层自己带一份组合根，`vue`/`react` 形态的
+ * 页面节点就不再与那份组合根同源。所以「是否需要原生端口」由运行时事实判定，
+ * 各形态的组合根都调同一个函数。
+ *
+ * 为什么用运行时判定：`tauri dev` 时页面可能被外部浏览器打开，构建期开关会判错。
+ * `__TAURI_INTERNALS__` 只由真实 WebView 注入，是此刻唯一可靠的事实。
+ *
+ * 为什么模块名写在这里：打包器按字面量说明符静态解析（所以本工程必须声明
+ * `@tauri-apps/api`），而适配器包不出现该模块名，浏览器与小程序形态才能在
+ * 没有它时也装得上。非壳形态直接返回 `undefined`，动态导入一次都不会发生。
+ */
+import {
+  createTauriSavePort,
+  type TauriInvoke,
+} from "@lingfan-engine/adapters";
+import type { BootPortOverrides } from "./boot";
+
+/** 当前页面是否由桌面壳加载（只有真实 WebView 会注入 `__TAURI_INTERNALS__`） */
+export function isTauriHosted(): boolean {
+  return typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+}
+
+/**
+ * 惰性 invoke：首次真正调用存档命令时才装载 `@tauri-apps/api/core`。
+ *
+ * 不在启动路径上 await 是刻意的——存档端口是同步构造的，而装载要等模块解析；
+ * 把等待推迟到第一次读写，启动时序与浏览器形态完全一致。装载失败会原样抛给
+ * 调用方，由存档流程的既有错误处理呈现，不会变成静默失败。
+ */
+function createLazyInvoke(): TauriInvoke {
+  let loading: Promise<TauriInvoke> | undefined;
+  return async (command, args) => {
+    loading ??= import("@tauri-apps/api/core").then((module) => {
+      const loaded: TauriInvoke = (name, payload) =>
+        module.invoke(name, payload);
+      return loaded;
+    });
+    const invoke = await loading;
+    return invoke(command, args);
+  };
+}
+
+/**
+ * 按运行时事实给出端口覆盖；非桌面壳形态返回 `undefined`。
+ *
+ * 现在只换存档（`localStorage` 落在 WebView 数据目录，清缓存、换账户、重装都会
+ * 带走存档）。其余端口沿用 `bootHost` 的 Web 缺省实现，随需要再加。
+ */
+export function createNativePorts(): BootPortOverrides | undefined {
+  if (!isTauriHosted()) return undefined;
+  return { saves: createTauriSavePort(createLazyInvoke()) };
+}