@lark-apaas/miaoda-cli 0.1.29 → 0.1.31-alpha.ceaafa0

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`。
+前置：当前工作目录已走过 `miaoda app init`，且 `.spark/meta.json` 的 `stack` 有对应 registry 包（当前支持 `design-html` / `html`）；其余 stack 执行时报 `REGISTRY_STACK_UNSUPPORTED` 并提示支持列表。meta 一律从 cwd 读取，不随 `--dir` 走。
 
 ```bash
 # 列出可用 SDK 条目（输出各文件 USAGE 注释块原文，便于 Agent 直接读用法）
@@ -76,7 +76,7 @@ miaoda registry add deck-slide --overwrite         # 目标已存在时覆盖（
 - **拍平落地**：所有文件**拍平**到项目根（`scripts/deck-slide.js` → 项目 `deck-slide.js`，不保留子目录）；闭包内同名 basename 撞车时后者覆盖前者。
 - **skip-by-disk**：项目已有同名（拍平后的 basename）文件默认跳过，`--overwrite` 才覆盖；不写任何安装记账文件，项目文件树即状态。
 - **add 回执带 usage**：`add` 结果的 `entries` 只列**你请求的条目**（不含被 `Depends` 传递拉进来的依赖——依赖照常落地在 `added`/`skipped`，但那是"管道"），逐条给出 `usage`（USAGE 块原文）与 `dependsOn`，Agent `add` 完即可直接读用法，无需再 `registry list`。请求的条目即使已存在被跳过也回带 usage（`status` 标 `added`/`skipped`，据此判断磁盘上是 registry 版还是你改过的旧版）。`--json` 结构为 `{registryVersion, added, skipped, dryRun, entries}`；pretty（默认）输出 `registry@<ver>` + `added:`/`skipped:` 逗号列表 + 各请求条目的 USAGE 块，稳定 label、无 JSON 数组、无截断，对 Agent 与人同样可读。
-- `--version <ver>` 指定 registry 包版本或 dist-tag（缺省 `latest`），`--dir <path>` 指定项目目录（缺省当前目录）。
+- `--version <ver>` 指定 registry 包版本或 dist-tag（缺省 `latest`）；`add` 的 `--dir <path>` 指定 copy-in 落地目录（缺省当前目录），不影响 `.spark/meta.json` 读取。
 
 ## 全局参数
 

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,9 @@ function registerRegistryCommands(program) {
   - add 落地：拍平到项目根（包根 scripts/x.js → 项目 x.js）；同名 basename 撞车时后者覆盖前者
 
 前置
-  当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack=design-html）
+  当前工作目录已走过 'miaoda app init'，且 .spark/meta.json 的 stack 有对应
+  registry 包（当前支持 design-html / html）；其余 stack 执行时报 REGISTRY_STACK_UNSUPPORTED
+  meta 一律从 cwd 读取，add 的 --dir 只影响 copy-in 落地目录
 `);
     registerRegistryList(registryCmd);
     registerRegistryAdd(registryCmd);
@@ -41,7 +44,6 @@ function registerRegistryList(parent) {
     const cmd = parent
         .command('list')
         .description('列出 registry 可用 SDK 条目，输出各文件的 USAGE 块原文')
-        .option('--dir <path>', '项目目录，默认当前目录', '.')
         .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
         .addHelpText('after', `
 输出
@@ -57,7 +59,6 @@ JSON 输出
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         await (0, index_1.handleRegistryList)({
-            dir: rawOpts.dir,
             version: rawOpts.version,
         });
     }));
