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

| 类别 | 数量 | 说明 | |---|---|---| | 写工具 | 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） | | 后端在线开发 programming-online-dev | programming.schemas、programming.sources、programming.get、programming.compile、programming.save、programming.publish（另配 omc programming pull/status/apply/adopt/test 文件级工作区） | | 运行数据 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 |

能力总览（17 项）

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 → - | | programming | 后端在线开发（业务规则 Java 源码） | programming-online-dev | executable | none | businessrule → - | | 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 后再执行：

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（能力契约、治理原语、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 稳定契约。

使用已发布包

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