# @stalfh233/omc-cli 中文文档

规范地址：https://npmcn.com/package/%40stalfh233/omc-cli/

版本：0\.5\.15
npm 元数据更新时间：2026-11-02T12:20:39.730Z
中文译文更新时间：2026-11-02T13:32:53.672Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40stalfh233/omc-cli
原文对照：https://npmcn.com/package/%40stalfh233/omc-cli/?lang=original
源码仓库：https://gitlab.h3yun.com/fuwenbin/oh-my-cpagents

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.5 MB，208 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2026-10-10T10:01:32.154Z
- 最新版本发布：2026-11-02T12:20:39.591Z
- 已发布版本数：110（近 12 个月 110 个）

## 中文简介

CloudPivot 8.6配置能力CLI管理、故障关闭、覆盖清单有限。

## 安装

```sh
npm install @stalfh233/omc-cli
```

也可以使用：`pnpm add @stalfh233/omc-cli`、`yarn add @stalfh233/omc-cli`、`bun add @stalfh233/omc-cli`

## README

# omc-cli

把 CloudPivot 8.6 的配置能力封装为一个本地 **CLI**——受治理、失败即关闭（fail-closed），并以一份机器可读的覆盖清单为边界。

-   **一条 CLI 工具面**——高层编排（`configure_model` / `configure_form` / `configure_rule` / `apply_changes` / `discover_environment` / `get_status`）与低层原子工具共用同一条管道。
-   **对话人门 + 环境写权限**——真正的人门在对话层：执行变更前先讲清草稿、资源、逐条改动与清理并等待明确批准；机器侧只有环境 profile 的 `writable` 开关。只读环境零 wire 拒绝，允许写入环境直接执行。
-   **生产是高危标签**——`production:true` 不再禁止写入；生产写必须在每笔参数中带 `confirmProduction:true`，结果和审计工件记录 `productionConfirmed:true`。
-   **不再有令牌审批**——删除 `approval.request`、HMAC/TTL/指纹令牌、`selfApprove`、`OMC_CLI_SELF_APPROVE`、`--yes` 和交互 y/N。保留 dry-run、覆盖门、版本族门、写租约、权威读回和不确定性冻结。
-   **覆盖清单边界**——随包内置的 M1 清单即契约；超出覆盖范围的调用会拒绝并引用清单条目。非 8.6 版本族（以及缺少版本证据）的写操作失败即关闭。
-   **写租约**——同一环境内的并发写会串行化（进程内）。
-   **本地 dry-lint**——写前零 wire 拒绝坏形状，而不是写到环境才发现： **规则图**（路由必备 `points`/`routeCondition`/`matchType`、节点类型/取值枚举、 动态来源键位）、**业务编码**（模型 ≤26/字段 ≤28、lowerCamel|lower\_snake、 拒绝平台保留字）、**表单布局**（span 白名单、行宽 ≤24、整行独占、控件覆盖率）、 字段族门。违规返回结构化 `validation`，不猜不改。
-   **规则图自动规范化**——线性图缺坐标或节点重叠时，工具自动铺成平台标准单列 （x=327、158×40、y=36/116/196…），缺失路由坐标按节点**边中点**推导，缺失 `routeCondition`/`matchType` 补 `true`/`ANY`；已可渲染的布局与分支图原样保留 ——调用方无需手算几何。
-   **读面一步取值**——大结果落到 artifact 时，`omc call <tool> … --extract <path>` / `--extract-keys` 直接在**同一次调用**里取值，不必再跑一次 `artifact get`；路径支持 `.rules[code=Create].name` 这类数组选择器。
-   **脚本面可读写**——表单在线 JS（`onlinejs.get/compose`）与**按钮 JS** （`listview.get --buttonCode` / `listview.configure --buttonScripts`、 `form.get --buttonScripts` / `form.publish --buttonScripts`）都能一次读写， 不必翻 artifact、也不必重发整张按钮表。
-   **应用目录（分组）**——`folder.tree/create/update/delete` + `model.move`； 应用树是嵌套 `children`，读面已递归展平并给 `path`/`depth`。
-   **方法论即可读**——`skills/` 下的方法论通过 `omc help <topic>` 按需读取；agent 不必去翻仓库文件。
-   **一次调用就是答案（0.4.100）**——`omc help --search "<词>"` 跨全部 topic 全文检索、命中节正文内联（严禁自己 `--all | grep`）；`omc describe <tool>` 默认带 `firstCall` 最小可跑形状（上下文键占位符化并列入 missing，绝不冒充合法值）；`omc next "<目标>"` 首答只给一个可执行动作或一个问题（`firstAnswer`）；`omc commands --filter` 支持能力语言（聚合/字典/业务集成…），零命中回 ≤3 个最近候选。
-   **拒绝即教学**——写前拒绝信封自带「你错在哪、正确形状、同源配方命令、不要做什么」；平台/权限/环境类只给「先修什么」，不给注定失败的重试命令。
-   **复合写命令**——`omc submit-verify`（逐条提交 → 真实 id 读回 → 差异汇总）、`omc rule-save-enable`（保存成功才启用，回执回答「会不会真的运行」）、`omc workflow-update-publish`（显式合成最终模板：默认保留旧节点，`--confirm-replace` 才丢弃）。全部默认 dry-run、第一步失败立即停、不自动重试。
-   **凭据零回显**——凭据（0600 存储或环境变量）不会出现在任何输出、产物或错误里。
-   **不确定性语义**——传输失败时冻结（`status: "uncertain", frozen: true`）， 绝不伪造成功。

