@lark-apaas/miaoda-cli 0.1.4 → 0.1.5-beta.27ede41

package/README.md

@@ -36,10 +36,11 @@ miaoda file ls --output json
 
 命令以"域"作为第一级命名空间：
 
-| 域 | 用途 |
-|---|---|
-| `miaoda file ...` | 文件操作：上传、下载、元数据、签名下载、批量删除 |
-| `miaoda db ...` | 数据操作：SQL 执行、表结构查询、数据导入导出 |
+| 域                         | 用途                                                 |
+| -------------------------- | ---------------------------------------------------- |
+| `miaoda file ...`          | 文件操作：上传、下载、元数据、签名下载、批量删除     |
+| `miaoda db ...`            | 数据操作：SQL 执行、表结构查询、数据导入导出         |
+| `miaoda observability ...` | 线上日志、链路、前端源码堆栈反查、监控指标、运营指标 |
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
@@ -54,7 +55,7 @@ miaoda file ls --output json
 ## 环境变量
 
 - `MIAODA_APP_ID`：默认应用 ID，等价于 `--app-id`。
-- `MIAODA_CANARY_HEADER`：设置后所有 HTTP 请求自动带上 `x-tt-env: <值>` 小流量头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。
+- `MIAODA_CANARY_HEADER`：HTTP 请求的 `x-tt-env` 小流量头取值。未设置时默认 `boe_miaoda_doubao`；设为空字符串则不带该头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。值形如 `ppe_xxx` 时额外带上 `x-use-ppe: 1`。
 
 ## 输出契约
 

package/dist/api/deploy/index.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodeStatus = exports.nodeStatusFromText = exports.nodeStatusText = exports.errorJobSchema = exports.deployGetSchema = exports.deployHistorySchema = exports.queryPipelineInstance = exports.getErrorLog = exports.listPipelineInstances = exports.createRelease = void 0;
+exports.NodeStatus = exports.nodeStatusFromText = exports.nodeStatusText = exports.errorJobSchema = exports.deployGetSchema = exports.deployHistorySchema = exports.batchSavePluginInstances = exports.LocalReleaseStatus = exports.getModernLastPublishedVersion = exports.getModernReleaseStatus = exports.createModernRelease = exports.callbackStatic = exports.updateLocalRelease = exports.createLocalRelease = exports.preRelease = exports.queryPipelineInstance = exports.getErrorLog = exports.listPipelineInstances = exports.createRelease = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "createRelease", { enumerable: true, get: function () { return api_1.createRelease; } });
 Object.defineProperty(exports, "listPipelineInstances", { enumerable: true, get: function () { return api_1.listPipelineInstances; } });
 Object.defineProperty(exports, "getErrorLog", { enumerable: true, get: function () { return api_1.getErrorLog; } });
 Object.defineProperty(exports, "queryPipelineInstance", { enumerable: true, get: function () { return api_1.queryPipelineInstance; } });
+var modern_1 = require("./modern");
+Object.defineProperty(exports, "preRelease", { enumerable: true, get: function () { return modern_1.preRelease; } });
+Object.defineProperty(exports, "createLocalRelease", { enumerable: true, get: function () { return modern_1.createLocalRelease; } });
+Object.defineProperty(exports, "updateLocalRelease", { enumerable: true, get: function () { return modern_1.updateLocalRelease; } });
+Object.defineProperty(exports, "callbackStatic", { enumerable: true, get: function () { return modern_1.callbackStatic; } });
+Object.defineProperty(exports, "createModernRelease", { enumerable: true, get: function () { return modern_1.createRelease; } });
+Object.defineProperty(exports, "getModernReleaseStatus", { enumerable: true, get: function () { return modern_1.getReleaseStatus; } });
+Object.defineProperty(exports, "getModernLastPublishedVersion", { enumerable: true, get: function () { return modern_1.getLastPublishedVersion; } });
+var modern_types_1 = require("./modern-types");
+Object.defineProperty(exports, "LocalReleaseStatus", { enumerable: true, get: function () { return modern_types_1.LocalReleaseStatus; } });
+var plugin_instances_1 = require("./plugin-instances");
+Object.defineProperty(exports, "batchSavePluginInstances", { enumerable: true, get: function () { return plugin_instances_1.batchSavePluginInstances; } });
 var schemas_1 = require("./schemas");
 Object.defineProperty(exports, "deployHistorySchema", { enumerable: true, get: function () { return schemas_1.deployHistorySchema; } });
 Object.defineProperty(exports, "deployGetSchema", { enumerable: true, get: function () { return schemas_1.deployGetSchema; } });

