@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/skills/omc-requirement-vocabulary.md

@@ -0,0 +1,51 @@
+---
+name: omc-requirement-vocabulary
+description: Chinese cue → OMC capability lookup. Disclosed reference for requirement-analysis steps 1–2.
+---
+
+# Requirement Vocabulary (需求线索词表)
+
+Reference for `omc-requirement-analysis.md` step 1. A flat peer-set: match each
+Chinese cue in the requirement to the OMC capability it implies, then read that
+capability's coverage/tools/boundaries from `omc-capabilities`.
+
+## 结构面 — structure
+
+| 中文线索 | Domain / Capability |
+| --- | --- |
+| 客户、联系人、供应商 | Customer |
+| 项目、合同、金额 | Project |
+| 产出、申报、月度、累计 | Output declaration / Cumulative amount |
+| 模型、对象、表、主数据 | Model |
+| 字段、属性、列 | Field |
+| 文本、长文本、数字、日期、时间、人员、部门、地址、附件、字典、关联、公式 | Field family (text-extension / numeric-logical / date-time / people-department / address-attachment / dictionary-enum / relevance / formula EXPRESSION-only) |
+| 表单、页面、布局、控件、必填、只读、显示 | Default form + form control binding |
+| 列表、视图、查询、筛选列 | List view |
+
+## 行为面 — behavior
+
+| 中文线索 | Capability |
+| --- | --- |
+| 规则、自动、校验、触发、事件 | businessrule graph (B 平面) |
+| create / update / delete 事件、按钮、定时任务 | Business-rule trigger |
+| 通知、站内通知、站内信、消息、提醒、报警、告警、ANDON | Business-rule **MESSAGE** 动作节点（站内通知，配置能力，非二开） |
+| 流程、审批、工作流、节点、待办 | Workflow template |
+| 脚本、联动、前端行为、onLoad、onValidate、预览 | Online JS (form-level) |
+
+## 集成面 — integration
+
+| 中文线索 | Capability |
+| --- | --- |
+| 集成、接口、服务、回调、对接外部系统 | B2 业务集成服务 (`service.register`)；二开接口 = 扩展模块写 REST 接口 + RESTFUL 服务指向它；自定义协议适配器 SPI 非常规、不在支持面 |
+| 数据、提交、保存、删除、查记录 | M2 runtime data |
+
+## 横切面 — landscape and boundaries
+
+Coverage status and boundaries for every capability (including 权限/子表/聚合/
+上线/内联/OCR) live in **`omc-capabilities`** — its 能力索引 table and
+[边界] section are the authority; read the relevant section there rather than a
+copy here. In particular, **跨模型/子表聚合、汇总、求和是配置能力**（表单「计算」
+FORMULA），不要当二开。
+
+Cue → capability is a starting point, never a substitute for 定面. A cue that
+could name two faces is resolved by the 定面表 in the parent skill.

package/skills/omc-start-here.md

