@lark-apaas/miaoda-cli 0.1.29 → 0.1.31

package/README.md

@@ -46,16 +46,16 @@ miaoda file ls --output json
 | `miaoda file ...`          | 文件操作：上传、下载、元数据、签名下载、批量删除     |
 | `miaoda db ...`            | 数据操作：SQL 执行、表结构查询、数据导入导出         |
 | `miaoda observability ...` | 线上日志、链路、前端源码堆栈反查、监控指标、运营指标 |
-| `miaoda comment ...`       | 应用评论：查看评论列表、解决评论                     |
-| `miaoda registry ...`      | 组件 registry：列出 / copy-in design-html SDK 文件（本地执行）     |
+| `miaoda comment ...`       | 应用评论：查看评论列表、解决评论（仅 design-html 场景开放）        |
+| `miaoda registry ...`      | 组件 registry：列出 / copy-in SDK 文件（本地执行）                 |
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
-## 组件 registry（design-html）
+## 组件 registry
 
-`miaoda registry` 为 design-html 技术栈提供 shadcn 式的「组件 registry」：把 SDK 文件**拷进**当前项目（copy-in），而非作为依赖安装。registry 是独立 npm 包，按运行时分发（design-html → buildless runtime → `@lark-apaas/coding-registry-buildless`）。
+`miaoda registry` 提供 shadcn 式的「组件 registry」：把 SDK 文件**拷进**当前项目（copy-in），而非作为依赖安装。registry 是独立 npm 包，按运行时分发（design-html / html → buildless runtime → `@lark-apaas/coding-registry-buildless`）。
 