package/dist/api/deploy/modern-types.js

@@ -0,0 +1,23 @@
+"use strict";
+// modern deploy 接口的请求 / 响应类型（与服务端发布编排接口对齐）。
+// 第一期落地的链路：本地构建 + 本地部署。
+//
+// 接口分两类：
+//   - preRelease：所有"本地构建"链路共用，签发动态配置（含 pre-signed TOS upload URL）
+//   - localPublish：本地构建 + 本地部署专用（createReleaseLocalPublish + updateReleaseLocalPublish）
+//
+// 远端部署链路（B/C）所需的 release 接口先预留类型骨架，待 B/C 落地时启用。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalReleaseStatus = void 0;
+/**
+ * localPublish 状态枚举（数值，与服务端 IDL 对齐）。
+ * CLI updateLocalRelease 只翻 Finished / Failed 两个终态；其它由后端流转。
+ */
+exports.LocalReleaseStatus = {
+    Unspecified: 0,
+    Publishing: 1,
+    Finished: 2,
+    Failed: 3,
+    Canceled: 4,
+    Rollback: 5,
+};

package/dist/api/deploy/modern.js

@@ -0,0 +1,78 @@
+"use strict";
+// modern deploy 接口客户端。统一走管理端 innerapi（postInnerApi 信封解析）。
+//
+// 第一期落地（本地构建 + 本地部署）：
+//   - preRelease：拿 pre_release_id + version + 动态配置 data
+//   - createLocalRelease / updateLocalRelease：完整本地部署生命周期
+//
+// 远端部署（本地构建+远端部署、远端构建+远端部署）需要 createRelease + getReleaseStatus，
+// 后续 commit 接入；本文件已预留 endpoint 骨架但暂不导出。
+//
+// 约定：所有接口的 appID 走 URL :appID 路径参数，body 不再冗余携带 appID。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preRelease = preRelease;
+exports.createLocalRelease = createLocalRelease;
+exports.updateLocalRelease = updateLocalRelease;
+exports.callbackStatic = callbackStatic;
+exports.createRelease = createRelease;
+exports.getReleaseStatus = getReleaseStatus;
+exports.getLastPublishedVersion = getLastPublishedVersion;
+const http_1 = require("../../utils/http");
+const devops_error_1 = require("../../utils/devops-error");
+const DEFAULT_ERR_CODE = 'INTERNAL_DEVOPS_ERROR';
+function envelopeOpts(errPrefix) {
+    // modern deploy 接口与 default deploy / app 走同一个 lark.apaas.devops PSM，
+    // 业务错误码命名空间共享，直接复用 mapDevopsError 把 BAM 码翻为 AppError。
+    return {
+        errPrefix,
+        defaultErrCode: DEFAULT_ERR_CODE,
+        mapErr: devops_error_1.mapDevopsError,
+    };
+}
+// ── preRelease ──
+/** POST /v1/devops/app/:appID/pre_release */
+async function preRelease(req) {
+    const { appID, ...body } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/pre_release`;
+    return (0, http_1.postInnerApi)(url, body, envelopeOpts('Failed to pre-release'));
+}
+// ── localPublish ──
+/** POST /v1/devops/app/:appID/local_publish/release */
+async function createLocalRelease(req) {
+    const { appID, ...body } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/local_publish/release`;
+    return (0, http_1.postInnerApi)(url, body, envelopeOpts('Failed to create local release'));
+}
+/** POST /v1/devops/app/:appID/local_publish/update_release */
+async function updateLocalRelease(req) {
+    const { appID, ...body } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/local_publish/update_release`;
+    await (0, http_1.postInnerApi)(url, body, envelopeOpts('Failed to update local release'));
+}
+// ── callbackStatic（PaaS Storage 静态资源上传完成回调） ──
+/** POST /v1/storage/app/:appID/bucket/:bucketID/object/callbackStatic */
+async function callbackStatic(req) {
+    const { appID, bucketID, uploadID } = req;
+    const url = `/v1/storage/app/${encodeURIComponent(appID)}/bucket/${encodeURIComponent(bucketID)}/object/callbackStatic`;
+    return (0, http_1.postInnerApi)(url, { uploadID }, envelopeOpts('Failed to callback static upload'));
+}
+// ── release（远端部署，B / C 链路；本期不导出，类型骨架已就绪） ──
+/** POST /v1/devops/app/:appID/remote_publish/release */
+async function createRelease(req) {
+    const { appID, ...body } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/remote_publish/release`;
+    return (0, http_1.postInnerApi)(url, body, envelopeOpts('Failed to create release'));
+}
+/** POST /v1/devops/app/:appID/release/status */
+async function getReleaseStatus(req) {
+    const { appID, ...body } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/release/status`;
+    return (0, http_1.postInnerApi)(url, body, envelopeOpts('Failed to query release status'));
+}
+// ── getLastPublishedVersion（URL path 待文档补充） ──
+/** POST /v1/devops/app/:appID/last_published_version（path 待后端确认） */
+async function getLastPublishedVersion(req) {
+    const { appID } = req;
+    const url = `/v1/devops/app/${encodeURIComponent(appID)}/last_published_version`;
+    return (0, http_1.postInnerApi)(url, {}, envelopeOpts('Failed to get last published version'));
+}

package/dist/api/deploy/plugin-instances-types.js

@@ -0,0 +1,6 @@
+"use strict";
+// plugin_instances batch_save 接口的请求 / 响应类型。
+//
+// 后端已统一到 InnerEnvelope（`{data, status_code, message}`），与 modern deploy
+// 其它接口一致；旧的 BaseResp 形态已下线，类型也不再保留。
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/deploy/plugin-instances.js

@@ -0,0 +1,22 @@
+"use strict";
+// studio_server 的 plugin_instances 批量保存接口。
+//
+// 后端已统一到 InnerEnvelope（`{data, status_code, message}`）信封；不再手撸
+// 旧 BaseResp 解析，直接复用 utils/http.ts 的 postInnerApi，verbose 下也能拿到
+// `→ POST` / `body:` / `resp:` 的完整日志。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchSavePluginInstances = batchSavePluginInstances;
+const http_1 = require("../../utils/http");
+const URL_PATH = '/api/v1/studio/innerapi/plugin_instances/batch_save';
+/**
+ * POST /api/v1/studio/innerapi/plugin_instances/batch_save
+ *
+ * 把发布版本的 capability 集合注册到 studio_server。
+ * 失败时抛 AppError("DEPLOY_PLUGIN_BATCH_SAVE_FAILED")，错误信息来自 envelope.message。
+ */
+async function batchSavePluginInstances(req) {
+    await (0, http_1.postInnerApi)(URL_PATH, req, {
+        errPrefix: 'Failed to save plugin instances',
+        defaultErrCode: 'DEPLOY_PLUGIN_BATCH_SAVE_FAILED',
+    });
+}

package/dist/api/observability/api.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchLogs = searchLogs;
 exports.searchTraces = searchTraces;
 exports.getTraces = getTraces;
+exports.resolveStackTrace = resolveStackTrace;
 exports.queryMetricsData = queryMetricsData;
 exports.queryAnalyticsData = queryAnalyticsData;
 const http_1 = require("../../utils/http");
@@ -30,6 +31,15 @@ async function getTraces(req) {
         defaultErrCode: DEFAULT_ERR_CODE,
     });
 }
+// ── 前端源码堆栈反解 ──
+async function resolveStackTrace(req) {
+    const url = `/v1/observability/app/${encodeURIComponent(req.appID)}/resolve_stack_trace`;
+    const { appID: _appID, ...body } = req;
+    return (0, http_1.postInnerApi)(url, body, {
+        errPrefix: 'Failed to resolve frontend source stack',
+        defaultErrCode: DEFAULT_ERR_CODE,
+    });
+}
 // ── 监控指标 ──
 async function queryMetricsData(req) {
     const url = `/v1/observability/app/${encodeURIComponent(req.appID)}/metrics/data/query`;

package/dist/api/observability/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StatusCode = exports.SpanKind = exports.WordOperator = exports.spanSchema = exports.logItemSchema = exports.queryAnalyticsData = exports.queryMetricsData = exports.getTraces = exports.searchTraces = exports.searchLogs = void 0;
+exports.StatusCode = exports.SpanKind = exports.WordOperator = exports.spanSchema = exports.logItemSchema = exports.queryAnalyticsData = exports.queryMetricsData = exports.resolveStackTrace = exports.getTraces = exports.searchTraces = exports.searchLogs = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "searchLogs", { enumerable: true, get: function () { return api_1.searchLogs; } });
 Object.defineProperty(exports, "searchTraces", { enumerable: true, get: function () { return api_1.searchTraces; } });
 Object.defineProperty(exports, "getTraces", { enumerable: true, get: function () { return api_1.getTraces; } });
+Object.defineProperty(exports, "resolveStackTrace", { enumerable: true, get: function () { return api_1.resolveStackTrace; } });
 Object.defineProperty(exports, "queryMetricsData", { enumerable: true, get: function () { return api_1.queryMetricsData; } });
 Object.defineProperty(exports, "queryAnalyticsData", { enumerable: true, get: function () { return api_1.queryAnalyticsData; } });
 var schemas_1 = require("./schemas");

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

@@ -3,8 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAppCommands = registerAppCommands;
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/app/index");
-function registerAppCommands(program) {
-    const appCmd = program.command('app').description('应用元数据管理：查看 / 修改');
+const error_1 = require("../../../utils/error");
+function registerAppCommands(program, opts = {}) {
+    const description = opts.includeInit
+        ? '应用元数据管理：查看 / 修改 / 初始化'
+        : '应用元数据管理：查看 / 修改';
+    const appCmd = program.command('app').description(description);
     appCmd.action(() => {
         appCmd.outputHelp();
     });
@@ -15,6 +19,9 @@ function registerAppCommands(program) {
 `);
     registerAppGet(appCmd);
     registerAppUpdate(appCmd);
