name: toolkit-map description: "AI agent 的本机工具发现与选择层：调用工具前查询绝对路径、项目要求和验证状态；明确需要安装时才单独安装。避免把 PATH 解析当机器盘点，避免重复安装或改全局环境。"

toolkit-map

先根据本 SKILL.md 的实际位置定位 scripts/map.ps1，使用它的绝对路径。不要把 ./scripts/map.ps1 当成用户当前项目下的文件。

安装技能不会自动写入前端的全局规则。希望在各项目持续遵守本流程时，将简短调用规则接入前端支持的全局指令；仅单个项目使用时可运行 setup -Project <目录>。接入位置、可复制模板和生效验收见 agent 接入指南。

调用流程

Windows 策略禁止直接执行脚本时，用当前 PowerShell 宿主以 -NoProfile -ExecutionPolicy Bypass -File <地图脚本绝对路径> <动作与参数> 单次调用；不修改全局执行策略，遵循组织组策略。

1. 执行 <地图脚本绝对路径> status -Json。没有地图时执行 setup -Project <项目目录>，或只执行 scan；过旧或 PATH 变化时重扫。
2. 执行 <地图脚本绝对路径> find <工具> -Project <当前项目目录> -Json。
3. 检查退出码、ok、status、requirement、verification。只有成功且已验证的结果默认可以直接使用 path。
4. 项目需要环境变量或配套工具时，通过已登记的 mise 执行 mise exec -- <命令>。

find 在地图没有合适副本时搜索 PATH、仓库和 mise 安装目录。失败只说明本次搜索范围没有合适副本，不代表全盘不存在，也不授权自动安装。

安装流程

先查地图和现场；只有明确需要时另行执行 install <工具>@<版本>。先用 -WhatIf -Json 查看计划。已有其他版本不代表项目要求的版本已满足。

下载前说明预计下载量、展开后的安装占用、实际目标目录及暂存/缓存位置，检查相关盘的可用空间。仅预计安装占用 ≥1 GB 时询问位置，下载包大小不触发询问；先问用户使用当前位置还是其他绝对目录，等回答再下载。体积未知时先核实估算；Rust、Android SDK 等预计达到门槛的工具即使精确体积未知也先确认。用户已有明确位置偏好且空间足够时复用，不重复询问；用户指定的门槛优先。

-WhatIf 不联网、不估算包体积；大小来自官方资产元数据/说明，未知就报告未知。TOOLCHAIN_ROOT 控制 portable 仓库，TEMP 控制安装暂存；管理器的数据和缓存目录另行配置。临时环境变量只在当前会话生效，持久化位置偏好需用户明确选择，不自动移动已有安装。详见 存储与大工具安装。

portable 工具落在 ~/toolchains/<工具>/<版本>/；-Via winget 由包管理器决定安装位置。已有副本用 add 登记，不搬路径、不改全局 PATH。不安装 venv/site-packages/node_modules 等应用依赖到工具仓库。

动作

所有动作支持 -Json；stdout 一个对象，协议 schemaVersion: 2。ok:false 时必须处理 status：map_missing、map_corrupt、not_found、no_usable_candidate、version_mismatch、requirement_unsupported、map_busy 等。

首选与护栏

项目要求 > 显式偏好 > 已验证副本的默认排序；-Version 可以显式覆盖项目要求。shim 永不作首选，IDE 运行时和 conda env 默认不参选。-AllowUnverified / -AllowIdeHost 只能在用户明确需要时使用，不能为了让查询成功而自行添加。

不执行 shim 探测版本；不把存在等同可用；不把未知要求判成满足。用 source 区分仓库、管理器、系统、手工和宿主副本。地图是索引，仓库是存放位置。

支持范围

完整地图动作仅限 Windows PowerShell 5.1/7；Unix 目前只有 census.sh 扫描内核。复杂 mise 配置交给管理器，不猜测其含义。

向用户报告时区分：项目要求什么、机器发现哪些副本、当前命令解析到谁。发现范围和验证状态都必须保留。

首次使用见 README；遇到问题见 故障排查，撤销见 卸载指南。不把本机环境告警或 doctor 待处理项误报为安装失败。

toolkit-map

让 AI 编程助手优先复用已经安装的工具，并按项目要求选对版本。

适合在 Windows 本机用 Cursor、Codex 或 Claude Code 开发，尤其是有多个工具版本、工具散落在不同目录的机器。接入方式是本地 PowerShell 脚本与 agent 规则，无需安装 mise。macOS / Linux 目前只有扫描内核，尚不支持完整地图流程。

开始使用 · 其他前端与全局接入 · 遇到问题 · 撤销接入

30 秒看懂它做什么

