lan-low-code-cli 2.5.0 → 2.7.0

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
@@ -73,7 +74,96 @@ The `general` family only supports `general` (approval-opinion) forms; `modeling
 `type=refer` does not store `fdConfig`.
 `--type` values: `common|general|config|modal|template|refer` (or `1..6`; Chinese names also work).
 
-## 5. field
+### 4.1 Category forms / simple category forms (`--type category|simpleCategory`)
+
+Uses the `categoryModel` family (`/data/sys-modeling/categoryModel/`), independent from normal forms:
+
+| `--type` | `fdType` | Tables | Notes |
+|---|---|---|---|
+| `category` (alias `categoryForm`) | 1 | category + template + main | category tree with multiple templates |
+| `simpleCategory` (alias `simpleCategoryForm`) | 2 | polymers + main | category and template merged; always multi-level; no shared category |
+
+```bash
+llc form create --name "Purchase categories" --app-id <appId> --type category --publish
+llc form create --name "Simple categories" --app-id <appId> --type simpleCategory --publish
+```
+
+- Flow: `categoryModel/init` → `categoryModel/add` → (with `--publish`: `get` + `save` + `publish`);
+- Extra options: `--category-table-name` `--template-table-name` `--polymers-table-name` `--share-category <fdCode>` `--no-support-hierarchy`;
+- Table names default to `sysModelingXForm/generateTableName`; `--table-name` is still the main table;
+- **Limits**: category forms carry no business fields, so `--add-field` / `--fields` / `--from-model` are rejected;
+  templates must be created in the platform's launch-page designer (the template table metadata is generated
+  there on first save), calling `categoryTemplate/init` directly returns a null-pointer error;
+- deletion is platform-only (`categoryModel/delete` rejects direct client calls); `form get --id` reads category forms.
+
+### 4.2 Category form templates (`llc template`)
+
+| Command | Required | Optional | Notes |
+|---|---|---|---|
+| `llc template list` | `--category-code` | `--json` | runtime tree (category nodes + template cards) |
+| `llc template create` | `--category-code` `--name` | `--from-form <fdId>` `--fields <names>` `--table-name` `--category-node <fdId>` `--category-name` `--code` `--publish` `--dry-run` `--json` | creates a template, optionally porting fields/views/permissions from an existing form |
+| `llc template add-fields` | `--template-id` `--add-field` | `--category-code` `--per-row` `--keep-layout` `--publish` `--dry-run` `--json` | appends fields to an existing template; rebuilds a grid layout by default, `--keep-layout` keeps the current one |
+| `llc template delete` | `--category-code` | `--template-id <fdId>` (repeatable) `--all` `--yes` `--json` | deletes templates; `--all` wipes every template of that category form |
+
+- Category forms (`fdType=1`) use `categoryTemplate/add`; simple category forms (`fdType=2`) use `virtualPolymers/add`;
+  read/write through `virtualCommonTemplate/get|save|publish`;
+- **Skips the official `init`** (null pointer until the template table metadata exists): `add` carries
+  `mechanisms['sys-xform'].fdBuildNew=true` so the backend creates the table, then `sys-xform/sysXFormDesign/save` writes the design;
+- `--from-form` clones the source form's main-table business fields, view layout (tabs/grid) and field permissions,
+  replacing table names and dropping detail nodes; `--fields` limits the ported fields;
+- Category-form templates must sit under a category node: without `--category-node` one is created
+  (name from `--category-name`).
+
+## 5. operation (form business operations)
+
+Adds buttons to a form's list/view page (the "业务操作" tab of a form). Built-in operations (`fdType=1`) are
+maintained by the platform; the CLI only lists them and manages **custom** operations.
+
+| Command | Required | Optional | Notes |
+|---|---|---|---|
+| `llc operation list` | `--form-id <fdId>` | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=100` `--json` | lists a form's operations (built-ins included) |
+| `llc operation get` | `--id <fdId>` | `--json` | detail; prints the parsed `fdConfig` |
+| `llc operation create` | `--form-id` `--name` `--code` `--type` | `--position list\|view` `--need-select` `--url` `--script <code\|@file>` `--dialog-id` `--desc` `--mobile-icon` `--dry-run` `--json` | creates an operation definition |
+| `llc operation update` | `--id <fdId>` | `--name` `--code` `--desc` `--position` `--type` `--url` `--script <code\|@file>` `--dialog-id` `--need-select`/`--no-need-select` `--enable`/`--disable` `--mobile-icon` `--dry-run` `--json` | edits an existing operation; `--type script` switches a button to script mode |
+| `llc operation delete` | `--id <fdId>` `--yes` | — | checks references (`listByRefer`) and refuses while still in use |
+| `llc operation attach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform desktop\|mobile` `--position top\|rightHand\|rightSide` | writes the button into the view `operationList`; auto-detects the single view when `--view-id` is omitted |
+| `llc operation detach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform` | removes the button from a view (definition kept) |
+
+`--type` (P0 supports three):
+
+| type | fdType | fdViewType | Required | Notes |
+|---|---|---|---|---|
+| `link` | 2 | 4 | `--url` | open a link |
+| `script` | 3 | 5 | `--script` (`@file` supported) | run a script |
+| `dialog` | 3 | 1 | `--dialog-id` | run a dialog |
+
+```bash
+llc operation list --form-id <fdId>
+llc operation create --form-id <fdId> --name 打开帮助 --code openHelp \
+  --type link --position view --url https://example.com
+llc operation create --form-id <fdId> --name 批量归档 --code archive \
+  --type script --script @archive.js
+llc operation get --id <operationId>
+llc operation update --id <operationId> --type script --script @examples/operation-script-modal-table.js
+llc operation delete --id <operationId> --yes
+llc operation attach --form-id <fdId> --operation-id <operationId>            # list view / desktop / top
+llc operation attach --form-id <fdId> --operation-id <operationId> --target view --position rightHand
+llc operation detach --form-id <fdId> --operation-id <operationId>            # remove from list view
+```
+
+- `--code`: starts with a letter, letters/digits/underscore/hyphen only, ≤15; `--name` ≤30; `--desc` ≤500.
+- New operations are **admin-only by default**; set visitors on the platform's "业务操作" page.
+- No row selection is required by default (`fdListViewIdValid=false`); pass `--need-select` when the button
+  must run on selected rows (for links this also sets `fdUrlType=2`, i.e. call the link as an API).
+- `attach` / `detach` only touch view config: list views use `fdExtendConfig[platform].operationList`,
+  view pages use `fdConfig[platform].operationList`; the whole config is saved back, so other settings and
+  existing buttons are preserved, and re-attaching is idempotent.
+- `--position`: `top` (toolbar), `rightHand` / `rightSide` (row actions); `--platform` accepts `desktop` / `mobile`.
+- Permissions, display conditions and triggers are still out of scope; `attach` does not validate the
+  operation's `fdPosition` and only warns on a mismatch.
+- `--dry-run` prints the payload (`fdConfig` is a JSON string) without sending it.
+
+## 6. field
 
 | Command | Options | Notes |
 |---|---|---|
