@stalfh233/omc-cli 0.4.99 → 0.4.100

package/dist/skills.js

@@ -81,6 +81,22 @@ function scanHeadings(lines) {
     }
     return found;
 }
+/**
+ * Slice one heading's body using the documented rule: a section runs until the
+ * next heading of the same or a higher level. Shared by `--section` and search
+ * so a search hit can announce the exact bytes `--section` would return.
+ */
+function sliceSectionText(lines, start, level) {
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
+        if (match && match[1].length <= level) {
+            end = index;
+            break;
+        }
+    }
+    return lines.slice(start, end).join("\n").trim() + "\n";
+}
 /** 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);
@@ -121,16 +137,7 @@ export function readSkillSection(name, requested) {
     if (start < 0)
         return { document, section: "", headings };
     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]);
-        if (match && match[1].length <= level) {
-            end = index;
-            break;
-        }
-    }
-    return { document, section: lines.slice(start, end).join("\n").trim() + "\n", headings };
+    return { document, section: sliceSectionText(lines, startEntry.index, startEntry.level), headings };
 }
 /**
  * The "shape" of a topic: every heading with the bytes it would cost to read.
@@ -147,17 +154,7 @@ export function readSkillOutline(name) {
     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`;
+        const body = sliceSectionText(lines, entry.index, entry.level);
         return { heading: entry.heading, level: entry.level, bytes: Buffer.byteLength(body, "utf8") };
     });
     const bytes = Buffer.byteLength(document.content, "utf8");
@@ -170,4 +167,75 @@ export function readSkillOutline(name) {
     const visible = indexLevel === undefined ? sections : sections.filter((entry) => entry.level === indexLevel);
     return { document, bytes, sections: visible.length > 0 ? visible : sections };
 }
+/**
+ * Cross-topic full-text search (`omc help --search`).
+ *
+ * Why this exists: r18 spent 173.8 KB re-dumping five whole topics twice to grep
+ * for `40000`, because `omc help` is a bookshelf (one heading index per topic)
+ * and there was no way to ask a question. A search that returns only
+ * topic/heading would still cost a second call, so a hit carries its section
+ * body and the exact bytes `--section` would return.
+ *
+ * Matching is deliberately literal: case-insensitive substring, whitespace
+ * splits terms, `all` requires every term in the same section and `any`
+ * requires one. No stemming, no fuzzy matching — an agent searching an exact
+ * error code must never be steered to a similar-looking section.
+ */
+export function searchSkills(query, options) {
+    const terms = query.trim().toLowerCase().split(/\s+/).filter((term) => term.length > 0);
+    if (terms.length === 0)
+        return { matches: [], total: 0 };
+    const found = [];
+    for (const entry of listSkills()) {
+        const document = readSkill(entry.name);
+        if (!document)
+            continue;
+        const lines = document.content.split(/\r?\n/);
+        const scanned = scanHeadings(lines);
+        // Same visible levels as the index: a whole-document H1 must not swallow
+        // every H2 hit into one giant match.
+        const levels = [...new Set(scanned.map((item) => item.level))].sort((left, right) => left - right);
+        const singleRoot = levels.length > 1 && scanned.filter((item) => item.level === levels[0]).length === 1;
+        const indexLevel = singleRoot ? levels[1] : levels[0];
+        const visible = scanned.filter((heading) => heading.level === indexLevel);
+        for (const [ordinal, heading] of visible.entries()) {
+            if (indexLevel === undefined)
+                continue;
+            const section = sliceSectionText(lines, heading.index, heading.level);
+            const lower = section.toLowerCase();
+            const hitTerms = terms.filter((term) => lower.includes(term));
+            if (hitTerms.length === 0)
+                continue;
+            if (options.mode === "all" && hitTerms.length < terms.length)
+                continue;
+            const matchLines = [];
+            for (let index = heading.index; index < lines.length && matchLines.length < 3; index += 1) {
+                const text = lines[index];
+                const lineTerms = hitTerms.filter((term) => text.toLowerCase().includes(term));
+                if (lineTerms.length === 0)
+                    continue;
+                if (matchLines.length > 0 && /^(#{1,6})\s+/.test(text))
+                    continue;
+                matchLines.push({ line: index + 1, text: text.trim(), terms: lineTerms });
+            }
+            const headingHit = hitTerms.some((term) => heading.heading.toLowerCase().includes(term));
+            const bytes = Buffer.byteLength(section, "utf8");
+            found.push({
+                topic: document.name,
+                heading: heading.heading,
+                sectionOrdinal: ordinal + 1,
+                matchLines,
+                sectionBytes: bytes,
+                section,
+                // Heading hits beat body hits; more distinct terms beat fewer; smaller
+                // sections beat larger ones (cheaper to carry, usually more specific).
+                score: (headingHit ? 1000 : 0) + hitTerms.length * 100 + Math.max(0, 100 - Math.round(bytes / 64)),
+            });
+        }
+    }
+    found.sort((left, right) => right.score - left.score
+        || left.topic.localeCompare(right.topic)
+        || left.sectionOrdinal - right.sectionOrdinal);
+    return { matches: found.slice(0, Math.max(1, options.limit)), total: found.length };
+}
 //# sourceMappingURL=skills.js.map

package/dist/tools.js

@@ -21,6 +21,8 @@ import { registerListViewLane } from "./lanes/list-view.js";
 import { registerReportLane } from "./lanes/report.js";
 import { registerApplyChangesLane } from "./lanes/apply-changes.js";
 import { executionMetadataFor } from "./execution-metadata.js";
+import { attachRefusalRecovery } from "./refusal-guidance.js";
+import { ToolRefusalError } from "./tool-types.js";
 export { ToolRefusalError, ToolUncertainError } from "./tool-types.js";
 export { makeToolContext };
 /**
@@ -59,6 +61,39 @@ export function buildToolRegistry() {
         if (metadata)
             tool.executionMetadata = metadata;
     }
+    // r19 ticket 06 — 拒绝即教学，收口在最深的一层：每个 handler 返回/抛出的
+    // refused 结果在这里统一附加 recovery（同源配方命令、正确形状、不要做什么）。
+    // 收口在 registry 而不是 CLI 出口，是因为 runToolCall、测试 harness、MCP
+    // client、组装器全部经过 handler——一处附加、处处生效。已自带 recovery 的
+    // 拒绝（write-lock-held）不会被覆盖（attachRefusalRecovery 幂等）。
+    for (const tool of tools) {
+        const inner = tool.handler;
+        const name = tool.name;
+        tool.handler = async (ctx, args, self) => {
+            try {
+                const result = await inner(ctx, args, self);
+                if (result && typeof result === "object") {
+                    const status = result.status;
+                    // attachRefusalRecovery decides for itself: refused envelopes get
+                    // guidance, uncertain ones only when the dashboard boundary is
+                    // pinned in the frozen detail (r19 p14).
+                    if (status === "refused" || status === "uncertain") {
+                        return attachRefusalRecovery(result, name, tools);
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                const payload = error.payload;
+                if (payload && typeof payload === "object" && payload.status === "refused") {
+                    const enriched = attachRefusalRecovery(payload, name, tools);
+                    if (enriched !== payload)
+                        throw new ToolRefusalError(enriched);
+                }
+                throw error;
+            }
+        };
+    }
     return tools;
 }
 export { loadCoverageManifest };

package/dist/usage-log.js

@@ -34,6 +34,21 @@ const USAGE_LOG_MAX_BYTES = 8 * 1024 * 1024;
  * Memos still read `logPath()` only — a fallback log is append-only telemetry,
  * never a source of "already did this" answers.
  */
+/**
+ * r19 ticket 02: explicit opt-out for the WRITE side of the ledger.
+ *
+ * A maintainer script or an investigation subprocess that runs read-only
+ * discovery faces inside a sandbox used to append to that round's
+ * `.omc/usage.jsonl` — the r18 probe was read as 469 calls where the agent
+ * made 184 (19 polling reads + 105 investigation reads). "What did this round
+ * cost" must mean "what did the AGENT spend": `OMC_NO_USAGE=1` mutes this
+ * invocation's records (project log, user fallback, explicit OMC_USAGE_LOG —
+ * the switch beats them all). Only the write entry points consult this guard;
+ * reading (`omc usage`, idempotency memos) is untouched.
+ */
+function recordingDisabled() {
+    return process.env.OMC_NO_USAGE === "1";
+}
 function recordLogPath() {
     const explicit = process.env.OMC_USAGE_LOG;
     if (explicit)
@@ -74,6 +89,8 @@ function appendRecord(path, record) {
 }
 /** Append a `script-call` record: one line of `omc script` = one inner tool call. */
 export function recordScriptCall(input) {
+    if (recordingDisabled())
+        return;
     const target = recordLogPath();
     if (!target)
         return;
@@ -209,7 +226,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", "--top"].includes(token))
+            if (["--out", "--max-output-bytes", "--args", "--args-file", "--env", "--environment", "--request-id", "--timeout-ms", "--wait", "--path", "--top", "--search", "--search-mode", "--limit"].includes(token))
                 index += 1;
             continue;
         }
@@ -227,7 +244,7 @@ function facesOf(argv) {
     // `omc artifact get <id> --jq <path>` showed up as a bare `artifact get` with
     // empty argKeys, so the cost report could not tell a 200 B projection from a
     // 44 KB pull — precisely the read path these flags exist to make cheap.
-    const faces = ["--full", "--compact", "--json", "--schema-only", "--param", "--example", "--section", "--sections", "--out", "--quiet", "--jq", "--summary", "--keys", "--path-only", "--extract", "--extract-keys", "--records"];
+    const faces = ["--full", "--compact", "--json", "--schema-only", "--param", "--example", "--section", "--sections", "--search", "--search-mode", "--out", "--quiet", "--jq", "--summary", "--keys", "--path-only", "--extract", "--extract-keys", "--records"];
     return faces.filter((face) => argv.includes(face));
 }
 const safeArgumentKeys = new Set(["schemaCode", "propertyCode", "code", "workflowCode", "ruleCode", "sheetCode", "id", "dataRuleType", "propertyType", "published", "handler"]);
@@ -270,6 +287,8 @@ function summarizeArgs(argv) {
     return summary;
 }
 export function beginUsage(argv) {
+    if (recordingDisabled())
+        return;
     const target = recordLogPath();
     if (!target)
         return;

package/dist/write.js

@@ -124,7 +124,7 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
             const artifactRef = writeArtifact(ctx, `${tool.name}-${randomUUID().slice(0, 8)}.json`, artifact);
             return { status: executed.status, steps: executed.steps, failedStep: executed.failedStep, ...executed.envelope, ...(args.requestId ? { requestId: args.requestId } : {}), artifactFingerprint: artifactRef.detailSha256 };
         }
-        const { performed, readback, steps } = executed;
+        const { performed, readback, steps, halfSuccess } = executed;
         // Readback gate (live 2026-10-17): a tool that reports `readback.present:false`
         // has NOT proven its own write — the platform accepted the request but the
         // object is absent from the authoritative face. "Called without error" must
@@ -177,7 +177,7 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
             });
             rollbackRef = { seq: entry.seq, hint: `omc rollback plan ${entry.seq}（--env ${entry.environment}）` };
         }
