# RoslynCodeMap 使用指南（团队版）

2026-07-24来源：CFNote 笔记Tags：达人、.Net、CodeMap、工具浏览：39

RoslynCodeMap（命令名 codemap）是基于 Roslyn 的 C# 大代码库语义索引 + MCP 查询服务：把整个解决方案的类型、方法、字段、调用关系、入口、DI、aspx 关系索引进一个 SQLite 库，再以 MCP 工具的形式暴露给 AI 客户端（如 Kiro），让 AI 精确地"找定义、查引用、追调用链、定位入口"，而不是在代码里 grep。

一个 exe 同时提供 index（索引）/ sync（增量）/ serve（MCP 服务）/ query（命令行查询）/ status / stats / log。

为什么用 CodeMap，而不是 grep

传统 grep 只按文本匹配，AI 拿到一堆同名结果还得逐个翻文件、猜调用关系，token 烧得多、还常猜错。CodeMap 用 Roslyn 把整个解决方案语义化进 SQLite，以 MCP 工具精准喂给 AI，让它基于真实调用图工作：

AI 开发：找定义 / 实现直接命中，重载自动消歧，不再被同名符号淹没，少走弯路。
AI 分析问题：一键反向追调用链、定位底层方法的所有上游，根因排查从"猜"变成"查"。
测试 / 影响面评估：find_entry_paths 从改动方法反查到所有 webapi/mvc/aspx 入口，一眼看清"这次改动该测哪些接口、会影响谁"。

存事实不存推断，查询毫秒级，百万方法大库也从容。让 AI 基于真实调用图工作，而不是在代码里 grep。

ChatGPT Image Jul 23, 2026, 06_24_14 PM.png

一、安装

0. 一键安装向导（推荐）

仓库根的交互式脚本 install-codemap.ps1 把本节的安装、下一节的 MCP 配置、第三节的索引串成一条向导，最省事：

.\install-codemap.ps1

它会依次：

让你填三个必填项——要索引的 .sln 绝对路径（示例 D:\SurErp\ERP-OMS-Workspaces\S3\S3.sln）、db 存放目录 db-home（示例 D:\Tools\RsCodeMap）、workspace 名（示例 s3）。
选安装方式：本地 .nupkg 包（默认，需给出包的完整路径）或私有 NuGet 源（给出 feed 地址）。
安装并执行 codemap --help 确认成功。
询问是否配置 Kiro MCP，以及配到用户级（~/.kiro/settings/mcp.json）还是工作区级（<项目>/.kiro/settings/mcp.json）；选工作区级时，还会问是否顺带在该项目 .kiro/steering/local/localStandards.md 写入"优先用 codemap 检索"规则（有则更新、无则生成，保留你已有的其它个人规则）。
询问是否立即索引，是则按上面的配置执行 codemap index。

说明：

脚本存为 UTF-8 带 BOM（PowerShell 5.1 读中文需要 BOM）；后续编辑请保持该编码。
写 MCP 配置是合并进已有 mcp.json（先备份、保留其它 server），不覆盖整个文件。
卸载旧版失败（通常是 MCP 服务器仍占用文件）时，会提示先在 Kiro 停用 rscodemap，再回车重试 / Ctrl+C 终止。

若想手动逐步操作，继续看下面的 1~3。

1. 配置私有 NuGet 源（只需一次）

dotnet nuget add source http://192.168.11.165:5000/v3/index.json -n MyPrivateSource --allow-insecure-connections

--allow-insecure-connections 用于内网 HTTP 源。-n 后面是本地给这个源起的名字，可自定义。

2. 安装 codemap 工具

前置：机器需装有 .NET 9 或 .NET 10 SDK（包按 net9.0 目标 + RollForward=Major，9/10 都能装能跑）。

# 安装（全局工具）
dotnet tool install -g RoslynCodeMap

