@lark-apaas/miaoda-cli 0.1.33-alpha.2ce4ff9 → 0.1.33-alpha.3cbfb24

package/README.md

@@ -57,7 +57,7 @@ miaoda file ls --output json
 `miaoda app pack`（默认 `--mode standalone`）把当前应用构建成一份自包含静态产物，可脱离妙搭平台本地打开。
 
 ```bash
-miaoda app pack                    # → dist/standalone/ + dist/standalone.zip
+miaoda app pack                    # → dist/standalone.zip（中间目录打完即删）
 miaoda app pack --out dist/share
 miaoda app pack --json
 miaoda app pack --upload-url 'https://tos.example.com/x.zip?sign=...'

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

@@ -184,8 +184,7 @@ function registerAppPack(parent) {
         .description('打包应用产物。默认 standalone 模式：自包含静态产物（目录 + zip），可脱离妙搭平台本地访问')
         .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
         .option('--mode <mode>', `打包形态（${index_1.PACK_MODES.join(' / ')}）`, index_1.DEFAULT_PACK_MODE)
-        .option('--out <dir>', '输出目录（相对项目根）', index_1.DEFAULT_PACK_OUT)
-        .option('--dev-server <url>', '图片下载的请求前缀，默认沙箱网关 http://localhost:8080')
+        .option('--out <dir>', '产物路径（相对项目根），实际产出 <out>.zip', index_1.DEFAULT_PACK_OUT)
         .option('--upload-url <url>', '打包后把 zip 以 PUT 上传到该预签名 URL（http/https）；上传成功后清掉本地产物')
         .addHelpText('after', `
 与 'miaoda app export' 的区别（**两个命令语义无关，别选错**）