-        return { status: "ok", deliveryState, performed, readback, ...(readbackWarning ? { readbackWarning } : {}), ...(steps !== undefined ? { steps } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), ...(rollbackRef ? { rollback: rollbackRef } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
+        return { status: "ok", deliveryState, performed, readback, ...(readbackWarning ? { readbackWarning } : {}), ...(steps !== undefined ? { steps } : {}), ...(halfSuccess !== undefined ? { halfSuccess } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), ...(rollbackRef ? { rollback: rollbackRef } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.99",
+  "version": "0.4.100",
   "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.99",
+    "@stalfh233/omc-fake-platform": "0.4.100",
     "commander": "14.0.3",
-    "omc-core": "0.4.99",
+    "omc-core": "0.4.100",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-start-here.md

@@ -26,7 +26,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>` 默认只回节索引（约 1KB，含每节字节数）；**不要 `--all` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。
+   方法论按 `route.readSections` 逐节读：对每条 `{topic, section}` 执行 `omc help <topic> --section "<section>"`（单节 0.4–3.4KB）。`omc help <topic>` 默认只回节索引（约 1KB，含每节字节数）；**不要 `--all` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。**带着具体问题（错误码/跨能力语义/某个词）直接 `omc help --search "<词>"`**——跨全部 topic 全文检索，命中节的正文随结果内联返回，一次调用就是答案；**严禁自己写 `for t in …; do omc help $t --all | grep …` 循环**（r18 实测 12 调用/176KB，检索一次 8KB 搞定）。
 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`。
@@ -50,6 +50,7 @@ omc script - --env <env> <<< '{"tool":"model.list"}'   # 多调链：NDJSON 每
 omc capability <selected-id>               # only the selected capability
 omc describe <tool> --example <recipe-id>   # recipe first; default describe otherwise
 omc help <topic> --section "<heading>"       # one methodology section, not all
+omc help --search "40000"                    # full-text search across all topics (answer in one call)
 ```
 
 Discovery precedes every write. 预算档位见 `omc-tool-selection` 的「Discovery 成本档位」；裸 `omc commands` 是有界索引，全量目录须显式 `commands --json`。