安装命令里的 RoslynCodeMap 是包 ID（固定，不能改）；装完后日常调用的命令名是 codemap。
需要确保 %USERPROFILE%\.dotnet\tools 在系统 PATH 中（首次装全局工具后重开终端即可）。

3. 升级到新版本

# 先卸载旧版
dotnet tool uninstall RoslynCodeMap --global
# 再装新版
dotnet tool install -g RoslynCodeMap

升级 codemap 后，若新版改了 db schema，旧库需要用 --force-full 重建（见"索引"一节）。

验证安装：

codemap --help

二、在 Kiro 中配置 MCP

编辑 MCP 配置文件（用户级：~/.kiro/settings/mcp.json；或工作区级：.kiro/settings/mcp.json），加入 rscodemap 服务器。推荐默认配置：

{
  "mcpServers": {
    "rscodemap": {
      "command": "codemap",
      "args": [
        "serve",
        "--workspace", "s3",
        "--db-home", "D:\\Tools\\RsCodeMap",
        "--index-args", "--sln \"D:/SurErp/ERP-OMS-Workspaces/S3/S3.sln\" --prefer-legacy --field-ref-mode full"
      ],
      "disabled": false,
      "autoApprove": [
        "search_symbol", "search_type",
        "find_callers", "find_callees", "find_call_chain",
        "find_entry_paths", "find_implementations", "find_references",
        "find_declaration", "find_di_bindings",
        "get_method_context", "list_type_members", "type_hierarchy",
        "find_aspx_codebehind", "list_file_symbols", "get_workspace_stats"
      ]
    }
  }
}

配置要点：

--workspace：库的名字，一个 workspace 一个独立 db。多个代码库就配多个 server（各用不同 workspace 名）。
--db-home：db 存放根目录。db 实际落在 <db-home>/<workspace>/<workspace>.db。index 与 serve 必须指向同一个 db-home + workspace 才会命中同一个库（配置里都写死最省心）。不写 --db-home 时默认用 %LOCALAPPDATA%\rscodemap。
--index-args：这个 workspace 的索引参数串（--sln/--csproj/--root + 开关，不含 --workspace/--db-home，serve 会自动补）。配了它，AI 客户端就多出一个 index 工具，可以直接让 AI 触发重索引。
autoApprove：列出免确认的工具。查询类工具都是只读的，建议全部加上，体验更顺。故意不把 index 放进去——它会拉起 MSBuild 全量重建并弹窗，属重写操作，值得每次人工确认。

保存后在 Kiro 的 MCP 面板重连（或重启），能看到 rscodemap 的工具列表即配置成功。

三、索引项目

索引前请先能完整编译整个解决方案（codemap 依赖 Roslyn 加载项目，编译不通过会影响符号解析）。

索引方式 1：在 Kiro 里让 AI 触发（推荐日常用）

直接对 AI 说"帮我重新索引这个代码库"。AI 会调用 MCP 的 index 工具，弹出一个新的终端窗口实时显示索引进度与结果汇总。

⚠️ 前提：MCP 配置里 --index-args 后面的 --sln（或 --csproj/--root）路径必须正确。路径不存在时不会弹窗，会直接返回提示。

索引方式 2：直接在命令行执行（首次建库 / 排错）

codemap index --sln "D:\SurErp\ERP-OMS-Workspaces\S3\S3.sln" --workspace s3 --prefer-legacy --db-home "D:\Tools\RsCodeMap" --field-ref-mode full

命令行里的 --workspace / --db-home 要和 MCP 配置里的一致，这样 serve 才查得到这个库。
在已建好的库上重跑同一条 index 会自动清空旧数据全量重建，重复执行总能得到正确结果。
升级 codemap 后若 schema 变了，加 --force-full 强制删库重建：在末尾追加 --force-full。若此时 serve 正占用着 db，会提示先在 MCP 面板停用/断开 codemap 再重试。

增量更新（可选）