## 快速开始

```bash
omc setup && omc doctor && omc commands --json
```

配置入口是 `omc setup`；不确定从哪开始读 `omc help omc-start-here`（任务→topic 路线）， 被拒或状态异常读 `omc help omc-refusals`（拒绝族的含义与下一步）， 写入治理读 `omc help omc-config-draft-review`。

### 权威发现路线（静态/就绪分离）

随包 `skills/` 是方法论 topic 的**权威**副本；下游 cpdocs 快照只是镜像，不得当作第二真相源。 `help` / `commands` / `capabilities` 都返回同一份 `discovery` 投影（`authoritative`、 `route`、`readiness`、`distributedMirror`）。

```bash
omc capabilities                                  # 能力 nickname/id/lane/aliases/tools/commands 一张表
omc capability <id-or-alias> --executable         # 选中能力的完整执行包（离线，不接触环境）
omc contract <lane-from-the-capability>           # wire 契约 + 该能力路由
omc describe <tool-from-the-bundle>               # schema + recipe + 能力路由
omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实环境）
```

`commands --json` 是完整工具清单，每个 lane-bound 工具都带 `capability` 映射； `describe` 与 `contract` 重复所选能力路由，切换面不必再宽扫 topic 或契约。 `omc eval:discovery-comparison` 输出相对 ticket 01 基线的调用数/字节数对比。

## 工具面（142 个工具）

| 类别 | 数量 | 说明 |
| --- | --- | --- |
| 写工具 | 87 | 高层编排 5（`configure_*` + `apply_changes`）+ 低层原子写 82 |
| 读工具 | 50 | `*.list` / `*.get` / `*.load` / `*.tree` / `discover_environment` |
| 治理/元工具 | 5 | `get_status`、`doctor`、`coverage.manifest`、`setup.*` |

**全集与逐工具参数**：`omc commands --json`（name/lane/kind/requiredArgs/writeGate/timeout）、 `omc describe <tool>`（完整 schema + 可运行示例）。大结果自动落到 `detailFile` 工件， 只回计数/摘要；相同目标 fingerprint 的重复读返回 `unchanged`（带缓存命中信号）。

### 治理 / 元工具（5）

| 工具 | 作用 |
| --- | --- |
| `get_status` | 环境健康：连通性、登录、版本族、凭据库权限位、租约、覆盖摘要、写入姿态（`writable` / 是否生产 / 是否需 `confirmProduction` / 已移除配置键） |
| `doctor` | 只报告的健康链：配置文件 → 凭据 → 登录 → 8.6 版本族兼容 → 环境指纹 |
| `coverage.manifest` | 覆盖清单投影（能力基线的机器可读视图） |
| `setup.start` | 配置引导入口：返回待填字段与当前非密值 |
| `setup.commit` | 幂等提交环境配置（写 `omc.config.json` + 0600 凭据库），随后跑连通性+登录+版本族校验 |

### 读工具（50）

| 域（lane） | 工具 |
| --- | --- |
| 环境 `environment-governance` | `discover_environment`、`environment.fingerprint` |
| 应用 `app-management` | `app.list` |
| 应用目录 `app-tree-folders` | `folder.tree`（递归展平嵌套 `children`，给 `path`/`depth`；`foldersOnly` 只回目录） |
| 数据字典 `dictionary-management` | `dictionary.list`、`dictionary.type`、`dictionary.names`、`dictionary.get`、`dictionary.records`、`dictionary.parent`、`dictionary.classes` |
| 业务模型 `model-management` | `model.list`、`model.inspect`（一次拿全字段/表单/视图/规则/流程摘要） |
| 字段 `field-families` | `field.list` |
| 表单 `form-publish-chain` | `form.get`（紧凑面直接回 `formButtons`/`formButtonCodes`；`--buttonScripts` 回按钮 JS 原文与 sha） |
| 列表视图 `W1-list-view` | `listview.get`（`--buttonCode`/`--buttons` 直接回按钮 JS 的 `scriptData`/sha）、`listview.list` |
| 字段级规则 `G1-datarule` | `datarule.list` |
| 业务规则 `B1-businessrule` | `rule.list`、`rule.get` |
| 流程 / 待办 / 组织 `W7-S29-greenfield` | `workflow.get_draft`（每节点 `formButtons.enabled/disabled`）、`workflow.get_published`、`workflow.validate`、`workflow.instanceActivity`、`workitem.list`、`org.role.list`、`org.role.users`、`org.role.userScope`、`org.department.list`、`org.department.users`、`org.user.search`、`org.user.info`、`org.user.departments` |
| 在线脚本 `online-js` | `onlinejs.get`（草稿/发布面 `customScript` 原文 + SHA-256） |
| 运行数据 `M2-runtime-data` | `data.list`、`data.load` |
| 报表 `R1-report` | `report.tree`、`report.get`、`report.chartdata`、`report.datasource.list` |
| 业务集成 `B2-registration` | `service.list`、`service.get`、`method.get`、`service.category.list`、`service.dbconnpool.list`、`service.adapter_config`、`service.table_list`、`service.table_sql`、`service.export`、`service.check` |