@@ -200,13 +199,14 @@ function registerAppPack(parent) {
   design-html / html / vite-react / nestjs-react-fullstack
 
 产物
-  <out>/          index.html + assets/ + images/（+ static/，vite 系有 shared/static 时）
-  <out>.zip       同内容的压缩包
+  <out>.zip       **唯一交付物**。内含 index.html + assets/ + images/
+                  （+ static/，vite 系有 shared/static 时）
+  <out>/          打包用的中间目录，**打完包即删除**——它与 zip 内容重复，
+                  留着占双份磁盘。要预览请先解压。
   传了 --upload-url 时，zip 会以 PUT 裸 body（Content-Type: application/zip）
   上传到该地址——预签名 URL 的标准形态，鉴权由 URL 自带签名承担，不加额外 header。
-  **上传成功后本地产物（目录 + zip）会被清掉**，交付物以远端为准，JSON 里
-  localRemoved=true；此时不要再去读 out / zip 路径。
-  上传失败则保留本地产物，便于修正后重跑或手动上传。
+  **上传成功后本地 zip 也会被清掉**（目录本就已删），交付物以远端为准，
+  JSON 里 localRemoved=true。上传失败则保留 zip，便于修正后重跑或手动上传。
   默认 <out> 是 dist/standalone —— 落在 dist/ 下是刻意的：dist 已在部署扫描的
   EXCLUDES 与各模板 .gitignore 中，产物不会污染部署包、不会被误提交。
   代价：下一次构建会 rm -rf dist，导出产物是易失的。
@@ -249,7 +249,6 @@ JSON 输出
         await (0, index_1.handleAppPack)({
             dir: rawOpts.dir,
             out: rawOpts.out,
-            devServer: rawOpts.devServer,
             uploadUrl: rawOpts.uploadUrl,
             mode: rawOpts.mode,
         });

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

@@ -7,6 +7,7 @@ exports.handleAppInit = handleAppInit;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../../../services/app/init/index");
+const dir_lock_1 = require("../../../utils/dir-lock");
 const coding_steering_1 = require("../../../utils/coding-steering");
 const logger_1 = require("../../../utils/logger");
 const githooks_1 = require("../../../utils/githooks");
@@ -86,16 +87,23 @@ async function handleAppInit(opts) {
         version: 'unknown',
         syncedSkills: [],
         techSynced: false,
+        prunedStacks: [],
     };
     let steeringError;
     if (scaffoldSteering) {
         try {
-            steeringResult = (0, coding_steering_1.syncCodingSteering)({
+            // 与会话期的 `skills sync` 互斥：两者都写 `.agent/skills`，而写入策略是按目录
+            // 整清再拷。线上实测过这条竞态 —— init 的 steering 同步撞上 sync 收尾的
+            // `chmod -R a=rX`，报 `EACCES: mkdir '.agent/skills/steering/<stack>/skills'`。
+            steeringResult = (0, dir_lock_1.withDirLock)(targetDir, () => (0, coding_steering_1.syncCodingSteering)({
                 stack,
                 targetDir,
                 logPrefix: 'init',
                 outputLayout,
-            });
+                // match-template-version 门禁的比对基准：用刚渲染的 template 实际版本，
+                // 与随后写入 .spark/meta.json 的 version 同源（见下方 writeSparkMeta）
+                templateVersion: tplResult.version,
+            }));
         }
         catch (err) {
             steeringError = err instanceof Error ? err.message : String(err);

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

@@ -144,12 +144,10 @@ async function handleAppMigrate(opts) {
     // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
     // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
     //
-    //   - 只在 SANDBOX_ID 非空时做(本地一般不会撞这条链路)
+    //   - 只在沙箱内做(isSandboxEnv;本地一般不会撞这条链路)
     //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
     //   - 软失败:.vite 不存在 / 删失败都不阻断
-    if (installError === undefined &&
-        process.env.SANDBOX_ID !== undefined &&
-        process.env.SANDBOX_ID !== '') {
+    if (installError === undefined && (0, env_1.isSandboxEnv)()) {
         const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
         if (node_fs_1.default.existsSync(viteCacheDir)) {
             (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');

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

@@ -37,19 +37,6 @@ function normalizeOutDir(rel) {
 }
 /** 沙箱网关地址：它才是代理 `/spark/app` 的那个服务（响应头 `Server: openresty`）。 */
 const SANDBOX_GATEWAY_BASE = 'http://localhost:8080';
-/**
- * 图片下载的请求前缀。
- *
- * **刻意写死 8080，不读 `CLIENT_DEV_PORT`。** 那个 env 表示的是「应用自己的 dev server
- * 监听端口」，与「谁在代理 `/spark/app`」是两回事：design-html / html 用
- * `coding-static-server`（默认 8001，纯静态、完全不代理），读了它会把请求打到静态
- * server 上，稳定 404。真机踩过。
- */
-function resolveDevServerBase(explicit) {
-    if (explicit)
-        return explicit.replace(/\/+$/, '');
-    return SANDBOX_GATEWAY_BASE;
-}
 /** 遍历产物树里的文本文件，返回 posix 相对路径。 */
 function* walkText(dir, rel = '') {
     for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
@@ -174,7 +161,7 @@ async function handleAppPack(opts) {
         }
     }
     // 3. 下载
-    const devServerBase = resolveDevServerBase(opts.devServer);
+    const devServerBase = SANDBOX_GATEWAY_BASE;
     (0, logger_1.log)('pack', `Matched ${String(urls.length)} image url(s), fetching via ${devServerBase}`);
     const { mapping, failed } = await (0, index_1.downloadImages)(urls, {
         imagesDir: node_path_1.default.join(outDir, 'images'),
@@ -189,17 +176,19 @@ async function handleAppPack(opts) {
                 ...(failed.length > 1
                     ? [`其余 ${String(failed.length - 1)} 条见 --verbose（每条请求地址都会打到 stderr）`]
                     : []),
-                `实际请求前缀：${devServerBase}${opts.devServer ? '（--dev-server 指定）' : '（沙箱网关默认）'}`,
-                '若端口不对，可用 --dev-server http://localhost:<port> 覆盖',
+                `实际请求前缀：${devServerBase}（沙箱网关）`,
             ],
         });
     }
     // 4. 改写
     const rewrittenFiles = (0, index_1.rewriteTree)(outDir, mapping);
-    // 5. 打包
-    (0, index_1.zipDir)(outDir, zipPath);
-    // 6. 统计。**必须在清理之前**——上传成功后本地产物会被删掉，那时就量不到了。
+    // 5. 统计。**必须在打包前做**——目录随后就被删掉，那时量不到了。
     const { fileCount, bytes } = measure(outDir);
+    // 6. 打包，随后删掉目录。目录是**中间态**，zip 才是交付物；两者内容重复，
+    // 留着等于占双份磁盘。预览需先解压。
+    (0, index_1.zipDir)(outDir, zipPath);
+    node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
+    (0, logger_1.log)('pack', `Packed ${zipRel}, staging dir removed`);
     // 7. 上传（可选）。放在 emit 之前——传了 --upload-url 就说明上传是目的，
     // 失败要让整个命令失败（退出码 1），不能先 emit 成功再抛。
     // JSON 输出里**不回显 URL**（凭证类信息），只给状态码与服务端 log_id。
@@ -215,10 +204,10 @@ async function handleAppPack(opts) {
     let localRemoved = false;
     if (upload) {
         try {
-            node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
+            // 目录在打包后已删，这里只需清 zip
             node_fs_1.default.rmSync(zipPath, { force: true });
             localRemoved = true;
-            (0, logger_1.log)('pack', `Uploaded, local artifacts removed (${outRel}, ${zipRel})`);
+            (0, logger_1.log)('pack', `Uploaded, local zip removed (${zipRel})`);
         }
         catch (err) {
             warnings.push({
@@ -248,8 +237,8 @@ async function handleAppPack(opts) {
             mode,
             out: outRel,
             zip: zipRel,
-            // 上传成功后本地产物已被清掉——调用方**不要**再去读 out / zip 这两个路径，
-            // 它们只描述"产出过什么"，不代表现在还在。
+            // ⚠️ out 指向的**目录在打包后即被删除**（它只是中间态），永远不要去读它。
+            // zip 是本地交付物；localRemoved=true 时连 zip 也被清了（已上传到远端）。
             localRemoved,
             fileCount,
             bytes,

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

@@ -9,6 +9,7 @@ const coding_steering_1 = require("../../../utils/coding-steering");
 const sandbox_skills_1 = require("../../../utils/sandbox-skills");
 const file_ops_1 = require("../../../utils/file-ops");
 const spark_meta_1 = require("../../../utils/spark-meta");
+const dir_lock_1 = require("../../../utils/dir-lock");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 /**
@@ -24,24 +25,35 @@ const output_1 = require("../../../utils/output");
  */
 function syncSteeringForSandbox(params) {
     let stack;
+    // 提到 try 外：下面 syncCodingSteering 要用它做 match-template-version 门禁
+    let templateVersion;
     try {
         const meta = (0, spark_meta_1.readSparkMeta)(params.targetDir);
         if (meta.stack === undefined || meta.stack === '' || meta.stack === 'null') {
             return { status: 'skipped', reason: '.spark/meta.json missing stack' };
         }
         stack = meta.stack;
+        templateVersion = meta.version;
     }
     catch (err) {
         return { status: 'skipped', reason: `read .spark/meta.json failed: ${err.message}` };
     }
-    // 版本口径与下方本地分支保持一致：--version > BOE 的 dist-tag dev > latest
-    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
-    const effectiveVersion = params.version ?? (isBoe ? 'dev' : undefined);
+    // 版本口径：--version > lane（TCC tgzKey）> BOE 的 dist-tag dev > latest。
+    //
+    // **这里不预先把 BOE 解成 'dev'**（下方本地分支为了回报 versionSource 才那么做）：
+    // 一旦提前填进 version，就会盖住 lane —— version 在优先级里高于 lane，BOE 沙箱上
+    // 配了 tgzKey 也永远命中不了。把 version 原样透传（未指定就是 undefined），让
+    // syncCodingSteering 一处算全链：version > lane > dev > latest。
     try {
         const r = (0, coding_steering_1.syncCodingSteering)({
             stack,
             targetDir: params.targetDir,
-            version: effectiveVersion,
+            version: params.version,
+            // TCC 的 X 与平铺 skill 共用：pickLaneVersion 只匹配 `-alpha.<X>` 后缀，
+            // 不看 base 版本，所以一个 key 同时定向 coding-steering 与 sandbox-skills。
+            tgzKey: params.tgzKey,
+            // match-template-version 门禁的比对基准（老 update-skills.sh 读的同一个字段）
+            templateVersion,
             // 必须显式传 mode，不能落到 inferMode()：它靠 env MIAODA_DEP_CACHE_DIR 嗅探，
             // 而 mode 决定读包内哪个 layer（sandbox→`skills/`，local→`skills_local/`）。
             // `--type` 分支本身就是沙箱语义，嗅探失手会去读不存在的 skills_local/、
@@ -56,6 +68,7 @@ function syncSteeringForSandbox(params) {
             version: r.version,
             syncedSkills: r.syncedSkills,
             techSynced: r.techSynced,
+            prunedStacks: r.prunedStacks,
         };
     }
     catch (err) {
@@ -70,9 +83,16 @@ function syncSteeringForSandbox(params) {
  *
  * 版本来源优先级（从高到低）：
  *   1. CLI `--version` flag（显式指定）
- *   2. `FORCE_FRAMEWORK_ENVIRONMENT=boe` → dist-tag `dev`（BOE 测试灰度，跟随
+ *   2. lane：`--type` 分支下由 TCC `skillsUpdateTgzKey` 透传 `--tgz-key`，反推 X 后
+ *      解析出 `-alpha.<X>` 版本。**与平铺 skill 共用同一个 X** —— 匹配只看后缀、
+ *      不看 base 版本，所以 TCC 配一个 key 就同时定向 coding-steering 与 sandbox-skills。
+ *      本地分支（不带 `--type`）没有 tgzKey，这一档天然不参与。
+ *   3. `FORCE_FRAMEWORK_ENVIRONMENT=boe` → dist-tag `dev`（BOE 测试灰度，跟随
  *      publish-alpha.sh 在 develop 分支打的 dev tag，便于在 BOE 沙箱里验证预发 steering）
- *   3. 默认 `latest`
+ *   4. 默认 `latest`
+ *
+ * 2/3/4 档统一在 `syncCodingSteering` 里算（见那边注释），handler 只负责透传，避免
+ * 提前把 `dev` 填进 version 把 lane 挤掉。
  *
  * **不读 meta.json**——steering 版本不在 meta 里钉。
  */
@@ -95,41 +115,57 @@ async function handleSkillsSync(opts) {
     // 冻结只冻结了一半。
     if (opts.type !== undefined && opts.type !== '') {
         const { type, tgzKey } = (0, sandbox_skills_1.validateSandboxSyncOpts)({ type: opts.type, tgzKey: opts.tgzKey });
-        const result = (0, sandbox_skills_1.syncSandboxSkills)({ type, tgzKey, targetDir });
-        const steering = result.skippedByKeepFile
-            ? { status: 'skipped', reason: '.keep file found, sync frozen' }
-            : syncSteeringForSandbox({ targetDir, version: opts.version });
-        // ③ 收尾锁只读（update-skills.sh:241 的 chmod -R a=rX）。必须在 ①② 全部写完之后，
-        //    锁上就写不进去了。`.keep` 冻结时不锁 —— 老链路那条路径是 exit 0 直接走、
-        //    末尾的 chmod 压根不执行，保持一致。
-        //
-        // **只锁沙箱侧**：这里的 result.targetDir 只会是 `.agent/skills` 或 `skills`
-        //   （见 sandbox-skills 的 skillsRoot），都是平台下发的资产根。本地 `--local` 走
-        //   flat layout 输出到 `.agents/`，压根不经过本分支，权限不会被碰。
-        //
-        // 回退风险由解锁侧兜：权限是持久化在磁盘的，代码能回退、磁盘状态不会。所以
-        //   file-ops 的 unlockDirForWrite 在**两处写入前**都调用了（syncSandboxSkills 的
-        //   写入前 + syncCodingSteering 的 nested 分支写入前），任一入口都不会因为
-        //   上一轮的锁而 EACCES。改动这里之前先确认那两处解锁还在。
-        const lockedReadonly = result.skippedByKeepFile ? false : (0, file_ops_1.lockDirReadonly)(result.targetDir);
-        (0, output_1.emit)({
-            data: {
-                mode: 'sandbox',
-                type,
-                packageName: result.packageName,
-                version: result.version,
-                lane: result.lane,
-                syncedTop: result.syncedTop,
-                deleted: result.deleted,
-                skippedByKeepFile: result.skippedByKeepFile,
-                lockedReadonly,
-                targetDir: result.targetDir,
-                steering,
-            },
+        // 并发锁覆盖「平铺同步 + steering 同步 + 收尾 chmod」整段：写入策略是按目录整清再拷，
+        // 两个实例并发会互相看到半清空状态，而 feida-ai 的 scanAllSkills 是会话期按需扫盘。
+        // 对齐老 update-skills.sh:157-159 的 flock。
+        (0, dir_lock_1.withDirLock)(targetDir, () => {
+            syncSandboxAndSteering({ opts, targetDir, type, tgzKey });
         });
         return;
     }
     // 原有 coding-steering 同步逻辑（本地 dev / miaoda app init 用）
+    (0, dir_lock_1.withDirLock)(targetDir, () => {
+        syncSteeringOnly({ opts, targetDir });
+    });
+}
+function syncSandboxAndSteering(params) {
+    const { opts, targetDir, type, tgzKey } = params;
+    const result = (0, sandbox_skills_1.syncSandboxSkills)({ type, tgzKey, targetDir });
+    const steering = result.skippedByKeepFile
+        ? { status: 'skipped', reason: '.keep file found, sync frozen' }
+        : syncSteeringForSandbox({ targetDir, version: opts.version, tgzKey });
+    // ③ 收尾锁只读（update-skills.sh:241 的 chmod -R a=rX）。必须在 ①② 全部写完之后，
+    //    锁上就写不进去了。`.keep` 冻结时不锁 —— 老链路那条路径是 exit 0 直接走、
+    //    末尾的 chmod 压根不执行，保持一致。
+    //
+    // **只锁沙箱侧**：这里的 result.targetDir 只会是 `.agent/skills` 或 `skills`
+    //   （见 sandbox-skills 的 skillsRoot），都是平台下发的资产根。本地 `--local` 走
+    //   flat layout 输出到 `.agents/`，压根不经过本分支，权限不会被碰。
+    //
+    // 回退风险由解锁侧兜：权限是持久化在磁盘的，代码能回退、磁盘状态不会。所以
+    //   file-ops 的 unlockDirForWrite 在**两处写入前**都调用了（syncSandboxSkills 的
+    //   写入前 + syncCodingSteering 的 nested 分支写入前），任一入口都不会因为
+    //   上一轮的锁而 EACCES。改动这里之前先确认那两处解锁还在。
+    const lockedReadonly = result.skippedByKeepFile ? false : (0, file_ops_1.lockDirReadonly)(result.targetDir);
+    (0, output_1.emit)({
+        data: {
+            mode: 'sandbox',
+            type,
+            packageName: result.packageName,
+            version: result.version,
+            lane: result.lane,
+            syncedTop: result.syncedTop,
+            deleted: result.deleted,
+            skippedByKeepFile: result.skippedByKeepFile,
+            lockedReadonly,
+            targetDir: result.targetDir,
+            steering,
+        },
+    });
+}
+/** 不带 --type 的本地 / init 形态：只同步 coding-steering。 */
+function syncSteeringOnly(params) {
+    const { opts, targetDir } = params;
     const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('SKILLS_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
@@ -141,6 +177,7 @@ async function handleSkillsSync(opts) {
         stack: meta.stack,
         targetDir,
         version: effectiveVersion,
+        templateVersion: meta.version,
         outputLayout: opts.local === true ? 'flat' : 'nested',
     });
     (0, output_1.emit)({
@@ -150,6 +187,7 @@ async function handleSkillsSync(opts) {
             versionSource,
             syncedSkills: result.syncedSkills,
             techSynced: result.techSynced,
+            prunedStacks: result.prunedStacks,
             ...(result.claudeSkillsLink !== undefined
                 ? { claudeSkillsLink: result.claudeSkillsLink }
                 : {}),

package/dist/config/sync-configs/design-stack.js

@@ -91,7 +91,7 @@ exports.SYNC_CONFIG = {
             ifStartsWith: 'npm run upgrade && ',
         },
         // ===== miaoda-cli 本地开发新增规则 =====
-        // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
+        // M1. scripts.dev:local —— 本地用户绕过沙箱判定直接跑本地链路（npm run dev:local）。
         {
             type: 'add-script',
             name: 'dev:local',

package/dist/config/sync-configs/index.js

@@ -23,13 +23,15 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const nestjs_react_fullstack_1 = __importDefault(require("./nestjs-react-fullstack"));
 const design_stack_1 = __importDefault(require("./design-stack"));
+const vite_react_1 = __importDefault(require("./vite-react"));
 /**
- * 已纳入新 sync 机制的 stack 注册表。未在表里的 stack（如老 vite-react / html）走旧的
+ * 已纳入新 sync 机制的 stack 注册表。未在表里的 stack（如 html / design-html）走旧的
  * `upgrade/templates/<stack>/{files,patches}` 机制，由 sync handler 兜底。
  */
 const STACK_REGISTRY = {
     'nestjs-react-fullstack': nestjs_react_fullstack_1.default,
     'design-stack': design_stack_1.default,
+    'vite-react': vite_react_1.default,
 };
 /** 返回该 stack 的 SyncConfig；表里没有时返回 null。 */
 function getSyncConfig(stack) {

package/dist/config/sync-configs/nestjs-react-fullstack.js

@@ -135,8 +135,8 @@ exports.SYNC_CONFIG = {
             ifStartsWith: 'concurrently ',
         },
         // 10. 把老 `npm run upgrade && ./scripts/dev.sh` 形式迁移到 `./scripts/dev.sh`，
-        //     让本地 `npm run dev` 不再前置跑 fullstack-cli sync。新版 dev.sh 按 SANDBOX_ID 是否非空
-        //     判分支：沙箱直接 exec dev.js（脚本同步由平台 pod 启动时做过，dev 入口不再 upgrade）；
+        //     让本地 `npm run dev` 不再前置跑 fullstack-cli sync。新版 dev.sh 按 MIAODA_DEP_CACHE_DIR
+        //     是否非空判分支：沙箱直接 exec dev.js（脚本同步由平台 pod 启动时做过，dev 入口不再 upgrade）；
         //     本地走 miaoda app sync 兜底 + dev-local.js。
         {
             type: 'patch-script',
@@ -160,8 +160,8 @@ exports.SYNC_CONFIG = {
             ifStartsWith: 'npx -y @lark-apaas/fullstack-cli sync',
         },
         // ===== miaoda-cli 本地开发新增规则（fullstack-cli sync 不会执行） =====
-        // M1. scripts.dev:local —— 本地用户绕过 SANDBOX_ID 分发直接跑本地链路（npm run dev:local）。
-        //     dev.sh 在 SANDBOX_ID 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.js；显式 dev:local
+        // M1. scripts.dev:local —— 本地用户绕过沙箱判定直接跑本地链路（npm run dev:local）。
+        //     dev.sh 在 MIAODA_DEP_CACHE_DIR 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.js；显式 dev:local
         //     用于 agent 在本地稳定调试，不受任何 env 影响。
         {
             type: 'add-script',

package/dist/config/sync-configs/vite-react.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * vite-react sync 规则（镜像 fullstack-cli 的 viteReactProfile）：只同步 build.sh 一支，
+ * 回溯 public/* → dist/output/ 修复。
+ * ⚠️ build.sh 源须与 miaoda-coding 模板、fullstack-cli `templates/vite-react/build.sh` 逐字一致。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_CONFIG = void 0;
+exports.SYNC_CONFIG = {
+    sync: [
+        // 覆盖 scripts/build.sh：回溯 public/* → dist/output/（同源根 /app/<appId>/*）修复
+        {
+            type: 'file',
+            from: 'scripts/build.sh',
+            to: 'scripts/build.sh',
+            overwrite: true,
+        },
+    ],
+};
+exports.default = exports.SYNC_CONFIG;

package/dist/services/app/pack/scan.js

@@ -53,6 +53,25 @@ function isSameOriginRelative(text, index) {
         return true;
     return BOUNDARY_CHARS.has(text[index - 1]);
 }
+/**
+ * aPaaS 存储路径特征段。命中其一才认为是「应用存储里的资源」。
+ *
+ * **为什么必须限定**：只按 `/spark/app/` 前缀匹配会把**接口地址**一并扫走 ——
+ * 真机踩过，SDK 里的 `/spark/app/<id>/runtime/api/v1/observability/logs/collect`、
+ * `.../permissions/roles` 四条接口进了下载队列，全部 404 后被报成「4 张图片下载失败」。
+ *
+ * 这三段与 `miaoda-coding` 的 `cd-elements/src/core/tos.ts` 的 `SRC_ALLOWLIST` 同一份。
+ */
+const STORAGE_PATH_SEGMENTS = [
+    '/runtime/api/v1/storage/object/',
+    '/aily/api/v1/feisuda/attachments/',
+    '/aily/api/v1/files/static/',
+];
+/**
+ * 模板字符串插值标记：`/spark/app/${e}/...`。压缩后的 SDK 里大量存在，它们**不是具体 URL**
+ * ——变量在运行时才求值，照原样请求必然 404。
+ */
+const TEMPLATE_INTERPOLATION = '${';
 /**
  * 扫出去重后的 URL 列表，保持首次出现的顺序（便于测试断言与日志可读）。
  */
@@ -63,6 +82,10 @@ function scanSparkAppUrls(text) {
         if (!isSameOriginRelative(text, m.index))
             continue;
         const url = m[0];
+        if (url.includes(TEMPLATE_INTERPOLATION))
+            continue;
+        if (!STORAGE_PATH_SEGMENTS.some((seg) => url.includes(seg)))
+            continue;
         if (seen.has(url))
             continue;
         seen.add(url);

package/dist/services/app/pack/strategies.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PACK_SUPPORTED_STACKS = void 0;
 exports.buildStandaloneEnv = buildStandaloneEnv;
 exports.liftNestedEntry = liftNestedEntry;
+exports.copySharedStatic = copySharedStatic;
+exports.pruneStaticNoise = pruneStaticNoise;
 exports.resolveStrategy = resolveStrategy;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -45,6 +47,12 @@ function buildStandaloneEnv(base) {
     // `/assets/x.js` 绝对路径，file:// 下指向文件系统根，页面白屏（真机踩过）。
     // vite-react 那边 build.sh 会用同样的值覆盖它，两条路结果一致。
     env.ASSETS_CDN_PATH = './';
+    // shared/static 的 URL 前缀。同样要**两个名字都给**：
+    //   vite-react 走 build.sh，里面 `export STATIC_ASSETS_BASE_URL="${MIAODA_STATIC_CDN_PREFIX}"`
+    //     会无条件覆盖直接注入的值 —— 只给 STATIC_ASSETS_BASE_URL 会被冲成空，
+    //     插件退化成绝对路径 `/avatar.jpg`，file:// 下必挂（真机踩过）。
+    //   nestjs 走 build:client 直连 vite，没有那层映射，只认 STATIC_ASSETS_BASE_URL。
+    env.MIAODA_STATIC_CDN_PREFIX = './static';
     env.STATIC_ASSETS_BASE_URL = './static';
     return env;
 }
@@ -109,6 +117,86 @@ function dropSourceMaps(outDir) {
     };
     walk(outDir);
 }
+/**
+ * 把 `shared/static/` 拷进产物的 `static/`。
+ *
+ * `shared/static/*` 不是 vite 的产物 —— 插件只把它们解析成 URL 字符串，真实文件靠
+ * 构建脚本搬。vite-react 的 `scripts/build.sh` 会 rsync 到 `dist/output_static`，
+ * 但 **nestjs 的 build.sh 完全没有这段**，而我们又绕过它直接跑 `build:client`，
+ * 所以没人搬 —— 产物里引用了 `./static/avatar.jpg` 却没有这个文件（真机踩过）。
+ *
+ * 排除规则对齐 vite-react build.sh：跳过 `.ts/.tsx/.js/.jsx`（那些是代码不是资源，
+ * 由 bundler 处理）。JSON 无需排除：它走 `window.__STATIC_JSON__` 内联，多拷一份无害。
+ *
+ * 只负责「搬」，模板 README 的剔除交给 `pruneStaticNoise` —— vite-react 那条路径
+ * 的 static/ 是 build.sh 搬的、根本不经过这里，规则放这儿会漏掉它（真机漏过）。
+ */
+const SHARED_STATIC_SKIP_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+function copySharedStatic(projectDir, outDir) {
+    const src = node_path_1.default.join(projectDir, 'shared', 'static');
+    if (!node_fs_1.default.existsSync(src))
+        return;
+    const dest = node_path_1.default.join(outDir, 'static');
+    const walk = (dir, rel) => {
+        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            const abs = node_path_1.default.join(dir, entry.name);
+            const childRel = rel ? node_path_1.default.join(rel, entry.name) : entry.name;
+            if (entry.isDirectory()) {
+                walk(abs, childRel);
+                continue;
+            }
+            if (SHARED_STATIC_SKIP_EXTENSIONS.has(node_path_1.default.extname(entry.name).toLowerCase())) {
+                continue;
+            }
+            const to = node_path_1.default.join(dest, childRel);
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(to), { recursive: true });
+            node_fs_1.default.copyFileSync(abs, to);
+        }
+    };
+    walk(src, '');
+}
+const STATIC_NOISE_FILENAME = 'readme.md';
+/**
+ * 从产物的 `static/` 里剔掉模板自带的 README.md，并清掉因此空掉的目录。
+ *
+ * 模板给 `shared/static/` 配了一份 README.md 讲这个目录怎么用（跟 `src/assets`、
+ * `public` 的区别、为什么要走 SDK 拿带 token 的 URL），是给开发者看的文档不是应用
+ * 资源。多数应用没往这个目录放东西，产物里就只剩这一个 README 孤零零躺着。
+ *
+ * **两条路径都要过这里**：nestjs 侧 static/ 由 `copySharedStatic` 搬，vite-react 侧
+ * 由 `scripts/build.sh` rsync 到 `dist/output_static` 再 merge 进来——build.sh 的
+ * `--exclude` 只排了四个代码扩展名，README 照样进产物。规则只写在搬运侧会漏掉另一条。
+ *
+ * 只排 `README.md` 这一个名字（大小写不敏感）。其余 `.md` 照留——应用拿 markdown
+ * 当资源（说明书、协议文本）是合理用法，不该替它做主。
+ */
+function pruneStaticNoise(outDir) {
+    const root = node_path_1.default.join(outDir, 'static');
+    if (!node_fs_1.default.existsSync(root))
+        return;
+    // 返回该目录清理后是否已空，空则连目录一起删（空目录进 zip 同样是噪音）
+    const prune = (dir) => {
+        let kept = 0;
+        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            const abs = node_path_1.default.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!prune(abs))
+                    kept += 1;
+                continue;
+            }
+            if (entry.name.toLowerCase() === STATIC_NOISE_FILENAME) {
+                node_fs_1.default.rmSync(abs, { force: true });
+                continue;
+            }
+            kept += 1;
+        }
+        if (kept > 0)
+            return false;
+        node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+        return true;
+    };
+    prune(root);
+}
 /** 从产物树里删掉 routes.json —— 平台/server 路由用，standalone 无人读取。 */
 function dropRoutesJson(outDir) {
     node_fs_1.default.rmSync(node_path_1.default.join(outDir, 'routes.json'), { force: true });
@@ -162,6 +250,7 @@ const viteReactStrategy = ({ projectDir, outDir }) => {
     mergeInto(node_path_1.default.join(dist, 'output'), outDir);
     mergeInto(node_path_1.default.join(dist, 'output_resource', 'assets'), node_path_1.default.join(outDir, 'assets'));
     mergeInto(node_path_1.default.join(dist, 'output_static'), node_path_1.default.join(outDir, 'static'));
+    pruneStaticNoise(outDir);
     dropSourceMaps(outDir);
     dropRoutesJson(outDir);
 };
@@ -196,6 +285,8 @@ const nestjsStrategy = ({ projectDir, outDir }) => {
         node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
         node_fs_1.default.mkdirSync(outDir, { recursive: true });
         mergeInto(tmpDist, outDir);
+        copySharedStatic(projectDir, outDir);
+        pruneStaticNoise(outDir);
     }
     finally {
         // 临时构建目录不留在用户项目里