@stalfh233/omc-cli 0.6.19 → 0.6.20

package/dist/cli-contract.js

@@ -386,6 +386,17 @@ export function classifyResult(result) {
         const nextCommand = nextCommandFor(result) ?? (auth ? undefined : "omc help omc-refusals");
         return { status: route.envelopeStatus, error: nextCommand === undefined ? error : { ...error, nextCommand }, exitCode: auth ? CLI_EXIT_CODES.authConfig : CLI_EXIT_CODES.policyRefused };
     }
+    // Cross-project environment isolation is a local policy gate. It is emitted
+    // as an error-shaped result by the call seam so ordinary ConfigurationError
+    // failures (unknown env, missing credentials, malformed config) retain their
+    // historical classification.
+    if (result.blocker === "cross-environment-policy" || /^跨环境访问被拒绝：/u.test(String(result.message ?? ""))) {
+        return {
+            status: "error",
+            error: withNext({ code: "policy-refused", message: String(result.message ?? "cross-environment access refused"), retryable: false }),
+            exitCode: CLI_EXIT_CODES.policyRefused,
+        };
+    }
     // r25 沙盒（2026-11-04，B1 的同类）：`meta.get_status` 返回 `status:"failed"`、
     // `rollback apply` 返回 `status:"stopped"`——两个都曾掉进 internal（exit 15）：
     // 调用方看到「CLI 内部故障」，其实是「配置/凭据读回失败」或「恢复链在 N 步停下」。

package/dist/cli.js

@@ -1666,7 +1666,7 @@ function cmdGraphReferences(kind, code, transport, requestedEnvironment) {
     }
     catch (error) {
         if (error instanceof GraphIndexAbsentError)
-            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: `${error.message} 只读核查（不写索引）：omc graph status --env <env>（当前配置根）；MCP 面工具读的可能是另一配置根，比对 dbId/dbPath。`, nextCommand: "omc graph pull --env <env>" }, transport);
         return emitThrown(error, transport);
     }
 }
@@ -1680,7 +1680,7 @@ function cmdGraphStatus(transport) {
     }
     catch (error) {
         if (error instanceof GraphIndexAbsentError)
-            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: `${error.message} 只读核查（不写索引）：omc graph status --env <env>（当前配置根）；MCP 面工具读的可能是另一配置根，比对 dbId/dbPath。`, nextCommand: "omc graph pull --env <env>" }, transport);
         return emitThrown(error, transport);
     }
 }
@@ -1693,7 +1693,7 @@ function cmdGraphImpact(kind, code, transport) {
     }
     catch (error) {
         if (error instanceof GraphIndexAbsentError)
-            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: `${error.message} 只读核查（不写索引）：omc graph status --env <env>（当前配置根）；MCP 面工具读的可能是另一配置根，比对 dbId/dbPath。`, nextCommand: "omc graph pull --env <env>" }, transport);
         return emitThrown(error, transport);
     }
 }
@@ -1704,7 +1704,7 @@ function cmdGraphSearch(term, transport) {
     }
     catch (error) {
         if (error instanceof GraphIndexAbsentError)
-            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: `${error.message} 只读核查（不写索引）：omc graph status --env <env>（当前配置根）；MCP 面工具读的可能是另一配置根，比对 dbId/dbPath。`, nextCommand: "omc graph pull --env <env>" }, transport);
         return emitThrown(error, transport);
     }
 }

package/dist/config-store.js

