lan-low-code-cli 2.6.0 → 2.7.0

package/dist/generator/flow/schema.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * 动作流节点元数据表
+ *
+ * 逐 case 翻译 `action-flow-ide/enter.tsx:217-336` 的 generateNodeData：
+ * IDE 保存时只挑每种 nodeType 的专属字段，其余字段丢弃。
+ * 必填规则来自 `configuration/nodes/utils.tsx:37-288` 与 `validate.ts:13-17`。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_KEYS = exports.FLOW_CODE_PATTERN = exports.NODE_ID_PATTERN = exports.KNOWN_START_WAYS = exports.MULTI_OUT_NODE_TYPES = exports.NODE_REQUIRED = exports.NODE_DEFAULTS = exports.NODE_FIELD_WHITELIST = void 0;
+/** 节点专属字段白名单；未列出的 nodeType 视为未知类型（透传 config 并告警） */
+exports.NODE_FIELD_WHITELIST = {
+    StartNode: ['startNodeDef'],
+    EndNode: ['outParamType', 'outParam', 'outputParamMapping'],
+    BranchNode: ['conditionType', 'flowWay', 'defaultTargetRef', 'ruleConfig', 'formulaConfig'],
+    LoopNode: ['loopDefine', 'subProcess'],
+    QueryLoopNode: [
+        'target', 'conditions', 'sortType', 'containsDeleted', 'executeTime',
+        'loopDefine', 'context_outputParam', 'limitTime',
+    ],
+    FilterDataNode: ['bindNode', 'formula'],
+    MessageNode: [
+        'bindNode', 'subject', 'notifyType', 'todoType', 'messageTarget', 'messageLink',
+        'eventCode', 'codeValue', 'notifyCategoryCode', 'subjectType', 'templateCode',
+        'templateFields', 'grantPermission',
+    ],
+    AddDataNode: ['bindNode', 'dataSourceVO', 'flow', 'commitType', 'fields', 'autoMatchField', 'fastExecute'],
+    DeleteDataNode: ['bindNode'],
+    QueryDataNode: ['target', 'conditions', 'sorts', 'resultType', 'maxSize', 'containsDeleted'],
+    UpdateDataNode: ['bindNode', 'fields', 'fastExecute'],
+    CreateKmReviewNode: ['bindNode', 'kmReviewTemplate', 'fdCreator', 'fdSubject', 'commitType', 'fields'],
+    AddOrUpdateNode: [
+        'bindNode', 'dataSourceVO', 'flow', 'commitType', 'fields', 'condition',
+        'autoMatchField', 'fastExecute',
+    ],
+    AssignValueNode: ['assignValueRuleConfigs'],
+    TransformNode: ['outParamType', 'outParam', 'outputParamMapping'],
+    ExecuteNode: ['outParamType', 'executeCode', 'inputParamMapping'],
+    FlowBotsNode: ['outParamType', 'flowBotsCode', 'inputParamMapping'],
+    InterfaceNode: ['apiType', 'apiMethodPath', 'inputParamMapping'],
+    SubActionNode: ['outParam', 'outParamType', 'actionFlowCode', 'inputParamMapping'],
+    MessageEliminateNode: ['eliminateRange', 'eliminateType', 'eventCode', 'bindNode'],
+    QueryStatisticsNode: [
+        'nativeNodeType', 'resultType', 'target', 'conditions', 'sorts',
+        'columns', 'statisticsDimensions', 'statisticsItems',
+    ],
+    DispatchNode: [],
+};
+/** 与 IDE 一致的缺省值（styleSheet.ts:404-445） */
+exports.NODE_DEFAULTS = {
+    BranchNode: { conditionType: 'formula', flowWay: 'singleBranch' },
+    QueryDataNode: { resultType: 'single' },
+    LoopNode: { loopDefine: { type: 'LoopArray' } },
+    MessageNode: { grantPermission: true },
+};
+/** 发布前 IDE 强校验的必填字段（configuration/nodes/utils.tsx:37-288） */
+exports.NODE_REQUIRED = {
+    AddDataNode: ['dataSourceVO', 'flow', 'fields'],
+    QueryDataNode: ['target'],
+    UpdateDataNode: ['bindNode'],
+    DeleteDataNode: ['bindNode'],
+    FilterDataNode: ['bindNode'],
+    BranchNode: ['conditionType', 'flowWay'],
+    SubActionNode: ['actionFlowCode'],
+    InterfaceNode: ['apiType', 'apiMethodPath'],
+    ExecuteNode: ['executeCode'],
+    QueryStatisticsNode: ['target'],
+    AddOrUpdateNode: ['dataSourceVO', 'flow', 'fields'],
+    LoopNode: ['loopDefine'],
+    AssignValueNode: ['assignValueRuleConfigs'],
+    CreateKmReviewNode: ['kmReviewTemplate', 'fdSubject'],
+    FlowBotsNode: ['flowBotsCode'],
+    MessageNode: ['subject', 'messageTarget'],
+    MessageEliminateNode: ['eliminateRange', 'eliminateType'],
+};
+/** 允许多条出边的节点（validateCommonVertex 的 getwayMap，另有 StartNode） */
+exports.MULTI_OUT_NODE_TYPES = new Set(['BranchNode', 'parallelGateway', 'StartNode']);
+exports.KNOWN_START_WAYS = [
+    'StartScheduledNode',
+    'StartDataNode',
+    'StartEventNode',
+    'StartActiveNode',
+];
+/** 节点编码 /^[0-9a-zA-Z_]{2,32}$/（configuration/nodes/utils.tsx:12-30） */
+exports.NODE_ID_PATTERN = /^[0-9a-zA-Z_]{2,32}$/;
+/** 动作流编码 /^[a-zA-Z0-9_]{1,30}$/（topbar/index.tsx:262-279） */
+exports.FLOW_CODE_PATTERN = /^[a-zA-Z0-9_]{1,30}$/;
+/** extraAttr 六个上下文键（enter.tsx:383-390） */
+exports.CONTEXT_KEYS = [
+    'context_bindFormId',
+    'context_bindNode',
+    'context_nodeParam',
+    'context_isMulti',
+    'context_fdInParam',
+    'context_outputParam',
+];

