@lark-apaas/miaoda-cli 0.1.4-alpha.b2fdfff → 0.1.4-alpha.dbe45ea

package/dist/cli/commands/app/index.js

@@ -6,7 +6,7 @@ const index_1 = require("../../../cli/handlers/app/index");
 const error_1 = require("../../../utils/error");
 function registerAppCommands(program, opts = {}) {
     const description = opts.includeInit
-        ? '应用元数据管理：查看 / 修改 / 初始化'
+        ? '应用元数据管理：查看 / 修改 / 初始化 / 同步平台脚本'
         : '应用元数据管理：查看 / 修改';
     const appCmd = program.command('app').description(description);
     appCmd.action(() => {
@@ -21,8 +21,35 @@ function registerAppCommands(program, opts = {}) {
     registerAppUpdate(appCmd);
     if (opts.includeInit) {
         registerAppInit(appCmd);
+        registerAppSync(appCmd);
     }
 }
+function registerAppSync(parent) {
+    const cmd = parent
+        .command('sync')
+        .description('按 stack 同步 platform-controlled/ 下的平台管控内容(scripts / package.json 字段等)到项目')
+        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .addHelpText('after', `
+流程
+  1. 读 .spark/meta.json.stack 决定从 platform-controlled/<stack>/ 拉取
+  2. files/   → 按相对路径覆盖到 <dir>(.sh 自动 +x)
+  3. patches/ → 每个 .json 文件按相对路径 deep merge 到 <dir>/<rel-path>
+                (支持任意 JSON:package.json / tsconfig.json / nest-cli.json / ...)
+
+JSON 输出
+  {"data": {"stack": "...", "syncedFiles": [...],
+            "mergedJsonFiles": [{"path": "...", "keys": [...]}]}}
+
+示例
+  $ miaoda app sync
+  $ miaoda app sync --dir /path/to/app --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleAppSync)({
+            dir: rawOpts.dir,
+        });
+    }));
+}
 function registerAppGet(parent) {
     const cmd = parent
         .command('get')
@@ -71,7 +98,6 @@ function registerAppInit(parent) {
     const cmd = parent
         .command('init')
         .description('初始化应用代码：抓 template 渲染、装 .agent/steering/ skills、写 .spark/meta.json。.spark/meta.json 已存在则直接退出')
-        .addOption((0, shared_1.appIdOption)().hideHelp())
         .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
         .option('--conf <json>', 'init 配置 JSON。支持 {"version": "<template 版本>"} / {"steeringVersion": "<steering 版本>"}，均默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
@@ -82,6 +108,10 @@ function registerAppInit(parent) {
   meta.json 在 init 流程最后才写，写了 = 已完整成功一次；
   上一次失败留下半渲染状态时（package.json 在但 meta.json 没在）允许重跑。
 
+应用身份（appId）
+  init 不再持久化 appId。运行端命令（deploy / file / plugin 等）始终从 MIAODA_APP_ID env 读，
+  init 阶段也无需感知 appId。
+
 依赖安装
   默认：npm install --no-audit --no-fund
   --skip-install: 跳过
@@ -104,10 +134,8 @@ JSON 输出
   $ MIAODA_DEP_CACHE_DIR=/tmp/dep-cache miaoda app init --template vite-react
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
-        (0, shared_1.rejectCliOverride)(cmd, 'appId');
         const conf = parseInitConf(rawOpts.conf);
         await (0, index_1.handleAppInit)({
-            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             template: rawOpts.template,
             conf,
             skipInstall: rawOpts.skipInstall,

package/dist/cli/commands/deploy/modern.js

@@ -20,7 +20,8 @@ function registerDeployCommandsModern(program) {
 不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
 
 前置要求
-  - 项目已 init（.spark/meta.json 含 appId / template）
+  - 项目已 init（.spark/meta.json 含 stack）
+  - MIAODA_APP_ID 已设置（应用身份从 env 读，不再从 meta.json 读）
   - node_modules 已安装
   - package.json 含 build script
   - 沙箱内预装 tosutil（用于把构建产物上传到 TOS）
@@ -42,6 +43,7 @@ JSON 输出（stdout）
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
         await (0, modern_1.handleDeployModern)({
             dir: rawOpts.dir ?? '.',
+            appId: (0, shared_1.resolveAppId)({}),
             skipBuild: rawOpts.skipBuild,
         });
     }));

package/dist/cli/commands/index.js

@@ -9,9 +9,21 @@ const index_4 = require("../../cli/commands/app/index");
 const index_5 = require("../../cli/commands/deploy/index");
 const modern_1 = require("../../cli/commands/deploy/modern");
 const index_6 = require("../../cli/commands/skills/index");
+// scene 跟 dispatcher(MIAODA_APP_TYPE)同语义层级 —— app 业务类型维度,
+// 对齐后端 devops app_common.AppType 枚举:
+//   3 = AppType_APPLICATION(全栈应用,当前仅 nestjs-react-fullstack 一个 stack)
+//   4 = AppType_DESIGN(design-stack,SSR 渲染、无业务逻辑、无数据库)
+//   7 = miaoda-cli 自定义 modern 占位(后端枚举无 7,沙箱目前不传)
+//   其它(0/1/2/5/6 / 未设)→ default(命令全开,本地 dev / CI / 兼容回退)
+// stack 维度(nestjs-react-fullstack / vite-react / ...)是正交的,
+// skills sync 内部按 .spark/meta.json.stack 拉对应 coding-steering/steering/<stack>/ 子目录。
 function resolveScene(appType, _archType) {
     if (appType === '7')
         return 'modern';
+    if (appType === '3')
+        return 'application';
+    if (appType === '4')
+        return 'design';
     return 'default';
 }
 const SCENE_REGISTRARS = {
@@ -27,6 +39,25 @@ const SCENE_REGISTRARS = {
         (0, modern_1.registerDeployCommandsModern)(p);
         (0, index_6.registerSkillsCommands)(p);
     },
+    // application scene(AppType_APPLICATION=3):
+    // 在 default 命令集基础上加 skills(按 meta.json.stack 拉对应 stack 技能)
+    // + app init(新一代应用走 init 写 .spark/meta.json)
+    application: (p) => {
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
+        (0, index_5.registerDeployCommands)(p);
+        (0, index_2.registerDbCommands)(p);
+        (0, index_1.registerFileCommands)(p);
+        (0, index_3.registerObservabilityCommands)(p);
+        (0, index_6.registerSkillsCommands)(p);
+    },
+    // design scene(AppType_DESIGN=4):design-stack 仅 SSR 渲染、无后端业务逻辑、
+    // 无数据库、无 UGC 文件。命令集裁掉 db / file,保留 deploy / observability / app(init) / skills。
+    design: (p) => {
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
+        (0, index_5.registerDeployCommands)(p);
+        (0, index_3.registerObservabilityCommands)(p);
+        (0, index_6.registerSkillsCommands)(p);
+    },
 };
 function readEnv(name) {
     const v = process.env[name]?.trim();

package/dist/cli/handlers/app/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_STACKS = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.SUPPORTED_STACKS = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
 Object.defineProperty(exports, "handleAppUpdate", { enumerable: true, get: function () { return update_1.handleAppUpdate; } });
 var init_1 = require("./init");
 Object.defineProperty(exports, "handleAppInit", { enumerable: true, get: function () { return init_1.handleAppInit; } });
+var sync_1 = require("./sync");
+Object.defineProperty(exports, "handleAppSync", { enumerable: true, get: function () { return sync_1.handleAppSync; } });
 // commands 层渲染 help 时需要这份枚举；从 handler barrel 转发，避免 commands → services 越界
 var index_1 = require("../../../services/app/init/index");
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return index_1.SUPPORTED_STACKS; } });

package/dist/cli/handlers/app/init.js

@@ -10,13 +10,19 @@ const index_1 = require("../../../services/app/init/index");
 const coding_steering_1 = require("../../../utils/coding-steering");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
-/** miaoda app init [--template <stack>] [--conf <json>] */
+/**
+ * miaoda app init
+ *
+ * 只负责本地脚手架：render template、sync skills、install deps，把 {stack, version, archType}
+ * 写入 .spark/meta.json。appId 不在此处持久化——deploy 等运行端通过 MIAODA_APP_ID env 拿。
+ *
+ * 幂等：.spark/meta.json 存在即表示已完整成功一次，直接退出，不重跑任何子步骤。
+ * 半渲染状态（package.json 在但 meta.json 不在）会重新跑完整流程。
+ */
 async function handleAppInit(opts) {
     await Promise.resolve();
     const targetDir = opts.targetDir ?? process.cwd();
     const metaPath = node_path_1.default.join(targetDir, '.spark', 'meta.json');
-    // 幂等：.spark/meta.json 是 init 流程最后才写的，存在即代表"已完整成功一次"。
-    // 用 package.json 判幂等会让 install 失败、CWD 留下半渲染状态的应用永远 init 不了。
     if (node_fs_1.default.existsSync(metaPath)) {
         if (!(0, output_1.isJsonMode)()) {
             process.stdout.write(`Already initialized: ${metaPath}\n`);
@@ -56,7 +62,6 @@ async function handleAppInit(opts) {
         quietStdout: (0, output_1.isJsonMode)(),
     });
     (0, index_1.writeSparkMeta)(targetDir, {
-        appId: opts.appId,
         stack,
         version: tplResult.version,
         archType: tplResult.archType,
@@ -67,7 +72,6 @@ async function handleAppInit(opts) {
     (0, output_1.emit)({
         data: {
             initialized: true,
-            appId: opts.appId,
             template: stack,
             templatePackage: tplResult.packageName,
             templateVersion: tplResult.version,

package/dist/cli/handlers/app/sync.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAppSync = handleAppSync;
+const node_path_1 = __importDefault(require("node:path"));
+const platform_sync_1 = require("../../../utils/platform-sync");
+const spark_meta_1 = require("../../../utils/spark-meta");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+/**
+ * miaoda app sync [--dir <path>]
+ *
+ * 从 platform-controlled/<stack>/ 同步平台管控内容到项目:
+ *   - files/         → 按相对路径覆盖
+ *   - package.json   → deep merge patch
+ *
+ * 需要 .spark/meta.json 已含 stack(走过 `miaoda app init`)。
+ * 不动 .agent/skills/(那是 `miaoda skills sync` 的事)。
+ */
+async function handleAppSync(opts) {
+    await Promise.resolve();
+    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+    if (meta.stack === undefined || meta.stack === '') {
+        throw new error_1.AppError('SYNC_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+    }
+    const result = (0, platform_sync_1.syncPlatformControlled)({
+        stack: meta.stack,
+        targetDir,
+    });
+    if (!result.stackFound) {
+        throw new error_1.AppError('SYNC_STACK_NOT_SUPPORTED', `platform-controlled/${meta.stack}/ not found — 该 stack 暂未纳入 app sync 范围`, {
+            next_actions: ['在 miaoda-cli 仓 platform-controlled/ 下添加该 stack 目录,然后重新发版'],
+        });
+    }
+    (0, output_1.emit)({
+        data: {
+            stack: meta.stack,
+            syncedFiles: result.syncedFiles,
+            mergedJsonFiles: result.mergedJsonFiles,
+        },
+    });
+}

package/dist/cli/handlers/deploy/modern.js

@@ -16,6 +16,7 @@ async function handleDeployModern(opts) {
     const projectDir = node_path_1.default.resolve(opts.dir);
     const result = await (0, index_1.runModernDeploy)({
         projectDir,
+        appId: opts.appId,
         skipBuild: opts.skipBuild ?? false,
     });
     (0, output_1.emit)({

package/dist/services/deploy/modern/atoms/context.js

@@ -6,23 +6,20 @@ const spark_meta_1 = require("../../../../utils/spark-meta");
 const check_1 = require("../check");
 const template_key_map_1 = require("../template-key-map");
 /**
- * 准备 deploy 上下文：跑前置检查、读 .spark/meta.json、抽出 appId / stack，
- * 并把 stack 短名映射成后端 templateKey。
+ * 准备 deploy 上下文：跑前置检查、读 .spark/meta.json 拿 stack，
+ * 并把 stack 短名映射成后端 templateKey。appId 由调用方从 env 解析后传入。
  *
  * 任何前置失败统一抛 AppError。返回值是后续 atom 唯一信任的入参源。
  */
-function prepareDeployContext(projectDir) {
+function prepareDeployContext(projectDir, appId) {
     (0, check_1.runDeployChecks)(projectDir);
     const meta = (0, spark_meta_1.readSparkMeta)(projectDir);
-    if (meta.appId === undefined || meta.appId === '') {
-        throw new error_1.AppError('DEPLOY_META_INCOMPLETE', '.spark/meta.json missing appId — run `miaoda app init` first');
-    }
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('DEPLOY_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
     }
     return {
         projectDir,
-        appId: meta.appId,
+        appId,
         stack: meta.stack,
         templateKey: (0, template_key_map_1.resolveTemplateKey)(meta.stack),
         meta,

package/dist/services/deploy/modern/check.js

@@ -24,13 +24,8 @@ function runDeployChecks(projectDir) {
     else {
         try {
             const meta = JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf-8'));
-            const missing = [];
-            if (!meta.appId)
-                missing.push('appId');
-            if (!meta.stack)
-                missing.push('stack');
-            if (missing.length > 0) {
-                issues.push(`.spark/meta.json missing fields: ${missing.join(', ')}`);
+            if (!meta.stack) {
+                issues.push('.spark/meta.json missing fields: stack');
             }
         }
         catch {

package/dist/services/deploy/modern/pipelines/local.js

@@ -22,7 +22,7 @@ const index_1 = require("../atoms/index");
  * 任一步失败都会精准把该发布单标记为 Failed，避免遗留挂态。
  */
 async function localBuildLocalPublishPipeline(opts) {
-    const ctx = (0, index_1.prepareDeployContext)(opts.projectDir);
+    const ctx = (0, index_1.prepareDeployContext)(opts.projectDir, opts.appId);
     (0, logger_1.log)('deploy', 'Pre-releasing...');
     const pre = await (0, index_1.preRelease)(ctx.appId, ctx.templateKey);
     (0, logger_1.log)('deploy', `pre_release_id=${pre.preReleaseID} version=${pre.version}`);
@@ -62,7 +62,7 @@ async function localBuildLocalPublishPipeline(opts) {
         throw err;
     }
     if (release.onlineUrl !== undefined && release.onlineUrl !== '') {
-        (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { ...ctx.meta, appUrl: release.onlineUrl });
+        (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { appUrl: release.onlineUrl });
     }
     (0, logger_1.log)('deploy', 'Deployed successfully');
     return {

package/dist/utils/coding-steering.js

@@ -9,6 +9,9 @@ const node_path_1 = __importDefault(require("node:path"));
 const npm_pack_1 = require("../utils/npm-pack");
 const logger_1 = require("../utils/logger");
 const STEERING_PACKAGE = '@lark-apaas/coding-steering';
+// 临时:本地测试 alpha 链路用,默认 pin 到 0.1.6-alpha.0
+// (用户显式传 version,例如 `miaoda skills sync latest`,仍会 override 这个默认值)
+const DEFAULT_PINNED_VERSION = '0.1.6-alpha.0';
 /**
  * 把 coding-steering 包内 _common/skills + <stack>/skills 同步到 <targetDir>/.agent/steering/skills/，
  * 同名 stack 子目录覆盖 _common。tech.md 存在时也同步到 .agent/steering/tech.md。
@@ -18,10 +21,11 @@ const STEERING_PACKAGE = '@lark-apaas/coding-steering';
  */
 function syncCodingSteering(opts) {
     const logPrefix = opts.logPrefix ?? 'skills';
-    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${opts.version ?? 'latest'}...`);
+    const effectiveVersion = opts.version ?? DEFAULT_PINNED_VERSION;
+    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${effectiveVersion}...`);
     const fetched = (0, npm_pack_1.fetchNpmPackage)({
         packageName: STEERING_PACKAGE,
-        version: opts.version,
+        version: effectiveVersion,
     });
     try {
         const steeringRoot = node_path_1.default.join(fetched.extractDir, 'steering');

package/dist/utils/platform-sync.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncPlatformControlled = syncPlatformControlled;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../utils/logger");
+function syncPlatformControlled(opts) {
+    const logPrefix = opts.logPrefix ?? 'app-sync';
+    const cliRoot = opts.cliRoot ?? resolveCliRoot();
+    const stackDir = node_path_1.default.join(cliRoot, 'platform-controlled', opts.stack);
+    if (!node_fs_1.default.existsSync(stackDir)) {
+        return { stackFound: false, syncedFiles: [], mergedJsonFiles: [] };
+    }
+    (0, logger_1.log)(logPrefix, `Syncing platform-controlled/${opts.stack}/ → ${opts.targetDir}`);
+    const syncedFiles = syncFilesDir(node_path_1.default.join(stackDir, 'files'), opts.targetDir, logPrefix);
+    const mergedJsonFiles = applyJsonPatches(node_path_1.default.join(stackDir, 'patches'), opts.targetDir, logPrefix);
+    return {
+        stackFound: true,
+        syncedFiles,
+        mergedJsonFiles,
+    };
+}
+/** 推断 cli 安装根:dist/utils/platform-sync.js 上溯两级即仓根 */
+function resolveCliRoot() {
+    return node_path_1.default.resolve(__dirname, '..', '..');
+}
+/** 递归同步 srcDir 下所有文件到 destDir,保持相对路径;.sh 文件 +x。返回 dest 相对路径列表 */
+function syncFilesDir(srcDir, destDir, logPrefix) {
+    if (!node_fs_1.default.existsSync(srcDir))
+        return [];
+    const synced = [];
+    walk(srcDir, srcDir, destDir, (rel, srcPath, destPath) => {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(destPath), { recursive: true });
+        node_fs_1.default.copyFileSync(srcPath, destPath);
+        if (rel.endsWith('.sh')) {
+            node_fs_1.default.chmodSync(destPath, 0o755);
+        }
+        synced.push(rel);
+        (0, logger_1.log)(logPrefix, `  + ${rel}`);
+    });
+    return synced;
+}
+/** 递归遍历 patchesDir 下每个 JSON 文件,deep merge 到 destDir 对应路径 */
+function applyJsonPatches(patchesDir, destDir, logPrefix) {
+    if (!node_fs_1.default.existsSync(patchesDir))
+        return [];
+    const merged = [];
+    walk(patchesDir, patchesDir, destDir, (rel, patchPath, destPath) => {
+        if (!rel.endsWith('.json')) {
+            (0, logger_1.log)(logPrefix, `  (skip non-json patch: ${rel})`);
+            return;
+        }
+        if (!node_fs_1.default.existsSync(destPath)) {
+            throw new Error(`[${logPrefix}] target JSON not found: ${destPath} ` +
+                `(patches/${rel} 要求项目根含同路径文件;app init 应该先创建它)`);
+        }
+        const patch = readJson(patchPath);
+        const target = readJson(destPath);
+        if (!isPlainObject(patch) || !isPlainObject(target)) {
+            throw new Error(`[${logPrefix}] patch 与 target 必须都是 JSON object: ${rel}`);
+        }
+        const changed = [];
+        for (const key of Object.keys(patch)) {
+            const before = JSON.stringify(target[key]);
+            target[key] = deepMerge(target[key], patch[key]);
+            const after = JSON.stringify(target[key]);
+            if (before !== after)
+                changed.push(key);
+        }
+        if (changed.length > 0) {
+            node_fs_1.default.writeFileSync(destPath, JSON.stringify(target, null, 2) + '\n', 'utf-8');
+            merged.push({ path: rel, keys: changed });
+            (0, logger_1.log)(logPrefix, `  ~ ${rel} (keys: ${changed.join(', ')})`);
+        }
+        else {
+            (0, logger_1.log)(logPrefix, `  = ${rel} (unchanged)`);
+        }
+    });
+    return merged;
+}
+/** 通用递归遍历:对 rootSrc 下每个文件调 visit(rel, srcAbsPath, destAbsPath) */
+function walk(rootSrc, curSrc, destDir, visit) {
+    for (const name of node_fs_1.default.readdirSync(curSrc)) {
+        const srcPath = node_path_1.default.join(curSrc, name);
+        const stat = node_fs_1.default.statSync(srcPath);
+        if (stat.isDirectory()) {
+            walk(rootSrc, srcPath, destDir, visit);
+            continue;
+        }
+        const rel = node_path_1.default.relative(rootSrc, srcPath);
+        const destPath = node_path_1.default.join(destDir, rel);
+        visit(rel, srcPath, destPath);
+    }
+}
+function readJson(filePath) {
+    return JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf-8'));
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** value 是 object 时递归 merge,其它(包括数组)直接以 patch 覆盖 */
+function deepMerge(target, patch) {
+    if (isPlainObject(patch) && isPlainObject(target)) {
+        const merged = { ...target };
+        for (const k of Object.keys(patch)) {
+            merged[k] = deepMerge(target[k], patch[k]);
+        }
+        return merged;
+    }
+    return patch;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.4-alpha.b2fdfff",
+  "version": "0.1.4-alpha.dbe45ea",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -10,10 +10,11 @@
     "access": "public"
   },
   "files": [
+    "LICENSE",
+    "README.md",
     "bin",
     "dist",
-    "README.md",
-    "LICENSE"
+    "platform-controlled"
   ],
   "keywords": [
     "miaoda",

package/platform-controlled/README.md

@@ -0,0 +1,33 @@
+# platform-controlled/
+
+平台管控的脚手架增量内容,按 stack 分目录,由 `miaoda app sync` 同步到用户项目。
+
+## 目录约定
+
+```
+platform-controlled/
+└── <stack>/
+    ├── files/                ← 文件模式:按相对路径整文件覆盖
+    │   └── <rel-path>        ← 例如 scripts/dev-local.sh → <app>/scripts/dev-local.sh
+    └── patches/              ← JSON merge 模式:按相对路径 deep merge(任意 JSON 文件)
+        └── <rel-path>.json   ← 例如 package.json / tsconfig.json / nest-cli.json
+```
+
+## 同步行为
+
+- **files/**:递归遍历,按相对路径全量覆盖 targetDir。`.sh` 后缀文件同步后自动 `chmod +x`。
+- **patches/**:递归遍历,**每个 `.json` 文件** 都跟 targetDir 同路径文件做 deep merge:
+  - 两边都必须是 JSON object(否则报错)
+  - value 是 object → 递归 merge;value 是数组 / 标量 → 整体替换
+  - 目标文件不存在则报错(patches 是补丁性质,不负责创建文件;app init 应该先创建)
+  - patches 下非 `.json` 文件会被跳过(预留给将来其它 patch 类型)
+- 不做用户改动保护(本期约定:`platform-controlled/` 下的文件路径由平台拥有,用户不应手改)。
+
+## 跟 `miaoda skills sync` 的区别
+
+| 链路 | 源 | 内容 | 目标 |
+|---|---|---|---|
+| `miaoda skills sync` | NPM 包 `@lark-apaas/coding-steering` | agent skills(`.md`) | `<app>/.agent/skills/steering/<stack>/` |
+| `miaoda app sync`  | 本仓 `platform-controlled/<stack>/` | 启动脚本、package.json 字段等 | `<app>/` 项目根 |
+
+两者独立调用,互不依赖。

package/platform-controlled/design-stack/files/scripts/dev-local.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# ============================================================================
+# 本地 dev 启动脚本(平台控制,通过 `miaoda app sync` 同步,请勿手改)
+# Stack: design-stack(SSR-only,无 server 业务逻辑,无数据库)
+# 流程:env pull → skills sync → 起 dev server
+# ============================================================================
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT_DIR"
+
+# Stack 是 design-stack,对应 miaoda CLI 的 design scene
+# 沙箱里这个 env 由平台注入,本地 dev 由本脚本兜底,确保 miaoda 子命令(skills/sync)能看见
+export MIAODA_APP_TYPE="${MIAODA_APP_TYPE:-4}"
+
+# 临时:绕 npmmirror/bnpm 内网到 npmjs 的同步延迟,等 coding-steering 正式版去掉
+export MIAODA_NPM_REGISTRY="${MIAODA_NPM_REGISTRY:-https://registry.npmjs.org/}"
+
+# 1. 拉本地 dev 所需 ENV(jwt / cookie 等,写入 .env.local)
+echo "[dev-local] (1/3) env pull..."
+if command -v lark-cli >/dev/null 2>&1; then
+  lark-cli apps env pull || echo "  (env pull 失败,后续按 .env.local 现状继续)"
+else
+  echo "  (lark-cli 未装,跳过 env pull;请确保 .env.local 已就绪)"
+fi
+
+# 2. 同步 stack 对应 skills(coding-steering)
+echo "[dev-local] (2/3) miaoda skills sync..."
+if command -v miaoda >/dev/null 2>&1; then
+  miaoda skills sync || echo "  (skills sync 失败,继续启动)"
+else
+  echo "  (miaoda 未装,跳过 skills sync)"
+fi
+
+# 3. 起 dev server(design-stack 只有 SSR 渲染,单进程即可;不走 scripts/dev.js 的保活)
+#    如果模板的 npm run dev 本身就是裸进程(无保活)则直接调即可;
+#    如果 design-stack 模板的 dev 也是 dev.js 包装,后续需要新增 dev:raw 之类的直通命令
+echo "[dev-local] (3/3) npm run dev"
+exec npm run dev

package/platform-controlled/design-stack/patches/package.json

@@ -0,0 +1,5 @@
+{
+  "scripts": {
+    "dev:local": "./scripts/dev-local.sh"
+  }
+}

package/platform-controlled/nestjs-react-fullstack/files/scripts/dev-local.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# ============================================================================
+# 本地 dev 启动脚本(平台控制,通过 `miaoda app sync` 同步,请勿手改)
+# Stack: nestjs-react-fullstack
+# 流程:env pull → skills sync → 起 server + client(用户访问 http://localhost:8001)
+# ============================================================================
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT_DIR"
+
+# Stack 是 nestjs-react-fullstack(全栈应用),对应 miaoda CLI 的 application scene
+# 沙箱里这个 env 由平台注入,本地 dev 由本脚本兜底,确保 miaoda 子命令(skills/sync)能看见
+export MIAODA_APP_TYPE="${MIAODA_APP_TYPE:-3}"
+
+# 临时:绕 npmmirror/bnpm 内网到 npmjs 的同步延迟,等 coding-steering 正式版去掉
+export MIAODA_NPM_REGISTRY="${MIAODA_NPM_REGISTRY:-https://registry.npmjs.org/}"
+
+# 1. 拉本地 dev 所需 ENV(jwt / cookie / sandbox URL 等,写入 .env.local)
+echo "[dev-local] (1/3) env pull..."
+if command -v lark-cli >/dev/null 2>&1; then
+  lark-cli apps env pull || echo "  (env pull 失败,后续按 .env.local 现状继续)"
+else
+  echo "  (lark-cli 未装,跳过 env pull;请确保 .env.local 已就绪)"
+fi
+
+# 2. 同步 stack 对应 skills(coding-steering)
+echo "[dev-local] (2/3) miaoda skills sync..."
+if command -v miaoda >/dev/null 2>&1; then
+  miaoda skills sync || echo "  (skills sync 失败,继续启动)"
+else
+  echo "  (miaoda 未装,跳过 skills sync)"
+fi
+
+# 3. 并发起 dev:server(NestJS 3000) + dev:client(rspack 8001),用户访问 8001
+#    不走 scripts/dev.js(那有保活 / restart 循环 / 日志写文件,本地 dev 不需要 ——
+#    进程崩了就让它崩,失败立即可见;日志直接 stdout 让 Agent 抓得到)
+echo "[dev-local] (3/3) 并发起 dev:server + dev:client → http://localhost:${CLIENT_DEV_PORT:-8001}/"
+exec npx --no-install concurrently \
+  --names "server,client" --prefix-colors "blue,green" --kill-others-on-fail \
+  "npm run dev:server" "npm run dev:client"

package/platform-controlled/nestjs-react-fullstack/patches/package.json

@@ -0,0 +1,5 @@
+{
+  "scripts": {
+    "dev:local": "./scripts/dev-local.sh"
+  }
+}