@@ -67,7 +68,7 @@ function registerRegistryAdd(parent) {
         .command('add')
         .description('把一个或多个 SDK 文件 copy-in 到当前项目（拍平到项目根，含 Depends 闭包）')
         .argument('<token...>', 'name / 完整文件名 / relPath，可传多个；同名多匹配全拉，Depends 自动传递解析')
-        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .option('--dir <path>', 'copy-in 落地目录，默认当前目录（stack 一律读 cwd 的 .spark/meta.json）', '.')
         .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
         .option('--overwrite', '目标文件已存在时覆盖（默认跳过以保护用户改动）', false)
         .option('--dry-run', '只报告将写 / 将跳哪些文件，不落盘', false)
@@ -75,8 +76,9 @@ function registerRegistryAdd(parent) {
 行为
   - token 寻址：name（foo）/ 完整文件名（foo.css）/ relPath（stylesheets/foo.css）任一形式
   - 多匹配全拉：token 命中多个同名条目时全部 copy-in；想只要其一就写完整文件名 / relPath
-  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件**拍平**拷到项目根
-    （包根 scripts/deck-stage.js → 项目 deck-stage.js；同名 basename 撞车时后者覆盖前者）
+  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件**拍平**拷到落地目录（--dir，默认当前目录）
+    （包根 scripts/deck-stage.js → 落地 deck-stage.js；同名 basename 撞车时后者覆盖前者）
+  - stack 一律读当前工作目录的 .spark/meta.json，--dir 不影响 meta 读取
   - skip-by-disk：目标文件已存在默认跳过；--overwrite 才覆盖
   - 不写任何安装记账文件（项目文件树即状态）
 

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/registry/add.js

@@ -13,7 +13,8 @@ const output_1 = require("../../../utils/output");
  * miaoda registry add <name...> [--overwrite] [--dry-run] [--dir <path>] [--version <ver>]
  *
  * 解析 USAGE 块 Depends 传递闭包，把每个条目对应的 SDK 文件从 registry 包根的 <relPath>
- * **保留相对路径**拷到项目根（--dir 指定目录的根）。
+ * **保留相对路径**拷到落地目录（--dir，默认 cwd）。stack 一律从 <cwd>/.spark/meta.json 读，
+ * 不随 --dir 走。
  * skip-by-disk：目标已存在默认跳过，--overwrite 才覆盖。不写任何安装记账文件。
  */
 async function handleRegistryAdd(opts) {
@@ -22,7 +23,7 @@ async function handleRegistryAdd(opts) {
         throw new error_1.AppError('ARGS_INVALID', 'registry add 至少需要一个条目名');
     }
     const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    const stack = (0, shared_1.resolveRegistryStack)(targetDir);
+    const stack = (0, shared_1.resolveRegistryStack)();
     const reg = (0, index_1.loadRegistry)({ stack, version: opts.version });
     try {
         const plan = (0, index_1.planAdd)({

package/dist/cli/handlers/registry/list.js

@@ -1,17 +1,13 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleRegistryList = handleRegistryList;
-const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../../../services/registry/index");
 const shared_1 = require("./shared");
 const output_1 = require("../../../utils/output");
 /**
- * miaoda registry list [--dir <path>] [--version <ver>]
+ * miaoda registry list [--version <ver>]
  *
- * 从 .spark/meta.json 读 stack → runtime → 包名，拉对应 registry 包，从包根递归扫含 USAGE 块的 SDK 文件。
+ * 从 <cwd>/.spark/meta.json 读 stack → runtime → 包名，拉对应 registry 包，从包根递归扫含 USAGE 块的 SDK 文件。
  *
  * - 默认（pretty）：输出各条目 USAGE 块原文，带文件名分隔，给 Agent 直接读注释。
  * - --json：输出 [{name, file, usage(原文字符串), dependsOn[]}]，usage 保持原文不解析成字段。
@@ -19,8 +15,7 @@ const output_1 = require("../../../utils/output");
  */
 async function handleRegistryList(opts) {
     await Promise.resolve();
-    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    const stack = (0, shared_1.resolveRegistryStack)(targetDir);
+    const stack = (0, shared_1.resolveRegistryStack)();
     const reg = (0, index_1.loadRegistry)({ stack, version: opts.version });
     try {
         if ((0, output_1.isJsonMode)()) {

package/dist/cli/handlers/registry/shared.js

@@ -5,16 +5,20 @@ const spark_meta_1 = require("../../../utils/spark-meta");
 const index_1 = require("../../../services/registry/index");
 const error_1 = require("../../../utils/error");
 /**
- * 从 <targetDir>/.spark/meta.json 读 stack，校验该 stack 有组件 registry。
+ * 从 <cwd>/.spark/meta.json 读 stack，校验该 stack 有组件 registry。
+ * meta 只与当前工作目录相关（CLI 必须在 user app 根目录下运行），不随 --dir 走——
+ * --dir 只影响 add 的 copy-in 落地目录。
  * 缺 stack → 提示先 init；stack 无 registry（无对应 runtime / runtime 无 registry 包）→ 提示支持哪些 stack。
  *
  * 这里只做「stack 是否在支持列表」的早校验给用户友好提示；包名的两跳解析
  * （stack → runtime → 包）由 loadRegistry/resolveRegistryPackage 负责。
  */
-function resolveRegistryStack(targetDir) {
-    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+function resolveRegistryStack() {
+    const meta = (0, spark_meta_1.readSparkMeta)(process.cwd());
     if (meta.stack === undefined || meta.stack === '') {
-        throw new error_1.AppError('REGISTRY_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+        throw new error_1.AppError('REGISTRY_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first', {
+            next_actions: ['meta 一律读当前工作目录（不随 --dir），请 cd 到 user app 根目录后重试'],
+        });
     }
     if (!index_1.REGISTRY_SUPPORTED_STACKS.includes(meta.stack)) {
         throw new error_1.AppError('REGISTRY_STACK_UNSUPPORTED', `stack "${meta.stack}" 没有组件 registry`, {