@lark-apaas/miaoda-cli 0.1.24-alpha.77f133a → 0.1.24-alpha.800d445

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

@@ -217,7 +217,7 @@ function registerAppInit(parent) {
         .command('init')
         .description('初始化应用代码：抓 template 渲染、同步 upgrade/templates、装 .agent/steering/ skills、写 .spark/meta.json。.spark/meta.json 已存在则直接退出')
         .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
-        .option('--app-type <type>', 'aPaaS 业务类型（html / modern_html / jspage / full_stack）；未传 --template 时用于解析技术栈')
+        .option('--app-type <type>', 'aPaaS 业务类型（html / modern_html / frontend / jspage / full_stack）；未传 --template 时用于解析技术栈')
         .option('--source-path <path>', '导入源目录：把该目录内容聚合进脚手架 src/（当前仅 --app-type modern_html 生效）')
         .option('--conf [json]', 'init 配置 JSON。支持 {"version": "<template 版本>"}，默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
@@ -237,7 +237,7 @@ function registerAppInit(parent) {
 
 技术栈解析（--template / --app-type）
   --template 传了      → 直接用（vite-react / html / design-html / nestjs-react-fullstack）
-  否则 --app-type 传了 → 查表：html→design-html, modern_html→html, jspage→vite-react, full_stack→nestjs-react-fullstack
+  否则 --app-type 传了 → 查表：html→design-html, modern_html→html, frontend/jspage→vite-react, full_stack→nestjs-react-fullstack
   两者都没传          → 报错 ARGS_INVALID
 
 源码导入（--source-path）

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

@@ -17,6 +17,7 @@ function registerDeployCommandsModern(program) {
         .description('触发 modern 应用发布：本地构建 + 本地部署（preRelease + localPublish）')
         .option('--dir <path>', '项目目录', '.')
         .option('--skip-build', '跳过 build 步骤（已构建好时使用）', false)
+        .option('--skip-release', '不创建/更新本地发布单，发布单状态由外部托管', false)
         .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID 两字段')
         .addHelpText('after', `
 不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
@@ -34,6 +35,15 @@ function registerDeployCommandsModern(program) {
   6. savePluginInstances（扫描 dist/output_capabilities/*.json 批量注册）
   7. finalizeLocalRelease(Finished|Failed)
 
+--skip-release（发布单外部托管）
+  跳过第 4、7 步（createLocalRelease / updateLocalRelease），其余步骤不变：
+  preRelease 仍照常签发 version，构建、上传、capability 注册照常执行。
+  外部据 stdout 返回的 version / preReleaseID 自行建单，并据本命令的
+  退出码决定把发布单翻成 Finished 还是 Failed —— 失败态由外部负责，CLI 不再兜底。
+  该模式下 releaseID / url 输出为 null（CLI 未建单，无从得知）。
+  注意：--conf 的 checkPointVersion / commitID 唯一消费者是 createLocalRelease，
+  本模式下不生效（静默忽略，不报错），需要关联请在外部建单时自行传递。
+
 --conf（关联元信息透传）
   值为 JSON string，只识别两个字段，其余 key 忽略：
     checkPointVersion  关联的 checkpoint 版本
@@ -42,11 +52,13 @@ function registerDeployCommandsModern(program) {
 
 JSON 输出（stdout）
   {"data": {"appId": "...", "version": <n>, "url": "...", "releaseID": "...", "preReleaseID": "..."}}
+  --skip-release 时 url 与 releaseID 为 null，字段本身仍在。
 
 示例
   $ miaoda deploy
   $ miaoda deploy --dir ./my-app
   $ miaoda deploy --skip-build
+  $ miaoda deploy --skip-release
   $ miaoda deploy --conf '{"checkPointVersion":"v3","commitID":"a1b2c3d"}'
 `);
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
@@ -54,6 +66,7 @@ JSON 输出（stdout）
             dir: rawOpts.dir ?? '.',
             appId: (0, shared_1.resolveAppId)({}),
             skipBuild: rawOpts.skipBuild,
+            skipRelease: rawOpts.skipRelease,
             conf: rawOpts.conf,
         });
     }));

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

