@stalfh233/omc-cli 0.4.78 → 0.4.80

package/README.md

@@ -18,6 +18,15 @@
   （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 不必去翻仓库文件。
 - **凭据零回显**——凭据（0600 存储或环境变量）不会出现在任何输出、产物或错误里。
 - **不确定性语义**——传输失败时冻结（`status: "uncertain", frozen: true`），
@@ -51,12 +60,12 @@ omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实
 `describe` 与 `contract` 重复所选能力路由，切换面不必再宽扫 topic 或契约。
 `omc eval:discovery-comparison` 输出相对 ticket 01 基线的调用数/字节数对比。
 
-## 工具面（90 个工具）
+## 工具面（142 个工具）
 
 | 类别 | 数量 | 说明 |
 |---|---|---|
-| 写工具 | 56 | 高层编排 4（`configure_*` + `apply_changes`）+ 低层原子写 52 |
-| 读工具 | 29 | `*.list` / `*.get` / `*.load` / `discover_environment` |
+| 写工具 | 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）、
@@ -73,22 +82,27 @@ omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实
 | `setup.start` | 配置引导入口：返回待填字段与当前非密值 |
 | `setup.commit` | 幂等提交环境配置（写 `omc.config.json` + 0600 凭据库），随后跑连通性+登录+版本族校验 |
 
-### 读工具（29）
+### 读工具（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` |
+| 表单 `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`、`workflow.get_published`、`workitem.list` |
+| 流程 / 待办 / 组织 `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` |
-| 业务集成 `B2-registration` | `service.get`、`method.get`、`service.category.list`、`service.dbconnpool.list`、`service.adapter_config`、`service.table_list`、`service.table_sql`、`service.export`、`service.check` |
+| 报表 `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` |
 
-## 能力总览（14 项）
+## 能力总览（16 项）
 
 `omc capabilities` 的静态快照；跑 `omc capabilities` / `omc capability <id>` 取实时投影。
 「依赖」= `requires → precedes`，即能力之间的配置顺序。
@@ -96,53 +110,75 @@ omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实
 | 能力 | 标题 | lane | 覆盖 | intent | 依赖 |
 |---|---|---|---|---|---|
 | `environment` | 环境治理 | `environment-governance` | executable | none | - → - |
-| `app` | 应用 | `app-management` | 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 |
+| `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 |
+| `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.74 → 0.4.80）
+
+| 版本 | 新增 / 修复 |
+|---|---|
+| 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. 高层编排（4 个，一次调用 = 一个变更包）
+### 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. 低层原子写（52 个，按域）
+### 2. 低层原子写（82 个，按域）
 
 | 域（lane） | 工具 |
 |---|---|
-| 模型 `model-management` | `model.create`、`model.update`（应用树节点改名补丁：bizSchemaCode/id/name/parentId 四键必需，modelType 恒拒——类型创建时固化）、`model.setSummary`（数据标题/摘要模板）、`model.delete`、`model.deleteMany`（一次 `physically_delete` 请求批量删；逐目标引用预检、被引用整批拒绝零副作用、逐模型缺席轮询；跨应用自动解析 AppFunction id） |
-| 字段 `field-families` | `field.create`、`field.update`、`field.delete`、`field.publish`（模型级一次发布；发布后逐字段读 `bizproperty/get` 比对 name/propertyType，与草稿面不一致即拒绝——不只查发布列表存在性） |
-| 表单 `form-publish-chain` | `form.draft`、`form.publish` |
+| 模型 `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` / `S25-rule-lifecycle` | `rule.save`、`rule.enable`、`rule.disable`、`rule.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` | `workflow.create`、`workflow.update`、`workflow.publish`、`workflow.bindRule`（支持 `ruleCodes[]` 一次绑多规则，MERGE 语义）、`workflow.delete` |
-| 在线脚本 `online-js` | `onlinejs.compose`（唯一工具；平台模板保真，SHA-256 读回）。后端的「在线开发」（`/api/api/programming` Java 源码）用二开扩展包，不在本 CLI 范围 |
-| 列表视图 `W1-list-view` | `listview.create`、`listview.configure`、`listview.delete`（列/排序/筛选字段引用可给 **propertyCode 或字段显示名**，唯一匹配自动解析，歧义或不存在则拒绝，不静默跳过） |
+| 流程 / 组织 `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`（字典/记录 upsert，KEY_VALUE/TREE）、`dictionary.status`（启停字典或记录）、`dictionary.usage`（批量 `initialUsed`）、`dictionary.class.save`、`dictionary.class.delete` |
-| 后端服务注册 `B2-registration` | `service.register`、`service.update`、`service.delete`、`method.update`、`method.delete`、`method.test`、`service.import`、`service.category.create`、`service.category.update`、`service.category.delete`、`service.dbconnpool.create`、`service.dbconnpool.update`、`service.dbconnpool.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. 每个写调用都经过的治理管道
 
@@ -186,10 +222,13 @@ omc intent readback intent.yaml --env <env>  # 解码回 intent 形状做等价
 
 | 命令 | 作用 |
 |---|---|
-| `omc artifact get <id>` | 取回大读回的 `detailFile` 工件（0600，校验 sha256） |
+| `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 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 写入） |
 
 ## 覆盖边界
@@ -204,7 +243,7 @@ omc intent readback intent.yaml --env <env>  # 解码回 intent 形状做等价
 
 ```
 coverage/   m1-coverage-manifest-v1.json（能力基线）
-skills/     12 篇方法论 topic —— 以 `omc help <topic>` 暴露（见「方法论 topics」）
+skills/     13 篇方法论 topic —— 以 `omc help <topic>` 暴露（见「方法论 topics」）
 docs/       tool-surface-map.md —— 工具面地图
 src/        args/support/plan/read/write/package/context（治理管道）
             lanes/（各域适配器）· fake/（离线夹具）
@@ -246,7 +285,7 @@ src/        args/support/plan/read/write/package/context（治理管道）
 
 ## npm 分发
 
-本包（`@stalfh233/omc-cli`，可执行命令仍是 `omc`）通过公共 npm registry 分发。`omc-core` 是 `omc-cli` 的内部依赖，发布时先发 `omc-core`，再发 `omc-cli`；两者版本保持一致。当前版本为 `0.4.36`，尚未宣称 `1.0.0` 稳定契约。
+本包（`@stalfh233/omc-cli`，可执行命令仍是 `omc`）通过公共 npm registry 分发。`omc-core` 是 `omc-cli` 的内部依赖，发布时先发 `omc-core`，再发 `omc-cli`；两者版本保持一致。当前版本为 `0.4.78`，尚未宣称 `1.0.0` 稳定契约。
 
 ### 使用已发布包
 
@@ -264,7 +303,8 @@ omc help omc-business-configuration
 
 ```bash
 npm run verify
