lan-low-code-cli 2.5.0 → 2.7.0

package/dist/commands/flow.js

@@ -0,0 +1,755 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFlowCommand = registerFlowCommand;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const flow_1 = require("../api/flow");
+const client_1 = require("../client");
+const config_1 = require("../config");
+const flow_2 = require("../generator/flow");
+const logger_1 = require("../utils/logger");
+/** 读取 --spec / --design：支持 @文件 或内联 JSON 字符串 */
+function readJsonInput(value, label) {
+    let text = value;
+    if (value.startsWith('@')) {
+        const file = (0, path_1.resolve)(process.cwd(), value.slice(1));
+        if (!(0, fs_1.existsSync)(file))
+            throw new Error(`${label} 文件不存在：${file}`);
+        text = (0, fs_1.readFileSync)(file, 'utf-8');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${label} 不是合法 JSON：${err.message}`);
+    }
+}
+function writeJsonFile(file, data) {
+    const target = (0, path_1.resolve)(process.cwd(), file.startsWith('@') ? file.slice(1) : file);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true });
+    (0, fs_1.writeFileSync)(target, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+    logger_1.logger.success(`已写出：${target}`);
+}
+function parseNumber(value, label) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${label} 必须是数字：${value}`);
+    return parsed;
+}
+function buildOptions(opts) {
+    const mode = (opts.layout ?? 'ide');
+    if (!['ide', 'layered', 'passthrough'].includes(mode)) {
+        throw new Error(`--layout 只支持 ide | layered | passthrough，收到：${mode}`);
+    }
+    return {
+        mode,
+        ...(opts.centerX !== undefined ? { centerX: parseNumber(opts.centerX, '--center-x') } : {}),
+        ...(opts.rankPadding !== undefined ? { rankPadding: parseNumber(opts.rankPadding, '--rank-padding') } : {}),
+        ...(opts.laneGap !== undefined ? { laneGap: parseNumber(opts.laneGap, '--lane-gap') } : {}),
+        ...(opts.minGap !== undefined ? { minGap: parseNumber(opts.minGap, '--min-gap') } : {}),
+        ...(opts.subCenterX !== undefined ? { subCenterX: parseNumber(opts.subCenterX, '--sub-center-x') } : {}),
+        emitWayPoints: Boolean(opts.emitWayPoints),
+    };
+}
+function printDiagnostics(result, force) {
+    const errors = result.diagnostics.filter((d) => d.level === 'error');
+    const warnings = result.diagnostics.filter((d) => d.level === 'warn');
+    warnings.forEach((d) => logger_1.logger.warn(`[${d.code}] ${d.message}`));
+    if (errors.length === 0) {
+        logger_1.logger.success(`离线校验通过（${result.diagnostics.length - errors.length} 条提示）`);
+        return;
+    }
+    errors.forEach((d) => logger_1.logger.error(`[${d.code}] ${d.message}`));
+    if (!force) {
+        throw new Error(`离线校验未通过（${errors.length} 项错误）；修正 spec 后重试，或追加 --force 仅用于查看输出`);
+    }
+    logger_1.logger.warn('已按 --force 输出，但存在错误，禁止直接发布到环境');
+}
+function printSummary(result) {
+    logger_1.logger.title('动作流编译结果');
+    logger_1.logger.info(`节点 ${result.design.nodes.length} · 连线 ${result.design.lines.length} · 启动方式 ${result.fdStartWay}`);
+    logger_1.logger.info(logger_1.color.gray(`fdDesign 长度 ${result.fdDesign.length} 字符`));
+    logger_1.logger.info('');
+    logger_1.logger.table(result.bounds.map((item) => ({
+        id: item.id,
+        nodeType: item.type,
+        rank: item.rank,
+        lane: item.lane,
+        x: item.bounds.x,
+        y: item.bounds.y,
+        size: `${item.bounds.width}×${item.bounds.height}`,
+    })));
+}
+function buildTemplateSpec(opts) {
+    return {
+        appCode: opts.appCode ?? '<appCode>',
+        name: opts.name ?? '新建动作流',
+        code: opts.code ?? 'flow_new',
+        startWay: (opts.startWay ?? 'StartActiveNode'),
+        trigger: { fdRunType: ['operate'], fdFormRelation: '0', dataType: 1 },
+        nodes: [
+            {
+                id: 'N2',
+                type: 'QueryDataNode',
+                name: '查询数据',
+                config: { target: { entityId: '<entityId>' }, resultType: 'single' },
+            },
+            {
+                id: 'N3',
+                type: 'AddDataNode',
+                name: '写入数据',
+                config: {
+                    dataSourceVO: { entityId: '<entityId>' },
+                    flow: '<flowId>',
+                    fields: {},
+                },
+            },
+        ],
+        edges: [{ from: 'N2', to: 'N3' }],
+    };
+}
+function addCommonOptions(cmd) {
+    return cmd
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）');
+}
+function createClient(opts) {
+    return new client_1.LcodeClient((0, config_1.resolveRuntime)({ baseUrl: opts.baseUrl, token: opts.token }));
+}
+/** 后端有的接口返回数组，有的返回 { content: [] } */
+function toRows(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === 'object') {
+        const content = value.content;
+        if (Array.isArray(content))
+            return content;
+    }
+    return [];
+}
+const STATUS_LABEL = { '-1': '草稿', '0': '停用', '1': '启用' };
+const STATUS_VALUE = { draft: -1, stopped: 0, enabled: 1 };
+/** --from 支持：get 响应（含 fdDesign）、编译结果（含 design）、或直接的设计对象 */
+function resolveDesign(input) {
+    let value = input;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            throw new Error('--from 传入的字符串不是合法 JSON');
+        }
+    }
+    if (!value || typeof value !== 'object')
+        throw new Error('--from 必须是对象或 JSON 字符串');
+    const obj = value;
+    if (Array.isArray(obj.nodes)) {
+        return {
+            nodes: obj.nodes,
+            lines: (Array.isArray(obj.lines) ? obj.lines : []),
+        };
+    }
+    if (typeof obj.fdDesign === 'string')
+        return resolveDesign(obj.fdDesign);
+    if (obj.design && typeof obj.design === 'object')
+        return resolveDesign(obj.design);
+    throw new Error('--from 需为 flow get 响应（含 fdDesign）、flow compile 结果（含 design）或设计对象（含 nodes）');
+}
+/**
+ * golden 模板抽取：剥离 drawAttr（坐标）与实例字段，只保留合法结构骨架。
+ * 坐标由布局引擎统一生成，不把某次手工拖拽的偶然位置固化进模板。
+ */
+function stripInstanceFields(node) {
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'drawAttr' || key === 'id' || key === 'code' || key === 'name')
+            continue;
+        if (key === 'subProcess' && value && typeof value === 'object') {
+            const sub = value;
+            out.subProcess = {
+                nodes: (Array.isArray(sub.nodes) ? sub.nodes : []).map((item) => stripInstanceFields(item)),
+                lines: [],
+            };
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function writeTextFile(file, text) {
+    const target = (0, path_1.resolve)(process.cwd(), file.startsWith('@') ? file.slice(1) : file);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true });
+    (0, fs_1.writeFileSync)(target, text, 'utf-8');
+    logger_1.logger.success(`已写出：${target}`);
+}
+/** 与 UI 一致的提交体：{ ...basicInfo, fdDesign: JSON.stringify(design) } */
+function buildPublishPayload(result) {
+    return { ...result.basicInfo, fdDesign: result.fdDesign };
+}
+/** diff 时默认忽略 drawAttr.bounds（坐标由布局引擎生成，不参与语义比较） */
+function normalizeForDiff(value, ignoreBounds) {
+    const copy = JSON.parse(JSON.stringify(value));
+    if (ignoreBounds && copy.drawAttr && typeof copy.drawAttr === 'object') {
+        delete copy.drawAttr.bounds;
+    }
+    return JSON.stringify(copy);
+}
+function diffDesigns(local, remote, ignoreBounds) {
+    const keyOfNode = (n) => String(n.id ?? '');
+    const keyOfLine = (l) => `${String(l.sourceRef ?? '')}->${String(l.targetRef ?? '')}`;
+    const index = (rows, key) => new Map(rows.map((row) => [key(row), normalizeForDiff(row, ignoreBounds)]));
+    const localNodes = index(local.nodes, keyOfNode);
+    const remoteNodes = index(remote.nodes, keyOfNode);
+    const localLines = index(local.lines, keyOfLine);
+    const remoteLines = index(remote.lines, keyOfLine);
+    const compare = (a, b) => ({
+        added: [...a.keys()].filter((k) => !b.has(k)),
+        removed: [...b.keys()].filter((k) => !a.has(k)),
+        changed: [...a.keys()].filter((k) => b.has(k) && a.get(k) !== b.get(k)),
+    });
+    const nodes = compare(localNodes, remoteNodes);
+    const lines = compare(localLines, remoteLines);
+    return {
+        ignoreBounds,
+        equal: Object.values(nodes).every((v) => v.length === 0) && Object.values(lines).every((v) => v.length === 0),
+        nodes,
+        lines,
+    };
+}
+/** 生成调用 MKXFORM.flow_{fdCode} 的按钮脚本（mkxform-api.md:2558-2574 / 190-229） */
+function buildFlowScript(detail) {
+    const code = String(detail.fdCode ?? '');
+    const fdId = String(detail.fdId ?? '');
+    const name = String(detail.fdName ?? code);
+    return `// 由 llc flow script 生成 · 动作流：${name}（${code}）
+(function () {
+  var MKXFORM = window.MKXFORM || {};
+  var fn = MKXFORM['flow_${code}'];
+  if (typeof fn !== 'function') {
+    console.warn('动作流函数未注册：flow_${code}（需已发布且启用、fdStartWay=StartActiveNode）');
+    return;
+  }
+  fn({
+    context: typeof context !== 'undefined' ? context : {},
+    fdProcessId: '${fdId}',
+    incParams: {},
+    fdProcessCode: '${code}'
+  }, function (error, res, ctx) {
+    if (error) { console.error('动作流执行失败', error); return; }
+    console.log('动作流返回', res);
+    if (ctx && typeof ctx.refresh === 'function') ctx.refresh();
+  });
+})();
+`;
+}
+function registerFlowCommand(program) {
+    const flow = program
+        .command('flow')
+        .description('动作流建模：Flow Spec 编译 / 只读查询 / golden 模板抽取');
+    addCommonOptions(flow
+        .command('spec')
+        .description('生成一份 Flow Spec 模板（开始/结束节点由编译器自动补齐）')
+        .option('--app-code <code>', '应用编码 fdAppCode')
+        .option('--name <name>', '流程名称')
+        .option('--code <code>', '流程编码（字母数字下划线，≤30）')
+        .option('--start-way <way>', '启动方式：StartActiveNode | StartScheduledNode | StartDataNode | StartEventNode')
+        .option('--out <file>', '写出到文件（缺省输出到终端）')
+        .option('--json', '以 JSON 输出')).action((opts) => {
+        const spec = buildTemplateSpec(opts);
+        if (opts.out)
+            writeJsonFile(opts.out, spec);
+        else
+            logger_1.logger.json(spec);
+        logger_1.logger.info(logger_1.color.gray('提示：把 <entityId> / <flowId> 等占位符替换为环境真实值后再执行 llc flow compile'));
+    });
+    addCommonOptions(flow
+        .command('compile')
+        .description('把 Flow Spec 编译为可直接提交的 fdDesign（含编排布局与离线校验）')
+        .requiredOption('--spec <@file|json>', 'Flow Spec：@文件路径 或内联 JSON 字符串')
+        .option('--layout <mode>', '布局模式：ide（默认，分支同层左右对称）| layered | passthrough（沿用已有坐标）')
+        .option('--center-x <n>', '主链中心 x，默认 679（对应 1920 宽屏）')
+        .option('--rank-padding <n>', '层间距增量，默认 52（层距 = 该层最高节点 + 52）')
+        .option('--lane-gap <n>', '泳道间距覆盖值，默认 2 × 层距')
+        .option('--min-gap <n>', '节点最小边缘间隙，默认 40（IDE 常规编排最小约 43px）')
+        .option('--sub-center-x <n>', '循环子画布中心线，默认与主画布一致')
+        .option('--emit-waypoints', '输出 drawAttr.wayPoints（IDE 自身保存时不写）')
+        .option('--out <file>', '写出完整编译结果到文件')
+        .option('--force', '有校验错误时仍输出（仅用于查看，禁止发布）')
+        .option('--json', '以 JSON 输出完整编译结果')).action((opts) => {
+        const spec = readJsonInput(String(opts.spec), '--spec');
+        const result = (0, flow_2.compileFlow)(spec, buildOptions(opts));
+        if (opts.json) {
+            logger_1.logger.json(result);
+        }
+        else {
+            printSummary(result);
+            logger_1.logger.info('');
+        }
+        printDiagnostics(result, Boolean(opts.force));
+        if (opts.out)
+            writeJsonFile(opts.out, result);
+        if (!opts.json)
+            logger_1.logger.info(logger_1.color.gray('追加 --json 或 --out <file> 可取得完整 fdDesign'));
+    });
+    addCommonOptions(flow
+        .command('validate')
+        .description('只做离线校验（图结构 / 必填 / 编码 / 布局重叠），不输出设计')
+        .requiredOption('--spec <@file|json>', 'Flow Spec：@文件路径 或内联 JSON 字符串')
+        .option('--layout <mode>', '布局模式：ide | layered | passthrough')
+        .option('--center-x <n>', '主链中心 x')
+        .option('--rank-padding <n>', '层间距增量')
+        .option('--lane-gap <n>', '泳道间距')
+        .option('--min-gap <n>', '节点最小边缘间隙')
+        .option('--json', '以 JSON 输出诊断结果')).action((opts) => {
+        const spec = readJsonInput(String(opts.spec), '--spec');
+        const result = (0, flow_2.compileFlow)(spec, buildOptions(opts));
+        if (opts.json) {
+            logger_1.logger.json(result.diagnostics);
+            if ((0, flow_2.hasErrors)(result.diagnostics)) {
+                result.diagnostics
+                    .filter((d) => d.level === 'error')
+                    .forEach((d) => logger_1.logger.error(`[${d.code}] ${d.message}`));
+                throw new Error('离线校验未通过');
+            }
+            return;
+        }
+        printDiagnostics(result, false);
+        logger_1.logger.info(logger_1.color.gray(`共 ${result.design.nodes.length} 个节点、${result.design.lines.length} 条连线`));
+    });
+    // ---------------------------------------------------------------- 阶段 2：只读查询
+    addCommonOptions(flow
+        .command('list')
+        .description('列出应用下的动作流（只读）')
+        .requiredOption('--app-code <code>', '应用编码 fdAppCode（可由 llc app get --id 取得）')
+        .option('--keyword <kw>', '按名称模糊过滤')
+        .option('--status <status>', '状态过滤：draft | stopped | enabled 或 -1/0/1')
+        .option('--page-no <n>', '页码，默认 1')
+        .option('--page-size <n>', '每页条数，默认 100')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        const client = createClient(opts);
+        const conditions = { fdAppCode: opts.appCode };
+        if (opts.keyword)
+            conditions.fdName = { $contains: String(opts.keyword) };
+        if (opts.status !== undefined) {
+            const value = STATUS_VALUE[String(opts.status)] ?? Number(opts.status);
+            if (!Number.isFinite(value))
+                throw new Error(`--status 只支持 draft|stopped|enabled 或 -1/0/1：${opts.status}`);
+            conditions.fdStatus = value;
+        }
+        const result = await flow_1.flowApi.list(client, {
+            conditions,
+            pageNo: parseNumber(opts.pageNo, '--page-no') ?? 1,
+            pageSize: parseNumber(opts.pageSize, '--page-size') ?? 100,
+        });
+        const rows = toRows(result);
+        if (opts.json) {
+            logger_1.logger.json(rows);
+            return;
+        }
+        logger_1.logger.table(rows.map((row) => ({
+            fdId: row.fdId ?? '',
+            fdName: row.fdName ?? '',
+            fdCode: row.fdCode ?? '',
+            启动方式: row.fdStartWay ?? '',
+            状态: STATUS_LABEL[String(row.fdStatus)] ?? row.fdStatus ?? '',
+            分类: row.fdCategory?.fdName ?? '',
+        })));
+        logger_1.logger.info(logger_1.color.gray(`共 ${rows.length} 条动作流`));
+    });
+    addCommonOptions(flow
+        .command('get')
+        .description('查看动作流详情（只读；--with-design 解析 fdDesign）')
+        .requiredOption('--id <fdId>', '动作流 fdId')
+        .option('--with-design', '把 fdDesign 字符串解析为对象后以 JSON 输出')
+        .option('--raw', '原样输出 fdDesign 字符串')
+        .option('--json', '以 JSON 输出详情')).action(async (opts) => {
+        const client = createClient(opts);
+        const detail = await flow_1.flowApi.get(client, String(opts.id));
+        if (opts.raw) {
+            process.stdout.write(`${detail.fdDesign ?? ''}\n`);
+            return;
+        }
+        if (opts.withDesign) {
+            let design = detail.fdDesign;
+            if (typeof design === 'string') {
+                try {
+                    design = JSON.parse(design);
+                }
+                catch (err) {
+                    throw new Error(`fdDesign 不是合法 JSON：${err.message}`);
+                }
+            }
+            logger_1.logger.json({ ...detail, fdDesign: design });
+            return;
+        }
+        if (opts.json) {
+            logger_1.logger.json(detail);
+            return;
+        }
+        logger_1.logger.table([
+            {
+                fdId: detail.fdId ?? '',
+                fdName: detail.fdName ?? '',
+                fdCode: detail.fdCode ?? '',
+                启动方式: detail.fdStartWay ?? '',
+                状态: STATUS_LABEL[String(detail.fdStatus)] ?? detail.fdStatus ?? '',
+                fdAppCode: detail.fdAppCode ?? '',
+                fdDesign长度: (detail.fdDesign ?? '').length,
+            },
+        ]);
+    });
+    const category = flow.command('category').description('动作流分类（只读）');
+    addCommonOptions(category
+        .command('list')
+        .description('列出应用的动作流分类')
+        .requiredOption('--app-code <code>', '应用编码 fdAppCode')
+        .option('--keyword <kw>', '按名称模糊过滤')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        const client = createClient(opts);
+        const result = await flow_1.flowApi.categoryList(client, {
+            conditions: {
+                fdAppCode: opts.appCode,
+                ...(opts.keyword ? { fdName: { $contains: String(opts.keyword) } } : {}),
+            },
+            sorts: { fdCreateTime: 'desc' },
+            pageNo: 1,
+            pageSize: 1000,
+        });
+        const rows = toRows(result);
+        if (opts.json) {
+            logger_1.logger.json(rows);
+            return;
+        }
+        logger_1.logger.table(rows.map((row) => ({ fdId: row.fdId ?? '', fdName: row.fdName ?? '' })));
+    });
+    addCommonOptions(flow
+        .command('logs')
+        .description('查询动作流运行日志（只读）')
+        .requiredOption('--id <fdId>', '动作流 fdId')
+        .option('--limit <n>', '条数，默认 20')
+        .option('--endpoint <path>', '覆盖日志端点相对路径（环境差异时用）')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        const client = createClient(opts);
+        const result = await flow_1.flowApi.logFindAll(client, {
+            conditions: { 'fdEntity.fdId': String(opts.id) },
+            fdGroup: 'modeling.process.log',
+            sorts: { fdBeginTime: 'desc' },
+            offset: 0,
+            pageSize: parseNumber(opts.limit, '--limit') ?? 20,
+        }, opts.endpoint);
+        const rows = toRows(result);
+        if (opts.json) {
+            logger_1.logger.json(rows);
+            return;
+        }
+        logger_1.logger.table(rows.map((row) => ({
+            fdId: row.fdId ?? '',
+            开始时间: row.fdBeginTime ?? '',
+            状态: row.fdStatus ?? '',
+            消息: String(row.fdMessage ?? '').slice(0, 60),
+        })));
+        logger_1.logger.info(logger_1.color.gray(`共 ${rows.length} 条日志`));
+    });
+    addCommonOptions(flow
+        .command('schema')
+        .description('查询动作流建模所需的后端 Schema / 元数据（只读，始终以 JSON 输出）')
+        .requiredOption('--kind <kind>', 'businessNodes | events | source | jsonSchema | condition | out | active | event | interface | apiMethod | flowBots | meta | dataModel | recycle')
+        .option('--entity-id <id>', '数据模型 / 表单实体 id')
+        .option('--code <code>', '动作流、事件或接口编码')
+        .option('--app-code <code>', '应用编码（--kind active 必填）')
+        .option('--api-type <type>', '内部接口类型（--kind apiMethod）')
+        .option('--api-method-path <path>', '内部接口方法路径（--kind apiMethod）')).action(async (opts) => {
+        const client = createClient(opts);
+        const kind = String(opts.kind);
+        const requireOpt = (value, name) => {
+            if (!value)
+                throw new Error(`--kind ${kind} 需要 ${name}`);
+            return value;
+        };
+        let result;
+        switch (kind) {
+            case 'businessNodes':
+                result = await flow_1.flowApi.businessNodes(client);
+                break;
+            case 'events':
+                result = await flow_1.flowApi.getProcessDataEventInfo(client);
+                break;
+            case 'source':
+                result = await flow_1.flowApi.getSourceFields(client, requireOpt(opts.entityId, '--entity-id'));
+                break;
+            case 'jsonSchema':
+                result = await flow_1.flowApi.getJsonSchema(client, requireOpt(opts.entityId, '--entity-id'));
+                break;
+            case 'condition':
+                result = await flow_1.flowApi.getConditionFields(client, { entityId: requireOpt(opts.entityId, '--entity-id') });
+                break;
+            case 'out':
+                result = await flow_1.flowApi.getDataOutJsonSchema(client, requireOpt(opts.entityId, '--entity-id'));
+                break;
+            case 'active':
+                result = await flow_1.flowApi.getActionFlowSchema(client, requireOpt(opts.code, '--code'), requireOpt(opts.appCode, '--app-code'));
+                break;
+            case 'event':
+                result = await flow_1.flowApi.getEventSchema(client, requireOpt(opts.code, '--code'));
+                break;
+            case 'interface':
+                result = await flow_1.flowApi.getInterfaceSchema(client, requireOpt(opts.code, '--code'));
+                break;
+            case 'apiMethod':
+                result = await flow_1.flowApi.getApiMethodSchema(client, { apiType: requireOpt(opts.apiType, '--api-type'), apiMethodPath: requireOpt(opts.apiMethodPath, '--api-method-path') });
+                break;
+            case 'flowBots':
+                result = await flow_1.flowApi.getFlowBotsSchema(client, requireOpt(opts.code, '--code'));
+                break;
+            case 'meta':
+                result = await flow_1.flowApi.getMetaJsonSchema(client, { entityId: requireOpt(opts.entityId, '--entity-id') });
+                break;
+            case 'dataModel':
+                result = await flow_1.flowApi.loadDataModel(client, { entityId: requireOpt(opts.entityId, '--entity-id') });
+                break;
+            case 'recycle':
+                result = await flow_1.flowApi.getRecycleState(client, requireOpt(opts.entityId, '--entity-id'));
+                break;
+            default: throw new Error(`未知 --kind：${kind}（可执行 llc help flow schema 查看支持项）`);
+        }
+        logger_1.logger.json(result);
+    });
+    // golden 模板抽取：纯离线，输入来自 flow get / flow compile 的产物
+    flow
+        .command('templates')
+        .description('从已有动作流抽取 golden 节点模板（剥离坐标，纯离线）')
+        .requiredOption('--from <@file|json>', 'flow get 响应 / flow compile 结果 / 设计对象')
+        .option('--out <file>', '写出模板文件')
+        .option('--json', '以 JSON 输出')
+        .action((opts) => {
+        const input = readJsonInput(String(opts.from), '--from');
+        const design = resolveDesign(input);
+        const templates = {};
+        for (const node of design.nodes) {
+            const nodeType = String(node.nodeType ?? 'unknown');
+            const existing = templates[nodeType];
+            if (existing)
+                existing.count += 1;
+            else
+                templates[nodeType] = { count: 1, skeleton: stripInstanceFields(node) };
+        }
+        const output = {
+            version: 1,
+            nodeTypes: Object.keys(templates),
+            lineSkeleton: { type: 'line', drawAttr: {} },
+            templates,
+        };
+        if (opts.out)
+            writeJsonFile(opts.out, output);
+        else
+            logger_1.logger.json(output);
+        logger_1.logger.info(logger_1.color.gray('模板已剥离 drawAttr.bounds；坐标由 llc flow compile 的布局引擎统一生成'));
+    });
+    // ---------------------------------------------------------------- 阶段 3：写入与闭环
+    addCommonOptions(flow
+        .command('apply')
+        .description('把 Flow Spec 写入环境（默认预览；--yes 才提交；--draft 只存草稿）')
+        .requiredOption('--spec <@file|json>', 'Flow Spec：@文件路径 或内联 JSON')
+        .option('--app-code <code>', '应用编码 fdAppCode（覆盖 spec.appCode，写入时建议显式指定）')
+        .option('--draft', '只保存草稿（addDraft/updateDraft），不发布')
+        .option('--enable', '成功后调用 startup 启用')
+        .option('--resolve-schema', '联网补齐 extraAttr.context_*（SchemaResolver）')
+        .option('--strict-schema', 'Schema 拉取失败时升级为错误')
+        .option('--layout <mode>', '布局模式：ide | layered | passthrough')
+        .option('--center-x <n>', '主链中心 x')
+        .option('--lane-gap <n>', '泳道间距')
+        .option('--min-gap <n>', '最小边缘间隙')
+        .option('--emit-waypoints', '输出 wayPoints')
+        .option('--force', '有校验错误时仍继续（仅调试）')
+        .option('--yes', '确认写入（不加则只打印 payload）')
+        .option('--json', '以 JSON 输出结果')).action(async (opts) => {
+        const spec = readJsonInput(String(opts.spec), '--spec');
+        if (opts.appCode)
+            spec.appCode = opts.appCode;
+        if (!spec.appCode) {
+            throw new Error('写入动作流必须指定应用编码：在 spec 里写 appCode，或追加 --app-code <code>');
+        }
+        let result = (0, flow_2.compileFlow)(spec, buildOptions(opts));
+        printDiagnostics(result, Boolean(opts.force));
+        const client = createClient(opts);
+        if (opts.resolveSchema) {
+            logger_1.logger.step(`补齐运行时上下文 extraAttr.context_*（应用 ${spec.appCode}）`);
+            result = await (0, flow_2.resolveFlowSchema)(client, spec, result, { strict: Boolean(opts.strictSchema) });
+            printDiagnostics(result, Boolean(opts.force));
+        }
+        const isUpdate = Boolean(spec.fdId);
+        if (!isUpdate) {
+            let unique;
+            try {
+                unique = await flow_1.flowApi.checkCodeUniqueness(client, spec.code, spec.appCode);
+            }
+            catch (err) {
+                logger_1.logger.warn(`编码唯一性检查失败，继续提交：${err.message.split('\n')[0]}`);
+            }
+            if (unique === false) {
+                throw new Error(`流程编码 ${spec.code} 在应用 ${spec.appCode} 中已存在；更换 code，或更新已有流程时在 spec 中写 fdId`);
+            }
+        }
+        const payload = buildPublishPayload(result);
+        if (!opts.yes) {
+            logger_1.logger.warn(`预览模式：未写入。目标应用 ${spec.appCode}；确认 payload 后追加 --yes`);
+            logger_1.logger.json(payload);
+            return;
+        }
+        let created;
+        if (opts.draft) {
+            created = isUpdate ? await flow_1.flowApi.updateDraft(client, payload) : await flow_1.flowApi.addDraft(client, payload);
+        }
+        else {
+            created = isUpdate ? await flow_1.flowApi.updatePublish(client, payload) : await flow_1.flowApi.addPublish(client, payload);
+        }
+        const returned = typeof created === 'string'
+            ? created
+            : created?.fdId ?? '';
+        const fdId = isUpdate ? String(spec.fdId) : returned;
+        if (!fdId) {
+            throw new Error(`提交成功但未取得 fdId；请用 llc flow list --app-code ${spec.appCode} 核对后再操作`);
+        }
+        logger_1.logger.success(`动作流已${opts.draft ? '保存草稿' : '发布'}：${fdId}`);
+        let readback;
+        try {
+            readback = await flow_1.flowApi.get(client, fdId);
+        }
+        catch (err) {
+            logger_1.logger.warn(`回读失败（不影响已提交结果）：${err.message.split('\n')[0]}`);
+        }
+        if (opts.enable) {
+            await flow_1.flowApi.startup(client, fdId);
+            logger_1.logger.success(`已启用：${fdId}`);
+        }
+        if (opts.json) {
+            logger_1.logger.json({
+                appCode: spec.appCode,
+                fdId,
+                fdCode: spec.code,
+                published: !opts.draft,
+                enabled: Boolean(opts.enable),
+                diagnostics: result.diagnostics,
+                readback: readback
+                    ? {
+                        fdStatus: readback.fdStatus,
+                        fdStartWay: readback.fdStartWay,
+                        fdProcessActive: readback.fdProcessActive,
+                        designLength: (readback.fdDesign ?? '').length,
+                    }
+                    : null,
+            });
+        }
+    });
+    addCommonOptions(flow
+        .command('diff')
+        .description('对比本地 Flow Spec 与远端动作流设计（默认忽略坐标差异）')
+        .requiredOption('--id <fdId>', '远端动作流 fdId')
+        .requiredOption('--spec <@file|json>', '本地 Flow Spec')
+        .option('--no-ignore-bounds', '比较时也包含 drawAttr.bounds')
+        .option('--resolve-schema', '对比前联网补齐 extraAttr.context_*（与发布时的选项保持一致）')
+        .option('--strict-schema', 'Schema 拉取失败时升级为错误')
+        .option('--layout <mode>', '布局模式：ide | layered | passthrough')
+        .option('--center-x <n>', '主链中心 x')
+        .option('--json', '以 JSON 输出差异')).action(async (opts) => {
+        const spec = readJsonInput(String(opts.spec), '--spec');
+        let result = (0, flow_2.compileFlow)(spec, buildOptions(opts));
+        printDiagnostics(result, false);
+        const client = createClient(opts);
+        if (opts.resolveSchema) {
+            result = await (0, flow_2.resolveFlowSchema)(client, spec, result, { strict: Boolean(opts.strictSchema) });
+        }
+        const remote = await flow_1.flowApi.get(client, String(opts.id));
+        let remoteDesign;
+        try {
+            remoteDesign = JSON.parse(remote.fdDesign ?? '{}');
+        }
+        catch (err) {
+            throw new Error(`远端 fdDesign 不是合法 JSON：${err.message}`);
+        }
+        const diff = diffDesigns(result.design, remoteDesign, opts.ignoreBounds !== false);
+        logger_1.logger.json(diff);
+        if (diff.equal)
+            logger_1.logger.success('结构与远端一致');
+        else
+            logger_1.logger.warn('设计与远端存在差异（见 nodes / lines 的 added / removed / changed）');
+    });
+    addCommonOptions(flow
+        .command('script')
+        .description('生成调用 MKXFORM.flow_{fdCode} 的按钮脚本')
+        .requiredOption('--id <fdId>', '动作流 fdId')
+        .option('--out <file>', '写出脚本文件')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        const client = createClient(opts);
+        const detail = await flow_1.flowApi.get(client, String(opts.id));
+        if (!detail.fdCode)
+            throw new Error('该动作流缺少 fdCode，无法生成 flow_{fdCode} 调用');
+        const script = buildFlowScript(detail);
+        if (opts.out)
+            writeTextFile(opts.out, script);
+        else if (opts.json)
+            logger_1.logger.json({ fdId: detail.fdId, fdCode: detail.fdCode, script });
+        else
+            process.stdout.write(`${script}\n`);
+        logger_1.logger.info(logger_1.color.gray('用法：llc operation create --form-id <id> --type script --script @<file>，再用 llc operation attach 挂载'));
+    });
+    addCommonOptions(flow
+        .command('enable')
+        .description('启用动作流（startup）')
+        .requiredOption('--id <fdId>', '动作流 fdId')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        const client = createClient(opts);
+        await flow_1.flowApi.startup(client, String(opts.id));
+        logger_1.logger.success(`已启用：${opts.id}`);
+        if (opts.json)
+            logger_1.logger.json({ fdId: opts.id, enabled: true });
+    });
+    addCommonOptions(flow
+        .command('disable')
+        .description('停用动作流（stop；会影响调用该动作流的业务模块）')
+        .requiredOption('--id <fdId>', '动作流 fdId')
+        .option('--yes', '确认停用')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        if (!opts.yes) {
+            logger_1.logger.warn('已取消：停用可能影响业务模块，请追加 --yes 确认');
+            return;
+        }
+        const client = createClient(opts);
+        await flow_1.flowApi.stop(client, String(opts.id));
+        logger_1.logger.success(`已停用：${opts.id}`);
+        if (opts.json)
+            logger_1.logger.json({ fdId: opts.id, enabled: false });
+    });
+    addCommonOptions(flow
+        .command('delete')
+        .description('删除动作流（先查引用，被引用时拒绝）')
+        .requiredOption('--id <fdId>', '动作流 fdId')
+        .option('--yes', '确认删除')
+        .option('--json', '以 JSON 输出')).action(async (opts) => {
+        if (!opts.yes) {
+            logger_1.logger.warn('已取消：删除动作流不可恢复，请追加 --yes 确认');
+            return;
+        }
+        const client = createClient(opts);
+        logger_1.logger.step('检查引用关系');
+        let refs = [];
+        try {
+            refs = toRows(await flow_1.flowApi.listByRefer(client, String(opts.id)));
+        }
+        catch (err) {
+            logger_1.logger.warn(`引用检查失败，继续删除：${err.message.split('\n')[0]}`);
+        }
+        if (refs.length > 0) {
+            refs.forEach((item, index) => {
+                logger_1.logger.info(`  ${index + 1}. ${String(item.fdEntityLabel ?? '')} -- ${String(item.fdEntitySubject ?? '')}`);
+            });
+            throw new Error('该动作流已被引用，请先在对应业务中移除后再删除');
+        }
+        await flow_1.flowApi.remove(client, String(opts.id));
+        logger_1.logger.success(`已删除：${opts.id}`);
+        if (opts.json)
+            logger_1.logger.json({ fdId: opts.id, deleted: true });
+    });
+}