-前置：当前目录（或 `--dir`）已走过 `miaoda app init`，`.spark/meta.json` 含 `stack=design-html`。
+前置：当前目录（或 `--dir`）已走过 `miaoda app init`，且 `.spark/meta.json` 的 `stack` 有对应 registry 包（当前支持 `design-html` / `html`）；其余 stack 执行时报 `REGISTRY_STACK_UNSUPPORTED` 并提示支持列表。
 
 ```bash
 # 列出可用 SDK 条目（输出各文件 USAGE 注释块原文，便于 Agent 直接读用法）

package/dist/api/app/api.js

@@ -5,6 +5,7 @@ exports.updateAppMeta = updateAppMeta;
 exports.getCodeArchive = getCodeArchive;
 const http_1 = require("../../utils/http");
 const devops_error_1 = require("../../utils/devops-error");
+const error_1 = require("../../utils/error");
 const DEFAULT_ERR_CODE = 'INTERNAL_DEVOPS_ERROR';
 function envelopeOpts(errPrefix) {
     return {
@@ -24,22 +25,66 @@ async function updateAppMeta(req) {
     // 路径已带 appID，body 里也保留以匹配 BAM IDL 的 sensitive:"no" 透传约定
     return (0, http_1.postInnerApi)(url, req, envelopeOpts('Failed to update app'));
 }
+function mapExportError(bizCode, message, source) {
+    // token 是敏感令牌，错误信息只截前 8 位辅助定位
+    const sourceDesc = source.sourceAppID
+        ? `应用 ${source.sourceAppID}`
+        : `分享 token ${(source.sourceMetaToken ?? '').slice(0, 8)}...`;
+    switch (bizCode) {
+        // 身份换取失败，或非源应用协作者（服务端 DOWNLOAD 鉴权不过）
+        case devops_error_1.BizErrCode.STUDIO_UNAUTHENTICATED:
+            return new error_1.AppError('EXPORT_PERMISSION_DENIED', `无权导出 ${sourceDesc}：${message}`, {
+                next_actions: [
+                    `确认你是源应用的协作者；不是的话请让应用所有者添加协作者后重试`,
+                    '这是权限问题，不是凭证配置或服务端抖动：不要重复执行本命令，也不要尝试自行签发 token',
+                ],
+            });
+        // meta_token 无效或未绑定妙搭应用（服务端 ResolveAppIDByMetaToken 反查失败）
+        case devops_error_1.BizErrCode.STUDIO_APP_NOT_FOUND:
+            return new error_1.AppError('EXPORT_APP_NOT_FOUND', `${sourceDesc} 未找到对应应用：${message}`, {
+                next_actions: [
+                    '核对分享 token / 链接是否完整（创意应用 URL 形如 https://<tenant>.feishu.cn/page/<token>）',
+                    '确认目标是创意应用（只有创意应用有分享 token）；这是目标不存在问题：不要重复执行本命令，请向用户确认',
+                ],
+            });
+        // 应用不存在（错误 ID）
+        case devops_error_1.BizErrCode.DEVOPS_APP_NOT_FOUND:
+        case devops_error_1.BizErrCode.DEVOPS_APP_NOT_FOUND_ALT:
+            return new error_1.AppError('EXPORT_APP_NOT_FOUND', `${sourceDesc} 不存在或不可访问：${message}`, {
+                next_actions: [
+                    '核对源应用 ID（应用页 URL 形如 /app/app_xxx，该段才是应用 ID）',
+                    '这是目标不存在问题：不要重复执行本命令，请向用户确认正确的应用 ID',
+                ],
+            });
+        default:
+            return (0, devops_error_1.mapDevopsError)(bizCode, message);
+    }
+}
 /**
- * GET /api/v1/studio/innerapi/apps/:appID/code-archive?sourceAppID=xxx — 导出源应用源码归档。
+ * GET /api/v1/studio/innerapi/apps/:appID/code-archive — 导出源应用源码归档。
  * 走 studio_server inner 通道（force 身份，服务侧 force→lark 换取后按 DOWNLOAD 鉴权，
- * 鉴权对象是 sourceAppID），与 comment 域同一 inner 信封；创意应用升级链路（app export）消费。
+ * 鉴权对象是源应用），与 comment 域同一 inner 信封；创意应用升级链路（app export）消费。
  *
  * path :appID 必须是当前沙箱应用：网关 apaas_force_admin_plugin 强校验 URL appID 与沙箱
  * AK 绑定应用一致（不一致 400 "appID in url is illegal"），跨应用导出目标因此走 query。
+ * 源应用定位二选一：sourceAppID（app_xxx），或 sourceMetaToken（创意应用分享 URL
+ * /page/<token> 的 CCM token，服务端反查 appID 后按同一口径鉴权）。
  */
 async function getCodeArchive(params) {
-    const { appID, sourceAppID, checkpointID } = params;
-    let url = `/api/v1/studio/innerapi/apps/${encodeURIComponent(appID)}/code-archive` +
-        `?sourceAppID=${encodeURIComponent(sourceAppID)}`;
+    const { appID, sourceAppID, sourceMetaToken, checkpointID } = params;
+    if (!sourceAppID === !sourceMetaToken) {
+        throw new error_1.AppError('ARGS_INVALID', 'sourceAppID 与 sourceMetaToken 必须恰传其一');
+    }
+    const sourceQuery = sourceAppID
+        ? `sourceAppID=${encodeURIComponent(sourceAppID)}`
+        : `sourceMetaToken=${encodeURIComponent(sourceMetaToken ?? '')}`;
+    let url = `/api/v1/studio/innerapi/apps/${encodeURIComponent(appID)}/code-archive?` + sourceQuery;
     if (checkpointID !== undefined && checkpointID > 0) {
         url += `&checkPointID=${String(checkpointID)}`;
     }
     return (0, http_1.getInnerApi)(url, {
         errPrefix: 'Failed to export code archive',
+        defaultErrCode: DEFAULT_ERR_CODE,
+        mapErr: (bizCode, message) => mapExportError(bizCode, message, { sourceAppID, sourceMetaToken }),
     });
 }

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

@@ -122,32 +122,37 @@ JSON 输出
 }
 function registerAppExport(parent) {
     const cmd = parent
-        .command('export <app-id>')
-        .description('导出指定应用的源码到本工程（创意应用升级：拉取创意稿作只读参考物）')
+        .command('export <app-id-or-token>')
+        .description('导出指定应用的源码到本工程（创意应用升级：拉取创意稿作只读参考物）；接受应用 ID（app_xxx）或创意应用分享 token')
         .option('--out <dir>', '输出目录（相对当前目录）', 'source_package/creative')
         .option('--checkpoint <n>', '按检查点版本导出；缺省为最新提交（HEAD）')
         .addHelpText('after', `
 说明