@@ -14,6 +14,12 @@ export function removedProfileKeys(profile) {
     return REMOVED_PROFILE_KEYS.filter((key) => raw[key] !== undefined);
 }
 export class ConfigurationError extends Error {
+    policyRefused;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "ConfigurationError";
+        this.policyRefused = options.policyRefused === true;
+    }
 }
 export function defaultPaths(projectDir = process.cwd()) {
     const configRoot = process.env.OMC_CONFIG_HOME
@@ -290,12 +296,25 @@ export class ConfigStore {
         const allowText = allowlist.length === 0
             ? `.omc-envs=（无或不存在；准入回退到 .omc-env ∪ 全局 default）`
             : `.omc-envs=${allowlist.join(",")}`;
+        const configuredEnvironments = this.readConfig().environments;
+        const candidates = Object.entries(configuredEnvironments)
+            .filter(([, profile]) => profile.applicationCode === name);
+        // If several environment names point at the same application, recommend
+        // the one the caller is already working in before falling back to the
+        // machine-wide configuration order. This avoids steering an agent from a
+        // project-local `local` environment to an unrelated `prod` entry merely
+        // because `prod` appears first in omc.config.json.
+        const applicationHint = candidates.find(([candidate]) => candidate === bound)?.[0]
+            ?? candidates.find(([candidate]) => allowlist.includes(candidate))?.[0]
+            ?? candidates.find(([, profile]) => profile.isDefault)?.[0]
+            ?? candidates[0]?.[0];
         throw new ConfigurationError(`跨环境访问被拒绝：环境 "${name}" 不属于本项目（本项目允许：${own.join("、") || "(none)"}）。` +
             `解析到的项目根=${projectRoot}；${boundText}；${allowText}。` +
             `准入由「当前工作目录」下的 .omc-envs（白名单）+ .omc-env（默认绑定）共同决定，不是由 --env 参数单独决定；` +
             `在无声明的目录里 --env local 会落到机器全局 default（常见是 test）。` +
             `请改到声明了该环境的项目根再跑，或先向用户报告并取得同意后执行 \`omc env allow ${name}\`（写入项目 .omc-envs），` +
-            `或临时设置 OMC_ALLOW_CROSS_ENV=1 单次放行。`);
+            `或临时设置 OMC_ALLOW_CROSS_ENV=1 单次放行。` +
+            (applicationHint === undefined ? "" : `\n也许你指的是 --env ${applicationHint}（app=${name}）。`), { policyRefused: true });
     }
     bindProjectEnvironment(name) {
         const config = this.readConfig();

package/dist/mcp-graph.js

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { DatabaseSync } from "node:sqlite";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline";
@@ -60,7 +61,7 @@ const EXPLORE_TOOL = {
         "一次查全一个目标的引用与影响面（本地索引，毫秒级）。",
         "输入 query 可为业务名（实体 name+code 子串）或规则 code+name 词首；也可直接给字段/模型/服务 code。kind 可选 field|model|service，不给则三种都查。",
         "返回 {index(freshness), references:{kind:[{schemaCode,ruleCode,nodeCode,nodeType,via}]}, impact:{kind:totals}, search:{matches:{model,field,service},rules}}。",
-        "references/impact 支持 offset+limit 分页；truncated 时按返回的 nextOffset 继续调用。",
+        "references/impact 支持 offset+limit 分页；truncated 时按返回的 nextOffset 继续调用。实体分页结果带 nextCall；分页不会改变 resolved。字段同名时请用 schemaCode 消歧。",
         "改/删/重命名任何字段、模型、服务之前必查；找\"关于 X 的规则\"拿 code 也走这里。",
         "索引不含规则条件叶子与流程绑定；freshness=partial 时命中可能不完整（答案里有 gapWarning）。",
     ].join(" "),
@@ -69,6 +70,7 @@ const EXPLORE_TOOL = {
         properties: {
             query: { type: "string", description: "业务名（实体 name+code 子串）、字段/模型/服务 code，或规则检索词（规则 code+name 词首匹配）" },
             kind: { type: "string", enum: [...KINDS], description: "限定一种引用种类；省略则 field/model/service 全查" },
+            schemaCode: { type: "string", description: "限定字段所属模型；也可用于校验模型。" },
             env: { type: "string", description: "期望的环境名；与索引所属环境不一致时会拒绝（防跨环境误答）" },
             offset: { type: "integer", minimum: 0, description: "引用/实体结果起始偏移；truncated 时使用 nextOffset" },
             limit: { type: "integer", minimum: 1, maximum: MATCH_CAP, description: "每类结果最多返回多少条（默认 50）" },
@@ -78,7 +80,7 @@ const EXPLORE_TOOL = {
 };
 const STATUS_TOOL = {
     name: "omc_graph_status",
-    description: "索引完整性与新鲜度：environmentName、freshness(complete|partial)、模型/规则计数、pulledAtIso、ageMinutes、staleAfterMinutes、dbPath、coverage.applicationCodes、gaps。超过阈值会给 warning；回答前先看一眼，索引缺失会给出 pull 指引。",
+    description: "索引完整性与新鲜度（所有身份与新鲜度字段同层）：environmentName、freshness(complete|partial)、模型/规则计数、pulledAtIso、ageMinutes、staleAfterMinutes、dbId、dbPath、coverage、gaps。超过阈值会给 warning；索引缺失会给出 pull 指引。",
     inputSchema: { type: "object", properties: {} },
 };
 export function graphToolDefinitions() {
@@ -90,6 +92,57 @@ function toolResult(payload, isError = false) {
 function toolError(message) {
     return toolResult({ status: "error", message }, true);
 }
+function withMatchedOn(row, query) {
+    const name = row.name ?? "";
+    const code = row.code ?? row.schemaCode ?? "";
+    const on = name.includes(query) ? "name" : "code";
+    const value = on === "name" ? name : code;
+    const at = value.toLocaleLowerCase().indexOf(query.toLocaleLowerCase());
+    if (at < 0)
+        return { ...row, matchedOn: { on, fragment: query } };
+    let start = at;
+    let end = at + query.length;
+    while (start > 0 && /[\p{L}\p{N}]/u.test(value[start - 1]))
+        start--;
+    while (end < value.length && /[\p{L}\p{N}]/u.test(value[end]))
+        end++;
+    return { ...row, matchedOn: { on, fragment: value.slice(start, end) } };
+}
+function levenshtein(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let corner = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const old = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, corner + (a[i - 1] === b[j - 1] ? 0 : 1));
+            corner = old;
+        }
+    }
+    return prev[b.length];
+}
+function entityInventory() {
+    const db = new DatabaseSync(graphDbPath(), { readOnly: true });
+    try {
+        return [
+            ...db.prepare("SELECT schema_code, name FROM models").all().map((r) => ({ kind: "model", schemaCode: r.schema_code, code: r.schema_code, name: r.name ?? "" })),
+            ...db.prepare("SELECT schema_code, code, name FROM fields").all().map((r) => ({ kind: "field", schemaCode: r.schema_code, code: r.code, name: r.name ?? "" })),
+            ...db.prepare("SELECT code, name FROM services").all().map((r) => ({ kind: "service", code: r.code, name: r.name ?? "" })),
+        ];
+    }
+    finally {
+        db.close();
+    }
+}
+function suggestions(query) {
+    return entityInventory().map((row) => {
+        const q = query.toLocaleLowerCase();
+        const values = [row.code, row.name].map((v) => v.toLocaleLowerCase());
+        const prefix = values.some((v) => v.startsWith(q)) ? 0 : values.some((v) => v.includes(q)) ? 1 : 2;
+        const distance = Math.min(...values.map((v) => levenshtein(q, v)));
+        return { kind: row.kind, code: row.code, name: row.name, score: prefix * 1000 + distance };
+    }).sort((a, b) => a.score - b.score || a.code.localeCompare(b.code)).slice(0, 3);
+}
 function cap(rows, offset = 0, limit = MATCH_CAP) {
     const page = rows.slice(offset, offset + limit);
     return { rows: page, truncated: offset + page.length < rows.length, offset, limit, ...(offset + page.length < rows.length ? { nextOffset: offset + page.length } : {}), total: rows.length };
@@ -100,7 +153,9 @@ export async function executeGraphTool(name, rawArgs) {
     try {
         if (name === STATUS_TOOL.name) {
             const status = readGraphStatus();
-            return toolResult({ status: "ok", ...status });
+            // Keep a tiny compatibility locator for older MCP clients; all identity,
+            // freshness, coverage and gaps fields live at the top level.
+            return toolResult({ status: "ok", ...status, ...status.index, index: { environmentName: status.index.environmentName } });
         }
         if (name === EXPLORE_TOOL.name) {
             const query = typeof args.query === "string" ? args.query.trim() : "";
@@ -109,6 +164,9 @@ export async function executeGraphTool(name, rawArgs) {
             const kind = args.kind === undefined ? undefined : String(args.kind);
             if (kind !== undefined && !KINDS.includes(kind))
                 return toolError(`kind 必须是 ${KINDS.join("|")} 之一`);
+            const schemaCode = typeof args.schemaCode === "string" && args.schemaCode.trim() ? args.schemaCode.trim() : undefined;
+            if (schemaCode && kind !== "field" && kind !== "model")
+                return toolError("schemaCode 仅适用于 kind=field|model");
             const status = readGraphStatus();
             const index = status.index;
             if (typeof args.env === "string" && args.env.trim() && args.env.trim() !== index.environmentName) {
@@ -119,14 +177,32 @@ export async function executeGraphTool(name, rawArgs) {
             const limit = typeof args.limit === "number" && Number.isSafeInteger(args.limit) && args.limit > 0 && args.limit <= MATCH_CAP ? args.limit : MATCH_CAP;
             const references = {};
             const impact = {};
+            // Resolve from an unpaged search. The result page is presentation only;
+            // otherwise offset=2 can silently change the subject being inspected.
+            const search = searchGraphRules(query, limit, offset);
+            const resolvedSearch = searchGraphRules(query, MATCH_CAP, 0);
+            const loweredQuery = query.toLocaleLowerCase();
+            const allCandidates = entityInventory().filter((r) => (r.code.toLocaleLowerCase().includes(loweredQuery) || r.name.toLocaleLowerCase().includes(loweredQuery)) &&
+                (!schemaCode || (r.kind !== "service" && r.schemaCode === schemaCode)));
+            const typedCandidates = kind ? allCandidates.filter((r) => r.kind === kind) : allCandidates;
+            const fieldCandidates = kind === "field" ? typedCandidates : allCandidates.filter((r) => r.kind === "field");
+            const exactSame = fieldCandidates.filter((r) => r.code === query);
+            const ambiguous = kind === "field" && !schemaCode && exactSame.length > 1;
+            const resolvedEntity = ambiguous ? undefined : typedCandidates[0] ?? (kind === undefined ? allCandidates[0] : undefined);
+            const subjectByName = query !== (resolvedEntity?.code ?? "") && resolvedEntity;
+            const subjects = resolvedEntity
+                ? [{ kind: resolvedEntity.kind, code: resolvedEntity.kind === "model" ? (resolvedEntity.schemaCode ?? resolvedEntity.code) : resolvedEntity.code }]
+                : [];
             for (const one of kinds) {
-                const ref = queryGraphReferences(one, query);
-                const capped = cap(ref.matches, offset, limit);
+                const subject = subjects.find((s) => s.kind === one);
+                const ref = queryGraphReferences(one, subject?.code ?? query);
+                const scopedMatches = subject && one === "field" && schemaCode ? ref.matches.filter((row) => row.schemaCode === schemaCode) : ref.matches;
+                const capped = cap(scopedMatches, offset, limit);
                 // r35a-F4c（真机 2026-11-06）：**MCP 面是第三个消费者**——CLI 的 references
                 // 与 impact 都带 coverage 了，这里若不显式透传，MCP 用户看到的仍是
                 // 「matches:[] + 一句旧 note」，照样会把「表单没扫」误读成「没人引用」。
                 references[one] = {
-                    count: ref.matches.length,
+                    count: scopedMatches.length,
                     rows: capped.rows,
                     offset: capped.offset,
                     limit: capped.limit,
@@ -134,35 +210,49 @@ export async function executeGraphTool(name, rawArgs) {
                     ...(ref.coverage ? { coverage: ref.coverage } : {}),
                     ...(ref.gapWarning ? { gapWarning: ref.gapWarning } : {}),
                 };
-                if (ref.matches.length > 0 || kind !== undefined) {
-                    const imp = impactGraph(one, query);
+                if (scopedMatches.length > 0 || kind !== undefined || subject !== undefined) {
+                    const imp = impactGraph(one, subject?.code ?? query);
+                    const scopedRules = subject && one === "field" && schemaCode ? imp.rules.filter((row) => row.schemaCode === schemaCode) : imp.rules;
                     impact[one] = {
-                        totals: imp.totals,
-                        rules: cap(imp.rules, offset, limit),
+                        totals: scopedRules.length === imp.rules.length ? imp.totals : { ...imp.totals, rules: scopedRules.length },
+                        rules: cap(scopedRules, offset, limit),
                         datarules: cap(imp.datarules, offset, limit),
                         listviews: cap(imp.listviews, offset, limit),
+                        ...(one === "model" ? {
+                            fieldsReferenced: [...imp.rules.flatMap((r) => r.touches.field.map((code) => ({ code, ruleCode: r.ruleCode }))).reduce((m, x) => {
+                                    const item = m.get(x.code) ?? { code: x.code, touchedByRules: [] };
+                                    if (!item.touchedByRules.includes(x.ruleCode))
+                                        item.touchedByRules.push(x.ruleCode);
+                                    m.set(x.code, item);
+                                    return m;
+                                }, new Map()).values()],
+                        } : {}),
                         ...(imp.coverage ? { coverage: imp.coverage } : {}),
                     };
                 }
             }
-            const search = searchGraphRules(query, limit, offset);
-            const resolvedEntity = search.matches.model.items[0] ? { kind: "model", schemaCode: search.matches.model.items[0].schemaCode, code: search.matches.model.items[0].schemaCode } :
-                search.matches.field.items[0] ? { kind: "field", schemaCode: search.matches.field.items[0].schemaCode, code: search.matches.field.items[0].code } :
-                    search.matches.service.items[0] ? { kind: "service", schemaCode: "", code: search.matches.service.items[0].code } :
-                        search.rules[0] ? { kind: "rule", schemaCode: search.rules[0].schemaCode, code: search.rules[0].ruleCode } : undefined;
+            const decorate = (row) => withMatchedOn({ ...row, ...(row.schemaCode && row.code === undefined ? { code: row.schemaCode } : {}) }, query);
+            const decoratedMatches = { ...search.matches, model: { ...search.matches.model, items: search.matches.model.items.map(decorate) }, field: { ...search.matches.field, items: search.matches.field.items.map(decorate) }, service: { ...search.matches.service, items: search.matches.service.items.map(decorate) } };
+            const noEntityHit = search.matches.model.total === 0 && search.matches.field.total === 0 && search.matches.service.total === 0;
+            const composite = /\s|\+|,|\b(?:AND|OR)\b/i.test(query);
             const searchNote = "实体检索：业务名/实体 name+code 使用子串匹配。\n规则检索：规则 code+name 使用词首匹配（中文子串不命中）。";
             const entityTruncated = Object.values(search.matches).some((match) => match.truncated === true);
-            const paginationNote = entityTruncated ? `\n结果已截断：共 N 条时请使用对应 match 的 nextOffset，并在下一次调用传 offset=nextOffset、limit=${limit} 取下一段。` : "";
+            const nextCall = entityTruncated ? Object.fromEntries(Object.entries(search.matches).filter(([, m]) => m.truncated).map(([k, m]) => [k, { query, kind: k, offset: m.nextOffset, limit }])) : undefined;
+            const paginationNote = entityTruncated ? `\n结果已截断：请使用 nextCall 中对应调用继续。` : "";
             return toolResult({
                 status: "ok",
                 query,
                 found: resolvedEntity !== undefined,
-                ...(resolvedEntity ? { resolved: resolvedEntity } : {}),
+                ...(resolvedEntity ? { resolved: { kind: resolvedEntity.kind, schemaCode: "schemaCode" in resolvedEntity ? resolvedEntity.schemaCode : "", code: resolvedEntity.code, matchedOn: { on: resolvedEntity.name.includes(query) ? "name" : "code", fragment: query } } } : {}),
+                ...(ambiguous ? { ambiguous: true, candidates: exactSame.map((r) => ({ schemaCode: r.schemaCode, code: r.code, name: r.name })) } : {}),
                 ...(kind !== undefined ? { kind } : {}),
                 index,
                 references,
                 impact,
-                search: { count: search.rules.length, rules: search.rules, matches: search.matches, coverage: search.coverage },
+                search: { count: search.rules.length, rules: search.rules, matches: decoratedMatches, coverage: search.coverage },
+                ...(nextCall ? { nextCall } : {}),
+                ...(noEntityHit && composite ? { unsupportedQuerySyntax: true, hint: "组合检索暂不支持，请拆词单查后求交" } : {}),
+                ...(noEntityHit ? { suggestions: suggestions(query), hint: "可尝试 suggestions 中的实体 code/name；引用明细请使用匹配 code 查 references/impact" } : {}),
                 searchNote: `${searchNote}${paginationNote}`,
                 ...(search.note ? { searchNote: `${searchNote}\n${search.note}` } : {}),
                 // 旧句「索引不含规则条件叶子与流程绑定」漏了表单与流程权限（r35a-F4 实证

package/dist/tool-types.js

@@ -187,6 +187,14 @@ const CONTEXTUAL_KEY_GUIDANCE = Object.freeze({
         precision: "precision→options.scale（数值小数位，不是顶层 precision）",
     }),
 });
+// A key can be valid for a sibling tool while still being invalid here. That
+// is a capability-routing problem, not a spelling problem, so do not present
+// the misleading "no close key" sentence. Keep this explicit and narrow: an
+// arbitrary key must continue to use the ordinary closest-key hint.
+const SIBLING_TOOL_KEY_HINTS = Object.freeze({
+    "app.update": Object.freeze({ name: '"name" 是 app.create 的入参；app.update 不收它' }),
+    "model.create": Object.freeze({ fields: '"fields" 是 configure_model 的入参；model.create 不收它' }),
+});
 function closestSchemaKey(key, schemaKeys) {
     if (schemaKeys.has(key))
         return key;
@@ -249,6 +257,9 @@ export function parseToolInput(tool, input) {
                 const guidance = TWO_STEP_GUIDANCE[tool.name]?.[key] ?? CONTEXTUAL_KEY_GUIDANCE[tool.name]?.[key];
                 if (guidance !== undefined)
                     return guidance;
+                const sibling = SIBLING_TOOL_KEY_HINTS[tool.name]?.[key];
+                if (sibling !== undefined)
+                    return sibling;
                 const semantic = KEY_SEMANTIC_HINTS[key];
                 const contextual = contextualClosestKey(tool.name, key, schemaKeys);
                 const closest = closestSchemaKey(key, schemaKeys);
@@ -259,14 +270,15 @@ export function parseToolInput(tool, input) {
             // 未知键的下一步应指向**正确的那个参数**，不是整份 describe（4–17 KB）。
             // 有近邻时 `--param <nearKey>` 是 150–900 B，且直接回答「本来想写哪个键」。
             // 语境建议优先于编辑距离（r34a-F18：data.delete 的 id 指 requestId 是噪声）。
+            const siblingHints = unknown.map((key) => SIBLING_TOOL_KEY_HINTS[tool.name]?.[key]).filter((hint) => typeof hint === "string");
             const nearestKey = contextualClosestKey(tool.name, unknown[0], schemaKeys) ?? closestSchemaKey(unknown[0], schemaKeys);
             const paramCommand = nearestKey !== undefined ? `omc describe ${tool.name} --param ${nearestKey}` : `omc describe ${tool.name}`;
             throw new ToolInputError({
                 status: "error",
                 blocker: "tool-input-unknown-keys",
                 tool: tool.name,
-                message: `写面工具不接受未知键（会被静默丢弃）：${unknown.join("、")}。${twoStep.length > 0 ? twoStep.join(" ") : `${guidanceLines.length > 0 ? guidanceLines.join("；") : `最接近的合法键：${suggestions.join("；")}`}。参数表：${paramCommand}`}`,
-                ...(twoStep.length > 0 || guidanceLines.length > 0 ? { nextCommand: `omc describe ${tool.name}` } : { nextCommand: paramCommand }),
+                message: `写面工具不接受未知键（会被静默丢弃）：${unknown.join("、")}。${twoStep.length > 0 ? twoStep.join(" ") : siblingHints.length > 0 ? siblingHints.join("；") : `${guidanceLines.length > 0 ? guidanceLines.join("；") : `最接近的合法键：${suggestions.join("；")}`}。参数表：${paramCommand}`}`,
+                ...(twoStep.length > 0 || guidanceLines.length > 0 || siblingHints.length > 0 ? { nextCommand: `omc describe ${tool.name}` } : { nextCommand: paramCommand }),
                 issues: unknown.map((key) => ({ path: [key], code: "unrecognized_key", message: issueHintFor(key) })),
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "commander": "14.0.3",
-    "omc-core": "0.6.19",
+    "omc-core": "0.6.20",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",
@@ -73,6 +73,6 @@
     "directory": "packages/omc-cli"
   },
   "optionalDependencies": {
-    "@stalfh233/omc-fake-platform": "0.6.19"
+    "@stalfh233/omc-fake-platform": "0.6.20"
   }
 }

package/skills/omc-refusals.md

@@ -11,6 +11,11 @@ Grouped by family. For a specific tool's exact wire and valid shapes, follow the
 Read `result.blocker` (refused) or `result.status`+`result.reason` (uncertain).
 `result.retryable` is advisory only — the family decides what to do.
 
+`status:"refused"` means a local preflight or policy gate stopped the call:
+it necessarily sent zero platform writes; there is no need to second-guess
+whether anything was written. A platform/wire error (`wire-business` or an
+`errcode`) is different: the outcome can be uncertain, so use readback.
+
 ## 1. Write permission declined
 
 - `environment-write-disabled` — the environment profile has `writable:false`.

package/skills/omc-start-here.md

@@ -28,6 +28,11 @@ be treated as a second source. Read this, then follow the topics it names.
    阶梯步骤已内联工具必填参数（`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，读一次就留在后续每一轮窗口）。**带着具体问题（错误码/跨能力语义/某个词）直接 `omc help --search "<词>"`**——跨全部 topic 全文检索，命中节的正文随结果内联返回，一次调用就是答案；**严禁自己写 `for t in …; do omc help $t --all | grep …` 循环**（r18 实测 12 调用/176KB，检索一次 8KB 搞定）。
 1b. **改/删/重命名既有对象前先看影响面（本地规则图索引）**：`omc graph pull --env <env>` 一次拉全平台建本地索引（增量、秒级、带锁与 gap 报告），之后 `omc graph references <service|model|field> <code>` 离线答「谁引用了它」——一调替代逐模型 `rule.get` 枚举（r30 实测影响评估手工枚举 8×rule.get，graph 一调可达）；`impact <kind> <code>` 看爆炸半径、`search <词>` 找规则 code、`status` 看索引新鲜度。索引不含规则条件叶子与流程绑定，命中后仍以 `rule.get` 原文为准。无索引时会拒绝并指路 pull。宿主已接 MCP 时用 `omc mcp-graph --path <项目根>`（工具 `omc_graph_explore`/`omc_graph_status`）。
+
+**图谱只覆盖单应用时怎么按应用盘点（只读）**：先用
+`omc call app.list` 列出应用，再用
+`omc call model.list --args '{"applicationCode":"<code>"}'` 按应用盘点模型。
+graph 索引 coverage 默认只含配置应用；coverage 未命中不等于应用或模型不存在。
 1c. **写后端 Java 源码（在线开发）走工作区而不是一条条 call**：`omc programming pull --env <env> --app <appCode>` 把业务规则源码拉进 `.omc-programming/`（git 可管），改文件后 `omc programming status` → `omc programming apply [--publish]`（逐文件走编程面治理）；图形化规则转编码用 `omc programming adopt --schema <s> --rule <r>`；验证用 `omc programming test --schema <s> --rule <r>`（fixture 驱动：compile→publish→触发→断言→清理）。**平台运行时只执行已发布版**：只 save 不 publish 等于没改；publish 内部会编译并把规则切 CODING+enable。包路径/类名不得改。
 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`。