## 能力总览（16 项）

`omc capabilities` 的静态快照；跑 `omc capabilities` / `omc capability <id>` 取实时投影。 「依赖」= `requires → precedes`，即能力之间的配置顺序。

| 能力 | 标题 | lane | 覆盖 | intent | 依赖 |
| --- | --- | --- | --- | --- | --- |
| `environment` | 环境治理 | `environment-governance` | executable | none | \- → - |
| `app` | 应用 | `app-management` | executable | none | \- → folder |
| `folder` | 应用目录（分组） | `app-tree-folders` | executable | none | app → - |
| `dictionary` | 数据字典 | `dictionary-management` | executable | none | \- → - |
| `model` | 业务模型 | `model-management` | executable | partial | \- → field, workflow |
| `field` | 字段（含子表、计算字段） | `field-families` | executable | partial | model → form, listview, datarule, businessrule, data |
| `form` | 默认表单 | `form-publish-chain` | executable | partial | field → onlinejs |
| `listview` | 列表视图 | `W1-list-view` | partial | partial | field → - |
| `datarule` | 字段级控件规则 | `G1-datarule` | partial | partial | field → - |
| `businessrule` | 业务规则（图形引擎，含定时任务） | `B1-businessrule` | executable | partial | field → rule-lifecycle |
| `rule-lifecycle` | 规则生命周期 | `S25-rule-lifecycle` | executable | none | businessrule → - |
| `workflow` | 流程模板 | `W7-S29-greenfield` | executable | partial | model → - |
| `onlinejs` | 表单在线 JS | `online-js` | executable | partial | form → - |
| `bizservice` | 业务集成 | `B2-registration` | executable | partial | \- → - |
| `report` | 报表 | `R1-report` | partial | partial | \- → - |
| `data` | 运行数据 | `M2-runtime-data` | executable | none | field → - |

-   **覆盖**：`executable` 全量可用；`partial` 有取证边界（见 `omc capability <id>` 的 notes）。
-   **intent**：`partial` 表示该能力可声明式（`omc intent`）覆盖一部分——通常 create/update； `none` 表示只走 `omc call`。删除类、方法面、分类/连接池等仍走 `omc call` 逃生舱。

## 近期能力（0.4.84 → 0.4.100）

