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）， 绝不伪造成功。

快速开始

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）。

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 个工具）

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

治理 / 元工具（5）

读工具（50）

能力总览（16 项）

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

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

近期能力（0.4.84 → 0.4.100）

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

写工具做什么

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

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

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

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 后再执行：

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 逃生舱。

其它命令

覆盖边界

• 随包 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（能力契约、治理原语、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。

npm 分发

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

使用已发布包

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，顺序不能反：

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/，可通过以下命令发现和读取方法论：

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、写租约和权威读回；浏览器不是常规验收步骤。