@@ -81,7 +171,7 @@ The `general` family only supports `general` (approval-opinion) forms; `modeling
 | `llc field library` | `--keyword <kw>` (`fdName` contains), `--page-no <n>=1`, `--page-size <n>=20`, `--json` | environment field library |
 | `llc field gen-key` | `--name <name>`, `--table <table>` | generates the physical field key |
 
-## 6. control / locale
+## 7. control / locale
 
 | Command | Options | Notes |
 |---|---|---|
@@ -89,7 +179,7 @@ The `general` family only supports `general` (approval-opinion) forms; `modeling
 | `llc control show` | `--element <@elem/xform-xxx>` or `--type <moneytext>`, `--json` | widget metadata plus property-panel items and defaults |
 | `llc locale list` | `--element <pkg>` (default `@elem/xform-input`), `--json` | returns the raw code (e.g. `zh-cn`) and the normalized code (e.g. `Cn`, usable in `--locale`); all environment locales are not exposed by any API |
 
-## 7. Which events a control supports
+## 8. Which events a control supports
 
 `$global` actions are fixed to `onLoad` / `onBeforeSubmit` / `onAfterSubmit` (validated by the CLI).
 
@@ -115,7 +205,7 @@ without error but never fires, so confirm it first:
 > §8 of `references/mkxform-api.md` (`MKXFORM.onChange/beforeSubmit/afterSubmit`) is the **runtime
 > listener API**, not the same event set as control actions — do not mix them up.
 