@@ -0,0 +1,82 @@
+---
+name: omc-start-here
+description: Onboarding router — use on first contact with the OMC CLI, or when unsure which methodology topic and command ladder a task needs. Maps a task to its topic sequence and the first commands to run.
+---
+
+# Start Here (从这里开始)
+
+Router for the `omc` CLI. Two jobs: the **first-contact command ladder**, and the
+**task → topic map**. This package's `skills/` directory is the authoritative
+shipped copy; a downstream distribution snapshot is only a mirror and must not
+be treated as a second source. Read this, then follow the topics it names.
+
+## 最小路径（先读这段就能开始）
+
+1. `omc next "<目标>"`：先看返回的 `mode` 决定读/写与路径——
+   - `read`（读回/盘点/查询/检查）→ 只给**读工具**（`field.list`/`rule.get`/`workflow.get_draft`/`data.load`…），`write:false`；这是「读回现状、为下一步或写代码取证据」的入口，别回写工具。**读全一个模型用 `model.inspect <schemaCode>`（一次拿字段/表单/列表/规则/数据规则/流程摘要），别逐面 6 次调用**；`field.list` 默认只返业务字段（`all:true` 取全）。
+   - `whole-package`（做应用/系统、从零搭）→ 带 `intent` 块：写声明式意图文件，`omc intent validate/plan/apply/readback` 按依赖顺序合成原生结构，比逐能力拼装更省、更不易漂移；`intent: partial` 未覆盖的（应用/字典/集成/运行数据）再用 `call` 补。
+   - `build`/`modify` → 按阶梯内联的**写工具 + 必填参数**执行。
+   - `scout`（能不能/怎么写/是否支持）→ 先探边界（`omc-capability-scouting`），别直接写。若 `next` 返回 **`boundary`**（`match.kind:"boundary"`，如 `ocr-e-signature`/`release-prod`/`inline-coding`），说明需求**不在覆盖内**（`write:false`）：如实报告、用 `omc capabilities` 核对，**不要**用相近能力伪造实现。
+   阶梯步骤已内联工具必填参数（`route.ladder[].tools`/`readTools`）与命中 recipe 的 `describe <tool> --example <id>`；据此直接执行——**不要再逐能力 `commands --lane`**，也不要先扫 `commands --json`/全部 `contract`/全部 `describe --full`。
+   方法论按 `route.readSections` 逐节读：对每条 `{topic, section}` 执行 `omc help <topic> --section "<section>"`（单节 0.4–3.4KB）。**不要 `omc help <topic>` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。
+2. 写前只需读 `omc-config-draft-review`（人审门）与 `omc-five-piece-flow`（发现→草稿→权限→执行→回读）；`omc-business-configuration` 按命中的能力分节读（见 `next` 的 `readSections`），不要整篇预取。
+3. 环境名以 `omc doctor` 的「环境=」或 `.omc-env` 为准；工具不确定先用默认 `describe`/`--example`，只有单个工具缺形状才用 `--full`；`describe` 带 `exampleHint`/`recipeHint` 时优先 `--example`。
+4. 只有工具不在 `next` 命中能力内、或要看 purpose/枚举时，才补一次 `commands --json --compact --lane <lane>`。非显然形状（规则图、流程模板、表单布局、RESTFUL）才单独 `describe --example`。
+5. 键名按对象不同：模型 `schemaCode`、默认表单 `sheetCode`（可省略，默认 == 模型 code）、流程 `workflowCode`/`code`——报错会提示同义键；字段族名认不出会给「最接近的族」。
+6. **写操作串行**：同一环境不要并发写；`write-lock-held` 是瞬态，等几秒重试一次即可。
+7. **单个对象优先高阶编排工具**：模型+字段用 `configure_model`（一次含全部字段），表单用 `configure_form`，列表用 `listview.configure`（**默认视图已存在，省略 code 即配置它，不要 `listview.create`**）。原子工具留给单点修改。
+8. 拿到 `detailArtifactId` 先 `artifact get <id> --summary` 看结构，再 `--keys/--jq` 取所需；`field.list`/`workflow.*` 默认面已给清单与节点摘要；`workflow.get_draft` 默认面已含 `edges`，改流程只需传 `activities`+`routes`。
+9. 每个 section 读一次即可；同一 topic 不要反复读。
+10. **复杂流程先预检角色**：读 `org.role.list`/`org.user.search`，用真实可解析对象；缺独立角色就报告阻塞，不伪造。主子表条件按规则行 `schemaCode` 回所属子模型验证。
+11. **验收不只看回读**：配置后用 opt-in `npm run test:live`（`OMC_LIVE=1`），验设计器控件/条件 Set、门户字段/列表列/选项/流程；业务规则走 `data.save(workflowCode)`→`workitem.list`→`data.submit`→`data.load`。门户断言硬重载≥2次。
+
+
+Run in a **clean project directory** (not the OMC dev repo). Start from the goal:
+
+```bash
+omc next "<目标>"                          # goal → ordered route (offline)
+omc doctor                                  # environment name and readiness
+omc call discover_environment --env <env> --args '{}'
+omc capability <selected-id>               # only the selected capability
+omc describe <tool> --example <recipe-id>   # recipe first; default describe otherwise
+omc help <topic> --section "<heading>"       # one methodology section, not all
+```
+
+Discovery precedes every write. 预算档位见 `omc-tool-selection` 的「Discovery 成本档位」；裸 `omc commands` 是有界索引，全量目录须显式 `commands --json`。
+
+Fallback faces: `omc capabilities`, `omc capability <id-or-alias> --executable`, `omc commands --json --compact`, `omc contract <lane>`, `omc describe <tool>`.
+
+## 1. Task → topic map
+
+| Your task | Read, in order |
+| --- | --- |
+| "能不能做 X" / 某能力覆盖什么 | `omc-capabilities`（能力总表；判"是否二开"前先自证） |
+| Fuzzy Chinese requirement, unknown scope | `omc-requirement-analysis` → `omc-requirement-vocabulary` |
+| Configure a business model end to end | `omc-config-draft-review` → `omc-business-configuration` → `omc-write-hazards` |
+| Unsure which tool / atom vs orchestration | `omc-tool-selection` |
+| About to write anything | `omc-config-draft-review` (human gate) → `omc-five-piece-flow` |
+| A write was refused / a status looks wrong | `omc-refusals` |
+| Cover a face the manifest doesn't have yet | `omc-capability-scouting` |
+| Decide whether the work is accepted | `omc-acceptance-criteria` |
+| A term is unclear | `omc-glossary` |
+
+The core loop behind all of them: **discover → draft → permission check →
+execute → readback/cleanup** (`omc-five-piece-flow`).
+
+## 2. The two gates every write passes
+
+1. **Human gate (conversational)** — `omc-config-draft-review`: present the
+   change package in plain language and get explicit approval.
+2. **Machine gate (environment)** — the profile's `writable` permission; a
+   production environment additionally requires `confirmProduction:true` per
+   write.
+
+There is no approval token, no `--yes`, and no self-approval switch. If a call
+refuses, work out which gate or boundary produced it from `omc-refusals`.
+
+## 3. Boundaries
+
+Out-of-coverage, blocked, or unsupported faces refuse with a manifest citation —
+that refusal is the answer, not an obstacle to route around with another tool.
+Non-8.6 (or missing version evidence) fails writes closed. `uncertain` is never
+`ok`.