+    if (opts.includeInit) {
+        registerAppInit(appCmd);
+    }
 }
 function registerAppGet(parent) {
     const cmd = parent
@@ -60,3 +67,78 @@ JSON 输出
         });
     }));
 }
+function registerAppInit(parent) {
+    const cmd = parent
+        .command('init')
+        .description('初始化应用代码：抓 template 渲染、装 .agent/steering/ skills、写 .spark/meta.json。.spark/meta.json 已存在则直接退出')
+        .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
+        .option('--conf <json>', 'init 配置 JSON。支持 {"version": "<template 版本>"} / {"steeringVersion": "<steering 版本>"}，均默认 latest')
+        .option('--skip-install', '跳过依赖安装', false)
+        .addHelpText('after', `
+幂等
+  .spark/meta.json 已存在时直接退出（initialized=false, reason=already_initialized），
+  不再触发 template 渲染、不重新拉 skills、不安装依赖。
+  meta.json 在 init 流程最后才写，写了 = 已完整成功一次；
+  上一次失败留下半渲染状态时（package.json 在但 meta.json 没在）允许重跑。
+
+应用身份（appId）
+  init 不再持久化 appId。运行端命令（deploy / file / plugin 等）始终从 MIAODA_APP_ID env 读，
+  init 阶段也无需感知 appId。
+
+依赖安装
+  默认：npm install --no-audit --no-fund
+  --skip-install: 跳过
+  MIAODA_DEP_CACHE_DIR 环境变量：
+    若设了且 CWD 含 package.json，先算 md5(package.json)，
+    命中 \${MIAODA_DEP_CACHE_DIR}/\${hash}.zip 则 unzip 复用缓存；未命中或解压后 node_modules
+    为空都会 fallback npm install。
+  JSON 模式下子进程 stdout 重定向到 stderr，避免污染最终 emit 的 JSON。
+
+JSON 输出
+  已初始化：{"data": {"initialized": false, "reason": "already_initialized", "targetDir": "..."}}
+  新初始化：{"data": {"initialized": true, "template": "...", "templateVersion": "...", "steeringVersion": "...",
+                     "installed": true, "installSource": "cache|npm|skipped", "installHash": "...", ...}}
+
+示例
+  $ miaoda app init --template vite-react
+  $ miaoda app init --template vite-react --conf '{"version": "0.1.0-alpha.1"}'
+  $ miaoda app init --template vite-react --conf '{"steeringVersion": "0.1.0"}'
+  $ miaoda app init --template vite-react --skip-install
+  $ MIAODA_DEP_CACHE_DIR=/tmp/dep-cache miaoda app init --template vite-react
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        const conf = parseInitConf(rawOpts.conf);
+        await (0, index_1.handleAppInit)({
+            template: rawOpts.template,
+            conf,
+            skipInstall: rawOpts.skipInstall,
+        });
+    }));
+}
+function parseInitConf(raw) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new error_1.AppError('ARGS_INVALID', `--conf 必须是合法 JSON：${msg}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new error_1.AppError('ARGS_INVALID', '--conf 必须是 JSON 对象');
+    }
+    const version = parsed.version;
+    if (version !== undefined && typeof version !== 'string') {
+        throw new error_1.AppError('ARGS_INVALID', '--conf.version 必须是字符串');
+    }
+    const steeringVersion = parsed.steeringVersion;
+    if (steeringVersion !== undefined && typeof steeringVersion !== 'string') {
+        throw new error_1.AppError('ARGS_INVALID', '--conf.steeringVersion 必须是字符串');
+    }
+    return { version, steeringVersion };
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDeployCommandsModern = registerDeployCommandsModern;
+const shared_1 = require("../../../cli/commands/shared");
+const modern_1 = require("../../../cli/handlers/deploy/modern");
+/**
+ * modern scene (MIAODA_APP_TYPE=7) 专用 deploy 注册。
+ * 仅披露顶层 `miaoda deploy`，CLI 表面对齐 openclaw-cli：`--dir / --skip-build`。
+ *
+ * 与 default 的 registerDeployCommands 完全平行：两套实现 100% 隔离，
+ * 不共享分支、不互相依赖。后端调用与编排在 src/services/deploy/modern/。
+ */
+function registerDeployCommandsModern(program) {
+    const deployCmd = program
+        .command('deploy')
+        .description('触发 modern 应用发布：本地构建 + 本地部署（preRelease + localPublish）')
+        .option('--dir <path>', '项目目录', '.')
+        .option('--skip-build', '跳过 build 步骤（已构建好时使用）', false)
+        .addHelpText('after', `
+不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
+
+前置要求
+  - 项目已 init（.spark/meta.json 含 stack）
+  - MIAODA_APP_ID 已设置（应用身份从 env 读，不再从 meta.json 读）
+  - node_modules 已安装
+  - package.json 含 build script
+  - 沙箱内预装 tosutil（用于把构建产物上传到 TOS）
+
+流程概览（stderr 进度提示）
+  1. prepareContext  2. preRelease   3. build
+  4. createLocalRelease              5. uploadArtifacts
+  6. savePluginInstances（扫描 dist/output_capabilities/*.json 批量注册）
+  7. finalizeLocalRelease(Finished|Failed)
+
+JSON 输出（stdout）
+  {"data": {"appId": "...", "version": <n>, "url": "...", "releaseID": "...", "preReleaseID": "..."}}
+
+示例
+  $ miaoda deploy
+  $ miaoda deploy --dir ./my-app
+  $ miaoda deploy --skip-build
+`);
+    deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
+        await (0, modern_1.handleDeployModern)({
+            dir: rawOpts.dir ?? '.',
+            appId: (0, shared_1.resolveAppId)({}),
+            skipBuild: rawOpts.skipBuild,
+        });
+    }));
+}