-npm publish --workspace packages/omc-core
+npm publish --workspace omc-core
+npm publish --workspace packages/omc-fake-platform
 npm publish --workspace packages/omc-cli
 ```
 
@@ -276,7 +316,7 @@ stdout 是机器解析的 JSON，编码按消费方选择：**终端**（`isTTY`
 
 ### 版本策略
 
-- `0.2.x`：继续演进 CLI/覆盖清单/配置契约，允许新增能力和必要的行为修复。
+- `0.4.x`：继续演进 CLI/覆盖清单/配置契约，允许新增能力和必要的行为修复。
 - `1.0.0`：等 CLI 面、intent 面、覆盖清单和分发安装流程稳定后再发布；发布前应增加迁移说明和兼容性检查。
 
 ### 分发后自检

package/dist/cli.js

@@ -14,7 +14,7 @@ import { readArgsFile, readStdinArgs, runToolCall, validateAgentPaths } from "./
 import { environmentWritable, requiresProductionConfirmation } from "./environment-policy.js";
 import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, requestId } from "./cli-contract.js";
 import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "./cli-output.js";
-import { beginUsage, completeUsage, recordUsageOutput, usageReport } from "./usage-log.js";
+import { beginUsage, completeUsage, ensureProjectIgnore, recordUsageOutput, usageReport } from "./usage-log.js";
 import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
 import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "./artifacts.js";
 import { projectJsonPath, projectResultExtract } from "./path-projection.js";
@@ -36,7 +36,7 @@ import { absencePointer } from "./capability-absences.js";
 import { intentConfigRoot, readIntentFile, validateIntentText } from "./intent/cli.js";
 import { intentSchemaBlock, intentExample, intentExampleIds } from "./intent/schema.js";
 import { planIntent, readbackIntent, applyIntent, intentWarnings } from "./intent/plan-apply.js";
-import { listSkills, readSkill, readSkillSection } from "./skills.js";
+import { listSkills, readSkill, readSkillOutline, readSkillSection } from "./skills.js";
 import { parseToolInput, ToolInputError } from "./tool-types.js";
 import { WireError, wireCall } from "./wire.js";
 import { ENDPOINTS } from "./endpoints.js";
@@ -115,8 +115,17 @@ async function cmdSetup(store, args) {
     if (username && password)
         store.writeCredential(name, { username, password });
     const bind = (await ask("将本项目（.omc-env）绑定到该环境？[y/N]：")).toLowerCase() === "y";
-    if (bind)
+    if (bind) {
         store.bindProjectEnvironment(name);
+        // Binding opts the directory into `.omc/` (artifacts + usage log), so keep
+        // that directory out of version control. Only an existing .gitignore is
+        // touched: creating VCS files unasked is worse than one warning line.
+        const ignore = ensureProjectIgnore();
+        if (ignore === "appended")
+            console.error("已把 .omc/ 追加到 .gitignore（用量账本与产物不纳入版本控制）");
+        else if (ignore === "no-gitignore")
+            console.error("提示：本项目没有 .gitignore；建议添加一行 .omc/（否则 .omc/ 的用量账本可能被提交）");
+    }
     console.error(`环境 ${name} 已保存（幂等，可随时重跑 omc setup）。凭据存储模式：${store.credentialsMode()}`);
     console.error(`安全建议：优先使用专用集成账号（只读+目标应用写权限）而非系统管理员账号；密码仅存于本机 ~/.config/omc/credentials（0600），请勿在对话或文档中传递。`);
     return 0;
@@ -460,6 +469,12 @@ function parseDurationMs(text) {
     const factor = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : unit === "d" ? 86_400_000 : 604_800_000;
     return amount * factor;
 }
+/**
+ * Above this size `omc artifact get` returns the outline, not the body. The
+ * transport cap (64 KB) is far too generous for a working context: one 27 KB
+ * template re-read three times is 81 KB of the session.
+ */
+const ARTIFACT_INLINE_CEILING_BYTES = 8192;
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes}B`;
@@ -531,14 +546,37 @@ async function cmdArtifactGet(id, transport, options = {}) {
         }
         // r6-onboarding 2026-10-21: 47 artifact fetches, 0 used a projection; the 10
         // large ones (up to 55 KB) pulled whole workflow templates just to read one
-        // nested key. Nudge once, in the same response, instead of hoping the hint
-        // in `fetch` is noticed.
-        const unprojected = artifact.content.length > 8192
-            ? { hint: `artifact ${Math.round(artifact.content.length / 1024)}KB 已整包返回。只要其中一段时用 --jq '<path>'（或 --summary 看形状、--keys 取顶层键），不要把整包带进上下文。` }
-            : {};
-        const result = { status: "ok", artifactId: id, sha256: artifact.sha256, content, ...unprojected };
+        // nested key. Round 10 still spent 247 KB (22.7% of the session) on 28
+        // `artifact get` calls, re-fetching 10–27 KB bodies — the nudge below was
+        // advisory and did not change behaviour.
+        //
+        // 0.4.80: shape first, the same rule as `omc help`. Above the inline ceiling
+        // the default is the outline (top-level keys + their sizes) plus runnable
+        // projections; `--full` returns the whole body exactly as before. Explicit
+        // projections (--summary/--keys/--jq/--path-only) are handled above and are
+        // never affected.
+        if (options.full !== true && artifact.content.length > ARTIFACT_INLINE_CEILING_BYTES) {
+            const record = content && typeof content === "object" && !Array.isArray(content) ? content : undefined;
+            const keys = record
+                ? Object.entries(record)
+                    .map(([key, value]) => ({ key, bytes: Buffer.byteLength(JSON.stringify(value) ?? "null", "utf8"), kind: Array.isArray(value) ? `array[${value.length}]` : value === null ? "null" : typeof value }))
+                    .sort((left, right) => right.bytes - left.bytes)
+                : [];
+            return emitTransportResult({
+                status: "ok",
+                artifactId: id,
+                sha256: artifact.sha256,
+                bytes: artifact.content.length,
+                outline: true,
+                ...(record ? { keys } : { kind: typeof content }),
+                hint: `正文 ${Math.round(artifact.content.length / 1024)}KB 超过内联上限 ${ARTIFACT_INLINE_CEILING_BYTES}B，本次只回形状（顶层键 + 体积）。要某几个键：--keys <a,b>；要某个路径：--jq '<path>'（支持 .rules[code=Create].name 这类数组选择器）；确实需要整包：--full。`,
+                keysCommand: keys.length > 0 ? `omc artifact get ${id} --keys ${keys.slice(0, 3).map((entry) => entry.key).join(",")}` : `omc artifact get ${id} --summary`,
+                fullCommand: `omc artifact get ${id} --full`,
+            }, transport);
+        }
+        const result = { status: "ok", artifactId: id, sha256: artifact.sha256, content };
         if (Buffer.byteLength(JSON.stringify(result), "utf8") > transport.maxOutputBytes)