package/skills/omc-tool-selection.md

@@ -0,0 +1,119 @@
+---
+name: omc-tool-selection
+description: Choose the right OMC CLI tool for a goal. Use when unsure whether a task needs a high-level orchestration or a low-level atom.
+---
+
+# Which Tool When (何时用哪个工具)
+
+## Discovery 成本档位（按量级选，别一上来就点大档）
+
+实测：一条重难业务里，agent 对**发现面**的重复读占了任务上下文的大头。先走小档，缺形状再逐级放大。
+（round14 已把各面瘦身，下表为当前实测。）
+
+| Face | ~size | 用途 |
+| --- | ---: | --- |
+| `omc next "<goal>"` | 2–5 KB | 目标→路线（首选） |
+| `omc commands --json --compact --lane <lane>` | ~1 KB | 单能力工具行（最省的枚举面） |
+| `omc describe <tool>` / `--example <id>` | 1.5–2.5 KB | 单工具形状 |
+| `omc commands` | ~8 KB | 有界索引（name/lane/kind） |
+| `omc commands --json --compact` | ~13 KB | 全量紧凑行 |
+| `omc capabilities` | ~6 KB | 14 能力总览；`next` 已给路线时可省 |
+| `omc commands --json` | ~20 KB | 全量目录（回退面，尽量避免） |
+| `omc describe <tool> --full` | 7–19 KB | 仅当 schema 需要；不再重发 recipes（用 `--example` 取可运行参数） |
+
+裸 `omc commands` 只是索引；**全量目录必须显式 `--json`**。同一 face 不要反复读。
+
+## Minimal-path cheat sheet（最小路径速查）
+
+一条需求先问"它属于哪一类"，直接走对应的最小调用，别一上来铺工具：
+
+| 你要做的事 | 一次调用（最小路径） |
+| --- | --- |
+| 读全**一个模型**的配置（字段/表单/列表/规则/数据规则/流程摘要） | `omc call model.inspect --args '{"schemaCode":"<m>"}'`（`all:true` 含系统字段） |
+| **列模型** | `omc call model.list --args '{"filter":"<词>"}'` |
+| 读**某条业务规则**的图 | `omc call rule.get --args '{"schemaCode":"<m>","ruleCode":"Create"}'`（不必先 list 取 id） |
+| 读某模型的**流程**（只知模型码） | `omc call workflow.get_draft --args '{"schemaCode":"<m>"}'` |
+| **改规则一个节点/分支阈值** | `omc call rule.node.update --args '{"schemaCode":"<m>","ruleCode":"Create","nodeCode":"Branch_1","patch":{...}}'`（改完 `rule.enable` 生效） |
+| 从零**建一个流程**并发布 | `omc call configure_workflow --args '{"schemaCode":"<m>","name":"…","code":"<wf>","template":{...}}'` |
+| **建模型+字段+表单+列表** | `omc call configure_model --args '{"name":"…","code":"<m>","fields":[...],"publishForm":true,"listview":{"fieldCodes":[...]}}'` |
+| publish 流程前**只读预检** | `omc call workflow.validate --args '{"schemaCode":"<m>"}'` |
+| **批量停用**某模型规则 | `omc call rule.disableMany --args '{"schemaCode":"<m>"}'`（默认含预置行；`customOnly:true` 只停自定义） |
+| 字段清单（去噪） | `omc call field.list --args '{"schemaCode":"<m>","published":true}'`（默认业务字段，`all:true` 取全） |
+
+**业务键优先**：`rule.get`/`datarule.update`/`datarule.delete`/`workflow.get_*` 接受业务键
+（schemaCode+ruleCode / schemaCode+propertyCode / schemaCode），免去先 list 取 id。
+
+**先看 `omc next` 的 `mode`**：`read` 只给读工具；`whole-package` 给 intent 声明式指引；
+`build`/`modify` 给写工具；`scout`（能不能/怎么写）先探边界。
+
+**纯读不必先发现**：已知读哪一面就直接 `omc call <读工具>`（上表），省掉 `next`/`discover_environment`；只有选不出工具时才用 `next`。发现仪式（`next`/`capabilities`/`discover_environment`）是写前与选不出工具时的路径。
+
+## High layer — orchestrated CLI calls
+
+| Goal | Tool |
+| --- | --- |
+| Inspect environment health | `get_status` |
+| Full first look | `discover_environment` |
+| New model to usable state (model → field → field.publish → form.draft → form.publish) | `configure_model`（+ `listview` 参数到列表） |
+| Bind fields into the default form and publish | `configure_form` |
+| Business rule saved and enabled | `configure_rule` |
+| New workflow: create → update → publish (+ bind rules) | `configure_workflow` |
+| Health chain (config → credential → login → version family → fingerprint) | `doctor` |
+| Configure in-session with the human | `setup.start` → `setup.commit` |
+
+## Low layer — atoms for fine control
+
+Reads: `environment.fingerprint`, `field.list`, `form.get`, `rule.list`,
+`data.list`, `data.load`, `service.get`, `app.list`, `coverage.manifest`,
+`workflow.get_draft`, `workflow.get_published`.
+
+Writes:
+
+- Model: `model.create`, `model.delete`
+- Applications: `app.create`, `app.delete` (deleting cascades its models)
+- Fields: `field.create`, `field.update`, `field.publish`, `field.delete`
+- Forms: `form.draft`, `form.publish`
+- Rules: `rule.save`, `rule.enable`, `rule.disable`, `rule.delete`
+- Workflow templates: `workflow.create`, `workflow.update`, `workflow.publish`, `workflow.bindRule`, `workflow.delete`
+- Online JS: 本 CLI 只**发布/回读**（`onlinejs.compose`，平台模板保真）；脚本**编写**不在 CLI 范围——遵循当前项目自带的在线 JS 编写规范（若有），否则向用户/设计者索取已定稿 `source`。后端的在线开发（Java 源码）用二开扩展包，也不在本 CLI 范围
+- M2 data: `data.save`, `data.submit`, `data.delete`
+- B2 services: `service.register`, `service.delete`
+- List views: `listview.create`, `listview.configure`, `listview.delete`
+
+## Decision rules
+
+1. Default to the high layer; drop to atoms only to compose what the orchestration doesn't cover.
+2. Preview any write with `dryRun:true`; it returns the plan and executes nothing.
+3. `writable:false` refuses before any wire. A production write additionally requires `confirmProduction:true`.
+4. Out-of-coverage desire (permissions, nested child tables, OCR, app publish)? The refusal cites the manifest entry — that is the answer. Check `coverage.manifest`.
+5. If any call returns `uncertain`, stop writing and re-run discovery before the next write.
+
+## Key-name table (同一对象在不同工具里的键名)
+
+The same object is addressed under different keys. A wrong key is dropped silently
+by the Tool-input gate and then reported only as `X: Required` — it never says
+"the field you sent was ignored". Check here first.
+
+| Object | Tools | Key |
+| --- | --- | --- |
+| Model | `model.*`, `field.*`, `form.*`, `datarule.*`, `rule.*` | `schemaCode` |
+| Workflow template | `workflow.get_draft`, `workflow.get_published`, `workflow.bindRule` | `workflowCode`（或 `schemaCode`，工具内部解析） |
+| Workflow template | `workflow.create`, `workflow.update`, `workflow.publish`, `workflow.delete` | `code`（+ `schemaCode`） |
+| Default form | `form.get`, `form.draft`, `form.publish`, `configure_form` | `schemaCode`（必填）+ `sheetCode`（可选，默认=schemaCode） |
+| Field | `field.create`, `field.update`, `field.delete` | `code` |
+
+**业务键优先（identity seam）**：多个只读/改写工具现在接受业务键，免去先 list 取 id：
+
+- `rule.get` 接受 `schemaCode + ruleCode`（返回**当前生效行**，不用先 `rule.list` 拿 id）。
+- `datarule.update` / `datarule.delete` 接受 `schemaCode + propertyCode(+dataRuleType)`（同一字段多条规则时必须带 `dataRuleType` 去歧义）。
+- `workflow.get_draft` / `workflow.get_published` 接受 `schemaCode`（不是每个模型都有流程；没有则 `exists:false`）。
+
+**按工具别名（同一对象换个键名也收）**：`workflow.create/update/publish/delete` 的 `code`
+也接受 `workflowCode`；`field.create/update/delete` 的 `code` 也接受 `propertyCode`。
+别名只在规范键缺失时补入，不会覆盖；它**按工具声明**（不是全局），因为同一个 `code`
+在不同工具里可能指不同对象。
+
+精确 `id` 仍然可用，旧调用不受影响。`workflowCode` 与 `code` 指同一流程：读/绑定工具用
+`workflowCode`，写工具用 `code`（写工具现已同时接受 `workflowCode`）；读工具现在也可直接给 `schemaCode`。
+
+Fixture discipline: one-shot `omc_mcp_*` fixtures, cleaned up in reverse order, zero residue.

