@stalfh233/omc-cli 0.4.79 → 0.4.80

package/README.md

@@ -130,10 +130,12 @@ omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实
 - **intent**：`partial` 表示该能力可声明式（`omc intent`）覆盖一部分——通常 create/update；
   `none` 表示只走 `omc call`。删除类、方法面、分类/连接池等仍走 `omc call` 逃生舱。
 
-## 近期能力（0.4.74 → 0.4.78）
+## 近期能力（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]` |
@@ -220,11 +222,13 @@ omc intent readback intent.yaml --env <env>  # 解码回 intent 形状做等价
 
 | 命令 | 作用 |
 |---|---|
-| `omc artifact get <id> [--summary\|--keys\|--jq <path>]` | 取回大读回的 `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 写入） |
 
 ## 覆盖边界

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.79",
+  "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.79",
+    "@stalfh233/omc-fake-platform": "0.4.80",
     "commander": "14.0.3",
-    "omc-core": "0.4.79",
+    "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`。