@lark-apaas/miaoda-cli 0.1.37 → 0.1.39-alpha.24bc5ff

package/README.md

@@ -52,6 +52,16 @@ miaoda file ls --output json
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 全栈应用的 MCP UI 检查
+
+创建 MCP UI 时，Agent 在 `server/mcp/ui` 中同时生成 `tsconfig.json` 和 `eslint.config.cjs`，修改 UI 或其 shared 依赖后主动运行独立检查。模板和 CLI 不生成 UI 配置，也不将 UI 检查接入主工程 lint/type:check。
+
+主工程保留原 client/server 检查。Agent 从工程根执行 `npx --no-install tsc --noEmit --project server/mcp/ui/tsconfig.json`，再执行 `npx --no-install eslint --config server/mcp/ui/eslint.config.cjs "server/mcp/ui/**/*.{ts,tsx,js,jsx}" --max-warnings 0`；必须检查退出码并修复错误。无需辅助脚本或新增 npm 命令。
+
+CLI 不注入 MCP UI 检查命令；主工程保留原有 client/server 检查，UI 由 Agent 按独立配置执行标准 tsc/eslint。
+
+存量 sync 不改写 ESLint 源码；UI 全局排除项由平台 ESLint 预设提供。TS 仅向已有显式 `exclude` 数组追加目录，保留注释和原项；依赖继承且未显式声明 `exclude` 的自定义配置保持不变并提示人工调整。自定义检查命令保留。lint.js 和 build.sh 仍由平台脚本模板维护，不依赖预设包中的脚本执行入口。
+
 ## 打包可本地访问的静态产物
 
 `miaoda app pack`（默认 `--mode standalone`）把当前应用构建成一份自包含静态产物，可脱离妙搭平台本地打开。

