@stalfh233/omc-cli 0.5.2 → 0.5.3

package/dist/cli.js

@@ -1839,7 +1839,7 @@ async function main() {
     });
     // ADR-0008: local derived rule-graph index — CLI management face, not a call
     // tool (so it stays out of `commands --json`/coverage by construction).
-    const graphCommand = command.command("graph").description("本地派生规则图索引（ADR-0008）：pull 全量重建（有界并发）/ references 离线引用 / impact 影响面 / search 规则全文 / status 完整性与新鲜度。候选定位器——不进 baseline/plan/写门禁");
+    const graphCommand = command.command("graph").description("本地派生规则图索引（ADR-0008）：pull 全量重建（有界并发）/ references 离线引用 / impact 影响面 / search 规则 code+name 检索（非规则体）/ status 完整性与新鲜度。候选定位器——不进 baseline/plan/写门禁");
     graphCommand.command("pull").option("--env <environment>").option("--environment <environment>").option("--concurrency <n>", "并发 wire 读数（1–32，默认 16）：拉取已流水线化，墙钟 ≈ max(模型面,规则面)/并发 × 延迟；过高可能触发平台限流形成缺口").option("--max-output-bytes <bytes>").addHelpText("after", "\n只读远端（model.list → 每模型 rule.list+datarule.list → 每规则 rule.get，统一任务池流水线并发）+ 本地原子重建；不写环境、不占环境写锁。新鲜度随结果回报（complete|partial），查询走 graph references / impact / search。\n").action(async (options) => {
         const parsed = options.concurrency === undefined ? undefined : Number.parseInt(String(options.concurrency), 10);
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphPull(options.environment ?? options.env, parsed, transport));
@@ -1850,12 +1850,24 @@ async function main() {
     graphCommand.command("impact <kind> <code>").option("--max-output-bytes <bytes>").addHelpText("after", "\n影响面（离线）：跳1=引用该编码的规则（同 references），跳2=这些规则还读写哪些 service/model/field——改前看爆炸半径。截断上限 50 规则×每类 20 码。\n").action(async (kind, code, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphImpact(kind, code, transport));
     });
-    graphCommand.command("search <term...>").option("--max-output-bytes <bytes>").addHelpText("after", "\n规则全文检索（code+name，FTS5，末词前缀匹配）：找到\"关于 X 的规则\"拿 code，再走 references/impact。中文需给全词或词首（如 报名*）。\n").action(async (term, options) => {
+    graphCommand.command("search <term...>").option("--max-output-bytes <bytes>").addHelpText("after", "\n检索规则的 code+name（FTS5，末词前缀匹配；**不含规则体/配置内容**）。找到\"关于 X 的规则\"拿 code，再走 references/impact。中文必须是全词或词首通配（如 报名* / 增加预算*）——子串不命中：FTS5 把「增加预算」当一个 token，搜「预算」为 0。\n").action(async (term, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphSearch(term.join(" "), transport));
     });
     graphCommand.command("status").option("--max-output-bytes <bytes>").action(async (options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphStatus(transport));
     });
+    // MCP stdio server (host registration: cpdocs installer's omc-graph entry;
+    // top-level verb like `codegraph serve --mcp`, not a graph subcommand).
+    // hidden like the graph lane — a transport, not a user verb. Only JSON-RPC
+    // may reach stdout from here; envelopes/banners never do.
+    command
+        .command("mcp-graph", { hidden: true })
+        .description("以 MCP stdio 服务器运行规则图检索（工具：omc_graph_explore / omc_graph_status）")
+        .option("--path <dir>", "项目根目录（定位 .omc/graph/graph.db；MCP 注册时传绝对路径，不信任宿主 cwd）")
+        .action(async (options) => {
+        const { runMcpGraphServer } = await import("./mcp-graph.js");
+        commandExitCode = await runMcpGraphServer(options.path);
+    });
     // `--jq` expressions the shell split arrive as several tokens; re-join them.
     await command.parseAsync(joinSplitFlagValues(stripOutputFlags(argv), ["--jq"]));
     return commandExitCode;

package/dist/graph.js

@@ -644,7 +644,14 @@ export function searchGraphRules(term, limit = 20) {
             rules: matches,
             index: summary,
             ...(matches.length === 0
-                ? { note: tokens.length === 0 ? "检索词为空" : "没有命中规则（code+name 全文；引用检索用 references/impact <kind> <code>）" }
+                ? {
+                    note: tokens.length === 0
+                        ? "检索词为空"
+                        // 实测摩擦（2026-10-30，zlt测试）：中文子串 0 命中后没有下一步提示，
+                        // 调用方在「换个词再试」里打转。把两个出口都写进 note：CJK 词首
+                        // 通配 + 找引用走 references/impact。
+                        : "没有命中规则。索引只覆盖规则的 code+name（不含规则体）；且只匹配**词首**——FTS5 把「增加预算」当一个词，「预算」匹配不到它。请给全词（增加预算）、词首（增加 或 增加*），或英文 code 前缀。找\"谁引用了 X\"请走 references/impact <kind> <code>。",
+                }
                 : {}),
             ...(gapped ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口；命中列表可能不完整` } : {}),
         };

package/dist/mcp-graph.js

@@ -0,0 +1,222 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { GraphIndexAbsentError, graphDbPath, impactGraph, queryGraphReferences, readGraphStatus, searchGraphRules, } from "./graph.js";
+/**
+ * Stdio MCP server for the local rule-graph index (ADR-0008).
+ *
+ * Wire format is the MCP standard — newline-delimited JSON-RPC 2.0 — hand
+ * rolled on purpose: the precedent in this stack (CodeGraph) ships its own
+ * transport too, and omc-cli keeps a single-digit dependency budget. The
+ * protocol surface needed by Claude Code / Codex / WorkBuddy is small:
+ * initialize → tools/list → tools/call (+ping), everything else is -32601.
+ *
+ * Why a server at all (friction evidence, 2026-10-30 zlt测试 session):
+ *   1. CLI return shapes had to be guessed (`rules` mis-read as `matches`);
+ *      MCP tools are self-describing via input/output examples in descriptions.
+ *   2. CJK terms passed through a Windows console got mangled — a process-bound
+ *      JSON pipe is UTF-8 end to end.
+ *   3. Iterative explore→refine→explore paid a full CLI boot per question.
+ *
+ * Read-only by construction: the handlers only query the local SQLite index;
+ * `pull` deliberately stays a CLI verb (it reads the platform for ~a minute).
+ */
+const PROTOCOL_VERSION = "2024-11-05";
+const ownVersion = () => {
+    try {
+        return createRequire(import.meta.url)("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+};
+const SERVER_INFO = { name: "omc-graph", version: ownVersion() };
+const KINDS = ["field", "model", "service"];
+const MATCH_CAP = 50;
+const ERROR_CODES = { parse: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602, internal: -32603 };
+function respond(id, result) {
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, result })}\n`);
+}
+function respondError(id, code, message) {
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error: { code, message } })}\n`);
+}
+const INSTRUCTIONS_INDEXED = [
+    "规则/配置图检索（本地索引，先于逐平台扫描使用）：",
+    "- 改名/删除/重构一个 字段(field)/模型(model)/服务(service) 前，先用 omc_graph_explore 查引用与影响面；查\"谁引用了 X\"也走它。",
+    "- 索引只覆盖：业务规则（methodMapping/targetObjectCode）、数据规则（propertyCodes 与公式 {字段}）、视图（列/排序/条件）。**不含**规则条件叶子与流程绑定。",
+    "- search 语义：只匹配规则 code+name 的**词首**（中文子串不命中：搜「预算」匹配不到「增加预算」）。",
+    "答案带 freshness/pulledAtIso——索引是快照，平台侧改动后需 CLI 重建：omc graph pull --env <env>（只读远端，约 1 分钟）。",
+    "索引绑定单一环境（environmentName）；查别的环境先重新 pull。",
+].join("\n");
+const INSTRUCTIONS_NO_INDEX = [
+    "规则/配置图检索（omc-graph）：当前项目还没有本地索引（<项目>/.omc/graph/graph.db 不存在），工具暂时无法回答。",
+    "先请用户执行 CLI：omc graph pull --env <环境名>（只读远端，约 1 分钟；环境名以 omc doctor 的「环境=」或 .omc-env 为准），完成后再来调用。",
+    "不要在无索引状态下反复重试本工具。",
+].join("\n");
+const EXPLORE_TOOL = {
+    name: "omc_graph_explore",
+    description: [
+        "一次查全一个目标的引用与影响面（本地索引，毫秒级）。",
+        "输入 query=字段/模型/服务的 code（或规则检索词）；kind 可选 field|model|service，不给则三种都查。",
+        "返回 {index(freshness), references:{kind:[{schemaCode,ruleCode,nodeCode,nodeType,via}]}, impact:{kind:totals}, search:{rules}}。",
+        "改/删/重命名任何字段、模型、服务之前必查；找\"关于 X 的规则\"拿 code 也走这里。",
+        "索引不含规则条件叶子与流程绑定；freshness=partial 时命中可能不完整（答案里有 gapWarning）。",
+    ].join(" "),
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "字段/模型/服务的 code，或规则检索词（code+name 词首匹配）" },
+            kind: { type: "string", enum: [...KINDS], description: "限定一种引用种类；省略则 field/model/service 全查" },
+            env: { type: "string", description: "期望的环境名；与索引所属环境不一致时会拒绝（防跨环境误答）" },
+        },
+        required: ["query"],
+    },
+};
+const STATUS_TOOL = {
+    name: "omc_graph_status",
+    description: "索引完整性与新鲜度：environmentName、freshness(complete|partial)、模型/规则计数、pulledAtIso、gaps。回答前先看一眼，索引缺失会给出 pull 指引。",
+    inputSchema: { type: "object", properties: {} },
+};
+export function graphToolDefinitions() {
+    return [EXPLORE_TOOL, STATUS_TOOL];
+}
+function toolResult(payload, isError = false) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }], ...(isError ? { isError: true } : {}) };
+}
+function toolError(message) {
+    return toolResult({ status: "error", message }, true);
+}
+function cap(rows) {
+    return { rows: rows.slice(0, MATCH_CAP), truncated: rows.length > MATCH_CAP };
+}
+/** Shared handler core — exported so tests drive it without a stdio pair. */
+export async function executeGraphTool(name, rawArgs) {
+    const args = (rawArgs ?? {});
+    try {
+        if (name === STATUS_TOOL.name) {
+            const status = readGraphStatus();
+            return toolResult({ status: "ok", ...status });
+        }
+        if (name === EXPLORE_TOOL.name) {
+            const query = typeof args.query === "string" ? args.query.trim() : "";
+            if (!query)
+                return toolError("query 不能为空");
+            const kind = args.kind === undefined ? undefined : String(args.kind);
+            if (kind !== undefined && !KINDS.includes(kind))
+                return toolError(`kind 必须是 ${KINDS.join("|")} 之一`);
+            const status = readGraphStatus();
+            const index = status.index;
+            if (typeof args.env === "string" && args.env.trim() && args.env.trim() !== index.environmentName) {
+                return toolError(`索引属于环境「${index.environmentName}」；要查「${args.env.trim()}」请先 omc graph pull --env ${args.env.trim()} 重建索引`);
+            }
+            const kinds = kind === undefined ? [...KINDS] : [kind];
+            const references = {};
+            const impact = {};
+            for (const one of kinds) {
+                const ref = queryGraphReferences(one, query);
+                const capped = cap(ref.matches);
+                references[one] = { count: ref.matches.length, ...capped, ...(ref.gapWarning ? { gapWarning: ref.gapWarning } : {}) };
+                if (ref.matches.length > 0 || kind !== undefined) {
+                    const imp = impactGraph(one, query);
+                    impact[one] = {
+                        totals: imp.totals,
+                        rules: cap(imp.rules),
+                        datarules: cap(imp.datarules),
+                        listviews: cap(imp.listviews),
+                    };
+                }
+            }
+            const search = searchGraphRules(query);
+            return toolResult({
+                status: "ok",
+                query,
+                ...(kind !== undefined ? { kind } : {}),
+                index,
+                references,
+                impact,
+                search: { count: search.rules.length, rules: search.rules },
+                ...(search.note ? { searchNote: search.note } : {}),
+                note: "索引不含规则条件叶子与流程绑定；改这些面仍需平台侧核查",
+            });
+        }
+        return toolError(`未知工具：${name}`);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError) {
+            return toolError(`本地索引不存在（${graphDbPath()}）。先执行：omc graph pull --env <环境名>（只读远端，约 1 分钟），完成后再调用`);
+        }
+        return toolError(error instanceof Error ? error.message : String(error));
+    }
+}
+async function handleMessage(message) {
+    const id = message.id;
+    if (id === undefined || id === null)
+        return; // notification — no response
+    if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+        respondError(id, ERROR_CODES.invalidRequest, "invalid JSON-RPC 2.0 request");
+        return;
+    }
+    const { method } = message;
+    if (method === "initialize") {
+        const params = (message.params ?? {});
+        const requested = typeof params.protocolVersion === "string" && params.protocolVersion ? params.protocolVersion : PROTOCOL_VERSION;
+        respond(id, {
+            protocolVersion: requested,
+            capabilities: { tools: {} },
+            serverInfo: SERVER_INFO,
+            instructions: existsSync(graphDbPath()) ? INSTRUCTIONS_INDEXED : INSTRUCTIONS_NO_INDEX,
+        });
+        return;
+    }
+    if (method === "ping") {
+        respond(id, {});
+        return;
+    }
+    if (method === "tools/list") {
+        respond(id, { tools: graphToolDefinitions() });
+        return;
+    }
+    if (method === "tools/call") {
+        const params = (message.params ?? {});
+        if (typeof params.name !== "string") {
+            respondError(id, ERROR_CODES.invalidParams, "params.name must be a string");
+            return;
+        }
+        respond(id, await executeGraphTool(params.name, params.arguments));
+        return;
+    }
+    respondError(id, ERROR_CODES.methodNotFound, `method not found: ${method}`);
+}
+/**
+ * Run the stdio server. Resolves when stdin closes (the host went away).
+ * `projectRoot` (from --path) pins the index location exactly like the
+ * codegraph registration does — never trust the host's cwd.
+ */
+export async function runMcpGraphServer(projectRoot) {
+    if (projectRoot)
+        process.chdir(resolve(projectRoot));
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    lines.on("line", (line) => {
+        const text = line.trim();
+        if (!text)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            respondError(null, ERROR_CODES.parse, "parse error");
+            return;
+        }
+        void handleMessage(parsed).catch((error) => {
+            respondError(idOf(parsed), ERROR_CODES.internal, error instanceof Error ? error.message : String(error));
+        });
+    });
+    await new Promise((resolve) => lines.on("close", () => resolve()));
+    return 0;
+}
+function idOf(message) {
+    return message.id ?? null;
+}
+//# sourceMappingURL=mcp-graph.js.map

package/package.json

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