@longzai-intelligence-templates/template-engine 0.0.5

package/.turbo/turbo-build$colon$prod.log

@@ -0,0 +1,5 @@
+$ NODE_ENV=production bun run build
+$ lzi-builder
+ℹ lzi-builder v0.2.13 powered by rolldown v1.2.2
+ℹ @longzai-intelligence-templates/template-engine tsconfig: tsconfig/build.json
+TypeScript 7.0 尚未提供稳定的 API，仍处于实验阶段。部分选项将不可用。

package/.turbo/turbo-build.log

@@ -0,0 +1,33 @@
+$ lzi-builder
+ℹ lzi-builder v0.2.13 powered by rolldown v1.2.2
+ℹ @longzai-intelligence-templates/template-engine tsconfig: tsconfig/build.json
+TypeScript 7.0 尚未提供稳定的 API，仍处于实验阶段。部分选项将不可用。
+
+ ERROR  Error: Build failed with 2 errors:
+
+[MISSING_EXPORT] "TemplateCategory" is not exported by "src/template.schema.ts".
+   ╭─[ src/index.ts:9:3 ]
+   │
+ 9 │   TemplateCategory,
+   │   ────────┬───────  
+   │           ╰───────── Missing export
+   │ 
+   │ Note: If you meant to import a type rather than a value, make sure to add the `type` modifier (e.g. `import { type Foo } from './template.schema'`).
+───╯
+
+[MISSING_EXPORT] "VariableType" is not exported by "src/template.schema.ts".
+    ╭─[ src/index.ts:10:3 ]
+    │
+ 10 │   VariableType,
+    │   ──────┬─────  
+    │         ╰─────── Missing export
+    │ 
+    │ Note: If you meant to import a type rather than a value, make sure to add the `type` modifier (e.g. `import { type Foo } from './template.schema'`).
+────╯
+
+    at aggregateBindingErrorsIntoJsError (/Volumes/JZAO/j-projects/workspaces/longzai/longzai-intelligence/longzai-intelligence-m5-edition/.lzi/bun/store/links/rolldown@1.2.2-8934269c46bb2da1/node_modules/rolldown/dist/shared/error-nLggAzpQ.mjs:48:22)
+    at unwrapBindingResult (/Volumes/JZAO/j-projects/workspaces/longzai/longzai-intelligence/longzai-intelligence-m5-edition/.lzi/bun/store/links/rolldown@1.2.2-8934269c46bb2da1/node_modules/rolldown/dist/shared/error-nLggAzpQ.mjs:18:128)
+    at #build (/Volumes/JZAO/j-projects/workspaces/longzai/longzai-intelligence/longzai-intelligence-m5-edition/.lzi/bun/store/links/rolldown@1.2.2-8934269c46bb2da1/node_modules/rolldown/dist/shared/rolldown-D23fYgSS.mjs:132:34)
+    at processTicksAndRejections (native:7:39)
+
+error: script "build" exited with code 1

package/.turbo/turbo-lint.log

