@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,71 @@
-{
-  "name": "@stalfh233/omc-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@stalfh233/omc-cli",
+  "version": "0.4.0",
+  "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
+  "type": "module",
+  "bin": {
+    "omc": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "coverage",
+    "skills",
+    "docs",
+    "package.json",
+    "README.md",
+    "!dist/**/*.js.map",
+    "!dist/**/*.d.ts",
+    "!dist/**/*.d.ts.map"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "lint": "tsc --noEmit --pretty false",
+    "typecheck": "tsc --noEmit",
+    "coverage:manifest": "tsx scripts/coverage-manifest.ts --write",
+    "coverage:check": "tsx scripts/coverage-manifest.ts --check",
+    "test": "npm run build && node --test --import tsx test/*.test.ts",
+    "verify": "npm run typecheck && npm run coverage:check && npm test",
+    "eval:call-face": "node --import tsx scripts/run-call-face-eval.ts",
+    "eval:intent-face": "node --import tsx scripts/run-intent-face-eval.ts",
+    "eval:discovery-cost": "node --import tsx scripts/run-discovery-cost-baseline.ts",
+    "eval:discovery-comparison": "node --import tsx scripts/run-discovery-cost-comparison.ts",
+    "conformance:read": "node conformance/run-conformance.mjs --layer read",
+    "conformance:write": "node conformance/run-conformance.mjs --layer write",
+    "conformance:frontend": "node conformance/frontend-acceptance.mjs",
+    "conformance:deep-config": "node conformance/deep-config-acceptance.mjs",
+    "test:live": "node --test --import tsx test/live-acceptance.test.ts",
+    "test:live-workflow": "node conformance/live-regression.mjs",
+    "test:live-permission": "node conformance/live-permission-acceptance.mjs",
+    "sandbox:dogfood": "node conformance/setup-dogfood-sandbox.mjs",
+    "payload:report": "tsx scripts/payload-report.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "14.0.3",
+    "omc-core": "0.4.0",
+    "proper-lockfile": "4.1.2",
+    "write-file-atomic": "6.0.0",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.h3yun.com/fuwenbin/oh-my-cpagents.git",
+    "directory": "packages/omc-cli"
+  }
+}

package/skills/omc-acceptance-criteria.md

@@ -0,0 +1,47 @@
+---
+name: omc-acceptance-criteria
+description: Decide whether a CLI change is accepted. Use before claiming done: readback, delivery-state, zero-residue, and negative-test gates.
+---
+
+# Acceptance Criteria (验收标准)
+
+A change is accepted only when every gate below holds.
+
+## Per-write
+
+1. **Environment permission** — `writable:true` admits the write; `writable:false` refuses before wire. A production write additionally carries `confirmProduction:true` and records `productionConfirmed:true`.
+2. **Authoritative readback** — the post-write read proves the intended state from the authoritative face (`field.list` published face, `form.get` published flags, `data.load` for M2 data, `onlinejs.compose` publishedHtmlJson + SHA-256 for Online JS). "Called without error" is not acceptance.
+3. **Delivery state recorded** — the `.omc/` artifact exists with `deliveryState: DELIVERED` and the environment fingerprint.
+4. **Zero residue** — fixtures removed and exact absence proven on every face (draft and published); final state CLEANED.
+
+## Per-session
+
+5. **`uncertain` resolved** — every uncertain outcome was re-discovered before any further write.
+6. **Secrets zero-echo** — no output, artifact, or error contains the credential or bearer token.
+7. **Boundaries respected** — every `capability-out-of-coverage` refusal was treated as a boundary, not retried through another tool.
+8. **Draft gate evidenced** — if the session performed any write, the report must attach each design draft it presented and the human's approval turn(s) (and every revision). A write with no preceding draft/approval record fails acceptance — read `omc-config-draft-review`.
+
+## Portal/DOM acceptance (opt-in, real platform)
+
+Storage readback is NOT platform consumption. When the change is a form/design
+artifact, the strongest acceptance is the opt-in live batteries — and they ARE
+the "open a browser" step; do not report "no portal acceptance entry point":
+
+- `npm run test:live` — designer canvas, condition panels **and the condition
+  dialog must render >=1 rule row** (a serialization can crash the formatter and
+  silently drop the row while the panel still says "Set"), portal fields (two
+  loads), list columns, list buttons, Online JS wrapper + `window.h3form` boot.
+- `npm run test:live-workflow` — two-stage workflow + rule write-back via
+  `data.save(workflowCode)` → `workitem.list` → `data.submit` → `data.load`.
+- `npm run test:live-permission` — node field permissions read from
+  `form/load.formPermission.dataPermissions` as a NON-admin participant (an
+  admin is force-granted `e:true`).
+
+## Negative baseline (must stay green)
+
+- Read-only environment → `environment-write-disabled`, zero wire calls.
+- Writable production without `confirmProduction:true` → `production-confirmation-required`, zero wire calls.
+- Concurrent writes → serialized by the write lease (max 1 in flight).
+- Blocked lane (e.g. `W2-permissions`) → refused with citation.
+- Transport outage during a write → `uncertain` + `frozen`, never `ok`.
+- Non-8.6 version (or missing version evidence) → writes fail closed.

package/skills/omc-business-configuration.md