package/dist/api/deploy/approval.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_NODE_STATUSES = void 0;
+exports.approvalStatusText = approvalStatusText;
+exports.findApproval = findApproval;
+exports.approvalURL = approvalURL;
+const types_1 = require("./types");
+/** 流水线终态；REJECTED 为卡点审批被拒 */
+exports.TERMINAL_NODE_STATUSES = [
+    types_1.NodeStatus.SUCCESS,
+    types_1.NodeStatus.FAILED,
+    types_1.NodeStatus.CANCELED,
+    types_1.NodeStatus.REJECTED,
+];
+const APPROVAL_STATUS_TEXT = {
+    [types_1.ApprovalStatus.UNSPECIFIED]: 'unknown',
+    [types_1.ApprovalStatus.PENDING]: 'pending',
+    [types_1.ApprovalStatus.APPROVED]: 'approved',
+    [types_1.ApprovalStatus.REJECTED]: 'rejected',
+    [types_1.ApprovalStatus.CANCELED]: 'canceled',
+    [types_1.ApprovalStatus.FAILED]: 'failed',
+};
+/** 仍需用户知道点什么的卡点：在等谁、为什么被拒、平台没把审批发出去；已通过 / 已撤回不再展示 */
+const SURFACED_APPROVAL_STATUSES = [
+    types_1.ApprovalStatus.PENDING,
+    types_1.ApprovalStatus.REJECTED,
+    types_1.ApprovalStatus.FAILED,
+];
+/** 卡点审批状态数字 → 可读字符串；未知值为 unknown(n) */
+function approvalStatusText(v) {
+    return APPROVAL_STATUS_TEXT[Number(v)] ?? `unknown(${String(v)})`;
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function* jobsOf(stages) {
+    if (!Array.isArray(stages))
+        return;
+    for (const stage of stages) {
+        if (!isRecord(stage) || !Array.isArray(stage.jobs))
+            continue;
+        for (const group of stage.jobs) {
+            if (!Array.isArray(group))
+                continue;
+            for (const job of group)
+                if (isRecord(job))
+                    yield job;
+        }
+    }
+}
+/**
+ * 从 CliQueryPipelineInstance 的 PipelineInstance（接口默认返回审批展示视图）中摘出需要输出的卡点：
+ * 第一个 status 为 PENDING / REJECTED / FAILED 的 Job.approval。一次发布可以被拦多次
+ * （build / db_check / deploy），已通过的卡点可能排在前面，不能取它；流水线串行，需要输出的至多一个。
+ * 与妙搭发布面板 findApprovalJob 同一口径。
+ *
+ * 原样透传，status 转为可读字符串，原始数字保留在 status_code（与 detail 各层 status 的约定一致）。
+ * 是否在审批中由顶层 status（PENDING）表达，这里只负责摘出审批链接、拒绝原因等上下文。
+ */
+function findApproval(instance) {
+    for (const job of jobsOf(instance.stages)) {
+        const approval = job.approval;
+        if (!isRecord(approval) || !SURFACED_APPROVAL_STATUSES.includes(approval.status))
+            continue;
+        return {
+            ...approval,
+            status: approvalStatusText(approval.status),
+            status_code: approval.status,
+        };
+    }
+    return undefined;
+}
+/** 取审批链接；缺失或不是非空字符串时返回 undefined。是否可信由调用方（Skill）判断。 */
+function approvalURL(approval) {
+    const url = approval?.approvalURL;
+    return typeof url === 'string' && url !== '' ? url : undefined;
+}

package/dist/api/deploy/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodeStatus = exports.nodeStatusFromText = exports.nodeStatusText = exports.errorJobSchema = exports.deployGetSchema = exports.deployHistorySchema = exports.batchSavePluginInstances = exports.TosActionType = exports.LocalReleaseStatus = exports.applyTosDiff = exports.getModernLastPublishedVersion = exports.getModernReleaseStatus = exports.createModernRelease = exports.callbackStatic = exports.updateLocalRelease = exports.createLocalRelease = exports.preRelease = exports.queryPipelineInstance = exports.getErrorLog = exports.listPipelineInstances = exports.createRelease = void 0;
+exports.TERMINAL_NODE_STATUSES = exports.approvalStatusText = exports.approvalURL = exports.findApproval = exports.ApprovalStatus = exports.NodeStatus = exports.nodeStatusFromText = exports.nodeStatusText = exports.errorJobSchema = exports.deployGetSchema = exports.deployHistorySchema = exports.batchSavePluginInstances = exports.TosActionType = exports.LocalReleaseStatus = exports.applyTosDiff = 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; } });
@@ -28,3 +28,9 @@ Object.defineProperty(exports, "nodeStatusText", { enumerable: true, get: functi
 Object.defineProperty(exports, "nodeStatusFromText", { enumerable: true, get: function () { return schemas_1.nodeStatusFromText; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "NodeStatus", { enumerable: true, get: function () { return types_1.NodeStatus; } });
+Object.defineProperty(exports, "ApprovalStatus", { enumerable: true, get: function () { return types_1.ApprovalStatus; } });
+var approval_1 = require("./approval");
+Object.defineProperty(exports, "findApproval", { enumerable: true, get: function () { return approval_1.findApproval; } });
+Object.defineProperty(exports, "approvalURL", { enumerable: true, get: function () { return approval_1.approvalURL; } });
+Object.defineProperty(exports, "approvalStatusText", { enumerable: true, get: function () { return approval_1.approvalStatusText; } });
+Object.defineProperty(exports, "TERMINAL_NODE_STATUSES", { enumerable: true, get: function () { return approval_1.TERMINAL_NODE_STATUSES; } });

package/dist/api/deploy/schemas.js

@@ -13,6 +13,9 @@ const NODE_STATUS_TEXT = {
     [types_1.NodeStatus.FAILED]: 'failed',
     [types_1.NodeStatus.CANCELED]: 'canceled',
     [types_1.NodeStatus.HOLD_ON]: 'hold_on',
+    [types_1.NodeStatus.SKIPPED]: 'skipped',
+    [types_1.NodeStatus.PENDING]: 'pending',
+    [types_1.NodeStatus.REJECTED]: 'rejected',
 };
 function nodeStatusText(v) {
     if (typeof v === 'string')

package/dist/api/deploy/types.js

@@ -8,7 +8,7 @@
 // 发布单的唯一标识是 pipelineTaskID，对外即 deploy-id；error-log 等接口直接用它做
 // URL 路径段（instanceID）。曾经的 Release/releaseID 概念已全面废弃。
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NodeStatus = void 0;
+exports.ApprovalStatus = exports.NodeStatus = void 0;
 /** Pipeline 节点状态（devops_platform） */
 var NodeStatus;
 (function (NodeStatus) {
@@ -18,5 +18,23 @@ var NodeStatus;
     NodeStatus[NodeStatus["SUCCESS"] = 3] = "SUCCESS";
     NodeStatus[NodeStatus["FAILED"] = 4] = "FAILED";
     NodeStatus[NodeStatus["CANCELED"] = 5] = "CANCELED";
+    /** 已废弃：服务端不再产出，保留仅为兼容历史数据 */
     NodeStatus[NodeStatus["HOLD_ON"] = 6] = "HOLD_ON";
+    /** 流水线内部中间态 */
+    NodeStatus[NodeStatus["SKIPPED"] = 7] = "SKIPPED";
+    NodeStatus[NodeStatus["PENDING"] = 8] = "PENDING";
+    /** 卡点审批被拒（人工拒绝 / 超时自动拒绝） */
+    NodeStatus[NodeStatus["REJECTED"] = 9] = "REJECTED";
 })(NodeStatus || (exports.NodeStatus = NodeStatus = {}));
+// ── 发布审批（卡点）信息 ────────────
+/** 卡点审批状态（devops_platform ApprovalStatus） */
+var ApprovalStatus;
+(function (ApprovalStatus) {
+    ApprovalStatus[ApprovalStatus["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    ApprovalStatus[ApprovalStatus["PENDING"] = 1] = "PENDING";
+    ApprovalStatus[ApprovalStatus["APPROVED"] = 2] = "APPROVED";
+    ApprovalStatus[ApprovalStatus["REJECTED"] = 3] = "REJECTED";
+    ApprovalStatus[ApprovalStatus["CANCELED"] = 4] = "CANCELED";
+    /** 卡点异常：发起审批失败等平台侧错误 */
+    ApprovalStatus[ApprovalStatus["FAILED"] = 5] = "FAILED";
+})(ApprovalStatus || (exports.ApprovalStatus = ApprovalStatus = {}));

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

@@ -4,6 +4,18 @@ exports.registerDeployCommands = registerDeployCommands;
 const commander_1 = require("commander");
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/deploy/index");
+/** deploy history --status 可选值（pipeline 节点状态）；hold_on 已被服务端废弃，仅为兼容保留 */
+const HISTORY_STATUS_CHOICES = [
+    'todo',
+    'running',
+    'success',
+    'failed',
+    'canceled',
+    'rejected',
+    'pending',
+    'skipped',
+    'hold_on',
+];
 const COMMON_TIME_HELP = `
 时间格式：
   - 相对时间：30m（30 分钟前）、1h、2d、1w
@@ -21,8 +33,9 @@ function registerDeployCommands(program) {
         .description('触发发布；支持 --wait 阻塞到终态。子命令：get / history / error-log')
         .addOption((0, shared_1.appIdOption)().hideHelp())
         .addOption((0, shared_1.branchOption)().hideHelp())
-        .option('--wait', '阻塞直到流水线终态', false)
+        .option('--wait', '阻塞直到流水线终态或进入人工审批', false)
         .option('--timeout <sec>', '--wait 最长等待秒数（默认 300）', parseTimeout, 300)
+        .option('--apply-reason <text>', '发布申请理由，写入审批单（单行，最多 1000 字符；是否必填由服务端按应用类型判定）')
         .addHelpText('after', `
 不要用异步模式或后台模式调用 deploy（例如 &、nohup、后台 task、detached run，或任何会让命令提前返回的包装方式），否则调用可能提前结束，Agent 会误判发布已完成。
 部署前置检查（Agent 必须执行）
@@ -31,20 +44,29 @@ function registerDeployCommands(program) {
     - 是本次任务的产物 → 先 commit + push 再 deploy
     - 不能确定意图 → 用 AskUser 跟用户确认（不要默默继续）
 
+发布理由与审批
+  需要审批的应用发布时须带 --apply-reason（是否必填由服务端判定，缺失时服务端会报错）。
+  理由为单行文本，最多 1000 字符，不能包含控制字符、零宽字符与双向控制字符。
+  发布进入人工审批（status=pending）后 --wait 会立即返回，退出码为 0，不会轮询到超时。
+
 JSON 输出
   不带 --wait：{"data": {"pipelineTaskID": "..."}}（pipelineTaskID 即 deploy-id）
-  带 --wait：data 额外包含 detail（pipeline 终态）
+  带 --wait：data 额外包含 detail（pipeline 当前状态）；
+    有卡点信息时还包含 approval（如 status、approvalURL、被拒时的 message）。
   detail/status 字段为可读字符串；对应 *_code 字段保留 BAM 原始数字枚举。
 
 状态确认（Agent 必须执行）
-  优先使用 --wait，但无论是否传 --wait，只要 deploy 调用后没有明确的 success / failed / canceled 终态，
+  优先使用 --wait。status 为 pending 时停止轮询，告诉用户正在等待审批负责人处理；
+  用户确认审批处理完后，查询同一个 deploy-id，不要重新发起发布。
+  其余情况下，只要 deploy 调用后没有明确的 success / failed / rejected / canceled 终态或 pending，
   都必须每 2s 轮询一次当前发布状态：拿到 pipelineTaskID 就执行 \`miaoda deploy get <pipelineTaskID> --json\`；
   如果没有拿到 deploy-id 或输出为空，先执行 \`miaoda deploy history --limit 1 --json\` 找到对应发布记录并取得 ID，
-  再用这个 ID 每 2s 执行一次 \`miaoda deploy get <ID> --json\`，直到 status 进入终态。
+  再用这个 ID 每 2s 执行一次 \`miaoda deploy get <ID> --json\`，直到 status 进入终态或 pending。
 
 示例
   $ miaoda deploy
   $ miaoda deploy --wait --timeout 600
+  $ miaoda deploy --wait --apply-reason "修复登录页报错"
   $ miaoda deploy get 12345
   $ miaoda deploy history --status failed
 `);
@@ -55,6 +77,7 @@ JSON 输出
             branch: rawOpts.branch,
             wait: rawOpts.wait,
             timeout: rawOpts.timeout,
+            applyReason: rawOpts.applyReason,
         });
     }));
     registerDeployGet(deployCmd);
@@ -72,6 +95,7 @@ JSON 输出
   {"data": {"ID": ..., "status": ..., "creator": "...", "createdAt": ..., "updatedAt": ..., ...}, "next_cursor": null, "has_more": false}
   ID 即 deploy-id（== pipelineTaskID）
   data.status 为可读字符串；data.status_code 为 BAM 原始数字枚举。
+  status 为 pending / rejected / failed 且存在审批单时，额外包含 approval（如 status、approvalURL、被拒时的 message）。
 
 示例
   $ miaoda deploy get 12345
@@ -90,8 +114,8 @@ function registerDeployHistory(parent) {
         .description('查询发布历史（按时间倒序，分页）')
         .addOption((0, shared_1.appIdOption)().hideHelp())
         .addOption(new commander_1.Option('--status <status>', '状态过滤（pipeline 节点状态，大小写不敏感）')
-        .choices(['todo', 'running', 'success', 'failed', 'canceled', 'hold_on'])
-        .argParser((0, shared_1.caseInsensitiveChoice)(['todo', 'running', 'success', 'failed', 'canceled', 'hold_on'])))
+        .choices(HISTORY_STATUS_CHOICES)
+        .argParser((0, shared_1.caseInsensitiveChoice)(HISTORY_STATUS_CHOICES)))
         .option('--since <time>', '起始时间')
         .option('--until <time>', '截止时间')
         .option('--limit <n>', '返回条数上限（1~100）', parseLimit, 50)

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

@@ -18,7 +18,14 @@ function registerDeployCommandsModern(program) {
         .option('--dir <path>', '项目目录', '.')
         .option('--skip-build', '跳过 build 步骤（已构建好时使用）', false)
         .option('--skip-release', '不创建/更新本地发布单，发布单状态由外部托管', false)
-        .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID 两字段')
+        .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID / sessionID / marker / versionLevel 五字段')
+        // 这三个 flag 只在父命令声明一份，deploy 与 deploy patch 共用。
+        // 不能在 patch 上再声明一遍：commander 遇到父子同名 option 会把值判给父命令，
+        // 子命令拿到空数组，`deploy patch --create x` 会静默失效（deploy-patch-wiring 测试可复现）。
+        // patch 从 deployCmd.opts() 读，与它今天读 --dir 的方式一致。
+        .option('--create <relpath>', '新增文件（可重复）', shared_1.collectRepeatedOption, [])
+        .option('--update <relpath>', '修改文件（可重复）', shared_1.collectRepeatedOption, [])
+        .option('--delete <relpath>', '删除文件（可重复）', shared_1.collectRepeatedOption, [])
         .addHelpText('after', `
 不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
 
@@ -41,14 +48,27 @@ function registerDeployCommandsModern(program) {
   外部据 stdout 返回的 version / preReleaseID 自行建单，并据本命令的
   退出码决定把发布单翻成 Finished 还是 Failed —— 失败态由外部负责，CLI 不再兜底。
   该模式下 releaseID / url 输出为 null（CLI 未建单，无从得知）。
-  注意：--conf 的 checkPointVersion / commitID 唯一消费者是 createLocalRelease，
+  注意：--conf 的四个字段唯一消费者是 createLocalRelease，
   本模式下不生效（静默忽略，不报错），需要关联请在外部建单时自行传递。
 
+--create / --update / --delete（变更文件清单）
+  可重复，值为工程根相对路径（禁绝对路径与 ".."）。deploy patch 消费它做增量发布；
+  在 deploy 下当前是预留口子——只校验路径并记一行日志，不改变上传行为：
+  deploy 仍然全量上传产物，latest 每次被重建为工作区的精确镜像（prune 清理远端多余对象），
+  以此保证 git 仓库与 TOS 资源不会不一致。
+  后续若实现增量上传，从这里取「要 PUT 哪些文件」即可，调用方无需改动；
+  删除仍交给 prune，因为 prune 比对的是完整本地清单，与上传了哪些文件无关。
+
 --conf（关联元信息透传）
-  值为 JSON string，只识别两个字段，其余 key 忽略：
+  值为 JSON string，只识别四个字段，其余 key 忽略：
     checkPointVersion  关联的 checkpoint 版本
     commitID           关联的代码 commit ID
-  两字段均可选；非法 JSON / 非对象 / 字段值非字符串会报错。
+    sessionID          发起本次发布的页面会话 ID，原样透传不做净化
+    marker             本次发布的变更说明，落发布单 description
+  四字段均可选；非法 JSON / 非对象 / 字段值非字符串会报错。
+  versionLevel：本次发布的版本档位。"major" 声明这是一个大版本，历史记录里强制开新组；
+  "minor" 声明是小版本，即使距上次发布超过聚合阈值也不提升。不传则由服务端按
+  时间间隔自动判定，与改造前行为一致——只有会主动声明档位的链路需要传。
 
 JSON 输出（stdout）
   {"data": {"appId": "...", "version": <n>, "url": "...", "releaseID": "...", "preReleaseID": "..."}}
@@ -60,6 +80,8 @@ JSON 输出（stdout）
   $ miaoda deploy --skip-build
   $ miaoda deploy --skip-release
   $ miaoda deploy --conf '{"checkPointVersion":"v3","commitID":"a1b2c3d"}'
+  $ miaoda deploy --conf '{"commitID":"a1b2c3d","sessionID":"<uuid>","marker":"编辑保存：修改 index.html"}'
+  $ miaoda deploy --update index.html --create assets/new.js --delete old.html
 `);
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
         await (0, modern_1.handleDeployModern)({
@@ -68,17 +90,18 @@ JSON 输出（stdout）
             skipBuild: rawOpts.skipBuild,
             skipRelease: rawOpts.skipRelease,
             conf: rawOpts.conf,
+            creates: rawOpts.create,
+            updates: rawOpts.update,
+            deletes: rawOpts.delete,
         });
     }));
     const patchCmd = deployCmd
         .command('patch')
         .description('design-html 增量发布：按文件 create/update/delete，.html 变动时同步 routes.json')