小范围改动后不想全量重建，可以增量同步（基于 mtime + SHA-256 只刷新变化的文件）：

codemap sync --workspace s3 --db-home "D:\Tools\RsCodeMap"

四、让 AI 优先使用 codemap 做代码检索

目前处于探索阶段。为了让 AI 在需要"查代码"时优先走 codemap 这个 MCP（而不是全文 grep），可以加一条 steering 规则。

在项目目录下新建 .kiro/steering/local/localStandards.md（local 目录一般已被 gitignore，属个人规则），内容示例：

---
inclusion: always
---

# 代码搜索相关工具

AI 需要查找代码位置、引用、实现、调用链，以及方法的调用入口时，
优先使用 codemap MCP 来检索代码，而不是全文搜索：

- 找方法/类型定义、看实现（含重载消歧）：find_declaration / get_method_context / search_symbol / search_type
- 查"谁引用/调用了它"：find_references / find_callers
- 追多跳调用链、从底层方法反查到入口（webapi/mvc/aspx）：find_call_chain / find_entry_paths
- 查接口/虚方法的实现、DI 注册、类型继承层级：find_implementations / find_di_bindings / type_hierarchy
- 按文件列符号、aspx 与 codebehind 互查：list_file_symbols / find_aspx_codebehind

仅当 codemap 查不到（如非 C# 文件、注释、配置）时才回退到全文搜索。

inclusion: always 表示这条规则对所有对话生效。改完后新开对话即生效。

五、MCP 查询工具一览

配置好后 AI 可用的工具（日常 AI 会自动选，无需手动记；这里供了解能力边界）：

工具	作用
`search_symbol`	统一符号搜索：跨方法/字段/委托字段/事件按名字召回，带类别标记
`search_type`	按类型名/FQN 搜类型
`find_declaration`	从调用点精确解析被调方法的定义/实现（自动消歧重载，可带方法体）
`get_method_context`	一个方法的全貌：基本信息 + 调用者 + 被调 + 入口路径概览 + 可选方法体
`find_callers` / `find_callees`	谁调用了它 / 它调用了谁（含接口/虚展开）
`find_call_chain`	多跳调用链反向 BFS
`find_entry_paths`	从底层方法反查到所有入口（webapi/mvc/aspx…）
`find_implementations`	接口/抽象/虚方法的所有实现
`find_references`	统一引用门面：跨方法与字段解析"谁用了这个符号"，按符号分组
`find_field_refs`	某字段/事件/委托字段的所有引用（读/写/委托调用）
`find_di_bindings`	查 DI 注册
`list_type_members`	列某类型的所有成员方法与字段
`type_hierarchy`	类型继承/实现层级（基类+接口+派生+实现者）
`find_aspx_codebehind`	aspx/ascx/master 与 codebehind 类互查
`list_file_symbols`	按文件路径反查其中声明的类型与方法
`get_workspace_stats`	workspace 概览（各实体计数、db 路径、字段引用模式等）
`index`	触发一次重索引（弹终端窗口）；需配了 `--index-args` 才注册

这些工具都有对应的命令行版本 codemap query <子命令>（如 codemap query find-callers …），一般只在调试时手动用。

六、命令与参数参考

所有命令都可加 --help 查看完整参数。db 定位统一靠 --workspace + --db-home（不写 db 路径）。

`codemap index` —— 全量索引

