toolkit-map
让 AI 编程助手先查工具、再动手：发现本机已装副本，按项目要求选对版本，只返回可验证的绝对路径。
简体中文 · English · 首次接入 · 参考手册 · agent 接入 · 更新记录
解决的问题
AI 编程助手执行 node、python、git 时，通常直接走 PATH。于是：
- PATH 上是 Node 16，而项目声明要求 Node 22 —— 构建失败，agent 反复试错；
- 机器上装着多个副本（PATH、
~/toolchains、mise 安装目录），agent 不知道选哪个； node --version只能说明"当前 PATH 是谁"，不说明"这个项目需要谁"。
toolkit-map 在调用前回答三个问题：
- 项目要求什么版本？ 读取
mise.toml、.tool-versions、.nvmrc、Nodeengines等常见声明； - 本机有哪些已验证的副本？ 扫描 PATH、工具仓库、mise 安装目录和手工登记的位置；
- 这次该用哪个绝对路径？ 返回
path、version、verification和requirement。
只查询，不安装、不改 PATH、不猜版本。 没有满足要求的副本时返回 version_mismatch，而不是退回旧版本；声明无法解释时返回 requirement_unsupported，交给版本管理器或人来处理。
和直接 PATH / mise / asdf 的区别
toolkit-map 不替代 mise / asdf：它补齐"项目要求 → 本机哪个副本 → 绝对路径"这一链，安装仍交给版本管理器，或在明确需要时执行一次
install。
效果示例
假设 PATH 上是 Node 16，机器另有 Node 22，项目声明需要 Node 22：
成功查询的关键字段（示例路径，不是你本机的清单）：
{
"ok": true,
"status": "ok",
"path": "C:\\tools\\node\\22\\node.exe",
"version": "22.23.2",
"verification": "verified",
"requirement": { "version": "22", "scope": "project", "source": "C:\\project\\mise.toml" }
}
首次接入一个项目
要求：Windows + Windows PowerShell 5.1 或 PowerShell 7 + Git。想用 MCP 接入时另需 Node.js 18+；地图本身不依赖 Node。
想先看效果？在源码目录运行 .\scripts\demo.ps1（临时地图，不改本机）。想一次完成下载、项目接入并生成 MCP 配置：
$d = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
git clone --branch v1.1.3 --depth 1 https://github.com/haxsd/toolkit-map $d
& powershell -NoProfile -ExecutionPolicy Bypass -File "$d\scripts\quickstart.ps1" -Project (Get-Location).Path -Mcp -WriteMcp
quickstart 只写项目 AGENTS.md 并打印 MCP 配置，不覆盖客户端已有的服务器配置。已经运行上面的块时可直接跳到第 2 步；下面是分步说明。加 -WriteMcp 可直接写入项目级 Cursor .cursor/mcp.json（默认）或 Claude Code .mcp.json（-McpClient claude / both），修改前备份并保留其他服务器。
1. 下载稳定版
在要接入的项目目录打开 PowerShell，按顺序执行（当前目录就是项目路径）：
$project = (Get-Location).Path
$installDir = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
git clone --branch v1.1.3 --depth 1 https://github.com/haxsd/toolkit-map $installDir
if ($LASTEXITCODE -ne 0) { throw '下载未完成。已有安装请按升级指南处理，不要覆盖。' }
$map = Join-Path $installDir 'scripts\map.ps1'
$ps = (Get-Process -Id $PID).Path
# 下面统一用 toolkit 调用，它等价于「用当前 PowerShell 宿主单次运行 map.ps1」
function toolkit { & $ps -NoProfile -ExecutionPolicy Bypass -File $map @args }
已有安装见升级步骤。没有 Git 或希望下载 ZIP 时，改走 ZIP 接入路线。
2. 预览并接入项目
toolkit setup -Project $project -WhatIf -Json
toolkit setup -Project $project
toolkit doctor -Project $project -Json
toolkit find git -Project $project
setup 首次建图，并把规则写入项目的 AGENTS.md（已有内容保留，修改前备份）。它不安装运行时、不改 PATH；首次扫描耗时取决于候选数量与探测情况。
doctor 正常时返回 ok: true、status: ok；find git 显示绝对路径、版本与 验证 verified。异常时按 checks 排查，见故障排查。
3. 在 agent 里验收
在同一项目新开一个 Cursor Agent Chat 或 Codex 会话，发送：
根据本项目的工具发现规则，查询 Git。先不安装、不改环境；报告项目要求、发现的副本、所选绝对路径及验证状态。验证通过后，用这个绝对路径执行
--version。
成功标志是看到 agent 实际调用地图，再调用返回的工具路径。doctor 只检查本机配置，不能证明模型已加载或遵守规则；模型直接调用裸 git 时，按规则未生效的排查步骤处理。
常用命令
toolkit status -Json # 地图新鲜度、PATH 变化
toolkit find node -Project $project -Json # 项目要求 + 绝对路径
toolkit add node -Path 'C:\existing-node\node.exe' -Json # 登记已有副本
toolkit install rg@latest -WhatIf -Json # 查看安装计划，不联网
完整命令、结果状态、适配器与声明规则见参考手册。
用 MCP 接入（推荐）
客户端支持 MCP 时，不需要把规则文件粘进每个项目：让地图选一个 Node 18+ 绝对路径，生成配置，粘贴一次即可。下面假设你已经按上一步设置了 $map 与 $installDir。
# 1. 用地图找一个已验证的 Node 18+，不要用 PATH 上的旧版本
$node = (& $map find node -Version '>=18' -Json | ConvertFrom-Json).path
# 2. 生成 Cursor / Claude Code 的 mcpServers JSON；Codex 用 --print-config codex
& $node (Join-Path $installDir 'mcp\server.mjs') --print-config
# 3. 先脱离客户端验证服务器和地图
& $node (Join-Path $installDir 'mcp\server.mjs') --check
把输出合并进 Cursor 的 ~/.cursor/mcp.json（或项目 .cursor/mcp.json）、Claude Code 的 .mcp.json，或按 TOML 粘进 ~/.codex/config.toml，重启客户端。新会话里应能看到 toolkit_find、toolkit_status、toolkit_doctor 三个只读工具。
MCP 与规则文件可以同时启用；MCP 不会自动改写 AGENTS.md，setup 也不会替你写 MCP 配置。完整配置、协议版本与故障排查见 MCP 接入。
接入前端
任何能读取规则文件的 agent 都可以接入。完整位置、模板与生效验收见 agent 接入指南。
能力范围
安全边界
- 默认只读：
scan/status/find/doctor不安装工具、不改 PATH、不写配置； - 安装是独立动作：
install需要显式调用，建议先用-WhatIf查看计划，不联网； - 改文件先备份：
setup只维护你指定的规则文件，已有内容保留、修改前备份； - 验证状态明确：
verified/unverified/unavailable/skipped不混用，未经验证的副本不会默认被选中； - 不碰凭据：本机地图、工具、缓存和凭据不进入发布包；
- 不修改全局执行策略：用当前宿主单次调用，组织组策略的限制照常遵守。
文档
参考手册 · 契约冻结 · MCP 接入 · 2 分钟演示 · agent 接入 · 平台说明 · 存储与大工具安装 · 故障排查 · 撤销与卸载 · 贡献指南 · 安全策略 · 更新记录
常见问题
- 没有项目声明时，会帮我选到最新的版本吗？ 不会。选择顺序是
-Version参数 > 项目声明 > 父目录/全局声明 > 系统默认（PATH 上的那个）。PATH 上是 Node 16、机器另有 Node 24 时，find node返回 16；要特定版本就写项目声明或传-Version。 - 会把工具搬走或改 PATH 吗？ 扫描和接入不会；已有副本留在原处。
install是单独的明确操作。bootstrap是可选环境配置，会修改机器，不在上述接入流程中。 - 必须用 mise 吗？ 不用。没有 mise 也能发现、登记和查询工具；项目需要完整管理器环境时再使用 mise。
- 工具默认放 C 盘吗？ 地图默认在
~/.toolkit/map.json，新的 portable 工具默认在~/toolchains。TOOLCHAIN_ROOT可改仓库位置，见存储指南。 - 能撤销吗？ 可以移除接入规则与技能链接，保留已有工具，见撤销与卸载。
- 升级后会自动生效吗？ 源码更新不等于旧规则更新。文件规则重跑
setup；Cursor 全局 User Rules 重新生成并粘贴；随后新开会话验收。
贡献与许可
欢迎 Issue 和 PR：先看贡献指南，Bug 与功能建议请用 Issue 模板，尽量附上复现步骤与 doctor -Bundle -Json 输出（粘贴前隐去路径中的用户名）。
源码、协议、通用示例与配方使用 MIT 许可。本机地图、工具、缓存和凭据不进入发布包。