-  从服务端导出 <app-id> 对应应用（源应用，可以不是当前应用）的源码归档并解压到 --out
-  目录，导出完成后写 --out/.upgrade-manifest.json（含 sourceAppId / 导出时间 / 文件数），
-  供升级链路幂等判定与 skill 发现使用。调用者须为源应用协作者（服务端 DOWNLOAD 鉴权）。
-  请求以当前应用（MIAODA_APP_ID）为路径主体、源应用走 sourceAppID 参数。
+  从服务端导出源应用（可以不是当前应用）的源码归档并解压到 --out 目录，导出完成后写
+  --out/.upgrade-manifest.json（含 sourceAppId / 导出时间 / 文件数），供升级链路幂等
+  判定与 skill 发现使用。调用者须为源应用协作者（服务端 DOWNLOAD 鉴权）。
+  <app-id-or-token> 两种形态等价：应用 ID（app_xxx）或创意应用分享 token。拿到的是
+  分享链接（https://<tenant>.feishu.cn/page/<token>）时，提取其中 /page/ 后的 <token> 段传入。
+  请求以当前应用（MIAODA_APP_ID）为路径主体、源应用走 sourceAppID / sourceMetaToken 参数。
 
 幂等
-  --out 已存在 manifest 且 sourceAppId 一致时跳过导出（skipped=true），重复调用安全。
+  --out 已存在 manifest 且源定位（sourceAppId / sourceMetaToken）一致时跳过导出
+  （skipped=true），重复调用安全。
 
 JSON 输出
   {"data": {"appId": "...", "out": "source_package/creative", "fileCount": <n>,
             "archiveName": "...", "skipped": false}}
   跳过时：{"data": {"appId": "...", "out": "...", "skipped": true, "reason": "already_exported"}}
+  appId 始终是实际导出的源应用 ID（传 token 时为服务端反查结果）。
 
 失败
   源应用无可导出内容（从未提交过代码）→ EXPORT_EMPTY_ARCHIVE，请先在源应用完成一轮创作。
-  无权限（非源应用协作者）→ 服务端鉴权错误透传。
+  非源应用协作者 → EXPORT_PERMISSION_DENIED，权限问题，重试无效，需应用所有者加协作者。
+  应用 ID 不存在，或 token 未找到对应应用 → EXPORT_APP_NOT_FOUND，核对入参，重试无效。
 
 示例
   $ miaoda app export app_demo_source