package/dist/cli/commands/index.js

@@ -1,15 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveScene = resolveScene;
 exports.registerCommands = registerCommands;
 const index_1 = require("../../cli/commands/file/index");
 const index_2 = require("../../cli/commands/db/index");
 const index_3 = require("../../cli/commands/observability/index");
 const index_4 = require("../../cli/commands/app/index");
 const index_5 = require("../../cli/commands/deploy/index");
+const modern_1 = require("../../cli/commands/deploy/modern");
+const index_6 = require("../../cli/commands/skills/index");
+function resolveScene(appType, _archType) {
+    if (appType === '7')
+        return 'modern';
+    return 'default';
+}
+const SCENE_REGISTRARS = {
+    default: (p) => {
+        (0, index_4.registerAppCommands)(p);
+        (0, index_5.registerDeployCommands)(p);
+        (0, index_2.registerDbCommands)(p);
+        (0, index_1.registerFileCommands)(p);
+        (0, index_3.registerObservabilityCommands)(p);
+    },
+    modern: (p) => {
+        (0, index_4.registerAppCommands)(p, { includeInit: true });
+        (0, modern_1.registerDeployCommandsModern)(p);
+        (0, index_6.registerSkillsCommands)(p);
+    },
+};
+function readEnv(name) {
+    const v = process.env[name]?.trim();
+    return v !== undefined && v !== '' ? v : undefined;
+}
 function registerCommands(program) {
-    (0, index_1.registerFileCommands)(program);
-    (0, index_2.registerDbCommands)(program);
-    (0, index_3.registerObservabilityCommands)(program);
-    (0, index_4.registerAppCommands)(program);
-    (0, index_5.registerDeployCommands)(program);
+    const appType = readEnv('MIAODA_APP_TYPE');
+    const archType = readEnv('MIAODA_APP_ARCH_TYPE');
+    const scene = resolveScene(appType, archType);
+    SCENE_REGISTRARS[scene](program);
+    if (process.env.MIAODA_VERBOSE === '1' || process.argv.includes('--verbose')) {
+        process.stderr.write(`[miaoda] scene=${scene} app_type=${appType ?? '-'} arch_type=${archType ?? '-'}\n`);
+    }
 }

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