@@ -0,0 +1,11 @@
+$ oxlint && oxfmt --check
+Found 0 warnings and 0 errors.
+Finished in 792ms on 8 files with 186 rules using 10 threads.
+(node:45992) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///Volumes/JZAO/j-projects/workspaces/longzai/longzai-intelligence/longzai-intelligence-m5-edition/longzai-intelligence-templates/oxfmt.config.ts?cache=1790354605913 is not specified and it doesn't parse as CommonJS.
+Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
+To eliminate this warning, add "type": "module" to /Volumes/JZAO/j-projects/workspaces/longzai/longzai-intelligence/longzai-intelligence-m5-edition/longzai-intelligence-templates/package.json.
+(Use `node --trace-warnings ...` to show where the warning was created)
+Checking formatting...
+
+All matched files use the correct format.
+Finished in 601ms on 16 files using 10 threads.

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,4 @@
+$ bun run typecheck:app && bun run typecheck:node && bun run typecheck:test
+$ lzi-tsgo typecheck tsconfig/app.json
+$ lzi-tsgo typecheck tsconfig/node.json
+$ lzi-tsgo typecheck tsconfig/test.json

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# 更新日志
+
+本项目的所有重要更改都将记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.0.5] - 2026-10-04
+
+### 变更
+
+- 升级 @longzai-intelligence-templates/template-engine 至 0.0.5
+
+## [0.0.4] - 2026-10-04
+
+### 修复
+
+- 修复模板引擎入口将纯类型按值导出导致的模块加载错误
+- 修复模板加载在分类目录缺失时的崩溃，缺失分类改为静默跳过
+
+## [0.0.3] - 2026-10-03
+
+### 变更
+
+- 升级 @longzai-intelligence-templates/template-engine 至 0.0.3
+
+## [0.0.2] - 2026-10-03
+
+### 变更
+
+- 升级 @longzai-intelligence-templates/template-engine 至 0.0.2
+
+## [0.0.1] - 2026-10-02
+
+### 新增
+
+- 新增模板引擎核心包，提供变量替换、文件生成与模板加载能力
+
+### 变更
+
+- 重构模板引擎模块结构与导出组织
+- 模板元数据校验失败时抛出携带路径与校验详情的错误
+- 批量加载模板时跳过校验未通过的模板

package/README.md

