lan-low-code-cli 2.4.0 → 2.6.0

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

@@ -0,0 +1,233 @@
+# llc CLI contract (commands and options)
+
+Command tree, options, spec-string syntax and exit codes for `llc` (lan-low-code-cli).
+`llc <command> --help` and actual behaviour are authoritative.
+
+## 1. Invocation
+
+```bash
+llc <group> <subcommand> [options]
+llc help [command...]        # multi-level, e.g. llc help form create
+llc -v | --version
+```
+
+- Global options `--base-url <url>` / `--token <token>` work before or after the subcommand
+  (root options are forwarded via a `preAction` hook).
+- Precedence: `--base-url`/`--token` > `LLC_BASE_URL`/`LLC_TOKEN` > `./lcode.config.json` (cwd) >
+  `~/.lcode/config.json` (written by `llc config set`). `timeout` defaults to `30000` ms.
+- 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.
+- An unknown `llc help` path prints `未知命令：llc ...` and exits `1`.
+
+## 2. config
+
+| Command | Options | Notes |
+|---|---|---|
+| `llc config set` | `--base-url <url>` `--token <token>` `--timeout <ms>` `--default-form-type <n>` | merges into the global config; with no options it only prints usage |
+| `llc config show` | — | JSON: global/project config paths, baseUrl, masked token (`abcd****wxyz`), timeout, defaultFormType, controlMapKeys, env vars |
+| `llc config clear` | `--all` | clears `baseUrl`/`token`; `--all` also `timeout`/`defaultFormType`/`controlMap` |
+
+## 3. app
+
+| Command | Required | Optional | Notes |
+|---|---|---|---|
+| `llc app list` | — | `--keyword <name>` `--no-auth` `--json` | columns `fdId/应用名称/应用编码/状态`; `fdId` is the `--app-id`; `--no-auth` uses the no-auth endpoint |
+| `llc app get` | `--id <fdId>` | `--json` | detail (code/description/visitors/maintainers) |
+| `llc app create` | `--name <name>` | `--code <code>` `--desc <text>` `--category <fdId>` `--icon <name\|json>` `--order <n>` `--json` | backend also creates the default home page; `--json` returns `{fdId}` |
+| `llc app update` | `--id <fdId>` | `--name` `--code` `--desc` `--category` `--icon` `--order` | loads the detail first, then patches; warns if nothing to change |
+| `llc app forms` | `--id <fdId>` | `--json` | forms under the app (preview before delete) |
+| `llc app delete` | `--id <fdId>` `--yes` | — | lists the forms that will be deleted along with the app |
+| `llc app delete-data` | `--id <fdId>` `--yes` | — | deletes business data only |
+
+`--code` must match `^[a-zA-Z0-9-]+$` (letters/digits/hyphen; **no underscore**).
+
+## 4. form
+
+| Command | Required | Optional | Notes |
+|---|---|---|---|
+| `llc form create` | `--name <name>` | see groups below | creates the form and generates field config from the data model |
+| `llc form list` | — | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=20` `--json` | **`generalFormDefine` only (approval-opinion forms)**; use `app forms` for app forms |
+| `llc form get` | `--id <fdId>` | `--with-config` `--json` | reads modeling → general → design; prints JSON by default |
+| `llc form publish` | `--id <fdId>` | `--api <family>` `--desc <text>` | modeling uses `saveDesignAndPublish` |
+| `llc form autofill` | `--id <fdId>` | field groups + `--apply` `--publish` `--from-model` `--icon` | rebuilds field config from the data model; **without `--apply` it only previews** |
+| `llc form category-list` | — | `--json` | form categories (max 1000) |
+| `llc form delete` | `--id <fdId>` `--yes` | — | deletes the data model too (irreversible) |
+| `llc form delete-data` | `--id <fdId>` `--yes` | — | runtime data only |
+
+`create` / `autofill` share these option groups:
+
+- **Basics** (create only): `--code <code>` (auto-generated by default), `--type <type>`, `--source-form-id <fdId>` (required for `type=refer`), `--category <fdId>`, `--readers <ids>`, `--editors <ids>`, `--icon <icon>`.
+- **API family** (create only): `--api auto|modeling|general|design`, `--app-id <appId>`, `--fd-entity-id` `--fd-entity-name` `--fd-entity-key` `--fd-run-entity-name`, `--table-name`, `--group-id`, `--edit-draft`/`--no-edit-draft`, `--reader-flag`, `--data-source-id`, `--outer-mapping`, `--mechanism-entity-name` `--mechanism-entity-code`.
+- **Fields**: `--from-model <fdId>`, `--fields <names>`, `--add-field <spec>`, `--option <spec>`, `--org-type <spec>`, `--detail <spec>`, `--include-system`.
+- **Layout**: `--per-row <n>` (default 2), `--span <n>`, `--layout rows|grid|tabs`, `--grid-columns <n>`, `--tabs <spec>`, `--tab-layout rows|grid`.
+- **Permissions**: `--required <fields>` `--readonly <fields>` `--hidden <fields>`, `--auth-file <path>`.
+- **Actions / relations**: `--action <spec>`, `--action-file <path>`, `--relation <spec>`.
+- **i18n**: `--locale <locales>`, `--lang-file <path>`.
+- **Execution**: `--no-config`, `--dry-run` (create only; prints the request body), `--publish`, `--force` (skip required-prop validation), `--json`.
+
+`--api auto` rules: `--app-id` given → `modeling`; `--type` omitted or `general` → `general`; otherwise `design`.
+The `general` family only supports `general` (approval-opinion) forms; `modeling` requires `--app-id`;
+`type=refer` does not store `fdConfig`.
+`--type` values: `common|general|config|modal|template|refer` (or `1..6`; Chinese names also work).
+
+### 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 |
+|---|---|---|
+| `llc field list` | `--form-id <fdId>` / `--model-id <fdId>` / `--table <tableName>` (at least one), `--json` | errors when all three are missing; columns 字段名/标题/数据类型/控件类型/长度/系统字段/uuid |
+| `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 |
+
+## 7. control / locale
+
+| Command | Options | Notes |
+|---|---|---|
+| `llc control list` | `--kind control\|layout\|appearance` (default `control`), `--all`, `--json` | remark marks 已登记/容器类/支持选项/已废弃/需设计器配置 |
+| `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 |
+
+## 8. Which events a control supports
+
+`$global` actions are fixed to `onLoad` / `onBeforeSubmit` / `onAfterSubmit` (validated by the CLI).
+
+Control-level events are defined by the **widget package implementation**. The CLI has no built-in
+whitelist and does not check whether a control supports a given event: `--action` only requires a valid
+identifier (`^[A-Za-z_$][\w$]*$`, e.g. `onChange`/`onFocus`/`onBlur`). An unsupported event is saved
+without error but never fires, so confirm it first:
+
+1. **Designer property panel** (authoritative): select the control in the form designer → "控件动作"
+   group → event dropdown. That list is the set the control supports.
+2. **Widget metadata** (auxiliary): `llc control show --element @elem/xform-<short> --json` returns the
+   package `config.json` verbatim under `meta`; the CLI only parses `xform` (type/dataType/dictType, …)
+   and `config` (property-panel items) and **does not parse events** — if the package happens to declare
+   them (`meta.events`, `meta.xform.events`), use them directly; otherwise fall back to the other options.
+   The human-readable output does not print those keys, so **use `--json`**.
+3. **Inspect existing forms**: in `llc form get --id <fdId>` output, the keys of
+   `fdConfig.attribute.formAttr.controlAction.control['<table>.<controlUuid>']` are the events already
+   configured for that control; `llc form autofill --id <fdId> --json` (without `--apply`) previews the
+   action structure that would be written.
+4. **Widget frontend source**: events are the callback props the widget emits (`onChange` / `onBlur` /
+   `onFocus` / `onClick`, …). Use the `@elem/xform-*` source or widget docs only if the above fails.
+
+> §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.
+
+## 9. Spec strings
+
+| Option | Syntax | Notes |
+|---|---|---|
+| `--add-field` | `"name:label[:dataType\|controlType[:controlType]]"` | repeatable; the 3rd token accepts `varchar`/`number` or a control type such as `select`/`moneytext`; an existing field name only gets its label and control type overwritten |
+| `--option` | `"field=option1,option2:value2"` | repeatable, merged per field; without `:value` values are `1..n` |
+| `--org-type` | `"field=org,dept,person"` | codes `1` org / `2` dept / `4` post / `8` person / `16` user group / `256` identity; `all` = org+dept+post+person+user group |
+| `--detail` | `"DetailTitle=field:label[:controlType],field2:label2"` | repeatable; an existing detail table is reused and adjusted |
+| `--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 §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` |
+
+## 10. Common failures
+
+| Message | Cause / fix |
+|---|---|
+| `缺少必要配置：baseUrl ... token ...` | no credentials; run `llc config set` or pass `--base-url`/`--token` |
+| `未知的控件类型：xxx，可选值：...` | wrong 3rd token in `--add-field`; check `llc control list` |
+| `"detail" 是容器类控件，不能用 --add-field 创建` | use `--detail`; `bigDetail`/`paged` are unsupported |
+| `控件必填属性校验失败（共 N 项），已中止保存/发布` | fix the listed props; `--force` skips the check |
+| `未获取到数据模型字段，无法自动完善` | `form autofill` found no data model; check `--id` / `--from-model` |
+| `未知命令：llc ...` | wrong `llc help <command...>` path |

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

@@ -0,0 +1,223 @@
+# llc CLI 契约（命令与参数）
+
+`llc`（lan-low-code-cli）的命令树、选项、规格字符串语法与退出码。
+以 `llc <command> --help` 与实际执行结果为准。
+
+## 1. 调用约定
+
+```bash
+llc <命令组> <子命令> [选项]
+llc help [命令...]        # 多级帮助，如 llc help form create
+llc -v | --version        # 版本号
+```
+
+- 全局选项 `--base-url <url>`、`--token <token>`：写在子命令前后均可（根部选项经 preAction 透传）。
+- 配置优先级：`--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`，否则仅告警且**不执行**。
+- `llc help xxx` 路径不存在时报 `未知命令：llc xxx` 并退出 `1`；未知子命令由 commander 报错（同为退出码 1）。
+
+## 2. config
+
+| 命令 | 选项 | 说明 |
+|---|---|---|
+| `llc config set` | `--base-url <url>` `--token <token>` `--timeout <ms>` `--default-form-type <n>` | 合并写入全局配置；无任何参数时仅提示用法 |
+| `llc config show` | — | JSON：全局/项目配置路径、baseUrl、脱敏 token（`abcd****wxyz`）、timeout、defaultFormType、controlMapKeys、环境变量 |
+| `llc config clear` | `--all` | 默认只清 `baseUrl`/`token`；`--all` 追加清 `timeout`/`defaultFormType`/`controlMap` |
+
+## 3. app（业务建模应用）
+
+| 命令 | 必需 | 可选 | 说明 |
+|---|---|---|---|
+| `llc app list` | — | `--keyword <name>` `--no-auth` `--json` | 列 `fdId/应用名称/应用编码/状态`；`fdId` 即 `--app-id`；`--no-auth` 走免鉴权接口 |
+| `llc app get` | `--id <fdId>` | `--json` | 详情（编码/描述/可访问者/可维护者） |
+| `llc app create` | `--name <name>` | `--code <code>` `--desc <text>` `--category <fdId>` `--icon <name\|json>` `--order <n>` `--json` | 后端同时创建默认首页；`--json` 输出 `{fdId}` |
+| `llc app update` | `--id <fdId>` | `--name` `--code` `--desc` `--category` `--icon` `--order` | 先读详情再合并提交；无修改项则告警退出 |
+| `llc app forms` | `--id <fdId>` | `--json` | 应用下表单（删除前预览） |
+| `llc app delete` | `--id <fdId>` `--yes` | — | 先列出将连带删除的表单，再删应用 |
+| `llc app delete-data` | `--id <fdId>` `--yes` | — | 只删业务数据，保留应用定义 |
+
+`--code` 须匹配 `^[a-zA-Z0-9-]+$`（字母/数字/连字符，**不能有下划线**）。
+
+## 4. form（表单）
+
+| 命令 | 必需 | 可选 | 说明 |
+|---|---|---|---|
+| `llc form create` | `--name <name>` | 见下方选项分组 | 创建表单，并在数据模型基础上生成字段配置 |
+| `llc form list` | — | `--keyword <kw>` `--page-no <n>=1` `--page-size <n>=20` `--json` | **仅 `generalFormDefine`（审批意见表单）**；应用下表单用 `app forms` |
+| `llc form get` | `--id <fdId>` | `--with-config` `--json` | 按 modeling → general → design 顺序读取；默认输出 JSON |
+| `llc form publish` | `--id <fdId>` | `--api <family>` `--desc <text>` | 发布（modeling 走 `saveDesignAndPublish`） |
+| `llc form autofill` | `--id <fdId>` | 字段分组 + `--apply` `--publish` `--from-model` `--icon` | 依赖数据模型重建字段配置；**不加 `--apply` 只预览** |
+| `llc form category-list` | — | `--json` | 表单分类（最多 1000 条） |
+| `llc form delete` | `--id <fdId>` `--yes` | — | 连同数据模型删除（不可逆） |
+| `llc form delete-data` | `--id <fdId>` `--yes` | — | 只删运行时业务数据 |
+
+`create` / `autofill` 共用选项分组：
+
+- **基本**（仅 create）：`--code <code>`（默认自动生成）、`--type <type>`、`--source-form-id <fdId>`（`type=refer` 必填）、`--category <fdId>`、`--readers <ids>`、`--editors <ids>`、`--icon <icon>`。
+- **接口族**（仅 create）：`--api auto|modeling|general|design`、`--app-id <appId>`、`--fd-entity-id` `--fd-entity-name` `--fd-entity-key` `--fd-run-entity-name`、`--table-name`、`--group-id`、`--edit-draft`/`--no-edit-draft`、`--reader-flag`、`--data-source-id`、`--outer-mapping`、`--mechanism-entity-name` `--mechanism-entity-code`。
+- **字段**：`--from-model <fdId>`、`--fields <names>`、`--add-field <spec>`、`--option <spec>`、`--org-type <spec>`、`--detail <spec>`、`--include-system`。
+- **布局**：`--per-row <n>`（默认 2）、`--span <n>`、`--layout rows|grid|tabs`、`--grid-columns <n>`、`--tabs <spec>`、`--tab-layout rows|grid`。
+- **权限**：`--required <fields>` `--readonly <fields>` `--hidden <fields>`、`--auth-file <path>`。
+- **动作/关联**：`--action <spec>`、`--action-file <path>`、`--relation <spec>`。
+- **多语言**：`--locale <locales>`、`--lang-file <path>`。
+- **执行**：`--no-config`、`--dry-run`（仅 create，只打印请求体）、`--publish`、`--force`（跳过控件必填校验）、`--json`。
+
+接口族规则（`--api auto`）：给了 `--app-id` → `modeling`；`--type` 缺省或为 `general` → `general`；其余 → `design`。
+`general` 族只支持 `general`（审批意见表单）；`modeling` 必须给 `--app-id`；`type=refer` 不保存 `fdConfig`。
+`--type` 取值：`common|general|config|modal|template|refer`（数字 `1..6`，中文名亦可）。
+
+### 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
+
+| 命令 | 选项 | 说明 |
+|---|---|---|
+| `llc field list` | `--form-id <fdId>` / `--model-id <fdId>` / `--table <tableName>`（至少一个）、`--json` | 三者全缺时报错；输出字段名/标题/数据类型/控件类型/长度/系统字段/uuid |
+| `llc field library` | `--keyword <kw>`（模糊匹配 fdName）、`--page-no <n>=1`、`--page-size <n>=20`、`--json` | 环境字段库 |
+| `llc field gen-key` | `--name <name>`、`--table <table>` | 生成字段物理名（fdKey） |
+
+## 7. control / locale
+
+| 命令 | 选项 | 说明 |
+|---|---|---|
+| `llc control list` | `--kind control\|layout\|appearance`（默认 control）、`--all`、`--json` | 环境可用控件；`备注` 标注「已登记/容器类/支持选项/已废弃/需设计器配置」 |
+| `llc control show` | `--element <@elem/xform-xxx>` 或 `--type <moneytext>`、`--json` | 控件元数据 + 属性面板配置项与默认值 |
+| `llc locale list` | `--element <pkg>`（默认 `@elem/xform-input`）、`--json` | 返回原始码（如 `zh-cn`）与归一化码（如 `Cn`，可直接用于 `--locale`）；环境全量语言无接口暴露 |
+
+## 8. 控件动作支持的事件（如何获取）
+
+`$global` 全局动作固定 3 个：`onLoad` / `onBeforeSubmit` / `onAfterSubmit`（CLI 会校验，写错直接报错）。
+
+控件级事件由**控件包实现**决定，CLI **不内置白名单**、也不校验事件是否被该控件支持：
+`--action` 只要求事件名是合法标识符（`^[A-Za-z_$][\w$]*$`，如 `onChange`/`onFocus`/`onBlur`）。
+写一个控件并不支持的事件不会报错，但运行时不会触发，所以必须先确认：
+
+1. **设计器属性面板**（权威）：表单设计器选中控件 →「控件动作」分组的事件下拉，即该控件支持的事件。
+2. **控件元数据**（辅助）：`llc control show --element @elem/xform-<短名> --json` 会把控件包
+   `config.json` 原样放在 `meta` 中；CLI 只解析其中的 `xform`（类型/数据项类型/字典类型等）与
+   `config`（属性面板项），**不解析事件**——若包内恰好声明了事件（如 `meta.events`、`meta.xform.events`）
+   可直接使用，否则走其他途径。人类可读输出不展示这些键，必须加 `--json`。
+3. **反查已有表单**：`llc form get --id <fdId>` 返回的
+   `fdConfig.attribute.formAttr.controlAction.control['<表名>.<控件uuid>']` 的键名即该控件已配置的事件；
+   也可 `llc form autofill --id <fdId> --json`（不加 `--apply`，仅预览）查看将要写入的动作结构。
+4. **控件包前端实现**：事件即控件对外抛出的回调 props（`onChange` / `onBlur` / `onFocus` / `onClick` 等），
+   以 `@elem/xform-*` 源码或控件文档为准；仅在前三步拿不到时使用。
+
+> `references/mkxform-api.md` 第 8 节的 `MKXFORM.onChange/beforeSubmit/afterSubmit` 是**运行时监听 API**，
+> 与这里的「控件动作」不是同一套事件，不要混用。
+
+## 9. 规格字符串（spec）速查
+
+| 选项 | 语法 | 说明 |
+|---|---|---|
+| `--add-field` | `"字段名:标题[:数据项类型\|控件类型[:控件类型]]"` | 可重复；第三段可写 `varchar`/`number`，也可直接写 `select`/`moneytext`；字段名已存在时只覆盖标题与控件类型 |
+| `--option` | `"字段名=选项1,选项2:值2"` | 可重复，同字段合并；省略 `:值` 时按序号 `1..n` |
+| `--org-type` | `"字段名=机构,部门,个人"` | 编码 `1`机构/`2`部门/`4`岗位/`8`个人/`16`常用群组/`256`人员身份；`all`=机构+部门+岗位+个人+常用群组；可重复 |
+| `--detail` | `"明细表标题=字段:标题[:控件类型],字段2:标题2"` | 可重复；同名明细表自动复用并调整字段 |
+| `--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`；控件级事件如何获取见第 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 可为字段标题或字段名；选项支持 `字段名#值` |
+
+## 10. 常见失败提示
+
+| 提示 | 原因与处理 |
+|---|---|
+| `缺少必要配置：baseUrl ... token ...` | 未配置凭据；`llc config set` 或传 `--base-url`/`--token` |
+| `未知的控件类型：xxx，可选值：...` | `--add-field` 第三段写错；先 `llc control list` 确认 |
+| `"detail" 是容器类控件，不能用 --add-field 创建` | 明细表用 `--detail`；`bigDetail`/`paged` 不支持 |
+| `控件必填属性校验失败（共 N 项），已中止保存/发布` | 按提示补属性；确需跳过用 `--force` |
+| `未获取到数据模型字段，无法自动完善` | `form autofill` 找不到数据模型；检查 `--id` / `--from-model` |
+| `未知命令：llc ...` | `llc help <命令...>` 路径写错 |

