@lark-apaas/miaoda-cli 0.1.19-alpha.4bf5458 → 0.1.19-alpha.6dad9cd

package/dist/cli/commands/index.js

@@ -9,6 +9,7 @@ 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");
+const index_7 = require("../../cli/commands/registry/index");
 // scene 跟 dispatcher(MIAODA_APP_TYPE)同语义层级 —— app 业务类型维度,
 // 对齐后端 devops app_common.AppType 枚举:
 //   3 = AppType_APPLICATION(全栈应用,当前仅 nestjs-react-fullstack 一个 stack)
@@ -67,10 +68,12 @@ const SCENE_REGISTRARS = {
     },
     // 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 专属)。
     'design-html': (p) => {
         (0, index_4.registerAppCommands)(p, { includeInit: true });
         (0, modern_1.registerDeployCommandsModern)(p);
         (0, index_6.registerSkillsCommands)(p);
+        (0, index_7.registerRegistryCommands)(p);
     },
 };
 function readEnv(name) {

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

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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）。
+ *
+ * registry 是独立 npm 包，按 runtime 命名分发（buildless runtime → @lark-apaas/coding-registry-buildless）。
+ * SDK 文件按目录组织**平铺在包根**（scripts/ · components/ · stylesheets/），每个文件以 USAGE 注释块
+ * 开头（声明描述 / 用法 / Depends）。CLI 抓 tarball、按 .spark/meta.json.stack → runtime → 包名 选包，
+ * 把 SDK 文件**保留相对包根的路径** copy-in 到用户项目根。
+ * 不写安装记账文件——项目文件树即状态（skip-by-disk）。
+ */
+function registerRegistryCommands(program) {
+    const registryCmd = program
+        .command('registry')
+        .description('组件 registry：列出 / copy-in design-html SDK 文件')
+        .usage('<command> [flags]');
+    registryCmd.action(() => {
+        registryCmd.outputHelp();
+    });
+    registryCmd.addHelpText('after', `
+概念
+  - registry 包：独立 npm 包（按 runtime 命名），SDK 文件平铺在包根（如 scripts/deck-stage.js）
+  - 条目 (entry)：name = 文件名去扩展名（全树唯一）；每个文件以 USAGE 注释块开头
+  - USAGE 块：声明描述 / Exports / Usage / Depends（可选，依赖其他 SDK 的 name）
+  - Depends：从 USAGE 块解析的跨条目依赖，add 时传递解析、一并 copy-in
+  - add 落地：保留文件相对包根的路径（包根 scripts/x.js → 项目 scripts/x.js）
+
+前置
+  当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack=design-html）
+`);
+    registerRegistryList(registryCmd);
+    registerRegistryAdd(registryCmd);
+}
+function registerRegistryList(parent) {
+    const cmd = parent
+        .command('list')
+        .description('列出 registry 可用 SDK 条目，输出各文件的 USAGE 块原文')
+        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
+        .addHelpText('after', `
+输出
+  默认（pretty）：各条目 USAGE 块原文拼接，带文件名分隔，给 Agent 直接读注释
+
+JSON 输出
+  {"data": [{"name": "...", "file": "...", "usage": "<原文>", "dependsOn": [...]}, ...]}
+  （usage 保持 USAGE 块原文，不解析成结构化字段）
+
+示例
+  $ miaoda registry list
+  $ miaoda registry list --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleRegistryList)({
+            dir: rawOpts.dir,
+            version: rawOpts.version,
+        });
+    }));
+}
+function registerRegistryAdd(parent) {
+    const cmd = parent
+        .command('add')
+        .description('把一个或多个 SDK 文件 copy-in 到当前项目（保留目录结构，含 Depends 闭包）')
+        .argument('<name...>', '条目名（文件名去扩展名），可传多个；Depends 会自动传递解析')
+        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
+        .option('--overwrite', '目标文件已存在时覆盖（默认跳过以保护用户改动）', false)
+        .option('--dry-run', '只报告将写 / 将跳哪些文件，不落盘', false)
+        .addHelpText('after', `
+行为
+  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件从包根 <rel> 按相对路径拷到项目根
+    （包根 scripts/deck-stage.js → 项目 scripts/deck-stage.js，1:1 保留路径）
+  - skip-by-disk：目标文件已存在默认跳过；--overwrite 才覆盖
+  - 不写任何安装记账文件（项目文件树即状态）
+
+JSON 输出
+  {"data": {"registryVersion": "...", "requested": [...], "resolved": [...],
+            "added": [...], "skipped": [...], "dryRun": false}}
+  （added / skipped 是项目内相对路径，如 scripts/deck-stage.js）
+
+示例
+  $ miaoda registry add deck-slide
+  $ miaoda registry add deck-slide theme --dry-run
+  $ miaoda registry add deck-slide --overwrite --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (names, rawOpts) => {
+        await (0, index_1.handleRegistryAdd)({
+            names,
+            dir: rawOpts.dir,
+            version: rawOpts.version,
+            overwrite: rawOpts.overwrite,
+            dryRun: rawOpts.dryRun,
+        });
+    }));
+}

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