@@ -0,0 +1,15 @@
+# @longzai-intelligence-templates/template-engine
+
+Longzai Intelligence Templates 的模板引擎核心包，为模板浏览与生成应用提供变量替换、文件生成与模板加载能力。
+
+## 简介
+
+治理模板生成中的变量处理与模板加载问题：预置模板中的占位变量需经统一解析、校验与合并后方可生成目标文件，模板元数据、模板分类与模板文件需要统一的 Schema 与类型约束，生成目标路径需要从模板路径统一解析——本包作为模板产品的核心引擎层承载这些约束，供模板浏览与生成应用直接引用。
+
+## 能力
+
+- 模板变量替换：变量解析、变量校验、内置变量构建与变量合并
+- 目标路径解析：模板文件路径到生成目标路径的统一映射
+- 模板加载：模板元数据加载、全量模板加载、模板文件读取、分类过滤、搜索与按 ID 查找
+- 预览与文件生成：生成前预览与目标文件生成
+- Schema 与类型定义：模板元数据、模板分类、变量类型、模板变量与模板文件

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+import * as z from "zod";
+//#region src/template.schema.d.ts
+/**
+ * 模板分类枚举 Schema
+ */
+declare const TemplateCategorySchema: z.ZodEnum<{
+  adapter: "adapter";
+  app: "app";
+  config: "config";
+  docs: "docs";
+  domain: "domain";
+  package: "package";
+  project: "project";
+}>;
+/**
+ * 模板分类类型
+ */
+type TemplateCategory = z.infer<typeof TemplateCategorySchema>;
+/**
+ * 模板变量类型枚举 Schema
+ */
+declare const VariableTypeSchema: z.ZodEnum<{
+  boolean: "boolean";
+  select: "select";
+  string: "string";
+}>;
+/**
+ * 模板变量类型
+ */
+type VariableType = z.infer<typeof VariableTypeSchema>;
+/**
+ * 模板变量定义 Schema
+ */
+declare const TemplateVariableSchema: z.ZodObject<{
+  name: z.ZodString;
+  type: z.ZodEnum<{
+    boolean: "boolean";
+    select: "select";
+    string: "string";
+  }>;
+  description: z.ZodString;
+  defaultValue: z.ZodOptional<z.ZodString>;
+  required: z.ZodDefault<z.ZodBoolean>;
+  options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodString;
+  }, z.core.$strip>>>;
+  pattern: z.ZodOptional<z.ZodString>;
+  patternMessage: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 模板变量定义类型
+ */
+type TemplateVariable = z.infer<typeof TemplateVariableSchema>;
+/**
+ * 模板文件定义 Schema
+ */
+declare const TemplateFileSchema: z.ZodObject<{
+  source: z.ZodString;
+  destination: z.ZodString;
+  executable: z.ZodDefault<z.ZodBoolean>;
+  condition: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 模板文件定义类型
+ */
+type TemplateFile = z.infer<typeof TemplateFileSchema>;
+/**
+ * 模板元数据 Schema
+ */
+declare const TemplateMetaSchema: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  description: z.ZodString;
+  category: z.ZodEnum<{
+    adapter: "adapter";
+    app: "app";
+    config: "config";
+    docs: "docs";
+    domain: "domain";
+    package: "package";
+    project: "project";
+  }>;
+  tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  variables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+      boolean: "boolean";
+      select: "select";
+      string: "string";
+    }>;
+    description: z.ZodString;
+    defaultValue: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      label: z.ZodString;
+      value: z.ZodString;
+    }, z.core.$strip>>>;
+    pattern: z.ZodOptional<z.ZodString>;
+    patternMessage: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    source: z.ZodString;
+    destination: z.ZodString;
+    executable: z.ZodDefault<z.ZodBoolean>;
+    condition: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  version: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 模板元数据类型
+ */
+type TemplateMeta = z.infer<typeof TemplateMetaSchema>;
+/**
+ * 内置变量名称常量
+ */
+declare const BUILTIN_VARIABLES: {
+  readonly projectName: 'projectName';
+  readonly projectScope: 'projectScope';
+  readonly domainName: 'domainName';
+  readonly packageName: 'packageName';
+  readonly author: 'author';
+  readonly year: 'year';
+};
+/**
+ * 内置变量类型
+ */
+type BuiltinVariable = keyof typeof BUILTIN_VARIABLES;
+//#endregion
+//#region src/engine.utils.d.ts
+/**
+ * 模板变量值映射
+ */
+type VariableValues = Record<string, string | boolean>;
+/**
+ * 替换模板内容中的变量占位符
+ *
+ * @param content - 模板内容
+ * @param variables - 变量值映射
+ * @returns 替换后的内容
+ */
+declare const replaceVariables: (content: string, variables: VariableValues) => string;
+/**
+ * 解析变量输入值
+ *
+ * @param variable - 变量定义
+ * @param rawValue - 原始输入值
+ * @returns 解析后的值
+ */
+declare const parseVariableValue: (variable: TemplateVariable, rawValue: string) => string | boolean;
+/**
+ * 验证变量值
+ *
+ * @param variable - 变量定义
+ * @param value - 变量值
+ * @returns 验证错误信息，无错误返回 null
+ */
+declare const validateVariable: (variable: TemplateVariable, value: string | boolean | undefined) => string | null;
+/**
+ * 构建内置变量
+ *
+ * @param projectName - 项目名称
+ * @returns 内置变量映射
+ */
+declare const buildBuiltinVariables: (projectName: string) => VariableValues;
+/**
+ * 合并模板变量默认值与用户输入值
+ *
+ * @param meta - 模板元数据
+ * @param userValues - 用户输入值
+ * @returns 合并后的变量值映射
+ */
+declare const mergeVariableValues: (meta: TemplateMeta, userValues: VariableValues) => VariableValues;
+/**
+ * 生成目标文件路径
+ *
+ * @param destinationTemplate - 目标路径模板
+ * @param variables - 变量值映射
+ * @returns 生成后的目标路径
+ */
+declare const resolveDestinationPath: (destinationTemplate: string, variables: VariableValues) => string;
+//#endregion
+//#region src/loader.service.d.ts
+/**
+ * 从目录加载模板元数据
+ *
+ * @param templateDir - 模板目录路径
+ * @returns 模板元数据
+ * @throws {@link Error} 元数据文件内容未通过 Schema 校验时抛出（含校验错误详情）
+ */
+declare const loadTemplateMeta: (templateDir: string) => Promise<TemplateMeta>;
+/**
+ * 加载目录下所有模板的元数据
+ *
+ * @param templatesRoot - 模板根目录路径
+ * @returns 模板元数据数组
+ */
+declare const loadAllTemplates: (templatesRoot: string) => Promise<TemplateMeta[]>;
+/**
+ * 读取模板文件内容
+ *
+ * @param templateDir - 模板目录路径
+ * @param sourcePath - 源文件路径（相对于模板目录）
+ * @returns 文件内容字符串
+ */
+declare const readTemplateFile: (templateDir: string, sourcePath: string) => Promise<string>;
+/**
+ * 按分类过滤模板
+ *
+ * @param templates - 模板列表
+ * @param category - 分类名称
+ * @returns 过滤后的模板列表
+ */
+declare const filterByCategory: (templates: TemplateMeta[], category?: string) => TemplateMeta[];
+/**
+ * 按关键词搜索模板
+ *
+ * @param templates - 模板列表
+ * @param keyword - 搜索关键词
+ * @returns 匹配的模板列表
+ */
+declare const searchTemplates: (templates: TemplateMeta[], keyword: string) => TemplateMeta[];
+/**
+ * 根据 ID 查找模板
+ *
+ * @param templates - 模板列表
+ * @param id - 模板 ID
+ * @returns 模板元数据或 undefined
+ */
+declare const findTemplateById: (templates: TemplateMeta[], id: string) => TemplateMeta | undefined;
+//#endregion
+//#region src/generator.service.d.ts
+/**
+ * 生成结果项
+ */
+type GeneratedFile = {
+  /**
+   * 目标文件路径
+   */
+  destination: string;
+  /**
+   * 是否跳过（条件不满足）
+   */
+  skipped: boolean;
+  /**
+   * 是否为可执行文件
+   */
+  executable: boolean;
+};
+/**
+ * 预览将要生成的文件列表
+ *
+ * @param meta - 模板元数据
+ * @param variables - 变量值映射
+ * @returns 生成结果预览
+ */
+declare const previewGeneration: (meta: TemplateMeta, variables: VariableValues) => GeneratedFile[];
+/**
+ * 生成模板文件到目标目录
+ *
+ * @param templateDir - 模板目录路径
+ * @param meta - 模板元数据
+ * @param variables - 变量值映射
+ * @param outputDir - 输出目录路径
+ * @param dryRun - 是否仅预览
+ * @returns 生成的文件列表
+ */
+declare const generateFiles: (templateDir: string, meta: TemplateMeta, variables: VariableValues, outputDir: string, dryRun?: boolean) => Promise<GeneratedFile[]>;
+//#endregion
+export { BUILTIN_VARIABLES, type BuiltinVariable, type GeneratedFile, type TemplateCategory, type TemplateFile, TemplateFileSchema, type TemplateMeta, TemplateMetaSchema, type TemplateVariable, TemplateVariableSchema, type VariableType, type VariableValues, buildBuiltinVariables, filterByCategory, findTemplateById, generateFiles, loadAllTemplates, loadTemplateMeta, mergeVariableValues, parseVariableValue, previewGeneration, readTemplateFile, replaceVariables, resolveDestinationPath, searchTemplates, validateVariable };

package/dist/index.js

@@ -0,0 +1 @@
+import*as e from"zod";import{existsSync as t}from"node:fs";const n=e.enum([`project`,`app`,`package`,`domain`,`config`,`docs`,`adapter`]),r=e.enum([`string`,`boolean`,`select`]),i=e.object({name:e.string(),type:r,description:e.string(),defaultValue:e.string().optional(),required:e.boolean().default(!0),options:e.array(e.object({label:e.string(),value:e.string()})).optional(),pattern:e.string().optional(),patternMessage:e.string().optional()}),a=e.object({source:e.string(),destination:e.string(),executable:e.boolean().default(!1),condition:e.string().optional()}),o=e.object({id:e.string(),name:e.string(),description:e.string(),category:n,tags:e.array(e.string()).default([]),variables:e.array(i).default([]),files:e.array(a).default([]),dependencies:e.array(e.string()).default([]),version:e.string().default(`0.1.0`)}),s={projectName:`projectName`,projectScope:`projectScope`,domainName:`domainName`,packageName:`packageName`,author:`author`,year:`year`},c=(e,t)=>{let n=e;return n=l(n,t),n=n.replace(/\{\{(\w+)\}\}/g,(e,n)=>{let r=t[n];return r===void 0?e:String(r)}),n},l=(e,t)=>e.replace(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g,(e,n,r)=>{let i=t[n];return typeof i==`boolean`?i?r:``:typeof i==`string`&&i&&i!==`false`?r:``}),u=(e,t)=>e.type===`boolean`?t===`true`||t===`1`:t,d=(e,t)=>e.required&&(t===void 0||t===``)?`${e.name} 是必填项`:e.pattern&&typeof t==`string`&&!new RegExp(e.pattern).test(t)?e.patternMessage??`${e.name} 格式不正确`:null,f=e=>{let t=e.replace(/^longzai-intelligence-/,``);return{projectName:e,projectScope:t,domainName:t,packageName:t,author:`Longzai Intelligence`,year:String((/* @__PURE__ */ new Date()).getFullYear())}},p=(e,t)=>{let n={};for(let r of e.variables){let e=t[r.name];e===void 0?r.defaultValue!==void 0&&(n[r.name]=r.defaultValue):n[r.name]=e}return n},m=(e,t)=>c(e,t),h=async e=>{let t=`${e}/template.json`,n=await Bun.file(t).json(),r=o.safeParse(n);if(!r.success)throw Error(`模板元数据校验失败（${t}）: ${r.error.message}`);return r.data},g=async e=>{let n=[`projects`,`apps`,`packages`,`domains`,`configs`,`docs`,`adapters`],r=[];for(let i of n){let n=`${e}/${i}`;if(!t(n))continue;let a=new Bun.Glob(`*`);for await(let e of a.scan({cwd:n,onlyFiles:!1})){let t=`${n}/${e}/template.json`;try{let e=Bun.file(t);if(await e.exists()){let t=await e.json(),n=o.safeParse(t);n.success&&r.push(n.data)}}catch{}}}return r},_=async(e,t)=>{let n=`${e}/${t}`;return await Bun.file(n).text()},v=(e,t)=>t?e.filter(e=>e.category===t):e,y=(e,t)=>{let n=t.toLowerCase();return e.filter(e=>e.name.toLowerCase().includes(n)||e.description.toLowerCase().includes(n)||e.tags.some(e=>e.toLowerCase().includes(n)))},b=(e,t)=>e.find(e=>e.id===t),x=(e,t)=>e.files.map(e=>{let n=S(e,t);return{destination:m(e.destination,t),skipped:!n,executable:e.executable}}),S=(e,t)=>{if(!e.condition)return!0;let n=t[e.condition];return typeof n==`boolean`?n:typeof n==`string`&&n!==``&&n!==`false`},C=async(e,t,n,r,i=!1)=>{let a=[];for(let o of t.files){let t=S(o,n),s=m(o.destination,n);if(!t){a.push({destination:s,skipped:!0,executable:o.executable});continue}if(i){a.push({destination:s,skipped:!1,executable:o.executable});continue}let l=await _(e,o.source),u=c(l,n),d=`${r}/${s}`;await Bun.write(d,u),a.push({destination:s,skipped:!1,executable:o.executable})}return a};export{s as BUILTIN_VARIABLES,a as TemplateFileSchema,o as TemplateMetaSchema,i as TemplateVariableSchema,f as buildBuiltinVariables,v as filterByCategory,b as findTemplateById,C as generateFiles,g as loadAllTemplates,h as loadTemplateMeta,p as mergeVariableValues,u as parseVariableValue,x as previewGeneration,_ as readTemplateFile,c as replaceVariables,m as resolveDestinationPath,y as searchTemplates,d as validateVariable};