package/skills/lan-low-code-cli/references/existing-app-flows.md

@@ -0,0 +1,88 @@
+# Flows: modifying an existing app / adding forms
+
+These flows operate on apps/forms that already exist. They reuse the same commands as
+the 0-to-1 flow in `SKILL.md`; the differences are inspection first, targeted changes,
+and explicit layout handling.
+
+## 1. Inspect before changing
+
+```bash
+llc app list --keyword 客户                  # find appId (fdId)
+llc app forms --id <appId>                   # forms under the app (formId, status)
+llc form get --id <formId> --with-config     # form detail + data model summary
+llc field list --form-id <formId>            # existing fields (fdName / label / type)
+llc control list                             # controls available for new fields
+```
+
+Rule: always inspect first — `--add-field` with an **existing** `fdName` updates that
+field instead of creating a duplicate.
+
+## 2. Add a new form to an existing app
+
+```bash
+llc form create --name 客户拜访记录 --app-id <existing-appId> --publish \
+  --add-field "fd_visit_date:拜访日期:datetime" \
+  --add-field "fd_visit_result:拜访结果:select" \
+  --option "fd_visit_result=满意,一般,不满意"
+```
+
+`--app-id` targets an existing app; the form is added under it (default home page is
+not touched). `--publish` keeps it official; omit it to stay in draft.
+
+## 3. Iterate an existing form (autofill)
+
+```bash
+# preview first — nothing is written
+llc form autofill --id <formId>
+
+# add fields / options / actions, then save (keep layout!)
+llc form autofill --id <formId> --apply \
+  --add-field "fd_col_memo:备注:textarea" \
+  --option "fd_col_level=D级" \
+  --action "fd_col_name:onChange:function onChange(v){ MKXFORM.setValue('表名.fd_col_code', v) }"
+
+# publish when verified
+llc form publish --id <formId>
+```
+
+Rules that matter here:
+
+- **Layout is preserved**: without `--layout`, autofill keeps the existing render tree
+  (grid/tabs). Newly added fields are not placed until you run once with an explicit
+  `--layout` (e.g. `--layout grid --grid-columns 3`).
+- **Draft regression**: `--apply` alone saves as draft (a warning is printed if the form
+  was official). Append `--publish`, or publish afterwards with `llc form publish`.
+- **Pre-publish validation**: required control props are validated before save; failures
+  abort (exit 1). Fix the values; `--force` is a last resort.
+- `--locale all` / `--lang-file` can be combined with any iteration to (re)fill i18n.
+
+## 4. Adjust permissions
+
+```bash
+llc form autofill --id <formId> --apply \
+  --required "fd_col_name" \
+  --readonly "fd_col_code" \
+  --hidden "fd_col_inner"
+# fine-grained: --auth-file perms.json  e.g. {"add":{"fd_col_a":{"required":true}}}
+```
+
+Applies to `auth[0].{add|edit|view}` in the saved config. Note: these are runtime
+permissions, not `fdDisplay` (field visibility in the data model).
+
+## 5. Fill i18n afterwards
+
+```bash
+llc form autofill --id <formId> --apply --locale all --lang-file ./lang.json
+llc locale list                               # which languages have translations
+```
+
+## 6. Rollback / cleanup
+
+```bash
+llc form delete-data --id <formId> --yes      # clear runtime data, keep the form
+llc form delete --id <formId> --yes           # remove form + data model (irreversible)
+llc app delete-data --id <appId> --yes        # clear app business data
+llc app delete --id <appId> --yes             # remove app and all its forms
+```
+
+Preview deletions with `llc app forms --id <appId>` first.