| 版本 | 新增 / 修复 |
| --- | --- |
| 0.4.100 | **回合经济学批（r19–r20，同题面实测 184 调用/503KB → 84 调用/98KB）**：`omc help --search "<词>"` 全文检索（命中节正文内联，单节 >6KB 只给精确回放命令）；`describe` 默认带 `firstCall`（offline-valid 最小可跑形状，`executable === missing为空`）；`omc next` 首答 `firstAnswer`（ready=无占位符可跑 / needs-input=一个问题 / blocked=不伪造路径），`discover_environment` 退出 firstCommands 首位、章节指针 ≤1 且非通用草稿模板、输出 ≤4096B；`commands --filter` 语义检索（工具名/能力别名/配方/摘要，大小写与分隔符归一；零命中最小信封+≤3 候选；宽词按能力分组 ≤3.5KB）；拒绝即教学（拒绝信封自带正确形状+与 firstCall 同源的配方命令+不要做什么；平台/权限类只给先修什么）；三条复合写命令 `submit-verify` / `rule-save-enable` / `workflow-update-publish`（默认 dry-run、第一步失败立即停、合并语义显式）；`OMC_NO_USAGE=1` 计量隔离（读侧不受影响）；报表能力按裁决暂缓（报表类目标 boundary 首答；`/dashboard/v1/*` 502 教学「环境边界不要重试」；`report.create` 半成功显式警示+清理命令） |
| 0.4.99 | 聚合算法三态实测定案：`LARGE/SMALL` 必带 k（缺 → 50000 掩码）、`UNION` 的 `resultType` 只能 0/1；审批提交**顶层 `agree` 才有效**（`approval.agree/opinion` 被静默忽略且仍按通过处理——写前拒绝 + `approvalNote` 顶层参数）；聚合事件回算窗口 ≈3 分钟实测（`field.publish --force` 重置） |
| 0.4.98 | 聚合指向子表 schema 写前拒绝（会让目标模型整体 40000 无明细且匹配恒 0）；`40000` 裸掩码给排查解释（先疑字段级配置）；`omc next` 造数据场景路由 |
| 0.4.97 | 三个写前 gate：日期毫秒时间戳（落库 NULL）、单值关联传数组（50000）、更新时无 id 子表行按新增插入不判重（实测 2 行变 8 行）；跨模型聚合行为图谱（混用条件/多组 OR/COUNTIF/MAX/来源删除回算） |
| 0.4.96 | 聚合定案（反编译 1.1.25 运行版 jar）：`propertyType/operatorType/resultType` 等 `@JsonCreator get(int)` 枚举**只认整数码**（写名字 → 305003 掩码，CLI 自动转码）；同模型子表聚合是平台死路（`checkCycleOfAggregation:1032` 判环，`field.create` 接受、`field.publish` 炸）→ 写前拒绝；跨模型汇总配方 `formula-aggregation-cross-model`（DYNAMIC 条件两侧字段分属两模型、`queryConditions` 不能为空） |
| 0.4.95 | `omc compute` 诚实化：`datarule` type2（shortTextStitch）在 REST 路径**永不执行**（`CalculateHandler` 由 `forceExecuteCalculateRule` 门控、全库 0 调用方；门户「能算」是客户端 JS 求值器）——不再假装可配 |
| 0.4.94 | QUERY 输出不可寻址写前拒绝；`100005` 判「同 workItem 已提交」（永久，非时间窗） |
| 0.4.92 | `rule.run` 真门（此前是假成功）；custompage 八工具 |
| 0.4.89/90 | 修 0.4.88 DRAFT 实例回归；`/organization/department/tree` 深度 BFS（deptIds 只回直接子级）；组织树参与人解析按 `ouScope ∩ 发起人部门链`（全空=静默回退发起人 → 写前拒绝）；结构化 nextCommand |
| 0.4.88 | **`omc model-purge`**：一条命令按依赖倒序清掉一个模型（流程实例 → model.delete 级联带走流程/视图/字段/表单/规则）。这是 r12–r14 三次「脏沙盒幽灵故障」的根治——顺手修了它的死锁（视图最后一条不能删 306103 + 列表绑定流程 303024，所以不删流程、让模型级联）。另：ladder 的 **recipe 命令提到 firstCommands**（r14 抱怨「ladder 没给可直接跑的命令」）、recipe 增加 `aliases` 意图词、`listview.configure` 的拒绝恢复补上 `targetCode` 按 bindAction 的语义 |
| 0.4.87 | **r14 真机探针修复**：`workitem.list` 的 50000 **不再是无解题**——按 `participant` 走 JPA 查询端点（能查**别人**名下的待办、且不解析流程模板），全局搜索失败时回 `workitem-search-unavailable` 带成因与三条绕行；`workflow.delete` 的 402508 改 `workflow-has-instances` 并说明**不要改用 model.delete 绕过**；`model.delete` 在有未完结待办时回 `workflowWarning`（级联会留脏待办 → 全局待办搜索整页 NPE）。另修两个 composer 模板参数名写错（`form-default --value`→`--default`、`rule-when --rule`→`--on`），并加**模板 vs `--help` 自动校验测试** |
| 0.4.86 | **r13 真机探针修复**：`omc next` 增加 **composer 路由**（含建模型+字段/审批流/计算/条件规则/表单默认值 → 直接给出对应一条命令；读面仍走 ladder，条件分支流程仍走 recipe）——r13 读了文档里那行 `model-scaffold` 却仍调 26 次 `field.create`，说明「写进文档」不等于「能被发现」。`data.submit` 审批提交**写前校验身份**：非本人在办的待办直接回 `submit-workitem-not-mine`（带待办持有者 + 三条出路），不再让平台回一个 `40005 权限不足`让 agent 猜 |
| 0.4.84 | **回合数优化（从省字节转向省往返）**：新增 `omc model-scaffold`（一条命令建模型+N 字段+子表+发布+表单，先 dry-run 预检零写入）与 `omc call <tool> --args-list`（同工具 N 次、逐条执行、回汇总）。修三个真 bug：键名提示自相矛盾（`workflow.delete` 两边互指）、`--dry-run` 与真写对 NUMERICAL 判定不一致（两套真相）、`runToolCall` 的 dry-run 被判失败 |
| 0.4.83 | **r12 真机探针修正（最重要：文档纠错）**：字段计算规则（`datarule` type2）**由服务端在 `data.submit`/`data.update` 时计算并回填，且覆盖传入值**——此前 skills/describe 六处写的「API 不回填、服务端聚合需二开」是错的（旧证据只覆盖 `FORMULA(100)` 字段）。另：`omc compute` 新增 `--where "<子列> = <值>"`（编译 COUNTIF/SUMIF）并**拒绝无条件子表聚合**（`--allow-unfiltered` 显式放行）；`model.delete` 把「孤儿模型」死锁变成一次明确回答——先复查读缓存，仍存在则回 `model-orphaned-record` 并给平台侧出路 |
| 0.4.82 | **流程发起权限（40009）**：新增 `workflow.permissions` / `workflow.addPermission` / `workflow.removePermission`（`/workflow/list_permission`、`create_permission`、`delete_permission`，unitType 线上为枚举序号 1=部门 2=角色 3=用户）。`data.submit`/`data.save+workflowCode` 的 40009 现在直接回 `workflow-start-permission-denied`：带上该流程的权限行现状、两种成因（无权限行 / 发起人部门记录已失效）与可粘贴的修复命令，不再是「流程发起权限不足」五个字 |
| 0.4.81 | **r11 真机探针修复**：`rule.save` 对 `AGGREGATION` 规则节点**写前 fail-closed**（平台会存进去、运行时 50000，真实路径是 `omc compute`/datarule type2）；`omc next "统计子表行数"` 路由补 `datarule` 阶梯与 `field-compute-subtable-sum` 配方；`org.user.search` 省略关键字时**按部门树列全员**（平台 `wd` 不支持空串，此前只能枚举 0–9）；`omc artifact get --jq` 无值回键清单（不再 commander 报错）；`usage` 的 `faces` 纳入 `--jq/--summary/--keys/--path-only/--extract`（此前读面投影完全不记账） |
| 0.4.80 | **省 token 与用量账本**：`omc help <topic>` 默认只回节索引（约 1KB，含每节字节数），`--all` 才读整篇；`omc artifact get` 正文 >8KB 默认只回形状（`--full` 才整包）；`omc usage` 默认只回汇总（`byTool`/`redundancy`/`estimatedTokens`），`--records` 才展开；`omc script` 的**每行工具调用单独记账**（`script-call` + `parentId`）；未绑定环境的目录回落 `$OMC_CONFIG_HOME/usage/<cwd-hash>.jsonl` |
| 0.4.79 | README 对齐 0.4.79 实际工具面（142 工具 / 16 能力） |
| 0.4.78 | **按钮 JS 直接读写**：`listview.get --buttonCode/--buttons`、`listview.configure --buttonScripts`、`form.get --buttonScripts`、`form.publish --buttonScripts`，外加 `buttons[].script` 简写 |
| 0.4.77 | **应用目录（分组）**：`folder.tree/create/update/delete` + `model.move`（`bizmodels/update` 换 parentId，跨应用目录单独报错） |
| 0.4.76 | **读面一键取值**：`call --extract <path>`（可重复）/`--extract-keys`，省掉一次 `artifact get`；`form.draft fromReadback:true` 允许平台原样布局回写；`--jq` 支持数组选择器 `[code=X]` |
| 0.4.75 | 节点级事件 `workflow.bindRule {activityCode,nodeEvent}`；`workflow.update` merge 拓扑保护（边数收缩即拒）；`workflow.setButtons`；`rule.run` / `form.runButton`；表单按钮 `options.customButtonJson` |
| 0.4.74 | 组织写面 15 工具（角色组/角色/成员/管理范围/部门/用户） |