package/docs/overview.md

@@ -0,0 +1,23 @@
+# template-engine 概览
+
+> 承接自 README 的介绍细节（README 发布口径精简迁移）；本文件为仓内内部文档，不随包发布，仓内互链合法。
+
+## 原四段叙述（承接）
+
+以下为原 README 的意图/定位/职能/实现情况叙述。原节结构（意图/定位/职能/实现情况）与全仓统一四段形态（品牌首句 + 简介 + 能力）不一致，且「实现情况」属状态/成熟度类字段（发布 README 不写），按 README 发布口径迁此承载：
+
+### 意图
+
+为模板产品提供模板引擎核心能力，支撑模板变量替换、文件生成与模板加载，作为模板浏览与生成应用的基础设施。
+
+### 定位
+
+属于模板产品的核心引擎层包，位于 packages/template-engine 目录下，不依赖任何业务框架，被 Web 应用引用以驱动模板管理与文件生成流程。
+
+### 职能
+
+导出模板元数据、模板分类、变量类型、模板变量、模板文件等 Schema 与类型定义；提供变量替换、变量解析、变量校验、内置变量构建、变量合并、目标路径解析等引擎能力；提供模板元数据加载、全量模板加载、模板文件读取、分类过滤、搜索、按 ID 查找等加载器能力；提供预览生成与文件生成器能力。
+
+### 实现情况
+
+已完整组织 Schema、引擎、加载器、生成器四大模块（src 下 template.schema.ts / engine.utils.ts / loader.service.ts / generator.service.ts）的导出，作为模板产品的核心引擎稳定交付。