-            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, ...unprojected, fetch: artifactFetchHint(id) }, transport);
+            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, fetch: artifactFetchHint(id) }, transport);
         return emitTransportResult(result, transport);
     }
     catch (error) {
@@ -692,8 +730,8 @@ function cmdDiscovery(kind, transport, value, options = {}) {
     }
     return emitTransportResult({ status: "ok", ...result }, transport);
 }
-function cmdUsage(transport) {
-    return emitTransportResult(usageReport(), transport);
+function cmdUsage(transport, options = {}) {
+    return emitTransportResult(usageReport(undefined, { records: options.records === true, top: options.top, resolveLikeWriter: true }), transport);
 }
 /**
  * Round 3, module A — `omc next "<goal>"`: the goal → route solver. Read-only,
@@ -853,7 +891,7 @@ function cmdIntentSchema(transport, example, exampleRequested) {
  * like `git help <concept>`. The command list is the "what"; these topics are
  * the "how".
  */
-function cmdHelp(topic, commandNames, transport, section, sections = false) {
+function cmdHelp(topic, commandNames, transport, section, sections = false, all = false) {
     const topics = listSkills();
     const commands = [...commandNames].sort();
     // Several sections in one call: `--section a --section b` or `--section a,b`.
@@ -943,8 +981,31 @@ function cmdHelp(topic, commandNames, transport, section, sections = false) {
         console.error(`help: ${message}`);
         return emitInvalid(transport, { message });
     }
-    console.error(`omc help ${document.name}`);
-    return emitTransportResult({ status: "ok", topic: document }, transport);
+    if (all) {
+        console.error(`omc help ${document.name} --all（${Buffer.byteLength(document.content, "utf8")} B）`);
+        return emitTransportResult({ status: "ok", topic: document }, transport);
+    }
+    // Shape first. Round 10 paid 35,872 B per full read of one topic, seven times
+    // in a single session, to use one or two headings. The index names every
+    // heading AND its price, so the caller can pick a section (or ask for --all)
+    // instead of buying the whole document by default.
+    const outline = readSkillOutline(topic);
+    if (outline === undefined)
+        return emitInvalid(transport, { message: `未知 topic "${topic}"；先用 omc help topics 查看可用 topic` });
+    console.error(`omc help ${topic}：${outline.sections.length} 节 / 全文 ${outline.bytes} B（默认只回索引；--section 取正文，--all 取全文）`);
+    return emitTransportResult({
+        status: "ok",
+        topic: outline.document.name,
+        bytes: outline.bytes,
+        sectionCount: outline.sections.length,
+        // Each section carries its price inline. `{"heading":"入口","bytes":282}`
+        // is cheaper than parallel arrays and reads better than a heading→bytes map;
+        // the heading names are what `--section` accepts.
+        sections: outline.sections.map((entry) => ({ heading: entry.heading, bytes: entry.bytes })),
+        hint: "默认只回节索引：先按各节 bytes 挑要读的节，再用 --section 取正文（可重复或逗号一次多节，也可用节序号或唯一前缀）。确需整篇才 --all。",
+        sectionCommand: `omc help ${outline.document.name} --section "<heading>"`,
+        fullCommand: `omc help ${outline.document.name} --all`,
+    }, transport);
 }
 /**
  * The text every agent should see when it lands on `omc --help`, `omc` with no
@@ -955,8 +1016,9 @@ function cmdHelp(topic, commandNames, transport, section, sections = false) {
 function onboardingHelp() {
     return [
         "首次使用、或不确定从哪开始：omc help omc-start-here（随包权威 topic 路线）；被拒或状态异常：omc help omc-refusals。",
+        "方法论按需读：omc help <topic> 默认只回节索引（每节字节数）；用 --section \"<标题>\" 取正文（可重复），确需整篇才 --all。",
         "目标→工具一步定位：omc next \"<你要做什么>\"（离线、只读，给能力/说明/首批命令；不确定会明说并回退到 omc-requirement-analysis）。",
-        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --extract <path>（可重复）或 --extract-keys，省掉再跑一次 omc artifact get。",
+        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --extract <path>（可重复）或 --extract-keys，省掉再跑一次 omc artifact get；artifact get 正文超 8KB 默认也只回形状（--jq/--keys 定向取，--full 才整包）。",
         "工具发现：omc commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。",
         "单工具/契约：omc describe <tool>（schema+recipe+能力路由）· omc contract <lane>（wire 契约+能力路由）；环境就绪：omc call discover_environment --env <env> --args '{}'。",
         "写入两道门：对话层草稿确认（omc help omc-config-draft-review）+ 环境 writable 开关；生产环境每笔写需在 args 里带 confirmProduction:true。",
@@ -1035,7 +1097,7 @@ async function main() {
         command.outputHelp();
         return CLI_EXIT_CODES.ok;
     }
-    command.command("help [topic]").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）", (value, previous) => [...previous, value], []).option("--sections").option("--max-output-bytes <bytes>").action(async (topic, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdHelp(topic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true)); });
+    command.command("help [topic]").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）", (value, previous) => [...previous, value], []).option("--sections").option("--all", "回整篇正文（默认只回节索引：标题 + 各节字节）").option("--max-output-bytes <bytes>").action(async (topic, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdHelp(topic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true, options.all === true)); });
     command.command("setup").option("--list").option("--edit <environment>").option("--remove <environment>").action(async (options) => {
         commandExitCode = await cmdSetup(new ConfigStore(defaultPaths()), [...(options.list ? ["--list"] : []), ...(options.edit ? ["--edit", options.edit] : []), ...(options.remove ? ["--remove", options.remove] : [])]);
     });
@@ -1169,8 +1231,8 @@ async function main() {
             console.error(`已清理 ${result.removed} 个读回产物，释放 ${formatBytes(result.freedBytes)}；保留 ${result.kept} 个（${formatBytes(result.keptBytes)}）`);
         commandExitCode = CLI_EXIT_CODES.ok;
     });
-    artifactCommand.command("get <id>").option("--jq <path>").option("--path-only").option("--summary").option("--keys [a,b]").option("--max-output-bytes <bytes>").action(async (id, options) => {
-        commandExitCode = await withTransport(options, request, (transport) => cmdArtifactGet(id, transport, { ...(options.jq ? { jq: options.jq } : {}), pathOnly: options.pathOnly === true, summary: options.summary === true || options.keys === true, ...(typeof options.keys === "string" ? { keys: options.keys } : {}) }));
+    artifactCommand.command("get <id>").option("--jq <path>").option("--path-only").option("--summary").option("--keys [a,b]").option("--full", "整包返回正文（默认：正文超过 8KB 时只回形状 outline + fetch，按需 --jq/--keys 定向取值）").option("--max-output-bytes <bytes>").action(async (id, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdArtifactGet(id, transport, { ...(options.jq ? { jq: options.jq } : {}), pathOnly: options.pathOnly === true, summary: options.summary === true || options.keys === true, ...(typeof options.keys === "string" ? { keys: options.keys } : {}), full: options.full === true }));
     });
     command.command("bench").option("--live-sample").option("--env <environment>").action(async (options) => { commandExitCode = await cmdBench([...(options.liveSample ? ["--live-sample"] : []), ...(options.env ? ["--env", options.env] : [])]); });
     command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}) })); });
@@ -1185,8 +1247,12 @@ async function main() {
     command.command("next <goal>").option("--env <environment>").option("--max-output-bytes <bytes>").action(async (goal, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdNext(goal, transport));
     });
-    command.command("usage").option("--max-output-bytes <bytes>").action(async (options) => {
-        commandExitCode = await withTransport(options, request, (transport) => cmdUsage(transport));
+    command.command("usage").option("--records").option("--top <n>").option("--max-output-bytes <bytes>").addHelpText("after", "\n用量账本（.omc/usage.jsonl）：默认只回汇总（调用数/字节/重复浪费/按工具 Top N）；--records 才回原始记录。\n").action(async (options) => {
+        const parsedTop = options.top === undefined ? undefined : Number.parseInt(String(options.top), 10);
+        commandExitCode = await withTransport(options, request, (transport) => cmdUsage(transport, {
+            records: options.records === true,
+            ...(Number.isFinite(parsedTop) && parsedTop > 0 ? { top: parsedTop } : {}),
+        }));
     });
     command.command("capability <id>").option("--executable").option("--max-output-bytes <bytes>").action(async (id, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdCapability(id, transport, options.executable === true));

package/dist/goal-routes.js

@@ -286,7 +286,7 @@ function sectionBytes(pointer) {
     const resolved = readSkillSection(pointer.topic, pointer.section);
     return resolved ? Buffer.byteLength(resolved.section, "utf8") : 0;
 }
-const READ_HINT = '按 readCommands 一次读完（每条命令用可重复的 `--section` 取该 topic 的所有相关节，等价于逐节 `omc help <topic> --section "<section>"` 但只花一次往返）；单节字节数见 readSectionBudget，按预算自选。除非确需全貌，不要 `omc help <topic>` 读整篇（5–14KB，读一次就留在后续每一轮）。';
+const READ_HINT = '按 readCommands 一次读完（每条命令用可重复的 `--section` 取该 topic 的所有相关节，等价于逐节 `omc help <topic> --section "<section>"` 但只花一次往返）；单节字节数见 readSectionBudget，按预算自选。`omc help <topic>` 默认只回节索引（每节带字节数，约 1KB），不要再用 `--all` 读整篇（5–14KB，读一次就留在后续每一轮）。';
 function orderedCapabilities(ids, index) {
     const selected = new Set(ids);
     const nodes = [...index.nodeById.values()];

package/dist/script.js

@@ -4,6 +4,7 @@ import { ConfigStore, defaultPaths } from "./config-store.js";
 import { SessionManager } from "./session-manager.js";
 import { makeToolContext } from "./tools.js";
 import { runToolCall } from "./call.js";
+import { currentUsageId, recordScriptCall } from "./usage-log.js";
 export function parseScript(text) {
     const lines = [];
     const raw = text.split("\n");
@@ -36,8 +37,14 @@ export function parseScript(text) {
 export async function runScript(lines, options = {}) {
     const print = options.print ?? ((line) => console.log(line));
     const context = options.context ?? makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+    // The outer `script` invocation is already recorded by completeUsage; these
+    // inner records are what make a batch measurable at all. Before this, all 23
+    // `script -` calls in round 10 logged stdoutBytes=0 and the actual work was
+    // invisible (the outer record says "script -", the log says nothing else).
+    const parentId = currentUsageId();
     let failed = false;
     for (const [index, line] of lines.entries()) {
+        const startedMs = Date.now();
         const { exitCode, result } = await runToolCall(line.tool, {
             args: line.args,
             environment: line.env ?? options.defaultEnv,
@@ -46,7 +53,18 @@ export async function runScript(lines, options = {}) {
             context,
             print: () => undefined,
         });
-        print(JSON.stringify({ index, tool: line.tool, exitCode, result }));
+        const rendered = JSON.stringify({ index, tool: line.tool, exitCode, result });
+        recordScriptCall({
+            ...(parentId ? { parentId } : {}),
+            index,
+            tool: line.tool,
+            ...(line.args ? { args: line.args } : {}),
+            exitCode,
+            result,
+            stdoutBytes: Buffer.byteLength(rendered, "utf8"),
+            durationMs: Date.now() - startedMs,
+        });
+        print(rendered);
         if (exitCode !== 0) {
             failed = true;
             if (options.continueOnError !== true) {

package/dist/skills.js

@@ -52,16 +52,45 @@ export function readSkill(name) {
         return undefined;
     }
 }
+/**
+ * Headings that are really headings. The naive `^#{1,6}` scan also matched
+ * shell/JS comments inside fenced code blocks — `# --env 在单环境项目...` in
+ * omc-business-configuration was listed as an H1 section, which both polluted
+ * the section list and (since it was a second H1) hid every H2 from the index.
+ * Fenced blocks (``` and ~~~) are skipped, per CommonMark: a closing fence is
+ * the same character and at least as long as the opening one.
+ */
+function scanHeadings(lines) {
+    const found = [];
+    let fence;
+    for (const [index, line] of lines.entries()) {
+        const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            if (fence === undefined)
+                fence = { char: marker[0], length: marker.length };
+            else if (marker[0] === fence.char && marker.length >= fence.length)
+                fence = undefined;
+            continue;
+        }
+        if (fence !== undefined)
+            continue;
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (match)
+            found.push({ index, level: match[1].length, heading: match[2] });
+    }
+    return found;
+}
 /** Return one Markdown heading and its nested content without loading the full topic into the envelope. */
 export function readSkillSection(name, requested) {
     const document = readSkill(name);
     if (!document)
         return undefined;
     const lines = document.content.split(/\r?\n/);
-    const headings = lines.flatMap((line) => {
-        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
-        return match ? [match[2]] : [];
-    });
+    const scanned = scanHeadings(lines);
+    // The section LIST is what `--section` with no value returns: every real
+    // heading (any level), in document order.
+    const headings = scanned.map((entry) => entry.heading);
     const normalized = requested.trim().toLowerCase();
     // A requested section may be given by its ordered number ("8") instead of the
     // full heading ("8. Canonical configuration order（规范配置顺序）") — the
@@ -80,25 +109,19 @@ export function readSkillSection(name, requested) {
         }
         return false;
     };
-    let start = lines.findIndex((line) => {
-        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
-        return match !== null && matches(match[2].trim().toLowerCase());
-    });
+    let start = scanned.find((entry) => matches(entry.heading.trim().toLowerCase()))?.index ?? -1;
     // Forgiving fallback: a unique prefix/substring match ("流程" for "流程字段权限").
     // A non-unique partial matches nothing (precision over recall) and the
     // not-found error lists the real headings, so the caller can retry once.
     if (start < 0 && normalized.length >= 2) {
-        const partial = lines.filter((line) => {
-            const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
-            return match !== null && match[2].trim().toLowerCase().includes(normalized);
-        });
+        const partial = scanned.filter((entry) => entry.heading.trim().toLowerCase().includes(normalized));
         if (partial.length === 1)
-            start = lines.indexOf(partial[0]);
+            start = partial[0].index;
     }
     if (start < 0)
         return { document, section: "", headings };
-    const startMatch = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[start]);
-    const level = startMatch[1].length;
+    const startEntry = scanned.find((entry) => entry.index === start);
+    const level = startEntry.level;
     let end = lines.length;
     for (let index = start + 1; index < lines.length; index += 1) {
         const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
@@ -109,4 +132,42 @@ export function readSkillSection(name, requested) {
     }
     return { document, section: lines.slice(start, end).join("\n").trim() + "\n", headings };
 }