@@ -69,8 +69,12 @@ async function handleAppInit(opts) {
     const projectName = node_path_1.default.basename(targetDir);
     const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
     // 先建 logs/,防止 user 跑 dev 之前 AI/工具 redirect 到 logs/*.log 因为父目录不存在直接挂
-    // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)
-    (0, logs_dir_1.ensureLogsDir)(targetDir);
+    // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)。
+    // 仅本地开发需要：沙箱环境由平台 supervisor 拉起 dev,无 init 前的 shell redirect 场景,
+    // 不预建 logs/ 以免在沙箱工作区留空目录。
+    if (!(0, env_1.isSandboxEnv)()) {
+        (0, logs_dir_1.ensureLogsDir)(targetDir);
+    }
     // skills 同步软失败：拉不到 coding-steering 包不该阻断 writeSparkMeta /
     // activateGitHooks（之前会让 .spark/meta.json 没写，下次 init 半渲染状态又得重跑全套）。
     // 按运行环境（isSandboxEnv：MIAODA_DEP_CACHE_DIR 非空）分流 outputLayout，不绑 stack:

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

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleRegistryAdd = handleRegistryAdd;
+const node_path_1 = __importDefault(require("node:path"));
+const index_1 = require("../../../services/registry/index");
+const shared_1 = require("./shared");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const logger_1 = require("../../../utils/logger");
+/**
+ * miaoda registry add <name...> [--overwrite] [--dry-run] [--dir <path>] [--version <ver>]
+ *
+ * 解析 USAGE 块 Depends 传递闭包，把每个条目对应的 SDK 文件从 registry 包根的 <relPath>
+ * **保留相对路径**拷到项目根（--dir 指定目录的根）。
+ * skip-by-disk：目标已存在默认跳过，--overwrite 才覆盖。不写任何安装记账文件。
+ */
+async function handleRegistryAdd(opts) {
+    await Promise.resolve();
+    if (opts.names.length === 0) {
+        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 reg = (0, index_1.loadRegistry)({ stack, version: opts.version });
+    try {
+        const plan = (0, index_1.planAdd)({
+            entries: reg.entries,
+            targetDir,
+            names: opts.names,
+        });
+        const result = (0, index_1.applyAdd)(plan.files, {
+            overwrite: opts.overwrite === true,
+            dryRun: opts.dryRun === true,
+        });
+        const verb = opts.dryRun === true ? 'Would add' : 'Added';
+        (0, logger_1.log)('registry', `${verb} ${String(result.added.length)} file(s), skipped ${String(result.skipped.length)} (registry@${reg.version})`);
+        (0, output_1.emit)({
+            data: {
+                registryVersion: reg.version,
+                requested: opts.names,
+                resolved: plan.entries.map((e) => e.name),
+                added: result.added,
+                skipped: result.skipped,
+                dryRun: opts.dryRun === true,
+            },
+        });
+    }
+    finally {
+        reg.cleanup();
+    }
+}

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

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleRegistryAdd = exports.handleRegistryList = void 0;
+var list_1 = require("./list");
+Object.defineProperty(exports, "handleRegistryList", { enumerable: true, get: function () { return list_1.handleRegistryList; } });
+var add_1 = require("./add");
+Object.defineProperty(exports, "handleRegistryAdd", { enumerable: true, get: function () { return add_1.handleRegistryAdd; } });

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

@@ -0,0 +1,48 @@
+"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>]
+ *
+ * 从 .spark/meta.json 读 stack → runtime → 包名，拉对应 registry 包，从包根递归扫含 USAGE 块的 SDK 文件。
+ *
+ * - 默认（pretty）：输出各条目 USAGE 块原文，带文件名分隔，给 Agent 直接读注释。
+ * - --json：输出 [{name, file, usage(原文字符串), dependsOn[]}]，usage 保持原文不解析成字段。
+ *   file 是相对包根的路径（如 scripts/deck-stage.js），即 add 后的落地相对路径。
+ */
+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 reg = (0, index_1.loadRegistry)({ stack, version: opts.version });
+    try {
+        if ((0, output_1.isJsonMode)()) {
+            (0, output_1.emit)({
+                data: reg.entries.map((e) => ({
+                    name: e.name,
+                    file: e.relPath,
+                    usage: e.usage,
+                    dependsOn: e.dependsOn,
+                })),
+            });
+            return;
+        }
+        // pretty：各条目 USAGE 块原文拼接，带文件路径分隔（让 Agent 直接读注释）
+        if (reg.entries.length === 0) {
+            (0, output_1.emit)('(no registry entries)');
+            return;
+        }
+        const blocks = reg.entries.map((e) => `# ${e.relPath}\n${e.usage}`);
+        (0, output_1.emit)(blocks.join('\n\n'));
+    }
+    finally {
+        reg.cleanup();
+    }
+}

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRegistryStack = resolveRegistryStack;
+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。
+ * 缺 stack → 提示先 init；stack 无 registry（无对应 runtime / runtime 无 registry 包）→ 提示支持哪些 stack。
+ *
+ * 这里只做「stack 是否在支持列表」的早校验给用户友好提示；包名的两跳解析
+ * （stack → runtime → 包）由 loadRegistry/resolveRegistryPackage 负责。
+ */
+function resolveRegistryStack(targetDir) {
+    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+    if (meta.stack === undefined || meta.stack === '') {
+        throw new error_1.AppError('REGISTRY_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+    }
+    if (!index_1.REGISTRY_SUPPORTED_STACKS.includes(meta.stack)) {
+        throw new error_1.AppError('REGISTRY_STACK_UNSUPPORTED', `stack "${meta.stack}" 没有组件 registry`, {
+            next_actions: [`支持 registry 的 stack：${index_1.REGISTRY_SUPPORTED_STACKS.join(', ') || '(none)'}`],
+        });
+    }
+    return meta.stack;
+}

package/dist/services/registry/index.js

@@ -0,0 +1,263 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY_SUPPORTED_STACKS = exports.REGISTRY_BY_RUNTIME = exports.STACK_RUNTIME = void 0;
+exports.resolveRegistryPackage = resolveRegistryPackage;
+exports.loadRegistry = loadRegistry;
+exports.extractUsageBlock = extractUsageBlock;
+exports.parseDependsOn = parseDependsOn;
+exports.indexEntries = indexEntries;
+exports.resolveDependencyClosure = resolveDependencyClosure;
+exports.planAdd = planAdd;
+exports.applyAdd = applyAdd;
+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 error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
+/**
+ * 解析链：stack → runtime → registry 包名。
+ *
+ * registry 包按 **运行时（runtime）** 命名分发（而非 stack）：多个 stack 可共享同一 runtime
+ * 的同一份 registry。runtime 不引入新的 meta 字段，从已有的 `.spark/meta.json.stack` 推得。
+ *   STACK_RUNTIME:        stack → runtime（design-html 跑在 buildless 运行时）
+ *   REGISTRY_BY_RUNTIME:  runtime → registry 包名
+ * 任一步查不到都明确报错（stack 无对应 runtime / runtime 无对应 registry）。
+ */
+exports.STACK_RUNTIME = {
+    'design-html': 'buildless',
+};
+exports.REGISTRY_BY_RUNTIME = {
+    buildless: '@lark-apaas/coding-registry-buildless',
+};
+/** 有对应 registry 的 stack 列表（stack 有 runtime 且该 runtime 有 registry 包）。 */
+exports.REGISTRY_SUPPORTED_STACKS = Object.keys(exports.STACK_RUNTIME).filter((stack) => Boolean(exports.REGISTRY_BY_RUNTIME[exports.STACK_RUNTIME[stack]]));
+/**
+ * stack → registry 包名。走 STACK_RUNTIME → REGISTRY_BY_RUNTIME 两跳。
+ * stack 无对应 runtime，或 runtime 无对应 registry，均抛 AppError。
+ */
+function resolveRegistryPackage(stack) {
+    const runtime = exports.STACK_RUNTIME[stack];
+    if (!runtime) {
+        throw new error_1.AppError('REGISTRY_STACK_UNSUPPORTED', `stack "${stack}" 没有对应的 runtime`, {
+            next_actions: [`支持 registry 的 stack：${exports.REGISTRY_SUPPORTED_STACKS.join(', ') || '(none)'}`],
+        });
+    }
+    const packageName = exports.REGISTRY_BY_RUNTIME[runtime];
+    if (!packageName) {
+        throw new error_1.AppError('REGISTRY_RUNTIME_UNSUPPORTED', `runtime "${runtime}"（来自 stack "${stack}"）没有对应的 registry 包`);
+    }
+    return packageName;
+}
+const USAGE_BEGIN = '/* BEGIN USAGE */';
+const USAGE_END = '/* END USAGE */';
+/**
+ * 拉取并解析某 stack 的 registry 包。
+ *
+ * 复用 fetchNpmPackage（npm pack + tar -xzf + 临时目录），与 template / steering 同一套
+ * tarball 基建。包内布局约定（SDK 文件**平铺在包根**，无外层 registry/ 目录）：
+ *   package/<subdir>/<sdk-file>    ← 按目录组织的 SDK 文件，每个以 USAGE 块开头
+ *     （scripts/ · components/ · stylesheets/ 等；CLI 不约束子目录名）
+ *
+ * 从包根递归扫整棵树，判定含 USAGE 块的为 SDK 条目（package.json / README / LICENSE 等无
+ * USAGE 块的文件自然跳过），解析其 USAGE 原文 + Depends。
+ * 调用方用完 **必须** 调 result.cleanup() 清理临时目录。
+ */
+function loadRegistry(opts) {
+    const packageName = resolveRegistryPackage(opts.stack);
+    const effectiveVersion = opts.version ?? 'latest';
+    (0, logger_1.log)('registry', `Fetching ${packageName}@${effectiveVersion}...`);
+    const fetched = (0, npm_pack_1.fetchNpmPackage)({ packageName, version: effectiveVersion });
+    try {
+        // 扫描根 = 包根（fetchNpmPackage 的 extractDir 即 tarball 内 package/ 目录）
+        const registryRoot = fetched.extractDir;
+        const entries = scanEntries(registryRoot);
+        return {
+            entries,
+            registryRoot,
+            version: fetched.version,
+            cleanup: () => {
+                fetched.cleanup();
+            },
+        };
+    }
+    catch (err) {
+        fetched.cleanup();
+        throw err;
+    }
+}
+/**
+ * 可作为 SDK 条目的代码文件扩展名白名单。
+ * 只扫代码文件 —— README.md / LICENSE / package.json 等不在此列，避免文档里出现的
+ * USAGE 字面量（如 README 解释 `/* BEGIN USAGE *​/` 格式）被误判为 SDK 条目。
+ */
+const SDK_FILE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.css']);
+/**
+ * 从包根递归扫整棵树，提取含 USAGE 块的 SDK 条目（任意子目录深度）。
+ * 只看代码文件（SDK_FILE_EXTENSIONS）；条目 name 全树唯一，撞名抛错。
+ */
+function scanEntries(registryRoot) {
+    const entries = [];
+    const byName = new Map(); // name → relPath（撞名诊断）
+    const walk = (dir) => {
+        for (const dirent of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            const absPath = node_path_1.default.join(dir, dirent.name);
+            if (dirent.isDirectory()) {
+                walk(absPath);
+                continue;
+            }
+            if (!dirent.isFile())
+                continue;
+            // 只扫代码文件，排除 README/LICENSE/package.json 等（它们正文可能含 USAGE 字面量）
+            if (!SDK_FILE_EXTENSIONS.has(node_path_1.default.extname(dirent.name).toLowerCase()))
+                continue;
+            const content = node_fs_1.default.readFileSync(absPath, 'utf-8');
+            const usage = extractUsageBlock(content);
+            if (usage === null)
+                continue; // 非 SDK 文件（无 USAGE 块）
+            // 相对包根的路径，统一用 '/' 分隔（落地时再按平台 join）
+            const relPath = node_path_1.default.relative(registryRoot, absPath).split(node_path_1.default.sep).join('/');
+            const name = stripExt(dirent.name);
+            const prev = byName.get(name);
+            if (prev !== undefined) {
+                throw new error_1.AppError('REGISTRY_DUPLICATE_NAME', `registry 条目名 "${name}" 重复：${prev} 与 ${relPath}`);
+            }
+            byName.set(name, relPath);
+            entries.push({
+                name,
+                relPath,
+                usage,
+                dependsOn: parseDependsOn(usage),
+                absPath,
+            });
+        }
+    };
+    walk(registryRoot);
+    // 稳定排序，便于 list 输出可预期
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    return entries;
+}
+/** 提取 BEGIN/END USAGE 标记之间的原文（含标记行）。无 USAGE 块返回 null。 */
+function extractUsageBlock(content) {
+    const begin = content.indexOf(USAGE_BEGIN);
+    if (begin === -1)
+        return null;
+    const end = content.indexOf(USAGE_END, begin);
+    if (end === -1)
+        return null;
+    return content.slice(begin, end + USAGE_END.length);
+}
+/** 从 USAGE 块文本里解析 `// Depends: <name>` 行（可多行），返回去重后的依赖名列表。 */
+function parseDependsOn(usage) {
+    const deps = [];
+    const seen = new Set();
+    for (const line of usage.split(/\r?\n/)) {
+        const m = /^\s*\/\/\s*Depends:\s*(.+?)\s*$/.exec(line);
+        if (m === null)
+            continue;
+        // 一行内允许逗号 / 空白分隔多个依赖
+        for (const raw of m[1].split(/[\s,]+/)) {
+            const name = raw.trim();
+            if (name !== '' && !seen.has(name)) {
+                seen.add(name);
+                deps.push(name);
+            }
+        }
+    }
+    return deps;
+}
+function stripExt(file) {
+    const ext = node_path_1.default.extname(file);
+    return ext === '' ? file : file.slice(0, -ext.length);
+}
+/** name → entry 索引，便于依赖解析。 */
+function indexEntries(entries) {
+    const map = new Map();
+    for (const e of entries)
+        map.set(e.name, e);
+    return map;
+}
+/**
+ * 解析 Depends 的传递闭包：从 requested 出发，递归把所有依赖一并纳入。
+ *
+ * 返回拓扑序（依赖在前、被依赖在后），便于按序拷贝。检测循环依赖并抛错；
+ * 引用了不存在的条目名也抛错（fail-fast，避免拷半套）。
+ */
+function resolveDependencyClosure(entries, requested) {
+    const index = indexEntries(entries);
+    const ordered = [];
+    const visited = new Set();
+    const onStack = new Set();
+    const visit = (name, trail) => {
+        if (visited.has(name))
+            return;
+        if (onStack.has(name)) {
+            throw new error_1.AppError('REGISTRY_CYCLE', `registry 条目依赖成环：${[...trail, name].join(' -> ')}`);
+        }
+        const entry = index.get(name);
+        if (entry === undefined) {
+            // requested 顶层缺失 vs 依赖链里缺失，都报清楚是谁引的
+            const via = trail.length > 0 ? `（被 "${trail[trail.length - 1]}" 依赖）` : '';
+            throw new error_1.AppError('REGISTRY_ENTRY_NOT_FOUND', `registry 没有条目 "${name}"${via}`, {
+                next_actions: ['用 `miaoda registry list` 查看可用条目'],
+            });
+        }
+        onStack.add(name);
+        for (const dep of entry.dependsOn) {
+            visit(dep, [...trail, name]);
+        }
+        onStack.delete(name);
+        visited.add(name);
+        ordered.push(entry);
+    };
+    for (const name of requested)
+        visit(name, []);
+    return ordered;
+}
+/**
+ * 规划 add：解析依赖闭包 → 每个条目按其相对包根的路径落地到项目根 → 标记是否已存在。
+ * 纯计算，不落盘（dry-run 与真实 add 共用）。
+ */
+function planAdd(opts) {
+    const entries = resolveDependencyClosure(opts.entries, opts.names);
+    const files = entries.map((entry) => {
+        // relPath 用 '/' 存，落地时按平台拆分 join，保证 Windows 也正确
+        const destAbs = node_path_1.default.join(opts.targetDir, ...entry.relPath.split('/'));
+        return {
+            entry: entry.name,
+            relPath: entry.relPath,
+            destAbs,
+            srcAbs: entry.absPath,
+            exists: node_fs_1.default.existsSync(destAbs),
+        };
+    });
+    return { entries, files };
+}
+/**
+ * 执行 add 计划：按 skip-by-disk 把 SDK 文件保留相对结构拷到项目根。
+ *   - 目标已存在且未 overwrite → skip（保护用户改动）
+ *   - 目标已存在且 overwrite → 覆盖写
+ *   - 目标不存在 → 写
+ * dryRun=true 时只分类不落盘。不写任何安装记账文件（项目文件树即状态）。
+ */
+function applyAdd(files, opts) {
+    const added = [];
+    const skipped = [];
+    for (const f of files) {
+        if (f.exists && !opts.overwrite) {
+            skipped.push(f.relPath);
+            continue;
+        }
+        if (!opts.dryRun) {
+            if (!node_fs_1.default.existsSync(f.srcAbs)) {
+                throw new error_1.AppError('REGISTRY_FILE_MISSING', `registry 包内缺少文件 ${f.relPath}（条目 "${f.entry}"）`);
+            }
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(f.destAbs), { recursive: true });
+            node_fs_1.default.copyFileSync(f.srcAbs, f.destAbs);
+        }
+        added.push(f.relPath);
+    }
+    return { added, skipped };
+}

package/package.json

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