package/lzi-builder.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@longzai-intelligence-builder/esm';
+
+/**
+ * lzi-builder 配置
+ */
+export default defineConfig();

package/lzi-dev.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from '@longzai-intelligence-dev-tools/config';
+
+/**
+ * lzi-dev 配置
+ */
+export default defineConfig({
+  clean: {
+    plugins: ['turbo', 'tsgo'],
+  },
+});

package/oxlint.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@longzai-intelligence-oxlint/presets/library';
+
+/**
+ * Oxlint 配置
+ */
+export default defineConfig();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@longzai-intelligence-templates/template-engine",
+  "version": "0.0.5",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {}
+}

package/src/engine.utils.ts

@@ -0,0 +1,190 @@
+/**
+ * 模板引擎核心
+ *
+ * 提供模板变量替换、条件块处理和文件生成功能
+ */
+
+import type { TemplateMeta, TemplateVariable } from './template.schema';
+
+/**
+ * 模板变量值映射
+ */
+export type VariableValues = Record<string, string | boolean>;
+
+/**
+ * 替换模板内容中的变量占位符
+ *
+ * @param content - 模板内容
+ * @param variables - 变量值映射
+ * @returns 替换后的内容
+ */
+export const replaceVariables = (content: string, variables: VariableValues): string => {
+  /**
+   * 逐轮替换的中间结果，先承载原始内容再逐步收敛
+   */
+  let result = content;
+
+  /**
+   * 先处理 {{#if variableName}}...{{/if}} 条件块，避免变量替换破坏块语法
+   */
+  result = processConditionalBlocks(result, variables);
+
+  /**
+   * 再处理 {{variableName}} 变量替换
+   */
+  result = result.replace(/\{\{(\w+)\}\}/g, (match, varName: string) => {
+    /**
+     * 当前占位符对应的变量值，未提供时保留原占位符
+     */
+    const value = variables[varName];
+    if (value === undefined) {
+      return match;
+    }
+    return String(value);
+  });
+
+  return result;
+};
+
+/**
+ * 处理条件块 {{#if variableName}}...{{/if}}
+ *
+ * @param content - 模板内容
+ * @param variables - 变量值映射
+ * @returns 处理后的内容
+ */
+const processConditionalBlocks = (content: string, variables: VariableValues): string => {
+  /**
+   * 匹配 {{#if var}}...{{/if}} 模式，支持嵌套空白
+   */
+  const pattern = /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+
+  return content.replace(pattern, (_match, varName: string, innerContent: string) => {
+    /**
+     * 条件变量对应的值，决定保留还是剔除块内容
+     */
+    const value = variables[varName];
+
+    /**
+     * 布尔值直接判断，字符串判断是否为真值
+     */
+    if (typeof value === 'boolean') {
+      return value ? innerContent : '';
+    }
+    if (typeof value === 'string') {
+      return value && value !== 'false' ? innerContent : '';
+    }
+    return '';
+  });
+};
+
+/**
+ * 解析变量输入值
+ *
+ * @param variable - 变量定义
+ * @param rawValue - 原始输入值
+ * @returns 解析后的值
+ */
+export const parseVariableValue = (
+  variable: TemplateVariable,
+  rawValue: string,
+): string | boolean => {
+  if (variable.type === 'boolean') {
+    return rawValue === 'true' || rawValue === '1';
+  }
+  return rawValue;
+};
+
+/**
+ * 验证变量值
+ *
+ * @param variable - 变量定义
+ * @param value - 变量值
+ * @returns 验证错误信息，无错误返回 null
+ */
+export const validateVariable = (
+  variable: TemplateVariable,
+  value: string | boolean | undefined,
+): string | null => {
+  if (variable.required && (value === undefined || value === '')) {
+    return `${variable.name} 是必填项`;
+  }
+
+  if (variable.pattern && typeof value === 'string') {
+    /**
+     * 按变量定义的正则校验输入格式
+     */
+    const regex = new RegExp(variable.pattern);
+    if (!regex.test(value)) {
+      return variable.patternMessage ?? `${variable.name} 格式不正确`;
+    }
+  }
+
+  return null;
+};
+
+/**
+ * 构建内置变量
+ *
+ * @param projectName - 项目名称
+ * @returns 内置变量映射
+ */
+export const buildBuiltinVariables = (projectName: string): VariableValues => {
+  /**
+   * 从项目名称剥离产品群前缀后得到的作用域名
+   */
+  const scope = projectName.replace(/^longzai-intelligence-/, '');
+  return {
+    projectName,
+    projectScope: scope,
+    domainName: scope,
+    packageName: scope,
+    author: 'Longzai Intelligence',
+    year: String(new Date().getFullYear()),
+  };
+};
+
+/**
+ * 合并模板变量默认值与用户输入值
+ *
+ * @param meta - 模板元数据
+ * @param userValues - 用户输入值
+ * @returns 合并后的变量值映射
+ */
+export const mergeVariableValues = (
+  meta: TemplateMeta,
+  userValues: VariableValues,
+): VariableValues => {
+  /**
+   * 用户输入优先、默认值兜底的合并结果
+   */
+  const result: VariableValues = {};
+
+  for (const variable of meta.variables) {
+    /**
+     * 用户为该变量提供的输入值，优先于默认值生效
+     */
+    const userValue = userValues[variable.name];
+    if (userValue !== undefined) {
+      result[variable.name] = userValue;
+    } else if (variable.defaultValue !== undefined) {
+      result[variable.name] = variable.defaultValue;
+    }
+  }
+
+  return result;
+};
+
+/**
+ * 生成目标文件路径
+ *
+ * @param destinationTemplate - 目标路径模板
+ * @param variables - 变量值映射
+ * @returns 生成后的目标路径
+ */
+export const resolveDestinationPath = (
+  destinationTemplate: string,
+  variables: VariableValues,
+): string => {
+  return replaceVariables(destinationTemplate, variables);
+};