> **脚本面只有三处**：表单在线 JS（`onlinejs.*`）、按钮 JS（本轮补齐读写）、自定义页面 JS （`h_custom_page`，CLI 未覆盖）。**列表视图本身没有 JS 面**（`h_biz_query` 无脚本列）。

## 写工具做什么

写工具分三层用法，**全部走同一条受治理管道**。

### 1\. 高层编排（5 个，一次调用 = 一个变更包）

| 工具 | 作用 |
| --- | --- |
| `configure_model` | 建模型 → 建 1..N 个字段 → 模型级 `field.publish`，`publishForm:true` 时再 `form.draft` + `form.publish`，一步到达**结构可用形态**。字段族门逐字段在写入前拒绝。 |
| `configure_form` | 给模型配默认表单：`fieldCodes` 决定绑定哪些已发布字段（按序；省略=全量；未知 code 在建表前拒绝 `form-fieldcodes-unknown`），再发布。 |
| `configure_rule` | 保存并启用一条业务规则（graph 规则引擎）——委托 `rule.save` 的 upsert + `rule.enable`。 |
| `configure_workflow` | 建流程模板 → 写活动/路由 → 发布 → 绑定事件规则，一步到达可发起形态（节点级事件用 `workflow.bindRule {activityCode,nodeEvent}`）。 |
| `apply_changes` | **批量入口**：一次提交异构变更清单 `changes:[{tool,args}]`（只收低层原子写工具），按序执行、逐步权威读回、**首败即停**并报已完成步骤与失败点；每步传输超时按 `uncertain` 冻结。含**整批时间预算** `totalTimeoutMs`（缺省 8 分钟）：超预算即停并返回 `uncertain` + `progressFile` + `resumeFromIndex`，绝不盲重试。 |