@@ -0,0 +1,257 @@
+---
+name: omc-business-configuration
+description: 中文 CloudPivot 业务配置 runbook。用于把模型、字段、表单、视图、子表、流程权限、业务规则、按钮、在线 JS 和现存业务集成方法按需求落地并验收。
+---
+
+# CloudPivot 业务配置 Runbook
+
+本技能讲业务需求如何落成配置包；底层 wire 形状和白屏陷阱见 `omc-write-hazards`。
+
+## 入口
+
+```bash
+CLI="packages/omc-cli/dist/cli.js"
+node "$CLI" commands --json
+node "$CLI" describe <tool>
+node "$CLI" contract <lane>
+node "$CLI" call discover_environment --env <env> --args '{}'
+node "$CLI" help omc-config-draft-review
+node "$CLI" help omc-five-piece-flow
+```
+
+## 需求五维
+
+把需求拆成五个维度（注意：这是**需求维度**，不同于 `omc-five-piece-flow` 的"五件套"执行五阶段）：
+
+1. **模型**：主对象、应用、业务 code。
+2. **字段**：类型、选项、关联目标、模型可空性。
+3. **表单与视图**：控件、子表 Sheet201、列表列、排序、筛选、按钮。
+4. **流程**：节点、参与人、每节点字段权限。
+5. **自动化**：规则、流程绑定、按钮、业务集成、在线 JS。
+
+## 标准顺序
+
+**配置顺序以 `omc-config-draft-review` §8 为唯一真相**（模型 → 字段 → 发布 → 表单 → 视图 → 规则 → 流程）；执行阶段见 `omc-five-piece-flow`。本 runbook 只补充业务侧要点：
+
+1. 读环境基线：应用、模型、字段、表单、视图、流程、规则、服务。
+2. 出中文草稿（`omc-config-draft-review`）：环境、应用、资源 code、字段表、流程图、映射、按钮、清理方案。
+3. 取得用户明确确认；确认前不写环境。
+4. 需求包含运行行为时，用 CLI 真实触发；测试数据的保留/清理要写进草稿。
+
+完成标准：每项资源有 readback；每个运行写入有 delivery 状态；每个映射字段都有目标值；失败步骤、已完成步骤和清理动作可追踪。
+
+## 模型与字段
+
+- 模型层字段默认可空；必填、只读、可见性在表单和流程节点配置。
+- `propertyEmpty` 默认 `false`，不要把业务必填硬编码在数据模型。
+- 关联单选优先读目标模型已发布字段，明确显示字段；无映射不要写空数组字符串。
+
+## 子表
+
+一个主表可以有多个子表，但子表不能嵌套子表。
+
+创建父字段：
+
+```json
+{
+  "schemaCode": "expense",
+  "code": "expense_items",
+  "name": "费用明细",
+  "propertyType": "CHILD_TABLE",
+  "subFields": [
+    { "code": "item_name", "name": "费用项目", "propertyType": "SHORT_TEXT" },
+    { "code": "item_amount", "name": "金额", "propertyType": "NUMERICAL" },
+    { "code": "item_date", "name": "发生日期", "propertyType": "DATE" }
+  ]
+}
+```
+
+子列像主表字段一样 CRUD，但 schemaCode 是父字段 code：
+
+```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"}'
+```
+
+父表单重建后，Sheet201 控件应有业务子列，子列 key 不应出现在普通 `viewJson`。
+
+声明式面同样支持子表（`intent.yaml`），子列写在父字段的 `subFields` 下；子列只接受标量族，不能嵌套子表/关联/公式：
+
+```yaml
+models:
+  - code: expense
+    name: 费用报销单
+    fields:
+      - code: expense_items
+        name: 费用明细
+        type: CHILD_TABLE
+        subFields:
+          - code: item_name
+            name: 费用项目
+            type: SHORT_TEXT
+          - code: item_amount
+            name: 金额
+            type: NUMERICAL
+```
+
+`intent plan/apply/readback` 会把子列的缺失、改名、类型漂移当成独立差异（`subfield:` 资源）；新增子列自动编译成 `field.create --schemaCode <父字段 code>` 并触发模型级 `field.publish`。父字段本身改名仍用 `field.update`，`field.update` 不接受 `subFields`。
+
+`intent apply` 默认在交付后自动做一次最终读回等价确认：等价则 `verification.status:"ok"`；不等价则整体 `refused` + `blocker:"intent-readback-mismatch"`（exit 12），**绝不当作成功**——按 `verification.differences` 定位后重新 `intent plan`，不要盲重试。`--no-verify` 可关闭该确认（只在你已单独跑 readback 时）。
+
+业务规则也进了声明式面（`models[].rules[]`）。常用数据事件规则用紧凑 `actions`，编译器合成 nodeGraph；复杂图用 `nodeGraph` 原样透传（二选一）：
+
+```yaml
+rules:
+  - code: Update                 # 平台预置码（Create/Update/Delete…）或自定义码
+    name: 更新归档
+    enabled: true                # true → 额外 rule.enable（publish+启用）；false → 已启用则 rule.disable
+    actions:
+      - type: UPDATE
+        target: archive_model     # 同模型可省略 target（默认本模型）；跨模型才必须写
+        filter:
+          - field: source_no
+            from: doc_no          # from = 动态（触发字段）；或比较键：equals/notEquals/gt/gte/lt/lte: <标量>
+        set:
+          - field: amount
+            from: total           # from = 动态；也可 value: <字面量>
+```
+
+- **每个 filter 项必须有且只有一个条件来源**：`from`（动态 EQ）或一个比较键（`equals`/`notEquals`/`gt`/`gte`/`lt`/`lte` + 标量）。缺来源 `intent-rule-leaf-source-missing` 拒绝；**绝不**静默成 `EQ null`。
+- 动作节点的条件分「定位数据」与「执行门」两类，**别混**（详见下「规则图的触发条件」）。
+- **跨模型写（`targetObjectCode`≠规则模型）平台支持、可运行时生效**（2026-09-28 真机复核）。两个前提：① 承载它的规则必须真的触发——`Create` 规则在提交时触发；`Update` 规则只在 `data.update` 触发，**submit 不执行它**（放进 `Update` 是典型静默空转，lint 警告 `rule-graph-cross-model-update-trigger-inert`；也可绑定流程事件如 `end`）。② 目标行必须已提交——目标查询不匹配 DRAFT 行，`data.save` 未 submit 的行不回写。
+- 关联字段：`type: WORK_SHEET` + `relativeCode: <目标模型>` + `options.displayField`，与 `field.create` 行形状一致。（键名是 `relativeCode`，wire 键 `relativeSchemaCode`，别混。）
+- 节点显示名用 activity 级的 `name`（`participant.name` 只作参与者说明，平台不认作节点名；`{type: Originator, name: 部门负责人}` 会被工具提升为节点名）。
+- **字段级数据规则**（`models[].datarules[]`，`dataRuleType` 1校验/2计算/3拼接/4必填/5只读）——注意是 `dataRuleType`（不是 `type`）：
+  ```yaml
+  datarules:
+    - { propertyCode: order_note, dataRuleType: 4, options: { requiredFormula: '{amount} 大于 {"valueType":"custom","value":5000}' }, name: 金额超5000说明必填 }
+  ```
+  ⚠️ **type 3/4/5 不驱动门户表单控件**（真机复核）：平台存成 bizdatarule，只镜像进控件 `historyOpt`，运行时门户读的是控件 `options`。门户条件（如「金额>5000 时必填」）必须写在 `fields[].options`（`requiredFormula`/`readonlyCondition`/`shortTextStitch`）；写进 `datarules[]` 设计器可见但门户不拦（validate/plan 给 `datarule-not-portal-facing` 警告）。datarule 只用于服务端引擎（校验/计算）。
+
+- 规则排在字段发布之后（编译器按能力排序：先建全部模型/字段，再跑规则）。
+- `rule.save` 只写草稿；`enabled` 由 `rule.enable` 保证（publish+启用）——readback 用 `enabled` 和**语义图摘要**（忽略画布几何）判等价。
+
+## 表单与视图
+
+- 新字段加入已有表单：`form.draft --rebuild`，然后 `form.publish`。
+- rebuild 会保留已识别的关系映射、显示和布局 options；Sheet201 columns 按最新子表字段刷新。
+- **配置列表视图用 `listview.configure`（省略 `code` 即平台自动生成的默认视图 code=schemaCode），不要先 `listview.create`——那会多出一个视图。** 只有确实要第二个视图才 create；两者职责分开。
+- 数值控件：`scale` 是小数位数（0=整数,1=1位,2=2位…）；「金额两位小数」用 `scale:2`。列表列 displayFormat 由 scale 推导。
+- **列表列只放业务字段**：平台 `listview.create` 会预置系统列（`name/creater/createdTime/sequenceNo`）和一条 `createdTime` 默认筛选；intent 的 `fieldCodes` 是权威集合，编译器用 `replaceColumns:true + hideDefaultSystemFields:true + conditions:[]` 清掉预置项。要展示某系统列/筛选就显式点名。
+- 筛选条件默认显示：`conditions[].visible` 不传也应为 true。
+- 配置默认视图后即可用 `data.list`；否则部分 8.6.26 读面业务列可能为 null，单行用 `data.load` 核对。
+- 读回视图用 `listview.get`（默认回列/排序/条件/动作紧凑清单）与 `listview.list`。
+
+## 流程字段权限
+
+新增字段后，必须重新检查每个参与节点的 `propertyPermissions`：
+
+- 填写节点：需求要求的字段可编辑，必要字段必填。
+- 审批节点：通常 `visible:true, editable:false, required:false`。
+- 不需要展示的字段明确 `visible:false`。
+
+**怎么配**（没有单独的权限工具，别把「找不到入口」当不支持→假阻塞）：`workflow.get_draft --full` 读节点正文，改目标
+`ParticipantActivity.propertyPermissions[]`（`{propertyCode, visible, editable, required, summary, subPropertyPermissions}`），
+用 `workflow.update` 原样回写，再 `workflow.publish`。**要生效必须 `summary:true`**（只有它进运行时 `activitySummaries`；
+否则 `form/load` 的 `formPermission.dataPermissions` 回退默认，读不到你的 `editable:false`）；子表列用 `subPropertyPermissions`。
+验收用 `npm run test:live-permission` + **非管理员参与者**（管理员会被后端强制 `e:true` 掩盖）。
+
+声明式流程（intent）的 `workflow.template` 用 **`activities` + `routes`**（不是 `nodes`/`edges`）：活动 `{id, type: START|END|PARTICIPANT|…, participant?}`，路由 `{preNode, postNode}` 必须指向已声明活动 code；`workflow.update` 只从 `activities` 读节点，写 `nodes` 会在 apply 时 `rules[0] references an unknown activity`（validate 会提前拦）。
+
+示例：
+
+```text
+开始 → 填写申请单 → 部门审批 → 财务审批 → 结束
+```
+
+如果环境里存在测试节点，先确认保留还是删除，不要静默覆盖。
+
+## 业务规则
+
+**先选对机制，别一律上规则图**（三者代价差很大）：
+
+| 需求形态 | 用哪个 | 入口 |
+| --- | --- | --- |
+| 条件必填 / 条件只读 / 恒只读（表单交互层） | 字段 `options` | `field.update --example form-conditional-required` / `form-conditional-readonly` / `form-always-readonly` |
+| 服务端字段级校验 / 计算 / 拼接 / 显示（type 1..5） | 数据规则 | `datarule.create`（字段级引擎） |
+| 数据事件自动化（创建/更新时改字段、调服务、发起流程） | 规则图 | 本节 `rule.save`（`--example standard-business-rule-graph`） |
+
+「超过某值必填 / 等于某值只读」= **字段 options**，**不要**建规则图、也**不要**用 `datarule.create`
+（实测：`datarule` type3/4/5 不会让门户表单控件变必填/只读，且符号式经 `historyOpt` 镜像会让表单渲染崩溃；
+平台的 bizdatarule 会被镜像进表单控件 `historyOpt`，而设计器/运行时读的是控件 `options`）。
+
+### 条件式（必填/只读/显示）怎么写
+
+- **恒必填**：`requiredFormula: "true"`（字面量）；**条件必填**：`requiredFormula: "{触发字段} 操作符 {\"valueType\":...,\"value\":...}"`。
+- 操作符用**中文**（设计器产出）：等于/不等于/大于/小于/大于等于/小于等于/包含/包含全部/等于任意一个/为空/不为空；也接受符号 `== != > >= <= Contains IsEmpty`。为空/不为空**不带值**。
+- 写完后 `field.publish` → `configure_form`（同步进控件）→ **门户打开表单改触发字段的值**，断言目标控件变 `required` / `disabled`（存储回读不算验证）。
+- 恒只读：`readonlyFormula: true`。
+
+### 规则图的触发条件（关键）
+
+规则支持**触发条件**，不要用「两条无条件规则」表达互斥结果：
+
+- **节点级条件有两大类，别混**（各节点类型都可能有，完整字段/样例见 `describe rule.save --full` 的 RULE_NODE_TEMPLATES）：
+  - **定位要操作哪些数据**（`filterCondition`：叶 `targetSchemaDataItem`+`ruleConditionType`）：UPDATE=改哪条（空=整表）、DELETE=删哪条、CREATE=存在符合则不新增+`findMainData`、QUERY=`targetConditionGroups`、**ASSIGN=在输入数据源匹配要取值的行（不是执行门！）**。⚠️ 非唯一字段（金额等）会命中**多条**；改「当前/关联那一条」用唯一键（`id` 或 `from`）。`actions.filter` 表达这类（同模型省略→默认 `id=id`；跨模型省略 fail-closed）。
+  - **执行门 / 满足条件触发**（`dataCondition`，BIZ_ACTION 用 `execConditionGroups`）：**与定位两码事**——决定「要不要执行」，不决定「改哪条」。compact `actions.when` 表达 UPDATE 执行门（叶 `currentSchemaDataItem`+`ruleDataConditionType`）；其它节点用 `nodeGraph`。**条件改自身**：`when: [{field: amount, gt: 10000}]` + 省略 `filter`（默认 `id=id`）——别把条件写进 `filter`，那会改掉所有符合的行（bench66 多行互覆）。
+  - 子表定位 `filterSubCondition`；子表触发范围 `childTriggerConditionType∈ADD/MODIFY/DELETE`。
+- **触发时机**：数据事件（`Create`/`Update`/`Delete`）**只分发到平台预置 code 行**；流程相关用预置 `Available`（流程生效）/`Cancel`（流程作废），或流程事件绑定 `workflow.bindRule` 的 `end`/`cancel`/`start`/`activate`。
+- **预置规则身份不可改**：`Create`/`Update`/`Delete`/`Load`/`GetList`/`Available`/`Cancel` 名称由平台维护（`Create`=数据新增）；传 `name` 不生效（仅自定义规则名称可改），可改的是节点名 `nodeName`。
+- **流程事件只绑自定义规则**：`workflow.bindRule` 的 `ruleCodes` 只能给自定义 code——设计器的事件规则选择器不提供预置触发行（绑 `Create` 到 `end` 非法，工具 fail closed）。要「审批通过后执行某逻辑」：新建自定义规则承载动作节点再绑 `end`。
+- **审批通过/驳回回写**：通过绑 `end`（或 `Available`）、驳回绑 `cancel`（或 `Cancel`）——**不要**把两条各自 FIXED 赋值的规则都绑到 `endEventHandler`（两条都会执行、后者覆盖前者；工具会在 `bizActions.length>1` 时回读 `advisory` 提醒）。真实生产只在 `endEventHandler` 绑**一条**多分支规则图。
+
+规则图需要显式：
+
+- `ruleCode`、名称、触发方式
+- 每个节点 `nodeName`
+- `nodeType`、路由、目标模型
+- 主表/子表 `findMainData`
+- 每个映射的 source/target 字段：**新增/更新节点的字段映射 = `dataActions`**（每目标字段一条叶：`{targetDataItem, ruleValueType:"DYNAMIC"/"FIXED", value:""/字面量, ruleActionType:"EQUALS", currentDataItemValue:"<来源字段>"}`）。**`execFormMapping` 只是展示开关，不是映射来源**——只写 `execFormMapping:true` 不写 `dataActions`，「主表字段值设置」是空的、新增行业务字段全 null（工具对 `execFormMapping:true` 缺 `dataActions` fail closed `rule-graph-create-mapping-missing`）。**写跨表节点前先 `rule.get` 读一条真实同型规则（如 `purchase_request`/`Create`）当基线**，不要从模板推断。
+
+流程结束后新增目标表单，配置发布后要真实跑完流程，再读目标表单每个字段（`data.load`，不是 `data.list`——后者只投影列表列）；只看到规则 `ENABLED` 不等于映射成功。
+
+## 业务集成
+
+优先复用现存 service/method，不做无必要的部署：
+
+```bash
+omc call service.get --env local --args '{"serviceCode":"omc_demo_restful"}'
+```
+
+- **新写一个接口 ≠ 新建一个服务**。同一个服务下可以挂多个方法：新服务用 `service.register`（`serviceCode` 已存在会 `duplicate-service` 拒绝），**往已有服务加方法用 `method.create`**（服务不存在 → 拒绝并提示先用 `service.register`；方法已存在 → 拒绝并提示改用 `method.update`）。不要为加一个方法而删服务重建（会连带丢掉服务的其它方法与规则绑定）。
+
+BIZ_ACTION：
+
+- 先读方法输入/输出参数面。
+- `codeType: 1` 的 PROPERTY 输入：`bizCode` 是源字段 code，`propertyName` 是显示名，`serviceMethodParameterCode` 必须命中方法参数。
+- **常量入参用 `codeType: 0`(CONST)**（如固定请求头 `X-LowCode-Corpid`）：值可放 `bizCode`，也可放 `value`（工具会自动移入 `bizCode`）。平台 CONST **只读 `bizCode`**——`value`/`expressionValue` 原样存着的话，运行时取到的是字面 `null`。
+- 参数面每参数必带 `bizPropertyType`（参数类型），否则业务规则按类型匹配字段会失败、映射不到（缺失即拒绝）；`externParameterType`/`description` 工具补齐。**返回值参数默认不必填（`required:false`），入参按需必填**——返回值声明为必填会经规则 designer 的 `required` 镜像强制每条输出映射也必填，是绑定摩擦的常见来源。
+- `rule.save` 自动补 `serviceName`/`serviceMethodName`/节点 `nodeCategory:"actionNode"`/映射元素 `index`（弹窗异步加载，稍候再判空）。
+- 配规则后读回 methodMapping，再用按钮或流程实际触发一次。
+- 服务、方法、参数不确定时拒绝猜，先读证据。
+
+## 按钮与在线 JS
+
+- 直接执行规则：`useLocation: ROW` + `operateType: WITH_OUT_VIEW`。
+- `WITH_VIEW` 是打开表单。
+- FLOW 按钮需要 workflowCode；CLI 会补安全的 actionConfig。
+- **在线 JS 分两条**：本 CLI 只做**发布与回读**——用 `onlinejs.compose` 把已定稿的 `source` 组合进平台 skeleton 的 `customScript` 再 publish，回读 `publishedHtmlJson`+SHA-256。**脚本内容的编写/增量合并不在本 CLI**：若当前项目自带在线 JS 编写规范（例如其 `.cpdocs`/技能或项目文档），遵循它；否则向用户/设计者索取已定稿的 `source`。不要在 omc 侧手写或臆造 JS 逻辑。
+
+## 运行验收与清理
+
+运行测试前在草稿里列出：
+
+- 测试输入值
+- 预计生成的记录/调用
+- 每个字段的验收值
+- 清理哪些测试数据，保留哪些配置
+
+推荐顺序：
+
+```text
+配置读回 → CLI 运行触发 → workitem/data/service 读回 → 比较字段 → 清理测试数据
+```
+
+浏览器不是常规验收步骤；只有用户报告 UI 回归时才做专项诊断。