@@ -14,6 +14,24 @@ const COMMON_TIME_HELP = `
     1) 不带时区的形式与 pretty 输出闭环（同机器复制粘贴稳定）；跨机器请带显式时区。
     2) 必须用 T 分隔日期与时间，禁止空格——shell 会把不带引号的 'YYYY-MM-DD HH:mm:ss' 拆成两个参数。
 `;
+function normalizeRepeatedOption(value) {
+    if (Array.isArray(value)) {
+        const items = value.filter((item) => typeof item === 'string' && item.length > 0);
+        return items.length === 1 ? items[0] : items;
+    }
+    return value;
+}
+function normalizeRepeatedArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string' && item.length > 0);
+    }
+    return typeof value === 'string' && value ? [value] : [];
+}
+function compactRepeatedOption(values) {
+    if (values.length === 0)
+        return undefined;
+    return values.length === 1 ? values[0] : values;
+}
 function registerObservabilityCommands(program) {
     const obCmd = program
         .command('observability')
@@ -31,6 +49,7 @@ function registerObservabilityCommands(program) {
 `);
     registerLog(obCmd);
     registerTrace(obCmd);
+    registerSourceStack(obCmd);
     registerMetric(obCmd);
     registerAnalytics(obCmd);
 }
@@ -45,8 +64,8 @@ function registerLog(parent) {
         .argParser((0, shared_1.caseInsensitiveChoice)(['DEBUG', 'INFO', 'WARN', 'ERROR'])))
         .option('--since <time>', '开始时间')
         .option('--until <time>', '截止时间')
-        .option('--log-id <id>', '按请求 logid 过滤（attributes.ob_data_id）')
-        .option('--trace-id <id>', '按 trace ID 过滤')
+        .addOption(new commander_1.Option('--log-id <id>', '按请求 logid 过滤（可重复传入）').argParser(shared_1.collectRepeatedOption))
+        .addOption(new commander_1.Option('--trace-id <id>', '按 trace ID 过滤（可重复传入）').argParser(shared_1.collectRepeatedOption))
         .option('--grep <pattern>', '按关键字模糊搜索 body')
         .option('--module <name>', '按模块名过滤')
         .option('--user-id <user-id>', '按触发用户 ID 过滤')
@@ -63,7 +82,9 @@ JSON 输出
 示例
   $ miaoda observability log --since 1h --level error --json
   $ miaoda observability log --log-id log_abc123 --json
+  $ miaoda observability log --log-id log_1 --log-id log_2 --json
   $ miaoda observability log --trace-id 140ebb5ac9b... --json
+  $ miaoda observability log --trace-id trace_1 --trace-id trace_2 --json
   $ miaoda observability log --api /api/orders --min-duration 200 --json
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
@@ -74,8 +95,8 @@ JSON 输出
             level: rawOpts.level,
             since: rawOpts.since,
             until: rawOpts.until,
-            logId: rawOpts.logId,
-            traceId: rawOpts.traceId,
+            logId: normalizeRepeatedOption(rawOpts.logId),
+            traceId: normalizeRepeatedOption(rawOpts.traceId),
             grep: rawOpts.grep,
             module: rawOpts.module,
             userId: rawOpts.userId,
@@ -100,7 +121,7 @@ function registerTrace(parent) {
         .addOption((0, shared_1.appIdOption)().hideHelp())
         .option('--since <time>', '开始时间')
         .option('--until <time>', '截止时间')
-        .option('--trace-id <id>', '按 trace ID 过滤')
+        .addOption(new commander_1.Option('--trace-id <id>', '按 trace ID 过滤（可重复传入）').argParser(shared_1.collectRepeatedOption))
         .option('--root-span <span-name>', '按入口节点关键词过滤')
         .option('--user-id <user-id>', '按触发用户 ID 过滤')
         .option('--limit <n>', '返回条数上限（1~100）', parseLimit, 50)
@@ -111,6 +132,7 @@ JSON 输出
 
 示例
   $ miaoda observability trace list --since 1h --json
+  $ miaoda observability trace list --trace-id trace_1 --trace-id trace_2 --json
   $ miaoda observability trace list --root-span api-gateway --limit 20 --json
 `);
     listCmd.action((0, shared_1.withHelp)(listCmd, async (rawOpts) => {
@@ -120,7 +142,7 @@ JSON 输出
             appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
             since: rawOpts.since,
             until: rawOpts.until,
-            traceId: rawOpts.traceId,
+            traceId: normalizeRepeatedOption(rawOpts.traceId),
             rootSpan: rawOpts.rootSpan,
             userId: rawOpts.userId,
             limit: rawOpts.limit,
@@ -154,6 +176,40 @@ JSON 输出
         });
     }));
 }