-## 8. Spec strings
+## 9. Spec strings
 
 | Option | Syntax | Notes |
 |---|---|---|
@@ -126,13 +216,82 @@ without error but never fires, so confirm it first:
 | `--tabs` | `"Title:field1,field2\|Title2:field3"` | `--layout tabs` only; unlisted fields go to a trailing "其它" tab |
 | `--required`/`--readonly`/`--hidden` | `"field1,field2"` | add/edit required, add/edit read-only, add/edit/view hidden |
 | `--auth-file` | `{"add":{"fd_col_a":{"required":true}}}` | keys `add`/`edit`/`view`, merged with the flags above |
-| `--action` | `"field:event:source"` or `"field:event:@file.js"` | repeatable; `$global` accepts only `onLoad`/`onBeforeSubmit`/`onAfterSubmit`; see §7 for how to find control events |
+| `--action` | `"field:event:source"` or `"field:event:@file.js"` | repeatable; `$global` accepts only `onLoad`/`onBeforeSubmit`/`onAfterSubmit`; see §8 for how to find control events |
 | `--action-file` | `{"field":{"onChange":"source"},"$global":{"onLoad":"source"}}` or `[{target,event,source,name?}]` | merged with `--action` |
 | `--relation` | `"field=TargetForm[:显示值=field][:显示项=field1,field2]"` | target may be a form name or `fdId`; writes `relationCfg` + `datasource` |
 | `--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` |
 
-## 9. 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
@@ -68,7 +68,95 @@ llc -v | --version        # 版本号
 `general` 族只支持 `general`（审批意见表单）；`modeling` 必须给 `--app-id`；`type=refer` 不保存 `fdConfig`。
 `--type` 取值：`common|general|config|modal|template|refer`（数字 `1..6`，中文名亦可）。
 