参数	说明	默认
`--sln <path>`	要索引的 `.sln`	—
`--csproj <path>…`	要索引的 `.csproj`（可多个）	—
`--root <dir>…`	递归索引的根目录（可多个，进同一 db 以连通跨项目调用边）	—
`--workspace <名>`	workspace 名（一库一名）	`default`
`--db-home <dir>`	db 根目录	环境变量 `RSCODEMAP_DB_HOME` > `%LOCALAPPDATA%\rscodemap`
`--field-ref-mode <off	entities	full>`
`--prefer-legacy`	对 SDK 项目也走 Legacy 解析器，绕过 MSBuildWorkspace（大代码库更快）	关
`--force-full`	跳过断点续跑，强制从零重建；schema 不兼容（升级后）时也用它删库重建	关
`--exclude-tests` / `--include-tests`	排除 / 纳入测试工程	排除
`--index-parallelism <n>`	项目级并行度（1=串行）	2
`--index-mem-cap-mb <mb>`	并行索引内存硬上限（MB）	6144
`--no-vacuum`	收尾跳过 VACUUM 压缩（一般不用；连接已设 busy_timeout，与 serve 并发也能压缩成功）	关
`--on-error <abort	continue>`	出错时中止还是继续
`--web-dir <dir>…`	（仅 `--sln`）发现 ASP.NET Web Site（无 csproj）的目录	sln 所在目录
`--quiet` / `--verbose` / `--json`	静默 / 详细日志到 stderr / NDJSON 进度	—

`codemap serve` —— 启动 MCP 服务（由 Kiro 拉起，一般不手动跑）

参数	说明
`--workspace <名>`	要服务的 workspace（默认 `default`）
`--db-home <dir>`	db 根目录（需与 index 一致）
`--index-args "<串>"`	`index` 工具默认索引参数（不含 workspace/db-home，自动补）；配了才注册 `index` 工具
`--search-limit` / `--callers-limit` / `--call-chain-max-depth` / `--entry-max-depth` / `--entry-max-paths` / `--implementations-limit` / `--di-bindings-limit` / `--type-members-limit` / `--type-hierarchy-limit` / `--aspx-limit` / `--context-entry-paths` / `--context-callers`	覆盖各查询工具的默认上限/跳数（按库微调，一般不用）

`codemap sync` —— 增量同步

参数	说明
`--workspace <名>` / `--db-home <dir>`	库定位（需与 index 一致）
`--dry-run`	仅检测变更不写库
`--quiet`	静默模式

`codemap stats` / `status` / `sessions` / `errors` / `vacuum` / `reset`

命令	说明
`codemap stats --workspace <名> --db-home <dir>`	各表行数汇总（类型/方法/调用边等规模）
`codemap status …`	最近一次会话与各 phase 进度
`codemap sessions [--limit N] …`	会话历史
`codemap errors …`	索引期错误列表
`codemap vacuum --workspace <名> --db-home <dir>`	手动执行 SQLite VACUUM 压缩库
`codemap reset [--yes] …`	清空 db 业务表（保留 sessions/errors 历史）

`codemap log show / clean / path`

命令	说明
`codemap log show [--category indexer	mcp
`codemap log clean [--older-than N] [--dry-run]`	清理超龄日志
`codemap log path`	打印日志目录绝对路径

`codemap query <子命令>` —— 命令行直接查询（调试用）

与 MCP 工具一一对应：search-symbol / search-type / find-declaration / get-method-context / find-callers / find-callees / find-call-chain / find-entry-paths / find-implementations / find-references / find-field-refs / find-di-bindings / list-type-members / type-hierarchy / find-aspx-codebehind / list-file-symbols / workspace-stats。每个都带 --workspace + --db-home，具体参数见 --help。

七、常见问题

serve 报"未找到数据库"：serve 的 --workspace/--db-home 与 index 时不一致，或还没索引过。让两边指向同一 db-home + workspace，并确认已 index。
db 文件偏大：--field-ref-mode full 会索引全部字段引用边，库会明显变大；不需要"查字段引用"时可用 entities。从 MCP 触发的索引默认会做 VACUUM 压缩。
改了代码 AI 还查到旧结构：需要重新索引（方式 1 让 AI 触发，或方式 2 命令行），完成后重新提问即可读到新结果。
升级后索引报 schema 不兼容 / 退出码 24：先在 MCP 面板停用/断开 codemap（释放 db 占用）→ 用 --force-full 重索引 → 重新启用。

· 完 ·