package/dist/generator/flow/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * 动作流编译内核 · 类型定义
+ *
+ * 依据 `sys-modeling/src/components/action-flow-ide/enter.tsx:339-428`：
+ * `fdDesign` 是 JSON 字符串，顶层 `{ nodes, lines, processVar? }`；
+ * 节点为扁平结构：`drawAttr.bounds` + `extraAttr.context_*` + 各 nodeType 专属字段。
+ * IDE 回显时原样使用 x/y，不重算坐标，因此坐标必须由本内核生成。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/generator/flow/validate.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * 动作流离线校验器
+ *
+ * 移植 IDE 发布前的 validate(true)：连线数量、必填、编码格式、无环
+ * （enter.tsx:468-529、validate.ts:150-327、mxgraph/utils.tsx:1206-1258）。
+ * 目的是在发包之前把错误挡住——CLI 直接调 addPublish 会绕过 IDE 校验。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSpec = validateSpec;
+exports.validateGraph = validateGraph;
+exports.hasErrors = hasErrors;
+const schema_1 = require("./schema");
+const err = (code, message, nodeId) => ({
+    level: 'error', code, message, nodeId,
+});
+const warn = (code, message, nodeId) => ({
+    level: 'warn', code, message, nodeId,
+});
+/** 基础信息校验 */
+function validateSpec(spec) {
+    const out = [];
+    if (!spec.name || !String(spec.name).trim())
+        out.push(err('SPEC_NAME_REQUIRED', '缺少流程名称 name'));
+    if (!spec.code || !schema_1.FLOW_CODE_PATTERN.test(spec.code)) {
+        out.push(err('SPEC_CODE_INVALID', `流程编码 code 必须匹配 /^[a-zA-Z0-9_]{1,30}$/：${spec.code ?? '(空)'}`));
+    }
+    const startWay = spec.startWay ?? 'StartActiveNode';
+    if (!schema_1.KNOWN_START_WAYS.includes(startWay)) {
+        out.push(err('SPEC_START_WAY_INVALID', `未知启动方式：${startWay}`));
+    }
+    if (!Array.isArray(spec.nodes))
+        out.push(err('SPEC_NODES_REQUIRED', '缺少 nodes 数组'));
+    if (!Array.isArray(spec.edges))
+        out.push(err('SPEC_EDGES_REQUIRED', '缺少 edges 数组'));
+    return out;
+}
+/** 开始节点按启动方式的必填项（configuration/nodes/utils.tsx:40-61、validate.ts:13-17） */
+function validateStartNode(graph, spec, startWay) {
+    const out = [];
+    const start = graph.nodes.find((n) => n._isStart);
+    if (!start)
+        return out;
+    const provided = start.config?.startNodeDef;
+    const def = provided ?? spec.trigger ?? {};
+    const has = (k) => def[k] !== undefined && def[k] !== null && def[k] !== '';
+    if (startWay === 'StartScheduledNode' && !has('scheduledDef')) {
+        out.push(err('START_SCHEDULE_REQUIRED', '定时触发必须在 trigger 中提供 scheduledDef', start.id));
+    }
+    if (startWay === 'StartDataNode' && !has('target')) {
+        out.push(err('START_DATA_TARGET_REQUIRED', '数据监听必须在 trigger 中提供 target（触发表单）', start.id));
+    }
+    if (startWay === 'StartEventNode' && !has('eventCode')) {
+        out.push(err('START_EVENT_REQUIRED', '事件监听必须在 trigger 中提供 eventCode', start.id));
+    }
+    if (startWay === 'StartActiveNode') {
+        const runTypes = def.fdRunType;
+        const byFlags = def.operateTrigger === true || def.bpmTrigger === true || def.apiTrigger === true;
+        const byList = Array.isArray(runTypes) && runTypes.length > 0;
+        if (!byFlags && !byList) {
+            out.push(err('START_ACTIVE_TRIGGER_REQUIRED', '主动触发必须提供 trigger.fdRunType（operate / bpm / api 至少一项）或对应布尔开关', start.id));
+        }
+    }
+    return out;
+}
+/** 图结构 + 节点必填校验 */
+function validateGraph(graph, spec, startWay = 'StartActiveNode') {
+    const out = [];
+    const ids = new Set();
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    for (const node of graph.nodes) {
+        if (!schema_1.NODE_ID_PATTERN.test(node.id)) {
+            out.push(err('NODE_ID_INVALID', `节点 id 必须匹配 /^[0-9a-zA-Z_]{2,32}$/：${node.id}`, node.id));
+        }
+        if (ids.has(node.id))
+            out.push(err('NODE_ID_DUPLICATE', `节点 id 重复：${node.id}`, node.id));
+        ids.add(node.id);
+        if (!schema_1.NODE_FIELD_WHITELIST[node.type]) {
+            out.push(warn('NODE_TYPE_UNKNOWN', `未知节点类型 ${node.type}，config 将原样透传；请用 llc flow templates list 核对环境支持的节点`, node.id));
+        }
+        // 与编译器一致：默认值（如 BranchNode.conditionType / flowWay）也算已填
+        const config = { ...(schema_1.NODE_DEFAULTS[node.type] ?? {}), ...(node.config ?? {}) };
+        for (const field of schema_1.NODE_REQUIRED[node.type] ?? []) {
+            if (config[field] === undefined || config[field] === null || config[field] === '') {
+                out.push(err('NODE_FIELD_REQUIRED', `节点 ${node.id}（${node.type}）缺少必填字段 ${field}`, node.id));
+            }
+        }
+    }
+    const inCount = new Map();
+    const outCount = new Map();
+    const seenEdge = new Set();
+    for (const edge of graph.edges) {
+        const key = `${edge.from}->${edge.to}`;
+        if (seenEdge.has(key)) {
+            out.push(err('EDGE_DUPLICATE', `重复连线：${key}（IDE 设置 setMultigraph(false)）`));
+        }
+        seenEdge.add(key);
+        if (!byId.has(edge.from))
+            out.push(err('EDGE_SOURCE_MISSING', `连线起点不存在：${edge.from}`));
+        if (!byId.has(edge.to))
+            out.push(err('EDGE_TARGET_MISSING', `连线终点不存在：${edge.to}`));
+        if (edge.from === edge.to)
+            out.push(err('EDGE_SELF_LOOP', `禁止自连：${edge.from}`));
+        inCount.set(edge.to, (inCount.get(edge.to) ?? 0) + 1);
+        outCount.set(edge.from, (outCount.get(edge.from) ?? 0) + 1);
+    }
+    for (const node of graph.nodes) {
+        const incoming = inCount.get(node.id) ?? 0;
+        const outgoing = outCount.get(node.id) ?? 0;
+        if (node._isStart && incoming > 0)
+            out.push(err('START_HAS_IN_EDGE', '开始节点不能有入边', node.id));
+        if (node._isEnd && outgoing > 0)
+            out.push(err('END_HAS_OUT_EDGE', '结束节点不能有出边', node.id));
+        if (!node._isEnd && outgoing === 0) {
+            out.push(err('NODE_NO_OUT_EDGE', `节点 ${node.id} 没有出边`, node.id));
+        }
+        if (!node._isStart && incoming === 0) {
+            out.push(err('NODE_NO_IN_EDGE', `节点 ${node.id} 没有入边`, node.id));
+        }
+        if (outgoing > 1 && !schema_1.MULTI_OUT_NODE_TYPES.has(node.type)) {
+            out.push(err('NODE_MULTI_OUT_EDGE', `节点 ${node.id}（${node.type}）有 ${outgoing} 条出边；仅 BranchNode / StartNode / parallelGateway 允许多出边`, node.id));
+        }
+    }
+    out.push(...validateStartNode(graph, spec, startWay));
+    return out;
+}
+function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.level === 'error');
+}

