@stalfh233/omc-cli 0.5.0 → 0.5.2

package/skills/omc-refusals.md

@@ -1,127 +1,127 @@
----
-name: omc-refusals
-description: Decode a refused or uncertain OMC result. Use when a call returns refused/uncertain, or a status looks wrong, to find what the blocker means and the correct next action. Grouped by family, not enumerated per code.
----
-
-# Refusals & Recovery (拒绝与恢复)
-
-Grouped by family. For a specific tool's exact wire and valid shapes, follow the
-`contract`/`describe` pointers; this page is the **meaning + next action**.
-
-Read `result.blocker` (refused) or `result.status`+`result.reason` (uncertain).
-`result.retryable` is advisory only — the family decides what to do.
-
-## 1. Write permission declined
-
-- `environment-write-disabled` — the environment profile has `writable:false`.
-  **Do not retry the same call.** Either the operator turns writes on in
-  `omc setup`, or the write is out of bounds. Zero wire was sent.
-- `production-confirmation-required` — the target is production and the call
-  omitted `confirmProduction:true`. If the human approved a production write,
-  re-send with `confirmProduction:true`; otherwise **stop**. Zero wire was sent.
-
-## 2. Boundary — the capability is not covered
-
-- `capability-out-of-coverage` — `result.citation` names the manifest entry and
-  its status (`blocked` / `unsupported` / `static-only`). **The refusal is the
-  answer.** Do not route around it with a lower-level tool; the boundary is the
-  same. If it should be covered, use `omc-capability-scouting`.
-- `version-family-evidence-missing` — no version evidence could be parsed at all;
-  writes fail closed. (A version that simply isn't 8.6 is **not** a refusal any
-  more: OMC is built on 8.6 but accepts other versions/product lines in
-  compatibility mode, surfacing a `versionNotice`; only truly absent evidence
-  still fails closed.) Verify the environment's version before retrying.
-
-## 3. Semantic preflight — the payload is malformed
-
-Refused **before any wire call**; fix the payload, don't retry as-is. The refusal
-usually carries `validation` entries to fix one by one.
-
-- `business-code-invalid`, `duplicate-field`, `duplicate-service`,
-  `dictionary-create-duplicate`, `app-create-duplicate`, `model-create-duplicate`
-- `field-*` family gates (unaccepted family, missing relation `relativeCode`,
-  child-table column that is itself a child table, OCR/ELECTRONIC_SIGN)
-- `form-layout-invalid`, `form-fieldcodes-unknown`, `form-html-render-invalid`
-- `rule-graph-validation-failed`, `rule-graph-*` (node-graph dry lint)
-- `datarule-options-invalid`, `datarule-property-not-published`, `datarule-duplicate-property-type`
-- `listview-*` (columns/buttons/sorts/gantt/presentation)
-- `configure-model-*`, `apply-changes-tool-not-atomic`, `apply-changes-step-failed`
-- `bizservice-*` (required field, name length, config invalid, category/dbconnpool)
-- `model-type-immutable`, `model-referenced-by`
-
-### 3b. A platform `errcode` is a SHAPE error, never a boundary
-
-`blocker:"wire-business"` + non-zero `errcode` means the payload's shape (or a
-referenced dependency) is wrong — **not** that the capability is unavailable.
-Fix the shape; never conclude 「配置表达不了 → 必须二开」 from an errcode.
-Known shape codes: `300010` a node resolves its input schema from `inputParam`
-and it is missing (BRANCH/UPDATE/CREATE/DELETE/ASSIGN/BIZ_ACTION/MESSAGE/QUERY;
-`prepareRuleGraph` defaults `"_input"`) or a node names a non-existent schema;
-`550018` a referenced field/out-param/mapping key is absent; `50000` a
-condition/expression/query shape is off. Compare against
-`omc describe <tool> --example …` and the node-graph prose, then re-save.
-Escalate to 二开 **only** for a real `capability-out-of-coverage` (§2).
-
-`40000 调用数据库发生异常` is the **most opaque** shape code — no detail at all.
-Line up the model's field-level config first: an `AGGREGATION` FORMULA field whose
-`aggregation.schemaCode` points at a **child-table schema** publishes fine and then
-makes every `data.submit`/`data.update` on that model 40000 (r18 2026-10-26 live;
-bisect by deleting/disabling the suspect formula field, which is reversible).
-`omc` now answers `runtime-write-db-exception` and lists the model's formula
-fields; the fix is to aggregate a MAIN-table scalar column instead.
-
-## 4. Readback mismatch — the write landed but does not match
-
-`*-readback-failed`, `*-readback-mismatch`, `cleanup-absence-readback`,
-`intent-readback-mismatch`, `workflow-render-readback-invalid`.
-
-**Stop and report.** Never auto-retry, never assume success. Inspect
-`result.readback` / `result.verification.differences`, compare against the
-approved draft, and decide with the human. A second write may duplicate.
-
-## 5. Dependency & async convergence
-
-- `model-referenced-by` — inbound relation references block the delete. Clean up
-  **dependency-inverted**: delete referencing models first, then the referenced
-  one.
-- `absent:false` + `treeNodePending:true` with `nextAction:"wait-and-recheck"` —
-  the platform's per-column cascade is still running (40–60s). **Not a failure.**
-  Wait ~60s and re-run; the call is idempotent and `already-absent` short-circuits.
-
-## 6. Idempotency & replay
-
-- A repeated `requestId` with identical args returns `replay:"already-completed"`
-  — the first write stands; treat as success, do not re-execute.
-- `intent-plan-tampered` — the plan file changed after planning. Re-run
-  `intent plan`.
-- `intent-baseline-drifted` — the environment moved after planning. Re-run
-  `intent plan` against the fresh baseline.
-- `intent-plan-environment-mismatch` — the plan targets a different environment.
-
-## 7. Transport uncertainty — outcome unknown
-
-`status:"uncertain"` with `frozen:true` (`cli-timeout`, `batch-timeout-budget`,
-`wire-transport:*`). The write **may** be in flight.
-
-1. Read back the affected resource (or `artifact get <id>` / the `requestId`).
-2. Only after the outcome is established, decide whether to retry.
-3. Never blind-retry — that risks a second write.
-
-`write-lock-held` — another write holds the environment lock; `owner` and
-`recovery` are included. Wait for it to clear (it auto-recovers when the holding
-process exits), then retry. This guards concurrency, not approval.
-
-## 8. Runtime / gateway errors (not tool refusals, same discipline)
-
-- `401 权限不够`（业务集成）→ 先查**前缀×鉴权**：`/openapi/**` 用 `xclient`，`/api/api/**` 用用户 token；混用必 401。对照同 adapter 既有成功服务（`service.get` 的方法 url）。
-- `500` 且仅 `X-LowCode-EngineCode should not be empty` → 补多租户头，不是业务错误。
-- `404 openresty` / `API 在服务端找不到` → url 层数不对（双层/三层 `/api`），按矩阵改一次，别反复试。
-- `position` 读回整数、写入枚举名 → 读侧编码，不是没写进去。
-- 版本证据缺失：先分 `pcServerUrl` 缺失（读取耦合，0.4.54 已修）与 `systemVersion` 真缺失（fail-closed 正确）；不要伪造 8.6。
-- `401/403` 且 body 是 HTML/空 → 网关层，不是业务拒绝；停手索要一条可运行样例，别继续改载荷。
-
-## 9. Input / target
-
-- `tool-input-invalid` — schema violation (exit 10); fix the arguments.
-- `dictionary-target-required`, `intent-plan-invalid` — a required selector or
-  shape is missing; see `describe <tool>`.
+---
+name: omc-refusals
+description: Decode a refused or uncertain OMC result. Use when a call returns refused/uncertain, or a status looks wrong, to find what the blocker means and the correct next action. Grouped by family, not enumerated per code.
+---
+
+# Refusals & Recovery (拒绝与恢复)
+
+Grouped by family. For a specific tool's exact wire and valid shapes, follow the
+`contract`/`describe` pointers; this page is the **meaning + next action**.
+
+Read `result.blocker` (refused) or `result.status`+`result.reason` (uncertain).
+`result.retryable` is advisory only — the family decides what to do.
+
+## 1. Write permission declined
+
+- `environment-write-disabled` — the environment profile has `writable:false`.
+  **Do not retry the same call.** Either the operator turns writes on in
+  `omc setup`, or the write is out of bounds. Zero wire was sent.
+- `production-confirmation-required` — the target is production and the call
+  omitted `confirmProduction:true`. If the human approved a production write,
+  re-send with `confirmProduction:true`; otherwise **stop**. Zero wire was sent.
+
+## 2. Boundary — the capability is not covered
+
+- `capability-out-of-coverage` — `result.citation` names the manifest entry and
+  its status (`blocked` / `unsupported` / `static-only`). **The refusal is the
+  answer.** Do not route around it with a lower-level tool; the boundary is the
+  same. If it should be covered, use `omc-capability-scouting`.
+- `version-family-evidence-missing` — no version evidence could be parsed at all;
+  writes fail closed. (A version that simply isn't 8.6 is **not** a refusal any
+  more: OMC is built on 8.6 but accepts other versions/product lines in
+  compatibility mode, surfacing a `versionNotice`; only truly absent evidence
+  still fails closed.) Verify the environment's version before retrying.
+
+## 3. Semantic preflight — the payload is malformed
+
+Refused **before any wire call**; fix the payload, don't retry as-is. The refusal
+usually carries `validation` entries to fix one by one.
+
+- `business-code-invalid`, `duplicate-field`, `duplicate-service`,
+  `dictionary-create-duplicate`, `app-create-duplicate`, `model-create-duplicate`
+- `field-*` family gates (unaccepted family, missing relation `relativeCode`,
+  child-table column that is itself a child table, OCR/ELECTRONIC_SIGN)
+- `form-layout-invalid`, `form-fieldcodes-unknown`, `form-html-render-invalid`
+- `rule-graph-validation-failed`, `rule-graph-*` (node-graph dry lint)
+- `datarule-options-invalid`, `datarule-property-not-published`, `datarule-duplicate-property-type`
+- `listview-*` (columns/buttons/sorts/gantt/presentation)
+- `configure-model-*`, `apply-changes-tool-not-atomic`, `apply-changes-step-failed`
+- `bizservice-*` (required field, name length, config invalid, category/dbconnpool)
+- `model-type-immutable`, `model-referenced-by`
+
+### 3b. A platform `errcode` is a SHAPE error, never a boundary
+
+`blocker:"wire-business"` + non-zero `errcode` means the payload's shape (or a
+referenced dependency) is wrong — **not** that the capability is unavailable.
+Fix the shape; never conclude 「配置表达不了 → 必须二开」 from an errcode.
+Known shape codes: `300010` a node resolves its input schema from `inputParam`
+and it is missing (BRANCH/UPDATE/CREATE/DELETE/ASSIGN/BIZ_ACTION/MESSAGE/QUERY;
+`prepareRuleGraph` defaults `"_input"`) or a node names a non-existent schema;
+`550018` a referenced field/out-param/mapping key is absent; `50000` a
+condition/expression/query shape is off. Compare against
+`omc describe <tool> --example …` and the node-graph prose, then re-save.
+Escalate to 二开 **only** for a real `capability-out-of-coverage` (§2).
+
+`40000 调用数据库发生异常` is the **most opaque** shape code — no detail at all.
+Line up the model's field-level config first: an `AGGREGATION` FORMULA field whose
+`aggregation.schemaCode` points at a **child-table schema** publishes fine and then
+makes every `data.submit`/`data.update` on that model 40000 (r18 2026-10-26 live;
+bisect by deleting/disabling the suspect formula field, which is reversible).
+`omc` now answers `runtime-write-db-exception` and lists the model's formula
+fields; the fix is to aggregate a MAIN-table scalar column instead.
+
+## 4. Readback mismatch — the write landed but does not match
+
+`*-readback-failed`, `*-readback-mismatch`, `cleanup-absence-readback`,
+`intent-readback-mismatch`, `workflow-render-readback-invalid`.
+
+**Stop and report.** Never auto-retry, never assume success. Inspect
+`result.readback` / `result.verification.differences`, compare against the
+approved draft, and decide with the human. A second write may duplicate.
+
+## 5. Dependency & async convergence
+
+- `model-referenced-by` — inbound relation references block the delete. Clean up
+  **dependency-inverted**: delete referencing models first, then the referenced
+  one.
+- `absent:false` + `treeNodePending:true` with `nextAction:"wait-and-recheck"` —
+  the platform's per-column cascade is still running (40–60s). **Not a failure.**
+  Wait ~60s and re-run; the call is idempotent and `already-absent` short-circuits.
+
+## 6. Idempotency & replay
+
+- A repeated `requestId` with identical args returns `replay:"already-completed"`
+  — the first write stands; treat as success, do not re-execute.
+- `intent-plan-tampered` — the plan file changed after planning. Re-run
+  `intent plan`.
+- `intent-baseline-drifted` — the environment moved after planning. Re-run
+  `intent plan` against the fresh baseline.
+- `intent-plan-environment-mismatch` — the plan targets a different environment.
+
+## 7. Transport uncertainty — outcome unknown
+
+`status:"uncertain"` with `frozen:true` (`cli-timeout`, `batch-timeout-budget`,
+`wire-transport:*`). The write **may** be in flight.
+
+1. Read back the affected resource (or `artifact get <id>` / the `requestId`).
+2. Only after the outcome is established, decide whether to retry.
+3. Never blind-retry — that risks a second write.
+
+`write-lock-held` — another write holds the environment lock; `owner` and
+`recovery` are included. Wait for it to clear (it auto-recovers when the holding
+process exits), then retry. This guards concurrency, not approval.
+
+## 8. Runtime / gateway errors (not tool refusals, same discipline)
+
+- `401 权限不够`（业务集成）→ 先查**前缀×鉴权**：`/openapi/**` 用 `xclient`，`/api/api/**` 用用户 token；混用必 401。对照同 adapter 既有成功服务（`service.get` 的方法 url）。
+- `500` 且仅 `X-LowCode-EngineCode should not be empty` → 补多租户头，不是业务错误。
+- `404 openresty` / `API 在服务端找不到` → url 层数不对（双层/三层 `/api`），按矩阵改一次，别反复试。
+- `position` 读回整数、写入枚举名 → 读侧编码，不是没写进去。
+- 版本证据缺失：先分 `pcServerUrl` 缺失（读取耦合，0.4.54 已修）与 `systemVersion` 真缺失（fail-closed 正确）；不要伪造 8.6。
+- `401/403` 且 body 是 HTML/空 → 网关层，不是业务拒绝；停手索要一条可运行样例，别继续改载荷。
+
+## 9. Input / target
+
+- `tool-input-invalid` — schema violation (exit 10); fix the arguments.
+- `dictionary-target-required`, `intent-plan-invalid` — a required selector or
+  shape is missing; see `describe <tool>`.

package/skills/omc-requirement-analysis.md

@@ -1,161 +1,161 @@
----
-name: omc-requirement-analysis
-description: Turn a fuzzy Chinese requirement into a platform-independent Configuration Intent. Use before discovery when the ask is vague or spans domains.
----
-
-# Requirement Analysis (需求分析)
-
-Turn a fuzzy Chinese requirement into a platform-independent **Configuration
-Intent** before any discovery, plan, or draft.
-
-This is reasoning, not a governed tool: it reads no environment, prints no
-credential, and writes nothing.
-
-**Leading word: 定面** — name the face. The same Chinese word names several
-OMC surfaces (规则, 表单, 字段, 集成, 在线, 数据). 定面 first; everything after
-depends on it. This word is shared with `omc-capability-scouting`.
-
-## Process
-
-Five moves, in order. Each ends on a completion criterion.
-
-### 1. 定面 — name the face
-
-For every noun in the requirement, assign exactly one OMC face from the 定面表.
-
-**Done when** every ambiguous noun carries exactly one face, and every noun
-with no face is marked a boundary.
-
-### 2. 归类 — capability and lane
-
-Map each face to its capability, lane, and status in the 能力表.
-
-**Done when** every face has a capability, its lane, and one status
-(`executable` / `partial` / `blocked` / `unsupported`).
-
-### 3. 选路 — implementation path
-
-Choose one path per behavior, in preference order: **native** →
-**configuration + Online JS** → **configuration + backend extension**.
-
-**Done when** each behavior carries a path, and every non-native path names
-the code owner and why native cannot carry it.
-
-### 4. 澄清 — risk-driven
-
-Ask only about unresolved details that change behavior, data, environment
-impact, or acceptance (see 澄清触发). A blocked or unsupported face is a
-**boundary** — stated, not asked. All other detail takes the established
-project convention.
-
-**Done when** the open-question list is emitted, or empty.
-
-### 5. 出意图 — emit Configuration Intent
-
-Emit the intent object (see Configuration Intent).
-
-**Done when** every field is populated and `nextStep` is set.
-
-## 定面表 — disambiguate before classifying
-
-| 需求里的词 | 面 A | 面 B | 判别 |
-| --- | --- | --- | --- |
-| 规则 | cross-model **businessrule** graph (B 平面) | 字段级控件规则 `dataRuleType` 3/4/5 | 跨模型/触发/动作 → businessrule；单字段随值必填/只读/显示 → 表单控件绑定 |
-| 表单 | default form **(`bizsheet`)** | list view **(`query`)** | 录入/详情/布局/控件 → default form；列表/视图/筛选列 → list view |
-| 字段 | model property **(`bizproperty`)** | form control binding | 结构/类型 → model field；可见/只读/必填 → form binding |
-| 集成 | B2 业务集成服务 **(`bizservice`,`service.register`)** | 方法体来源：原生适配器（RESTFUL→外部 API）/ 二开扩展接口（也用 RESTFUL 指向扩展端点） | 对接接口/外部系统、或需自定义 Java 方法体 → **一律用 RESTFUL 业务集成服务**（二开接口 = 扩展模块写 REST 接口 + RESTFUL 服务指向它）；自定义协议适配器 SPI 是「新增一种协议类型」，非常规、且不在工具支持面 |
-| 在线 | form **Online JS** | 在线后端编码 | 表单脚本 → Online JS；内联后端代码 → boundary (unsupported) |
-| 数据 | M2 runtime data | model/field 定义 | 记录读写 → M2 data；结构 → model/field |
-
-## 归类 — face → capability
-
-Each face maps to a capability; **read the capability's coverage, tools,
-recipes, and boundaries from `omc-capabilities`** — that catalogue is the prose
-authority (this section is a pointer, not a second copy). Read only the section
-you need: `omc help omc-capabilities --section "<能力>"`. At call time the
-coverage manifest is authoritative and the tool gate rejects out-of-coverage
-calls.
-
-> `blocked` / `unsupported` are **native-config** verdicts. They route the
-> behavior to another code owner (`config + backend extension`), they do NOT
-> mean the requirement is undeliverable. Compiling a blocked face into "can't
-> do it, leave it manual" is a failure mode — see 选路.
-
-Full Chinese cue vocabulary lives in `omc-requirement-vocabulary.md` — reach
-for it when a cue in step 1 is not obvious from 定面表.
-
-## 选路 — path rules
-
-> 落点判据（配置 vs 二开、组合观）的唯一权威源是 `cpdocs-guide` 的「落点」；本节只列 OMC 侧的落点执行。
-
-- **Native configuration** owns structure and lifecycle: models, fields,
-  forms, list views, rule graphs, workflow templates.
-- **Online JS** owns form interaction and presentation: visibility, labels,
-  field linkage, preview. It *previews* a computed value; the saved value
-  comes from native config or a backend extension.
-- **Backend extension** is the method-BODY source when native config cannot
-  express the logic. Expose it the normal way: **write an interface (a REST
-  endpoint) in the extension package, then register a `RESTFUL` service pointing
-  at it** (`service.register`, `adapterCode:RESTFUL`, `methodConfig.url` → the
-  extension endpoint). Do NOT use `INTERNAL` / `custom_protocol` adapters — those
-  are platform-internal protocol mechanisms, not the way a 二开 interface is
-  registered, and they are outside the write face. A RESTFUL service pointing at
-  an external API is the same face.
-- **Business-rule action dual path**: a rule's action nodes use product-native
-  CRUD/query nodes (no code) **or** bind an already-released BizMethod. Surface
-  both paths; the clarification decides.
-- **Cannot express declaratively ⇒ `config + backend extension`, do not stop** —
-  the code owner is a backend extension (interface in the extension package +
-  `RESTFUL` service + BIZ_ACTION/button binding). **Do not report "blocked" and
-  leave the value unbuilt, and do not substitute an external throwaway script.**
-
-## 澄清触发 — ask only when
-
-- the business domain is unknown, or a noun in 定面表 stays ambiguous;
-- money, cumulative values, or concurrency are involved;
-- the requirement is environment-impacting (上线 / 发布 / 生产 / 释放冻结);
-- two capabilities could satisfy it and the choice changes behavior.
-
-Proceed with the convention when the detail is cosmetic (label wording,
-layout polish) or already implied by an established project pattern.
-
-## Configuration Intent
-
-```jsonc
-{
-  "domains": ["customer", "project"],
-  "capabilities": ["model", "field", "form", "businessrule", "workflow"],
-  "intent": {
-    "entities": [{ "name": "…", "fields": [{ "name": "…", "type": "…" }] }],
-    "behaviors": [{ "trigger": "create|update|delete|button|system|timed|…", "action": "…" }],
-    "integrations": [{ "kind": "native-crud|bizmethod|b2-service", "target": "…" }]
-  },
-  "implementationPath": "native | config+onlinejs | config+backend-extension",
-  "risks": ["…"],
-  "clarifications": ["…"],
-  "acceptanceScenarios": ["…"],
-  "nextStep": "discover_and_plan | clarify | boundary"
-}
-```
-
-`clarify` whenever 澄清触发 fires; `boundary` when a face is out of coverage;
-otherwise `discover_and_plan`.
-
-## 反模式
-
-- Classifying a noun before 定面 — e.g. mapping 规则 to `dataRuleType` when a
-  cross-model graph was meant.
-- Treating 对接外部系统 as a cue to develop a custom protocol adapter SPI — that
-  is a rare NEW PROTOTYPE, not integration. The normal path is a
-  business-integration service (`service.register`).
-- Routing a saved value through Online JS.
-- Inventing a capability for a blocked face. Cite the boundary instead.
-- Emitting a plan or DTO payload here — intent stays platform-independent
-  until discovery.
-
-## 接续
-
-Intent feeds, in order: `discover_environment` (fingerprint + existing
-resources) → configuration baseline → `omc-five-piece-flow`. For a face not
-yet proven, use `omc-capability-scouting`. For the concrete tool to call, use
-`omc-tool-selection`.
+---
+name: omc-requirement-analysis
+description: Turn a fuzzy Chinese requirement into a platform-independent Configuration Intent. Use before discovery when the ask is vague or spans domains.
+---
+
+# Requirement Analysis (需求分析)
+
+Turn a fuzzy Chinese requirement into a platform-independent **Configuration
+Intent** before any discovery, plan, or draft.
+
+This is reasoning, not a governed tool: it reads no environment, prints no
+credential, and writes nothing.
+
+**Leading word: 定面** — name the face. The same Chinese word names several
+OMC surfaces (规则, 表单, 字段, 集成, 在线, 数据). 定面 first; everything after
+depends on it. This word is shared with `omc-capability-scouting`.
+
+## Process
+
+Five moves, in order. Each ends on a completion criterion.
+
+### 1. 定面 — name the face
+
+For every noun in the requirement, assign exactly one OMC face from the 定面表.
+
+**Done when** every ambiguous noun carries exactly one face, and every noun
+with no face is marked a boundary.
+
+### 2. 归类 — capability and lane
+
+Map each face to its capability, lane, and status in the 能力表.
+
+**Done when** every face has a capability, its lane, and one status
+(`executable` / `partial` / `blocked` / `unsupported`).
+
+### 3. 选路 — implementation path
+
+Choose one path per behavior, in preference order: **native** →
+**configuration + Online JS** → **configuration + backend extension**.
+
+**Done when** each behavior carries a path, and every non-native path names
+the code owner and why native cannot carry it.
+
+### 4. 澄清 — risk-driven
+
+Ask only about unresolved details that change behavior, data, environment
+impact, or acceptance (see 澄清触发). A blocked or unsupported face is a
+**boundary** — stated, not asked. All other detail takes the established
+project convention.
+
+**Done when** the open-question list is emitted, or empty.
+
+### 5. 出意图 — emit Configuration Intent
+
+Emit the intent object (see Configuration Intent).
+
+**Done when** every field is populated and `nextStep` is set.
+
+## 定面表 — disambiguate before classifying
+
+| 需求里的词 | 面 A | 面 B | 判别 |
+| --- | --- | --- | --- |
+| 规则 | cross-model **businessrule** graph (B 平面) | 字段级控件规则 `dataRuleType` 3/4/5 | 跨模型/触发/动作 → businessrule；单字段随值必填/只读/显示 → 表单控件绑定 |
+| 表单 | default form **(`bizsheet`)** | list view **(`query`)** | 录入/详情/布局/控件 → default form；列表/视图/筛选列 → list view |
+| 字段 | model property **(`bizproperty`)** | form control binding | 结构/类型 → model field；可见/只读/必填 → form binding |
+| 集成 | B2 业务集成服务 **(`bizservice`,`service.register`)** | 方法体来源：原生适配器（RESTFUL→外部 API）/ 二开扩展接口（也用 RESTFUL 指向扩展端点） | 对接接口/外部系统、或需自定义 Java 方法体 → **一律用 RESTFUL 业务集成服务**（二开接口 = 扩展模块写 REST 接口 + RESTFUL 服务指向它）；自定义协议适配器 SPI 是「新增一种协议类型」，非常规、且不在工具支持面 |
+| 在线 | form **Online JS** | 在线后端编码 | 表单脚本 → Online JS；内联后端代码 → boundary (unsupported) |
+| 数据 | M2 runtime data | model/field 定义 | 记录读写 → M2 data；结构 → model/field |
+
+## 归类 — face → capability
+
+Each face maps to a capability; **read the capability's coverage, tools,
+recipes, and boundaries from `omc-capabilities`** — that catalogue is the prose
+authority (this section is a pointer, not a second copy). Read only the section
+you need: `omc help omc-capabilities --section "<能力>"`. At call time the
+coverage manifest is authoritative and the tool gate rejects out-of-coverage
+calls.
+
+> `blocked` / `unsupported` are **native-config** verdicts. They route the
+> behavior to another code owner (`config + backend extension`), they do NOT
+> mean the requirement is undeliverable. Compiling a blocked face into "can't
+> do it, leave it manual" is a failure mode — see 选路.
+
+Full Chinese cue vocabulary lives in `omc-requirement-vocabulary.md` — reach
+for it when a cue in step 1 is not obvious from 定面表.
+
+## 选路 — path rules
+
+> 落点判据（配置 vs 二开、组合观）的唯一权威源是 `cpdocs-guide` 的「落点」；本节只列 OMC 侧的落点执行。
+
+- **Native configuration** owns structure and lifecycle: models, fields,
+  forms, list views, rule graphs, workflow templates.
+- **Online JS** owns form interaction and presentation: visibility, labels,
+  field linkage, preview. It *previews* a computed value; the saved value
+  comes from native config or a backend extension.
+- **Backend extension** is the method-BODY source when native config cannot
+  express the logic. Expose it the normal way: **write an interface (a REST
+  endpoint) in the extension package, then register a `RESTFUL` service pointing
+  at it** (`service.register`, `adapterCode:RESTFUL`, `methodConfig.url` → the
+  extension endpoint). Do NOT use `INTERNAL` / `custom_protocol` adapters — those
+  are platform-internal protocol mechanisms, not the way a 二开 interface is
+  registered, and they are outside the write face. A RESTFUL service pointing at
+  an external API is the same face.
+- **Business-rule action dual path**: a rule's action nodes use product-native
+  CRUD/query nodes (no code) **or** bind an already-released BizMethod. Surface
+  both paths; the clarification decides.
+- **Cannot express declaratively ⇒ `config + backend extension`, do not stop** —
+  the code owner is a backend extension (interface in the extension package +
+  `RESTFUL` service + BIZ_ACTION/button binding). **Do not report "blocked" and
+  leave the value unbuilt, and do not substitute an external throwaway script.**
+
+## 澄清触发 — ask only when
+
+- the business domain is unknown, or a noun in 定面表 stays ambiguous;
+- money, cumulative values, or concurrency are involved;
+- the requirement is environment-impacting (上线 / 发布 / 生产 / 释放冻结);
+- two capabilities could satisfy it and the choice changes behavior.
+
+Proceed with the convention when the detail is cosmetic (label wording,
+layout polish) or already implied by an established project pattern.
+
+## Configuration Intent
+
+```jsonc
+{
+  "domains": ["customer", "project"],
+  "capabilities": ["model", "field", "form", "businessrule", "workflow"],
+  "intent": {
+    "entities": [{ "name": "…", "fields": [{ "name": "…", "type": "…" }] }],
+    "behaviors": [{ "trigger": "create|update|delete|button|system|timed|…", "action": "…" }],
+    "integrations": [{ "kind": "native-crud|bizmethod|b2-service", "target": "…" }]
+  },
+  "implementationPath": "native | config+onlinejs | config+backend-extension",
+  "risks": ["…"],
+  "clarifications": ["…"],
+  "acceptanceScenarios": ["…"],
+  "nextStep": "discover_and_plan | clarify | boundary"
+}
+```
+
+`clarify` whenever 澄清触发 fires; `boundary` when a face is out of coverage;
+otherwise `discover_and_plan`.
+
+## 反模式
+
+- Classifying a noun before 定面 — e.g. mapping 规则 to `dataRuleType` when a
+  cross-model graph was meant.
+- Treating 对接外部系统 as a cue to develop a custom protocol adapter SPI — that
+  is a rare NEW PROTOTYPE, not integration. The normal path is a
+  business-integration service (`service.register`).
+- Routing a saved value through Online JS.
+- Inventing a capability for a blocked face. Cite the boundary instead.
+- Emitting a plan or DTO payload here — intent stays platform-independent
+  until discovery.
+
+## 接续
+
+Intent feeds, in order: `discover_environment` (fingerprint + existing
+resources) → configuration baseline → `omc-five-piece-flow`. For a face not
+yet proven, use `omc-capability-scouting`. For the concrete tool to call, use
+`omc-tool-selection`.