假设 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" }
}

node --version 只说明当前 PATH 调用了谁；地图把项目要求、发现的副本与调用路径分开。查询不安装工具；默认不选 shim、未验证文件或 IDE 内置运行时。搜索范围不是全盘穷尽。

首次接入一个项目

推荐先在一个 Cursor 或 Codex 项目中试用，确认成功后再配置跨项目的全局规则。需要 Windows PowerShell 5.1 / PowerShell 7、Git。源码发布 ZIP 约 170 KB，工具仓库与实际工具另行存放。

1. 下载稳定版

在你要接入的项目目录打开 PowerShell，在同一个终端按顺序执行。当前目录就是项目路径，无需反复替换盘符。

$project = (Get-Location).Path
$installDir = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
git clone --branch v0.3.0 --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

已有安装见升级步骤。没有 Git 或希望下载 ZIP 时，改走 ZIP 接入路线，它使用系统 PowerShell 验证地图。

2. 预览并接入

检查下载的源码后，使用当前 PowerShell 宿主单次运行脚本；这不会修改全局执行策略。组织组策略的限制需遵循组织要求。

& $ps -NoProfile -ExecutionPolicy Bypass -File $map setup -Project $project -WhatIf -Json
& $ps -NoProfile -ExecutionPolicy Bypass -File $map setup -Project $project
& $ps -NoProfile -ExecutionPolicy Bypass -File $map doctor -Project $project -Json
& $ps -NoProfile -ExecutionPolicy Bypass -File $map find git -Project $project

预览返回 status: planned；setup 首次建图并将规则写入当前项目的 AGENTS.md，已有内容保留、修改前备份。首次扫描可能需要等待，耗时取决于候选数量与探测情况。它不安装运行时、不改 PATH。

doctor 正常时返回 ok: true、status: ok；Git 查询显示绝对路径、版本和 验证 verified。attention_required 需按 checks 排查，见故障排查。先查 Git 是因为下载前已要求安装它，首次成功无需另外安装 Node。

3. 在 agent 中验收

在同一项目新开 Cursor Agent Chat 或 Codex 会话，发送：

根据本项目的工具发现规则，查询 Git。先不安装、不改环境；报告项目要求、发现的副本、所选绝对路径及验证状态。验证通过后，用这个绝对路径执行 --version。

成功标志是看到 agent 实际调用地图，再调用返回的工具路径。doctor 只检查本机配置，不能证明模型已加载或遵守规则。模型直接调用裸 git 时，按规则未生效的排查步骤处理。

能力范围

常用命令

下面假定已设置 $ps、$map、$project。每个动作都支持 -Json，stdout 一个 JSON 对象；检查退出码、ok、status、requirement 和 verification 后再调用工具。

& $ps -NoProfile -ExecutionPolicy Bypass -File $map status -Json
& $ps -NoProfile -ExecutionPolicy Bypass -File $map find node -Project $project -Json
& $ps -NoProfile -ExecutionPolicy Bypass -File $map add node -Path 'C:\existing-node\node.exe' -Json
& $ps -NoProfile -ExecutionPolicy Bypass -File $map install rg@latest -WhatIf -Json

完整命令、结果状态、适配器与声明规则见参考手册。全局规则、Claude Code、Cursor MDC 和可选技能安装见agent 接入指南。

常见问题

• 会把工具搬走或改 PATH 吗？ 扫描和接入不会；已有副本留在原处。install 是单独的明确操作。bootstrap 是可选环境配置，会修改机器，不在上述接入流程中。
• 必须用 mise 吗？ 无需安装 mise 也能发现、登记和查询工具；项目需要完整管理器环境时再使用 mise。
• 工具默认放 C 盘吗？ 地图默认在 ~/.toolkit/map.json，新 portable 工具默认在 ~/toolchains。TOOLCHAIN_ROOT 可改仓库位置，TEMP 与管理器缓存需分别考虑。接入规则仅在预计安装占用 ≥1 GB 时询问位置，CLI 本身不估算或弹窗。见存储指南。
• 能撤销吗？ 可以移除接入规则与技能链接，保留已有工具；见撤销与卸载。
• 升级后会自动生效吗？ 源码更新不等于旧规则更新。文件规则重跑 setup；Cursor 全局 User Rules 重新生成并粘贴；随后新开会话验收。
• 怎么反馈问题？ 先看故障排查，再使用 问题/建议模板，提供复现步骤与相关诊断结果。

贡献与进一步了解

参考手册 · agent 接入 · 平台说明 · 存储指南 · 贡献指南 · 更新记录

源码、协议、通用示例与配方使用 MIT 许可。本机地图、工具、缓存和凭据不进入发布包。