### 2\. 低层原子写（82 个，按域）

| 域（lane） | 工具 |
| --- | --- |
| 模型 `model-management` | `model.create`、`model.update`（应用树节点改名补丁：bizSchemaCode/id/name/parentId 四键必需，modelType 恒拒）、`model.move`（换目录，只改菜单节点归属）、`model.setSummary`、`model.delete`、`model.deleteMany` |
| 应用目录 `app-tree-folders` | `folder.create`（省略 `parentId` = 顶层；同父同名默认拒）、`folder.update`（改名/挂载）、`folder.delete`（非递归，有子节点即拒） |
| 字段 `field-families` | `field.create`、`field.update`、`field.delete`、`field.publish`（模型级一次发布 + 逐字段读回比对） |
| 表单 `form-publish-chain` | `configure_form`、`form.draft`（`buttons`/`buttonScripts`/`fromReadback`）、`form.publish`（`buttons`/`buttonScripts`）、`form.runButton`（表单按钮执行，`runtime/form/executeCustomButton`） |
| 字段级规则 `G1-datarule` | `datarule.create`、`datarule.update`、`datarule.delete` |
| 业务规则图 `B1-businessrule` | `rule.save`、`rule.node.update` |
| 规则生命周期 `S25-rule-lifecycle` | `configure_rule`、`rule.enable`、`rule.disable`、`rule.disableMany`、`rule.delete`、`rule.run`（自定义规则手动执行/按钮验收） |
| 运行时数据 `M2-runtime-data` | `data.save`、`data.update`、`data.submit`、`data.delete` |
| 流程 / 组织 `W7-S29-greenfield` | `configure_workflow`、`workflow.create`、`workflow.update`、`workflow.publish`、`workflow.bindRule`（流程级 `handler` 或节点级 `activityCode+nodeEvent`）、`workflow.setButtons`（节点「表单操作」勾选）、`workflow.delete`；组织：`org.roleGroup.create/delete`、`org.role.create/update/delete`、`org.role.addUsers/removeUsers/setUserScope`、`org.department.create/update/delete`、`org.user.create/update/delete/transferDepartment` |
| 在线脚本 `online-js` | `onlinejs.compose`（表单在线 JS；平台模板保真 + SHA-256 读回） |
| 列表视图 `W1-list-view` | `listview.create`、`listview.configure`（`buttons[].script` / `buttonScripts` 直接写按钮 JS）、`listview.delete` |
| 应用 `app-management` | `app.create`、`app.update`、`app.delete` |
| 数据字典 `dictionary-management` | `dictionary.save`、`dictionary.status`、`dictionary.usage`、`dictionary.class.save`、`dictionary.class.delete` |
| 报表 `R1-report` | `report.create`、`report.update`、`report.configure`、`report.datasource.link`、`report.delete` |
| 后端服务注册 `B2-registration` | `service.register/update/delete/import`、`method.create/update/delete/test`、`service.category.create/update/delete`、`service.dbconnpool.create/update/delete` |
| 批量编排（lane-less） | `apply_changes` |

### 3\. 每个写调用都经过的治理管道

```
语义门（字段族 / 规则图 dry-lint / 业务编码 / 表单布局 / 各工具 preflight，零 wire 调用）
  → 覆盖门（清单声明；超界拒绝并引用条目）
  → 环境写入门（writable=false 拒绝；生产需 confirmProduction:true）
  → 会话 + 版本族门（缺版本证据即关闭）
  → dry-run / requestId 重放门
  → 写租约（同环境串行）
  → 执行 → 权威读回 → 交付工件（artifact）+ 中文人话 summary
```

> 人门在对话层，不在这条管道里：agent 必须先出草稿并取得用户明确批准，才发起 下列任何写入。机器管道只执行 writable 与生产 confirmProduction 检查。

-   **计划与结果同源**：计划卡显示「即将…」，回执显示「已…」，由 `human-summary.ts` 同一来源按真实参数生成；空转写报「无变更：原因」，不假装有变更。
-   **完整性字段不被摘要替代**：`performed` / `readback` / `deliveryState` / `artifactFingerprint` 始终在内，`summary` 是**并列新增**。
-   **失败即停**：批量在失败步停止，返回 `{status, steps(已完成), failedStep, blocker}`； 已完成步骤的效果真实存在，需善后时按 `steps` 清单处理。

## 声明式意图面（omc intent）

除 `omc call` 的一次一工具外，可用宣言式 YAML 描述一组变更，编译为**不可变 plan** 后再执行：

```bash
omc intent validate intent.yaml         # 离线语义校验（错误带 源行:列）
omc intent plan intent.yaml --env <env> # 读基线 → 编译 → plan（planHash 复核对象）
omc intent apply plan.json              # 基线 drift 门 + writable 检查 + 串行执行 + 默认读回等价确认
omc intent readback intent.yaml --env <env>  # 解码回 intent 形状做等价校验
```