package/skills/omc-capabilities.md

@@ -0,0 +1,197 @@
+---
+name: omc-capabilities
+description: The OMC capability catalogue — what each capability can do, its tools, recipes, and boundaries. Use to answer "can OMC/platform do X?" and to find the tool for X before discovery.
+---
+
+# Capability Catalogue (能力总表)
+
+The one place that says **what OMC can configure and what each capability
+covers**. Read it when you need to answer "能不能做 X？/ 用哪个能力？" yourself —
+before you escalate the question to the user, and before you decide "X 要二开".
+
+This topic is the **prose authority** for capability coverage; `omc capabilities`
+/ `omc next` / `omc capability <id>` are its machine-readable projection over the
+same 15 capabilities (a `verify` test fails if the two drift). A concrete wire
+shape is always reached by `omc describe <tool> --example <recipe>` — this
+catalogue only names the tool and the recipe, never re-specifies the payload.
+
+**How to read it (progressive disclosure):** scan the 能力索引 table, then read
+only the section for the capability you need —
+`omc help omc-capabilities --section "<能力>"`. Do not load every section.
+
+## 能力索引
+
+| 能力 | 一句话 | 能做哪些事（需求线索） | 读哪节 |
+| --- | --- | --- | --- |
+| 环境治理 `environment` | 环境发现/指纹/就绪 | 环境、指纹、版本、连接、登录、就绪、发现 | [环境治理](#环境治理-environment) |
+| 应用 `app` | 应用包生命周期 | 应用、门户、分组、app 建删移 | [应用](#应用-app) |
+| 数据字典 `dictionary` | 字典与字典记录 | 字典、选项来源、树型、键值、字段下拉来源 | [数据字典](#数据字典-dictionary) |
+| 业务模型 `model` | 模型生命周期 | 模型、对象、表、主数据、改名、物理删除 | [业务模型](#业务模型-model) |
+| 字段 `field` | 字段族 + 子表 + **计算字段** | 字段、属性、子表、明细、下拉、单选、多选、附件、人员、部门、日期、数值、关联、**公式/计算/求和/汇总/合计/回主表** | [字段](#字段-field) |
+| 默认表单 `form` | 表单布局与发布 | 表单、页面、布局、控件、只读、显示 | [默认表单](#默认表单-form) |
+| 列表视图 `listview` | 列表表头与列 | 列表、视图、查询列、筛选、表头、甘特 | [列表视图](#列表视图-listview) |
+| 字段级规则 `datarule` | 字段级控件规则 | 字段级规则、控件规则、校验规则、计算拼接、显示规则、条件必填/只读/显示 | [字段级规则](#字段级规则-datarule) |
+| 业务规则 `businessrule` | 图形规则图 + **定时任务** | 业务规则、触发器、规则图、事件、BRANCH、BIZ_ACTION、**定时任务/定时/每天/周期/调度** | [业务规则](#业务规则-businessrule) |
+| 规则生命周期 `rule-lifecycle` | 规则启停删 | 启用规则、停用规则、删除规则、规则启停 | [规则生命周期](#规则生命周期-rule-lifecycle) |
+| 流程模板 `workflow` | 审批流程模板 | 流程、工作流、审批、节点、待办、流转、参与人、审批人 | [流程模板](#流程模板-workflow) |
+| 表单在线 JS `onlinejs` | 表单脚本发布/回读 | 在线js、脚本、联动、onload、onvalidate | [表单在线 JS](#表单在线-js-onlinejs) |
+| 业务集成 `bizservice` | 集成服务与方法 | 集成、接口、服务、回调、对接、外部系统、datasql、restful | [业务集成](#业务集成-bizservice) |
+| 报表 `report` | 报表页 + BI 图表（**仅显式要求时**） | 报表、图表、看板、bi、dashboard（用户点名的才做） | [报表](#报表-report) |
+| 运行数据 `data` | 业务记录读写 | 运行数据、提交数据、保存记录、查记录 | [运行数据](#运行数据-data) |
+
+**边界**（不在覆盖内）见 [边界](#边界boundaries)。**落点判据**（配置 vs 二开）
+的唯一权威源是 `cpdocs-guide` 的「落点」。
+
+---
+
+## 环境治理 `environment`
+
+- **能做哪些事**：读环境指纹与版本桶（决定证据版本）；就绪自检（登录/许可证/最小路径），写入开关与生产授权在 `omc setup`。
+- **工具**：`discover_environment`、`environment.fingerprint`
+- **边界 / 陷阱**：只读；不进 intent（用 `omc setup` / `discover_environment`）。写前一律先确认环境真相。
+
+## 应用 `app`
+
+- **能做哪些事**：列出应用包、创建、改名/分组移动、删除（删除级联其模型）。
+- **工具**：`app.list`、`app.create`、`app.update`、`app.delete`
+- **边界 / 陷阱**：环境已带默认 `applicationCode`，建模**不必**先建应用；未进 intent，用 `omc call app.*`。
+
+## 数据字典 `dictionary`
+
+- **能做哪些事**：字典与字典记录全生命周期（键值型/树型、启停）；作为选择字段的选项来源；字典分类。
+- **工具**：`dictionary.list`、`dictionary.type`、`dictionary.names`、`dictionary.get`、`dictionary.records`、`dictionary.save`、`dictionary.status`、`dictionary.usage`、`dictionary.parent`、`dictionary.classes`、`dictionary.class.save`、`dictionary.class.delete`
+- **recipe**：`omc describe dictionary.save --example dictionary-key-value`
+- **边界 / 陷阱**：选择字段有三种选项来源——`custom` / `dictionary` / `businessModel`；关联单选/多选支持 `searchFormula` 与 `conditions` JSON 筛选。
+
+## 业务模型 `model`
+
+- **能做哪些事**：模型创建、改名、物理删除（`absent:true` 回读）、存在性、批量删除、摘要；一次建模型+字段+表单用 `configure_model`。
+- **工具**：`model.list`、`model.inspect`、`model.create`、`model.delete`、`model.deleteMany`、`model.setSummary`、`model.update`、`configure_model`
+- **recipe**：`omc describe configure_model --example model-with-fields-form`
+- **边界 / 陷阱**：`model.inspect <schemaCode>` 一次拿全字段/表单/列表/规则/流程摘要，别逐面 6 次调用。**保留 code**：字段 code 用 `name` 会被平台占用，须避开。**每个模型都必须建并发布默认表单**——只建模型不建/不发布表单则无法录入查看（`configure_form` 或 `form.draft(rebuild:true)` + `form.publish`）。**「汇总/统计/按月」类需求**：常见做法是**一张汇总表**（独立业务模型，如 `x_monthly_summary`）接住结果，用定时任务/规则把源数据汇总写进去——**但这按需求定**，不是写死的规则。需求确认时把"汇总表"作为常规选项提出来跟用户确认，别默认往报表或二开上引。
+
+## 字段 `field`
+
+- **单据号/自动编号（原生，勿二开）**：单据号是表单 **Serial Number 控件**（字段类型 100 SequenceNo）的 `options.seqNoSetting` 分段构建器（CONSTANT/DATE/SEQNO/DATAITEM/UID 段），SEQNO 段 `resetDate:DAY/MONTH/YEAR` 原生按期重置——`describe field.update --example field-serial-number`。**不要落 SequenceService SPI 二开**（r5-crm 实证重造轮子）；编号生成时机=submit（`data.save` 不生成）。
+
+- **能做哪些事**：字段族全链 create→publish→表单绑定；**CHILD_TABLE 子表**（子列是 schemaCode=父字段 code 上的普通字段）；**计算字段**（默认用普通字段 + 「计算规则」，见下）。
+- **工具**：`field.list`、`field.create`、`field.update`、`field.publish`、`field.delete`
+- **recipe**：
+  - `omc describe field.create --example numeric-two-decimals`（数值 + scale）
+  - `omc describe field.create --example dictionary-backed-single-select`
+  - `omc describe field.create --example minimal-child-table`（子表 + 标量子列）
+  - `omc describe field.create --example business-model-dropdown`
+- **边界 / 陷阱**：
+  - **计算类需求默认走「普通字段 + 计算规则」，不要建「计算公式」字段类型（FORMULA）**：建一个**数值/单行文本**业务字段，再配一条**字段级计算规则**（`datarule.create` `dataRuleType:2`，`options.shortTextStitch={"formula","editorText","editorMark"}`）。理由：平台约定用正常业务字段承载、顺带配计算规则（真机 2026-10-08 production 表单核验 + 设计器弹窗显示）。「计算公式」字段类型不是默认，仅当确需一列专用公式时才用。
+  - **计算规则公式引用**：同类字段裸 `{字段code}`（`{a}+{b}`）；**子表列用 `{子表字段code.子列code}`**（`{Sub_item_information_table.taxInclusiveAmount}`）；子表求和 `SUM({子表.子列})`；支持 `IF(cond,a,b)`、`CASE(v,c1,r1,c2,r2)`、`VALUE()`、`AND`、比较 `=`、字符串字面量与运算符空格。recipe：`omc describe datarule.create --example field-compute-rule|field-compute-subtable-sum|field-compute-child-column`。
+  - 计算由**门户前端**执行，API（`data.save/update`）不回填/重算——写测试数据带预算值，正确性人工前台确认。（FORMULA 字段类型仍受支持，但非默认。）
+  - 计算由**门户前端**执行，API（`data.save/update`）不回填/重算——写测试数据带预算值，正确性人工前台确认。
+  - 子表列支持标量族 + WORK_SHEET 关联列（需 `relativeCode`+options）；**嵌套子表 / MULT_WORK_SHEET / RELEVANCE_DATA 不覆盖**。
+
+## 默认表单 `form`
+
+- **能做哪些事**：表单 draft-first 布局、发布、`publishedHtmlJson` 绑定读回；把已发布字段绑进默认表单。
+- **工具**：`form.get`、`form.draft`、`form.publish`、`configure_form`
+- **recipe**：`omc describe configure_form --example publish-default-form`
+- **边界 / 陷阱**：默认表单已存在，用 `configure_form`/`form.draft(rebuild)` 改它，不要新建。
+  - **每个模型交付前其默认表单必须已发布**：只建草稿=用户无法录入/查看。用 `configure_form` 或 `form.draft(rebuild:true)`+`form.publish` 发布。
+  - **发布态以 `form.get` 的 `published`/`existDraft` 布尔为准**，不要看 `publishedControlCodes` 是否非空（草稿字段也非空，会误判）。交付前列出每个模型的 `form.get.published` 核对。
+  - **写业务数据的前提是先发布模型+表单**：正确顺序 = 建模型 → 发布字段（`field.publish`）→ 建并**发布**默认表单（`form.publish`）→ 才 `data.save`/`data.submit`。不要在建/未发布状态下写业务数据。
+
+## 列表视图 `listview`
+
+- **能做哪些事**：视图表头列、排序、筛选条件生命周期（create/configure/delete）。
+- **工具**：`listview.get`、`listview.list`、`listview.create`、`listview.configure`、`listview.delete`
+- **recipe**：`omc describe listview.configure --example configure-default-list`
+- **边界 / 陷阱**：默认视图已存在，`listview.configure` 省略 code 即配置默认视图。**按字段分组（queryLayer）未取证**——别猜写。
+
+## 字段级规则 `datarule`
+
+- **能做哪些事**：字段级数据规则（bizdatarule）create/update/delete；条件必填（type4）、条件只读（type5）、条件显示（type3）、计算拼接（type2）等，按平台校验器闭环。
+- **工具**：`datarule.list`、`datarule.create`、`datarule.update`、`datarule.delete`
+- **recipe**：
+  - `omc describe datarule.create --example datarule-conditional-required`
+  - `omc describe datarule.create --example datarule-conditional-readonly`
+  - `omc describe datarule.create --example datarule-conditional-display`
+- **边界 / 陷阱**：目标字段必须已发布；同一字段多条规则时 update/delete 必须带 `dataRuleType` 去歧义。
+
+## 业务规则 `businessrule`
+
+- **能做哪些事**：图形规则图（nodeGraph）——数据事件（Create/Update/Delete）触发、按钮/流程触发、动作节点（UPDATE/CREATE/DELETE/QUERY/ASSIGN/MESSAGE/BIZ_ACTION/GET_LIST…）、BRANCH 条件分支、**定时任务 TIMING_TASK**（每天/周期，SCHEDULER 节点）。
+- **工具**：`rule.list`、`rule.get`、`rule.save`、`rule.node.update`
+- **recipe**：
+  - `omc describe rule.save --example standard-business-rule-graph`
+  - `omc describe rule.save --example business-rule-branch-conditional`
+  - `omc describe rule.save --example rule-timing-task`（**每天/周期定时执行**）
+- **边界 / 陷阱**：
+  - **「每天定时执行」= 定时任务 TIMING_TASK，是平台原生配置，不是外部定时器、不是在线 JS、无需二开**；`nodeGraph.bizRuleType:2` + SCHEDULER 节点 + `nodeGraph.schedulerSetting`。
+  - 数据事件只分发到平台预置 code 行（Create/Update/Delete）；自定义 ruleCode 需按钮/流程/定时/显式触发。
+  - 保存 ≠ 可见，需 `rule.enable`（见 rule-lifecycle；绑流程事件前必须 enable，否则运行时 Business rule does not exist——r3-wms 实测）。BRANCH 多出口是「全部命中即走」，分级互斥用嵌套 BRANCH。
+  - **无存在性/计数判定原语**：BRANCH 不能按「QUERY 是否返回行」分支（PRE_OUT 分支不接收 QUERY 空结果，r3-wms 实测）。因此**硬拦保存做不到**（重复校验只能降级为打标，且**规则图内 QUERY→UPDATE 打标会静默空转**（8.6.26 UPDATE 的 inputParam 只认触发行 `_input`，`_QN_output` 引用被忽略——r4-fin 双跑实证 2026-10-09）。唯一可靠路径=改写预置 Create 规则挂 BIZ_ACTION 自调二开 markDuplicates（见 `describe rule.save --example data-duplicate-flag`））。
+
+## 规则生命周期 `rule-lifecycle`
+
+- **能做哪些事**：业务规则的启用、停用、批量停用、删除。
+- **工具**：`rule.enable`、`rule.disable`、`rule.delete`、`rule.disableMany`、`configure_rule`
+- **边界 / 陷阱**：`enabled` 是运行时真相，`status` 可能滞后。`rule.disableMany` 默认含预置行，`customOnly:true` 只停自定义。
+
+## 流程模板 `workflow`
+
+- **能做哪些事**：流程模板 get_draft/get_published、create、update、publish、bindRule（事件处理器规则绑定）、delete、workitem.list；参与人用组织对象。
+- **工具**：`workflow.get_draft`、`workflow.get_published`、`workflow.validate`、`workflow.create`、`workflow.update`、`workflow.publish`、`workflow.bindRule`、`workflow.delete`、`configure_workflow`、`workitem.list`、`org.role.list`、`org.department.list`、`org.user.search`
+- **recipe**：`omc describe workflow.bindRule --example workflow-handler-binding`
+- **边界 / 陷阱**：greenfield 首版；`publish`/`bindRule` 不得在 `ValidateMessage[]` 拒绝时报告成功。运行时 workitem（提交/审批）走 `data.submit`。
+
+## 表单在线 JS `onlinejs`
+
+- **能做哪些事**：表单在线 JS 的 compose 六元素骨架、`draftHtmlJson.customScript`、发布与 SHA-256 回读（脚本**编写**不在 CLI 范围，遵循项目在线 JS 规范或向用户索取定稿 source）。
+- **工具**：`onlinejs.compose`
+- **边界 / 陷阱**：仅表单在线 JS；后端在线开发（`/api/api/programming` Java 源码）用二开扩展包，不在 CLI 范围。
+
+## 业务集成 `bizservice`
+
+- **能做哪些事**：业务服务与方法注册（RESTFUL/DATA_SQL/DATA_TABLE/SAP/KAFKA/SOAP）、方法增改删、分类/连接池、导入导出、设计器测试。
+- **工具**：`service.get`、`method.get`、`method.update`、`method.create`、`method.delete`、`service.category.list`、`service.category.create`、`service.category.update`、`service.category.delete`、`service.dbconnpool.list`、`service.dbconnpool.create`、`service.dbconnpool.update`、`service.dbconnpool.delete`、`service.adapter_config`、`service.table_list`、`service.table_sql`、`service.register`、`service.update`、`service.delete`、`service.export`、`service.check`、`service.import`、`method.test`
+- **recipe**：`omc describe service.register --example restful-query-service`
+- **边界 / 陷阱**：方法 `configJson` 走 AES-128-ECB；**二开接口 = 扩展模块写 REST 接口 + RESTFUL 服务指向它**（页面/规则引用）；RESTFUL/DATA_SQL 绑定前须带适配器必需配置（否则是注册壳）。
+
+## 报表 `report`
+
+- **能做哪些事**：报表树/元数据读取、报表页建改删、BI dashboard 配置、图表增改删、图表数据查询、数据集读取/关联。
+- **工具**：`report.tree`、`report.get`、`report.chartdata`、`report.datasource.list`、`report.datasource.link`、`report.create`、`report.update`、`report.delete`、`report.configure`
+- **边界 / 陷阱**：
+  - **`report` 是"按需出现"的能力：只有用户显式要求报表 / 图表 / 看板 / dashboard 时才使用。常规开发流程不产出报表——不要在方案/存疑清单里对"统计/汇总/按月"之类的需求主动引入 `report`。**
+  - **跨对象统计聚合（如"按月按客户统计金额"）默认不落 `report`**：先看能否用字段/查询配置表达；表达不了就落二开聚合接口（扩展写接口 + RESTFUL），**不要默认引 BI/报表**。报表是另一条独立交付物，需用户点名。
+  - 报表页走 `/api/api/report/*`；BI 走 `/dashboard/v1/*`（无 errcode 信封，body 必带 `config:{token,reportCode,appCode}`，缺则静默 no-op）；外层 `corpId` 是真实查询键，默认 `"a"`。
+
+## 运行数据 `data`
+
+- **能做哪些事**：业务记录列出、加载、保存、更新、删除、提交（工作流）。
+- **工具**：`data.list`、`data.load`、`data.save`、`data.update`、`data.delete`、`data.submit`
+- **recipe**：
+  - `omc describe data.save --example workflow-backed-data-save`
+  - `omc describe data.submit --example workflow-backed-data-submit`
+- **边界 / 陷阱**：读实际业务记录是 OMC 独有能力。**计算字段（FORMULA/子表计算）不由 API 回填**——写测试数据带预算值，公式正确性人工前台确认；带子表计算字段的模型 API 写可能 50000（服务端重算 NPE），前台正常。
+
+---
+
+## 边界（boundaries）
+
+这些面**不在配置覆盖内**。被挡/不支持是**明确的答复**，不是要绕过的障碍——如实报告，不要用相近能力伪造。
+
+| 面 | 状态 | 说明 |
+| --- | --- | --- |
+| 权限 / 授权矩阵 | blocked | 授权矩阵不在配置面 |
+| 嵌套子表（子表套子表） | blocked | 一级子表可用，嵌套不可 |
+| OCR / 电子签章 / 发票识别 | unsupported | 不在平台配置覆盖内 |
+| 应用发布 / 环境上线 / 生产发布 | unsupported | CLI 只做配置，不做环境发布 |
+| 在线后端编码 / EXECUTE_CODE / ONLINE_DEVELOP | unsupported | 用二开扩展包，不用在线 JS 伪造 |
+
+> `blocked` / `unsupported` 是**原生配置**的判定，通常把行为路由到另一个代码所有者（`配置 + 后端扩展`），**不等于**需求不可交付。把 blocked face 编译成「做不了、留人工」是失败模式。
+
+## 相关 topic
+
+- 需求分析（定面/归类/选路）：`omc-requirement-analysis`；线索词表：`omc-requirement-vocabulary`
+- 用哪个工具最省：`omc-tool-selection`；写前人审门：`omc-config-draft-review`
+- 被拒/状态异常：`omc-refusals`；新面取证：`omc-capability-scouting`
+- 每能力的配置怎么配：`omc-business-configuration` 的对应节；写入风险：`omc-write-hazards`