lan-low-code-cli 2.4.0 → 2.6.0

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

@@ -0,0 +1,264 @@
+---
+name: lan-low-code-cli
+version: 2.6.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:
+  - low-code
+  - llc
+  - form
+  - landray
+  - cli
+allowed-tools:
+  - Bash(llc:*)
+  - Bash(npx lan-low-code-cli:*)
+  - Bash(node scripts/self-update.mjs:*)
+  - Read
+  - Grep
+  - Glob
+user-invocable: true
+---
+
+
+# llc CLI — low-code form engine operations
+
+`llc` is a CLI that drives the Landray sys-modeling / sys-xform HTTP APIs to manage
+business apps and form definitions **as data** (no UI required). This skill describes
+how to use it correctly and what invariants must be preserved.
+
+## 0. Prerequisites
+
+### Install the CLI
+
+```bash
+npm i -g lan-low-code-cli            # global install, provides the `llc` command
+# mirror users: append --registry https://registry.npmjs.org/ (npm mirror syncs with ~10min delay)
+# or without a global install: npx lan-low-code-cli <command>
+```
+
+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`):
+
+| 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. |
+| 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. |
+
+When versions disagree, `llc <command> --help` wins over this file; the option list is in
+[references/cli-contract.md](references/cli-contract.md).
+
+### Self-update
+
+The skill ships a zero-dependency updater (`scripts/self-update.mjs`) that keeps the skill and CLI in sync:
+
+```bash
+node scripts/self-update.mjs                    # check only (default): exit 0 compatible, 2 stale/older
+node scripts/self-update.mjs --apply --from ./lan-low-code-cli-skill-<version>.tgz  # from a skill package
+node scripts/self-update.mjs --apply --from <dir>   # from an unpacked skill directory
+node scripts/self-update.mjs --apply --from-cli     # from the installed CLI package (skills/ ships with npm)
+```
+
+- Flow: `npm i -g lan-low-code-cli@latest` → `node scripts/self-update.mjs --apply --from-cli`
+  (the npm package bundles `skills/`; older CLI versions need the upgrade first) → confirm the `version:`
+  in `SKILL.md` and re-read this file.
+- The updater backs up the current skill to `<skill>.backup-<old>-<timestamp>` next to the folder, keeps
+  files absent from the new version (and reports them), and refuses a source lacking `SKILL.md` or with a
+  different `name`.
+- Ask the user before `--apply` (it rewrites the skill files) and never update mid-task: finish or abort
+  the current operation first, since option names may change.
+- Sources: `--from` accepts a `.tgz`/`.tar.gz` skill package (`lan-low-code-cli-skill-<version>.tgz`, which
+  already has a `lan-low-code-cli/` top-level folder) or an unpacked directory; `LLC_CLI` overrides the
+  `llc` executable (a `.js` entry-script path also works).
+
+### Configure credentials
+
+
+```bash
+llc config set --base-url http://<host>/data --token <X-AUTH-TOKEN>   # once
+# or per-invocation / per environment:
+#   --base-url / --token flags, or LLC_BASE_URL / LLC_TOKEN env vars
+```
+
+Always run `llc <command> --help` before inventing flags — the CLI is the source of truth.
+
+## 1. Command map
+
+| Command | Purpose |
+|---|---|
+| `llc app list / create / forms / delete / delete-data` | business apps (`--code` allows letters/digits/hyphen only, **no underscore**) |
+| `llc form create / list / get / publish / autofill / delete / delete-data` | form lifecycle; `create --type category\|simpleCategory` builds a category form (no business fields; templates are created in the platform designer) |
+| `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 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 |
+
+> Full per-command options, spec-string syntax and exit codes: **§7 CLI contract**. When in doubt, `llc <command> --help` is authoritative.
+>
+> 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).
+
+## 2. Core workflow
+
+```bash
+# 1. create app (returns appId)
+llc app create --name 客户管理 --code crm
+
+# 2. create form, generate field config, publish
+llc form create --name 客户信息 --app-id <appId> --publish \
+  --add-field "fd_col_name:客户名称" \
+  --add-field "fd_col_level:客户等级:select" \
+  --option "fd_col_level=A级,B级,C级" \
+  --detail "联系人明细=fd_pname:姓名,fd_pphone:电话:phoneNumber" \
+  --layout tabs --tabs "基本信息:fd_col_name,fd_col_level" --tab-layout grid --grid-columns 3 \
+  --required "fd_col_name" --readonly "fd_col_code" --hidden "fd_col_inner"
+
+# 3. iterate (all layout options are optional — see §3)
+llc form autofill --id <fdId> --apply --publish
+
+# 4. verify
+llc app forms --id <appId>
+llc form get --id <fdId> --with-config
+
+# 5. rollback / cleanup (both need --yes)
+llc form delete --id <fdId> --yes
+llc app delete --id <appId> --yes
+```
+
+### Modifying an existing app / adding forms
+
+Working on apps/forms that already exist (inspect, add a form under an existing app,
+iterate a form, adjust permissions, backfill i18n, rollback) follows the same commands —
+read [references/existing-app-flows.md](references/existing-app-flows.md) before doing so.
+
+## 3. Invariants and pitfalls (violating these breaks forms in the designer)
+
+1. **Layout preservation**. `form autofill` WITHOUT `--layout` reuses the existing
+   `viewModel` untouched (grid/tabs layouts survive). Only an explicit `--layout`
+   rebuilds the render tree. Fields added via `--add-field` are NOT in the old layout —
+   the CLI warns; pass `--layout` (e.g. `--layout grid --grid-columns 3`) to place them.
+2. **Draft regression**. Saving via autofill sets the form to draft state. Add
+   `--publish` to keep it official. `llc form publish --id <fdId>` publishes later.
+3. **messageKey format**. i18n keys must be `!{<base36>}` (no hyphens) — the designer
+   matches them with `/\!\{([\w\.]*)\}/`. The CLI generates correct keys; never invent keys manually.
+4. **Default value mode**. New fields use `defaultValueType: "null"`. NEVER write
+   `"formula"` without also providing `defaultValueFormulaVO`
+   (`{script, type:'Eval', vo:{mode:'formula', content}}` in `fdFontExtendData`) —
+   the designer blocks submit with a required prompt.
+5. **Pre-publish validation**. CLI validates required control props before save/publish
+   (aligned with the designer, including conditional requireds like
+   `defaultValueType='formula'` → `defaultValueFormulaVO`). Failures abort with exit 1;
+   `--force` skips. Prefer fixing values over forcing.
+6. **Labels default to horizontal layout** (`labelProps.layout: 'horizontal'`).
+7. **Data-dictionary options** (`messageKey` like `${sys-xform:enum.*}`) are static
+   i18n resources — never rewrite them into `lang`.
+8. **Deleting** requires `--yes`; `form delete` removes the data model too (irreversible).
+
+## 4. i18n
+
+```bash
+llc form autofill --id <fdId> --apply --publish --locale all --lang-file ./lang.json
+```
+
+- `--locale` is comma-separated; **first entry is the primary language** (`all` = `Cn,Us,Tw`).
+- `lang.json`: `{ "Us": { "姓名": "Name" }, "Tw": { "金额": "金額" } }` —
+  matched by field label, then field name; for options also `fdName#value`.
+- Missing translations fall back to the primary text (never blank).
+- `llc locale list` shows which languages actually have translations in the environment.
+
+## 5. Control actions (onChange / onLoad / …)
+
+```bash
+llc form autofill --id <fdId> --apply --publish \
+  --action "fd_col_a:onChange:function onChange(value){ MKXFORM.setValue('表名.fd_col_b', value) }" \
+  --action-file ./actions.json
+```
+
+- Target is the field `fdName`; `$global` targets form-level events
+  (`onLoad` / `onBeforeSubmit` / `onAfterSubmit` only).
+- **Which events a control supports**: the CLI has no whitelist and does not validate them (any identifier
+  is accepted), so an unsupported event saves fine but never fires. Confirm in this order: the designer's
+  "控件动作" event dropdown (authoritative) → `llc control show --element <pkg> --json`, i.e. event
+  declarations in `meta` if the package has any (not shown in human output) → the keys of
+  `controlAction.control['<table>.<uuid>']` on an existing form. See §8 of
+  [references/cli-contract.md](references/cli-contract.md).
+- `source` is function **source code** (evaluated via
+  `new Function('MKXFORM', 'return (fn)')`); `@path` reads it from a file.
+- Storage: `fdConfig.attribute.formAttr.controlAction.control['<table>.<uuid>'][<event>]`.
+- Existing actions (and form rules) are preserved on autofill.
+- **Naming convention**: control-level actions must not use bare event names (`onChange`, …) —
+  the CLI auto-renames them to `onChange_<fdName>` and rewrites the function declaration in the source.
+  `$global` actions keep the bare event name (e.g. `onLoad`). Provide suffixed names directly to avoid the warning.
+- **Full runtime API reference**: see [references/mkxform-api.md](references/mkxform-api.md) (Chinese) — setValue/getValue, detail-table APIs, events, modals, ajax, org/flow helpers, etc.
+
+## 6. Control types (including advanced controls)
+
+**Always inspect the environment first**: `llc control list` (desktop/mobile packages, data type,
+registered / option support), `llc control show --type <type>` for property defaults.
+
+`--add-field "fdName:label[:dataType][:controlType]"` — put the control type in the 3rd/4th token:
+
+```bash
+llc form autofill --id <fdId> --apply --publish \
+  --add-field "fd_note:Description:desc" \
+  --add-field "fd_tag:Tags:tags" \
+  --add-field "fd_code:Platform No.:mechnumber"
+```
+
+- 64 of the environment's 67 `kind=control` controls are registered (`CONTROL_TYPE_MAP`):
+  base controls plus advanced ones (`desc`/`interval`/`button`/`html`/`iframe`/`review`/`timeAxis`/
+  `associatedFields`/`serial-number`, numbering `mechnumber`/`manualNumber`/`reserveNumber`,
+  data `association`/`mdm`/`cfg`/`dynamic`/`tags`/`location`/`area`/`calculate`/`fileEdit`/
+  `invoice`/`ocr`/`template`/`ikm-*`, …).
+- **Org / people fields use `address`** — the **address book** control (person / org / dept / post /
+  user-group picker), *not* a plain address text field. It stores `fdDataType=address` with
+  `fdDictType=orgElementDict`; defaults are “all range + person only + single select”.
+  `org.orgTypeArr` is a code array: `1` org, `2` dept, `4` post, `8` person, `16` user group,
+  `256` person identity (only when the platform enables multiple identities). **Set the selectable
+  types with `--org-type`** (`"field=部门,个人"`; codes `1/2/4/8/16/256`, English aliases and `all`
+  also work); `multi` toggles multi-select, `range` selects the scope (`all` / `custom`).
+  Its settings live in both `controlProps` and `fdFontExtendData`, which the CLI keeps in sync.
+- **Related-data controls**: `relation` (**business relation**) is marked **deprecated** by the
+  platform (`xform.group=deprecated`). Its property panel is assembled by the designer (the control
+  package ships no required props), and the mandatory items are **关联表单 / business object**
+  (`relationCfg`) plus **datasource display columns** (`datasource.columns`), with card / navigation /
+  tree-level rules for those render modes — the CLI now validates these and blocks a bare skeleton
+  (exit code 1); prefer `association`. **Configure it with `--relation`**, which resolves the business
+  object / display value / display columns and writes `relationCfg` + `datasource`:
+  `llc form autofill --id <fdId> --apply --publish --relation "fd_x=TargetFormName[:显示值=field][:显示项=field1,field2]"`. `relationQuery` (needs `tabs`),
+  `association` (needs `xlistColumn`), `foreignKey` (needs `mappedType`), `refTemplate` and
+  `associatedFields` all require picking a business object / datasource in the designer (the CLI only
+  creates the skeleton; once configured, `autofill` preserves those settings).
+  `llc control list` marks them `已废弃` / `需设计器配置`.
+- **Placeholder (prompt text)**: the CLI fills a default per control — the lang resource key differs
+  by widget (`@elem/xform-datetime`/`timepicker` use `pleaseEnter` → 请选择日期/请选择时间,
+  `m-datetime` uses `enter`, `area` uses `pleaseSelect`, others use `placeholder` → 请输入/请选择).
+  An existing placeholder (designer-customised text plus its `lang` entry) is **kept as is**.
+- **Element** controls (`desc`/`html`/`interval`/…) have `fdIsStored=false`: they are written into
+  `dataModel` but create no physical column.
+- **Containers** (`detail`/`bigDetail`/`paged`) are not data fields: use `--detail` for detail tables;
+  the other two are unsupported (no usage samples in the environment).
+- Controls that need **designer configuration** (association range, master data, config item,
+  numbering rule, OCR type, …) are created as skeletons only: the CLI warns, and pre-publish
+  validation blocks unless fixed (`--force` skips it, but the control still needs configuration).
+  `associatedFields` is special: no required props, yet publishing **fails with HTTP 500** until its
+  associated source field is set in the designer.
+- **Unregistered controls are protected**: a platform-added/custom widget package is no longer
+  downgraded to a text input by `autofill` — the CLI restores the package from the field's existing
+  attribute and keeps `fdType`.
+
+## 7. CLI contract
+
+Full command tree, options, spec-string syntax, config precedence and exit codes live in a dedicated file:
+[references/cli-contract.md](references/cli-contract.md).
+
+Quick facts: `llc <group> <subcommand> [options]`; multi-level help `llc help form create`;
+credentials precedence `--base-url`/`--token` > `LLC_BASE_URL`/`LLC_TOKEN` > project `lcode.config.json` >
+global `~/.lcode/config.json`; exit codes `0` success / `1` failure; delete commands need `--yes`;
+`form autofill` without `--apply` only previews.

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