package/skills/omc-write-hazards.md

@@ -0,0 +1,87 @@
+---
+name: omc-write-hazards
+description: 分发版 CLI 的底层写面安全形状。配置表单、视图、按钮、子表、关联、规则或在线 JS 时使用；CLI dry-lint 是主防线，浏览器不是常规验收步骤。
+---
+
+# CLI 写面安全形状
+
+本技能随 `omc-cli` 包分发，可用：
+
+```bash
+omc help omc-write-hazards
+```
+
+优先依赖 CLI 的 schema、contract、dry-lint、writable/生产确认和权威读回。浏览器只在用户报告明确的 UI 回归时使用。
+
+## 表单与 Sheet201
+
+- 控件 `options` 必须是 **object**，不能是 JSON 字符串。8.6.34 渲染器会写 `options.name_i18n`；字符串会抛 `Cannot create property 'name_i18n' on string` 并白屏。
+- 子表父控件是 `type: 201`，业务子列放 `columns`；子列 key 不得进入 `viewJson`。
+- 调用方显式传 `draftAttributesJson`/`draftViewJson` 时，CLI 会在写前拒绝字符串 options、非字符串 viewJson 单元、子列混入 viewJson。
+- `form.draft rebuild:true` 会重建布局，但会保留已存在的非结构性控件 options；Sheet201 columns 以最新 subSchema 为准。
+- 空布局 `[]`/`{}` 默认拒绝；只有显式 `allowEmptyLayout:true` 才能清空。
+
+## 模型字段与关联
+
+- **code 定位写前先核在册**：`field.update` / `rule.node.update` 等按 code 定位的精确写，先 `model.inspect` / `field.list` 确认 code 在册；缺码即停并报"目标不存在 + 当前字段清单"——**别凭用户措辞假定 code 正确**（用户可能记错字段名），**也别擅自替换成语义相近的字段**（改错对象比不改更糟）。缺码 `field.update` 本就拒 301001，但写前先核能省一轮失败往返，并在草稿阶段就把"字段不存在"与"需求理解偏差"分清。
+- **改名核对以字段读为准**：`field.update` 改名后，`model.inspect` 聚合面的 `fields[].name` 可能仍是旧值（发布态快照/聚合缓存）；核对显示名、options 一律用 `field.list` / `field.get` 或 `form.publish` 回读——两处读数不一致时以字段读为准，别误判"写入没生效"而重复写。
+- `propertyEmpty` 默认 `false`。模型层保持可空；必填、只读、可见性在表单和流程节点配置。
+- 无映射关联单选 `WORK_SHEET` 使用 `mappings: ""`，不要用 `"[]"`。`"[]"` 是非空字符串，设计器会显示“已设置”，但弹窗没有映射行。
+- 有映射时传非空 JSON 数组字符串，并在 draft/published 两面读回。
+- **运行时写关联值是另一种形状**（`data.save`/`data.update` 的 formData）：单选关联（`propertyType 9`）传 **id 字符串或 `{ id }`**，传**数组会稳定 50000**；多选关联（11）才用数组；**人员/组织（50/51/60/61）传 `[{"id","type","name"}]`，`type` 必填**（缺它稳定 50000）——`type` 是 UnitType 索引：**用户=3、部门=1**。用错形状只会拿到一个不透明的 50000。
+- **`mappings` 由表单运行时在用户选择时套用**，服务端 `data.save` **不会**自动回填映射目标字段。API 侧要自己写被映射字段，否则读回为空——别把它误判成“映射配置失败”。
+- **运行时写值的最小形状**（组合出错只会得到一个不透明的 `50000`/NPE，逐一最小化再合）：单选关联(9) → id 字符串 `"<id>"`；**人员/组织(50/51/60/61) → `[{"id":"<id>","type":3,"name":"<名>"}]`，`type` 必填且为整数**（缺/非整数 → `BizField.parseFromClient` 拆箱 NPE→50000；用户=3、部门=1）；日期(3) → 字符串 `"2026-09-30 10:00:00"`；子表(8) → 行对象数组 `[{"<子列code>":<值>, ...}]`。先各写一条最小行通过，再组合。
+- **DATE(3) 字段的 `options.format` 必须是平台大写枚举**（`YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss`、`YYYY年MM月DD日`…），**不是 Java 的 `yyyy-MM-dd`**：平台 `DateBizField` 按字面比较，Java 写法能创建字段但**首次运行时 save 稳定 `50000`（`不支持的format`）**（2026-09-30 R5 实测）。`field.create`/`intent` 会就地拒绝非枚举值。
+
+## 视图
+
+- `conditions[].visible` 未传时 CLI 默认 `true`；只有需求明确隐藏时传 `false`。
+- `fieldCodes` 不要加入系统字段。平台可能在最终查询面保留默认系统列，那不是 agent 配置的业务列。
+- 新模型先配列表视图再依赖 `data.list`。部分 8.6.26 读面在没有 query/view 配置时会把业务列投影为 null；单行核对可用 `data.load`。
+- **默认列表视图不能单独 `listview.delete`**（平台回 `303025 列表是默认列表`）；要清掉它就删模型（`model.delete` 级联）。清理时别把它当失败。
+
+## 按钮
+
+- 列表按钮用 `listview.configure` 的 `buttons`（传 `code`/`name`/`useLocation`/`bindAction`/`targetModel`/`targetForm`…）；**不要因为没找到就叫「CLI 无列表按钮能力」**（dogfood 实测该误判会假阻塞整条需求）。配完 `listview.get --full` 回读 `customButtons`。
+- `BUSINESS_RULE` 按钮需要 target rule 和 actionConfig 对象。
+- `FLOW`/`FORM`/`ADD_DATA` 的 actionConfig 必须有 `configureList: []`；FLOW 还需要 `WorkflowListData[0].workflowCode` 与 `schemaCodeVal`。CLI 只给 FLOW 的 targetCode 时会自动展开。
+- `WITH_VIEW` 是打开表单；`WITH_OUT_VIEW` 才是直接执行。行级按钮要用 `useLocation: ROW` 才能拿到当前行上下文。
+
+## 子表
+
+- 一个主表可以有多个 `CHILD_TABLE`，子表不能嵌套 `CHILD_TABLE`。
+- 子列是子表字段 code 对应 schema 上的普通字段：
+
+```bash
+omc call field.create --env local --args '{"schemaCode":"expense_items","code":"item_note","name":"明细备注","propertyType":"LONG_TEXT"}'
+omc call field.update --env local --args '{"schemaCode":"expense_items","code":"item_note","name":"备注"}'
+omc call field.delete --env local --args '{"schemaCode":"expense_items","code":"item_note"}'
+omc call field.publish --env local --args '{"schemaCode":"expense"}'
+```
+
+父 `CHILD_TABLE` 行不接受 `options/choices/subFields` 更新；子列直接走上面的 CRUD 面。
+
+## 规则与业务集成
+
+- 规则节点缺 `nodeName` 时 CLI 按平台 `RuleNodeType` 补默认名并给 warning；业务节点优先显式命名。
+- BIZ_ACTION 先 `service.get` 读取现存方法参数面，再写 methodMapping。PROPERTY 输入使用 `codeType: 1`、`bizCode` 为业务字段 code、`propertyName` 为显示名、`serviceMethodParameterCode` 命中方法参数。
+- **`codeType:1` 映射的 `bizCode` 必须是该模型上**已创建且已发布**的字段 code**：指向不存在/未发布的字段时，平台 publish 只回一个**无明细的 `550018 保存规则失败，规则存在异常`**（真因只经设计器「检测」/`POST /api/app/businessrule/node_run_map → notExistPropertyObjectList` 可见）。`rule.save` 现已本地前置校验并拒绝（`rule-graph-bizaction-mapping-field-missing`）；改字段族类型也要同步映射。
+- **把 BIZ_ACTION 挂到预置数据事件规则（`Create`/`Update`）上时**：映射的 `bizCode` 数据项必须真实存在于该模型，否则发布被拒 `550010 业务规则使用的数据项不存在`（典型：REST 短文本入参要映射一个关联字段——先在模型加一个短文本「快照」字段承接，再映射它）。若预置规则仍不接受，改挂**自定义按钮触发规则**（`customTrigger:true`）或 `Update` 规则，更稳；不要因此判定“平台不支持 BIZ_ACTION”。
+- **BIZ_ACTION 的 `outputMappings` 按“响应 JSON 根级路径”取值**（源码 `MapOps.toMapByBizServiceJson`/`convertJsonObject`：keyMap 以 `serviceMethodParameterCode` 为键，与响应体**根级**各键匹配）。所以 `serviceMethodParameterCode` 必须等于 REST 响应**根级**的键名：
+  - **扩展接口若返回信封 `ResponseResult{errcode,data:{x}}`，平铺出参 `x` 在根级找不到 → 静默空回写**（真机 2026-10-01 实证：`h_log_biz_service` 显示 invoke SUCCESS、`data.amount:300`，目标字段仍空）。**正解：扩展接口在根级返回业务负载**（`GET` handler 直接 `return Map.of("amount", n)`，不分信封），出参 code=根键 `amount`。
+  - 也**不要**试图用输出参数的 `subParameters` 下沉取值：实测把出参声明为父 `data`+`subParameters[value]` 会把整个 `{value:99}` 子对象赋给标量字段，触发 `数据项【x】的值是未知的类型:com.alibaba.JSONObject`（50000）。嵌套出参结构只用于 OBJECT/子表类的整体赋值，不能用来“取 `data.x` 这个标量”。
+  - 对照：平台自带 `skb_risk_service` 出参平铺 `riskLevel` ↔ 响应根级键；真机三态验证：平铺根级→回写 42 ✓；信封+平铺出参→不回写 ✗；信封+嵌套出参→50000 ✗。
+  - `method.test` 的 `externalSuccess:true` **不代表**回写成功——回写要另看目标字段实际值（`data.submit` 读回）。
+- 流程结束新增目标表单必须运行验证；配置发布不等于映射成功。检查目标记录的每个字段。
+- **`model.delete` 不物理清理 `h_business_rule`**：预置规则（Create/Update/GetList/Load/Delete/Available/Cancel）与历史版本行会残留在规则表（`rule.list` 对已删 schema 也读不到，属物理孤儿）。平台写面没有“按 schema 物理清规则”的手段；验收“零残留”以**可见面**为准（`model.list`/`rule.list`/`service.get`/列表/按钮），物理行需 DB 侧清理。清理顺序让规则先于模型删能减少、但不消除预置规则行。
+
+## 在线 JS
+
+- **本 CLI 只负责发布，不负责写 JS**。脚本内容的创作与增量合并不在本 CLI：若当前项目自带在线 JS 编写规范（例如其 `.cpdocs`/技能或项目文档），遵循它；否则向用户/设计者索取已定稿 `source`。不要在 omc 技能里手写/臆造 JS 逻辑。
+- 经 omc 发布时用 `onlinejs.compose`：把已定稿的 `source` 组合进平台 skeleton 的 `customScript`，再 `publish`，并回读 `publishedHtmlJson` + SHA-256。不要用裸脚本覆盖平台 skeleton。
+- **`replace:true` 对裸代码被拒是设计**：`replace` 必须传完整的 `(function(form){…})`，否则会写坏脚本槽让表单空白；同样，`merge` 传完整带外层的脚本也会被拒（避免嵌套丢内容）。远端 `customScript` 为空时，定稿脚本带外层 + `replace:true` 即可，不要把它当成缺陷。
+- 源码不能有 import/export，事件名必须在支持集合内；compose 后读回 draft/published HTML，浏览器不是默认步骤。
+
+## 固定验收顺序
+
+执行阶段以 `omc-five-piece-flow` 为准；写面安全只额外强调两点：写前先 `commands/describe/contract` + dry-run 静态校验，写后权威 readback，必要时再用 CLI 触发运行验证。