@ai-partner-x/aiko-boot-cli 0.1.4 → 0.1.5

package/dist/cli.js

@@ -11,6 +11,7 @@ import { registerAddAppCommand } from './commands/add-app.js';
 import { registerAddApiCommand } from './commands/add-api.js';
 import { registerAddFeatureCommand } from './commands/add-feature.js';
 import { registerListCommand } from './commands/list.js';
+import { registerEnvCommand } from './commands/env.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 export function runCli(argv = process.argv) {
@@ -25,6 +26,7 @@ export function runCli(argv = process.argv) {
     registerAddApiCommand(program);
     registerAddFeatureCommand(program);
     registerListCommand(program);
+    registerEnvCommand(program);
     program.parse(argv);
 }
 runCli();

package/dist/commands/add-api.js

@@ -8,9 +8,12 @@ export function registerAddApiCommand(program) {
     program
         .command('add-api')
         .argument('[name]', '服务端名称，例如 api、user-api')
-        .option('--db <db>', '数据库类型（预留：sqlite | postgres | mysql 等）', 'sqlite')
+        .option('--db <db>', '数据库类型：sqlite | postgres | mysql')
+        .option('--preset <preset>', '服务端预设：plain | system')
+        .option('--features <items>', '要启用的组件，逗号分隔：mq,file,redis,log')
+        .option('--yes', '非交互模式：缺省值直接使用默认值')
+        .option('--interactive', '强制交互模式（即使已检测到非 TTY）')
         .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
-        .option('--template-dir <dir>', '模板根目录（开发阶段通常为 ai-first-framework/scaffold）')
         .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
         .description('在现有脚手架中新增服务端工程（自动包含数据库初始化逻辑）')
         .action(async (name, options) => {
@@ -21,8 +24,11 @@ export function registerAddApiCommand(program) {
             await usecase.execute({
                 name,
                 db: options.db,
+                preset: options.preset,
+                features: options.features,
+                yes: !!options.yes,
+                interactive: !!options.interactive,
                 rootDir: options.root,
-                templateDir: options.templateDir,
                 dryRun: !!options.dryRun,
             });
         }

package/dist/commands/add-app.js

@@ -10,7 +10,6 @@ export function registerAddAppCommand(program) {
         .argument('[name]', '应用名称，例如 admin、mobile-v2')
         .option('-t, --type <type>', '应用类型：admin | mobile')
         .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
-        .option('--template-dir <dir>', '模板根目录（开发阶段通常为 ai-first-framework/scaffold）')
         .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
         .description('在现有脚手架中新增前端应用（admin / mobile）')
         .action(async (name, options) => {
@@ -22,7 +21,6 @@ export function registerAddAppCommand(program) {
                 name,
                 type: options.type,
                 rootDir: options.root,
-                templateDir: options.templateDir,
                 dryRun: !!options.dryRun,
             });
         }

package/dist/commands/env.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from 'commander';
+/**
+ * env 命令集合：list / add / remove
+ * - list：列出现有环境（基于 .env.<mode> 文件）
+ * - add：生成 .env.<mode> 并注入 dev:<mode>/build:<mode>/start:<mode> 脚本
+ * - remove：删除 .env.<mode> 并清理对应脚本
+ */
+export declare function registerEnvCommand(program: Command): void;

package/dist/commands/env.js

@@ -0,0 +1,55 @@
+import { createEnvUseCase } from '../usecases/env.usecase.js';
+import { createCliLogger } from '../core/logger.js';
+/**
+ * env 命令集合：list / add / remove
+ * - list：列出现有环境（基于 .env.<mode> 文件）
+ * - add：生成 .env.<mode> 并注入 dev:<mode>/build:<mode>/start:<mode> 脚本
+ * - remove：删除 .env.<mode> 并清理对应脚本
+ */
+export function registerEnvCommand(program) {
+    const envCmd = program
+        .command('env')
+        .description('Manage scaffold multi-environment files and scripts');
+    envCmd
+        .command('list')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .action(async (options) => {
+        const logger = createCliLogger();
+        const usecase = createEnvUseCase({ logger });
+        await usecase.list({
+            rootDir: options.root ?? process.cwd(),
+        });
+    });
+    envCmd
+        .command('add')
+        .argument('<mode>', '环境模式，例如 dev / stage / prod / qa')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .option('--force', '覆盖已有 .env.<mode> 并更新脚本')
+        .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
+        .action(async (mode, options) => {
+        const logger = createCliLogger();
+        const usecase = createEnvUseCase({ logger });
+        await usecase.add({
+            rootDir: options.root ?? process.cwd(),
+            mode,
+            dryRun: !!options.dryRun,
+            force: !!options.force,
+        });
+    });
+    envCmd
+        .command('remove')
+        .argument('<mode>', '环境模式，例如 dev / stage / prod / qa')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .option('--force', '即使脚本/文件不存在也继续')
+        .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
+        .action(async (mode, options) => {
+        const logger = createCliLogger();
+        const usecase = createEnvUseCase({ logger });
+        await usecase.remove({
+            rootDir: options.root ?? process.cwd(),
+            mode,
+            dryRun: !!options.dryRun,
+            force: !!options.force,
+        });
+    });
+}

package/dist/commands/init.js

@@ -11,11 +11,10 @@ export function registerCreateCommand(program) {
         .command('create')
         .argument('[targetDir]', '目标目录（默认：当前目录下以项目名命名的文件夹）')
         .option('-n, --name <name>', '项目名 / scope，例如 my-app')
-        .option('--empty', '仅创建空的 monorepo 结构，不包含 admin/mobile/api')
-        .option('--with-admin', '在初始化时创建 admin 应用')
-        .option('--with-mobile', '在初始化时创建 mobile 应用')
-        .option('--with-api', '在初始化时创建 api 服务端')
-        .option('--template-dir <dir>', '模板目录（默认：<cwd>/scaffold）')
+        .option('--with-admin-suite', '创建 admin + mobile + system(api) 套件')
+        .option('--db <db>', 'with-admin-suite 时的数据库类型：sqlite | postgres | mysql')
+        .option('--features <items>', 'with-admin-suite 时启用的组件，逗号分隔：mq,file,redis,log')
+        .option('--empty', '仅创建空的 monorepo 结构')
         .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
         .description('创建一个新的 aiko-boot 脚手架 monorepo')
         .action(async (targetDir, options) => {
@@ -26,11 +25,10 @@ export function registerCreateCommand(program) {
             await usecase.execute({
                 targetDir,
                 name: options.name,
+                withAdminSuite: !!options.withAdminSuite,
+                db: options.db,
+                features: options.features,
                 empty: !!options.empty,
-                withAdmin: !!options.withAdmin,
-                withMobile: !!options.withMobile,
-                withApi: !!options.withApi,
-                templateDir: options.templateDir,
                 dryRun: !!options.dryRun,
             });
         }

package/dist/core/project-config.d.ts

@@ -7,6 +7,7 @@ export type AikoApiConfig = {
     name: string;
     path: string;
     db: string;
+    preset?: 'plain' | 'system' | string;
     features?: string[];
 };
 export type AikoProjectConfig = {

package/dist/core/prompts.d.ts

@@ -1,5 +1,7 @@
 export type Prompter = {
     input: (question: string, defaultValue?: string) => Promise<string>;
     confirm: (question: string, defaultValue?: boolean) => Promise<boolean>;
+    select: (question: string, options: string[], defaultValue?: string) => Promise<string>;
+    multiSelect: (question: string, options: string[], defaultValues?: string[]) => Promise<string[]>;
 };
 export declare function createPrompter(): Prompter;

package/dist/core/prompts.js

@@ -1,42 +1,43 @@
-import readline from 'readline';
+import { input as inquirerInput, confirm as inquirerConfirm, select as inquirerSelect, checkbox as inquirerCheckbox, } from '@inquirer/prompts';
 export function createPrompter() {
     return {
         async input(question, defaultValue) {
-            const rl = readline.createInterface({
-                input: process.stdin,
-                output: process.stdout,
-            });
-            const suffix = defaultValue !== undefined ? ` (${defaultValue})` : '';
-            return new Promise((resolve) => {
-                rl.question(`${question}${suffix}: `, (answer) => {
-                    rl.close();
-                    const trimmed = answer.trim();
-                    if (!trimmed && defaultValue !== undefined) {
-                        resolve(defaultValue);
-                    }
-                    else {
-                        resolve(trimmed);
-                    }
-                });
+            return inquirerInput({
+                message: question,
+                default: defaultValue,
             });
         },
         async confirm(question, defaultValue = false) {
-            const rl = readline.createInterface({
-                input: process.stdin,
-                output: process.stdout,
+            return inquirerConfirm({
+                message: question,
+                default: defaultValue,
+            });
+        },
+        async select(question, options, defaultValue) {
+            if (options.length === 0) {
+                throw new Error('select options 不能为空');
+            }
+            const fallback = defaultValue ?? options[0];
+            if (!options.includes(fallback)) {
+                throw new Error(`select 默认值不在选项中：${fallback}`);
+            }
+            return inquirerSelect({
+                message: question,
+                choices: options.map((item) => ({ value: item, name: item })),
+                default: fallback,
             });
-            const hint = defaultValue ? 'Y/n' : 'y/N';
-            return new Promise((resolve) => {
-                rl.question(`${question} [${hint}]: `, (answer) => {
-                    rl.close();
-                    const lower = answer.trim().toLowerCase();
-                    if (!lower) {
-                        resolve(defaultValue);
-                    }
-                    else {
-                        resolve(lower === 'y' || lower === 'yes');
-                    }
-                });
+        },
+        async multiSelect(question, options, defaultValues = []) {
+            if (options.length === 0)
+                return [];
+            const defaults = defaultValues.filter((x) => options.includes(x));
+            return inquirerCheckbox({
+                message: question,
+                choices: options.map((item) => ({
+                    value: item,
+                    name: item,
+                    checked: defaults.includes(item),
+                })),
             });
         },
     };

package/dist/core/workspace.js

@@ -47,18 +47,39 @@ export async function syncRootPackageJson(rootDir) {
         pkg.version = '0.1.0';
     }
     const scripts = pkg.scripts ?? {};
-    // 通用脚本：对所有 @<scope>/* 包执行 dev / build / lint
-    scripts.dev = `pnpm -r --parallel --filter "@${scope}/*" dev`;
-    scripts.build = `pnpm -r --filter "@${scope}/*" build`;
-    scripts.lint = `pnpm -r --filter "@${scope}/*" lint`;
-    // API 相关脚本：只针对 name === 'api' 的服务，保持与 scaffold 模板一致
-    const api = (config.apis ?? []).find((x) => x.name === 'api');
-    if (api) {
-        const apiPkgName = `@${scope}/${api.name}`;
+    // 通用脚本：仅对配置中出现的 api / apps 执行 dev/build，避免 core/shared 被误启动
+    const apiPkgs = (config.apis ?? []).map((x) => `@${scope}/${x.name}`);
+    const appPkgs = (config.apps ?? []).map((x) => `@${scope}/${x.name}`);
+    const allRunPkgs = [...apiPkgs, ...appPkgs];
+    const toPnpmFilterArgs = (pkgs) => pkgs.map((p) => `--filter "${p}"`).join(" ");
+    if (allRunPkgs.length > 0) {
+        scripts.dev = `pnpm -r --parallel ${toPnpmFilterArgs(allRunPkgs)} dev`;
+        scripts.build = `pnpm -r ${toPnpmFilterArgs(allRunPkgs)} build`;
+    }
+    // lint：包含 core（模板 core 一般有 lint），避免在生成项目里遗漏
+    const corePkgName = `@${scope}/core`;
+    const corePkgPath = path.join(rootDir, 'packages', 'core', 'package.json');
+    const lintPkgs = (await fs.pathExists(corePkgPath)) ? [...allRunPkgs, corePkgName] : allRunPkgs;
+    scripts.lint = `pnpm -r ${toPnpmFilterArgs(lintPkgs)} lint`;
+    // Environment-level scripts（stage/prod）
+    if (allRunPkgs.length > 0) {
+        scripts['dev:stage'] = `pnpm -r --parallel ${toPnpmFilterArgs(allRunPkgs)} dev:stage`;
+        scripts['dev:prod'] = `pnpm -r --parallel ${toPnpmFilterArgs(allRunPkgs)} dev:prod`;
+    }
+    // API 相关脚本：
+    // - dev/build/start:api 仍绑定到一个“主服务”（优先 api，再 system，再第一个）
+    // - init-db 聚合执行所有 API 服务的 init-db
+    const preferredApi = (config.apis ?? []).find((x) => x.name === 'api') ??
+        (config.apis ?? []).find((x) => x.name === 'system') ??
+        (config.apis ?? [])[0];
+    if (preferredApi) {
+        const apiPkgName = `@${scope}/${preferredApi.name}`;
         scripts['dev:api'] = `pnpm -F ${apiPkgName} dev`;
         scripts['build:api'] = `pnpm -F ${apiPkgName} build`;
         scripts['start:api'] = `pnpm -F ${apiPkgName} start`;
-        scripts['init-db'] = `pnpm -F ${apiPkgName} init-db`;
+    }
+    if (apiPkgs.length > 0) {
+        scripts['init-db'] = `pnpm -r ${toPnpmFilterArgs(apiPkgs)} init-db`;
     }
     // Admin / Mobile 应用脚本：按照 type 分类
     const apps = config.apps ?? [];

package/dist/scaffold.js

@@ -27,7 +27,7 @@ export async function createScaffold(options) {
     const { templateDir, targetDir, scope, withBaseSystem } = options;
     if (!(await fs.pathExists(templateDir))) {
         throw new Error(`Template directory not found: ${templateDir}. ` +
-            'You can specify a custom template with --template-dir, or use the built-in templates.');
+            'Please ensure scaffold-default templates are synced and available.');
     }
     if (await fs.pathExists(targetDir)) {
         const files = await fs.readdir(targetDir);

package/dist/usecases/add-api.usecase.d.ts

@@ -2,9 +2,12 @@ import type { Logger } from '../core/logger.js';
 import type { Prompter } from '../core/prompts.js';
 export type AddApiInput = {
     name?: string;
-    db: string;
+    db?: string;
+    preset?: string;
+    features?: string;
+    yes: boolean;
+    interactive: boolean;
     rootDir?: string;
-    templateDir?: string;
     dryRun: boolean;
 };
 export type AddApiDeps = {

package/dist/usecases/add-api.usecase.js

@@ -4,11 +4,18 @@ import fs from 'fs-extra';
 import { loadProjectConfig } from '../core/project-config.js';
 import { ensurePnpmWorkspace, syncRootPackageJson, withProjectConfig, } from '../core/workspace.js';
 import { replaceScopeInDir } from '../core/template-utils.js';
+import { createEnvUseCase } from './env.usecase.js';
+import { createAddFeatureUseCase } from './add-feature.usecase.js';
 export function createAddApiUseCase(deps) {
     const { logger, prompter } = deps;
     async function execute(input) {
         let { name } = input;
+        let db = input.db;
+        let preset = input.preset;
         const rootDir = input.rootDir ?? process.cwd();
+        const allowedDbs = ['sqlite', 'postgres', 'mysql'];
+        const allowedPresets = ['plain', 'system'];
+        const allowedFeatures = ['mq', 'file', 'redis', 'log'];
         const config = await loadProjectConfig(rootDir);
         if (!config) {
             throw new Error('未找到 .aiko-boot.json，当前目录似乎不是脚手架根目录，请在 create 生成的根目录下执行。');
@@ -16,31 +23,55 @@ export function createAddApiUseCase(deps) {
         if (!name) {
             name = await prompter.input('服务端名称（包名）', 'api');
         }
-        // 计算模板根目录：
-        // - 默认使用 CLI 包内部的 templates/api-base 作为 base-api 模板；
-        // - 如果用户通过 --template-dir 显式提供：
-        //   - 若该目录本身是一个 api 根（包含 app.config.ts 和 src/），则直接使用；
-        //   - 若该目录下存在 packages/api（例如传入 scaffold 根目录），则使用 packages/api 作为模板。
-        const defaultTemplateApiDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../templates/api-base');
-        let templateApiDir = defaultTemplateApiDir;
-        if (input.templateDir) {
-            const candidateRoot = path.resolve(input.templateDir);
-            const candidateAsApiRoot = path.join(candidateRoot, 'app.config.ts');
-            const candidateApiDir = path.join(candidateRoot, 'packages', 'api');
-            if (await fs.pathExists(candidateAsApiRoot)) {
-                // 传入的是 api 根目录（类似 api-base）
-                templateApiDir = candidateRoot;
+        if (db && !allowedDbs.includes(db)) {
+            throw new Error(`不支持的数据库类型: ${db}，仅支持 ${allowedDbs.join(' | ')}`);
+        }
+        if (preset &&
+            !allowedPresets.includes(preset)) {
+            throw new Error(`不支持的 preset: ${preset}，仅支持 ${allowedPresets.join(' | ')}`);
+        }
+        const featuresFromArg = parseFeatureList(input.features);
+        const invalidFeatures = featuresFromArg.filter((x) => !allowedFeatures.includes(x));
+        if (invalidFeatures.length > 0) {
+            throw new Error(`不支持的组件: ${invalidFeatures.join(', ')}，仅支持 ${allowedFeatures.join(', ')}`);
+        }
+        const shouldPrompt = input.interactive || (!input.yes && process.stdin.isTTY);
+        if (!preset) {
+            if (shouldPrompt) {
+                preset = await prompter.select('请选择 API 预设', [...allowedPresets], 'plain');
             }
-            else if (await fs.pathExists(path.join(candidateApiDir, 'app.config.ts'))) {
-                // 传入的是 scaffold 根目录，内部有 packages/api
-                templateApiDir = candidateApiDir;
+            else {
+                preset = 'plain';
+            }
+        }
+        if (!db) {
+            if (shouldPrompt) {
+                db = await prompter.select('请选择数据库类型', [...allowedDbs], 'sqlite');
             }
             else {
-                throw new Error(`无法识别的模板目录：${candidateRoot}（需要是 api 根目录，或包含 packages/api 的 scaffold 根目录）`);
+                db = 'sqlite';
             }
         }
+        const selectedFeatures = input.features
+            ? featuresFromArg
+            : shouldPrompt
+                ? await prompter.multiSelect('请选择要启用的组件（可多选）', [...allowedFeatures], [])
+                : [];
+        // 计算模板根目录：
+        // - 默认使用 CLI 包内部模板（plain => templates/api-clean，system => templates/api-system）
+        const defaultTemplatePlainApiDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../templates/api-clean');
+        const defaultTemplateSystemApiDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../templates/api-system');
+        const defaultTemplateApiDir = preset === 'system' && (await fs.pathExists(defaultTemplateSystemApiDir))
+            ? defaultTemplateSystemApiDir
+            : defaultTemplatePlainApiDir;
+        if (preset === 'system' && defaultTemplateApiDir !== defaultTemplateSystemApiDir) {
+            logger.warn?.(`未找到 system 预设模板目录：${defaultTemplateSystemApiDir}，已回退到 plain 模板：${defaultTemplatePlainApiDir}`);
+        }
+        const templateApiDir = defaultTemplateApiDir;
         if (input.dryRun) {
-            logger.info(`[dry-run] 将在 ${rootDir} 中新增服务端：name=${name}, db=${input.db}`);
+            logger.info(`[dry-run] 将在 ${rootDir} 中新增服务端：name=${name}, db=${db}`);
+            logger.info(`[dry-run] API 预设：${preset}`);
+            logger.info(`[dry-run] 组件配置：${selectedFeatures.length > 0 ? selectedFeatures.join(', ') : '(none)'}`);
             logger.info(`[dry-run] 使用模板目录: ${templateApiDir}`);
             return;
         }
@@ -74,14 +105,45 @@ export function createAddApiUseCase(deps) {
             apis.push({
                 name: name,
                 path: path.join('packages', name),
-                db: input.db,
+                db,
+                preset,
                 features: [],
             });
             cfg.apis = apis;
         });
         // 同步根 package.json（dev/build/start:api 等脚本）
         await syncRootPackageJson(rootDir);
-        logger.info(`已在 ${apiDir} 创建服务端 "${name}"（db=${input.db}）。`);
+        // 补齐现有工程已启用的环境（例如用户先 `env add qa`，再 add-api 时，新的 api 也应拥有 .env.qa 与对应脚本）
+        const envUseCase = createEnvUseCase({ logger });
+        const existingModes = await envUseCase.list({ rootDir });
+        const modesToEnsure = existingModes.length > 0 ? existingModes : ['dev', 'stage', 'prod'];
+        for (const mode of modesToEnsure) {
+            await envUseCase.add({
+                rootDir,
+                mode,
+                dryRun: false,
+                force: false,
+                onExisting: 'skip',
+                injectScripts: true,
+            });
+        }
+        if (selectedFeatures.length > 0) {
+            const featureUseCase = createAddFeatureUseCase({ logger, prompter });
+            for (const feature of selectedFeatures) {
+                await featureUseCase.execute({
+                    serviceName: name,
+                    feature,
+                    rootDir,
+                    dryRun: false,
+                });
+            }
+        }
+        logger.info(`已在 ${apiDir} 创建服务端 "${name}"（preset=${preset}，db=${db}，features=${selectedFeatures.length > 0 ? selectedFeatures.join(',') : 'none'}）。`);
     }
     return { execute };
 }
+function parseFeatureList(features) {
+    if (!features)
+        return [];
+    return [...new Set(features.split(',').map((x) => x.trim()).filter(Boolean))];
+}

package/dist/usecases/add-app.usecase.d.ts

@@ -4,7 +4,6 @@ export type AddAppInput = {
     name?: string;
     type?: string;
     rootDir?: string;
-    templateDir?: string;
     dryRun: boolean;
 };
 export type AddAppDeps = {

package/dist/usecases/add-app.usecase.js

@@ -4,6 +4,7 @@ import fs from 'fs-extra';
 import { loadProjectConfig } from '../core/project-config.js';
 import { ensurePnpmWorkspace, syncRootPackageJson, withProjectConfig, } from '../core/workspace.js';
 import { replaceScopeInDir } from '../core/template-utils.js';
+import { createEnvUseCase } from './env.usecase.js';
 export function createAddAppUseCase(deps) {
     const { logger, prompter } = deps;
     async function execute(input) {
@@ -26,15 +27,10 @@ export function createAddAppUseCase(deps) {
         if (type !== 'admin' && type !== 'mobile') {
             throw new Error('应用类型目前仅支持 admin 或 mobile');
         }
-        // 计算模板目录：
-        // - 如果用户提供了 --template-dir，使用用户指定的（可能是 scaffold 根目录或自定义模板）
-        // - 否则，使用内置的 scaffold-default 模板
-        let templateRoot = input.templateDir;
-        if (!templateRoot) {
-            const defaultTemplateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../templates/scaffold-default');
-            templateRoot = defaultTemplateRoot;
-        }
-        const templateAppDir = path.join(templateRoot, 'packages', type);
+        // 使用内置顶层模板目录：templates/{admin|mobile|core}
+        const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../templates');
+        const templateDirName = type === 'admin' ? 'app-admin' : 'app-mobile';
+        const templateAppDir = path.join(templateRoot, templateDirName);
         if (!(await fs.pathExists(templateAppDir))) {
             throw new Error(`模板不存在：${templateAppDir}`);
         }
@@ -44,7 +40,7 @@ export function createAddAppUseCase(deps) {
             throw new Error(`目标应用目录已存在：${appDir}`);
         }
         // 如果还没有 core 包，则在第一次添加 admin/mobile 时一起从模板复制 core
-        const templateCoreDir = path.join(templateRoot, 'packages', 'core');
+        const templateCoreDir = path.join(templateRoot, 'app-core');
         const coreDir = path.join(packagesDir, 'core');
         await fs.ensureDir(packagesDir);
         if (!(await fs.pathExists(coreDir)) && (await fs.pathExists(templateCoreDir))) {
@@ -95,6 +91,20 @@ export function createAddAppUseCase(deps) {
         });
         // 同步根 package.json（dev:admin / dev:mobile 等脚本）
         await syncRootPackageJson(rootDir);
+        // 补齐现有工程已启用的环境（例如用户先 `env add qa`，再 add-app 时，新的 app 也应拥有 .env.qa 与对应脚本）
+        const envUseCase = createEnvUseCase({ logger });
+        const existingModes = await envUseCase.list({ rootDir });
+        const modesToEnsure = existingModes.length > 0 ? existingModes : ['dev', 'stage', 'prod'];
+        for (const mode of modesToEnsure) {
+            await envUseCase.add({
+                rootDir,
+                mode,
+                dryRun: false,
+                force: false,
+                onExisting: 'skip',
+                injectScripts: true,
+            });
+        }
         logger.info(`已在 ${appDir} 创建 ${type} 应用 "${name}"。`);
     }
     return { execute };

package/dist/usecases/add-feature.usecase.js

@@ -146,34 +146,32 @@ async function addFileFeatureToApi(ctx) {
     if (await fs.pathExists(serverPath)) {
         let serverCode = await fs.readFile(serverPath, 'utf-8');
         if (!serverCode.includes('hasFileUpload')) {
-            // import { dirname } from 'path'; => import { dirname, join } from 'path';
-            serverCode = serverCode.replace("import { dirname } from 'path';", "import { dirname, join } from 'path';");
             if (!serverCode.includes("from 'multer'")) {
                 serverCode = serverCode.replace("import express from 'express';", "import express from 'express';\nimport multer from 'multer';");
             }
-            const loggerBlock = `  logger.info('Express middleware configured', {
-    hasRequestLogging: true,
-  });
-`;
-            const replacementBlock = `  // 配置 multer 文件上传中间件
-  const upload = multer({ storage: multer.memoryStorage() });
-  expressApp.post('/api/upload', upload.single('file'));
-  expressApp.post('/api/upload/multiple', upload.array('files', 10));
+            const middlewareAnchor = 'expressApp.use(express.json());';
+            const uploadBlock = `expressApp.use(express.json());
 
-  // 配置静态文件服务（本地存储时访问上传的文件）
-  const uploadsDir = join(__dirname, '..', 'uploads');
-  expressApp.use('/api/uploads', express.static(uploadsDir));
+// 配置 multer 文件上传中间件
+const upload = multer({ storage: multer.memoryStorage() });
+expressApp.post('/api/upload', upload.single('file'));
+expressApp.post('/api/upload/multiple', upload.array('files', 10));
 
-  logger.info('Express middleware configured', {
-    hasRequestLogging: true,
-    hasFileUpload: true,
-    hasStaticFiles: true,
-  });
-`;
-            if (!serverCode.includes(loggerBlock)) {
-                throw new Error('无法在 server.ts 中找到 Express 中间件配置位置，请手动合并文件上传逻辑。');
+// 配置静态文件服务（本地存储时访问上传的文件）
+const uploadsDir = join(projectDir, 'uploads');
+expressApp.use('/api/uploads', express.static(uploadsDir));
+
+logger.info('Express middleware configured', {
+  hasRequestLogging: true,
+  hasFileUpload: true,
+  hasStaticFiles: true,
+});`;
+            if (serverCode.includes(middlewareAnchor)) {
+                serverCode = serverCode.replace(middlewareAnchor, uploadBlock);
+            }
+            else {
+                throw new Error('无法在 server.ts 中找到 expressApp.use(express.json()) 注入点，请手动合并文件上传逻辑。');
             }
-            serverCode = serverCode.replace(loggerBlock, replacementBlock);
             await fs.writeFile(serverPath, serverCode, 'utf-8');
             logger.info('已在 server.ts 中配置 multer 中间件和静态文件服务。');
         }
@@ -321,8 +319,13 @@ async function addMqFeatureToApi(ctx) {
     if (!pkg.dependencies['@ai-partner-x/aiko-boot-starter-mq']) {
         pkg.dependencies['@ai-partner-x/aiko-boot-starter-mq'] = 'workspace:*';
     }
+    // aiko-boot/di 当前会静态导出 React 集成，未安装 react 时在某些 starter 加载阶段会报错。
+    // 这里补齐最小运行时依赖，避免新建 API 后直接启动失败。
+    if (!pkg.dependencies.react) {
+        pkg.dependencies.react = '^18.2.0';
+    }
     await fs.writeJson(pkgPath, pkg, { spaces: 2 });
-    logger.info('更新依赖：已写入 aiko-boot-starter-mq。');
+    logger.info('更新依赖：已写入 aiko-boot-starter-mq / react。');
     // 2) 更新 app.config.ts，增加 mq 配置（如果尚未存在）
     const appConfigPath = path.join(apiDir, 'app.config.ts');
     if (await fs.pathExists(appConfigPath)) {

package/dist/usecases/env.usecase.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from '../core/logger.js';
+export type EnvUseCaseDeps = {
+    logger: Logger;
+};
+export declare function createEnvUseCase(deps: EnvUseCaseDeps): {
+    list: (args: {
+        rootDir: string;
+    }) => Promise<string[]>;
+    add: (args: {
+        rootDir: string;
+        mode: string;
+        dryRun: boolean;
+        force: boolean;
+        injectScripts?: boolean;
+        onExisting?: "error" | "skip";
+    }) => Promise<void>;
+    remove: (args: {
+        rootDir: string;
+        mode: string;
+        dryRun: boolean;
+        force: boolean;
+    }) => Promise<void>;
+};