@@ -0,0 +1,247 @@
+---
+name: lan-low-code-cli
+version: 2.6.0
+author: Pig George
+description: 通过 `llc` CLI 操作蓝凌低代码表单引擎。适用于：创建、查看、修改、发布或删除低代码应用与表单；生成字段配置；配置布局（栅格/页签）、字段权限、选项、多语言、控件动作（onChange/onLoad）；或执行发布前校验、排查表单加载/渲染报错。
+tags:
+  - low-code
+  - llc
+  - form
+  - landray
+  - cli
+allowed-tools:
+  - Bash(llc:*)
+  - Bash(npx lan-low-code-cli:*)
+  - Bash(node scripts/self-update.mjs:*)
+  - Read
+  - Grep
+  - Glob
+user-invocable: true
+---
+
+
+# llc CLI —— 低代码表单引擎操作
+
+`llc` 是驱动蓝凌 sys-modeling / sys-xform HTTP 接口的命令行工具，
+以**数据方式**管理业务应用与表单定义（无需 UI）。本文件说明如何正确使用，
+以及哪些不变量必须保持。
+
+## 0. 前置条件
+
+### 安装 CLI
+
+```bash
+npm i -g lan-low-code-cli            # 全局安装，获得 `llc` 命令
+# 镜像用户：追加 --registry https://registry.npmjs.org/（npm 镜像同步延迟约 10 分钟）
+# 或不全局安装，直接用：npx lan-low-code-cli <命令>
+```
+
+验证：`llc -v` 应输出版本号。
+
+### 升级前的版本校验
+
+升级前（以及 `llc -v` 与本 skill 版本不一致时），先用 CLI 的**大版本**对比本文件 frontmatter 的
+`version:`：
+
+| CLI 版本 vs skill | 处理 |
+|---|---|
+| 同一大版本（`2.4.1` → 如 `2.6.0`） | **直接升级**：`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 降级。 |
+
+版本不一致时，以 `llc <command> --help` 为准；完整选项见
+[references/cli-contract.zh-CN.md](references/cli-contract.zh-CN.md)。
+
+### 自更新
+
+技能自带零依赖更新脚本（`scripts/self-update.mjs`），用于让技能与 CLI 保持同版本：
+
+```bash
+node scripts/self-update.mjs                    # 仅检查（默认）：0 一致，2 过期/落后
+node scripts/self-update.mjs --apply --from ./lan-low-code-cli-skill-<version>.tgz  # 用技能发行包更新
+node scripts/self-update.mjs --apply --from <目录>   # 用已解压的技能目录更新
+node scripts/self-update.mjs --apply --from-cli     # 从已安装的 CLI 包内取（npm 包已内置 skills/）
+```
+
+- 流程：`npm i -g lan-low-code-cli@latest` → `node scripts/self-update.mjs --apply --from-cli`
+  （npm 包已随包分发 `skills/`，旧版本需先升级 CLI）→ 确认 `SKILL.md` 的 `version:` 并重新读取本文件。
+- 更新脚本会把当前技能备份到同级目录 `<技能目录>.backup-<旧版本>-<时间戳>`；新版本中不存在的文件
+  **保留并提示**；来源缺少 `SKILL.md` 或 `name` 不一致时拒绝执行。
+- 执行 `--apply` 前先征得用户同意（会改写技能文件）；不要在任务中途更新——先完成或放弃当前操作，
+  避免参数变更导致半途失败。
+- 来源：`--from` 支持 `.tgz`/`.tar.gz` 技能包（`lan-low-code-cli-skill-<version>.tgz`，包内顶层目录为
+  `lan-low-code-cli/`）或已解压目录；`LLC_CLI` 可指定 `llc` 可执行文件或 CLI 入口脚本路径。
+
+### 配置凭据
+
+
+```bash
+llc config set --base-url http://<host>/data --token <X-AUTH-TOKEN>   # 一次即可
+# 或按次/按环境覆盖：
+#   --base-url / --token 参数，或 LLC_BASE_URL / LLC_TOKEN 环境变量
+```
+
+使用前先执行 `llc <command> --help` 查看可用参数——CLI 本身是唯一事实来源。
+
+## 1. 命令一览
+
+| 命令 | 用途 |
+|---|---|
+| `llc app list / create / forms / delete / delete-data` | 业务应用（`--code` 仅允许字母/数字/连字符，**不允许下划线**） |
+| `llc form create / list / get / publish / autofill / delete / delete-data` | 表单生命周期；`create --type category\|simpleCategory` 建分类表单（无业务字段，模板需在平台设计器创建） |
+| `llc field list / gen-key / library` | 可用字段 |
+| `llc operation list / get / create / update / delete / attach / detach` | 表单业务操作（链接、脚本、对话框），含挂载到列表/查看视图 |
+| `llc template list / create / add-fields / delete` | 分类表单模板：创建模板并把既有表单的字段/视图/权限移植进来，追加字段，或清理模板（自动建分类节点、跳过官方 init） |
+| `llc control list / show` | 环境已安装控件（`--add-field` 第三段的取值依据） |
+| `llc locale list` | 环境中有现成译文的语言（来自控件多语言资源） |
+| `llc config set / show / clear` | 全局凭据与默认值 |
+
+> 每个命令的完整参数、规格字符串语法与退出码见**第 7 节 CLI 契约**；不确定时以 `llc <命令> --help` 为准。
+>
+> 业务操作「脚本模式」的运行时 `context`（选中数据、刷新列表、查询、跳转、事件总线、`window.MKXFORM`）
+> 见 [references/operation-script-context.md](references/operation-script-context.md)。
+
+## 2. 核心流程
+
+```bash
+# 1. 创建应用（返回 appId）
+llc app create --name 客户管理 --code crm
+
+# 2. 创建表单、生成字段配置并发布
+llc form create --name 客户信息 --app-id <appId> --publish \
+  --add-field "fd_col_name:客户名称" \
+  --add-field "fd_col_level:客户等级:select" \
+  --option "fd_col_level=A级,B级,C级" \
+  --detail "联系人明细=fd_pname:姓名,fd_pphone:电话:phoneNumber" \
+  --layout tabs --tabs "基本信息:fd_col_name,fd_col_level" --tab-layout grid --grid-columns 3 \
+  --required "fd_col_name" --readonly "fd_col_code" --hidden "fd_col_inner"
+
+# 3. 迭代调整（布局参数可选——见第 3 节）
+llc form autofill --id <fdId> --apply --publish
+
+# 4. 校验
+llc app forms --id <appId>
+llc form get --id <fdId> --with-config
+
+# 5. 回滚 / 清理（均需 --yes）
+llc form delete --id <fdId> --yes
+llc app delete --id <appId> --yes
+```
+
+### 修改现有应用 / 增加表单
+
+对已存在的应用与表单做改动（查看、向既有应用加表单、迭代修改表单、调整权限、补齐多语言、回滚清理）
+使用同一批命令——动手前先阅读 [references/existing-app-flows.zh-CN.md](references/existing-app-flows.zh-CN.md)。
+
+## 3. 不变量与易错点（违反会导致设计器中表单异常）
+
+1. **布局保护**。`form autofill` **不带 `--layout`** 时原样沿用现有 `viewModel`
+   （栅格/页签布局不动）；只有显式传 `--layout` 才重建渲染树。
+   `--add-field` 新增的字段不在旧布局中——CLI 会告警；
+   需展示时传 `--layout`（如 `--layout grid --grid-columns 3`）。
+2. **草稿回归**。autofill 保存后表单变为草稿态，加 `--publish` 保持发布态；
+   也可稍后用 `llc form publish --id <fdId>` 单独发布。
+3. **messageKey 格式**。多语言 key 必须是 `!{<base36>}`（不含连字符）——
+   设计器用 `/\!\{([\w\.]*)\}/` 匹配。CLI 会生成合法 key，禁止手工拼 key。
+4. **初始值模式**。新建字段默认 `defaultValueType: "null"`。禁止只写 `"formula"`
+   而不提供 `defaultValueFormulaVO`（`fdFontExtendData` 中的
+   `{script, type:'Eval', vo:{mode:'formula', content}}`）——设计器提交会被必填拦截。
+5. **发布前校验**。CLI 在保存/发布前校验控件必填属性（对齐设计器，
+   含条件必填：`defaultValueType='formula'` → `defaultValueFormulaVO`）。
+   失败即中止（退出码 1）；`--force` 可跳过，但应优先修正属性值。
+6. **标题默认左右布局**（`labelProps.layout: 'horizontal'`）。
+7. **数据字典选项**（`messageKey` 形如 `${sys-xform:enum.*}`）走平台静态多语言，
+   禁止改写入 `lang`。
+8. **删除**需 `--yes`；`form delete` 连同数据模型一并删除（不可逆）。
+
+## 4. 多语言
+
+```bash
+llc form autofill --id <fdId> --apply --publish --locale all --lang-file ./lang.json
+```
+
+- `--locale` 逗号分隔，**第一个为主语言**（`all` = `Cn,Us,Tw`）。
+- `lang.json`：`{ "Us": { "姓名": "Name" }, "Tw": { "金额": "金額" } }`——
+  按「字段标题」再按「字段名」匹配；选项支持 `字段名#选项值` 精确匹配。
+- 未命中的翻译回落主语言文案（不会出现空白标题）。
+- `llc locale list` 查看环境中实际有译文的语言。
+
+## 5. 控件动作（onChange / onLoad / …）
+
+```bash
+llc form autofill --id <fdId> --apply --publish \
+  --action "fd_col_a:onChange:function onChange(value){ MKXFORM.setValue('表名.fd_col_b', value) }" \
+  --action-file ./actions.json
+```
+
+- 目标为字段物理名；`$global` 表示表单级事件
+  （仅 `onLoad` / `onBeforeSubmit` / `onAfterSubmit`）。
+- **控件支持哪些事件**：CLI 不内置白名单、也不校验（只要求标识符），写错不会报错但不会触发。
+  按序确认：设计器「控件动作」事件下拉（权威）→ `llc control show --element <pkg> --json` 的 `meta`
+  （若包内声明了事件；人类可读输出不展示）→ 已有表单 `controlAction.control['<表名>.<uuid>']` 的键名。
+  详见 [references/cli-contract.zh-CN.md](references/cli-contract.zh-CN.md) 第 8 节。
+- `source` 是函数**源码**（运行时经 `new Function('MKXFORM', 'return (fn)')` 求值）；
+  `@路径` 表示从文件读取。
+- 落库位置：`fdConfig.attribute.formAttr.controlAction.control['<表名>.<uuid>'][<事件>]`。
+- autofill 会保留已有动作与表单规则。
+- **命名规范**：控件级动作禁止裸事件名（`onChange` 等）——CLI 自动规范为
+  `onChange_<控件id>` 并同步重写函数源码声明；`$global` 全局动作保持裸事件名（如 `onLoad`）。
+  直接带后缀命名可避免告警。
+- **完整运行时 API 参考**：见 [references/mkxform-api.md](references/mkxform-api.md) ——setValue/getValue、明细表系列 API、事件、弹窗、ajax、组织/流程助手等。
+
+## 6. 控件类型（含高级控件）
+
+**先查环境再选控件**：`llc control list`（含桌面/移动端包、数据项类型、是否已登记、是否支持选项），
+`llc control show --type <类型>` 看属性面板默认值。
+
+`--add-field "字段名:标题[:数据项类型][:控件类型]"` 第三/四个 token 写控件类型即可创建高级控件：
+
+```bash
+llc form autofill --id <fdId> --apply --publish \
+  --add-field "fd_note:说明文字:desc" \
+  --add-field "fd_tag:标签:tags" \
+  --add-field "fd_code:平台编码:mechnumber"
+```
+
+- 环境 67 个 `kind=control` 控件中 **64 个已登记**（`CONTROL_TYPE_MAP`）：
+  基础控件 + 高级控件（`desc`/`interval`/`button`/`html`/`iframe`/`review`/`timeAxis`/
+  `associatedFields`/`serial-number`、编号类 `mechnumber`/`manualNumber`/`reserveNumber`、
+  数据类 `association`/`mdm`/`cfg`/`dynamic`/`tags`/`location`/`area`/`calculate`/`fileEdit`/
+  `invoice`/`ocr`/`template`/`ikm-*` …）。
+- **组织人员字段用 `address`（地址本）**——它不是「地址文本」，而是选人/选组织/部门/岗位的
+  控件（`fdDictType=orgElementDict`，落库 `fdDataType=address`）。默认「全部范围 + 仅个人 + 单选」；
+  `org.orgTypeArr` 是编码数组：`1`机构、`2`部门、`4`岗位、`8`个人、`16`常用群组、`256`人员身份
+  （仅开启「多身份」时可选）。**用 `--org-type` 指定可选类型**（`"字段名=部门,个人"`，也支持编码
+  `1/2/4/8/16/256`、英文别名与 `all`）；`multi` 控制多选、`range` 控制范围（`all`/`custom`）。
+  这类字段的配置在 `controlProps` 与 `fdFontExtendData` 两处并存，CLI 会同步维护。
+- **关联类控件**：`relation`（**业务关联**）被平台标记**废弃**（`xform.group=deprecated`），
+  其属性面板由设计器拼装（控件包无必填属性），**必填项为「关联表单（业务对象）」+「数据源显示项」**
+  （另有卡片/导航/树层级按显示方式要求）——CLI 已按设计器规则做语义校验，裸字段会被拦截（退出码 1），
+  新表单建议改用 `association`；
+  **用 `--relation` 可直接配置**（自动解析业务对象/显示值/显示项并写入 `relationCfg`+`datasource`）：
+  `llc form autofill --id <fdId> --apply --publish --relation "fd_x=目标表单名[:显示值=字段][:显示项=字段1,字段2]"`；
+  `relationQuery`（需 `tabs`）、`association`（需 `xlistColumn`）、`foreignKey`（需 `mappedType`）、
+  `refTemplate`、`associatedFields` 都必须在设计器里选好业务对象/数据源（CLI 只建骨架，
+  选了之后 `autofill` 会原样保留）。`llc control list` 的 `备注` 会标注「已废弃」「需设计器配置」。
+- **提示文字（placeholder）**：CLI 会按控件的资源键补默认文案（资源键因控件而异——
+  `@elem/xform-datetime`/`timepicker` 用 `pleaseEnter`→「请选择日期/请选择时间」、
+  `m-datetime` 用 `enter`、`area` 用 `pleaseSelect`、其余用 `placeholder`→「请输入/请选择」）；
+  字段已有提示文字（含设计器自定义文案与其 `lang` 条目）会**原样保留**。
+- **元素类**控件（`desc`/`html`/`interval`…）`fdIsStored=false`：写入 `dataModel` 但不建物理列。
+- **容器类**（`detail`/`bigDetail`/`paged`）不是数据项：明细表用 `--detail`，
+  另两个暂不支持（环境无使用样例）。
+- **需设计器补配置**的控件（关联范围、主数据、配置项、编号规则、识别类型…）CLI 只建骨架：
+  生成时会提示，发布前校验会拦截（`--force` 可跳过，但控件仍需人工补配置）。
+  特例 `associatedFields`：无必填属性，但未配置关联源时**后端发布会 500**。
+- **未登记控件受保护**：平台新增/定制控件包不会被 `autofill` 降级成输入框——
+  CLI 从字段已有属性还原控件包并保留 `fdType`。
+
+## 7. CLI 契约
+
+完整命令树、选项、规格字符串语法、配置优先级与退出码单独维护：
+[references/cli-contract.zh-CN.md](references/cli-contract.zh-CN.md)。
+
+速记：`llc <命令组> <子命令> [选项]`；多级帮助 `llc help form create`；凭据优先级
+`--base-url`/`--token` > `LLC_BASE_URL`/`LLC_TOKEN` > 项目 `lcode.config.json` > 全局 `~/.lcode/config.json`；
+退出码 `0` 成功、`1` 失败；删除类命令需 `--yes`；`form autofill` 不加 `--apply` 只预览。
+