@mycodemap/mycodemap 1.9.0 → 2.0.0

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，动态注册
 
 ### 快速选择
 
@@ -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）
@@ -808,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) - 人类用户安装指南

package/docs/README.md

@@ -1,6 +1,8 @@
 # docs/ - 文档信息架构
 
-本目录采用“入口文档短、细节文档分层”的结构。
+> **v2.0 里程碑上下文**：当前文档体系对应 CodeMap v2.0（”agent-native-foundation”）。v2.0 引入了 CLI-as-MCP 自动网关、接口契约 Schema、WASM-first 构建基础等核心能力。详见下方 [v2.0 文档索引](#v20-文档索引)。
+
+本目录采用”入口文档短、细节文档分层”的结构。
 
 ## 目录职责
 
@@ -11,6 +13,8 @@
 - `docs/product-specs/`：当前仍有效的产品规格与验收边界。
 - `docs/references/`：外部参考、设计系统、工具链资料。
 - `docs/archive/`：历史方案、迁移遗留、过期文档索引。
+- `docs/ai-guide/`：AI / Agent 集成指南（v2.0 新增）。
+- `src/cli/interface-contract/`：接口契约 Schema 定义（单一 Schema 生成 parser、MCP tool 定义、`--help-json`、shell 补全）。
 
 ## 当前状态
 
@@ -19,6 +23,20 @@
 - `docs/design-docs/` 与 `docs/product-specs/` 当前不再保留旧稿；历史内容请从 `docs/archive/README.md` 进入。
 - 新增内容优先写入分层目录，不再把新设计或新计划继续堆到根层。
 
+### v2.0 功能状态
+
+v2.0（"agent-native-foundation"）已引入以下核心能力，相关文档已就位：
+
+| 功能 | 状态 | 文档位置 |
+|------|------|----------|
+| **CLI-as-MCP 自动网关** | 已交付 | `docs/ai-guide/INTEGRATION.md` |
+| `codemap doctor` 持续健康诊断 | 已交付 | `AI_GUIDE.md` + `src/cli/doctor/` |
+| `codemap benchmark` WASM/Native 性能对比 | 已交付 | `AI_GUIDE.md` |
+| `--schema` 接口契约输出 | 已交付 | `AI_GUIDE.md` + `src/cli/interface-contract/` |
+| WASM-first 构建基础 | 已交付 | `AI_GUIDE.md` + `src/cli/loaders/` |
+| AI-First 默认输出（JSON/NDJSON） | 已交付 | `AI_GUIDE.md` |
+| Failure-to-Action 协议 | 已交付 | `docs/rules/harness.md` |
+
 ## 建议阅读顺序
 
 1. `../AGENTS.md`
@@ -28,6 +46,27 @@
 5. 与任务最相关的现行文档；如需历史背景，再看 `docs/archive/README.md`
 6. 如需过程信息，再看 `docs/exec-plans/*`
 
+## v2.0 文档索引
+
+以下文档涵盖 v2.0 核心功能，按主题分类：
+
+### AI / Agent 集成
+- `docs/ai-guide/INTEGRATION.md` — CLI-as-MCP 自动网关配置指南（动态 tool 注册、20+ 命令自动暴露）
+- `docs/ai-guide/AI_ASSISTANT_SETUP.md` — AI 助手（Kimi、Claude、Codex、Cursor、Copilot）集成配置
+- `AI_GUIDE.md` — CodeMap CLI / MCP / AI 使用总览（含 `doctor`、`benchmark`、`--schema` 用法）
+
+### 接口契约与 Schema
+- `src/cli/interface-contract/` — 单一 Schema 源文件（生成 parser、MCP tool 定义、`--help-json`、shell 补全）
+- 运行 `codemap --schema` 可输出完整契约 JSON，供 Agent 自省
+
+### Harness 与 Agent 控制
+- `docs/rules/harness.md` — Harness 设计、Agent 控制、上下文分层、权限升级策略
+- `docs/rules/harness.md` — Failure-to-Action 协议（每个错误返回 `rootCause` + `remediationPlan` + `confidence` + `nextCommand`）
+
+### 架构与构建
+- `ARCHITECTURE.md` — 架构分层、依赖方向、模块边界
+- `src/cli/loaders/` — WASM-first 构建基础（`tree-sitter` → `web-tree-sitter`；`better-sqlite3` → `node:sqlite` / `sql.js`）
+
 ## 维护规则
 
 - 入口文档只做导航，不复述大段细节。

package/docs/SETUP_GUIDE.md

@@ -210,24 +210,21 @@ mycodemap impact -f src/cli/index.ts --transitive
 ### 统一分析（analyze）
 
 ```bash
-# 影响分析
-mycodemap analyze -i impact -t src/cli/index.ts
-mycodemap analyze -i impact -t src/cli/index.ts --scope transitive --include-tests
+# 搜索符号或文件
+mycodemap analyze -i find -k "UnifiedResult" --topK 10
 
-# 依赖分析
-mycodemap analyze -i dependency -t src/orchestrator
+# 读取代码范围
+mycodemap analyze -i read -t src/cli/index.ts
+mycodemap analyze -i read -t src/cli/index.ts --scope transitive --include-tests
 
-# 复杂度分析
-mycodemap analyze -i complexity -t src/domain
+# 查看模块依赖关系
+mycodemap analyze -i link -t src/orchestrator
 
-# 搜索分析
-mycodemap analyze -i search -k "UnifiedResult" --topK 10
+# 展示项目概览或复杂度
+mycodemap analyze -i show -t src/
 
-# 项目概览
-mycodemap analyze -i overview -t src/
-
-# JSON 输出
-mycodemap analyze -i impact -t src/index.ts --json
+# JSON 结构化输出
+mycodemap analyze -i find -k "UnifiedResult" --json --structured
 ```
 
 ### 工作流编排（workflow）

package/docs/ai-guide/COMMANDS.md

@@ -2,8 +2,9 @@
 
 > 完整的 CLI 命令详解
 >
-> CodeMap 是 AI-first 代码地图工具。以下文档记录当前公开命令，并补充已移除命令的迁移提示。  
-> 当前 CLI 过渡现实：多数命令显式使用 `--json` 输出机器可读结果；`analyze` 额外支持 `--output-mode machine|human`。
+> CodeMap 是 AI-Native 优先、人类友好的代码架构治理基础设施。以下文档记录当前公开命令，并补充已移除命令的迁移提示。  
+> 命名规范：公开命令示例统一使用 `mycodemap`；`codemap` 只作为兼容别名保留，不作为新示例首选。  
+> v2.0 AI-First Default Output：默认输出 JSON/NDJSON（非 TTY 或显式 `--json`），人类阅读使用 `--human` 或 TTY 自动检测。
 
 ---
 
@@ -124,7 +125,9 @@ mycodemap impact -f "src/cli/index.ts" -j   # JSON 输出
 
 ---
 
-### mcp - experimental 本地 MCP 集成
+### mcp - MCP 集成 (CLI-as-MCP Automatic Gateway)
+
+> v2.0 升级为 CLI-as-MCP Automatic Gateway。所有 20+ schema 定义的 CLI 命令自动暴露为 MCP tools；动态 tool 注册。
 
 ```bash
 mycodemap mcp install                     # 把当前仓库写入 .mcp.json
@@ -134,14 +137,14 @@ mycodemap generate --symbol-level         # 使用前必须先生成 symbol-leve
 
 | 子命令 | 说明 |
 |--------|------|
-| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap-experimental` server entry |
-| `start` | 启动 local-only / read-only / stdio-first experimental MCP server |
+| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap` server entry |
+| `start` | 启动 local-only / read-only / stdio-first MCP server |
 
-**首期规则**:
-- `mcp` 是 experimental surface，不要把它当成稳定长期 public API。
+**v2.0 行为**:
+- CLI-as-MCP Automatic Gateway：所有 schema 定义的命令（`generate`、`query`、`deps`、`impact`、`analyze`、`doctor`、`benchmark`、`design`、`check`、`ci`、`history`、`workflow` 等）自动映射为 MCP tools。
+- 动态 tool 注册：新增命令无需手动更新 MCP server，schema 变更后自动生效。
 - `mcp start` 的 `stdout` 只能承载 MCP 协议帧；欢迎信息、迁移提示与 runtime log 不会走这条流。
-- 当前只暴露两个工具：`codemap_query`、`codemap_impact`。
-- `codemap_query` / `codemap_impact` 都会返回 `graph_status`、`generated_at` 与显式 `error.code`。
+- 所有 MCP tools 返回 `graph_status`、`generated_at` 与显式 `error.code`。
 - 若图尚未生成，会返回 `GRAPH_NOT_FOUND`；若符号不存在，返回 `SYMBOL_NOT_FOUND`；若同名符号无法消歧，返回 `AMBIGUOUS_EDGE`。
 - 详细安装步骤见 `docs/ai-guide/INTEGRATION.md`；完整 output contract 见 `docs/ai-guide/OUTPUT.md`。
 
@@ -248,6 +251,7 @@ mycodemap analyze -i show -t "src/index.ts" --output-mode human
 | `--include-tests` | 包含测试文件关联 | - |
 | `--include-git-history` | 包含 Git 历史分析 | - |
 | `--json` | JSON 格式输出 | - |
+| `--human` | 强制人类可读输出（覆盖非 TTY 默认 JSON 行为） | - |
 | `--structured` | 纯结构化输出（移除自然语言字段，配合 `--json` 使用） | - |
 | `--output-mode <mode>` | 输出模式：`machine`/`human` | `human` |
 <!-- END GENERATED: analyze-commands-options -->
@@ -515,6 +519,60 @@ mycodemap workflow template recommend "任务"  # 推荐模板
 
 ---
 
+## doctor - 持续健康诊断
+
+> v2.0 新增。检测 ghost 命令、native 依赖问题、workspace drift、agent 连通性。
+
+```bash
+mycodemap doctor              # 人类可读摘要
+mycodemap doctor --json       # 机器可读完整诊断
+```
+
+| 类别 | 检查项 | 说明 |
+|------|--------|------|
+| `install` | native 依赖完整性 | 检查 `better-sqlite3` 等 native 模块是否可加载 |
+| `config` | workspace 完整性 | 检查 `.mycodemap/config.json`、图存储后端配置 |
+| `runtime` | ghost 命令检测 | 检测已注册但无实际实现的命令 |
+| `agent` | MCP 连通性 | 检查 MCP server 注册与工具发现是否正常 |
+
+- 每个类别独立返回 `ok` / `warn` / `error` 状态
+- `--json` 输出纯结构化 diagnostics，包含 `categories[]`、`summary`、`recommendations`
+- `error` 级别诊断会设置非零 exit code
+
+---
+
+## benchmark - WASM vs Native 性能对比
+
+> v2.0 新增。对比 WASM fallback 与 Native 实现的性能差异。
+
+```bash
+mycodemap benchmark           # 完整对比（WASM + Native）
+mycodemap benchmark --wasm    # 仅 WASM 性能
+mycodemap benchmark --native  # 仅 Native 性能
+mycodemap benchmark --json    # JSON 输出
+```
+
+- 输出包含各分析阶段的耗时对比（generate、query、deps、impact 等）
+- `--json` 输出结构化 benchmark 结果，便于 CI 集成与回归检测
+- 用于决定是否启用 WASM fallback 或排查性能退化
+
+---
+
+## --schema - 接口契约输出
+
+> v2.0 新增。输出完整的 Interface Contract Schema JSON，供 agent 自省与动态 tool 注册。
+
+```bash
+mycodemap --schema            # 输出完整 schema JSON
+mycodemap --schema | jq '.'   # 格式化查看
+```
+
+- 单一 schema 同时生成：parser、MCP tools、`--help-json`、shell completions
+- Agent 可通过读取 schema 动态发现所有可用命令及其参数契约
+- 输出包含所有 20+ 命令的完整接口定义（参数、类型、返回值结构）
+
+---
+
 ## 已移除的公共命令
 
 以下命令已从 public CLI 移除；直接调用时，CLI 会显式失败并给出迁移提示，而不是继续执行旧功能。
@@ -544,7 +602,7 @@ mycodemap export json -o ./output.json       # 指定输出
 
 ### ship - 一键智能发布（非代码地图首屏能力）
 
-> `ship` 负责发布整合，不是 AI-first 代码地图工具的首屏入口；首次接触项目时优先使用分析命令而非发布命令。
+> `ship` 负责发布整合，不是 CodeMap 代码分析的首屏入口；首次接触项目时优先使用分析命令而非发布命令。
 
 ```bash
 mycodemap ship                              # 完整发布流程

package/docs/ai-guide/INTEGRATION.md

@@ -1,6 +1,6 @@
 # AI Guide - MCP / Agent 集成
 
-> 当前 canonical integration path：**真实本地 stdio MCP server**。旧 CLI wrapper 只作为 fallback。
+> v2.0 更新：CLI-as-MCP Automatic Gateway。所有 schema 定义的 CLI 命令自动暴露为 MCP tools。
 
 ---
 
@@ -11,11 +11,16 @@
 | transport | 本地 `stdio` |
 | 读写权限 | **只读** |
 | public surface | `mycodemap mcp install`、`mycodemap mcp start` |
-| MCP tools | `codemap_query`、`codemap_impact` |
+| MCP tools | **ALL 20+ schema 定义的 CLI 命令** |
 | 图前置条件 | 先执行 `mycodemap generate --symbol-level` |
-| 稳定性 | **experimental** |
+| 稳定性 | **stable (v2.0)** |
 | 非目标 | HTTP MCP、远程 transport、写操作、全局 host lifecycle |
 
+### 动态 Tool 注册
+
+- 向 `Interface Contract Schema` 添加新命令 → 重启 MCP server → 新 tool 自动出现在 host 中
+- 无需手写 tool 定义、无需修改 MCP server 代码、无需重新安装
+
 ---
 
 ## 1.1 速查表
@@ -44,7 +49,7 @@ mycodemap generate --symbol-level
 mycodemap mcp install
 ```
 
-该命令当前只做一件事：在**当前仓库根目录**的 `.mcp.json` 里写入一个 experimental server entry。
+该命令在当前仓库根目录的 `.mcp.json` 里写入一个 v2.0 server entry。
 
 ### Step 3: 让 MCP host 启动 stdio server
 
@@ -57,6 +62,8 @@ mycodemap mcp start
 - `stdout` 只承载 MCP 协议帧
 - 欢迎信息、迁移提示、runtime log 不会混入 `stdout`
 
+> **v2.0 关键变更**：所有在 `Interface Contract Schema` 中定义的命令自动作为 MCP tools 可用。无需手写 tool 定义，无需逐个注册。
+
 ---
 
 ## 3. `.mcp.json` 参考配置
@@ -66,7 +73,7 @@ mycodemap mcp start
 ```json
 {
   "mcpServers": {
-    "mycodemap-experimental": {
+    "mycodemap": {
       "command": "node",
       "args": ["dist/cli/index.js", "mcp", "start"],
       "cwd": "/absolute/path/to/repo",
@@ -80,7 +87,7 @@ mycodemap mcp start
 
 ### 当前宿主支持边界
 
-- 当前文档只保证**repo-local `.mcp.json`** 这一路径
+- 当前文档只保证 **repo-local `.mcp.json`** 这一路径
 - 不承诺全局安装、升级覆盖策略或卸载命令
 - 若你的 host 不读取 `.mcp.json`，请手动拷贝上面的 server entry 到宿主自己的 MCP 配置文件
 
@@ -88,7 +95,25 @@ mycodemap mcp start
 
 ## 4. MCP tool contract
 
-### `codemap_query`
+### Gateway 模式
+
+CLI-as-MCP Automatic Gateway 将所有 CLI 命令统一映射为 MCP tools：
+
+| CLI 命令 | MCP tool 名 | 输入参数 |
+|----------|-------------|----------|
+| `mycodemap query -s X` | `codemap_query` | `{ symbol: string, filePath?: string }` |
+| `mycodemap impact -f X` | `codemap_impact` | `{ symbol: string, filePath?: string, depth?: number, limit?: number }` |
+| `mycodemap doctor` | `codemap_doctor` | `{ category?: string, json?: boolean }` |
+| `mycodemap benchmark` | `codemap_benchmark` | `{ command?: string, json?: boolean }` |
+| `mycodemap analyze -i find -k X` | `codemap_analyze` | `{ intent: string, keyword: string, ... }` |
+| ... | ... | ... |
+
+映射规则：
+- CLI 命令名 → MCP tool 名前缀为 `codemap_`
+- CLI 短选项（`-s`）和长选项（`--symbol`）→ MCP tool 参数名使用长选项名
+- CLI 输出结构 → MCP tool 返回结构完全一致
+
+### `codemap_query`（示例之一）
 
 输入：
 
@@ -107,7 +132,7 @@ interface CodemapQueryInput {
 - `generated_at`
 - `error.code`（若失败）
 
-### `codemap_impact`
+### `codemap_impact`（示例之一）
 
 输入：
 
@@ -128,7 +153,7 @@ interface CodemapImpactInput {
 - `generated_at`
 - `error.code`（若失败）
 
-> 完整输出类型见 `docs/ai-guide/OUTPUT.md`。
+> 完整输出类型见 `docs/ai-guide/OUTPUT.md`。以上仅为 20+ tools 中的两个示例。
 
 ---
 
@@ -140,6 +165,40 @@ interface CodemapImpactInput {
 | `SYMBOL_NOT_FOUND` | 请求的 symbol 不存在 | 检查拼写，或先用 `query -S` / `analyze -i find` 搜索 |
 | `AMBIGUOUS_EDGE` | 同名 symbol 无法仅靠 `symbol` / `filePath` 消歧 | 补充更具体的 `filePath` |
 
+### Failure-to-Action Protocol
+
+v2.0 错误响应包含可执行的修复指引：
+
+```typescript
+interface McpError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  // Failure-to-Action Protocol 字段
+  rootCause?: string;           // 根因分析
+  remediationPlan?: string[];   // 修复步骤（按优先级）
+  confidence: "high" | "medium" | "low";
+  nextCommand?: string;         // 建议执行的下一步命令
+}
+```
+
+示例：
+
+```json
+{
+  "code": "GRAPH_NOT_FOUND",
+  "message": "symbol-level 图不存在",
+  "rootCause": "未执行 mycodemap generate --symbol-level",
+  "remediationPlan": [
+    "mycodemap generate --symbol-level",
+    "mycodemap mcp install",
+    "重启 MCP host"
+  ],
+  "confidence": "high",
+  "nextCommand": "mycodemap generate --symbol-level"
+}
+```
+
 ### `graph_status` 解读
 
 | 值 | 含义 |
@@ -158,6 +217,8 @@ interface CodemapImpactInput {
 mycodemap query -s "SymbolName" -j
 mycodemap impact -f "src/file.ts" -j
 mycodemap analyze -i find -k "SymbolName" --json --structured
+mycodemap doctor --json
+mycodemap benchmark --json
 ```
 
 但要注意：
@@ -178,7 +239,7 @@ mycodemap generate --symbol-level
 ### `mcp install` 后看不到 server
 
 - 确认 host 会读取当前仓库根目录的 `.mcp.json`
-- 不会读取的话，手动复制 `mycodemap-experimental` entry 到宿主配置
+- 不会读取的话，手动复制 `mycodemap` entry 到宿主配置
 
 ### `mcp start` 无法启动
 
@@ -200,6 +261,12 @@ npm ls better-sqlite3
 - 先检查 `graph_status` 是否为 `partial`
 - 再检查 symbol 是否真的唯一；必要时补 `filePath`
 
+### 新增命令后 MCP host 看不到新 tool
+
+- 确认新命令已注册到 `Interface Contract Schema`（`mycodemap --schema` 检查）
+- 重启 MCP server（host 侧或 `mycodemap mcp start`）
+- 不需要重新运行 `mcp install`，除非 server entry 本身有变更
+
 ### storage 运行时错误速查表
 
 | 错误 / 信号 | 含义 | 处理方式 |