-  $ miaoda app export app_demo_source --out source_package/creative
+  $ miaoda app export DemoPageTokenAbCdEf123456789
   $ miaoda app export app_demo_source --checkpoint 3
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (appId, rawOpts) => {
@@ -217,7 +222,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 +242,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/commands/index.js

@@ -31,6 +31,9 @@ function resolveScene(appType, _archType) {
         return 'design-html';
     return 'default';
 }
+// registry(shadcn 式 copy-in SDK)挂在全部 scene:scene 路由不感知 registry 的可用性,
+// stack 是否有对应 registry 包由运行时映射表(services/registry STACK_RUNTIME)校验,
+// 无映射的 stack 执行时报 REGISTRY_STACK_UNSUPPORTED 并提示支持列表。
 const SCENE_REGISTRARS = {
     default: (p) => {
         // init / upgrade / skills 都挂出来：本地用户不需要 export MIAODA_APP_TYPE=3
@@ -42,13 +45,13 @@ const SCENE_REGISTRARS = {
         (0, index_1.registerFileCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
         (0, index_6.registerSkillsCommands)(p);
-        (0, index_7.registerCommentCommands)(p);
+        (0, index_8.registerRegistryCommands)(p);
     },
     modern: (p) => {
         (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, modern_1.registerDeployCommandsModern)(p);
         (0, index_6.registerSkillsCommands)(p);
-        (0, index_7.registerCommentCommands)(p);
+        (0, index_8.registerRegistryCommands)(p);
     },
     // application scene(AppType_APPLICATION=3):
     // 在 default 命令集基础上加 skills(按 meta.json.stack 拉对应 stack 技能)
@@ -60,7 +63,7 @@ const SCENE_REGISTRARS = {
         (0, index_1.registerFileCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
         (0, index_6.registerSkillsCommands)(p);
-        (0, index_7.registerCommentCommands)(p);
+        (0, index_8.registerRegistryCommands)(p);
     },
     // design scene(AppType_DESIGN=4):design-stack 仅 SSR 渲染、无后端业务逻辑、
     // 无数据库、无 UGC 文件。命令集裁掉 db / file,保留 deploy / observability / app(init) / skills。
@@ -69,11 +72,11 @@ const SCENE_REGISTRARS = {
         (0, index_5.registerDeployCommands)(p);
         (0, index_3.registerObservabilityCommands)(p);
         (0, index_6.registerSkillsCommands)(p);
-        (0, index_7.registerCommentCommands)(p);
+        (0, index_8.registerRegistryCommands)(p);
     },
     // design-html scene(AppType_DESIGN_HTML=8):buildless 静态 HTML,
     // 命令集与 modern 一致(app init/sync + modern 拆分版 deploy + skills),不挂 db/file/observability。
-    // 额外挂 registry(shadcn 式 copy-in SDK,design-html scene 专属)。
+    // comment(应用评论)仅 design-html 开放。
     'design-html': (p) => {
         (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, modern_1.registerDeployCommandsModern)(p);

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

@@ -4,7 +4,8 @@ exports.registerRegistryCommands = registerRegistryCommands;
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/registry/index");
 /**
- * miaoda registry：design-html 技术栈的「组件 registry」（shadcn 式 copy-in）。
+ * miaoda registry：「组件 registry」（shadcn 式 copy-in），供有对应 registry 包的 stack 使用
+ * （当前 design-html / html，见 services/registry 的 STACK_RUNTIME）。
  *
  * registry 是独立 npm 包，按 runtime 命名分发（buildless runtime → @lark-apaas/coding-registry-buildless）。
  * SDK 文件放在包根的 components/ · scripts/ · stylesheets/ 三个目录下（这三个顶层目录里的代码文件
@@ -15,7 +16,7 @@ const index_1 = require("../../../cli/handlers/registry/index");
 function registerRegistryCommands(program) {
     const registryCmd = program
         .command('registry')
-        .description('组件 registry：列出 / copy-in design-html SDK 文件')
+        .description('组件 registry：列出 / copy-in SDK 文件')
         .usage('<command> [flags]');
     registryCmd.action(() => {
         registryCmd.outputHelp();
@@ -32,7 +33,8 @@ function registerRegistryCommands(program) {
   - add 落地：拍平到项目根（包根 scripts/x.js → 项目 x.js）；同名 basename 撞车时后者覆盖前者
 
 前置
-  当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack=design-html）
+  当前目录（或 --dir）已走过 'miaoda app init'，且 .spark/meta.json 的 stack 有对应
+  registry 包（当前支持 design-html / html）；其余 stack 执行时报 REGISTRY_STACK_UNSUPPORTED
 `);
     registerRegistryList(registryCmd);
     registerRegistryAdd(registryCmd);

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

@@ -21,11 +21,16 @@ function registerSkillsCommands(program) {
 function registerSkillsSync(parent) {
     const cmd = parent
         .command('sync')
-        .description('同步 coding-steering（latest 或指定版本）到 user app')
+        .description('同步 skills 到 user app（默认 coding-steering；带 --type 时走 sandbox-skills）')
         .option('--dir <path>', '项目目录，默认当前目录', '.')
         .option('--version <ver>', 'coding-steering 包版本或 dist-tag，缺省 latest')
         .option('--local', '走本地 dev / agent 输出形态：拷到 .agents/skills 平铺 + 创建 .claude/skills 软链。' +
         '不传时退回老形态：拷到 .agent/skills/steering/<stack>/skills/（跟沙箱端 update-skills.sh 对齐）', false)
+        .option('--type <type>', '走 sandbox 分支：miaoda | miaoda-modern | miaoda-design | openclaw。有值时忽略 --local，' +
+        '从 @lark-apaas/coding-<pkg>-sandbox-skills 拉包平铺写入，并额外同步 steering ' +
+        '到 .agent/skills/steering/<stack>/（--version 对后者仍生效）')
+        .option('--tgz-key <key>', '配合 --type 使用；老 TCC skillsUpdateTgzKey 值透传，' +
+        '从 skills_versions/all_<X>.tgz 反推出 lane 名 X，再过滤出 -alpha.<X> 版本；缺省走 @latest')
         .addHelpText('after', `
 前置要求
   当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack）
@@ -41,21 +46,36 @@ function registerSkillsSync(parent) {
     .agents/tech.md
     .claude/skills → ../.agents/skills（软链，让 Claude Code 识别同一份）
 
+  传 --type（沙箱链路，两部分都同步）：
+    .agent/skills/<skill>/...                        ← 业务线 skill，平铺
+    .agent/skills/steering/<stack>/skills/<skill>/   ← steering，同上面默认形态
+    （openclaw 的业务线部分落 skills/ 而非 .agent/skills/）
+
 JSON 输出
   {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false,
             "claudeSkillsLink": "created|updated|noop|conflict"  // 仅 --local 时}}
 
+  传 --type 时：
+  {"data": {"mode": "sandbox", "type": "...", "packageName": "...", "version": "...",
+            "lane": "...", "syncedTop": [...], "targetDir": "...",
+            "steering": {"status": "synced|skipped|failed", ...}}}
+  steering 失败或无 stack 不影响整体成功——业务线 skill 已同步，不该因增量部分阻断
+
 示例
   $ miaoda skills sync                              # 拉 @latest
   $ miaoda skills sync --local                      # 本地 dev / agent 用
   $ miaoda skills sync --version 0.2.0              # 显式指定版本
   $ miaoda skills sync --dir ./my-app
+  # 沙箱链路（由 feida-ai 下发）：业务线 skill + steering 一次同步到位
+  $ miaoda skills sync --type miaoda-modern --tgz-key 'skills_versions/all_demo-lane.tgz'
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         await (0, index_1.handleSkillsSync)({
             dir: rawOpts.dir,
             version: rawOpts.version,
             local: rawOpts.local,
+            type: rawOpts.type,
+            tgzKey: rawOpts.tgzKey,
         });
     }));
 }

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

@@ -46,6 +46,29 @@ const api = __importStar(require("../../../api/index"));
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const logger_1 = require("../../../utils/logger");
+/** 妙搭应用 ID 形态：`app_` + 字母数字下划线。非此形态按创意应用分享 token 处理。 */
+const MIAODA_APP_ID_PATTERN = /^app_\w{1,64}$/;
+/** 分享 token 宽松形态：16-128 位字母数字（CCM token 实际 20+ 位）。只拦明显不是 token 的输入（误传 flag / 短串），不追平服务端精确口径。 */
+const META_TOKEN_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+/**
+ * 解析位置参数为源应用定位：app_xxx → appId；满足 token 宽松形态的串 → metaToken 透传
+ * （精确校验交给服务端反查，避免和服务端口径漂移）。不支持直接传分享链接——调用方
+ * （上游 agent）自行从链接提取 /page/<token> 段后传 token。
+ */
+function parseSourceRef(raw) {
+    if (MIAODA_APP_ID_PATTERN.test(raw)) {
+        return { appId: raw };
+    }
+    if (!META_TOKEN_PATTERN.test(raw)) {
+        throw new error_1.AppError('ARGS_INVALID', `无法识别的源应用定位：${raw}`, {
+            next_actions: [
+                '接受两种形态：应用 ID（app_xxx）或创意应用分享 token（16 位以上字母数字）',
+                '拿到的是分享链接（https://<tenant>.feishu.cn/page/<token>）时，请提取其中 /page/ 后的 <token> 段传入',
+            ],
+        });
+    }
+    return { metaToken: raw };
+}
 /** 导出目录默认值：创意升级链路的参考物约定位置。 */
 exports.DEFAULT_EXPORT_OUT = 'source_package/creative';
 /** 升级 manifest 文件名：前置钩子幂等标记 / skill workspace-contains 锚点 / skill 第 0 步信息源。 */
@@ -97,7 +120,7 @@ function countFiles(dir) {
     return count;
 }
 /**
- * miaoda app export <app-id> [--out <dir>] [--checkpoint <n>]
+ * miaoda app export <app-id-or-token> [--out <dir>] [--checkpoint <n>]
  *
  * 创意应用升级链路：把源应用（创意稿）的源码从服务端导出到本工程，作为只读参考物。
  * 链路：studio_server InnerGetCodeArchive（inner 通道，force 身份鉴权：调用者须为源应用
@@ -105,15 +128,18 @@ function countFiles(dir) {
  * skill workspace-contains 锚点 + skill 第 0 步信息源）。
  *
  * URL 形状：path :appID 是当前沙箱应用（网关强校验其与沙箱 AK 一致），源应用走 query
- * sourceAppID —— 跨应用（升级常态：新应用沙箱里导出源创意应用）必须如此。
+ * （sourceAppID 或 sourceMetaToken 二选一）—— 跨应用（升级常态：新应用沙箱里导出源
+ * 创意应用）必须如此。位置参数接受应用 ID / 分享 token 两种形态。
  *
- * 幂等：--out 已存在 manifest 且 sourceAppId 一致时跳过导出直接返回（重试/多轮不重复拉取）。
+ * 幂等：--out 已存在 manifest 且源定位（sourceAppId / sourceMetaToken）一致时跳过导出
+ * 直接返回（重试/多轮不重复拉取）。
  */
 async function handleAppExport(opts) {
-    const appId = (opts.appId || '').trim();
-    if (!appId) {
-        throw new error_1.AppError('ARGS_INVALID', 'app-id 不能为空');
+    const rawSource = (opts.appId || '').trim();
+    if (!rawSource) {
+        throw new error_1.AppError('ARGS_INVALID', 'app-id-or-token 不能为空');
     }
+    const source = parseSourceRef(rawSource);
     // 当前沙箱应用：网关 AK 校验要求 path :appID 与沙箱绑定应用一致
     const currentAppId = (opts.currentAppId || '').trim();
     if (!currentAppId) {
@@ -124,13 +150,24 @@ async function handleAppExport(opts) {
     const outRel = normalizeOutDir(opts.out ?? exports.DEFAULT_EXPORT_OUT);
     const outDir = node_path_1.default.resolve(process.cwd(), outRel);
     const manifestPath = node_path_1.default.join(outDir, exports.UPGRADE_MANIFEST_FILENAME);
-    // 幂等：同源应用已导出过则直接复用（前置钩子重试 / 多轮对话不重复拉取）
+    // 幂等：同源应用已导出过则直接复用（前置钩子重试 / 多轮对话不重复拉取）。
+    // token 入参时按 manifest 记录的 sourceMetaToken 比对（导出前拿不到反查后的 appId）。
     if (node_fs_1.default.existsSync(manifestPath)) {
         try {
             const prev = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf-8'));
-            if (prev.sourceAppId === appId) {
+            const matched = source.appId
+                ? prev.sourceAppId === source.appId
+                : prev.sourceMetaToken === source.metaToken;
+            if (matched) {
                 (0, logger_1.log)('export', `Already exported (manifest matched), skip: ${outRel}`);
-                (0, output_1.emit)({ data: { appId, out: outRel, skipped: true, reason: 'already_exported' } });
+                (0, output_1.emit)({
+                    data: {
+                        appId: prev.sourceAppId ?? '',
+                        out: outRel,
+                        skipped: true,
+                        reason: 'already_exported',
+                    },
+                });
                 return;
             }
         }
@@ -138,10 +175,11 @@ async function handleAppExport(opts) {
             // manifest 损坏视为未导出，走覆盖导出
         }
     }
-    (0, logger_1.log)('export', `Fetching code archive of ${appId}...`);
+    (0, logger_1.log)('export', `Fetching code archive of ${source.appId ?? 'meta token source'}...`);
     const resp = await api.app.getCodeArchive({
         appID: currentAppId,
-        sourceAppID: appId,
+        sourceAppID: source.appId,
+        sourceMetaToken: source.metaToken,
         checkpointID: opts.checkpoint,
     });
     const fileBase64 = resp.file ?? '';
@@ -157,9 +195,11 @@ async function handleAppExport(opts) {
     if (archive.length > MAX_ARCHIVE_BYTES) {
         throw new error_1.AppError('EXPORT_ARCHIVE_TOO_LARGE', `归档超过大小上限（${String(archive.length)} > ${String(MAX_ARCHIVE_BYTES)} bytes）`);
     }
+    // 实际导出的源应用 ID：服务端回传优先（token 入参时为反查结果），appId 入参时兜底自身
+    const resolvedSourceAppId = resp.sourceAppID ?? source.appId ?? '';
     // 归档先落临时文件再解压；解压成功前不动已存在的 outDir 内容之外的文件
     const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-export-'));
-    const archivePath = node_path_1.default.join(tmpDir, resp.name ?? `${appId}.zip`);
+    const archivePath = node_path_1.default.join(tmpDir, resp.name ?? `${resolvedSourceAppId || 'source'}.zip`);
     try {
         node_fs_1.default.writeFileSync(archivePath, archive);
         node_fs_1.default.mkdirSync(outDir, { recursive: true });
@@ -177,7 +217,9 @@ async function handleAppExport(opts) {
     node_fs_1.default.rmSync(node_path_1.default.join(outDir, '.gitignore'), { force: true });
     const fileCount = countFiles(outDir);
     const manifest = {
-        sourceAppId: appId,
+        sourceAppId: resolvedSourceAppId,
+        // token 入参时记录 token 供幂等比对；appId 入参时不写该字段
+        ...(source.metaToken ? { sourceMetaToken: source.metaToken } : {}),
         archiveName: resp.name ?? '',
         checkpointId: opts.checkpoint ?? 0,
         exportedAt: new Date().toISOString(),
@@ -186,6 +228,12 @@ async function handleAppExport(opts) {
     node_fs_1.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
     (0, logger_1.log)('export', 'Exported successfully');
     (0, output_1.emit)({
-        data: { appId, out: outRel, fileCount, archiveName: manifest.archiveName, skipped: false },
+        data: {
+            appId: resolvedSourceAppId,
+            out: outRel,
+            fileCount,
+            archiveName: manifest.archiveName,
+            skipped: false,
+        },
     });
 }

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/cli/handlers/skills/sync.js

@@ -6,9 +6,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleSkillsSync = handleSkillsSync;
 const node_path_1 = __importDefault(require("node:path"));
 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 error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
+/**
+ * sandbox 分支下补同步 steering（`.agent/skills/steering/<stack>/`）。
+ *
+ * **绝不抛错**，因为它在 sandbox 链路里是「附加项」而非门禁：
+ *   - 无 `.spark/meta.json` / 无 stack → skipped。对齐老 cp-skills.sh 的
+ *     `[ -n "$STACK" ] && [ "$STACK" != "null" ]` 判断（无 stack 就跳过 steering）。
+ *   - 拉包 / 写盘失败 → failed，但仍让整条 sync 算成功。
+ *
+ * 为什么不能抛：feida-ai 侧 TCC 可配 `allowFailure: false`，一抛就阻断 agent 启动。
+ * 平铺业务线 skill 已经同步好了，不该因为 steering 这个增量部分让用户开不了会话。
+ */
+function syncSteeringForSandbox(params) {
+    let stack;
+    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;
+    }
+    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);
+    try {
+        const r = (0, coding_steering_1.syncCodingSteering)({
+            stack,
+            targetDir: params.targetDir,
+            version: effectiveVersion,
+            // 必须显式传 mode，不能落到 inferMode()：它靠 env MIAODA_DEP_CACHE_DIR 嗅探，
+            // 而 mode 决定读包内哪个 layer（sandbox→`skills/`，local→`skills_local/`）。
+            // `--type` 分支本身就是沙箱语义，嗅探失手会去读不存在的 skills_local/、
+            // 静默同步 0 个 skill。
+            mode: 'sandbox',
+            // 同理固定 nested：落 .agent/skills/steering/<stack>/，与老链路一致
+            outputLayout: 'nested',
+        });
+        return {
+            status: 'synced',
+            stack,
+            version: r.version,
+            syncedSkills: r.syncedSkills,
+            techSynced: r.techSynced,
+        };
+    }
+    catch (err) {
+        return { status: 'failed', reason: err.message };
+    }
+}
 /**
  * miaoda skills sync [--dir <path>] [--version <ver>]
  *
@@ -26,6 +79,57 @@ const output_1 = require("../../../utils/output");
 async function handleSkillsSync(opts) {
     await Promise.resolve();
     const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    // --type 走 sandbox-skills 分支（迁仓后沙箱内由 feida-ai 直接下发调用）。
+    //
+    // 这条分支必须**同时**同步两部分，缺一不可 —— 线上老链路 update-skills.sh 也是两步
+    // （自己 rsync 平铺，再于第 230 行调不带 --type 的 `miaoda skills sync` 写 steering）：
+    //   ① syncSandboxSkills：平铺业务线 skill，rsync 式对齐（保 .keep/.config/steering）
+    //   ② steering：`.agent/skills/steering/<stack>/`，按 .spark/meta.json 的 stack 过滤
+    //   ③ lockDirReadonly：锁只读收尾（update-skills.sh:241），仅沙箱侧路径
+    //
+    // 历史 bug：早期这里 ① 完就 return，steering 既不同步、又被当时的整目录清空删掉，
+    // 沙箱少掉整批技术栈 skill（BOE 实测 scanAllSkills 从 59 掉到 34）。
+    //
+    // `.keep` 语义（update-skills.sh:149）：目标目录挂了 .keep 表示「我手改过，别覆盖」，
+    // ① 会跳过并回报 skippedByKeepFile，此时 ② 也必须跳过 —— 否则 steering 仍被覆写，
+    // 冻结只冻结了一半。
+    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,
+            },
+        });
+        return;
+    }
+    // 原有 coding-steering 同步逻辑（本地 dev / miaoda app init 用）
     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');