+// ── source-stack ──
+function registerSourceStack(parent) {
+    const cmd = parent
+        .command('source-stack')
+        .description('反解前端错误堆栈到源码位置')
+        .argument('[log-ids...]', '前端错误请求 logid，可传多个')
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addOption(new commander_1.Option('--log-id <id>', '前端错误请求 logid（可重复传入）').argParser(shared_1.collectRepeatedOption))
+        .addOption(new commander_1.Option('--trace-id <id>', '包含前端错误的 trace ID（可重复传入）').argParser(shared_1.collectRepeatedOption))
+        .option('--since <time>', '开始时间')
+        .option('--until <time>', '截止时间')
+        .option('--limit <n>', '每类查询返回条数上限（1~100）', parseLimit, 50)
+        .addHelpText('after', `${COMMON_TIME_HELP}
+JSON 输出
+  {"data": [{"log_id": "...", "trace_id": "...", "status": "resolved", "error_message_stack": "Error: boom\\n  at src/App.tsx:42:7"}], "next_cursor": null, "has_more": false}
+
+示例
+  $ miaoda observability source-stack --log-id log_1 --log-id log_2 --json
+  $ miaoda observability source-stack --trace-id trace_1 --trace-id trace_2 --json
+  $ miaoda observability source-stack log_abc123 --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (logIds, rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, 'since', 'until');
+        (0, shared_1.rejectCliOverride)(cmd, 'appId');
+        await (0, index_1.handleObservabilitySourceStack)({
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            logId: compactRepeatedOption([...logIds, ...normalizeRepeatedArray(rawOpts.logId)]),
+            traceId: normalizeRepeatedOption(rawOpts.traceId),
+            since: rawOpts.since,
+            until: rawOpts.until,
+            limit: rawOpts.limit,
+        });
+    }));
+}
 // ── metric ──
 function registerMetric(parent) {
     const cmd = parent

package/dist/cli/commands/shared.js

@@ -7,6 +7,7 @@ exports.softRequiredOption = softRequiredOption;
 exports.resolveAppId = resolveAppId;
 exports.withHelp = withHelp;
 exports.caseInsensitiveChoice = caseInsensitiveChoice;
+exports.collectRepeatedOption = collectRepeatedOption;
 exports.validateTimeOptions = validateTimeOptions;
 exports.rejectCliOverride = rejectCliOverride;
 const commander_1 = require("commander");
@@ -86,6 +87,10 @@ function caseInsensitiveChoice(canonical) {
         return hit;
     };
 }
+/** Commander repeatable option parser：重复传入时收集为数组。 */
+function collectRepeatedOption(value, previous = []) {
+    return [...previous, value];
+}
 /**
  * --since / --until 等时间参数的 action 阶段校验。
  *

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSkillsCommands = registerSkillsCommands;
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../cli/handlers/skills/index");
+/**
+ * miaoda skills：本地 agent skills 维护。
+ *
+ * 当前仅 steering 一类子集（coding-steering 包内的 _common/skills + <stack>/skills + tech.md）；
+ * 后续如有更多 skill 类型再加 --type。`app init` 会一次性同步装上，独立 `skills sync` 用于
+ * 后续单独升级 / pin 版本，不必走完整 init。
+ */
+function registerSkillsCommands(program) {
+    const skillsCmd = program.command('skills').description('本地 agent skills（含 steering）维护');
+    skillsCmd.action(() => {
+        skillsCmd.outputHelp();
+    });
+    registerSkillsSync(skillsCmd);
+    registerSkillsStatus(skillsCmd);
+}
+function registerSkillsSync(parent) {
+    const cmd = parent
+        .command('sync')
+        .description('同步 coding-steering（latest 或指定版本）到 .agent/steering/')
+        .argument('[version]', 'coding-steering 包版本或 dist-tag，缺省 latest')
+        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .addHelpText('after', `
+前置要求
+  当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack）
+
+JSON 输出
+  {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false}}
+
+示例
+  $ miaoda skills sync
+  $ miaoda skills sync 0.2.0
+  $ miaoda skills sync --dir ./my-app
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (version, rawOpts) => {
+        await (0, index_1.handleSkillsSync)({
+            dir: rawOpts.dir,
+            version,
+        });
+    }));
+}
+function registerSkillsStatus(parent) {
+    const cmd = parent
+        .command('status')
+        .description('查看本地 .agent/steering/ 的当前状态（不联网）')
+        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .addHelpText('after', `
+JSON 输出
+  {"data": {"present": true|false, "skills": [...], "techSynced": true|false}}
+
+示例
+  $ miaoda skills status
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleSkillsStatus)({
+            dir: rawOpts.dir,
+        });
+    }));
+}