-        .option('--create <relpath>', '新增文件（可重复）', shared_1.collectRepeatedOption, [])
-        .option('--update <relpath>', '覆盖已有文件（可重复）', shared_1.collectRepeatedOption, [])
-        .option('--delete <relpath>', '删除文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--session-id <id>', '会话 ID，发布时透传给下游（可选）')
         .addHelpText('after', `
---dir 为项目目录（与 deploy 同名参数，默认当前目录）。
+--dir / --create / --update / --delete 声明在父命令 deploy 上，本命令共用，用法不变。
+--dir 为项目目录，默认当前目录。
 仅支持 design-html（design_local_deploy）。路径为工程根相对路径（= 服务端 latest 下 key），
 禁绝对路径与 ".."。--create/--update 的本地文件必须存在。改动里含任意 .html（增 / 改 / 删）
 时自动重算并随包更新 routes.json；纯非 .html 改动不动 routes.json。
@@ -98,9 +121,9 @@ JSON 输出
         await (0, index_1.handleDeployPatch)({
             appId: (0, shared_1.resolveAppId)({}),
             dir: deployCmd.opts().dir ?? '.',
-            creates: rawOpts.create,
-            updates: rawOpts.update,
-            deletes: rawOpts.delete,
+            creates: deployCmd.opts().create,
+            updates: deployCmd.opts().update,
+            deletes: deployCmd.opts().delete,
             sessionID: rawOpts.sessionId,
         });
     }));

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

@@ -53,7 +53,7 @@ function registerSkillsSync(parent) {
 
 JSON 输出
   {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false,
-            "claudeSkillsLink": "created|updated|noop|conflict"  // 仅 --local 时}}
+            "claudeSkillsLink": "created|updated|noop|conflict|unsupported"  // 仅 --local 时}}
 
   传 --type 时：
   {"data": {"mode": "sandbox", "type": "...", "packageName": "...", "version": "...",

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

@@ -38,11 +38,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = void 0;
 exports.handleAppExport = handleAppExport;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const api = __importStar(require("../../../api/index"));
+const archive_1 = require("../../../utils/archive");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const logger_1 = require("../../../utils/logger");
@@ -95,11 +95,11 @@ function extractArchive(archivePath, destDir, head) {
     const isZip = head.length >= 4 && head[0] === 0x50 && head[1] === 0x4b;
     const isGzip = head.length >= 2 && head[0] === 0x1f && head[1] === 0x8b;
     if (isZip) {
-        (0, node_child_process_1.execFileSync)('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio: 'pipe' });
+        (0, archive_1.extractZip)(archivePath, destDir);
         return;
     }
     if (isGzip) {
-        (0, node_child_process_1.execFileSync)('tar', ['-xzf', archivePath, '-C', destDir], { stdio: 'pipe' });
+        (0, archive_1.extractTarGz)(archivePath, destDir);
         return;
     }
     throw new error_1.AppError('EXPORT_ARCHIVE_INVALID', '无法识别归档格式（非 zip / tar.gz）', {

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

@@ -16,6 +16,7 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const env_1 = require("../../../utils/env");
 const logger_1 = require("../../../utils/logger");
+const run_npm_1 = require("../../../utils/run-npm");
 /**
  * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
  *
@@ -126,7 +127,7 @@ async function handleAppMigrate(opts) {
     (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
     let installError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
+        (0, run_npm_1.execNpmSync)(installArgs, {
             cwd: targetDir,
             stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
         });
@@ -167,6 +168,8 @@ async function handleAppMigrate(opts) {
     //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
     //     留着旧进程让用户先处理 installError
     //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
+    //   - pkill 是 POSIX-only,但整段被 isSandboxEnv() 包着(沙箱恒为 Linux),
+    //     Windows 本地永远走不到这里,故不需要跨平台封装
     let devRestarted = false;
     if (installError === undefined && (0, env_1.isSandboxEnv)()) {
         (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');

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

@@ -9,7 +9,6 @@ exports.runStackSync = runStackSync;
 exports.summarizeSyncResults = summarizeSyncResults;
 exports.snapshotManagedDepSpecs = snapshotManagedDepSpecs;
 exports.diffManagedSpecs = diffManagedSpecs;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const sync_configs_1 = require("../../../config/sync-configs");
@@ -19,6 +18,7 @@ const githooks_1 = require("../../../utils/githooks");
 const logs_dir_1 = require("../../../utils/logs-dir");
 const install_1 = require("../../../services/app/init/install");
 const spark_meta_1 = require("../../../utils/spark-meta");
+const run_npm_1 = require("../../../utils/run-npm");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const logger_1 = require("../../../utils/logger");
@@ -127,7 +127,7 @@ async function handleAppSync(opts) {
     (0, logger_1.log)('sync', `Running npm ${installArgs.join(' ')}...`);
     let installError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
+        (0, run_npm_1.execNpmSync)(installArgs, {
             cwd: targetDir,
             stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
         });

package/dist/cli/handlers/db/sql.js

@@ -47,7 +47,7 @@ const colors_1 = require("../../../utils/colors");
 const fuzzy_match_1 = require("../../../utils/fuzzy-match");
 const index_1 = require("../../../api/db/index");
 const sql_keywords_1 = require("../../../api/db/sql-keywords");
-const node_child_process_1 = require("node:child_process");
+const run_npm_1 = require("../../../utils/run-npm");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 /**
@@ -140,20 +140,22 @@ async function maybeSyncAgentSchema(results) {
     (0, logger_1.debug)(`[db sql] DDL detected, running \`npm run gen:db-schema\` in ${projectRoot}`);
     try {
         await new Promise((resolve) => {
-            const proc = (0, node_child_process_1.spawn)('npm', ['run', 'gen:db-schema'], {
+            const proc = (0, run_npm_1.spawnNpm)(['run', 'gen:db-schema'], {
                 stdio: ['ignore', 'pipe', 'pipe'],
                 cwd: projectRoot,
             });
             // --verbose：实时透传到 stderr 看进度；默认完全静默丢弃。
             // 任何路径下子进程输出都不会进入当前 CLI 的 stdout，--json 模式安全。
             // 注：默认路径必须 attach 监听器，否则 pipe 缓冲区写满会反压子进程。
+            // `?.`：stdio 走数组形式时 node 类型上 stdout/stderr 可为 null。这里 fd1/fd2
+            // 显式给了 'pipe'，实际恒非 null；真为 null 也意味着不是 pipe、不存在缓冲反压。
             if (verbose) {
-                proc.stdout.pipe(process.stderr);
-                proc.stderr.pipe(process.stderr);
+                proc.stdout?.pipe(process.stderr);
+                proc.stderr?.pipe(process.stderr);
             }
             else {
-                proc.stdout.on('data', drainChunk);
-                proc.stderr.on('data', drainChunk);
+                proc.stdout?.on('data', drainChunk);
+                proc.stderr?.on('data', drainChunk);
             }
             let timedOut = false;
             const timer = setTimeout(() => {

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

@@ -34,20 +34,28 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDeploy = handleDeploy;
+exports.writeApprovalNotice = writeApprovalNotice;
 const api = __importStar(require("../../../api/index"));
 const output_1 = require("../../../utils/output");
 const index_1 = require("../../../api/deploy/index");
 const polling_1 = require("./polling");
 const format_1 = require("./format");
+const helpers_1 = require("./helpers");
 /** miaoda deploy [--branch ...] [--wait] [--timeout 300] */
 async function handleDeploy(opts) {
     const appID = opts.appId;
-    const resp = await api.deploy.createRelease({ appID, branch: opts.branch });
+    if (opts.applyReason !== undefined)
+        (0, helpers_1.validateApplyReason)(opts.applyReason);
+    const resp = await api.deploy.createRelease({
+        appID,
+        branch: opts.branch,
+        ...(opts.applyReason !== undefined && { applyReason: opts.applyReason }),
+    });
     const pipelineTaskID = resp.pipelineTaskID ?? '';
     if (!opts.wait) {
         if (!(0, output_1.isJsonMode)()) {
             process.stdout.write(`✓ Deployment triggered. (deploy-id: ${pipelineTaskID})\n`);
-            process.stdout.write(`  hint: No terminal status yet. Poll every 2s with \`miaoda deploy get ${pipelineTaskID} --json\`; if no deploy-id is visible, first get it from \`miaoda deploy history --limit 1 --json\`.\n`);
+            process.stdout.write(`  hint: No terminal status yet. Poll every 2s with \`miaoda deploy get ${pipelineTaskID} --json\`; if no deploy-id is visible, first get it from \`miaoda deploy history --limit 1 --json\`. Stop polling when status is pending (awaiting approval) and hand it to the user.\n`);
         }
         (0, output_1.emit)({
             data: { pipelineTaskID },
@@ -64,7 +72,8 @@ async function handleDeploy(opts) {
         pipelineTaskID,
         timeoutSec: opts.timeout ?? 300,
     });
-    if (!(0, output_1.isJsonMode)()) {
+    const approval = (0, index_1.findApproval)(detail);
+    if (!(0, output_1.isJsonMode)() && !writeApprovalNotice(detail.status, approval, pipelineTaskID)) {
         if (detail.status === index_1.NodeStatus.SUCCESS) {
             process.stdout.write('✓ 发布成功\n');
         }
@@ -77,8 +86,52 @@ async function handleDeploy(opts) {
         }
     }
     (0, output_1.emit)({
-        data: { pipelineTaskID, detail: (0, format_1.formatPipelineInstance)(detail) },
+        data: { pipelineTaskID, ...(approval && { approval }), detail: (0, format_1.formatPipelineInstance)(detail) },
         next_cursor: null,
         has_more: false,
     });
 }
+/** 控制字符与不可见的 Unicode 格式字符替换成空格，防止服务端字段改写终端输出 */
+function toDisplay(text) {
+    return text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, ' ').trim();
+}
+function writeReason(approval) {
+    const message = approval?.message;
+    if (typeof message === 'string' && message !== '') {
+        process.stdout.write(`  原因：${toDisplay(message)}\n`);
+    }
+}
+/** 卡点异常：平台没把审批发出去，没有任何一方做过裁决，不是代码问题 */
+function writeApprovalGateFailed(approval) {
+    process.stdout.write('✗ 发布卡点异常：审批未能发起，不是代码问题，请稍后重试或联系平台\n');
+    writeReason(approval);
+}
+function writeRejected(approval) {
+    process.stdout.write('✗ 发布审批未通过，本次未上线\n');
+    writeReason(approval);
+}
+/**
+ * 审批相关状态的 pretty 提示：审批中 / 审批被拒 / 卡点异常。
+ * 不属于这三类时不输出并返回 false，由调用方按普通状态处理。
+ */
+function writeApprovalNotice(status, approval, pipelineTaskID) {
+    if (status === index_1.NodeStatus.PENDING) {
+        writeApprovalHint(approval, pipelineTaskID);
+    }
+    else if (status === index_1.NodeStatus.REJECTED) {
+        writeRejected(approval);
+    }
+    else if (status === index_1.NodeStatus.FAILED && approval?.status === 'failed') {
+        writeApprovalGateFailed(approval);
+    }
+    else {
+        return false;
+    }
+    return true;
+}
+function writeApprovalHint(approval, pipelineTaskID) {
+    const url = (0, index_1.approvalURL)(approval);
+    process.stdout.write('⏸ 发布已进入人工审批，等待审批负责人处理\n');
+    process.stdout.write(url ? `  审批链接：${toDisplay(url)}\n` : '  服务端未返回审批链接\n');
+    process.stdout.write(`  hint: 审批处理完成后运行 \`miaoda deploy get ${pipelineTaskID}\` 查询本次发布结果，不要重新发起发布\n`);
+}

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

@@ -29,6 +29,7 @@ function formatPipelineInstance(detail) {
             jobs: stage.jobs.map((group) => group.map((job) => ({
                 ...job,
                 ...formatStatusMetadata(job.status),
+                ...formatJobApproval(job),
                 steps: job.steps?.map((step) => ({
                     ...step,
                     ...formatStatusMetadata(step.status),
@@ -37,3 +38,15 @@ function formatPipelineInstance(detail) {
         })),
     };
 }
+/** Job 上的卡点信息同样翻译 status，与 data.approval 的表示保持一致 */
+function formatJobApproval(job) {
+    if (!job.approval)
+        return {};
+    return {
+        approval: {
+            ...job.approval,
+            status: (0, index_1.approvalStatusText)(job.approval.status),
+            status_code: job.approval.status,
+        },
+    };
+}

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

@@ -41,16 +41,28 @@ const error_1 = require("../../../utils/error");
 const index_1 = require("../../../api/deploy/index");
 const helpers_1 = require("./helpers");
 const format_1 = require("./format");
+const polling_1 = require("./polling");
+const deploy_1 = require("./deploy");
 /**
  * 单页拉取上限：BAM listPipelineInstances 限制 1~500，取 500 让 deploy get
  * 在最近 500 条记录里按 ID 命中。
  */
 const DEPLOY_GET_LOOKUP_LIMIT = 500;
+/**
+ * 可能挂着审批单的状态：审批中、审批被拒，以及卡点异常（平台没能发起审批，顶层表现为 FAILED）。
+ * 只有这些状态才额外查详情取审批单，其余状态保持单次列表请求。
+ */
+const APPROVAL_LOOKUP_STATUSES = [
+    index_1.NodeStatus.PENDING,
+    index_1.NodeStatus.REJECTED,
+    index_1.NodeStatus.FAILED,
+];
 /**
  * miaoda deploy get <deploy-id>
  *
  * BAM 没有 by-ID 的查询接口，复用 listPipelineInstances 在最近窗口里按 ID 筛一条。
  * 命中失败时抛 DEPLOY_NOT_FOUND，提示用户用 history 查窗口。
+ * status 为 pending / rejected / failed 时额外查详情，有审批单则输出 approval（审批链接、拒绝原因等）。
  */
 async function handleDeployGet(opts) {
     if (!opts.deployId)
@@ -67,5 +79,16 @@ async function handleDeployGet(opts) {
             next_actions: ['运行 `miaoda deploy history` 确认 deploy-id 是否在最近窗口内'],
         });
     }
-    (0, output_1.emit)({ data: (0, format_1.formatSimpleInstance)(instance), next_cursor: null, has_more: false }, index_1.deployGetSchema);
+    // 列表项不含审批信息：按同一个 ID 查详情接口（默认返回审批视图）取审批单。
+    // 详情失败直接抛错，不降级为只输出列表数据，避免丢掉审批链接 / 拒绝原因却无人察觉。
+    const approval = APPROVAL_LOOKUP_STATUSES.includes(instance.status)
+        ? (0, index_1.findApproval)((0, polling_1.normalizePipelineInstance)(await api.deploy.queryPipelineInstance({ appID, instanceID: opts.deployId })))
+        : undefined;
+    (0, output_1.emit)({
+        data: { ...(0, format_1.formatSimpleInstance)(instance), ...(approval && { approval }) },
+        next_cursor: null,
+        has_more: false,
+    }, index_1.deployGetSchema);
+    if (!(0, output_1.isJsonMode)())
+        (0, deploy_1.writeApprovalNotice)(instance.status, approval, opts.deployId);
 }