+/**
+ * The "shape" of a topic: every heading with the bytes it would cost to read.
+ *
+ * Round 10 measured a single `help omc-business-configuration` at 35,872 B and
+ * seven such full reads in one session; the caller only ever needed one or two
+ * headings. An index costs ~600 B and names the price of each part, so the
+ * caller chooses instead of paying for the whole document by default.
+ */
+export function readSkillOutline(name) {
+    const document = readSkill(name);
+    if (!document)
+        return undefined;
+    const lines = document.content.split(/\r?\n/);
+    const headings = scanHeadings(lines);
+    const sections = headings.map((entry) => {
+        let end = lines.length;
+        // Same slicing rule as readSkillSection: a section runs until the next
+        // heading of the same or a higher level, so reported bytes match the read.
+        for (let index = entry.index + 1; index < lines.length; index += 1) {
+            const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
+            if (match && match[1].length <= entry.level) {
+                end = index;
+                break;
+            }
+        }
+        const body = `${lines.slice(entry.index, end).join("\n").trim()}\n`;
+        return { heading: entry.heading, level: entry.level, bytes: Buffer.byteLength(body, "utf8") };
+    });
+    const bytes = Buffer.byteLength(document.content, "utf8");
+    // A topic whose whole body sits under a single H1 (the title) would produce a
+    // one-entry index — useless. Descend to the next level in that case, so the
+    // index always names the parts a caller can actually choose between.
+    const levels = [...new Set(headings.map((entry) => entry.level))].sort((left, right) => left - right);
+    const singleRoot = levels.length > 1 && headings.filter((entry) => entry.level === levels[0]).length === 1;
+    const indexLevel = singleRoot ? levels[1] : levels[0];
+    const visible = indexLevel === undefined ? sections : sections.filter((entry) => entry.level === indexLevel);
+    return { document, bytes, sections: visible.length > 0 ? visible : sections };
+}
 //# sourceMappingURL=skills.js.map

