@lark-apaas/miaoda-cli 0.1.5 → 0.1.6

package/dist/services/deploy/modern/check.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeployChecks = runDeployChecks;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const error_1 = require("../../../utils/error");
+/**
+ * 项目级 deploy 前置检查：node_modules / .spark/meta.json / package.json.scripts.build。
+ * 任一 error 级别失败抛 AppError，附错误码 DEPLOY_PROJECT_CHECK_FAILED。
+ */
+function runDeployChecks(projectDir) {
+    const issues = [];
+    const nodeModules = node_path_1.default.join(projectDir, 'node_modules');
+    if (!node_fs_1.default.existsSync(nodeModules)) {
+        issues.push('node_modules not found. Run `npm install` (or equivalent) first.');
+    }
+    const metaPath = node_path_1.default.join(projectDir, '.spark', 'meta.json');
+    if (!node_fs_1.default.existsSync(metaPath)) {
+        issues.push('.spark/meta.json not found. Run `miaoda app init` first.');
+    }
+    else {
+        try {
+            const meta = JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf-8'));
+            if (!meta.stack) {
+                issues.push('.spark/meta.json missing fields: stack');
+            }
+        }
+        catch {
+            issues.push('.spark/meta.json is not valid JSON.');
+        }
+    }
+    const pkgPath = node_path_1.default.join(projectDir, 'package.json');
+    if (!node_fs_1.default.existsSync(pkgPath)) {
+        issues.push('package.json not found.');
+    }
+    else {
+        try {
+            const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
+            if (!pkg.scripts?.build) {
+                issues.push('package.json missing "build" script.');
+            }
+        }
+        catch {
+            issues.push('package.json is not valid JSON.');
+        }
+    }
+    if (issues.length > 0) {
+        throw new error_1.AppError('DEPLOY_PROJECT_CHECK_FAILED', `Project check failed:\n${issues.map((i) => `  - ${i}`).join('\n')}`);
+    }
+}

package/dist/services/deploy/modern/constants.js

@@ -0,0 +1,13 @@
+"use strict";
+// modern deploy 流程使用的目录常量。
+// （旧版的 STACK_CONFIGS / archType / FaaS 相关常量在新接口契约下不再需要——
+//  发布模板差异完全由后端 preRelease.data 下发，CLI 不维护 stack 配置。）
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTPUT_CAPABILITIES_DIR = exports.OUTPUT_STATIC_DIR = exports.OUTPUT_RESOURCE_DIR = exports.OUTPUT_DIR = exports.DIST_DIR = void 0;
+/** 构建产物固定目录约定 */
+exports.DIST_DIR = 'dist';
+exports.OUTPUT_DIR = 'output';
+exports.OUTPUT_RESOURCE_DIR = 'output_resource';
+exports.OUTPUT_STATIC_DIR = 'output_static';
+/** 发布插件能力声明目录：含若干 capability.json 文件，发布时批量注册到 plugin_instances */
+exports.OUTPUT_CAPABILITIES_DIR = 'output_capabilities';