@@ -60,11 +60,16 @@ async function handleAppInit(opts) {
     const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
     // source_path 导入：当前仅 app_type=modern_html 生效。渲染完模板后、装依赖前叠加进 src/。
     const sourceImport = applySourcePathImport(opts, targetDir);
+    // 本地脚手架门禁：沙箱内所有栈照旧同步（nested，产出 .agent/）；本地只有 LOCAL_STEERING_STACKS
+    // 白名单栈（nestjs-react-fullstack / vite-react）才落地 steering（.claude/.agents）与 logs/。
+    // html / design-html 是纯静态 / 设计产物，本地不需要这套 agent skills 脚手架，整段跳过。
+    const sandbox = (0, env_1.isSandboxEnv)();
+    const scaffoldSteering = sandbox || index_1.LOCAL_STEERING_STACKS.has(stack);
     // 先建 logs/,防止 user 跑 dev 之前 AI/工具 redirect 到 logs/*.log 因为父目录不存在直接挂
     // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)。
-    // 仅本地开发需要：沙箱环境由平台 supervisor 拉起 dev,无 init 前的 shell redirect 场景,
-    // 不预建 logs/ 以免在沙箱工作区留空目录。
-    if (!(0, env_1.isSandboxEnv)()) {
+    // 仅本地白名单栈需要：沙箱环境由平台 supervisor 拉起 dev,无 init 前的 shell redirect 场景;
+    // 非白名单栈本地不落 steering 脚手架,也无需预建 logs/。
+    if (!sandbox && scaffoldSteering) {
         (0, logs_dir_1.ensureLogsDir)(targetDir);
     }
     // skills 同步软失败：拉不到 coding-steering 包不该阻断 writeSparkMeta /
@@ -74,21 +79,28 @@ async function handleAppInit(opts) {
     //     跟沙箱端 update-skills.sh 链路对齐
     //   - 本地 → flat (.agents/skills + .claude/skills 软链),
     //     Agent / Claude Code 用同一份;nrf 在本地是主战场,vite-react 等也一样适用
-    const outputLayout = (0, env_1.isSandboxEnv)() ? 'nested' : 'flat';
-    let steeringResult;
+    const outputLayout = sandbox ? 'nested' : 'flat';
+    // 默认空结果：非白名单栈跳过 steering 同步时（scaffoldSteering=false）直接沿用，
+    // 与"拉不到 coding-steering 包"软失败路径共用同一份占位，emit / meta 落盘不受影响。
+    let steeringResult = {
+        version: 'unknown',
+        syncedSkills: [],
+        techSynced: false,
+    };
     let steeringError;
-    try {
-        steeringResult = (0, coding_steering_1.syncCodingSteering)({
-            stack,
-            targetDir,
-            logPrefix: 'init',
-            outputLayout,
-        });
-    }
-    catch (err) {
-        steeringError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
-        steeringResult = { version: 'unknown', syncedSkills: [], techSynced: false };
+    if (scaffoldSteering) {
+        try {
+            steeringResult = (0, coding_steering_1.syncCodingSteering)({
+                stack,
+                targetDir,
+                logPrefix: 'init',
+                outputLayout,
+            });
+        }
+        catch (err) {
+            steeringError = err instanceof Error ? err.message : String(err);
+            (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
+        }
     }
     // 依赖安装：async 模式留到 meta 落盘后派发后台进程（不等装完），同步模式当场装。
     // 同步：装模板钉死的依赖。不带 <pkg>@latest 位置参数,因此 npm 不会改写 package.json/lockfile

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

@@ -55,6 +55,7 @@ async function handleDeployModern(opts) {
         projectDir,
         appId: opts.appId,
         skipBuild: opts.skipBuild ?? false,
+        skipRelease: opts.skipRelease ?? false,
         checkPointVersion: conf.checkPointVersion,
         commitID: conf.commitID,
     });

package/dist/services/app/init/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ASYNC_INSTALL_LOG = exports.runAsyncInstallWorker = exports.dispatchAsyncInstall = exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.IMPORT_SKIP_FILES = exports.IMPORT_SKIP_DIRS = exports.importSourceSrc = exports.TEMPLATE_PACKAGE_BY_STACK = exports.STACK_BY_APP_TYPE = exports.APP_TYPES = exports.SUPPORTED_STACKS = exports.resolveStack = exports.renderTemplate = void 0;
+exports.ASYNC_INSTALL_LOG = exports.runAsyncInstallWorker = exports.dispatchAsyncInstall = exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.IMPORT_SKIP_FILES = exports.IMPORT_SKIP_DIRS = exports.importSourceSrc = exports.TEMPLATE_PACKAGE_BY_STACK = exports.STACK_BY_APP_TYPE = exports.APP_TYPES = exports.LOCAL_STEERING_STACKS = exports.SUPPORTED_STACKS = exports.resolveStack = exports.renderTemplate = void 0;
 var template_1 = require("./template");
 Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
 Object.defineProperty(exports, "resolveStack", { enumerable: true, get: function () { return template_1.resolveStack; } });
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return template_1.SUPPORTED_STACKS; } });
+Object.defineProperty(exports, "LOCAL_STEERING_STACKS", { enumerable: true, get: function () { return template_1.LOCAL_STEERING_STACKS; } });
 Object.defineProperty(exports, "APP_TYPES", { enumerable: true, get: function () { return template_1.APP_TYPES; } });
 Object.defineProperty(exports, "STACK_BY_APP_TYPE", { enumerable: true, get: function () { return template_1.STACK_BY_APP_TYPE; } });
 Object.defineProperty(exports, "TEMPLATE_PACKAGE_BY_STACK", { enumerable: true, get: function () { return template_1.TEMPLATE_PACKAGE_BY_STACK; } });

package/dist/services/app/init/template.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APP_TYPES = exports.STACK_BY_APP_TYPE = exports.SUPPORTED_STACKS = exports.TEMPLATE_PINNED_VERSION_BY_STACK = exports.TEMPLATE_PACKAGE_BY_STACK = void 0;
+exports.APP_TYPES = exports.STACK_BY_APP_TYPE = exports.LOCAL_STEERING_STACKS = exports.SUPPORTED_STACKS = exports.TEMPLATE_PINNED_VERSION_BY_STACK = exports.TEMPLATE_PACKAGE_BY_STACK = void 0;
 exports.resolveStack = resolveStack;
 exports.renderTemplate = renderTemplate;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -27,14 +27,25 @@ exports.TEMPLATE_PACKAGE_BY_STACK = {
  */
 exports.TEMPLATE_PINNED_VERSION_BY_STACK = {};
 exports.SUPPORTED_STACKS = Object.keys(exports.TEMPLATE_PACKAGE_BY_STACK);
+/**
+ * 本地开发（非沙箱）需要落地 agent skills 脚手架（.claude/.agents）与 logs/ 的 stack 白名单。
+ * 只有这些全栈 / 前端框架栈在本地才需要 coding-steering 的 skills；html / design-html 是纯
+ * 静态 / 设计产物，本地无需这套脚手架，init 直接跳过 syncCodingSteering 与 logs 创建。
+ * 沙箱环境不受此白名单约束（所有栈照旧走 nested 同步，产出 .agent/）。
+ */
+exports.LOCAL_STEERING_STACKS = new Set(['nestjs-react-fullstack', 'vite-react']);
 /**
  * app_type（业务类型）→ stack 短名映射。仅在调用方未显式传 --template 时用于解析 stack。
  * 与 src/api/app/types.ts 的 AppType 枚举无关，是独立的业务类型概念。
+ *
+ * 注：`frontend` 是 lark-cli 对外的纯前端应用类型；`jspage` 是内部历史代号，二者同映射
+ * 到 vite-react。保留 jspage 键以兼容内部既有调用方（豆包 / 妙搭链路），不删除。
  */
 exports.STACK_BY_APP_TYPE = {
     html: 'design-html',
     modern_html: 'html',
     jspage: 'vite-react',
+    frontend: 'vite-react',
     full_stack: 'nestjs-react-fullstack',
 };
 exports.APP_TYPES = Object.keys(exports.STACK_BY_APP_TYPE);

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.savePluginInstances = exports.LocalReleaseStatus = exports.finalizeLocalRelease = exports.createLocalRelease = exports.uploadArtifacts = exports.uploadDesignArtifacts = exports.cleanDesignDist = exports.buildDesignOutput = exports.runBuild = exports.preRelease = exports.prepareDeployContext = void 0;
+exports.savePluginInstances = exports.resolveReleaseTracker = exports.createManagedReleaseTracker = exports.NOOP_RELEASE_TRACKER = exports.LocalReleaseStatus = exports.finalizeLocalRelease = exports.createLocalRelease = exports.uploadArtifacts = exports.uploadDesignArtifacts = exports.cleanDesignDist = exports.buildDesignOutput = exports.runBuild = exports.preRelease = exports.prepareDeployContext = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "prepareDeployContext", { enumerable: true, get: function () { return context_1.prepareDeployContext; } });
 var pre_release_1 = require("./pre-release");
@@ -18,5 +18,9 @@ var local_release_1 = require("./local-release");
 Object.defineProperty(exports, "createLocalRelease", { enumerable: true, get: function () { return local_release_1.createLocalRelease; } });
 Object.defineProperty(exports, "finalizeLocalRelease", { enumerable: true, get: function () { return local_release_1.finalizeLocalRelease; } });
 Object.defineProperty(exports, "LocalReleaseStatus", { enumerable: true, get: function () { return local_release_1.LocalReleaseStatus; } });
+var release_tracker_1 = require("./release-tracker");
+Object.defineProperty(exports, "NOOP_RELEASE_TRACKER", { enumerable: true, get: function () { return release_tracker_1.NOOP_RELEASE_TRACKER; } });
+Object.defineProperty(exports, "createManagedReleaseTracker", { enumerable: true, get: function () { return release_tracker_1.createManagedReleaseTracker; } });
+Object.defineProperty(exports, "resolveReleaseTracker", { enumerable: true, get: function () { return release_tracker_1.resolveReleaseTracker; } });
 var save_plugin_instances_1 = require("./save-plugin-instances");
 Object.defineProperty(exports, "savePluginInstances", { enumerable: true, get: function () { return save_plugin_instances_1.savePluginInstances; } });

package/dist/services/deploy/modern/atoms/release-tracker.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOOP_RELEASE_TRACKER = void 0;
+exports.createManagedReleaseTracker = createManagedReleaseTracker;
+exports.resolveReleaseTracker = resolveReleaseTracker;
+const logger_1 = require("../../../../utils/logger");
+const local_release_1 = require("./local-release");
+/**
+ * 建本地发布单并返回受管 tracker。
+ *
+ * url 沿用原有口径：后端 onlineUrl 缺失时为空串（`''` 表示"后端没给"，
+ * 与外部托管模式的 `null`「本模式不产生」是两个不同语义，别合并）。
+ */
+async function createManagedReleaseTracker(appId, version, extra) {
+    (0, logger_1.log)('deploy', 'Creating local release...');
+    const release = await (0, local_release_1.createLocalRelease)(appId, version, extra);
+    return {
+        releaseID: release.releaseID,
+        url: release.onlineUrl ?? '',
+        finish: () => (0, local_release_1.finalizeLocalRelease)(appId, release.releaseID, local_release_1.LocalReleaseStatus.Finished),
+        fail: () => (0, local_release_1.finalizeLocalRelease)(appId, release.releaseID, local_release_1.LocalReleaseStatus.Failed),
+    };
+}
+/**
+ * 空实现：发布单由外部托管，CLI 不建单也不翻终态。
+ *
+ * 外部据 CLI 的退出码决定把自己的发布单翻成 Finished 还是 Failed，
+ * 因此这里的 finish/fail 必须是真正的 no-op，不能顺手打日志误导排查。
+ */
+exports.NOOP_RELEASE_TRACKER = {
+    releaseID: null,
+    url: null,
+    finish: () => Promise.resolve(),
+    fail: () => Promise.resolve(),
+};
+/** 按 skipRelease 选 tracker：跳过则 NOOP，否则建真实发布单。 */
+async function resolveReleaseTracker(opts) {
+    if (opts.skipRelease) {
+        (0, logger_1.log)('deploy', 'Skipping local release (managed externally)');
+        return exports.NOOP_RELEASE_TRACKER;
+    }
+    return createManagedReleaseTracker(opts.appId, opts.version, opts.extra);
+}

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

@@ -24,25 +24,26 @@ async function designLocalPublishPipeline(opts) {
         if (!opts.skipBuild) {
             (0, index_1.buildDesignOutput)({ projectDir: ctx.projectDir });
         }
-        (0, logger_1.log)('deploy', 'Creating local release...');
-        const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
-            checkPointVersion: opts.checkPointVersion,
-            commitID: opts.commitID,
+        const tracker = await (0, index_1.resolveReleaseTracker)({
+            skipRelease: opts.skipRelease ?? false,
+            appId: ctx.appId,
+            version: pre.version,
+            extra: { checkPointVersion: opts.checkPointVersion, commitID: opts.commitID },
         });
         try {
             await (0, index_1.uploadDesignArtifacts)({ projectDir: ctx.projectDir, data });
-            await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
+            await tracker.finish();
         }
         catch (err) {
-            await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
+            await tracker.fail();
             throw err;
         }
         (0, logger_1.log)('deploy', 'Deployed successfully');
         return {
             appId: ctx.appId,
             version: pre.version,
-            url: release.onlineUrl ?? '',
-            releaseID: release.releaseID,
+            url: tracker.url,
+            releaseID: tracker.releaseID,
             preReleaseID: pre.preReleaseID,
         };
     }

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

@@ -11,14 +11,14 @@ const index_1 = require("../atoms/index");
  *   1. prepareDeployContext    — 校验项目 + 读 meta
  *   2. preRelease              — 签发 pre_release_id / version / 动态配置 data
  *   3. runBuild                — 本地 npm run build（注入 data 中的 CDN 前缀）
- *   4. createLocalRelease      — 创建发布单（加锁、拿 releaseID）
+ *   4. resolveReleaseTracker   — 创建发布单（加锁、拿 releaseID）；--skip-release 下为 NOOP
  *   5. uploadArtifacts         — 把产物推到 preRelease 下发的 pre-signed URL
  *   6. savePluginInstances     — 扫描 dist/output_capabilities/*.json，批量注册插件能力
- *   7. finalizeLocalRelease    — Finished / Failed 翻终态
+ *   7. tracker.finish/fail     — Finished / Failed 翻终态
  *
- * createLocalRelease 提前到 upload 之前：发布单先建出来，
- * upload / savePluginInstances 在已知 releaseID 的前提下进行；
+ * 发布单先于 upload 建出来：upload / savePluginInstances 在已知 releaseID 的前提下进行；
  * 任一步失败都会精准把该发布单标记为 Failed，避免遗留挂态。
+ * `--skip-release` 下发布单由外部托管，tracker 为 NOOP，失败信息通过非零退出码传递。
  */
 async function localBuildLocalPublishPipeline(opts) {
     const ctx = (0, index_1.prepareDeployContext)(opts.projectDir, opts.appId);
@@ -41,10 +41,11 @@ async function localBuildLocalPublishPipeline(opts) {
             data,
         });
     }
-    (0, logger_1.log)('deploy', 'Creating local release...');
-    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
-        checkPointVersion: opts.checkPointVersion,
-        commitID: opts.commitID,
+    const tracker = await (0, index_1.resolveReleaseTracker)({
+        skipRelease: opts.skipRelease ?? false,
+        appId: ctx.appId,
+        version: pre.version,
+        extra: { checkPointVersion: opts.checkPointVersion, commitID: opts.commitID },
     });
     try {
         (0, logger_1.log)('deploy', 'Uploading artifacts...');
@@ -57,18 +58,18 @@ async function localBuildLocalPublishPipeline(opts) {
         if (saveResult.saved > 0) {
             (0, logger_1.log)('deploy', `${String(saveResult.saved)} capability instance(s) registered`);
         }
-        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
+        await tracker.finish();
     }
     catch (err) {
-        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
+        await tracker.fail();
         throw err;
     }
     (0, logger_1.log)('deploy', 'Deployed successfully');
     return {
         appId: ctx.appId,
         version: pre.version,
-        url: release.onlineUrl ?? '',
-        releaseID: release.releaseID,
+        url: tracker.url,
+        releaseID: tracker.releaseID,
         preReleaseID: pre.preReleaseID,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.24-alpha.77f133a",
+  "version": "0.1.24-alpha.800d445",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {