@mycodemap/mycodemap 0.5.2-beta.1 → 2.0.0

package/dist/server/mcp/schema-adapter.js

@@ -0,0 +1,290 @@
+// [META] since:2026-04-30 | owner:server-team | stable:false
+// [WHY] Adapt CLI interface contract schema to MCP tool definitions with zero handwritten maintenance
+import { z } from 'zod';
+/**
+ * Convert a single contract flag definition into a Zod schema.
+ * Handles type mapping, arrays, defaults, optionality, and descriptions.
+ */
+export function convertFlagTypeToZod(flag) {
+    let schema;
+    switch (flag.type) {
+        case 'string': {
+            schema = z.string();
+            break;
+        }
+        case 'boolean': {
+            schema = z.boolean();
+            break;
+        }
+        case 'number': {
+            schema = z.number();
+            break;
+        }
+        default: {
+            // Graceful degradation for unknown flag types
+            schema = z.string();
+        }
+    }
+    if (flag.multiple) {
+        schema = z.array(schema);
+    }
+    if (flag.defaultValue !== undefined) {
+        schema = schema.default(flag.defaultValue);
+    }
+    else if (!flag.required) {
+        schema = schema.optional();
+    }
+    if (flag.description) {
+        schema = schema.describe(flag.description);
+    }
+    return schema;
+}
+/**
+ * Convert an array of flag definitions into a Zod raw shape object
+ * suitable for the MCP SDK's `inputSchema` field.
+ */
+export function convertFlagsToZodShape(flags) {
+    const shape = {};
+    for (const flag of flags) {
+        shape[flag.name] = convertFlagTypeToZod(flag);
+    }
+    return shape;
+}
+/**
+ * Recursively convert an OutputProperty into a JSON Schema fragment.
+ * Falls back to permissive schemas on unexpected depth or complexity.
+ */
+function convertOutputPropertyToJsonSchema(prop, depth = 0) {
+    // Prevent runaway recursion on deeply nested or circular schemas
+    if (depth > 10) {
+        return { type: 'object', description: 'Nested structure (depth limit reached)' };
+    }
+    const schema = {};
+    if (prop.description) {
+        schema.description = prop.description;
+    }
+    if (prop.nullable) {
+        schema.type = [prop.type, 'null'];
+    }
+    else {
+        schema.type = prop.type;
+    }
+    if (prop.items) {
+        schema.items = convertOutputPropertyToJsonSchema(prop.items, depth + 1);
+    }
+    if (prop.properties && prop.properties.length > 0) {
+        schema.properties = Object.fromEntries(prop.properties.map(p => [p.name, convertOutputPropertyToJsonSchema(p, depth + 1)]));
+    }
+    return schema;
+}
+/**
+ * Convert an OutputShape into a JSON Schema object.
+ * Degrades gracefully to a permissive object schema on failure.
+ */
+export function convertOutputShapeToJsonSchema(outputShape) {
+    try {
+        const properties = {};
+        const required = [];
+        for (const prop of outputShape.properties) {
+            properties[prop.name] = convertOutputPropertyToJsonSchema(prop);
+            if (!prop.nullable) {
+                required.push(prop.name);
+            }
+        }
+        const schema = {
+            type: outputShape.type,
+            properties,
+        };
+        if (required.length > 0) {
+            schema.required = required;
+        }
+        if (outputShape.description) {
+            schema.description = outputShape.description;
+        }
+        return schema;
+    }
+    catch {
+        return {
+            type: 'object',
+            description: outputShape.description ?? 'Command output',
+        };
+    }
+}
+/**
+ * Convert an OutputProperty into a Zod schema.
+ * Degrades to z.any() for complex or unsupported structures.
+ */
+function outputPropertyToZodSchema(prop, depth = 0) {
+    if (depth > 10) {
+        return z.any().describe(prop.description ?? 'Nested structure');
+    }
+    let schema;
+    switch (prop.type) {
+        case 'string': {
+            schema = z.string();
+            break;
+        }
+        case 'number': {
+            schema = z.number();
+            break;
+        }
+        case 'boolean': {
+            schema = z.boolean();
+            break;
+        }
+        case 'null': {
+            schema = z.null();
+            break;
+        }
+        case 'array': {
+            schema = prop.items
+                ? z.array(outputPropertyToZodSchema(prop.items, depth + 1))
+                : z.array(z.any());
+            break;
+        }
+        case 'object': {
+            if (prop.properties && prop.properties.length > 0) {
+                const shape = {};
+                for (const p of prop.properties) {
+                    shape[p.name] = outputPropertyToZodSchema(p, depth + 1);
+                }
+                schema = z.object(shape);
+            }
+            else {
+                schema = z.record(z.string(), z.any());
+            }
+            break;
+        }
+        default: {
+            schema = z.any();
+        }
+    }
+    if (prop.nullable) {
+        schema = schema.nullable();
+    }
+    if (prop.description) {
+        schema = schema.describe(prop.description);
+    }
+    return schema;
+}
+/**
+ * Convert an OutputShape into a Zod schema suitable for the MCP SDK's `outputSchema` field.
+ * Degrades gracefully to z.any() on failure.
+ */
+export function convertOutputShapeToZodSchema(outputShape) {
+    try {
+        if (outputShape.type === 'array') {
+            const itemSchema = outputShape.properties.length === 1
+                ? outputPropertyToZodSchema(outputShape.properties[0])
+                : z.any();
+            let schema = z.array(itemSchema);
+            if (outputShape.description) {
+                schema = schema.describe(outputShape.description);
+            }
+            return schema;
+        }
+        const shape = {};
+        for (const prop of outputShape.properties) {
+            shape[prop.name] = outputPropertyToZodSchema(prop);
+        }
+        let schema = z.object(shape);
+        if (outputShape.description) {
+            schema = schema.describe(outputShape.description);
+        }
+        return schema;
+    }
+    catch {
+        return z.any().describe(outputShape.description ?? 'Command output');
+    }
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9@+_./:-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function buildCliCommandLine(contract, args, programName = 'codemap') {
+    const flagArgs = Object.entries(args)
+        .filter(([, v]) => v !== undefined && v !== '' && v !== false && !(Array.isArray(v) && v.length === 0))
+        .map(([k, v]) => {
+        if (Array.isArray(v)) {
+            return v.map(item => `--${k} ${shellQuote(String(item))}`).join(' ');
+        }
+        if (typeof v === 'boolean') {
+            return `--${k}`;
+        }
+        return `--${k} ${shellQuote(String(v))}`;
+    })
+        .join(' ');
+    return `${programName} ${contract.name}${flagArgs ? ` ${flagArgs}` : ''}`;
+}
+function createCliAvailabilityHandler(contract, programName) {
+    return async (args) => {
+        const commandLine = buildCliCommandLine(contract, args, programName);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Command available via CLI: ${commandLine}`,
+                }],
+            structuredContent: {
+                status: 'cli_redirect',
+                command: contract.name,
+                args,
+                cliCommand: commandLine,
+                description: contract.description,
+                examples: contract.examples,
+                errorCodes: contract.errorCodes.map(e => e.code),
+            },
+            isError: false,
+        };
+    };
+}
+/**
+ * Zod schema matching the structured content returned by cli_redirect handlers.
+ * Used as the output schema for contract tools until handlers return real command output.
+ *
+ * NOTE: `z.unknown()` is used for `args` instead of `z.record(z.unknown())` because
+ * Zod v4's `z.record()` triggers a crash in `z4mini.toJSONSchema` when the SDK
+ * serializes the schema for `listTools()` discovery.
+ */
+const cliRedirectOutputSchema = z.object({
+    status: z.literal('cli_redirect'),
+    command: z.string(),
+    args: z.unknown(),
+    cliCommand: z.string(),
+    description: z.string(),
+    examples: z.array(z.string()),
+    errorCodes: z.array(z.string()),
+});
+/**
+ * Convert a CommandContract into one or more MCP tool definitions.
+ * The primary command and any aliases each get their own tool name.
+ */
+export function convertContractToMcpTools(contract, programName = 'codemap') {
+    const definitions = [];
+    const inputSchema = convertFlagsToZodShape(contract.flags);
+    definitions.push({
+        name: `codemap_${contract.name}`,
+        config: {
+            title: `CodeMap ${contract.name}`,
+            description: `${contract.description}\n\nExamples:\n${contract.examples.join('\n')}`,
+            inputSchema,
+            outputSchema: cliRedirectOutputSchema,
+        },
+        handler: createCliAvailabilityHandler(contract, programName),
+    });
+    for (const alias of contract.aliases ?? []) {
+        definitions.push({
+            name: `codemap_${alias}`,
+            config: {
+                title: `CodeMap ${alias}`,
+                description: `${contract.description} (alias for ${contract.name})\n\nExamples:\n${contract.examples.join('\n')}`,
+                inputSchema,
+                outputSchema: cliRedirectOutputSchema,
+            },
+            handler: createCliAvailabilityHandler({ ...contract, name: alias }, programName),
+        });
+    }
+    return definitions;
+}
+//# sourceMappingURL=schema-adapter.js.map

package/dist/server/mcp/schema-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-adapter.js","sourceRoot":"","sources":["../../../src/server/mcp/schema-adapter.ts"],"names":[],"mappings":"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"}

package/dist/server/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/server/mcp/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAOjE,MAAM,WAAW,4BAA4B;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAuDD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAUnE;AAED,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC;IACT,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,QAAQ,CAAC;IAClB,SAAS,EAAE,oBAAoB,CAAC;IAChC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC,CAiBD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/server/mcp/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAUjE,MAAM,WAAW,4BAA4B;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAqFD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAanE;AAED,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC;IACT,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,QAAQ,CAAC;IAClB,SAAS,EAAE,oBAAoB,CAAC;IAChC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC,CAiBD"}

package/dist/server/mcp/server.js

@@ -5,13 +5,15 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { createConfiguredStorage } from '../../cli/storage-runtime.js';
+import { getFullContract } from '../../cli/interface-contract/index.js';
 import { CodeMapMcpService } from './service.js';
+import { convertContractToMcpTools } from './schema-adapter.js';
 const MCP_SERVER_NAME = 'mycodemap-experimental';
 const MCP_SERVER_VERSION = process.env.npm_package_version ?? '0.5.0';
 function renderStructuredContent(result) {
     return JSON.stringify(result, null, 2);
 }
-function registerTools(server, service) {
+function registerNativeTools(server, service) {
     server.registerTool('codemap_query', {
         title: 'CodeMap Query',
         description: 'Experimental: query a symbol definition plus callers and callees from the local CodeMap graph.',
@@ -56,13 +58,41 @@ function registerTools(server, service) {
         };
     });
 }
+function registerContractTools(server, contract, reservedNames) {
+    const registeredNames = new Set(reservedNames);
+    for (const command of contract.commands) {
+        const definitions = convertContractToMcpTools(command, contract.programName);
+        for (const def of definitions) {
+            let toolName = def.name;
+            // If a native tool occupies this name, register under a stable alternative
+            if (registeredNames.has(toolName)) {
+                const altName = `${toolName}_contract`;
+                if (registeredNames.has(altName)) {
+                    console.warn(`Contract tool "${def.name}" skipped — name reserved by native tool and alternative "${altName}" also taken`);
+                    continue;
+                }
+                console.warn(`Contract tool "${def.name}" renamed to "${altName}" — name reserved by native tool`);
+                toolName = altName;
+            }
+            registeredNames.add(toolName);
+            server.registerTool(toolName, {
+                title: def.config.title,
+                description: def.config.description,
+                inputSchema: def.config.inputSchema,
+                outputSchema: def.config.outputSchema,
+            }, async (args) => def.handler(args));
+        }
+    }
+}
 export function createCodeMapMcpServer(storage) {
     const server = new McpServer({
         name: MCP_SERVER_NAME,
         version: MCP_SERVER_VERSION,
     });
     const service = new CodeMapMcpService(storage);
-    registerTools(server, service);
+    const reservedNames = new Set(['codemap_query', 'codemap_impact']);
+    registerNativeTools(server, service);
+    registerContractTools(server, getFullContract(), reservedNames);
     return server;
 }
 export async function startCodeMapMcpServer(options = {}) {

package/dist/server/mcp/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/mcp/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/mcp/server.ts"],"names":[],"mappings":"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"}

package/docs/AI_ASSISTANT_SETUP.md

@@ -24,6 +24,10 @@ MyCodeMap 可以与多种 AI 编程助手集成，让 AI 能够：
 - 📊 **依赖分析** - 理解项目结构和模块关系
 - ⚡ **影响评估** - 分析代码变更的影响范围
 - 🛡️ **质量门禁** - 自动执行 CI 检查
+- 🩺 **持续健康诊断** (`doctor`) - 安装 / 配置 / 运行时 / Agent 四类健康检查
+- 🧬 **WASM 回退** - 当 Native 依赖不可用时自动切换 WASM 实现
+- 📜 **接口契约自省** (`--schema`) - 输出完整 CLI 契约 JSON，供 Agent 动态发现能力
+- 🔌 **MCP 自动网关** - 所有 Schema 定义的 CLI 命令自动暴露为 MCP tools，动态注册
 
 ### 快速选择
 
@@ -53,7 +57,7 @@ MyCodeMap 可以与多种 AI 编程助手集成，让 AI 能够：
 - 也可以通过 `mycodemap ci check-docs-sync` 走统一的 CI 子命令入口
 - 当前仓库的 agent 工程规则以 `docs/rules/engineering-with-codex-openai.md` 为准
 - 若文档或提示词仍把 `server`、`watch`、`report`、`logs` 当成当前 public CLI，必须同步改成 removed-command 迁移说明
-- 若项目启用了 `mycodemap.config.json.storage` 的 `sqlite`，先确认 `better-sqlite3` 已安装且 Node.js `>=20`；若仍看到 `kuzudb` / `neo4j` 配置，应先迁移再让 AI 判断 graph backend 失败原因
+- 若项目启用了 `.mycodemap/config.json` 中 `storage.type = "sqlite"`，先确认 `better-sqlite3` 已安装且 Node.js `>=20`；若仍看到 `kuzudb` / `neo4j` 配置，应先迁移再让 AI 判断 graph backend 失败原因
 
 ---
 
@@ -138,23 +142,20 @@ $CODEMAP_CMD complexity -f "<file-path>"
 
 ### 统一分析入口（analyze）
 ```bash
-# 影响分析
-$CODEMAP_CMD analyze -i impact -t "<file-path>"
+# 符号查找
+$CODEMAP_CMD analyze -i find -s "<symbol-name>"
 
-# 依赖分析
-$CODEMAP_CMD analyze -i dependency -t "<module-path>"
-
-# 复杂度分析
-$CODEMAP_CMD analyze -i complexity -t "<path>"
+# 代码读取（含上下文）
+$CODEMAP_CMD analyze -i read -t "<file-path>" --scope transitive
 
-# 搜索分析
-$CODEMAP_CMD analyze -i search -k "<keyword>"
+# 依赖链接分析
+$CODEMAP_CMD analyze -i link -t "<module-path>"
 
-# 项目概览
-$CODEMAP_CMD analyze -i overview -t "<path>"
+# 项目概览展示
+$CODEMAP_CMD analyze -i show -t "<path>"
 
 # JSON 输出
-$CODEMAP_CMD analyze -i impact -t "<file>" --json
+$CODEMAP_CMD analyze -i find -s "<symbol>" --json
 ```
 
 ### CI 门禁（ci）
@@ -422,7 +423,9 @@ mycodemap impact -f "src/file.ts"
 
 ## 关键文件
 
-- `mycodemap.config.json` - CodeMap 配置文件
+- `.mycodemap/config.json` - CodeMap canonical 配置文件
+- `.mycodemap/status/init-last.json` - init receipt / managed asset ledger
+- `.mycodemap/rules/` - 通用 AI guardrails rules bundle（需手动引用到 `CLAUDE.md` / `AGENTS.md`）
 - `.mycodemap/AI_MAP.md` - 项目全局概览
 
 ## 开发规范
@@ -806,6 +809,162 @@ npm install --save-dev @mycodemap/mycodemap
 
 ---
 
+## AI CLI 一键安装引导
+
+> 本章节面向 AI CLI 工具（Claude Code、Codex CLI 等），提供结构化安装引导。
+> 当用户说"帮我安装 mycodemap"时，AI CLI 应按照以下步骤引导。
+
+### Step 1: 前置条件检查 [CONFIRM]
+
+在开始安装前，确认以下条件：
+
+- Node.js >= 18 是否已安装（`node --version`）
+- 当前项目是否有 package.json（`ls package.json`）
+- 向用户确认：是项目级别安装还是全局安装
+
+### Step 2: 安装依赖 [CONFIRM]
+
+```bash
+# 项目级别安装（推荐）
+npm install @mycodemap/mycodemap
+
+# 或全局安装
+npm install -g @mycodemap/mycodemap
+```
+
+### Step 3: 初始化 [CONFIRM]
+
+```bash
+# 先预览配置（不写入文件）
+mycodemap init
+
+# 确认后写入
+mycodemap init -y
+```
+
+### Step 4: 生成代码地图
+
+```bash
+mycodemap generate
+```
+
+安装完成后会生成：
+- `.mycodemap/AI_MAP.md` — 项目全局概览
+- `.mycodemap/codemap.json` — 结构化数据
+- `.mycodemap/CONTEXT.md` — 上下文入口
+
+### Step 5: 环境健康诊断 [CONFIRM]
+
+运行 `codemap doctor` 验证环境健康状态：
+
+```bash
+# 运行全部诊断（安装 / 配置 / 运行时 / Agent）
+codemap doctor
+
+# 或按类别诊断
+codemap doctor --category install
+codemap doctor --category config
+codemap doctor --category runtime
+codemap doctor --category agent
+```
+
+诊断输出为结构化 JSON，包含 `rootCause` + `remediationPlan` + `confidence` + `nextCommand`。修复所有 HIGH 级别问题后再继续。
+
+### Step 6: 查看接口契约 [CONFIRM]
+
+运行 `codemap --schema` 查看完整 CLI 接口契约，供 Agent 自省：
+
+```bash
+# 输出完整契约 JSON
+codemap --schema
+
+# 或保存到文件供 skill 引用
+codemap --schema > .mycodemap/interface-contract.json
+```
+
+契约包含所有命令、参数、输出格式的结构化定义，是 MCP Gateway 动态暴露 tools 的单一数据源。
+
+### Step 7: 配置 AI 助手 skill [CONFIRM]
+
+根据使用的 AI 助手，拷贝对应的 skill 文件：
+
+**Claude Code:**
+```bash
+mkdir -p .claude/skills/codemap
+cp node_modules/@mycodemap/mycodemap/examples/claude/codemap-skill.md .claude/skills/codemap/SKILL.md
+
+# 可选：安装架构分析技能（Phase 48 已交付）
+mkdir -p .claude/skills/mycodemap-repo-analyzer
+cp node_modules/@mycodemap/mycodemap/examples/claude/skills/mycodemap-repo-analyzer/SKILL.md .claude/skills/mycodemap-repo-analyzer/SKILL.md
+cp -r node_modules/@mycodemap/mycodemap/examples/claude/skills/mycodemap-repo-analyzer/references .claude/skills/mycodemap-repo-analyzer/
+```
+
+**Codex CLI:**
+```bash
+mkdir -p .agents/skills/codemap
+cp node_modules/@mycodemap/mycodemap/examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
+```
+
+### Step 8: 更新项目 rules [CONFIRM]
+
+在项目的 `CLAUDE.md` 和 `AGENTS.md` 中追加以下内容：
+
+```markdown
+## CodeMap Skill
+
+### 何时使用
+- 需要理解项目整体结构或模块关系
+- 分析代码变更的影响范围
+- 查询符号定义、调用关系、依赖链
+- 评估代码复杂度或检测循环依赖
+
+### 何时不用
+- 简单的单文件修改或调试
+- 非代码文件操作（文档、配置等）
+- 已有明确上下文的局部改动
+
+### 如何使用
+- 参考 .claude/skills/codemap/ 中的 skill 指令
+- 使用 mycodemap CLI 命令（generate/query/impact/deps/cycles/complexity）
+
+### 索引维护
+- 代码变更后需运行 `mycodemap generate` 更新索引
+- 在重大功能开发/重构完成后，主动更新一次
+- 如发现 mycodemap 查询结果与代码不一致，先更新索引再使用
+```
+
+### Step 9: 验证安装
+
+```bash
+# 验证 CLI 可用
+mycodemap query --help
+
+# 验证 doctor 可用
+codemap doctor --help
+
+# 验证 schema 输出
+codemap --schema | head -20
+
+# 验证 skill 文件已就位
+ls .claude/skills/codemap/SKILL.md
+```
+
+### 可选：MCP 服务器配置
+
+CodeMap v2.0 采用 **CLI-as-MCP 自动网关**：所有 Schema 定义的 CLI 命令自动暴露为 MCP tools，无需手动维护 tool 列表。
+
+```bash
+# 安装 MCP 适配器（一次性）
+codemap mcp install
+
+# 验证动态 tool 注册（应列出 20+ 个 tools）
+codemap mcp list-tools
+```
+
+配置完成后，AI 助手可通过 MCP 调用任意 `codemap` 命令（如 `doctor`、`benchmark`、`analyze`、`query` 等），Gateway 会根据 Interface Contract Schema 动态生成 tool 定义。无需再使用实验性的 2-tool 限制模式。
+
+---
+
 ## 参考
 
 - [SETUP_GUIDE.md](./SETUP_GUIDE.md) - 人类用户安装指南