-   顶层 `models[]` / `services[]`；各能力声明式覆盖程度见「能力总览」的 intent 列（`partial` = 覆盖 create/update 等一部分）。
-   **plan 不可变**：apply 前 plan 被改一字节即拒（`intent-plan-tampered`），plan 后环境漂移即拒（`intent-baseline-drifted`，重跑 `intent plan`）。
-   生产环境 apply 加 `--confirm-production`；`--dry-run` 预览，`--no-verify` 跳过最终读回等价确认。
-   未声明式覆盖的操作（删除类、方法面、分类/连接池等）仍走 `omc call` 逃生舱。

## 其它命令

| 命令 | 作用 |
| --- | --- |
| `omc artifact get <id> [--summary|--keys|--jq <path>|--full]` | 取回大读回的 `detailFile` 工件（0600，校验 sha256）。**正文超 8KB 默认只回形状**（`outline:true` + 顶层键与体积 + `keysCommand`/`fullCommand`）；`--jq`/`--keys`/`--summary` 定向取，`--full` 才整包 |
| `omc help <topic>` | 方法论 topic：**默认只回节索引**（`{heading, bytes}`，约 1KB）；`--section "<标题>"`（可重复/逗号多节/序号/唯一前缀）取正文；`--all` 取整篇 |
| `omc call <tool> … --extract <path>` | **一步取值**：在本次结果的 artifact 内解析路径并直接回值（可重复给多个路径）；`--extract-keys` 列顶层键与体积。路径支持 `.rules[code=Create].name` 这种数组选择器，免掉一次 `artifact get` |
| `omc setup [--list|--edit <env>|--remove <env>]` | 命名环境的增删改查 |
| `omc doctor [--environment <env>]` | 只报告的健康链 |
| `omc bench [--live-sample] [--env <env>]` | 工具面/wire 面的双面埋点跑分（离线 fake 或 live 采样） |
| `omc model-scaffold --code <c> --name <n> --fields '<json>'` | 一条命令建模型：模型 → N 字段（含 `subFields` 子表）→ 发布字段 → 发布表单。**先对每个字段跑 dry-run 预检**（零写入），有错一次报全；执行期幂等（已存在记 skipped） |
| `omc call <tool> --args-list '<json array>'` | 同一工具跑 N 次、一个进程：逐条执行、默认不中断，回 `succeeded`/`failed` 汇总；失败只列 `failures[]`（带 index），成功不回包。省掉手写 ndjson |
| `omc model-purge --code <c> [--purge-instances] --apply` | 一条命令按依赖倒序清掉模型：**流程实例 → model.delete 级联带走**流程模板/列表视图/字段/表单/规则。默认 dry-run；有实例不删时会 `blocked` 并说明为何不能改用 model.delete 绕过 |
| `omc usage [--top <n>] [--records]` | 用量账本：默认只回汇总（调用数/字节/`redundancy` 重复浪费/`byTool` 排名/`estimatedTokens`≈字节/4）；`--records` 才回原始记录。数据源 `.omc/usage.jsonl`（每条 `omc` 调用一行，`omc script` 的每行工具调用另记 `script-call`，带 `parentId`） |
| `npm run eval:discovery-cost --workspace omc-cli` | 三组离线 discovery 成本基线（调用次数、stdout 字节、拒绝/重试、CloudPivot 写入） |

## 覆盖边界

-   随包 `coverage/m1-coverage-manifest-v1.json` 是能力契约；工具面受其约束，超界调用 拒绝并引用条目。
-   **永久不支持**：应用发布 / 环境级发布、CloudPivot 在线后端内联编码、 OCR/电子签字段族。
-   后端逻辑来自二开扩展包，经受治理发布后经 `BizMethodMapping` 服务注册表消费。

## 目录结构

```
coverage/   m1-coverage-manifest-v1.json（能力基线）
skills/     13 篇方法论 topic —— 以 `omc help <topic>` 暴露（见「方法论 topics」）
docs/       tool-surface-map.md —— 工具面地图
src/        args/support/plan/read/write/package/context（治理管道）
            lanes/（各域适配器）· fake/（离线夹具）
```