package/dist/usage-log.js

@@ -1,6 +1,7 @@
-import { appendFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, closeSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, closeSync, renameSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
 let pending;
 /**
  * The project session marker: a working directory that opted into the usage log
@@ -10,6 +11,11 @@ let pending;
 export function projectSessionActive() {
     return logPath() !== undefined;
 }
+/**
+ * The project-scoped log: only present when the working directory opted in with
+ * `.omc-env` (or `OMC_USAGE_LOG`). Session-scoped caches and idempotency memos
+ * key off THIS path so repo tests and the golden master stay stable.
+ */
 function logPath() {
     const explicit = process.env.OMC_USAGE_LOG;
     if (explicit)
@@ -17,6 +23,83 @@ function logPath() {
     const projectEnv = resolve(process.cwd(), ".omc-env");
     return existsSync(projectEnv) ? resolve(process.cwd(), ".omc", "usage.jsonl") : undefined;
 }
+const USAGE_LOG_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * Where invocation records are WRITTEN. Measurement must not silently stop just
+ * because a directory never ran `omc env use`: fall back to a per-directory file
+ * under the config root (`$OMC_CONFIG_HOME/usage/<cwd-hash>.jsonl`, default
+ * `~/.config/omc/usage/`). Tests isolate with OMC_CONFIG_HOME, so the fallback
+ * never leaks into the developer's real home during `npm test`.
+ *
+ * Memos still read `logPath()` only — a fallback log is append-only telemetry,
+ * never a source of "already did this" answers.
+ */
+function recordLogPath() {
+    const explicit = process.env.OMC_USAGE_LOG;
+    if (explicit)
+        return { path: resolve(explicit), scope: "project" };
+    const project = logPath();
+    if (project)
+        return { path: project, scope: "project" };
+    if (process.env.OMC_USAGE_DISABLE === "1")
+        return undefined;
+    // The fallback writes into the user's config root. Keep it out of the test
+    // suite and out of scripted non-interactive runs unless explicitly asked:
+    // a measurement side effect must never be the reason a fixture directory
+    // suddenly has an extra file (or the developer's home grows during npm test).
+    if (process.env.NODE_TEST_CONTEXT !== undefined)
+        return undefined;
+    if (process.env.OMC_USAGE_USER_FALLBACK === "0")
+        return undefined;
+    const configRoot = process.env.OMC_CONFIG_HOME ? resolve(process.env.OMC_CONFIG_HOME) : join(homedir(), ".config", "omc");
+    const cwd = resolve(process.cwd());
+    const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+    return { path: join(configRoot, "usage", `${hash}.jsonl`), scope: "user" };
+}
+/**
+ * `.omc/` holds artifacts and this log; committing it leaks business data. The
+ * append is explicit-only (`omc setup` binding a project); `projectIgnoreState`
+ * is what the read side reports, so `omc usage` never edits the working tree.
+ */
+function appendRecord(path, record) {
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        if (existsSync(path) && statSync(path).size > USAGE_LOG_MAX_BYTES)
+            renameSync(path, `${path}.1`);
+    }
+    catch {
+        // Rotation is best-effort: a failed rename must not drop the record.
+    }
+    appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+/** Append a `script-call` record: one line of `omc script` = one inner tool call. */
+export function recordScriptCall(input) {
+    const target = recordLogPath();
+    if (!target)
+        return;
+    const envelope = input.result ?? {};
+    const error = envelope.error && typeof envelope.error === "object" ? envelope.error : undefined;
+    const resultEnvelope = envelope.result && typeof envelope.result === "object" ? envelope.result : undefined;
+    const blocker = typeof resultEnvelope?.blocker === "string" ? resultEnvelope.blocker : typeof envelope.blocker === "string" ? envelope.blocker : undefined;
+    const status = typeof envelope.status === "string" ? envelope.status : input.exitCode === 0 ? "ok" : "error";
+    appendRecord(target.path, {
+        kind: "script-call",
+        id: createHash("sha256").update(`${Date.now()}\u0000${input.tool}\u0000${input.index}`).digest("hex").slice(0, 16),
+        ...(input.parentId ? { parentId: input.parentId } : {}),
+        index: input.index,
+        tool: input.tool,
+        argsDigest: createHash("sha256").update(`${input.tool}\u0000${JSON.stringify(input.args ?? {})}`).digest("hex"),
+        argSummary: summarizeArgsObject(input.args ?? {}),
+        stdoutBytes: input.stdoutBytes,
+        durationMs: input.durationMs,
+        status,
+        exitCode: input.exitCode,
+        ...(typeof error?.code === "string" ? { errorCode: error.code } : {}),
+        ...(blocker ? { blocker } : {}),
+        startedAt: new Date().toISOString(),
+        ...(target.scope === "user" ? { scope: "user", cwd: resolve(process.cwd()) } : {}),
+    });
+}
 /** The args digest of the in-flight invocation (session-scoped memo key). */
 export function currentUsageArgsDigest() {
     return pending?.argsDigest;
@@ -126,7 +209,7 @@ function commandOf(argv) {
     for (let index = 2; index < argv.length && values.length < 2; index += 1) {
         const token = argv[index];
         if (token.startsWith("--")) {
-            if (["--out", "--max-output-bytes", "--args", "--args-file", "--env", "--environment", "--request-id", "--timeout-ms", "--wait", "--path"].includes(token))
+            if (["--out", "--max-output-bytes", "--args", "--args-file", "--env", "--environment", "--request-id", "--timeout-ms", "--wait", "--path", "--top"].includes(token))
                 index += 1;
             continue;
         }
@@ -143,25 +226,32 @@ function facesOf(argv) {
     return faces.filter((face) => argv.includes(face));
 }
 const safeArgumentKeys = new Set(["schemaCode", "propertyCode", "code", "workflowCode", "ruleCode", "sheetCode", "id", "dataRuleType", "propertyType", "published", "handler"]);
-function summarizeArgs(argv) {
+function summarizeArgsObject(parsed) {
     const summary = { argKeys: [] };
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const keys = Object.keys(parsed).sort();
+        summary.argKeys = keys;
+        // Only key names plus a fixed allowlist of business identifiers: the log is
+        // durable and shared, so free-form values (scripts, form data) stay out.
+        for (const key of keys)
+            if (safeArgumentKeys.has(key)) {
+                const value = parsed[key];
+                if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+                    summary[key] = value;
+            }
+    }
+    return summary;
+}
+function summarizeArgs(argv) {
+    let summary = { argKeys: [] };
     const argsIndex = argv.indexOf("--args");
     if (argsIndex >= 0) {
         try {
             const parsed = JSON.parse(argv[argsIndex + 1] ?? "{}");
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                const keys = Object.keys(parsed).sort();
-                summary.argKeys = keys;
-                for (const key of keys)
-                    if (safeArgumentKeys.has(key)) {
-                        const value = parsed[key];
-                        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
-                            summary[key] = value;
-                    }
-            }
+            summary = summarizeArgsObject(parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {});
         }
         catch {
-            summary.argKeys = ["<invalid-json>"];
+            summary = { argKeys: ["<invalid-json>"] };
         }
     }
     const envIndex = argv.findIndex((token) => token === "--env" || token === "--environment");
@@ -175,8 +265,8 @@ function summarizeArgs(argv) {
     return summary;
 }
 export function beginUsage(argv) {
-    const path = logPath();
-    if (!path)
+    const target = recordLogPath();
+    if (!target)
         return;
     const raw = argv.slice(2).join("\u0000");
     const argsDigest = createHash("sha256").update(raw).digest("hex");
@@ -191,8 +281,13 @@ export function beginUsage(argv) {
         stdoutBytes: 0,
         fileBytes: 0,
         status: "no-envelope",
+        scope: target.scope,
     };
 }
+/** The id of the in-flight invocation — `script-call` records point back at it. */
+export function currentUsageId() {
+    return pending?.id;
+}
 export function recordUsageOutput(value, stdoutBytes, fileBytes = 0) {
     if (!pending)
         return;
@@ -218,10 +313,9 @@ export function completeUsage(exitCode) {
         return;
     const current = pending;
     pending = undefined;
-    const path = logPath();
-    if (!path)
+    const target = recordLogPath();
+    if (!target)
         return;
-    mkdirSync(dirname(path), { recursive: true });
     const record = {
         kind: "invocation",
         id: current.id,
@@ -238,8 +332,37 @@ export function completeUsage(exitCode) {
         ...(current.errorCode ? { errorCode: current.errorCode } : {}),
         ...(current.blocker ? { blocker: current.blocker } : {}),
         ...(current.requestId ? { requestId: current.requestId } : {}),
+        ...(target.scope === "user" ? { scope: "user", cwd: resolve(process.cwd()) } : {}),
     };
-    appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+    appendRecord(target.path, record);
+}
+/**
+ * Whether the project's `.omc/` directory is excluded from version control.
+ * Reported by `omc usage`; the actual append happens only in `env use`, because
+ * a read command must not mutate the working tree (r10 review: `omc usage` in a
+ * repo would otherwise edit .gitignore behind the caller's back).
+ */
+export function projectIgnoreState(projectRoot = process.cwd()) {
+    if (!existsSync(join(projectRoot, ".git")))
+        return "no-git";
+    const ignoreFile = join(projectRoot, ".gitignore");
+    if (!existsSync(ignoreFile))
+        return "no-gitignore";
+    const text = readFileSync(ignoreFile, "utf8");
+    const present = text.split(/\r?\n/).some((line) => [".omc/", ".omc", "/.omc/", "/.omc"].includes(line.trim()));
+    return present ? "ignored" : "missing";
+}
+/** Add `.omc/` to an existing .gitignore (explicit setup path only). */
+export function ensureProjectIgnore(projectRoot = process.cwd()) {
+    const state = projectIgnoreState(projectRoot);
+    if (state === "no-git" || state === "no-gitignore")
+        return state;
+    if (state === "ignored")
+        return "ignored";
+    const ignoreFile = join(projectRoot, ".gitignore");
+    const text = readFileSync(ignoreFile, "utf8");
+    appendFileSync(ignoreFile, `${text.endsWith("\n") || text.length === 0 ? "" : "\n"}.omc/\n`, "utf8");
+    return "appended";
 }
 function readUsageTail(path, maxBytes) {
     if (!existsSync(path))
@@ -280,67 +403,132 @@ function readUsage(path) {
         }
     });
 }
-export function usageReport(pathArg) {
-    const path = pathArg ? resolve(pathArg) : logPath() ?? resolve(process.cwd(), ".omc", "usage.jsonl");
+/** `call rule.save` → `rule.save`; anything else keeps its command name. */
+function toolOf(command) {
+    return command.startsWith("call ") ? command.slice(5) : command;
+}
+export function usageReport(pathArg, options = {}) {
+    const fallback = options.resolveLikeWriter === true ? recordLogPath() : undefined;
+    const path = pathArg ? resolve(pathArg) : fallback?.path ?? logPath() ?? resolve(process.cwd(), ".omc", "usage.jsonl");
+    const scope = pathArg ? "explicit" : fallback?.scope ?? "project";
     const records = readUsage(path);
     const calls = records.filter((record) => record.kind === "invocation");
+    const scriptCalls = records.filter((record) => record.kind === "script-call");
+    const top = Math.max(1, Math.min(options.top ?? 10, 100));
     const commandCounts = new Map();
+    const toolCounts = new Map();
     let stdoutBytes = 0;
     let fileBytes = 0;
     let fullCalls = 0;
     for (const record of calls) {
         const command = String(record.command ?? "(unknown)");
+        const bytes = Number(record.stdoutBytes ?? 0);
         commandCounts.set(command, (commandCounts.get(command) ?? 0) + 1);
-        stdoutBytes += Number(record.stdoutBytes ?? 0);
+        const tool = toolOf(command);
+        const entry = toolCounts.get(tool) ?? { calls: 0, bytes: 0, viaScript: 0 };
+        toolCounts.set(tool, { ...entry, calls: entry.calls + 1, bytes: entry.bytes + bytes });
+        stdoutBytes += bytes;
         fileBytes += Number(record.fileBytes ?? 0);
         if (Array.isArray(record.faces) && record.faces.includes("--full"))
             fullCalls += 1;
     }
-    const repeated = [...commandCounts.entries()].filter(([, count]) => count > 1).map(([command, count]) => ({ command, count }));
+    // Inner `omc script` calls: the outer record's command is just "script <file>"
+    // and its bytes are 0 (script owns stdout), so without this roll-up every
+    // batch was invisible to cost accounting (round 10: 23 such calls, 0 B).
+    let scriptBytes = 0;
+    for (const record of scriptCalls) {
+        const bytes = Number(record.stdoutBytes ?? 0);
+        scriptBytes += bytes;
+        const tool = String(record.tool ?? "(unknown)");
+        const entry = toolCounts.get(tool) ?? { calls: 0, bytes: 0, viaScript: 0 };
+        toolCounts.set(tool, { ...entry, calls: entry.calls + 1, bytes: entry.bytes + bytes, viaScript: entry.viaScript + 1 });
+    }
+    const totalBytes = stdoutBytes + scriptBytes;
+    // Measurement, not vanity: how much of the session was the SAME call repeated.
     const exactCounts = new Map();
     const createdCodes = new Set();
     const referencedCodes = new Set();
-    for (const record of calls) {
+    // Redundancy spans both faces: the same tool called twice inside ONE batch is
+    // exactly as wasteful as twice across two `omc call` invocations (round 10
+    // hid 23 batched calls behind `script -`).
+    const examined = [...calls, ...scriptCalls];
+    for (const record of examined) {
         const summary = record.argSummary && typeof record.argSummary === "object" ? record.argSummary : {};
-        const command = String(record.command ?? "");
+        const command = record.kind === "script-call" ? String(record.tool ?? "") : String(record.command ?? "");
         const digest = `${command}:${String(record.argsDigest ?? "")}`;
-        exactCounts.set(digest, (exactCounts.get(digest) ?? 0) + 1);
+        const entry = exactCounts.get(digest) ?? { count: 0, bytes: 0, command };
+        exactCounts.set(digest, { count: entry.count + 1, bytes: entry.bytes + Number(record.stdoutBytes ?? 0), command });
         if (command === "call model.create" && typeof summary.code === "string")
             createdCodes.add(summary.code);
         for (const key of ["schemaCode", "workflowCode"])
             if (typeof summary[key] === "string")
                 referencedCodes.add(summary[key]);
     }
-    const exactRepeated = [...exactCounts.entries()].filter(([, count]) => count > 1).map(([digest, count]) => ({ digest: digest.slice(-16), count }));
+    const repeated = [...commandCounts.entries()].filter(([, count]) => count > 1).map(([command, count]) => ({ command, count })).sort((left, right) => right.count - left.count);
+    // Wasted bytes: for a group of N identical calls, N-1 copies bought nothing.
+    let redundantCalls = 0;
+    let redundantBytes = 0;
+    const exactRepeated = [...exactCounts.entries()]
+        .filter(([, entry]) => entry.count > 1)
+        .map(([digest, entry]) => {
+        const wasted = Math.round((entry.bytes * (entry.count - 1)) / entry.count);
+        redundantCalls += entry.count - 1;
+        redundantBytes += wasted;
+        return { digest: digest.slice(-16), command: entry.command, count: entry.count, wastedBytes: wasted };
+    })
+        .sort((left, right) => right.wastedBytes - left.wastedBytes)
+        .slice(0, top);
     const unseenTargetReferences = [...referencedCodes].filter((code) => !createdCodes.has(code));
-    // Round 4: attribute large reads. The complex benchmark showed `artifact get`
-    // at 56% of stdout; without this the next session cannot see the whale.
     const artifactBytes = calls.filter((record) => String(record.command).startsWith("artifact get")).reduce((sum, record) => sum + Number(record.stdoutBytes ?? 0), 0);
     const largestReads = calls
         .filter((record) => Number(record.stdoutBytes ?? 0) >= 8192)
         .map((record) => ({ command: String(record.command ?? ""), bytes: Number(record.stdoutBytes ?? 0), summary: record.argSummary ?? {} }))
         .sort((left, right) => right.bytes - left.bytes)
-        .slice(0, 8);
+        .slice(0, Math.min(top, 8));
+    const byTool = [...toolCounts.entries()]
+        .map(([tool, entry]) => ({
+        tool,
+        calls: entry.calls,
+        bytes: entry.bytes,
+        ...(entry.viaScript > 0 ? { viaScript: entry.viaScript } : {}),
+        share: totalBytes === 0 ? 0 : Number((entry.bytes / totalBytes).toFixed(3)),
+    }))
+        .sort((left, right) => right.bytes - left.bytes)
+        .slice(0, top);
     const violations = [
         ...(fullCalls > 3 ? [{ code: "batch-full-prefetch", message: `${fullCalls} calls used --full; prefer next/recipe/default describe` }] : []),
         ...(calls.some((record) => String(record.command).startsWith("commands") && !Array.isArray(record.faces)) ? [{ code: "broad-command-catalog", message: "full commands inventory was requested" }] : []),
         ...(artifactBytes > 32768 ? [{ code: "large-artifact-read", message: `artifact get pulled ${artifactBytes} B; prefer --summary/--keys/--jq or the projected workflow summary` }] : []),
+        ...(scope === "project" && projectIgnoreState(process.cwd()) === "missing" ? [{ code: "project-log-not-ignored", message: ".omc/ is not in .gitignore；重跑 `omc setup` 并选择绑定本项目（会自动追加），或手动加一行 .omc/，否则用量账本与产物可能被提交" }] : []),
     ];
     return {
         status: "ok",
         path,
+        scope,
+        // `path` is redacted (host layout stays private), so name the file itself:
+        // project logs are `<project>/.omc/usage.jsonl`, user logs live under
+        // `<config root>/usage/<hash>.jsonl`.
+        logFile: basename(path),
         calls: calls.length,
+        scriptCalls: scriptCalls.length,
         stdoutBytes,
+        scriptBytes,
+        totalBytes,
         fileBytes,
+        // Explicit estimate, never presented as a measurement: the CLI cannot see
+        // the agent's tokenizer, so bytes/4 is a floor for planning only.
+        estimatedTokens: Math.round(totalBytes / 4),
         fullCalls,
-        repeated,
+        redundancy: { calls: redundantCalls, bytes: redundantBytes, share: Number((redundantCalls / Math.max(examined.length, 1)).toFixed(3)) },
+        repeated: repeated.slice(0, top),
         exactRepeated,
+        byTool,
         createdCodes: [...createdCodes],
         unseenTargetReferences,
         artifactBytes,
         largestReads,
         violations,
-        records,
+        ...(options.records === true ? { records } : {}),
     };
 }
 //# sourceMappingURL=usage-log.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.78",
+  "version": "0.4.80",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -50,9 +50,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.4.78",
+    "@stalfh233/omc-fake-platform": "0.4.80",
     "commander": "14.0.3",
-    "omc-core": "0.4.78",
+    "omc-core": "0.4.80",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-start-here.md

@@ -24,7 +24,7 @@ be treated as a second source. Read this, then follow the topics it names.
    - `build`/`modify` → 按阶梯内联的**写工具 + 必填参数**执行。
    - `scout`（能不能/怎么写/是否支持）→ 先探边界（`omc-capability-scouting`），别直接写。若 `next` 返回 **`boundary`**（`match.kind:"boundary"`，如 `ocr-e-signature`/`release-prod`/`inline-coding`），说明需求**不在覆盖内**（`write:false`）：如实报告、用 `omc capabilities` 核对，**不要**用相近能力伪造实现。
    阶梯步骤已内联工具必填参数（`route.ladder[].tools`/`readTools`）与命中 recipe 的 `describe <tool> --example <id>`；据此直接执行——**不要再逐能力 `commands --lane`**，也不要先扫 `commands --json`/全部 `contract`/全部 `describe --full`。
-   方法论按 `route.readSections` 逐节读：对每条 `{topic, section}` 执行 `omc help <topic> --section "<section>"`（单节 0.4–3.4KB）。**不要 `omc help <topic>` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。
+   方法论按 `route.readSections` 逐节读：对每条 `{topic, section}` 执行 `omc help <topic> --section "<section>"`（单节 0.4–3.4KB）。`omc help <topic>` 默认只回节索引（约 1KB，含每节字节数）；**不要 `--all` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。
 2. 写前只需读 `omc-config-draft-review`（人审门）与 `omc-five-piece-flow`（发现→草稿→权限→执行→回读）；`omc-business-configuration` 按命中的能力分节读（见 `next` 的 `readSections`），不要整篇预取。
 3. 环境名以 `omc doctor` 的「环境=」或 `.omc-env` 为准；工具不确定先用默认 `describe`/`--example`，只有单个工具缺形状才用 `--full`；`describe` 带 `exampleHint`/`recipeHint` 时优先 `--example`。
 4. 只有工具不在 `next` 命中能力内、或要看 purpose/枚举时，才补一次 `commands --json --compact --lane <lane>`。非显然形状（规则图、流程模板、表单布局、RESTFUL）才单独 `describe --example`。