package/skills/lan-low-code-cli/references/existing-app-flows.zh-CN.md

@@ -0,0 +1,86 @@
+# 流程：修改现有应用 / 增加表单
+
+以下流程针对**已存在**的应用与表单，复用 `SKILL.md` 中的同一批命令；
+区别在于：先查看、再精准修改、显式处理布局。
+
+## 1. 修改前先查看
+
+```bash
+llc app list --keyword 客户                  # 找 appId（fdId）
+llc app forms --id <appId>                   # 应用下的表单（formId、状态）
+llc form get --id <formId> --with-config     # 表单详情 + 数据模型概要
+llc field list --form-id <formId>            # 已有字段（fdName / 标题 / 类型）
+llc control list                             # 可用于新字段的控件
+```
+
+原则：先查看再动手——`--add-field` 指定**已存在**的 `fdName` 时是「调整该字段」，
+不会重复创建。
+
+## 2. 向现有应用增加表单
+
+```bash
+llc form create --name 客户拜访记录 --app-id <既有appId> --publish \
+  --add-field "fd_visit_date:拜访日期:datetime" \
+  --add-field "fd_visit_result:拜访结果:select" \
+  --option "fd_visit_result=满意,一般,不满意"
+```
+
+`--app-id` 指向既有应用，新表单挂在其下（不影响默认首页）；
+`--publish` 直接发布，省略则保持草稿态。
+
+## 3. 迭代修改现有表单（autofill）
+
+```bash
+# 先预览——不写入任何数据
+llc form autofill --id <formId>
+
+# 加字段 / 补选项 / 加动作，然后仅保存（布局保持不变！）
+llc form autofill --id <formId> --apply \
+  --add-field "fd_col_memo:备注:textarea" \
+  --option "fd_col_level=D级" \
+  --action "fd_col_name:onChange:function onChange(v){ MKXFORM.setValue('表名.fd_col_code', v) }"
+
+# 确认无误后发布
+llc form publish --id <formId>
+```
+
+此场景的关键规则：
+
+- **布局保护**：不带 `--layout` 时 autofill 保持现有渲染树（栅格/页签不动）；
+  新增字段不会被放置，需显式跑一次 `--layout`（如 `--layout grid --grid-columns 3`）。
+- **草稿回归**：仅 `--apply` 保存后表单变为草稿态（原为发布态时 CLI 会告警）；
+  追加 `--publish`，或事后 `llc form publish --id <formId>`。
+- **发布前校验**：保存前校验控件必填属性，失败即中止（退出码 1）；
+  应优先修正属性值，`--force` 仅作最后手段。
+- `--locale all` / `--lang-file` 可与任意迭代组合补齐多语言。
+
+## 4. 调整字段权限
+
+```bash
+llc form autofill --id <formId> --apply \
+  --required "fd_col_name" \
+  --readonly "fd_col_code" \
+  --hidden "fd_col_inner"
+# 精细权限：--auth-file perms.json，如 {"add":{"fd_col_a":{"required":true}}}
+```
+
+写入 `auth[0].{add|edit|view}`。注意这是**运行时权限**，
+不是数据模型的 `fdDisplay`（字段是否显示）。
+
+## 5. 事后补齐多语言
+
+```bash
+llc form autofill --id <formId> --apply --locale all --lang-file ./lang.json
+llc locale list                               # 查看哪些语言有现成译文
+```
+
+## 6. 回滚 / 清理
+
+```bash
+llc form delete-data --id <formId> --yes      # 清空运行时数据，保留表单
+llc form delete --id <formId> --yes           # 删除表单 + 数据模型（不可逆）
+llc app delete-data --id <appId> --yes        # 清空应用业务数据
+llc app delete --id <appId> --yes             # 删除应用及其全部表单
+```
+
+删除前先用 `llc app forms --id <appId>` 预览。