@stalfh233/omc-cli 0.5.6 → 0.5.7

package/docs/omc-introduction.md

@@ -1,851 +1,851 @@
-# OMC CLI 介绍 —— CloudPivot 的受治理配置命令行
-
-> **面向**：想了解「omc 到底是什么、能替我把 CloudPivot 的哪些事情做掉」的人。
->
-> **版本基线**：`@stalfh233/omc-cli@0.4.100`（锚点 CloudPivot 8.6.26，兼容其它版本族）。
-
-## 目录
-
-**先看实战**
-
-1. [一句话](#1-一句话)
-2. [实战一：尼西双表单与流程搭建](#2-实战一尼西双表单与流程搭建)
-3. [实战二：用 OMC 排查并修复线上问题](#3-实战二用-omc-排查并修复线上问题)
-
-**再了解它**
-
-4. [它能做什么](#4-它能做什么)
-5. [怎么用](#5-怎么用)
-6. [设计取舍：为什么是 CLI](#6-设计取舍为什么是-cli)
-
-**备查**
-
-7. [治理与安全](#7-治理与安全每个写调用都过的管道)
-8. [不能做什么（边界）](#8-不能做什么边界)
-9. [安装（npm）](#9-安装npm)
-10. [上手速查](#10-上手速查)
-11. [术语速记](#11-术语速记)
-12. [附录：全部工具清单](#12-附录全部工具清单)
-
-## 1. 一句话
-
-**omc 是 CloudPivot 的配置执行器。**
-
-它把平台的低代码配置能力封装成一条本地 CLI。
-
-它覆盖：
-
-发现环境 · 建模型 · 配字段 · 排版表单 · 写业务规则 · 搭审批流 · 注册业务集成 · 灌运行数据。
-
-每次写入前做机器校验，写入后做权威读回。
-
-受治理（governed），失败即关闭（fail-closed）；边界由随包覆盖清单约束。
-
-**它首先是给 AI 用的。**
-
-相当于给 AI 装上「手脚」：不再只是聊天，而是能稳定地把低代码配置改对、改快。
-
-更进一步，是让 AI 把整条二开链路串起来：
-
-> 读现状 → 改配置 → 造数据 → 触发流程 → 读回验证
-
-人只在关键节点做判断和验收。
-
-**下面两个实战，是这套东西最真实的样子。** 先看它们，再看能力与设计取舍。
-
-> **当前状态**
->
-> 工程底子不糙——治理管道、写前校验、写后读回、写锁、幂等、回滚、基线评测都已经在跑。
->
-> 真正年轻的是**覆盖面和边界**：有些能力只覆盖了已经踩过坑、验过证的部分，遇到新场景还要继续补。
->
-> 它会跟着真实使用一轮轮长大：补能力、修形状、磨体验。先把它当成一个**还在长的手艺活**，而不是一版定型的成品。
-
-## 2. 实战一：尼西双表单与流程搭建
-
-> **一次真实交付的记录。**
->
-> 一个会话里，用 OMC 把「代工厂异常批次（SubCon Maverick Lot）」项目的
-> **两张表单 + 两条审批流 + 角色路由 + 节点字段权限 + 在线 JS** 全部配完。
->
-> 参考价值：从客户 Excel 到可用的审批应用，中间没有手工点过一次界面。
-
-### 背景
-
-客户给了两份材料。
-
-**一份 Excel**：`SubCon Maverick Lot流程表单`，两个 Sheet。
-
-- `FT`：成品 / 封装层
-- `FP`：晶圆层
-
-每行列了字段名、显示名、类型、是否必填、LotClass 显隐说明。
-
-**两张流程图**：FT / FP 各一张，结构相同。
-
-```text
-填写申请单 → AOS PE Review
-  →（SubConRootCause=Y）SQE approve
-  → SubCon ENG 执行
-  → AOS PE Confirm
-```
-
-目标：**新建一个应用**，内含两个模型、两个子表组、两条审批流。
-
-> **[截图 01｜客户源需求：FT 表单规格]**
-> 占位文件：`docs/images/omc-nixi/01-requirement-ft-sheet.png`
-> 建议内容：客户 Excel 的 `FT` Sheet（字段清单 + 必填列 + LotClass 显隐说明）
-
-> **[截图 02｜客户源需求：FP 表单规格]**
-> 占位文件：`docs/images/omc-nixi/02-requirement-fp-sheet.png`
-> 建议内容：客户 Excel 的 `FP` Sheet
-
-> **[截图 03｜客户源需求：流程图]**
-> 占位文件：`docs/images/omc-nixi/03-requirement-flow.png`
-> 建议内容：FT/FP 两张流程图（含 `SubConRootCause=1` 分支）
-
-### 步骤 1：环境自检 + 建应用
-
-```bash
-omc doctor                                          # 配置/登录/版本族/指纹/许可证
-omc call discover_environment --env nixi --args '{}'  # 确认环境、默认应用、门户分组
-omc call app.create --env nixi --args '{"code":"SubConMaverick","name":"代工厂异常批次","groupId":"<AOSPE 分组 id>"}'
-```
-
-要点：**应用创建不在 `intent` 声明式面内**。
-
-必须先 `app.create`，再把环境默认应用指向它；后续 `intent` 建模才会落到新应用。
-
-> **[截图 04｜对话：应用与环境确认]**
-> 占位文件：`docs/images/omc-nixi/04-chat-app-create.png`
-> 建议内容：与 Agent 确认「新建应用」并返回 `app.create ok` 的那段对话
-
-### 步骤 2：读需求，定型号
-
-把两个 Sheet 的每一行读成 `{code, name, type, required, 显隐}`，识别出：
-
-- FT：39 个字段 + 2 个子表（`Chip` 2 列、`SBLTriggerItem` 3 列）
-- FP：38 个字段 + 1 个子表（`Wafer` 9 列）
-- 类型映射：`字符串→SHORT_TEXT`、`长文本→LONG_TEXT`、`数字→NUMERICAL(+scale)`、`固定枚举→RADIO(choices)`、`附件→ATTACHMENT`、`子表→CHILD_TABLE(subFields)`
-
-这里唯一需要人拍板的是几处歧义：节点名 TE/PE、`programName` 类型、子表列数。
-
-其余照表落。
-
-### 步骤 3：一次声明式建模（intent）
-
-两个模型、77 个字段、3 个子表、2 张默认表单、2 个列表视图，全部写进**一个 `intent.yaml`**：
-
-```bash
-omc intent validate intent.yaml           # 离线校验（会卡 code 命名：必须 lowerCamel / lower_snake）
-omc intent plan intent.yaml --env nixi    # 编译成 plan（本例 89 个动作）
-omc intent apply plan.json                # 串行执行 + 默认读回等价确认
-```
-
-回执关键行：`equivalent: true`。
-
-意思是平台实际状态与 intent 声明**逐字段等价**，不是「大概建上了」。
-
-> **[截图 05｜对话：intent apply 回执]**
-> 占位文件：`docs/images/omc-nixi/05-chat-intent-apply.png`
-> 建议内容：`intent apply` 返回 `DELIVERED` + `equivalent: true`（89 个动作）的那段
-
-这一步的收益最直观：**两条命令代替了几百次界面点击**。
-
-而且重复跑是幂等的（零变更）。
-
-### 步骤 4：两条审批流 + 角色路由
-
-流程用 `workflow.create` 起骨架。
-
-再用 `workflow.update` 一次性补**节点 + 路由 + 参与人 + 节点字段权限**：
-
-```bash
-omc call workflow.create --env nixi --args '{"schemaCode":"scmFt","name":"SubCon Maverick Lot-FT 流程","code":"scmFtFlow"}'
-omc call workflow.update --env nixi --args-file wf_scmFt.json    # 整模板：START/END + 5 节点 + routes + propertyPermissions
-omc call workflow.publish --env nixi --args '{"schemaCode":"scmFt","code":"scmFtFlow"}'
-```
-
-拓扑（两条流程一致）：
-
-```text
-开始 → 填写申请单 → AOS PE Review ─[subConRootCause = Y]→ SQE approve ─┐
-                          └────────[else 兜底]────────────────────────→ ┴→ SubCon ENG 执行并反馈 → AOS PE Confirm → 结束
-```
-
-**角色路由**（本例的「配置角色」落在节点的参与人表达式上）：
-
-| 节点 | 办理人 |
-|---|---|
-| 填写申请单 | `{Originator}`（发起人） |
-| AOS PE Review | `IF({productType}=="PIC",[蔡依涛],[赵益])` —— 按产品线分流到不同 AOS 工程师 |
-| SQE approve | 部门 `AOSIT` |
-| SubCon ENG 执行并反馈 | 部门 `AOSENG` |
-| AOS PE Confirm | 部门 `AOSIT` |
-
-> **[截图 06｜对话：流程节点与角色配置]**
-> 占位文件：`docs/images/omc-nixi/06-chat-workflow-role.png`
-> 建议内容：确认「PIC→蔡依涛 / MOS→赵益、SQE/确认→AOSIT、执行→AOSENG」的对话
-
-### 步骤 5：节点字段权限 —— 累计可见
-
-客户的真实诉求是一句话：
-
-> **「每个节点都要能看到本节点以及之前所有节点的字段，不然审批怎么知道表里填了什么」**
-
-于是每个审批节点的可见集合 = 前面所有节点字段 ∪ 本节点字段。
-
-**只有本节点自己的字段可编辑**，之前的一律只读：
-
-| 节点 | 可见 | 可编辑 |
-|---|---|---|
-| 填写申请单 | 22 | 22 |
-| AOS PE Review | 25（22 + 本节点 3） | 3 |
-| SQE approve | 31（+ 本节点 6） | 6 |
-| SubCon ENG 执行 | 33（+ 本节点 2） | 2 |
-| AOS PE Confirm | 39（全部） | 6 |
-
-这一步最能体现 CLI 的价值。
-
-39 个字段 × 5 个节点的权限矩阵，人手工点要几百次勾选；这里是**一份 JSON 一次写回**。
-
-> **[截图 07｜对话：节点字段权限矩阵确认]**
-> 占位文件：`docs/images/omc-nixi/07-chat-permission-matrix.png`
-> 建议内容：审批节点「本节点 + 之前所有字段可见」的确认与回读矩阵
-
-### 步骤 6：规则类补配
-
-| 需求 | 落点 |
-|---|---|
-| 良率自动计算 `Yield = TestOutQty / TestInQty` | `datarule.create`（type2，门户前端计算） |
-| `LotClass=ENG` 时若干字段不显示 | 字段 `options.displayFormula` |
-| Action 与 SubConRootCause 二选一必填 | `options.requiredFormula` + 节点必填 |
-
-### 步骤 7：快速配置业务集成（一条命令 = 服务 + 方法 + 参数）
-
-这一步是「配置面里最容易低估」的。
-
-**平台业务集成不用点界面。**
-
-`service.register` 一条命令，就能把一个 SQL 服务连同它的方法、入参、出参一次注册好。
-
-本例注册了两个数据源方法（都是 `DATA_SQL` 适配器，直连客户 Oracle）：
-
-| 服务 code | 服务名 | 连接池 | 方法 | 入参 | 出参 |
-|---|---|---|---|---|---|
-| `productType` | 产品线(件号-PDM) | `PDM` | `GetProductTypeByPartName` | `PartName` | `PRODUCT_TYPE` |
-| `datahub` | datahub | `datahub` | `GetProductTypeByWaferName` | `WaferName` | `PRODUCT_TYPE` |
-
-注册顺序（先建分类，再一次注册）：
-
-```bash
-# 1. 建集成分类（返回 id，下一步要用）
-omc call service.category.create --env nixi --args '{"name":"产品线查询"}'
-# → readback.id = d0db6b83be474234b8ab66c63fb6cbb8
-
-# 2. 一条命令：服务 + 方法 + 入参 + 出参（DATA_SQL）
-omc call service.register --env nixi --args '{
-  "serviceCode": "productType",
-  "name": "产品线(件号-PDM)",
-  "adapterCode": "DATA_SQL",
-  "serviceCategoryId": "d0db6b83be474234b8ab66c63fb6cbb8",
-  "description": "根据件号查询产品线（MOS/PIC/NA）",
-  "serviceConfig": {
-    "auth": {"code": "", "name": "", "parameterlist": []},
-    "commonlist": [{"code": "databaseConnectionPoolCode", "name": "数据库连接池编码", "required": true, "value": "PDM"}]
-  },
-  "methodName": "GetProductTypeByPartName",
-  "methodConfig": {
-    "sql": "select itemname, case when product_line in (...) then ''MOS'' ... end product_type from (...) where itemname = :PartName",
-    "countSql": "select count(*) as count from (...) t where itemname = :PartName",
-    "returnType": "SingleObject",
-    "frontEndExtensionEnable": true
-  },
-  "methodInputParameters": [{"code":"PartName","name":"PartName","required":true,"externParameterType":1000,"bizPropertyType":0}],
-  "methodOutputParameters": [{"name":"PRODUCT_TYPE","code":"PRODUCT_TYPE","externParameterType":1000,"required":false,"bizPropertyType":0}]
-}'
-```
-
-> **`frontEndExtensionEnable: true` 是整件事的关键开关** —— 只有打开它，表单在线 JS 才能通过
-> `/api/runtime/bizbus/invoke` 直接调这个方法。忘了它，SQL 再对，前端也调不到。
-
-**立刻验证（会真连客户库）**
-
-```bash
-omc call method.test --env nixi --args '{"serviceCode":"productType","methodCode":"GetProductTypeByPartName","inputParameters":{"PartName":"AO3406L"}}'
-# → {"success":true,"data":{"ITEMNAME":"AO3406L","PRODUCT_TYPE":"MOS"}}
-```
-
-`method.test` 的 `externalSideEffect` 会是 `real`（真打外部数据源），所以**只读查询可以直接测，写库型方法要谨慎**。
-
-后续改 SQL 用 `method.update`：只动方法，不重建服务。
-
-重跑 `method.test` 和 `service.get` 复核；读回是脱敏的，凭据不会进日志。
-
-> 本例最终 `service.get` 读回：`adapterCode: DATA_SQL`、`configJson.commonlist[0].value: PDM`、
-> `frontEndExtensionEnable: true`、`methods[0].configJson.returnType: SingleObject`。
-
-> **[截图 08｜对话：业务集成快速注册]**
-> 占位文件：`docs/images/omc-nixi/08-chat-biz-integration.png`
-> 建议内容：`service.register` 注册 productType 服务 + `method.test` 返回 `PRODUCT_TYPE=MOS` 的那段
-
-### 步骤 8：在线 JS（产品线自动带出）
-
-客户另给了 SQL（`FT_Get_ProductTypeByAOSPartName`）。
-
-需求是：在 FT 表单填「AOS产品名」后，自动带出**产品线**和**封装类型**。
-
-关键结论：表单 JS 不用自定义接口，走平台内置的**业务集成调用端点**：
-
-```js
-h3form.axios.post(config.apiHost + '/api/runtime/bizbus/invoke', {
-    serviceCode: 'productType',
-    methodCode: 'GetProductTypeByPartName',
-    args: { PartName: value }
-})
-```
-
-发布也走 CLI，不必进设计器粘贴：
-
-```bash
-omc call onlinejs.compose --env nixi --args-file compose_scmFt.json   # replace:true + publish:true
-```
-
-> **[截图 09｜对话：在线 JS 发布]**
-> 占位文件：`docs/images/omc-nixi/09-chat-onlinejs-publish.png`
-> 建议内容：`onlinejs.compose` 返回 `DELIVERED` / `published: true` 的那段
-
-### 交付物
-
-```text
-intent.yaml                     # 两个模型 + 字段 + 子表 + 表单 + 视图（可重放）
-wf_scmFt.json / wf_scmFp.json   # 两条流程整模板（节点 + 路由 + 权限）
-service-productType.json        # service.register 参数（服务 + 方法 + 入出参）
-compose_scmFt.json              # 在线 JS 发布参数
-SQL-已参数化.sql                # 业务集成 SQL（:PartName 绑定变量）
-README.md                       # 内网手工配置步骤
-```
-
-一次会话的产出，换来的是一整套**可重放、可 diff、可回滚**的配置源文件。
-
-而不是一堆「当时点对了但没留下痕迹」的界面操作。
-
----
-
-## 3. 实战二：用 OMC 排查并修复线上问题
-
-> **中冶的两个线上问题。**
->
-> 不点菜单、不连库，靠 OMC 只读面逐步收敛到「配置的哪一行」，再用写面（五件套）改掉。
->
-> 日志只做一件事：提供**运行时刻**的证据。
-
-### 排障主链路：四步全在 OMC 里
-
-下面表格里的调用都省略了 `omc call` 前缀，只写工具名和参数。
-
-```text
-① 定模型   model.list（按应用过滤）→ model.inspect
-② 定口径   field.list（中文名 → code，别猜字段名）
-③ 定写入者 datarule.list（1=校验 2=计算/拼接）/ onlinejs.get / rule.get + artifact / form.get
-④ 定数据   data.load / data.list → 与日志报文对照：「本来没有」还是「被覆盖」
-```
-
-第 ③ 步是成败点。
-
-**一个字段有四种写入来源**：
-
-- 在线 JS
-- 字段级数据规则
-- 业务规则节点
-- 关联表单带出映射
-
-只查一种就下结论，必翻车。日志在这四步之外补位，用法只有两条：
-
-```bash
-cd <backend>/launcher/logs/total
-grep -o 'expression=[^ ]*' <(sed -n '4540,4700p' log-total-<日期>.12.log) | sort | uniq -c  # 当时跑了哪些规则
-grep -ho '"<字段>":"[^"]*"' *<日期>*.log | sort | uniq -c                                        # 该字段历史上出现过什么值
-```
-
-### 案例 A：合同编号每次新增被冲空
-
-| 步 | OMC 调用 | 拿到什么 |
-|---|---|---|
-| ① | `model.list --args '{"applicationCode":"HTGL","filter":"合同"}'` | 定位到 `pr_contract_registration`（登记）、`contract_master_data1`（主数据） |
-| ② | `field.list --args '{"schemaCode":"pr_contract_registration","code":"contract_number"}'` | 「合同编号」= `contract_number`；顺带发现「合同编码」是另一个字段 `contract_code` |
-| ③ | `datarule.list --args '{"schemaCode":"pr_contract_registration","dataRuleType":2}'` | **命中根因**：`contract_number` 有一条短文本拼接规则 `CASE({constep}="合同变更/补充",{changeContractCode},{constep}="主合同",{mainCode})` |
-| ③ | `form.get --args '{"schemaCode":"pr_contract_registration","controls":["ref_contract_review"]}'` | 关联评审单的带出映射：`contractNumber → mainCode`、`contractNumber3 → changeContractCode` |
-| ④ | `data.load` 登记单 + 主数据 | 登记单 `contract_number=""`、`mainCode=""`；主数据 `businessCode=""` —— 上游就是空 |
-
-日志佐证两点：
-
-- 01:24:32 出现 `expression=CASE({constep}=…{mainCode})`，说明保存时规则确实重算并回写了空值——这就是「必现」的机制。
-- `grep '"mainCode":"'` 全时间窗零条非空，说明输入变量从未有值。
-
-**结论**：不是谁删了编号，是编号压根没产生。
-
-拼接规则的两个输入来自评审单的「经营合同编号 / 变更编号」。
-
-这两列为空 → 带出即空 → 拼接再覆盖空 → 主数据与 NC 的 `vbillcode` 一路空。
-
-反证：成本类走 `pc_contract_registration`，同期 `cbht01`、`CIEHTGU-01` 正常出号。
-
-**OMC 修法（二选一，按业务口径定）**
-
-- A｜补上游（推荐）：评审单侧让编号真正生成/回填，登记单的拼接规则原样保留 —— 不写配置，改流程/编号规则。
-- B｜改规则：`datarule.update` 给 CASE 加 `ELSE` 兜底（如取 `contract_code`），保证不落空；
-  代价是「合同编号」与「合同编码」被混同，需业务确认。
-
-### 案例 B：收款计划变更子表为空
-
-| 步 | OMC 调用 | 拿到什么 |
-|---|---|---|
-| ① | `model.inspect --args '{"schemaCode":"contract_master_data1"}'` | 找到 `Update` 规则（14 节点），其中 `DataCreate10` 发起 `collection_plan_adjust` |
-| ③ | `rule.get --args '{"schemaCode":"contract_master_data1","ruleCode":"Update","full":true}'` + `artifact get <id> --jq "nodes"` | **命中根因**：`DataCreate10` 19 条主表映射，`children=""` —— 子表映射根本没配 |
-| ③ | `form.get --args '{"schemaCode":"collection_plan_adjust","sheetCode":"performance_payment","controls":true}'` | 子表控件 `performance_paymentrs` 的 `dataItemName=contract_payment_item` |
-| ④ | `data.list --args '{"schemaCode":"contract_payment_item"}'` / `--args '{"schemaCode":"performance_payment"}'` | 前者 **0 条**，后者 12 条且 `parentId` 指向的主记录**都已不存在**（孤儿行） |
-
-**结论**：两层问题叠在一起。
-
-1. 规则节点没配子表映射，新单子表天然为空。
-2. 控件绑定的子模型（`contract_payment_item`）与历史数据所在的子模型（`performance_payment`）已经错位，老数据成孤儿。
-
-**OMC 修法**
-
-1. `rule.node.update` 给 `DataCreate10` 补 children：合同主数据 `con1collectionSchedule_jndv` →
-   `performance_paymentrs`，并补 `contractTotalAmount` 映射。
-2. 统一子表模型口径（控件 `dataItemName` 与规则写入目标一致），迁移或清理 12 条孤儿行。
-
-### 用 OMC 写：五件套
-
-```text
-discover → draft（人工确认）→ 权限门（writable / production 需 confirmProduction:true）
-        → execute（一次写调用）→ readback（证明状态）
-```
-
-排障阶段全是读面，改的时候按这个顺序：
-
-```bash
-omc call discover_environment --args '{}'                       # 拿环境指纹，写前必须重取
-omc call datarule.update --args '{…,"dryRun":true}'             # 先看计划，不落盘
-omc call datarule.update --args '{…,"confirmProduction":true}'  # 生产必带该字段
-omc call datarule.list  --args '{"schemaCode":"…","dataRuleType":2}'   # 读回：确认不是只改了草稿
-```
-
-纪律：
-
-- **一个变更包只用一个引擎**（OMC 或 cp-model），读、Dry Run、写、回读都归它。
-- 写前把设计用大白话讲清并拿到明确同意；草稿未批准可随意改，批准后指纹变了就作废重来。
-- 改完固定三条回读：
-    1. **规则读回**：`rule.get` / `datarule.list` 确认已发布态。
-    2. **数据读回**：造一条新单 `data.load`，看落值 / 子表行数。
-    3. **日志读回**：grep 该单 id + TID，确认计算输出符合预期。
-
-### 一页速查
-
-```text
-字段为空 / 被清空
-  ├─ datarule.list --dataRuleType 2   → 是不是计算/拼接字段（会被重算覆盖）
-  ├─ onlinejs.get                     → 前端有没有在写
-  ├─ form.get --controls              → 关联表单 mappings，源字段是否本来就空
-  └─ data.load 对照日志 bizObject 报文 → 「本来没有」还是「被覆盖」
-
-下游单据 / 子表没数据
-  ├─ rule.get + artifact --jq nodes   → CREATE 节点 children 是否为空
-  ├─ 控件 dataItemName 指向哪个子模型 → data.list 该子模型总条数
-  └─ 孤儿行：子表 parentId 在主模型 data.load 是否存在
-```
-
----
-
-## 4. 它能做什么
-
-想确认某个能力能不能做，先跑两条：
-
-```bash
-omc capabilities                     # 一张表看清 16 项能力
-omc capability <id> --executable     # 单个能力的完整执行包
-```
-
-覆盖的环节：
-
-- 环境、应用、模型、字段
-- 表单、视图、业务规则
-- 审批流、业务集成
-- 运行数据、报表
-
-| 能力 | 能做的事（需求线索） | 工具数 | 覆盖 | 声明式(intent) | 依赖 |
-|---|---|---|---|---|---|
-| `environment` 环境治理 | 环境发现、指纹、版本、连接/登录/就绪 | 2 | executable | none | - |
-| `app` 应用 | 应用包建/改/删、列出 | 4 | executable | none | - → folder |
-| `folder` 应用目录（分组） | 应用树目录/分组、移动模型、**自定义页面** | 12 | executable | none | app → - |
-| `dictionary` 数据字典 | 字典与字典记录、键值/树型、选项来源 | 12 | executable | none | - |
-| `model` 业务模型 | 建/改名/移动/删除模型、摘要、一次建模型+字段+表单 | 9 | executable | partial | - → field, workflow |
-| `field` 字段 | 字段族、**子表**、下拉/人员/部门/日期/数值/关联、**计算字段**、单据号 | 5 | executable | partial | model → form, listview, datarule, businessrule, data |
-| `form` 默认表单 | 表单布局、发布、按钮（含按钮 JS） | 5 | executable | partial | field → onlinejs |
-| `listview` 列表视图 | 表头列、排序、筛选、按钮（含按钮 JS） | 5 | partial | partial | field → - |
-| `datarule` 字段级规则 | 条件必填/只读/显示、计算拼接 | 4 | partial | partial | field → - |
-| `businessrule` 业务规则 | 图形规则图、事件触发、BRANCH、BIZ_ACTION、**定时任务**、跨规则引用检索 | 5 | executable | partial | field → rule-lifecycle |
-| `rule-lifecycle` 规则生命周期 | 启用/停用/删除/手动执行 | 6 | executable | none | businessrule → - |
-| `workflow` 流程模板 | 审批流模板、节点/路由、发布、事件规则绑定、发起权限、待办、组织（角色/部门/用户） | 38 | executable | partial | model → - |
-| `onlinejs` 表单在线 JS | 表单在线脚本 compose / 读回（含 SHA-256） | 2 | executable | partial | form → - |
-| `bizservice` 业务集成 | 服务与方法注册（RESTFUL/DATA_SQL/…）、分类、连接池、导入导出、设计器测试 | 24 | executable | partial | - |
-| `report` 报表 | 报表页、BI 图表、数据集（**仅用户显式要求时**） | 9 | partial | partial | - |
-| `data` 运行数据 | 业务记录读/写/更新/删除/提交（工作流） | 6 | executable | none | field → - |
-
-> **覆盖**：`executable` 全量可用；`partial` 有已取证边界（见 `omc capability <id>` 的 notes）。
-> **声明式(intent)**：`partial` = 该能力可用 YAML 声明一部分（通常 create/update）；`none` = 只走 `omc call`。
-> **依赖** = `requires → precedes`，即能力之间的配置顺序；例如字段依赖模型，表单依赖字段。
-> **组织**：`workflow` 的 38 个工具里包含 `org.*`（角色/部门/用户）——组织是流程的一部分，不单独成能力。
-
-工具面合计 **154 个**：元/治理 5 + 读 55 + 写 94。
-
-## 5. 怎么用
-
-### 5.1 `omc call` —— 一次一工具（原子面）
-
-```bash
-omc call discover_environment --env test --args '{}'
-omc call model.create --env test --args '{"name":"客户","code":"x_customer"}'
-omc describe field.create --example dictionary-backed-single-select   # 拿可运行示例
-```
-
-读面可一步取值：`--jq` / `--extract <path>` / `--extract-keys`。
-
-这样能省掉再跑一次 `artifact get`。
-
-### 5.2 `omc intent` —— 声明式意图面（推荐默认）
-
-用一份 YAML 描述一组变更，编译成**不可变 plan** 再执行：
-
-```bash
-omc intent validate intent.yaml          # 离线语义校验（错误带 源行:列）
-omc intent plan intent.yaml --env test   # 读基线 → 编译 → plan（planHash 复核对象）
-omc intent apply plan.json               # drift 门 + writable 检查 + 串行执行 + 默认读回等价确认
-omc intent readback intent.yaml --env test   # 解码回 intent 形状做等价校验
-```
-
-- 顶层 `models[]` / `services[]`；`models[].{code,name,fields,datarules,rules,form,listview,workflow,onlinejs}`。
-- `intent apply` 既可以吃 `plan` 文件，也可以直接吃 YAML（`omc intent apply intent.yaml --env <env>`，自动编译）；大 plan 会自动外置，回 `planFile`。
-- **幂等收敛**：已达标环境重跑 plan/apply → 零变更、零重复创建。
-- 显式缺席（删除）：`models[].absent:true` 删整模型、`fields[].absent:true` 删单字段；plan 的 `riskClass` 升为 `destructive`。
-- 生产 apply 加 `--confirm-production`；`--dry-run` 预览，`--no-verify` 跳过最终读回。
-
-### 5.3 复合命令 —— 一条命令 = 一个变更包
-
-| 命令 | 作用 |
-|---|---|
-| `omc model-scaffold` | 一条命令建模型 → N 字段（含子表）→ 发布字段 → 发布表单；先对每个字段 dry-run 预检 |
-| `omc model-purge` | 按依赖倒序清掉一个模型（流程实例 → `model.delete` 级联） |
-| `omc submit-verify` | 逐条提交 → 真实 id 读回 → 差异汇总 |
-| `omc rule-save-enable` | 保存成功才启用，回执回答「会不会真的运行」 |
-| `omc workflow-update-publish` | 显式合成最终模板（默认保留旧节点，`--confirm-replace` 才丢弃） |
-| `omc call apply_changes` | 批量提交异构变更清单 `changes:[{tool,args}]`，首败即停、逐步读回、整批时间预算 |
-| `omc script` | NDJSON 多调脚本，一个进程一次会话跑完全部 |
-| `omc rollback` | 配置回滚（list / plan / apply），git-revert 语义；journal 与 before 快照是本机边界（不跨机器），publish 类生命周期推进不可逆 |
-
-另有若干「不写环境」的辅助命令：`compute`（聚合公式编译）、`rule-when`、`approval-flow`、`form-default`、
-`bench`（跑分）、`usage`（用量账本）、`next`（目标 → 工具一步定位）。
-
-### 5.4 一条完整链路
-
-```bash
-# 0. 配置与自检
-omc setup && omc doctor && omc call discover_environment --env test --args '{}'
-
-# 1. 建模型 + 字段 + 表单（默认 dry-run 只列计划；加 --apply 才执行）
-omc model-scaffold --code x_customer --name 客户 \
-  --fields '[{"name":"名称","code":"name","propertyType":"SHORT_TEXT"},{"name":"等级","code":"level","propertyType":"DROPDOWN_BOX","choices":["A","B"]}]' \
-  --env test --apply
-
-# 2. 配业务规则（--node-graph 传规则图 JSON；保存成功才启用；默认 dry-run）
-omc rule-save-enable --schema x_customer --rule-code customer-oncreate --name 创建客户后处理 \
-  --node-graph "$(cat rule-graph.json)" --env test --apply
-
-# 3. 更新并发布审批流（--template 传流程模板 JSON；默认 dry-run 合成预览）
-omc workflow-update-publish --schema x_customer --code customer_flow \
-  --template "$(cat workflow.json)" --env test --apply
-
-# 4. 灌一条正式数据（无流程模型）
-omc call data.submit --env test --args '{"schemaCode":"x_customer","formData":{"name":"甲","level":"A"}}'
-
-# 5. 验收：读回、核对交付态、清理测试数据
-omc call model.inspect --env test --args '{"schemaCode":"x_customer"}'
-omc rollback list
-```
-
-## 6. 设计取舍：为什么是 CLI
-
-### 6.1 初衷与一次转向
-
-这套 CLI 的初衷很简单：**让二开更简单、更方便**。
-
-让 AI 把散落在平台各处的配置、数据、触发和核对，串成一条链。
-
-它最早不是这个形态。
-
-最初想做的是**基于 dsh 的云枢专用 agent**：一套二开插件，把前后端改造、表单配置、环境配置、二开代码配置都收进去。
-
-名字 **Oh My CpAgent / omc**，则受 **Oh My OpenAgent** 和 **Oh My Pi** 启发。
-
-**放弃的原因有两个。**
-
-- **分发性**。插件绑平台——所有人得先下客户端、再装插件。就像 AI 大赛上基于 dsh 发布的 **Authine X**，能力不错，但使用门槛是「先装一套东西」。我们要的是谁都能用。
-- **版本成本**。dsh 迭代太快，接口几个月换一轮，插件跟着追版本是长期负债。
-
-最后选了 **npm CLI**：装在本机，agent 有 shell 就能调用。
-
-换模型、换客户端、换平台都不受影响。
-
-将来要 MCP 或平台插件，可以在同一条治理管线上再包一层。
-
-### 6.2 三条路都比过
-
-**MCP：schema 常驻太贵。**
-
-81 个工具的 schema 实测 208,985 B（约 53k tokens）。
-
-同一条发现流程：MCP 约 214.5 KB，CLI 约 6 KB——约 35 倍、接近 97% 的缩减。
-
-工具越多越明显。MCP 面已按 ADR-0004 移除。
-
-**Skill：适合讲方法，不适合承担强制治理。**
-
-cpdocs 用 Skill 承载编码知识，做得很好。
-
-但「真正去改环境」如果只靠文档里的纪律，就依赖模型自觉。
-
-CLI 把 writable、生产确认、写锁、幂等、读回做进**进程边界**。
-
-结论是：**方法论放 Skill，执行放 CLI。**
-
-**平台插件：可分发性最差。**
-
-见上面 dsh 那段。
-
-### 6.3 Token 治理：渐进式披露
-
-**发现面分档，按需放大。**
-
-- `next`：2–5 KB
-- `commands --json --compact --lane`：约 1 KB
-- `describe`：1.5–2.5 KB
-- `commands --json`：约 20 KB（回退面）
-
-先走小档，缺形状再放大。
-
-**默认只回索引 / 摘要 / 形状。**
-
-- `help` 回节索引（约 1 KB）
-- `artifact get` 正文 > 8 KB 只回形状
-- `usage` 只回汇总
-
-**一步取值，不重复搬。**
-
-- `--jq` / `--extract`
-- `model.inspect` 替代六连调
-- `script` / `--args-list` 一进程多调
-
-**有基线守着。**
-
-`eval:call-face` / `eval:intent-face` / `eval:discovery-cost` 都会跑固定任务；能力投影路线的发现调用约减半（20 → 10）。
-
-### 6.4 方法论随包走
-
-`omc help` 带 13 个 topic，默认只回节索引。
-
-常用的有：
-
-- `start-here` · `tool-selection` · `requirement-analysis`
-- `capabilities` · `config-draft-review` · `five-piece-flow`
-- `write-hazards` · `acceptance-criteria` · `refusals`
-- `glossary` · `business-configuration`
-
-写操作固定五段式：
-
-> 发现现状 → 出草稿 → 过写入门 → 执行 → 读回/清理
-
-### 6.5 和 cpdocs 的分工
-
-**OMC 是操作低代码配置的「手脚」，cpdocs 是帮 AI 做编码开发的「知识库」。**
-
-- cpdocs 负责：需求理解、方案与编码（Java 后端、Vue 前端、规范）。
-- OMC 负责：把方案落到平台配置，并做读回、造数、验收。
-
-两者重叠的模型 / 字段 / 表单 / 视图 / 规则 / 流程上，`cpdocs-guide` 会给出两个候选：`cp-model` 与 `omc`。
-
----
-
-## 7. 治理与安全（每个写调用都过的管道）
-
-```
-语义门（字段族 / 规则图 dry-lint / 业务编码 / 表单布局 / 各工具 preflight，零 wire）
-  → 覆盖门（清单声明；超界拒绝并引用条目）
-  → 环境写入门（writable=false 拒绝；生产需 confirmProduction:true）
-  → 会话 + 版本族门（缺版本证据即关闭）
-  → dry-run / requestId 重放门
-  → 写租约（同环境跨进程文件锁串行；冲突回 write-lock-held）
-  → 执行 → 权威读回 → artifact 交付 + 人话 summary
-```
-
-- **stdout 恒为恰好一个 JSON envelope** `{ok,status,result,requestId,error{code,message,retryable}}`；人类诊断全在 stderr。
-- **退出码族**：`0` ok · `10` invalid-input · `11` auth-config · `12` policy-refused · `14` uncertain · `15` internal；细分以 `error.code` 为准。
-- **不确定性语义**：传输失败冻结为 `status:"uncertain", frozen:true`，绝不伪造成功。
-- **人门在对话层**：机器管道只执行 writable 与 `confirmProduction` 检查；Agent 必须先出草稿并取得用户明确批准（`omc help omc-config-draft-review`）。
-
-## 8. 不能做什么（边界）
-
-这些是**明确答复**，不是要绕过的障碍：
-
-| 面 | 状态 | 说明 |
-|---|---|---|
-| 通用权限 / 授权矩阵 | blocked | 授权矩阵不在配置面（流程发起权限、组织/角色写入另有工具） |
-| 跨模型子表 / 关联联动 / 子到子 | blocked | 未取证，不猜写 |
-| OCR / 电子签章 / 发票识别 | unsupported | 不在平台配置覆盖内 |
-| 应用发布 / 环境上线 / 生产发布 | unsupported | CLI 只做配置，不做环境发布 |
-| 在线后端编码（`/api/api/programming` Java 源码） | unsupported | 用二开扩展包，本 CLI 无工具 |
-| 列表视图分组（queryLayer） | 未取证 | 别猜写 |
-
-**两条补充：**
-
-- **子表天生只有一级。** 一个主表可以有多个子表，但子表不能再套子表。所以「嵌套子表」不是 CLI 的能力缺口，而是平台不存在的形态，别按这个方向设计需求。
-- **被挡不等于做不了。** `blocked / unsupported` 通常意味着行为要路由到另一个代码所有者（配置 + 后端扩展）。
-
-## 9. 安装（npm）
-
-包名：**`@stalfh233/omc-cli`**（命令仍是 `omc`）。
-
-已发布到公共 npm registry：
-<https://www.npmjs.com/package/@stalfh233/omc-cli>
-
-环境要求：Node.js 22.13+（`omc-core` 使用内置 `node:sqlite`）。
-
-```bash
-# 全局安装（推荐）
-npm install -g @stalfh233/omc-cli@latest
-
-# 验证
-omc --version        # 当前基线 0.4.100
-omc setup && omc doctor
-
-# 查看 npm 上的最新版本
-npm view @stalfh233/omc-cli version
-
-# 固定 / 升级版本
-npm install -g @stalfh233/omc-cli@0.4.100
-npm update -g @stalfh233/omc-cli
-```
-
-也可以只在当前项目里安装、用 `npx` 调用：
-
-```bash
-npm install @stalfh233/omc-cli
-npx omc setup && npx omc doctor
-```
-
-> `omc-core` 是内部依赖，会随 `@stalfh233/omc-cli` 自动安装，不需要单独装。
->
-> 现在还在 `0.4.x` 的阶段，能力覆盖和部分形状还会继续扩、继续调——我们会跟着实际使用不断打磨、修问题。
->
-> `1.0.0` 之前，别把它当成冻结的契约。
-
-## 10. 上手速查
-
-```bash
-omc setup && omc doctor && omc commands --json
-
-omc help                    # 命令清单 + 方法论 topic 清单
-omc help --search "<词>"     # 跨 topic 找具体事实
-omc next "我想做一个审批流程"       # 目标 → 工具一步定位
-omc capabilities            # 16 能力一张表
-omc capability model --executable  # 单能力完整执行包
-omc describe <tool>         # 单工具 schema + 可运行示例
-```
-
-**在什么目录运行？**
-
-把 omc 当工具用时，请在**独立、干净的项目目录**里运行，不要放在 OMC 研发仓里。
-
-否则 Agent 可能读到只属于研发的产物（`.scratch/`、`CONTEXT.md` 等），误当成使用指引。
-
-## 11. 术语速记
-
-- **覆盖清单（coverage manifest）**：随包的能力契约，`executable / partial / blocked / static-only / unsupported` 五态。
-- **交付态（delivery state）**：写入后权威读回得到的真实状态，是「配好了」的唯一判据。
-- **artifact**：大读回外置的、带 sha256 的 0600 文件。
-- **plan / planHash**：intent 编译出的不可变复核对象。
-- **写租约（write lease）**：同环境写入的跨进程互斥。
-- **最小路径（minimal path）**：某类需求实际需要的最短发现→草稿→写→读回路线，是用量分析的对照基线。
-
-## 12. 附录：全部工具清单
-
-> 以 `omc commands --json` 为准；下面是按能力分组的当前快照（154 个）。
-
-**元 / 治理（6）**
-
-`coverage.manifest` · `get_status` · `setup.start` · `setup.commit` · `doctor` · `apply_changes`
-
-**environment 环境治理（2）**
-
-`discover_environment` · `environment.fingerprint`
-
-**app 应用（4）**
-
-`app.list` · `app.create` · `app.update` · `app.delete`
-
-**folder 应用目录 / 自定义页面（12）**
-
-`folder.tree` · `folder.create` · `folder.update` · `folder.delete` · `custompage.list` · `custompage.get` · `custompage.create` · `custompage.update` · `custompage.content.get` · `custompage.content.update` · `custompage.content.publish` · `custompage.delete`
-
-**dictionary 数据字典（12）**
-
-`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`
-
-**model 业务模型（9）**
-
-`model.list` · `model.inspect` · `model.create` · `model.delete` · `model.deleteMany` · `model.setSummary` · `model.update` · `model.move` · `configure_model`
-
-**field 字段（5）**
-
-`field.list` · `field.create` · `field.update` · `field.publish` · `field.delete`
-
-**form 默认表单（5）**
-
-`form.get` · `form.draft` · `form.publish` · `configure_form` · `form.runButton`
-
-**listview 列表视图（5）**
-
-`listview.get` · `listview.list` · `listview.create` · `listview.configure` · `listview.delete`
-
-**datarule 字段级规则（4）**
-
-`datarule.list` · `datarule.create` · `datarule.update` · `datarule.delete`
-
-**businessrule 业务规则（5）**
-
-`rule.list` · `rule.references` · `rule.get` · `rule.save` · `rule.node.update`
-
-**rule-lifecycle 规则生命周期（6）**
-
-`rule.enable` · `rule.disable` · `rule.delete` · `rule.run` · `rule.disableMany` · `configure_rule`
-
-**workflow 流程模板（38）**
-
-`workflow.get_draft` · `workflow.get_published` · `workflow.validate` · `workflow.create` · `workflow.update` · `workflow.publish` · `workflow.bindRule` · `workflow.setButtons` · `workflow.delete` · `configure_workflow` · `workitem.list` · `workflow.instanceActivity` · `workflow.permissions` · `workflow.addPermission` · `workflow.removePermission` · `org.role.list` · `org.department.list` · `org.user.search` · `org.role.users` · `org.role.userScope` · `org.roleGroup.create` · `org.role.create` · `org.department.create` · `org.department.update` · `org.department.delete` · `org.department.users` · `org.user.create` · `org.user.update` · `org.user.delete` · `org.user.info` · `org.user.departments` · `org.role.delete` · `org.roleGroup.delete` · `org.user.transferDepartment` · `org.role.update` · `org.role.addUsers` · `org.role.removeUsers` · `org.role.setUserScope`
-
-**onlinejs 表单在线 JS（2）**
-
-`onlinejs.get` · `onlinejs.compose`
-
-**bizservice 业务集成（24）**
-
-`service.get` · `service.list` · `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`
-
-**report 报表（9）**
-
-`report.tree` · `report.get` · `report.chartdata` · `report.datasource.list` · `report.datasource.link` · `report.create` · `report.update` · `report.delete` · `report.configure`
-
-**data 运行数据（6）**
-
-`data.list` · `data.load` · `data.save` · `data.update` · `data.delete` · `data.submit`
+# OMC CLI 介绍 —— CloudPivot 的受治理配置命令行
+
+> **面向**：想了解「omc 到底是什么、能替我把 CloudPivot 的哪些事情做掉」的人。
+>
+> **版本基线**：`@stalfh233/omc-cli@0.4.100`（锚点 CloudPivot 8.6.26，兼容其它版本族）。
+
+## 目录
+
+**先看实战**
+
+1. [一句话](#1-一句话)
+2. [实战一：尼西双表单与流程搭建](#2-实战一尼西双表单与流程搭建)
+3. [实战二：用 OMC 排查并修复线上问题](#3-实战二用-omc-排查并修复线上问题)
+
+**再了解它**
+
+4. [它能做什么](#4-它能做什么)
+5. [怎么用](#5-怎么用)
+6. [设计取舍：为什么是 CLI](#6-设计取舍为什么是-cli)
+
+**备查**
+
+7. [治理与安全](#7-治理与安全每个写调用都过的管道)
+8. [不能做什么（边界）](#8-不能做什么边界)
+9. [安装（npm）](#9-安装npm)
+10. [上手速查](#10-上手速查)
+11. [术语速记](#11-术语速记)
+12. [附录：全部工具清单](#12-附录全部工具清单)
+
+## 1. 一句话
+
+**omc 是 CloudPivot 的配置执行器。**
+
+它把平台的低代码配置能力封装成一条本地 CLI。
+
+它覆盖：
+
+发现环境 · 建模型 · 配字段 · 排版表单 · 写业务规则 · 搭审批流 · 注册业务集成 · 灌运行数据。
+
+每次写入前做机器校验，写入后做权威读回。
+
+受治理（governed），失败即关闭（fail-closed）；边界由随包覆盖清单约束。
+
+**它首先是给 AI 用的。**
+
+相当于给 AI 装上「手脚」：不再只是聊天，而是能稳定地把低代码配置改对、改快。
+
+更进一步，是让 AI 把整条二开链路串起来：
+
+> 读现状 → 改配置 → 造数据 → 触发流程 → 读回验证
+
+人只在关键节点做判断和验收。
+
+**下面两个实战，是这套东西最真实的样子。** 先看它们，再看能力与设计取舍。
+
+> **当前状态**
+>
+> 工程底子不糙——治理管道、写前校验、写后读回、写锁、幂等、回滚、基线评测都已经在跑。
+>
+> 真正年轻的是**覆盖面和边界**：有些能力只覆盖了已经踩过坑、验过证的部分，遇到新场景还要继续补。
+>
+> 它会跟着真实使用一轮轮长大：补能力、修形状、磨体验。先把它当成一个**还在长的手艺活**，而不是一版定型的成品。
+
+## 2. 实战一：尼西双表单与流程搭建
+
+> **一次真实交付的记录。**
+>
+> 一个会话里，用 OMC 把「代工厂异常批次（SubCon Maverick Lot）」项目的
+> **两张表单 + 两条审批流 + 角色路由 + 节点字段权限 + 在线 JS** 全部配完。
+>
+> 参考价值：从客户 Excel 到可用的审批应用，中间没有手工点过一次界面。
+
+### 背景
+
+客户给了两份材料。
+
+**一份 Excel**：`SubCon Maverick Lot流程表单`，两个 Sheet。
+
+- `FT`：成品 / 封装层
+- `FP`：晶圆层
+
+每行列了字段名、显示名、类型、是否必填、LotClass 显隐说明。
+
+**两张流程图**：FT / FP 各一张，结构相同。
+
+```text
+填写申请单 → AOS PE Review
+  →（SubConRootCause=Y）SQE approve
+  → SubCon ENG 执行
+  → AOS PE Confirm
+```
+
+目标：**新建一个应用**，内含两个模型、两个子表组、两条审批流。
+
+> **[截图 01｜客户源需求：FT 表单规格]**
+> 占位文件：`docs/images/omc-nixi/01-requirement-ft-sheet.png`
+> 建议内容：客户 Excel 的 `FT` Sheet（字段清单 + 必填列 + LotClass 显隐说明）
+
+> **[截图 02｜客户源需求：FP 表单规格]**
+> 占位文件：`docs/images/omc-nixi/02-requirement-fp-sheet.png`
+> 建议内容：客户 Excel 的 `FP` Sheet
+
+> **[截图 03｜客户源需求：流程图]**
+> 占位文件：`docs/images/omc-nixi/03-requirement-flow.png`
+> 建议内容：FT/FP 两张流程图（含 `SubConRootCause=1` 分支）
+
+### 步骤 1：环境自检 + 建应用
+
+```bash
+omc doctor                                          # 配置/登录/版本族/指纹/许可证
+omc call discover_environment --env nixi --args '{}'  # 确认环境、默认应用、门户分组
+omc call app.create --env nixi --args '{"code":"SubConMaverick","name":"代工厂异常批次","groupId":"<AOSPE 分组 id>"}'
+```
+
+要点：**应用创建不在 `intent` 声明式面内**。
+
+必须先 `app.create`，再把环境默认应用指向它；后续 `intent` 建模才会落到新应用。
+
+> **[截图 04｜对话：应用与环境确认]**
+> 占位文件：`docs/images/omc-nixi/04-chat-app-create.png`
+> 建议内容：与 Agent 确认「新建应用」并返回 `app.create ok` 的那段对话
+
+### 步骤 2：读需求，定型号
+
+把两个 Sheet 的每一行读成 `{code, name, type, required, 显隐}`，识别出：
+
+- FT：39 个字段 + 2 个子表（`Chip` 2 列、`SBLTriggerItem` 3 列）
+- FP：38 个字段 + 1 个子表（`Wafer` 9 列）
+- 类型映射：`字符串→SHORT_TEXT`、`长文本→LONG_TEXT`、`数字→NUMERICAL(+scale)`、`固定枚举→RADIO(choices)`、`附件→ATTACHMENT`、`子表→CHILD_TABLE(subFields)`
+
+这里唯一需要人拍板的是几处歧义：节点名 TE/PE、`programName` 类型、子表列数。
+
+其余照表落。
+
+### 步骤 3：一次声明式建模（intent）
+
+两个模型、77 个字段、3 个子表、2 张默认表单、2 个列表视图，全部写进**一个 `intent.yaml`**：
+
+```bash
+omc intent validate intent.yaml           # 离线校验（会卡 code 命名：必须 lowerCamel / lower_snake）
+omc intent plan intent.yaml --env nixi    # 编译成 plan（本例 89 个动作）
+omc intent apply plan.json                # 串行执行 + 默认读回等价确认
+```
+
+回执关键行：`equivalent: true`。
+
+意思是平台实际状态与 intent 声明**逐字段等价**，不是「大概建上了」。
+
+> **[截图 05｜对话：intent apply 回执]**
+> 占位文件：`docs/images/omc-nixi/05-chat-intent-apply.png`
+> 建议内容：`intent apply` 返回 `DELIVERED` + `equivalent: true`（89 个动作）的那段
+
+这一步的收益最直观：**两条命令代替了几百次界面点击**。
+
+而且重复跑是幂等的（零变更）。
+
+### 步骤 4：两条审批流 + 角色路由
+
+流程用 `workflow.create` 起骨架。
+
+再用 `workflow.update` 一次性补**节点 + 路由 + 参与人 + 节点字段权限**：
+
+```bash
+omc call workflow.create --env nixi --args '{"schemaCode":"scmFt","name":"SubCon Maverick Lot-FT 流程","code":"scmFtFlow"}'
+omc call workflow.update --env nixi --args-file wf_scmFt.json    # 整模板：START/END + 5 节点 + routes + propertyPermissions
+omc call workflow.publish --env nixi --args '{"schemaCode":"scmFt","code":"scmFtFlow"}'
+```
+
+拓扑（两条流程一致）：
+
+```text
+开始 → 填写申请单 → AOS PE Review ─[subConRootCause = Y]→ SQE approve ─┐
+                          └────────[else 兜底]────────────────────────→ ┴→ SubCon ENG 执行并反馈 → AOS PE Confirm → 结束
+```
+
+**角色路由**（本例的「配置角色」落在节点的参与人表达式上）：
+
+| 节点 | 办理人 |
+|---|---|
+| 填写申请单 | `{Originator}`（发起人） |
+| AOS PE Review | `IF({productType}=="PIC",[蔡依涛],[赵益])` —— 按产品线分流到不同 AOS 工程师 |
+| SQE approve | 部门 `AOSIT` |
+| SubCon ENG 执行并反馈 | 部门 `AOSENG` |
+| AOS PE Confirm | 部门 `AOSIT` |
+
+> **[截图 06｜对话：流程节点与角色配置]**
+> 占位文件：`docs/images/omc-nixi/06-chat-workflow-role.png`
+> 建议内容：确认「PIC→蔡依涛 / MOS→赵益、SQE/确认→AOSIT、执行→AOSENG」的对话
+
+### 步骤 5：节点字段权限 —— 累计可见
+
+客户的真实诉求是一句话：
+
+> **「每个节点都要能看到本节点以及之前所有节点的字段，不然审批怎么知道表里填了什么」**
+
+于是每个审批节点的可见集合 = 前面所有节点字段 ∪ 本节点字段。
+
+**只有本节点自己的字段可编辑**，之前的一律只读：
+
+| 节点 | 可见 | 可编辑 |
+|---|---|---|
+| 填写申请单 | 22 | 22 |
+| AOS PE Review | 25（22 + 本节点 3） | 3 |
+| SQE approve | 31（+ 本节点 6） | 6 |
+| SubCon ENG 执行 | 33（+ 本节点 2） | 2 |
+| AOS PE Confirm | 39（全部） | 6 |
+
+这一步最能体现 CLI 的价值。
+
+39 个字段 × 5 个节点的权限矩阵，人手工点要几百次勾选；这里是**一份 JSON 一次写回**。
+
+> **[截图 07｜对话：节点字段权限矩阵确认]**
+> 占位文件：`docs/images/omc-nixi/07-chat-permission-matrix.png`
+> 建议内容：审批节点「本节点 + 之前所有字段可见」的确认与回读矩阵
+
+### 步骤 6：规则类补配
+
+| 需求 | 落点 |
+|---|---|
+| 良率自动计算 `Yield = TestOutQty / TestInQty` | `datarule.create`（type2，门户前端计算） |
+| `LotClass=ENG` 时若干字段不显示 | 字段 `options.displayFormula` |
+| Action 与 SubConRootCause 二选一必填 | `options.requiredFormula` + 节点必填 |
+
+### 步骤 7：快速配置业务集成（一条命令 = 服务 + 方法 + 参数）
+
+这一步是「配置面里最容易低估」的。
+
+**平台业务集成不用点界面。**
+
+`service.register` 一条命令，就能把一个 SQL 服务连同它的方法、入参、出参一次注册好。
+
+本例注册了两个数据源方法（都是 `DATA_SQL` 适配器，直连客户 Oracle）：
+
+| 服务 code | 服务名 | 连接池 | 方法 | 入参 | 出参 |
+|---|---|---|---|---|---|
+| `productType` | 产品线(件号-PDM) | `PDM` | `GetProductTypeByPartName` | `PartName` | `PRODUCT_TYPE` |
+| `datahub` | datahub | `datahub` | `GetProductTypeByWaferName` | `WaferName` | `PRODUCT_TYPE` |
+
+注册顺序（先建分类，再一次注册）：
+
+```bash
+# 1. 建集成分类（返回 id，下一步要用）
+omc call service.category.create --env nixi --args '{"name":"产品线查询"}'
+# → readback.id = d0db6b83be474234b8ab66c63fb6cbb8
+
+# 2. 一条命令：服务 + 方法 + 入参 + 出参（DATA_SQL）
+omc call service.register --env nixi --args '{
+  "serviceCode": "productType",
+  "name": "产品线(件号-PDM)",
+  "adapterCode": "DATA_SQL",
+  "serviceCategoryId": "d0db6b83be474234b8ab66c63fb6cbb8",
+  "description": "根据件号查询产品线（MOS/PIC/NA）",
+  "serviceConfig": {
+    "auth": {"code": "", "name": "", "parameterlist": []},
+    "commonlist": [{"code": "databaseConnectionPoolCode", "name": "数据库连接池编码", "required": true, "value": "PDM"}]
+  },
+  "methodName": "GetProductTypeByPartName",
+  "methodConfig": {
+    "sql": "select itemname, case when product_line in (...) then ''MOS'' ... end product_type from (...) where itemname = :PartName",
+    "countSql": "select count(*) as count from (...) t where itemname = :PartName",
+    "returnType": "SingleObject",
+    "frontEndExtensionEnable": true
+  },
+  "methodInputParameters": [{"code":"PartName","name":"PartName","required":true,"externParameterType":1000,"bizPropertyType":0}],
+  "methodOutputParameters": [{"name":"PRODUCT_TYPE","code":"PRODUCT_TYPE","externParameterType":1000,"required":false,"bizPropertyType":0}]
+}'
+```
+
+> **`frontEndExtensionEnable: true` 是整件事的关键开关** —— 只有打开它，表单在线 JS 才能通过
+> `/api/runtime/bizbus/invoke` 直接调这个方法。忘了它，SQL 再对，前端也调不到。
+
+**立刻验证（会真连客户库）**
+
+```bash
+omc call method.test --env nixi --args '{"serviceCode":"productType","methodCode":"GetProductTypeByPartName","inputParameters":{"PartName":"AO3406L"}}'
+# → {"success":true,"data":{"ITEMNAME":"AO3406L","PRODUCT_TYPE":"MOS"}}
+```
+
+`method.test` 的 `externalSideEffect` 会是 `real`（真打外部数据源），所以**只读查询可以直接测，写库型方法要谨慎**。
+
+后续改 SQL 用 `method.update`：只动方法，不重建服务。
+
+重跑 `method.test` 和 `service.get` 复核；读回是脱敏的，凭据不会进日志。
+
+> 本例最终 `service.get` 读回：`adapterCode: DATA_SQL`、`configJson.commonlist[0].value: PDM`、
+> `frontEndExtensionEnable: true`、`methods[0].configJson.returnType: SingleObject`。
+
+> **[截图 08｜对话：业务集成快速注册]**
+> 占位文件：`docs/images/omc-nixi/08-chat-biz-integration.png`
+> 建议内容：`service.register` 注册 productType 服务 + `method.test` 返回 `PRODUCT_TYPE=MOS` 的那段
+
+### 步骤 8：在线 JS（产品线自动带出）
+
+客户另给了 SQL（`FT_Get_ProductTypeByAOSPartName`）。
+
+需求是：在 FT 表单填「AOS产品名」后，自动带出**产品线**和**封装类型**。
+
+关键结论：表单 JS 不用自定义接口，走平台内置的**业务集成调用端点**：
+
+```js
+h3form.axios.post(config.apiHost + '/api/runtime/bizbus/invoke', {
+    serviceCode: 'productType',
+    methodCode: 'GetProductTypeByPartName',
+    args: { PartName: value }
+})
+```
+
+发布也走 CLI，不必进设计器粘贴：
+
+```bash
+omc call onlinejs.compose --env nixi --args-file compose_scmFt.json   # replace:true + publish:true
+```
+
+> **[截图 09｜对话：在线 JS 发布]**
+> 占位文件：`docs/images/omc-nixi/09-chat-onlinejs-publish.png`
+> 建议内容：`onlinejs.compose` 返回 `DELIVERED` / `published: true` 的那段
+
+### 交付物
+
+```text
+intent.yaml                     # 两个模型 + 字段 + 子表 + 表单 + 视图（可重放）
+wf_scmFt.json / wf_scmFp.json   # 两条流程整模板（节点 + 路由 + 权限）
+service-productType.json        # service.register 参数（服务 + 方法 + 入出参）
+compose_scmFt.json              # 在线 JS 发布参数
+SQL-已参数化.sql                # 业务集成 SQL（:PartName 绑定变量）
+README.md                       # 内网手工配置步骤
+```
+
+一次会话的产出，换来的是一整套**可重放、可 diff、可回滚**的配置源文件。
+
+而不是一堆「当时点对了但没留下痕迹」的界面操作。
+
+---
+
+## 3. 实战二：用 OMC 排查并修复线上问题
+
+> **中冶的两个线上问题。**
+>
+> 不点菜单、不连库，靠 OMC 只读面逐步收敛到「配置的哪一行」，再用写面（五件套）改掉。
+>
+> 日志只做一件事：提供**运行时刻**的证据。
+
+### 排障主链路：四步全在 OMC 里
+
+下面表格里的调用都省略了 `omc call` 前缀，只写工具名和参数。
+
+```text
+① 定模型   model.list（按应用过滤）→ model.inspect
+② 定口径   field.list（中文名 → code，别猜字段名）
+③ 定写入者 datarule.list（1=校验 2=计算/拼接）/ onlinejs.get / rule.get + artifact / form.get
+④ 定数据   data.load / data.list → 与日志报文对照：「本来没有」还是「被覆盖」
+```
+
+第 ③ 步是成败点。
+
+**一个字段有四种写入来源**：
+
+- 在线 JS
+- 字段级数据规则
+- 业务规则节点
+- 关联表单带出映射
+
+只查一种就下结论，必翻车。日志在这四步之外补位，用法只有两条：
+
+```bash
+cd <backend>/launcher/logs/total
+grep -o 'expression=[^ ]*' <(sed -n '4540,4700p' log-total-<日期>.12.log) | sort | uniq -c  # 当时跑了哪些规则
+grep -ho '"<字段>":"[^"]*"' *<日期>*.log | sort | uniq -c                                        # 该字段历史上出现过什么值
+```
+
+### 案例 A：合同编号每次新增被冲空
+
+| 步 | OMC 调用 | 拿到什么 |
+|---|---|---|
+| ① | `model.list --args '{"applicationCode":"HTGL","filter":"合同"}'` | 定位到 `pr_contract_registration`（登记）、`contract_master_data1`（主数据） |
+| ② | `field.list --args '{"schemaCode":"pr_contract_registration","code":"contract_number"}'` | 「合同编号」= `contract_number`；顺带发现「合同编码」是另一个字段 `contract_code` |
+| ③ | `datarule.list --args '{"schemaCode":"pr_contract_registration","dataRuleType":2}'` | **命中根因**：`contract_number` 有一条短文本拼接规则 `CASE({constep}="合同变更/补充",{changeContractCode},{constep}="主合同",{mainCode})` |
+| ③ | `form.get --args '{"schemaCode":"pr_contract_registration","controls":["ref_contract_review"]}'` | 关联评审单的带出映射：`contractNumber → mainCode`、`contractNumber3 → changeContractCode` |
+| ④ | `data.load` 登记单 + 主数据 | 登记单 `contract_number=""`、`mainCode=""`；主数据 `businessCode=""` —— 上游就是空 |
+
+日志佐证两点：
+
+- 01:24:32 出现 `expression=CASE({constep}=…{mainCode})`，说明保存时规则确实重算并回写了空值——这就是「必现」的机制。
+- `grep '"mainCode":"'` 全时间窗零条非空，说明输入变量从未有值。
+
+**结论**：不是谁删了编号，是编号压根没产生。
+
+拼接规则的两个输入来自评审单的「经营合同编号 / 变更编号」。
+
+这两列为空 → 带出即空 → 拼接再覆盖空 → 主数据与 NC 的 `vbillcode` 一路空。
+
+反证：成本类走 `pc_contract_registration`，同期 `cbht01`、`CIEHTGU-01` 正常出号。
+
+**OMC 修法（二选一，按业务口径定）**
+
+- A｜补上游（推荐）：评审单侧让编号真正生成/回填，登记单的拼接规则原样保留 —— 不写配置，改流程/编号规则。
+- B｜改规则：`datarule.update` 给 CASE 加 `ELSE` 兜底（如取 `contract_code`），保证不落空；
+  代价是「合同编号」与「合同编码」被混同，需业务确认。
+
+### 案例 B：收款计划变更子表为空
+
+| 步 | OMC 调用 | 拿到什么 |
+|---|---|---|
+| ① | `model.inspect --args '{"schemaCode":"contract_master_data1"}'` | 找到 `Update` 规则（14 节点），其中 `DataCreate10` 发起 `collection_plan_adjust` |
+| ③ | `rule.get --args '{"schemaCode":"contract_master_data1","ruleCode":"Update","full":true}'` + `artifact get <id> --jq "nodes"` | **命中根因**：`DataCreate10` 19 条主表映射，`children=""` —— 子表映射根本没配 |
+| ③ | `form.get --args '{"schemaCode":"collection_plan_adjust","sheetCode":"performance_payment","controls":true}'` | 子表控件 `performance_paymentrs` 的 `dataItemName=contract_payment_item` |
+| ④ | `data.list --args '{"schemaCode":"contract_payment_item"}'` / `--args '{"schemaCode":"performance_payment"}'` | 前者 **0 条**，后者 12 条且 `parentId` 指向的主记录**都已不存在**（孤儿行） |
+
+**结论**：两层问题叠在一起。
+
+1. 规则节点没配子表映射，新单子表天然为空。
+2. 控件绑定的子模型（`contract_payment_item`）与历史数据所在的子模型（`performance_payment`）已经错位，老数据成孤儿。
+
+**OMC 修法**
+
+1. `rule.node.update` 给 `DataCreate10` 补 children：合同主数据 `con1collectionSchedule_jndv` →
+   `performance_paymentrs`，并补 `contractTotalAmount` 映射。
+2. 统一子表模型口径（控件 `dataItemName` 与规则写入目标一致），迁移或清理 12 条孤儿行。
+
+### 用 OMC 写：五件套
+
+```text
+discover → draft（人工确认）→ 权限门（writable / production 需 confirmProduction:true）
+        → execute（一次写调用）→ readback（证明状态）
+```
+
+排障阶段全是读面，改的时候按这个顺序：
+
+```bash
+omc call discover_environment --args '{}'                       # 拿环境指纹，写前必须重取
+omc call datarule.update --args '{…,"dryRun":true}'             # 先看计划，不落盘
+omc call datarule.update --args '{…,"confirmProduction":true}'  # 生产必带该字段
+omc call datarule.list  --args '{"schemaCode":"…","dataRuleType":2}'   # 读回：确认不是只改了草稿
+```
+
+纪律：
+
+- **一个变更包只用一个引擎**（OMC 或 cp-model），读、Dry Run、写、回读都归它。
+- 写前把设计用大白话讲清并拿到明确同意；草稿未批准可随意改，批准后指纹变了就作废重来。
+- 改完固定三条回读：
+    1. **规则读回**：`rule.get` / `datarule.list` 确认已发布态。
+    2. **数据读回**：造一条新单 `data.load`，看落值 / 子表行数。
+    3. **日志读回**：grep 该单 id + TID，确认计算输出符合预期。
+
+### 一页速查
+
+```text
+字段为空 / 被清空
+  ├─ datarule.list --dataRuleType 2   → 是不是计算/拼接字段（会被重算覆盖）
+  ├─ onlinejs.get                     → 前端有没有在写
+  ├─ form.get --controls              → 关联表单 mappings，源字段是否本来就空
+  └─ data.load 对照日志 bizObject 报文 → 「本来没有」还是「被覆盖」
+
+下游单据 / 子表没数据
+  ├─ rule.get + artifact --jq nodes   → CREATE 节点 children 是否为空
+  ├─ 控件 dataItemName 指向哪个子模型 → data.list 该子模型总条数
+  └─ 孤儿行：子表 parentId 在主模型 data.load 是否存在
+```
+
+---
+
+## 4. 它能做什么
+
+想确认某个能力能不能做，先跑两条：
+
+```bash
+omc capabilities                     # 一张表看清 16 项能力
+omc capability <id> --executable     # 单个能力的完整执行包
+```
+
+覆盖的环节：
+
+- 环境、应用、模型、字段
+- 表单、视图、业务规则
+- 审批流、业务集成
+- 运行数据、报表
+
+| 能力 | 能做的事（需求线索） | 工具数 | 覆盖 | 声明式(intent) | 依赖 |
+|---|---|---|---|---|---|
+| `environment` 环境治理 | 环境发现、指纹、版本、连接/登录/就绪 | 2 | executable | none | - |
+| `app` 应用 | 应用包建/改/删、列出 | 4 | executable | none | - → folder |
+| `folder` 应用目录（分组） | 应用树目录/分组、移动模型、**自定义页面** | 12 | executable | none | app → - |
+| `dictionary` 数据字典 | 字典与字典记录、键值/树型、选项来源 | 12 | executable | none | - |
+| `model` 业务模型 | 建/改名/移动/删除模型、摘要、一次建模型+字段+表单 | 9 | executable | partial | - → field, workflow |
+| `field` 字段 | 字段族、**子表**、下拉/人员/部门/日期/数值/关联、**计算字段**、单据号 | 5 | executable | partial | model → form, listview, datarule, businessrule, data |
+| `form` 默认表单 | 表单布局、发布、按钮（含按钮 JS） | 5 | executable | partial | field → onlinejs |
+| `listview` 列表视图 | 表头列、排序、筛选、按钮（含按钮 JS） | 5 | partial | partial | field → - |
+| `datarule` 字段级规则 | 条件必填/只读/显示、计算拼接 | 4 | partial | partial | field → - |
+| `businessrule` 业务规则 | 图形规则图、事件触发、BRANCH、BIZ_ACTION、**定时任务**、跨规则引用检索 | 5 | executable | partial | field → rule-lifecycle |
+| `rule-lifecycle` 规则生命周期 | 启用/停用/删除/手动执行 | 6 | executable | none | businessrule → - |
+| `workflow` 流程模板 | 审批流模板、节点/路由、发布、事件规则绑定、发起权限、待办、组织（角色/部门/用户） | 38 | executable | partial | model → - |
+| `onlinejs` 表单在线 JS | 表单在线脚本 compose / 读回（含 SHA-256） | 2 | executable | partial | form → - |
+| `bizservice` 业务集成 | 服务与方法注册（RESTFUL/DATA_SQL/…）、分类、连接池、导入导出、设计器测试 | 24 | executable | partial | - |
+| `report` 报表 | 报表页、BI 图表、数据集（**仅用户显式要求时**） | 9 | partial | partial | - |
+| `data` 运行数据 | 业务记录读/写/更新/删除/提交（工作流） | 6 | executable | none | field → - |
+
+> **覆盖**：`executable` 全量可用；`partial` 有已取证边界（见 `omc capability <id>` 的 notes）。
+> **声明式(intent)**：`partial` = 该能力可用 YAML 声明一部分（通常 create/update）；`none` = 只走 `omc call`。
+> **依赖** = `requires → precedes`，即能力之间的配置顺序；例如字段依赖模型，表单依赖字段。
+> **组织**：`workflow` 的 38 个工具里包含 `org.*`（角色/部门/用户）——组织是流程的一部分，不单独成能力。
+
+工具面合计 **154 个**：元/治理 5 + 读 55 + 写 94。
+
+## 5. 怎么用
+
+### 5.1 `omc call` —— 一次一工具（原子面）
+
+```bash
+omc call discover_environment --env test --args '{}'
+omc call model.create --env test --args '{"name":"客户","code":"x_customer"}'
+omc describe field.create --example dictionary-backed-single-select   # 拿可运行示例
+```
+
+读面可一步取值：`--jq` / `--extract <path>` / `--extract-keys`。
+
+这样能省掉再跑一次 `artifact get`。
+
+### 5.2 `omc intent` —— 声明式意图面（推荐默认）
+
+用一份 YAML 描述一组变更，编译成**不可变 plan** 再执行：
+
+```bash
+omc intent validate intent.yaml          # 离线语义校验（错误带 源行:列）
+omc intent plan intent.yaml --env test   # 读基线 → 编译 → plan（planHash 复核对象）
+omc intent apply plan.json               # drift 门 + writable 检查 + 串行执行 + 默认读回等价确认
+omc intent readback intent.yaml --env test   # 解码回 intent 形状做等价校验
+```
+
+- 顶层 `models[]` / `services[]`；`models[].{code,name,fields,datarules,rules,form,listview,workflow,onlinejs}`。
+- `intent apply` 既可以吃 `plan` 文件，也可以直接吃 YAML（`omc intent apply intent.yaml --env <env>`，自动编译）；大 plan 会自动外置，回 `planFile`。
+- **幂等收敛**：已达标环境重跑 plan/apply → 零变更、零重复创建。
+- 显式缺席（删除）：`models[].absent:true` 删整模型、`fields[].absent:true` 删单字段；plan 的 `riskClass` 升为 `destructive`。
+- 生产 apply 加 `--confirm-production`；`--dry-run` 预览，`--no-verify` 跳过最终读回。
+
+### 5.3 复合命令 —— 一条命令 = 一个变更包
+
+| 命令 | 作用 |
+|---|---|
+| `omc model-scaffold` | 一条命令建模型 → N 字段（含子表）→ 发布字段 → 发布表单；先对每个字段 dry-run 预检 |
+| `omc model-purge` | 按依赖倒序清掉一个模型（流程实例 → `model.delete` 级联） |
+| `omc submit-verify` | 逐条提交 → 真实 id 读回 → 差异汇总 |
+| `omc rule-save-enable` | 保存成功才启用，回执回答「会不会真的运行」 |
+| `omc workflow-update-publish` | 显式合成最终模板（默认保留旧节点，`--confirm-replace` 才丢弃） |
+| `omc call apply_changes` | 批量提交异构变更清单 `changes:[{tool,args}]`，首败即停、逐步读回、整批时间预算 |
+| `omc script` | NDJSON 多调脚本，一个进程一次会话跑完全部 |
+| `omc rollback` | 配置回滚（list / plan / apply），git-revert 语义；journal 与 before 快照是本机边界（不跨机器），publish 类生命周期推进不可逆 |
+
+另有若干「不写环境」的辅助命令：`compute`（聚合公式编译）、`rule-when`、`approval-flow`、`form-default`、
+`bench`（跑分）、`usage`（用量账本）、`next`（目标 → 工具一步定位）。
+
+### 5.4 一条完整链路
+
+```bash
+# 0. 配置与自检
+omc setup && omc doctor && omc call discover_environment --env test --args '{}'
+
+# 1. 建模型 + 字段 + 表单（默认 dry-run 只列计划；加 --apply 才执行）
+omc model-scaffold --code x_customer --name 客户 \
+  --fields '[{"name":"名称","code":"name","propertyType":"SHORT_TEXT"},{"name":"等级","code":"level","propertyType":"DROPDOWN_BOX","choices":["A","B"]}]' \
+  --env test --apply
+
+# 2. 配业务规则（--node-graph 传规则图 JSON；保存成功才启用；默认 dry-run）
+omc rule-save-enable --schema x_customer --rule-code customer-oncreate --name 创建客户后处理 \
+  --node-graph "$(cat rule-graph.json)" --env test --apply
+
+# 3. 更新并发布审批流（--template 传流程模板 JSON；默认 dry-run 合成预览）
+omc workflow-update-publish --schema x_customer --code customer_flow \
+  --template "$(cat workflow.json)" --env test --apply
+
+# 4. 灌一条正式数据（无流程模型）
+omc call data.submit --env test --args '{"schemaCode":"x_customer","formData":{"name":"甲","level":"A"}}'
+
+# 5. 验收：读回、核对交付态、清理测试数据
+omc call model.inspect --env test --args '{"schemaCode":"x_customer"}'
+omc rollback list
+```
+
+## 6. 设计取舍：为什么是 CLI
+
+### 6.1 初衷与一次转向
+
+这套 CLI 的初衷很简单：**让二开更简单、更方便**。
+
+让 AI 把散落在平台各处的配置、数据、触发和核对，串成一条链。
+
+它最早不是这个形态。
+
+最初想做的是**基于 dsh 的云枢专用 agent**：一套二开插件，把前后端改造、表单配置、环境配置、二开代码配置都收进去。
+
+名字 **Oh My CpAgent / omc**，则受 **Oh My OpenAgent** 和 **Oh My Pi** 启发。
+
+**放弃的原因有两个。**
+
+- **分发性**。插件绑平台——所有人得先下客户端、再装插件。就像 AI 大赛上基于 dsh 发布的 **Authine X**，能力不错，但使用门槛是「先装一套东西」。我们要的是谁都能用。
+- **版本成本**。dsh 迭代太快，接口几个月换一轮，插件跟着追版本是长期负债。
+
+最后选了 **npm CLI**：装在本机，agent 有 shell 就能调用。
+
+换模型、换客户端、换平台都不受影响。
+
+将来要 MCP 或平台插件，可以在同一条治理管线上再包一层。
+
+### 6.2 三条路都比过
+
+**MCP：schema 常驻太贵。**
+
+81 个工具的 schema 实测 208,985 B（约 53k tokens）。
+
+同一条发现流程：MCP 约 214.5 KB，CLI 约 6 KB——约 35 倍、接近 97% 的缩减。
+
+工具越多越明显。MCP 面已按 ADR-0004 移除。
+
+**Skill：适合讲方法，不适合承担强制治理。**
+
+cpdocs 用 Skill 承载编码知识，做得很好。
+
+但「真正去改环境」如果只靠文档里的纪律，就依赖模型自觉。
+
+CLI 把 writable、生产确认、写锁、幂等、读回做进**进程边界**。
+
+结论是：**方法论放 Skill，执行放 CLI。**
+
+**平台插件：可分发性最差。**
+
+见上面 dsh 那段。
+
+### 6.3 Token 治理：渐进式披露
+
+**发现面分档，按需放大。**
+
+- `next`：2–5 KB
+- `commands --json --compact --lane`：约 1 KB
+- `describe`：1.5–2.5 KB
+- `commands --json`：约 20 KB（回退面）
+
+先走小档，缺形状再放大。
+
+**默认只回索引 / 摘要 / 形状。**
+
+- `help` 回节索引（约 1 KB）
+- `artifact get` 正文 > 8 KB 只回形状
+- `usage` 只回汇总
+
+**一步取值，不重复搬。**
+
+- `--jq` / `--extract`
+- `model.inspect` 替代六连调
+- `script` / `--args-list` 一进程多调
+
+**有基线守着。**
+
+`eval:call-face` / `eval:intent-face` / `eval:discovery-cost` 都会跑固定任务；能力投影路线的发现调用约减半（20 → 10）。
+
+### 6.4 方法论随包走
+
+`omc help` 带 13 个 topic，默认只回节索引。
+
+常用的有：
+
+- `start-here` · `tool-selection` · `requirement-analysis`
+- `capabilities` · `config-draft-review` · `five-piece-flow`
+- `write-hazards` · `acceptance-criteria` · `refusals`
+- `glossary` · `business-configuration`
+
+写操作固定五段式：
+
+> 发现现状 → 出草稿 → 过写入门 → 执行 → 读回/清理
+
+### 6.5 和 cpdocs 的分工
+
+**OMC 是操作低代码配置的「手脚」，cpdocs 是帮 AI 做编码开发的「知识库」。**
+
+- cpdocs 负责：需求理解、方案与编码（Java 后端、Vue 前端、规范）。
+- OMC 负责：把方案落到平台配置，并做读回、造数、验收。
+
+两者重叠的模型 / 字段 / 表单 / 视图 / 规则 / 流程上，`cpdocs-guide` 会给出两个候选：`cp-model` 与 `omc`。
+
+---
+
+## 7. 治理与安全（每个写调用都过的管道）
+
+```
+语义门（字段族 / 规则图 dry-lint / 业务编码 / 表单布局 / 各工具 preflight，零 wire）
+  → 覆盖门（清单声明；超界拒绝并引用条目）
+  → 环境写入门（writable=false 拒绝；生产需 confirmProduction:true）
+  → 会话 + 版本族门（缺版本证据即关闭）
+  → dry-run / requestId 重放门
+  → 写租约（同环境跨进程文件锁串行；冲突回 write-lock-held）
+  → 执行 → 权威读回 → artifact 交付 + 人话 summary
+```
+
+- **stdout 恒为恰好一个 JSON envelope** `{ok,status,result,requestId,error{code,message,retryable}}`；人类诊断全在 stderr。
+- **退出码族**：`0` ok · `10` invalid-input · `11` auth-config · `12` policy-refused · `14` uncertain · `15` internal；细分以 `error.code` 为准。
+- **不确定性语义**：传输失败冻结为 `status:"uncertain", frozen:true`，绝不伪造成功。
+- **人门在对话层**：机器管道只执行 writable 与 `confirmProduction` 检查；Agent 必须先出草稿并取得用户明确批准（`omc help omc-config-draft-review`）。
+
+## 8. 不能做什么（边界）
+
+这些是**明确答复**，不是要绕过的障碍：
+
+| 面 | 状态 | 说明 |
+|---|---|---|
+| 通用权限 / 授权矩阵 | blocked | 授权矩阵不在配置面（流程发起权限、组织/角色写入另有工具） |
+| 跨模型子表 / 关联联动 / 子到子 | blocked | 未取证，不猜写 |
+| OCR / 电子签章 / 发票识别 | unsupported | 不在平台配置覆盖内 |
+| 应用发布 / 环境上线 / 生产发布 | unsupported | CLI 只做配置，不做环境发布 |
+| 在线后端编码（`/api/api/programming` Java 源码） | unsupported | 用二开扩展包，本 CLI 无工具 |
+| 列表视图分组（queryLayer） | 未取证 | 别猜写 |
+
+**两条补充：**
+
+- **子表天生只有一级。** 一个主表可以有多个子表，但子表不能再套子表。所以「嵌套子表」不是 CLI 的能力缺口，而是平台不存在的形态，别按这个方向设计需求。
+- **被挡不等于做不了。** `blocked / unsupported` 通常意味着行为要路由到另一个代码所有者（配置 + 后端扩展）。
+
+## 9. 安装（npm）
+
+包名：**`@stalfh233/omc-cli`**（命令仍是 `omc`）。
+
+已发布到公共 npm registry：
+<https://www.npmjs.com/package/@stalfh233/omc-cli>
+
+环境要求：Node.js 22.13+（`omc-core` 使用内置 `node:sqlite`）。
+
+```bash
+# 全局安装（推荐）
+npm install -g @stalfh233/omc-cli@latest
+
+# 验证
+omc --version        # 当前基线 0.4.100
+omc setup && omc doctor
+
+# 查看 npm 上的最新版本
+npm view @stalfh233/omc-cli version
+
+# 固定 / 升级版本
+npm install -g @stalfh233/omc-cli@0.4.100
+npm update -g @stalfh233/omc-cli
+```
+
+也可以只在当前项目里安装、用 `npx` 调用：
+
+```bash
+npm install @stalfh233/omc-cli
+npx omc setup && npx omc doctor
+```
+
+> `omc-core` 是内部依赖，会随 `@stalfh233/omc-cli` 自动安装，不需要单独装。
+>
+> 现在还在 `0.4.x` 的阶段，能力覆盖和部分形状还会继续扩、继续调——我们会跟着实际使用不断打磨、修问题。
+>
+> `1.0.0` 之前，别把它当成冻结的契约。
+
+## 10. 上手速查
+
+```bash
+omc setup && omc doctor && omc commands --json
+
+omc help                    # 命令清单 + 方法论 topic 清单
+omc help --search "<词>"     # 跨 topic 找具体事实
+omc next "我想做一个审批流程"       # 目标 → 工具一步定位
+omc capabilities            # 16 能力一张表
+omc capability model --executable  # 单能力完整执行包
+omc describe <tool>         # 单工具 schema + 可运行示例
+```
+
+**在什么目录运行？**
+
+把 omc 当工具用时，请在**独立、干净的项目目录**里运行，不要放在 OMC 研发仓里。
+
+否则 Agent 可能读到只属于研发的产物（`.scratch/`、`CONTEXT.md` 等），误当成使用指引。
+
+## 11. 术语速记
+
+- **覆盖清单（coverage manifest）**：随包的能力契约，`executable / partial / blocked / static-only / unsupported` 五态。
+- **交付态（delivery state）**：写入后权威读回得到的真实状态，是「配好了」的唯一判据。
+- **artifact**：大读回外置的、带 sha256 的 0600 文件。
+- **plan / planHash**：intent 编译出的不可变复核对象。
+- **写租约（write lease）**：同环境写入的跨进程互斥。
+- **最小路径（minimal path）**：某类需求实际需要的最短发现→草稿→写→读回路线，是用量分析的对照基线。
+
+## 12. 附录：全部工具清单
+
+> 以 `omc commands --json` 为准；下面是按能力分组的当前快照（154 个）。
+
+**元 / 治理（6）**
+
+`coverage.manifest` · `get_status` · `setup.start` · `setup.commit` · `doctor` · `apply_changes`
+
+**environment 环境治理（2）**
+
+`discover_environment` · `environment.fingerprint`
+
+**app 应用（4）**
+
+`app.list` · `app.create` · `app.update` · `app.delete`
+
+**folder 应用目录 / 自定义页面（12）**
+
+`folder.tree` · `folder.create` · `folder.update` · `folder.delete` · `custompage.list` · `custompage.get` · `custompage.create` · `custompage.update` · `custompage.content.get` · `custompage.content.update` · `custompage.content.publish` · `custompage.delete`
+
+**dictionary 数据字典（12）**
+
+`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`
+
+**model 业务模型（9）**
+
+`model.list` · `model.inspect` · `model.create` · `model.delete` · `model.deleteMany` · `model.setSummary` · `model.update` · `model.move` · `configure_model`
+
+**field 字段（5）**
+
+`field.list` · `field.create` · `field.update` · `field.publish` · `field.delete`
+
+**form 默认表单（5）**
+
+`form.get` · `form.draft` · `form.publish` · `configure_form` · `form.runButton`
+
+**listview 列表视图（5）**
+
+`listview.get` · `listview.list` · `listview.create` · `listview.configure` · `listview.delete`
+
+**datarule 字段级规则（4）**
+
+`datarule.list` · `datarule.create` · `datarule.update` · `datarule.delete`
+
+**businessrule 业务规则（5）**
+
+`rule.list` · `rule.references` · `rule.get` · `rule.save` · `rule.node.update`
+
+**rule-lifecycle 规则生命周期（6）**
+
+`rule.enable` · `rule.disable` · `rule.delete` · `rule.run` · `rule.disableMany` · `configure_rule`
+
+**workflow 流程模板（38）**
+
+`workflow.get_draft` · `workflow.get_published` · `workflow.validate` · `workflow.create` · `workflow.update` · `workflow.publish` · `workflow.bindRule` · `workflow.setButtons` · `workflow.delete` · `configure_workflow` · `workitem.list` · `workflow.instanceActivity` · `workflow.permissions` · `workflow.addPermission` · `workflow.removePermission` · `org.role.list` · `org.department.list` · `org.user.search` · `org.role.users` · `org.role.userScope` · `org.roleGroup.create` · `org.role.create` · `org.department.create` · `org.department.update` · `org.department.delete` · `org.department.users` · `org.user.create` · `org.user.update` · `org.user.delete` · `org.user.info` · `org.user.departments` · `org.role.delete` · `org.roleGroup.delete` · `org.user.transferDepartment` · `org.role.update` · `org.role.addUsers` · `org.role.removeUsers` · `org.role.setUserScope`
+
+**onlinejs 表单在线 JS（2）**
+
+`onlinejs.get` · `onlinejs.compose`
+
+**bizservice 业务集成（24）**
+
+`service.get` · `service.list` · `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`
+
+**report 报表（9）**
+
+`report.tree` · `report.get` · `report.chartdata` · `report.datasource.list` · `report.datasource.link` · `report.create` · `report.update` · `report.delete` · `report.configure`
+
+**data 运行数据（6）**
+
+`data.list` · `data.load` · `data.save` · `data.update` · `data.delete` · `data.submit`