依赖 [`omc-core`](https://npmcn.com/package/%40stalfh233/omc-core)（能力契约、治理原语、wire 解码器——零 DSH 依赖， 由 CI 强制）。

## 在什么目录运行

把本 CLI 当**工具**用，请在**独立、干净的项目目录**里运行，而不要放在 OMC 的 研发仓库里。工具描述是自包含的（字段族、关联 `options`、规则 `nodeGraph`、 工作流 `template`、`formData` 与写入治理都已在工具 schema 与描述里声明）， 因此只看到工具的 agent 不需要去读仓库文件。

如果 agent 在 OMC 研发仓里启动，它可能读到只属于研发的产物——`.scratch/` 历史、 `CONTEXT.md`、既有的业务域 spec 与驱动脚本——并误当成使用指引。请优先选择一个只包含本包与目标项目的目录。

## 方法论 topics

`skills/` 随包分发，用 `omc help <topic>` 读取（等价 `git help <concept>`）。 首触路线与"任务→topic"映射见 `omc help omc-start-here`。

| topic | 用途 |
| --- | --- |
| `omc-start-here` | 首触命令阶梯 + 任务→topic 路线（router） |
| `omc-capabilities` | **能力总表**：每个能力能做哪些事、工具、recipe、边界（"能不能做 X"先读它） |
| `omc-config-draft-review` | 写前草稿确认：对话人门协议（**任何写前必读**） |
| `omc-five-piece-flow` | 治理变更五阶段：发现→草稿→权限→执行→读回清理 |
| `omc-tool-selection` | 目标 → 工具：何时用高层编排、何时落到原子 |
| `omc-refusals` | 拒绝/不确定族的含义与下一步（按族，不逐码） |
| `omc-write-hazards` | 底层写面安全形状（表单/视图/按钮/子表/关联/规则/在线 JS） |
| `omc-business-configuration` | 中文业务配置 runbook（需求维度 → 落地） |
| `omc-requirement-analysis` | 模糊中文需求 → 平台无关的 Configuration Intent |
| `omc-requirement-vocabulary` | 中文线索词 → 能力 lookup |
| `omc-capability-scouting` | 覆盖清单之外的新能力如何诚实取证 |
| `omc-acceptance-criteria` | 验收门：读回、交付态、零残留、反例基线 |
| `omc-glossary` | 术语：环境指纹、覆盖清单、交付态、Void envelope、结果状态 |

## npm 分发

本包（`@stalfh233/omc-cli`，可执行命令仍是 `omc`）通过公共 npm registry 分发。`omc-core` 是 `omc-cli` 的内部依赖，发布时先发 `omc-core`，再发 `omc-cli`；两者版本保持一致。当前版本为 `0.4.78`，尚未宣称 `1.0.0` 稳定契约。

### 使用已发布包

```bash
npm install -g @stalfh233/omc-cli@latest
omc setup
omc doctor
omc help omc-write-hazards
omc help omc-business-configuration
```

### 发布新版本

发布在开发机执行，必须先 `omc-core` 后 `omc-cli`，顺序不能反：

```bash
npm run verify
npm publish --workspace omc-core
npm publish --workspace packages/omc-fake-platform
npm publish --workspace packages/omc-cli
```

`omc-core` 与 `omc-cli` 版本保持一致；发布前先用 `git tag vX.Y.Z` 记录该版本。新包首次发布进入 npm staged-publishing 审核队列，需维护者在 npmjs.com 用交互式 2FA 批准后真实版本才可见。

### 输出编码

stdout 是机器解析的 JSON，编码按消费方选择：**终端**（`isTTY`）写原始 UTF-8（Windows 上 Node 走 `WriteConsoleW`，中文正常显示）；**管道/重定向/捕获**写 ASCII 安全 JSON（非 ASCII 转义成 `\uXXXX`，任何代码页都能正确解析，等价于 Python `json.dumps(ensure_ascii=True)`）。Linux/macOS 始终原始 UTF-8；`--out` 文件、artifact、stderr、CloudPivot 请求体始终原始 UTF-8。强制用 `OMC_ASCII_STDOUT=1|0`。

### 版本策略

-   `0.4.x`：继续演进 CLI/覆盖清单/配置契约，允许新增能力和必要的行为修复。
-   `1.0.0`：等 CLI 面、intent 面、覆盖清单和分发安装流程稳定后再发布；发布前应增加迁移说明和兼容性检查。

### 分发后自检

新会话不需要依赖本仓库的 `AGENTS.md`。安装包内置 `skills/`，可通过以下命令发现和读取方法论：

```bash
omc commands --json
omc help
omc help omc-start-here
omc help omc-write-hazards
omc help omc-business-configuration
omc help omc-refusals
omc describe <tool>
omc contract <lane>
```

CLI 自己执行 dry-lint、覆盖清单、writable/production confirmation、写租约和权威读回；浏览器不是常规验收步骤。

## 常见问题

### @stalfh233/omc-cli 是什么？

CloudPivot 8\.6配置能力CLI管理、故障关闭、覆盖清单有限。

### 如何安装 @stalfh233/omc-cli？

在项目目录运行 npm install @stalfh233/omc-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 omc，可以用 npx omc 直接运行。

### @stalfh233/omc-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/stalfh233\_\_omc-cli 是否存在。

### @stalfh233/omc-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @stalfh233/omc-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @stalfh233/omc-cli 可以商用吗？

@stalfh233/omc-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @stalfh233/omc-cli 还在维护吗？

最新版本 0\.5\.15 发布于 2026/11/02（1 天前）；至今共发布 110 个版本，其中过去 12 个月发布了 110 个；首次发布于 2026/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。