-## 5. field
+### 4.1 分类表单 / 简单分类表单（`--type category|simpleCategory`）
+
+走 `categoryModel` 接口族（`/data/sys-modeling/categoryModel/`），与普通表单完全独立：
+
+| `--type` | `fdType` | 表结构 | 说明 |
+|---|---|---|---|
+| `category`（别名 `categoryForm`） | 1 | 分类表 + 模板表 + 主表 | 分类树 + 多个模板 |
+| `simpleCategory`（别名 `simpleCategoryForm`） | 2 | 聚合表 + 主表 | 分类与模板合一，强制多层级，不支持共享分类 |
+
+```bash
+llc form create --name "采购分类表单" --app-id <appId> --type category --publish
+llc form create --name "简版分类表单" --app-id <appId> --type simpleCategory --publish
+```
+
+- 链路：`categoryModel/init` → `categoryModel/add` →（`--publish` 时 `get` + `save` + `publish`）；
+- 专属选项：`--category-table-name` `--template-table-name` `--polymers-table-name` `--share-category <fdCode>` `--no-support-hierarchy`；
+- 表名缺省逐个调用 `sysModelingXForm/generateTableName`；`--table-name` 仍是主表名；
+- **限制**：分类表单本身没有业务字段，`--add-field` / `--fields` / `--from-model` 会被拒绝；
+  模板（模板表单）需在平台「发起页设计器」创建——模板表元数据由设计器首次保存生成，
+  CLI 直接调用 `categoryTemplate/init` 会返回空指针异常；
+- 删除只能在平台操作（`categoryModel/delete` 禁止前端调用）；`form get --id` 可读取分类表单详情。
+
+### 4.2 分类表单模板（`llc template`）
+
+| 命令 | 必需 | 可选 | 说明 |
+|---|---|---|---|
+| `llc template list` | `--category-code` | `--json` | 运行时分类树（分类节点 + 模板卡片） |
+| `llc template create` | `--category-code` `--name` | `--from-form <fdId>` `--fields <names>` `--table-name` `--category-node <fdId>` `--category-name` `--code` `--publish` `--dry-run` `--json` | 创建模板，可把来源表单的业务字段/视图/权限移植进来 |
+| `llc template add-fields` | `--template-id` `--add-field` | `--category-code` `--per-row` `--keep-layout` `--publish` `--dry-run` `--json` | 向已有模板追加字段；默认重建为栅格布局（新字段可见），`--keep-layout` 保留原布局 |
+| `llc template delete` | `--category-code` | `--template-id <fdId>`（可重复） `--all` `--yes` `--json` | 删除模板；`--all` 清空该分类表单下的全部模板 |
+
+- 分类表单（`fdType=1`）走 `categoryTemplate/add`，简单分类（`fdType=2`）走 `virtualPolymers/add`；
+  读写统一用 `virtualCommonTemplate/get|save|publish`；
+- **跳过官方 `init`**（模板表元数据未就绪时必空指针）：`add` 时带 `mechanisms['sys-xform'].fdBuildNew=true`
+  让后端建表并注册元数据，再用 `sys-xform/sysXFormDesign/save` 写入设计；
+- `--from-form` 克隆来源表单主表的业务字段、视图布局（页签/栅格）与字段权限，
+  表名替换为模板表，**明细节点剔除**；`--fields` 可只取部分字段；
+- 分类表单的模板必须挂在分类节点下：不传 `--category-node` 时自动新建节点（`--category-name` 指定名称）。
+
+## 5. operation（表单业务操作）
+
+在表单的列表页/查看页上增加按钮（对应平台「表单 → 业务操作」Tab）。内置按钮（`fdType=1`）由平台维护，
+这里只负责查询与**自定义**操作的增删。
+
+| 命令 | 必需 | 可选 | 说明 |
+|---|---|---|---|
+| `llc operation list` | `--form-id <fdId>` | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=100` `--json` | 按表单列出操作（含内置） |
+| `llc operation get` | `--id <fdId>` | `--json` | 详情；默认展开 `fdConfig` JSON |
+| `llc operation create` | `--form-id` `--name` `--code` `--type` | `--position list\|view` `--need-select` `--url` `--script <code\|@file>` `--dialog-id` `--desc` `--mobile-icon` `--dry-run` `--json` | 新建操作定义 |
+| `llc operation update` | `--id <fdId>` | `--name` `--code` `--desc` `--position` `--type` `--url` `--script <code\|@file>` `--dialog-id` `--need-select`/`--no-need-select` `--enable`/`--disable` `--mobile-icon` `--dry-run` `--json` | 修改已有操作；`--type script` 可把按钮切换为脚本模式 |
+| `llc operation delete` | `--id <fdId>` `--yes` | — | 先查引用（`listByRefer`），被引用时拒绝删除 |
+| `llc operation attach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform desktop\|mobile` `--position top\|rightHand\|rightSide` | 把按钮写入视图 `operationList`；省略 `--view-id` 时自动定位唯一视图 |
+| `llc operation detach` | `--form-id` `--operation-id` | `--target list\|view` `--view-id` `--platform` | 从视图移除按钮（保留操作定义） |
+
+`--type` 取值（P0 仅三种）：
+
+| type | fdType | fdViewType | 必填参数 | 说明 |
+|---|---|---|---|---|
+| `link` | 2 | 4 | `--url` | 打开链接 |
+| `script` | 3 | 5 | `--script`（`@file` 读文件） | 执行脚本 |
+| `dialog` | 3 | 1 | `--dialog-id` | 执行对话框（业务操作） |
+
+```bash
+llc operation list --form-id <fdId>
+llc operation create --form-id <fdId> --name 打开帮助 --code openHelp \
+  --type link --position view --url https://example.com
+llc operation create --form-id <fdId> --name 批量归档 --code archive \
+  --type script --script @archive.js
+llc operation get --id <operationId>
+llc operation update --id <operationId> --type script --script @examples/operation-script-modal-table.js
+llc operation delete --id <operationId> --yes
+llc operation attach --form-id <fdId> --operation-id <operationId>            # 列表视图 / desktop / top
+llc operation attach --form-id <fdId> --operation-id <operationId> --target view --position rightHand
+llc operation detach --form-id <fdId> --operation-id <operationId>            # 从列表视图移除
+```
+
+约束与说明：
+
+- `--code`：字母开头，仅字母/数字/下划线/连字符，≤15；`--name` ≤30；`--desc` ≤500。
+- 新建操作**默认仅管理员可用**，可访问者需到平台「业务操作」中设置。
+- 默认**不要求勾选数据**（`fdListViewIdValid=false`）；需要“先勾选数据再执行”时加 `--need-select`
+  （链接类型会同时把 `fdUrlType` 置为 `2`，按接口调用）。
+- `attach` / `detach` 只改视图配置：列表视图写 `fdExtendConfig[platform].operationList`，查看视图写
+  `fdConfig[platform].operationList`；整体覆盖保存时会保留其它配置与已有按钮，重复挂载幂等。
+- `--position`：`top`（工具栏）、`rightHand` / `rightSide`（行右侧）；`--platform` 支持 `desktop` / `mobile`。
+- 仍不处理权限公式、显示条件、触发器；`attach` 不校验操作的 `fdPosition`，目标页面不匹配时仅告警。
+- `--dry-run` 打印请求体（`fdConfig` 为 JSON 字符串），建议先在测试环境核对再提交。
+
+## 6. field
 
 | 命令 | 选项 | 说明 |
 |---|---|---|
@@ -76,7 +164,7 @@ llc -v | --version        # 版本号
 | `llc field library` | `--keyword <kw>`（模糊匹配 fdName）、`--page-no <n>=1`、`--page-size <n>=20`、`--json` | 环境字段库 |
 | `llc field gen-key` | `--name <name>`、`--table <table>` | 生成字段物理名（fdKey） |
 
-## 6. control / locale
+## 7. control / locale
 
 | 命令 | 选项 | 说明 |
 |---|---|---|
@@ -84,7 +172,7 @@ llc -v | --version        # 版本号
 | `llc control show` | `--element <@elem/xform-xxx>` 或 `--type <moneytext>`、`--json` | 控件元数据 + 属性面板配置项与默认值 |
 | `llc locale list` | `--element <pkg>`（默认 `@elem/xform-input`）、`--json` | 返回原始码（如 `zh-cn`）与归一化码（如 `Cn`，可直接用于 `--locale`）；环境全量语言无接口暴露 |
 
-## 7. 控件动作支持的事件（如何获取）
+## 8. 控件动作支持的事件（如何获取）
 
 `$global` 全局动作固定 3 个：`onLoad` / `onBeforeSubmit` / `onAfterSubmit`（CLI 会校验，写错直接报错）。
 
@@ -106,7 +194,7 @@ llc -v | --version        # 版本号
 > `references/mkxform-api.md` 第 8 节的 `MKXFORM.onChange/beforeSubmit/afterSubmit` 是**运行时监听 API**，
 > 与这里的「控件动作」不是同一套事件，不要混用。
 
-## 8. 规格字符串（spec）速查
+## 9. 规格字符串（spec）速查
 
 | 选项 | 语法 | 说明 |
 |---|---|---|
@@ -117,13 +205,80 @@ llc -v | --version        # 版本号
 | `--tabs` | `"标题:字段1,字段2\|标题2:字段3"` | 仅 `--layout tabs`；未列出的字段归入末尾「其它」页 |
 | `--required`/`--readonly`/`--hidden` | `"字段1,字段2"` | 分别写入 add/edit 必填、add/edit 只读、add/edit/view 隐藏 |
 | `--auth-file` | `{"add":{"fd_col_a":{"required":true}}}` | 键为 `add`/`edit`/`view`，与上述开关合并 |
-| `--action` | `"字段名:事件:函数源码"` 或 `"字段名:事件:@file.js"` | 可重复；`$global` 仅 `onLoad`/`onBeforeSubmit`/`onAfterSubmit`；控件级事件如何获取见第 7 节 |
+| `--action` | `"字段名:事件:函数源码"` 或 `"字段名:事件:@file.js"` | 可重复；`$global` 仅 `onLoad`/`onBeforeSubmit`/`onAfterSubmit`；控件级事件如何获取见第 8 节 |
 | `--action-file` | `{"字段名":{"onChange":"源码"},"$global":{"onLoad":"源码"}}` 或 `[{target,event,source,name?}]` | 与 `--action` 合并 |
 | `--relation` | `"字段名=目标表单[:显示值=字段][:显示项=字段1,字段2]"` | 目标可写表单名或 `fdId`；写入 `relationCfg` + `datasource` |
 | `--locale` | `"Cn,Us,Tw"` 或 `all` | 逗号分隔，**第一个为主语言**；`all` = `Cn,Us,Tw` |
 | `--lang-file` | `{"Us":{"姓名":"Name"}}` | 内层 key 可为字段标题或字段名；选项支持 `字段名#值` |
 
-## 9. 常见失败提示
+## 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. 常见失败提示
 
 | 提示 | 原因与处理 |
 |---|---|