package/dist/services/deploy/modern/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTPUT_STATIC_DIR = exports.OUTPUT_RESOURCE_DIR = exports.OUTPUT_DIR = exports.DIST_DIR = exports.optionalDataKey = exports.requireDataKey = exports.DataKey = exports.runDeployChecks = exports.runModernDeploy = void 0;
+var run_1 = require("./run");
+Object.defineProperty(exports, "runModernDeploy", { enumerable: true, get: function () { return run_1.runModernDeploy; } });
+var check_1 = require("./check");
+Object.defineProperty(exports, "runDeployChecks", { enumerable: true, get: function () { return check_1.runDeployChecks; } });
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "DataKey", { enumerable: true, get: function () { return protocol_1.DataKey; } });
+Object.defineProperty(exports, "requireDataKey", { enumerable: true, get: function () { return protocol_1.requireDataKey; } });
+Object.defineProperty(exports, "optionalDataKey", { enumerable: true, get: function () { return protocol_1.optionalDataKey; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "DIST_DIR", { enumerable: true, get: function () { return constants_1.DIST_DIR; } });
+Object.defineProperty(exports, "OUTPUT_DIR", { enumerable: true, get: function () { return constants_1.OUTPUT_DIR; } });
+Object.defineProperty(exports, "OUTPUT_RESOURCE_DIR", { enumerable: true, get: function () { return constants_1.OUTPUT_RESOURCE_DIR; } });
+Object.defineProperty(exports, "OUTPUT_STATIC_DIR", { enumerable: true, get: function () { return constants_1.OUTPUT_STATIC_DIR; } });

package/dist/services/deploy/modern/pipelines/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localBuildLocalPublishPipeline = void 0;
+var local_1 = require("./local");
+Object.defineProperty(exports, "localBuildLocalPublishPipeline", { enumerable: true, get: function () { return local_1.localBuildLocalPublishPipeline; } });

package/dist/services/deploy/modern/pipelines/local.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localBuildLocalPublishPipeline = localBuildLocalPublishPipeline;
+const spark_meta_1 = require("../../../../utils/spark-meta");
+const error_1 = require("../../../../utils/error");
+const logger_1 = require("../../../../utils/logger");
+const index_1 = require("../atoms/index");
+/**
+ * 本地构建 + 本地部署 pipeline。
+ *
+ * 步骤顺序：
+ *   1. prepareDeployContext    — 校验项目 + 读 meta
+ *   2. preRelease              — 签发 pre_release_id / version / 动态配置 data
+ *   3. runBuild                — 本地 npm run build（注入 data 中的 CDN 前缀）
+ *   4. createLocalRelease      — 创建发布单（加锁、拿 releaseID）
+ *   5. uploadArtifacts         — 把产物推到 preRelease 下发的 pre-signed URL
+ *   6. savePluginInstances     — 扫描 dist/output_capabilities/*.json，批量注册插件能力
+ *   7. finalizeLocalRelease    — Finished / Failed 翻终态
+ *
+ * createLocalRelease 提前到 upload 之前：发布单先建出来，
+ * upload / savePluginInstances 在已知 releaseID 的前提下进行；
+ * 任一步失败都会精准把该发布单标记为 Failed，避免遗留挂态。
+ */
+async function localBuildLocalPublishPipeline(opts) {
+    const ctx = (0, index_1.prepareDeployContext)(opts.projectDir, opts.appId);
+    (0, logger_1.log)('deploy', 'Pre-releasing...');
+    const pre = await (0, index_1.preRelease)(ctx.appId, ctx.templateKey);
+    (0, logger_1.log)('deploy', `pre_release_id=${pre.preReleaseID} version=${pre.version}`);
+    // data 文档标注为选填，但本地构建链路所有 atom 都需要其中的 key；
+    // 此处早期检查，把"data 缺失"翻为明确错误码，比让 requireDataKey 在
+    // 各 atom 里散落抛错好排查。
+    if (pre.data === undefined) {
+        throw new error_1.AppError('DEPLOY_PRE_RELEASE_DATA_MISSING', 'preRelease did not return a `data` map — backend tcc may not be configured for current template_key');
+    }
+    const data = pre.data;
+    if (!opts.skipBuild) {
+        (0, index_1.runBuild)({
+            projectDir: ctx.projectDir,
+            appId: ctx.appId,
+            version: pre.version,
+            templateKey: ctx.templateKey,
+            data,
+        });
+    }
+    (0, logger_1.log)('deploy', 'Creating local release...');
+    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version);
+    try {
+        (0, logger_1.log)('deploy', 'Uploading artifacts...');
+        await (0, index_1.uploadArtifacts)({ projectDir: ctx.projectDir, appId: ctx.appId, data });
+        const saveResult = await (0, index_1.savePluginInstances)({
+            projectDir: ctx.projectDir,
+            appId: ctx.appId,
+            version: pre.version,
+        });
+        if (saveResult.saved > 0) {
+            (0, logger_1.log)('deploy', `${String(saveResult.saved)} capability instance(s) registered`);
+        }
+        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
+    }
+    catch (err) {
+        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
+        throw err;
+    }
+    if (release.onlineUrl !== undefined && release.onlineUrl !== '') {
+        (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { appUrl: release.onlineUrl });
+    }
+    (0, logger_1.log)('deploy', 'Deployed successfully');
+    return {
+        appId: ctx.appId,
+        version: pre.version,
+        url: release.onlineUrl ?? '',
+        releaseID: release.releaseID,
+        preReleaseID: pre.preReleaseID,
+    };
+}

package/dist/services/deploy/modern/protocol.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataKey = void 0;
+exports.requireDataKey = requireDataKey;
+exports.optionalDataKey = optionalDataKey;
+exports.parseTosUploadCredential = parseTosUploadCredential;
+exports.parsePaasStorageCredential = parsePaasStorageCredential;
+exports.parseTosUploadPrefix = parseTosUploadPrefix;
+const error_1 = require("../../../utils/error");
+/**
+ * modern deploy 对外协议常量集中地（SSOT）。
+ *
+ * preRelease 接口返回 `data` 动态配置 map，其 key 由后端按 template_key 在 tcc
+ * 中下发。CLI 端通过本文件枚举的 DataKey 访问 `data`，避免拼写错误散布，
+ * 同时让协议演进（新增 key / 重命名）只需要改这一个文件。
+ */
+exports.DataKey = {
+    // ── CDN 前缀（构建期注入到 build env，用于客户端资源访问） ──
+    /** dist/output_resource 对应的 CDN 域名前缀 */
+    RESOURCE_CDN_PREFIX: 'resource_cdn_prefix',
+    // ── TOS 上传凭证（output / output_resource 两条线，value 为 JSON.stringify 的凭证对象） ──
+    // 凭证对象形态（camelCase）：
+    //   { accessKeyID, secretAccessKey, sessionToken, endpoint, region, bucket, prefix }
+    // CLI 端 JSON.parse 后写 tosutil 临时 config，cp 到 tos://bucket/prefix。
+    /** dist/output 上传凭证（必传） */
+    OUTPUT_TOS_UPLOAD_CREDENTIAL: 'output_tos_upload_credential',
+    /** dist/output_resource 上传凭证（仅当目录存在时使用） */
+    OUTPUT_RESOURCE_TOS_UPLOAD_CREDENTIAL: 'output_resource_tos_upload_credential',
+    // ── PaaS Storage 静态资源凭证（dist/output_static 专用） ──
+    // 形态：JSON.stringify 后的 PaasStorageCredential（见下方 interface）。
+    // 上传走 tosutil（从 uploadPrefix 解析出 bucket/prefix）；上传完成后再调
+    // callbackStatic(appID, bucketID, uploadID) 把本次上传核销给后端；
+    // downloadURLPrefix 替代原 static_cdn_prefix 注入 build env。
+    /** dist/output_static 上传凭证（仅当目录存在时使用） */
+    OUTPUT_STATIC_PAAS_STORAGE_CREDENTIAL: 'output_static_paas_storage_credential',
+};
+/** 取必传 key，缺失抛 AppError（带 key 名，便于后端 tcc 配置排查） */
+function requireDataKey(data, key) {
+    const v = data[key];
+    if (v === undefined || v === '') {
+        throw new error_1.AppError('DEPLOY_DATA_KEY_MISSING', `preRelease.data missing required key "${key}" — backend tcc may not be configured for the current template_key`);
+    }
+    return v;
+}
+/** 取可选 key，缺失返回 undefined（不抛错） */
+function optionalDataKey(data, key) {
+    const v = data[key];
+    return v === undefined || v === '' ? undefined : v;
+}
+const TOS_CREDENTIAL_REQUIRED_FIELDS = [
+    'accessKeyID',
+    'secretAccessKey',
+    'sessionToken',
+    'endpoint',
+    'region',
+    'bucket',
+    'prefix',
+];
+const PAAS_STORAGE_CREDENTIAL_REQUIRED_FIELDS = [
+    'accessKeyID',
+    'secretAccessKey',
+    'sessionToken',
+    'endpoint',
+    'region',
+    'uploadPrefix',
+    'downloadURLPrefix',
+    'uploadID',
+    'bucketID',
+];
+function parseCredentialObject(raw, dataKey) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new error_1.AppError('DEPLOY_CRED_INVALID_JSON', `preRelease.data["${dataKey}"] is not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new error_1.AppError('DEPLOY_CRED_INVALID_JSON', `preRelease.data["${dataKey}"] is not an object`);
+    }
+    return parsed;
+}
+function assertStringFields(obj, required, dataKey) {
+    const missing = required.filter((k) => {
+        const v = obj[k];
+        return typeof v !== 'string' || v === '';
+    });
+    if (missing.length > 0) {
+        throw new error_1.AppError('DEPLOY_CRED_INCOMPLETE', `preRelease.data["${dataKey}"] credential missing fields: ${missing.join(', ')}`);
+    }
+    return obj;
+}
+/** JSON.parse + 字段完整性校验：output / output_resource 凭证 */
+function parseTosUploadCredential(raw, dataKey) {
+    const obj = parseCredentialObject(raw, dataKey);
+    return assertStringFields(obj, TOS_CREDENTIAL_REQUIRED_FIELDS, dataKey);
+}
+/** JSON.parse + 字段完整性校验：output_static PaaS Storage 凭证 */
+function parsePaasStorageCredential(raw, dataKey) {
+    const obj = parseCredentialObject(raw, dataKey);
+    return assertStringFields(obj, PAAS_STORAGE_CREDENTIAL_REQUIRED_FIELDS, dataKey);
+}
+/**
+ * 解析 `tos://<storage-bucket>/<segments...>/` 形态的 uploadPrefix。
+ * 返回的 bucket 是 tosutil cp 视角的 TOS 物理 bucket（uploadPrefix 第一段），
+ * prefix 是其余路径（不含开头斜杠，保留可能存在的尾部斜杠以贴合 tosutil 习惯）。
+ *
+ * 注意：这里返回的 bucket 与 PaasStorageCredential.bucketID 不是同一个概念
+ * （bucketID 是 PaaS Storage 逻辑 bucket，给 callbackStatic 用）。
+ */
+function parseTosUploadPrefix(uploadPrefix, dataKey) {
+    const match = /^tos:\/\/([^/]+)\/(.*)$/.exec(uploadPrefix);
+    if (!match) {
+        throw new error_1.AppError('DEPLOY_CRED_INCOMPLETE', `preRelease.data["${dataKey}"].uploadPrefix must look like "tos://<bucket>/<prefix>/", got: ${uploadPrefix}`);
+    }
+    const bucket = match[1];
+    const prefix = match[2];
+    if (bucket === '' || prefix === '') {
+        throw new error_1.AppError('DEPLOY_CRED_INCOMPLETE', `preRelease.data["${dataKey}"].uploadPrefix missing bucket or prefix segment: ${uploadPrefix}`);
+    }
+    return { bucket, prefix };
+}

package/dist/services/deploy/modern/run-types.js

@@ -0,0 +1,4 @@
+"use strict";
+// modern deploy 主入口与 pipeline 共享的输入 / 输出类型。
+// 抽出来避免 run.ts <-> pipelines/* 之间的循环依赖。
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/deploy/modern/run.js

@@ -0,0 +1,13 @@
+"use strict";
+// modern deploy 主入口（dispatch 层）。
+//
+// 当前阶段（Scope A）只接入"本地构建 + 本地部署"一条 pipeline；
+// 后续接入"本地构建 + 远端部署 / 远端构建 + 远端部署"时，在此处按 template_key
+// 或显式 flag 选不同 pipeline。pipeline 之间彼此独立、不共享中间状态。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runModernDeploy = runModernDeploy;
+const index_1 = require("./pipelines/index");
+async function runModernDeploy(opts) {
+    // 暂只支持本地构建 + 本地部署
+    return (0, index_1.localBuildLocalPublishPipeline)(opts);
+}

package/dist/services/deploy/modern/template-key-map.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTemplateKey = resolveTemplateKey;
+/**
+ * 本地 stack 短名 → 后端发布模板 key 的映射。
+ *
+ * .spark/meta.json.stack 存的是脚手架模板短名（vite-react / html ...），
+ * 而服务端 preRelease 接受的 templateKey 是"部署类别"维度，由后端 tcc 注册。
+ * 当前所有支持的 stack 都属于纯前端类别，默认映射到 client_local_deploy；
+ * 未来出现需要走别的 templateKey 的 stack，再在表里加一行覆盖默认。
+ */
+const DEFAULT_TEMPLATE_KEY = 'client_local_deploy';
+const TEMPLATE_KEY_MAP = {
+    'vite-react': DEFAULT_TEMPLATE_KEY,
+    html: DEFAULT_TEMPLATE_KEY,
+};
+/**
+ * 把本地 stack 短名映射到后端 templateKey；未配置的 stack 走默认 client_local_deploy。
+ */
+function resolveTemplateKey(template) {
+    return TEMPLATE_KEY_MAP[template] ?? DEFAULT_TEMPLATE_KEY;
+}

package/dist/services/skills/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSkillsStatus = void 0;
+var status_1 = require("./status");
+Object.defineProperty(exports, "readSkillsStatus", { enumerable: true, get: function () { return status_1.readSkillsStatus; } });

package/dist/services/skills/status.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSkillsStatus = readSkillsStatus;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 扫描 <targetDir>/.agent/skills/steering/<stack>/，给出"当前装了什么"的快照。
+ * 不联网、不解析任何 SKILL.md 内容；只列目录名 + tech.md 是否在。
+ *
+ * stack 缺省（meta.json 缺 stack）时直接返回 present=false，
+ * 让 handler 把"先 init"的引导留给用户。
+ */
+function readSkillsStatus(opts) {
+    if (opts.stack === undefined || opts.stack === '') {
+        return { present: false, skills: [], techSynced: false };
+    }
+    const root = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack);
+    if (!node_fs_1.default.existsSync(root)) {
+        return { present: false, skills: [], techSynced: false };
+    }
+    const skillsDir = node_path_1.default.join(root, 'skills');
+    const skills = node_fs_1.default.existsSync(skillsDir)
+        ? node_fs_1.default
+            .readdirSync(skillsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort()
+        : [];
+    return {
+        present: true,
+        skills,
+        techSynced: node_fs_1.default.existsSync(node_path_1.default.join(root, 'tech.md')),
+    };
+}

package/dist/utils/coding-steering.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncCodingSteering = syncCodingSteering;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const npm_pack_1 = require("../utils/npm-pack");
+const logger_1 = require("../utils/logger");
+const STEERING_PACKAGE = '@lark-apaas/coding-steering';
+/**
+ * 把 coding-steering 包内 _common/skills + <stack>/skills 同步到 <targetDir>/.agent/steering/skills/，
+ * 同名 stack 子目录覆盖 _common。tech.md 存在时也同步到 .agent/steering/tech.md。
+ *
+ * 纯本地 atom（pull npm package + 拷贝文件），不属于任何 cli 域；放在 utils 让
+ * app init handler 与独立 skills sync handler 都能复用。
+ */
+function syncCodingSteering(opts) {
+    const logPrefix = opts.logPrefix ?? 'skills';
+    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${opts.version ?? 'latest'}...`);
+    const fetched = (0, npm_pack_1.fetchNpmPackage)({
+        packageName: STEERING_PACKAGE,
+        version: opts.version,
+    });
+    try {
+        const steeringRoot = node_path_1.default.join(fetched.extractDir, 'steering');
+        const stackDir = node_path_1.default.join(steeringRoot, opts.stack);
+        const commonSkillsDir = node_path_1.default.join(steeringRoot, '_common', 'skills');
+        // steering 落到 .agent/skills/steering/<stack>/。.agent/skills/ 是 agent skills 的
+        // 公共容器，steering 是其中一个 producer，<stack> 再做命名空间隔离。内部仍保留
+        // 包内 steering/<stack>/skills/ 的结构，便于按"包内子目录 → 本地子目录"一一对应排查。
+        const dstRoot = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack);
+        const dstSkillsDir = node_path_1.default.join(dstRoot, 'skills');
+        node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
+        let techSynced = false;
+        const techSrc = node_path_1.default.join(stackDir, 'tech.md');
+        if (node_fs_1.default.existsSync(techSrc)) {
+            node_fs_1.default.copyFileSync(techSrc, node_path_1.default.join(dstRoot, 'tech.md'));
+            techSynced = true;
+        }
+        const synced = [];
+        // 先拷 _common/skills/，再拷 <stack>/skills/。stack 同名覆盖 common
+        if (node_fs_1.default.existsSync(commonSkillsDir)) {
+            for (const name of node_fs_1.default.readdirSync(commonSkillsDir)) {
+                const src = node_path_1.default.join(commonSkillsDir, name);
+                if (!node_fs_1.default.statSync(src).isDirectory())
+                    continue;
+                copyDir(src, node_path_1.default.join(dstSkillsDir, name));
+                synced.push(`_common/skills/${name}`);
+            }
+        }
+        const stackSkillsDir = node_path_1.default.join(stackDir, 'skills');
+        if (node_fs_1.default.existsSync(stackSkillsDir)) {
+            for (const name of node_fs_1.default.readdirSync(stackSkillsDir)) {
+                const src = node_path_1.default.join(stackSkillsDir, name);
+                if (!node_fs_1.default.statSync(src).isDirectory())
+                    continue;
+                const dst = node_path_1.default.join(dstSkillsDir, name);
+                if (node_fs_1.default.existsSync(dst))
+                    node_fs_1.default.rmSync(dst, { recursive: true, force: true });
+                copyDir(src, dst);
+                synced.push(`${opts.stack}/skills/${name}`);
+            }
+        }
+        (0, logger_1.log)(logPrefix, `Synced ${String(synced.length)} skill(s), tech.md ${techSynced ? 'yes' : 'no'}`);
+        return { version: fetched.version, syncedSkills: synced, techSynced };
+    }
+    finally {
+        fetched.cleanup();
+    }
+}
+function copyDir(src, dest) {
+    node_fs_1.default.mkdirSync(dest, { recursive: true });
+    for (const entry of node_fs_1.default.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = node_path_1.default.join(src, entry.name);
+        const destPath = node_path_1.default.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            node_fs_1.default.copyFileSync(srcPath, destPath);
+        }
+    }
+}

package/dist/utils/http.js

@@ -60,13 +60,27 @@ function createClient(opts) {
     instance.interceptors.request.use(applyCanaryHeader);
     return instance;
 }
-/** 若 MIAODA_CANARY_HEADER 已设置，注入 x-tt-env 小流量头 */
+/**
+ * 默认灰度泳道。当前 miaoda CLI 接入的新接口（modern deploy 等）只在该泳道生效，
+ * 缺省走这个。MIAODA_CANARY_HEADER 可显式覆盖；设为空字符串则去掉头。
+ */
+const DEFAULT_CANARY_HEADER = 'boe_miaoda_doubao';
+/**
+ * 注入 x-tt-env 小流量头：env 显式设值 > DEFAULT_CANARY_HEADER。
+ *
+ * 当泳道形如 `ppe_xxx`（PPE 预发环境）时，额外加 `x-use-ppe: 1`；
+ * BOE 泳道（`boe_xxx`）只带 x-tt-env，不加该头。
+ */
 function applyCanaryHeader(reqConfig) {
-    const canary = process.env.MIAODA_CANARY_HEADER;
+    // env 显式设为空字符串视为"去掉灰度头"；未设置时用 DEFAULT_CANARY_HEADER
+    const canary = process.env.MIAODA_CANARY_HEADER ?? DEFAULT_CANARY_HEADER;
     if (!canary)
         return reqConfig;
     const headers = new Headers(reqConfig.headers);
     headers.set('x-tt-env', canary);
+    if (canary.startsWith('ppe_')) {
+        headers.set('x-use-ppe', '1');
+    }
     reqConfig.headers = headers;
     return reqConfig;
 }
@@ -103,14 +117,14 @@ async function handleInnerEnvelope(response, url, opts) {
         throw new error_1.HttpError(response.status, url, `${opts.errPrefix}: ${String(response.status)} ${response.statusText}`);
     }
     const result = await response.json();
+    // verbose: 把完整响应体打到 stderr，便于排查（业务错误 / 字段缺失等）
+    if ((0, config_1.getConfig)().verbose) {
+        (0, logger_1.debug)(`  resp: ${truncateForLog(safeStringify(result), 2000)}`);
+    }
     if (typeof result === 'object' && result !== null && 'status_code' in result) {
         const env = result;
         if (env.status_code !== undefined && env.status_code !== '0') {
             const msg = env.message ?? env.error_msg ?? 'unknown error';
-            // verbose: 把完整业务错误信封打到 stderr，便于追溯
-            if ((0, config_1.getConfig)().verbose) {
-                (0, logger_1.debug)(`  envelope: ${truncateForLog(safeStringify(env), 1000)}`);
-            }
             const mapped = opts.mapErr?.(env.status_code, msg);
             if (mapped)
                 throw mapped;
@@ -163,12 +177,8 @@ function logResponseFailure(method, url, err, startMs) {
     const msgPart = e.message ? ` (${e.message})` : '';
     (0, logger_1.debug)(`✗ ${method} ${url} ${statusPart} ${String(elapsedMs)}ms${logidPart}${msgPart}`);
 }
-/** BAM gateway 在不同 PSM/版本上 logid 落在不同 header；按命中顺序取第一个非空。 */
 function pickLogid(headers) {
-    return (headers.get('x-tt-logid') ??
-        headers.get('x-logid') ??
-        headers.get('logid') ??
-        headers.get('x-tt-trace-tag'));
+    return headers.get('x-tt-logid');
 }
 function safeStringify(v) {
     try {

package/dist/utils/npm-pack.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchNpmPackage = fetchNpmPackage;
+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 error_1 = require("./error");
+const logger_1 = require("./logger");
+const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/';
+/**
+ * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
+ * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。
+ */
+function fetchNpmPackage(opts) {
+    const registry = opts.registry ?? process.env.MIAODA_NPM_REGISTRY ?? DEFAULT_REGISTRY;
+    const version = opts.version ?? 'latest';
+    const pkgSpec = `${opts.packageName}@${version}`;
+    const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-pack-'));
+    try {
+        (0, logger_1.debug)(`npm pack ${pkgSpec} --registry ${registry} → ${tmpDir}`);
+        const stdout = (0, node_child_process_1.execFileSync)('npm', ['pack', pkgSpec, '--pack-destination', tmpDir, '--json', '--registry', registry], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const packInfo = JSON.parse(stdout);
+        const tgzFilename = packInfo[0]?.filename;
+        const pkgVersion = packInfo[0]?.version ?? version;
+        if (!tgzFilename) {
+            throw new error_1.AppError('NPM_PACK_FAILED', `npm pack 未返回 filename：${pkgSpec}`);
+        }
+        const tgzPath = node_path_1.default.join(tmpDir, tgzFilename);
+        const extractDir = node_path_1.default.join(tmpDir, 'extracted');
+        node_fs_1.default.mkdirSync(extractDir, { recursive: true });
+        (0, node_child_process_1.execFileSync)('tar', ['-xzf', tgzPath, '-C', extractDir], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return {
+            extractDir: node_path_1.default.join(extractDir, 'package'),
+            version: pkgVersion,
+            cleanup: () => {
+                node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        if (err instanceof error_1.AppError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new error_1.AppError('NPM_PACK_FAILED', `抓取 npm 包失败 (${pkgSpec}): ${msg}`, {
+            next_actions: [`确认包已发布到 registry：${registry}`, `检查版本号 / dist-tag 拼写`],
+        });
+    }
+}

package/dist/utils/spark-meta.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSparkMeta = readSparkMeta;
+exports.writeSparkMeta = writeSparkMeta;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SPARK_DIR = '.spark';
+const SPARK_META_FILE = 'meta.json';
+function readSparkMeta(appDir) {
+    const metaPath = node_path_1.default.join(appDir, SPARK_DIR, SPARK_META_FILE);
+    if (!node_fs_1.default.existsSync(metaPath))
+        return {};
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * merge 写入：已有字段保留，undefined 不覆盖；不再维护时间戳。
+ */
+function writeSparkMeta(appDir, meta) {
+    const sparkDir = node_path_1.default.join(appDir, SPARK_DIR);
+    node_fs_1.default.mkdirSync(sparkDir, { recursive: true });
+    const metaPath = node_path_1.default.join(sparkDir, SPARK_META_FILE);
+    let existing = {};
+    if (node_fs_1.default.existsSync(metaPath)) {
+        try {
+            existing = JSON.parse(node_fs_1.default.readFileSync(metaPath, 'utf-8'));
+        }
+        catch {
+            /* 读不出就当空 */
+        }
+    }
+    const defined = Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined));
+    const merged = { ...existing, ...defined };
+    node_fs_1.default.writeFileSync(metaPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {