@stalfh233/omc-cli 0.5.6 → 0.5.8

package/skills/omc-tool-selection.md

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