package/dist/index.js

@@ -6,12 +6,13 @@ const app_1 = require("./commands/app");
 const config_1 = require("./commands/config");
 const control_1 = require("./commands/control");
 const field_1 = require("./commands/field");
+const flow_1 = require("./commands/flow");
 const form_1 = require("./commands/form");
 const locale_1 = require("./commands/locale");
 const operation_1 = require("./commands/operation");
 const template_1 = require("./commands/template");
 const logger_1 = require("./utils/logger");
-const VERSION = '2.6.0';
+const VERSION = '2.7.0';
 const program = new commander_1.Command();
 exports.program = program;
 program
@@ -38,6 +39,7 @@ program.hook('preAction', (thisCommand, actionCommand) => {
 (0, field_1.registerFieldCommand)(program);
 (0, operation_1.registerOperationCommand)(program);
 (0, template_1.registerTemplateCommand)(program);
+(0, flow_1.registerFlowCommand)(program);
 (0, locale_1.registerLocaleCommand)(program);
 (0, control_1.registerControlCommand)(program);
 /**
@@ -114,6 +116,15 @@ ${logger_1.color.bold('常用查询')}
   llc operation create --form-id <fdId> --name 打开帮助 --code openHelp --type link --url https://example.com
   llc operation delete --id <operationId> --yes  删除业务操作（被引用时会拒绝）
   llc operation attach --form-id <fdId> --operation-id <opId>  挂到列表视图（--target view 挂查看视图）
+  llc flow list --app-code <appCode>                 应用下的动作流（只读）
+  llc flow get --id <flowId> --with-design           查看动作流并解析 fdDesign
+  llc flow spec --out flow.json                      生成 Flow Spec 模板
+  llc flow validate --spec @flow.json                离线校验（图结构 / 必填 / 布局）
+  llc flow compile --spec @flow.json --json           编译出含编排布局的 fdDesign
+  llc flow apply --spec @flow.json --app-code <code>  预览提交体（追加 --yes 才写入）
+  llc flow diff --id <flowId> --spec @flow.json        对比本地与远端设计（忽略坐标）
+  llc flow script --id <flowId>                       生成 flow_{fdCode} 按钮脚本
+  llc flow enable/disable/delete --id <flowId>         生命周期管理
 
 ${logger_1.color.gray('高级控件（desc / tags / mdm / association / mechnumber …）与普通控件同样写法：')}
   llc form autofill --id <fdId> --apply --add-field "字段名:标题:控件类型"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lan-low-code-cli",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "lan-low-code cli：低代码表单引擎命令行工具（创建表单、获取可用字段、自动完善表单字段）",
   "keywords": [
     "low-code",

package/skills/lan-low-code-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lan-low-code-cli
-version: 2.6.0
+version: 2.7.0
 author: Pig George
 description: Operate the Landray low-code form engine through the `llc` CLI. Use when the user asks to create, inspect, modify, publish, or delete low-code apps and forms; generate field configs; configure layouts (grid/tabs), field permissions, options, i18n, or control actions (onChange/onLoad); or run pre-publish validation. Also use for troubleshooting form loading/rendering errors.
 tags:
@@ -41,11 +41,11 @@ Verify: `llc -v` should print the version.
 ### Version check before upgrading
 
 Before upgrading (and whenever `llc -v` does not match this skill), compare the **major** version of the
-installed CLI with this skill's frontmatter `version:` (currently `2.4.1`):
+installed CLI with the `version:` in this skill's frontmatter:
 
 | CLI version vs skill | Action |
 |---|---|
-| Same major (`2.4.1` → e.g. `2.6.0`) | **Upgrade directly**: `npm i -g lan-low-code-cli@latest`. Non-major releases keep the flags in this skill valid. |
+| Same major (e.g. skill `2.x` → CLI `2.y`) | **Upgrade directly**: `npm i -g lan-low-code-cli@latest`. Non-major releases keep the flags in this skill valid. |
 | CLI major is higher (`2.x` skill vs `3.x` CLI) | A **major** version has been crossed: **this skill may be out of date**. Do not assume its flags/fields still exist — tell the user the skill may be stale and update it (see **Self-update** below) before running write operations. |
 | CLI major is lower | The CLI is older than the skill: upgrade the CLI first (`npm i -g lan-low-code-cli@latest`); never downgrade the skill. |
 
@@ -95,6 +95,9 @@ Always run `llc <command> --help` before inventing flags — the CLI is the sour
 | `llc field list / gen-key / library` | available fields |
 | `llc operation list / get / create / update / delete / attach / detach` | form business operations (link, script, dialog), including attaching to list/view pages |
 | `llc template list / create / add-fields / delete` | category-form templates: create/append/delete templates, porting fields/views/permissions from an existing form (auto category node, bypasses official init) |
+| `llc flow spec / compile / validate` | **offline**: generate a Flow Spec, compile it into `fdDesign` with IDE-style layout, run offline validation |
+| `llc flow list / get / category / logs / schema / templates` | **read-only** action-flow queries; `templates` extracts golden node skeletons (coordinates stripped) |
+| `llc flow apply / diff / script / enable / disable / delete` | **write** action-flow lifecycle; `apply` previews by default and needs `--yes` + `--app-code` |
 | `llc control list / show` | controls installed in the environment (basis for `--add-field` third segment) |
 | `llc locale list` | languages with translations available (from control i18n resources) |
 | `llc config set / show / clear` | global credentials and defaults |
@@ -103,6 +106,13 @@ Always run `llc <command> --help` before inventing flags — the CLI is the sour
 >
 > Runtime `context` of operation scripts (selected rows, list refresh, query, navigation, event bus,
 > `window.MKXFORM`) is documented in [references/operation-script-context.md](references/operation-script-context.md) (Chinese).
+>
+> Action flows are **application-scoped** (`--app-code`, `fdAppCode`), not form-scoped. Always start with
+> `llc flow spec --out flow.json` → `llc flow validate --spec @flow.json` → `llc flow compile --spec @flow.json --json`.
+> `llc flow apply` **only previews** until `--yes` is added, and requires an explicit `--app-code`.
+> `--layout ide` (default) reproduces the platform's branch arrangement; never hand-write `drawAttr.bounds`.
+> Full Flow Spec syntax: **§10 of [references/cli-contract.md](references/cli-contract.md)**.
+> Add `--resolve-schema` when publishing nodes that reference a data model (`sys-modeling#<fdId>`).
 
 ## 2. Core workflow
 

package/skills/lan-low-code-cli/SKILL.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 name: lan-low-code-cli
-version: 2.6.0
+version: 2.7.0
 author: Pig George
 description: 通过 `llc` CLI 操作蓝凌低代码表单引擎。适用于：创建、查看、修改、发布或删除低代码应用与表单；生成字段配置；配置布局（栅格/页签）、字段权限、选项、多语言、控件动作（onChange/onLoad）；或执行发布前校验、排查表单加载/渲染报错。
 tags:
@@ -45,7 +45,7 @@ npm i -g lan-low-code-cli            # 全局安装，获得 `llc` 命令
 
 | CLI 版本 vs skill | 处理 |
 |---|---|
-| 同一大版本（`2.4.1` → 如 `2.6.0`） | **直接升级**：`npm i -g lan-low-code-cli@latest`。非大版本升级不影响本 skill 的参数与写法。 |
+| 同一大版本（如 skill `2.x` → CLI `2.y`） | **直接升级**：`npm i -g lan-low-code-cli@latest`。非大版本升级不影响本 skill 的参数与写法。 |
 | CLI 大版本更高（skill `2.x` vs CLI `3.x`） | 已**跨大版本**：**本 skill 可能已过期**。不要假设其中的参数/字段仍然有效——告知用户 skill 可能过期，按下方**自更新**更新后再执行写操作。 |
 | CLI 大版本更低 | CLI 比 skill 旧：先升级 CLI（`npm i -g lan-low-code-cli@latest`），不要把 skill 降级。 |
 
@@ -92,6 +92,9 @@ llc config set --base-url http://<host>/data --token <X-AUTH-TOKEN>   # 一次
 | `llc field list / gen-key / library` | 可用字段 |
 | `llc operation list / get / create / update / delete / attach / detach` | 表单业务操作（链接、脚本、对话框），含挂载到列表/查看视图 |
 | `llc template list / create / add-fields / delete` | 分类表单模板：创建模板并把既有表单的字段/视图/权限移植进来，追加字段，或清理模板（自动建分类节点、跳过官方 init） |
+| `llc flow spec / compile / validate` | **纯离线**：生成 Flow Spec、编译出符合 IDE 编排布局的 `fdDesign`、离线校验 |
+| `llc flow list / get / category / logs / schema / templates` | **只读**查询动作流；`templates` 抽取 golden 节点骨架（已剥离坐标） |
+| `llc flow apply / diff / script / enable / disable / delete` | **写入**动作流全生命周期；`apply` 默认预览，需 `--yes` + `--app-code` 才提交 |
 | `llc control list / show` | 环境已安装控件（`--add-field` 第三段的取值依据） |
 | `llc locale list` | 环境中有现成译文的语言（来自控件多语言资源） |
 | `llc config set / show / clear` | 全局凭据与默认值 |
@@ -100,6 +103,13 @@ llc config set --base-url http://<host>/data --token <X-AUTH-TOKEN>   # 一次
 >
 > 业务操作「脚本模式」的运行时 `context`（选中数据、刷新列表、查询、跳转、事件总线、`window.MKXFORM`）
 > 见 [references/operation-script-context.md](references/operation-script-context.md)。
+>
+> 动作流是**应用级**对象（`--app-code` 即 `fdAppCode`），不是表单级。固定起手式：
+> `llc flow spec --out flow.json` → `llc flow validate --spec @flow.json` → `llc flow compile --spec @flow.json --json`。
+> `llc flow apply` **默认只预览**，必须追加 `--yes`，且必须显式给 `--app-code`。
+> `--layout ide`（默认）复刻平台分支编排，不要手写 `drawAttr.bounds`。
+> Flow Spec 完整语法见 [references/cli-contract.md](references/cli-contract.md) **第 10 节**。
+> 节点引用数据模型（`sys-modeling#<fdId>`）时，发布请加 `--resolve-schema`。
 
 ## 2. 核心流程
 

package/skills/lan-low-code-cli/references/cli-contract.md

@@ -18,8 +18,9 @@ llc -v | --version
 - Most commands accept `--json` for script-friendly output.
 - Exit codes: `0` success (including `--help`/`--version`); `1` failure (arguments, validation, API).
   `LLC_DEBUG=1` also prints the stack.
-- Destructive commands (`app|form delete`, `app|form delete-data`) require `--yes`; without it the CLI
-  only warns and does **not** execute.
+- Destructive commands (`app|form delete`, `app|form delete-data`, `flow delete`, `flow disable`) require
+  `--yes`; without it the CLI only warns and does **not** execute. `flow apply` also needs `--yes` —
+  by default it only prints the payload.
 - An unknown `llc help` path prints `未知命令：llc ...` and exits `1`.
 
 ## 2. config
@@ -221,7 +222,76 @@ without error but never fires, so confirm it first:
 | `--locale` | `"Cn,Us,Tw"` or `all` | comma-separated, **first entry is primary**; `all` = `Cn,Us,Tw` |
 | `--lang-file` | `{"Us":{"姓名":"Name"}}` | inner keys may be field labels or field names; options support `field#value` |
 
-## 10. Common failures
+## 10. flow (action flow / process define)
+
+Application-scoped action flows. Every write command needs `--yes` and an explicit `--app-code`
+(or `appCode` in the spec). `--json` goes to stdout; all other output goes to stderr.
+
+| Command | Required | Key options | Notes |
+|---|---|---|---|
+| `llc flow spec` | — | `--app-code` `--name` `--code` `--start-way` `--out` `--json` | prints a Flow Spec template; Start/End nodes are added by the compiler |
+| `llc flow compile` | `--spec <@file\|json>` | `--layout ide\|layered\|passthrough` `--center-x` `--rank-padding` `--lane-gap` `--min-gap` `--sub-center-x` `--emit-waypoints` `--out` `--force` `--json` | compiles to `fdDesign` (JSON string) + `basicInfo`; **offline** |
+| `llc flow validate` | `--spec` | layout options, `--json` | offline checks only; exits `1` on errors |
+| `llc flow list` | `--app-code` | `--keyword` `--status draft\|stopped\|enabled` `--page-no` `--page-size` `--json` | read-only |
+| `llc flow get` | `--id` | `--with-design` `--raw` `--json` | `--with-design` parses `fdDesign` |
+| `llc flow category list` | `--app-code` | `--keyword` `--json` | read-only |
+| `llc flow logs` | `--id` | `--limit` `--endpoint` `--json` | log endpoints differ per deployment; `--endpoint` overrides |
+| `llc flow schema` | `--kind` | `--entity-id` `--code` `--app-code` `--api-type` `--api-method-path` | read-only, always JSON. Kinds: `businessNodes` `events` `source` `jsonSchema` `condition` `out` `active` `event` `interface` `apiMethod` `flowBots` `meta` `dataModel` `recycle` |
+| `llc flow templates` | `--from <@file\|json>` | `--out` `--json` | extracts golden node skeletons from a `get` response / compile result / design; strips `drawAttr.bounds` |
+| `llc flow apply` | `--spec` `--app-code` | `--draft` `--enable` `--resolve-schema` `--strict-schema` layout options `--force` `--yes` `--json` | **preview by default**; `--yes` calls `addPublish`/`addDraft` (or `update*` when the spec has `fdId`), then reads back |
+| `llc flow diff` | `--id` `--spec` | `--no-ignore-bounds` `--resolve-schema` `--strict-schema` layout options `--json` | compares local design with remote; ignores coordinates by default |
+| `llc flow script` | `--id` | `--out` `--json` | generates a `MKXFORM.flow_<fdCode>` button script |
+| `llc flow enable` | `--id` | `--json` | `startup` |
+| `llc flow disable` | `--id` `--yes` | `--json` | `stop` |
+| `llc flow delete` | `--id` `--yes` | `--json` | checks `listByRefer` before deleting |
+
+**Flow Spec** (JSON — no new runtime dependency):
+
+```json
+{
+  "appCode": "cli-test", "name": "My flow", "code": "flow_a",
+  "startWay": "StartActiveNode", "centerX": 679,
+  "trigger": { "fdRunType": ["operate"], "fdFormRelation": "0", "dataType": 1,
+    "inParamType": 2, "inParam": { "id": "requestBody", "type": "object", "properties": {} } },
+  "nodes": [
+    { "id": "N2", "type": "QueryDataNode", "name": "query",
+      "config": { "target": { "entityId": "sys-modeling#<fdId>" }, "resultType": "single" } },
+    { "id": "N3", "type": "BranchNode", "name": "branch" },
+    { "id": "N4", "type": "TransformNode", "name": "A", "config": { "outParamType": 0 } },
+    { "id": "N5", "type": "TransformNode", "name": "B", "config": { "outParamType": 0 } }
+  ],
+  "edges": [
+    { "from": "N2", "to": "N3" },
+    { "from": "N3", "to": "N4", "name": "yes", "formula": { "type": "Script", "script": "return true" } },
+    { "from": "N3", "to": "N5", "name": "no", "default": true }
+  ]
+}
+```
+
+- `--code` must match `^[a-zA-Z0-9_]{1,30}$`; node `id` `^[0-9a-zA-Z_]{2,32}$`. Start/End nodes
+  and their edges are auto-added; disconnected roots/leaves are wired automatically.
+- **Layout**: `ide` (default) reproduces the platform's arrangement — main chain centred on
+  `--center-x` (default `679`), `BranchNode` 56×56, branch successors on the same rank at lanes ±1,
+  join one rank lower, rank spacing `maxHeight + 52`. `layered` pushes branch successors to the
+  next rank; `passthrough` keeps `bounds` from the spec. `drawAttr.bounds` uses top-left `x/y` with
+  `relative:false` and is persisted verbatim by the IDE (it never recomputes coordinates).
+- Branch handling: `defaultTargetRef` comes from the edge with `"default": true`; a
+  `formulaConfig.branchFormulas` referencing the real line IDs is generated automatically, and branch
+  edges get `exitX=0/1` anchor styles so they do not overlap in the designer.
+- `--resolve-schema` fills `extraAttr.context_*` via `getSourceJsonSchema` /
+  `getProcessDataOutJsonSchema`. Those endpoints require a `sys-modeling#` prefixed `entityId`
+  (the CLI adds it). Failures are warnings unless `--strict-schema`.
+- `fields` of `AddDataNode` / `AddOrUpdateNode` uses the platform's real shape
+  (`{field:{...},value:{format,valueJson}}`); the CLI passes it through and only validates field
+  names — it does **not** synthesise formulas. Use `llc flow templates` / `flow get` for golden shapes.
+- Publishing derives `fdProcessActive` on the backend from `startNodeDef`; `fdStatus=1` means enabled.
+  `flow logs` endpoints vary by deployment (`ModelingProcessLog/findAll` vs
+  `sysModelingLog/findAllWithAppId`); use `--endpoint` if the defaults fail.
+- Runtime trigger: `flow script` emits a `MKXFORM.flow_<fdCode>` call; attach it with
+  `llc operation create --type script --script @file` + `llc operation attach`.
+  `executeFlowForAjax` lives in the `sys-xform` runtime package, not in a documented REST endpoint.
+
+## 11. Common failures
 
 | Message | Cause / fix |
 |---|---|

package/skills/lan-low-code-cli/references/cli-contract.zh-CN.md

@@ -15,7 +15,7 @@ llc -v | --version        # 版本号
 - 配置优先级：`--base-url`/`--token` > `LLC_BASE_URL`/`LLC_TOKEN` > `./lcode.config.json`（当前目录）> `~/.lcode/config.json`（`llc config set` 写入）；`timeout` 默认 `30000` ms。
 - 多数查询/变更命令支持 `--json`（结构化输出，便于脚本处理）。
 - 退出码：`0` 成功（含 `--help`/`--version`）；`1` 失败（参数、校验、接口错误）。`LLC_DEBUG=1` 额外打印堆栈。
-- 破坏性命令（`app|form delete`、`app|form delete-data`）必须带 `--yes`，否则仅告警且**不执行**。
+- 破坏性命令（`app|form delete`、`app|form delete-data`、`flow delete`、`flow disable`）必须带 `--yes`，否则仅告警且**不执行**；`flow apply` 同样需要 `--yes`，默认只打印提交体。
 - `llc help xxx` 路径不存在时报 `未知命令：llc xxx` 并退出 `1`；未知子命令由 commander 报错（同为退出码 1）。
 
 ## 2. config
@@ -211,7 +211,74 @@ llc operation detach --form-id <fdId> --operation-id <operationId>            #
 | `--locale` | `"Cn,Us,Tw"` 或 `all` | 逗号分隔，**第一个为主语言**；`all` = `Cn,Us,Tw` |
 | `--lang-file` | `{"Us":{"姓名":"Name"}}` | 内层 key 可为字段标题或字段名；选项支持 `字段名#值` |
 
-## 10. 常见失败提示
+## 10. flow（动作流 / process define）
+
+应用级动作流（`fdAppCode`）。所有写命令都需要 `--yes` 与显式 `--app-code`（或 spec 中的 `appCode`）。
+`--json` 输出到 stdout，其余输出走 stderr。
+
+| 命令 | 必填 | 主要选项 | 说明 |
+|---|---|---|---|
+| `llc flow spec` | — | `--app-code` `--name` `--code` `--start-way` `--out` `--json` | 生成 Flow Spec 模板；开始/结束节点由编译器自动补齐 |
+| `llc flow compile` | `--spec <@文件\|json>` | `--layout ide\|layered\|passthrough` `--center-x` `--rank-padding` `--lane-gap` `--min-gap` `--sub-center-x` `--emit-waypoints` `--out` `--force` `--json` | 编译出 `fdDesign`（JSON 字符串）与 `basicInfo`；**纯离线** |
+| `llc flow validate` | `--spec` | 布局选项、`--json` | 仅离线校验；有错误退出 `1` |
+| `llc flow list` | `--app-code` | `--keyword` `--status draft\|stopped\|enabled` `--page-no` `--page-size` `--json` | 只读 |
+| `llc flow get` | `--id` | `--with-design` `--raw` `--json` | `--with-design` 解析 `fdDesign` |
+| `llc flow category list` | `--app-code` | `--keyword` `--json` | 只读 |
+| `llc flow logs` | `--id` | `--limit` `--endpoint` `--json` | 日志端点因部署而异；`--endpoint` 可覆盖 |
+| `llc flow schema` | `--kind` | `--entity-id` `--code` `--app-code` `--api-type` `--api-method-path` | 只读、恒为 JSON。kind：`businessNodes` `events` `source` `jsonSchema` `condition` `out` `active` `event` `interface` `apiMethod` `flowBots` `meta` `dataModel` `recycle` |
+| `llc flow templates` | `--from <@文件\|json>` | `--out` `--json` | 从 `get` 响应 / 编译结果 / 设计对象抽取 golden 节点骨架；剥离 `drawAttr.bounds` |
+| `llc flow apply` | `--spec` `--app-code` | `--draft` `--enable` `--resolve-schema` `--strict-schema` 布局选项 `--force` `--yes` `--json` | **默认预览**；`--yes` 才调用 `addPublish`/`addDraft`（spec 带 `fdId` 时走 `update*`），随后回读 |
+| `llc flow diff` | `--id` `--spec` | `--no-ignore-bounds` `--resolve-schema` `--strict-schema` 布局选项 `--json` | 对比本地与远端设计；默认忽略坐标 |
+| `llc flow script` | `--id` | `--out` `--json` | 生成 `MKXFORM.flow_<fdCode>` 按钮脚本 |
+| `llc flow enable` | `--id` | `--json` | `startup` |
+| `llc flow disable` | `--id` `--yes` | `--json` | `stop` |
+| `llc flow delete` | `--id` `--yes` | `--json` | 删除前先查 `listByRefer` |
+
+**Flow Spec**（JSON，不引入新的运行时依赖）：
+
+```json
+{
+  "appCode": "cli-test", "name": "示例流程", "code": "flow_a",
+  "startWay": "StartActiveNode", "centerX": 679,
+  "trigger": { "fdRunType": ["operate"], "fdFormRelation": "0", "dataType": 1,
+    "inParamType": 2, "inParam": { "id": "requestBody", "type": "object", "properties": {} } },
+  "nodes": [
+    { "id": "N2", "type": "QueryDataNode", "name": "查询",
+      "config": { "target": { "entityId": "sys-modeling#<fdId>" }, "resultType": "single" } },
+    { "id": "N3", "type": "BranchNode", "name": "条件分支" },
+    { "id": "N4", "type": "TransformNode", "name": "分支A", "config": { "outParamType": 0 } },
+    { "id": "N5", "type": "TransformNode", "name": "分支B", "config": { "outParamType": 0 } }
+  ],
+  "edges": [
+    { "from": "N2", "to": "N3" },
+    { "from": "N3", "to": "N4", "name": "是", "formula": { "type": "Script", "script": "return true" } },
+    { "from": "N3", "to": "N5", "name": "否", "default": true }
+  ]
+}
+```
+
+- `--code` 需匹配 `^[a-zA-Z0-9_]{1,30}$`；节点 `id` 需匹配 `^[0-9a-zA-Z_]{2,32}$`。
+  开始/结束节点及其连线自动补齐，无入边/无出边的业务节点自动接线。
+- **布局**：`ide`（默认）复刻平台编排——主链以 `--center-x`（默认 `679`）居中，`BranchNode`
+  为 56×56，分支后继与分支节点同层、泳道 ±1，汇聚下移一层，层距 = 该层最高节点 + 52。
+  `layered` 把分支后继放到下一层；`passthrough` 沿用 spec 中的 `bounds`。
+  `drawAttr.bounds` 是左上角 `x/y` 且带 `relative:false`，IDE **原样持久化、不会重算坐标**。
+- 分支处理：`defaultTargetRef` 取自 `"default": true` 的出边；自动生成引用真实连线 ID 的
+  `formulaConfig.branchFormulas`；分支连线写入 `exitX=0/1` 锚点，避免 IDE 内两条线重叠。
+- `--resolve-schema` 通过 `getSourceJsonSchema` / `getProcessDataOutJsonSchema` 补齐
+  `extraAttr.context_*`。这两个端点要求 `entityId` 带 `sys-modeling#` 前缀（CLI 自动补）。
+  失败默认只告警，`--strict-schema` 时升级为错误。
+- `AddDataNode` / `AddOrUpdateNode` 的 `fields` 使用平台真实结构
+  （`{field:{...},value:{format,valueJson}}`）；CLI 原样透传并只校验字段名，**不臆造公式**。
+  需要真实结构请用 `llc flow templates` / `flow get` 抽取 golden 骨架。
+- 发布时后端从 `startNodeDef` 派生 `fdProcessActive`；`fdStatus=1` 表示已启用。
+  `flow logs` 端点因部署而异（`ModelingProcessLog/findAll` 与
+  `sysModelingLog/findAllWithAppId`）；默认都失败时用 `--endpoint` 指定。
+- 运行时触发：`flow script` 生成 `MKXFORM.flow_<fdCode>` 调用，可用
+  `llc operation create --type script --script @文件` + `llc operation attach` 挂载。
+  `executeFlowForAjax` 位于 `sys-xform` 运行时包，没有文档化的 REST 端点。
+
+## 11. 常见失败提示
 
 | 提示 | 原因与处理 |
 |---|---|