Back to search
toolkit-map
SkillWorks with Claude CodeGitHub
"AI agent 的本机工具发现与选择层:调用工具前查询绝对路径、项目要求和验证状态;查询只读,find 返回维护建议,setup 预授权后 agent 可自动定向 update,scan/install 仍确认。避免把 PATH 解析当机器盘点,避免重复安装或改全局环境。"
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked yesterday
Badge for your README
Markdown
[](/listings/haxsd--toolkit-map)HTML
<a href="/listings/haxsd--toolkit-map"><img src="/api/listings/haxsd--toolkit-map/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 67 lines
- ---
- name: toolkit-map
- description: "AI agent 的本机工具发现与选择层:调用工具前查询绝对路径、项目要求和验证状态;查询只读,find 返回维护建议,setup 预授权后 agent 可自动定向 update,scan/install 仍确认。避免把 PATH 解析当机器盘点,避免重复安装或改全局环境。"
- ---
- # toolkit-map
- 先根据本 SKILL.md 的实际位置定位 `scripts/map.ps1`,使用它的绝对路径。**不要把 `./scripts/map.ps1` 当成用户当前项目下的文件**。
- 安装技能不会自动写入前端的全局规则。希望在各项目持续遵守本流程时,将简短调用规则接入前端支持的全局指令;仅单个项目使用时可运行 `setup -Project <目录>`。接入位置、可复制模板和生效验收见 [agent 接入指南](docs/agent-integration.md)。
- 客户端支持 MCP 时,优先配置 `mcp/server.mjs`:它提供 `toolkit_find` / `toolkit_status` / `toolkit_doctor` 三个只读查询工具,以及 `toolkit_scan` / `toolkit_update` / `toolkit_add` 三个维护工具,直接调用同一份 `map.ps1 -Json`,不依赖模型记住规则文件。维护工具默认只预览;`find.maintenance.autoAllowed` 为 true 时,`toolkit_update` 可传 `confirm:true` 直接执行(策略已授权),然后重试 `find`;`toolkit_scan` / `toolkit_add` 仍需用户明确确认。配置与验收见 [MCP 接入](docs/mcp.md);规则文件仍可作为回退,两者可以同时启用。
- `find` 只读:不执行新候选、不写地图;只读发现的新候选保持未验证。结果里的 `maintenance` 会说明地图是否过期、有没有待验证候选、建议动作和 `autoAllowed`。`setup` 默认预授权定向 `update`;未执行 `setup` 不预授权,`-NoAutoUpdate` 可关闭;`scan` / `add` / `install` 仍确认。团队共享仓库不要提交含本机绝对路径的规则块或 MCP 配置。
- **有 MCP 工具时,不要再用 shell 执行 `map.ps1` 做同样的查询**;直接用 MCP 工具。只有 MCP 不可用时,才按下面的脚本流程回退。这样既少一层参数拼接,也避免每次查询都经过宿主终端。
- ## 调用流程
- Windows 策略禁止直接执行脚本时,用当前 PowerShell 宿主以 `-NoProfile -ExecutionPolicy Bypass -File <地图脚本绝对路径> <动作与参数>` 单次调用;不修改全局执行策略,遵循组织组策略。
- 1. 执行 `<地图脚本绝对路径> status -Json`。没有地图时,取得用户同意后用 `setup` / `scan` 建图;地图过旧或候选变化时,优先按 `find` 返回的 `maintenance` 处理。PATH 因会话不同而变化时先确认实际影响,不必反复重扫。
- 2. 执行 `<地图脚本绝对路径> find <工具> -Project <当前项目目录> -Json`。`find` 只读:不执行新候选、不写地图;新候选保持未验证,并出现在 `maintenance.pending` 里。
- 3. 检查退出码、`ok`、`status`、`requirement`、`verification`。同时检查 `maintenance`:`required` 必须先处理,`recommended` 可先维护再执行。
- 4. 若 `maintenance.actions` 里的定向 `update <tool>` 为 `autoAllowed:true`,直接执行并重试一次 `find`;`scan` / `add` / `install` 或 `autoAllowed:false` 时只确认一次。不要因为地图旧就每次全量重扫。
- 5. 项目需要环境变量或配套工具时,通过已登记的 mise 执行 `mise exec -- <命令>`。
- `find` 只读当前地图与项目声明;地图没有可用候选时不会执行新候选,也不会写地图。只读发现的新候选保持未验证,需要维护动作验证后才可能被选中。失败只说明当前地图没有可用候选,不代表全盘不存在,也不授权自动安装。`maintenance.autoAllowed` 只授权定向 `update`,不授权 `scan` / `add` / `install`。
- ## 安装流程
- 先查地图和现场;只有明确需要时另行执行 `install <工具>@<版本>`。先用 `-WhatIf -Json` 查看计划。已有其他版本不代表项目要求的版本已满足。
- 下载前说明预计下载量、展开后的安装占用、实际目标目录及暂存/缓存位置,检查相关盘的可用空间。**仅预计安装占用 ≥1 GB 时询问位置**,下载包大小不触发询问;先问用户使用当前位置还是其他绝对目录,等回答再下载。体积未知时先核实估算;Rust、Android SDK 等预计达到门槛的工具即使精确体积未知也先确认。用户已有明确位置偏好且空间足够时复用,不重复询问;用户指定的门槛优先。
- `-WhatIf` 不联网、不估算包体积;大小来自官方资产元数据/说明,未知就报告未知。`TOOLCHAIN_ROOT` 控制 portable 仓库,`TEMP` 控制安装暂存;管理器的数据和缓存目录另行配置。临时环境变量只在当前会话生效,持久化位置偏好需用户明确选择,不自动移动已有安装。详见 [存储与大工具安装](docs/storage.md)。
- portable 工具落在 `~/toolchains/<工具>/<版本>/`;`-Via winget` 由包管理器决定安装位置。已有副本用 `add` 登记,不搬路径、不改全局 PATH。不安装 venv/site-packages/node_modules 等应用依赖到工具仓库。
- ## 动作
- | 动作 | 用途 |
- |---|---|
- | `setup -Project <目录> [-WhatIf] [-AutoUpdate|-NoAutoUpdate]` | 首次建图并接入项目 AGENTS.md;写入维护策略(默认预授权定向 update);已有文件先备份;`-RulesFile` 可指定文件 |
- | `doctor -Project <目录>` | 只读验证地图、宿主与接入文件;不证明模型行为 |
- | `scan` | 完整扫描,保留手工副本、备注和偏好 |
- | `status` | 完整扫描年龄、局部更新时间和 PATH 变化 |
- | `find <工具> [-Project <目录>] [-Version <要求>]` | 只读选择;不执行新候选、不写地图;返回 `maintenance`(地图年龄、待验证候选、建议动作、`autoAllowed`);不满足时失败,不降级 |
- | `add <工具> -Path <绝对路径> [-Note <文本>] [-Prefer]` | 登记已有文件;保存路径偏好 |
- | `update [工具]` | 重探条目,不刷新完整扫描时间;`find.maintenance.autoAllowed` 为 true 时可由 agent 自动执行 |
- | `install <工具>@<版本> [-WhatIf]` | 明确安装,可用 `-Url` / `-Sha256` 或 `-Via winget` |
- 所有动作支持 `-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 默认不参选。`find` 不再支持 `-AllowUnverified`;`-AllowIdeHost` 只能在用户明确需要时使用,不能为了让查询成功而自行添加。
- 不执行 shim 探测版本;不把存在等同可用;不把未知要求判成满足。用 `source` 区分仓库、管理器、系统、手工和宿主副本。地图是索引,仓库是存放位置。
- ## 支持范围
- 完整地图动作仅限 Windows PowerShell 5.1/7;Unix 目前只有 census.sh 扫描内核。复杂 mise 配置交给管理器,不猜测其含义。
- 向用户报告时区分:项目要求什么、机器发现哪些副本、当前命令解析到谁。发现范围和验证状态都必须保留。
- 首次使用见 [README](README.md#快速开始);遇到问题见 [故障排查](docs/troubleshooting.md),撤销见 [卸载指南](docs/uninstall.md)。不把本机环境告警或 doctor 待处理项误报为安装失败。
README.md · README · 87 lines
- <div align="center">
- # toolkit-map
- **让 AI 编程助手先查工具、再动手:发现本机已装副本,按项目要求选对版本,只返回可验证的绝对路径。**
- [](https://github.com/haxsd/toolkit-map/actions/workflows/ci.yml)
- [](https://github.com/haxsd/toolkit-map/releases/latest)
- [](LICENSE)
- [](docs/platform-notes.md)
- 简体中文 · [English](README-EN.md) · [快速开始](#快速开始) · [参考手册](docs/reference.md) · [agent 接入](docs/agent-integration.md) · [更新记录](CHANGELOG.md)
- </div>
- 
- ## 解决的问题
- AI 编程助手执行 `node`、`python`、`git` 时通常直接走 PATH:PATH 上是 Node 16,项目声明要求 Node 22;机器上装着多份副本,agent 不知道选哪个;`node --version` 只说明 PATH 解析到谁,不说明这个项目需要谁。
- toolkit-map 在调用前回答三件事:
- 1. **项目要求什么版本?** 读取 `mise.toml`、`.tool-versions`、`.nvmrc`、Node `engines` 等常见声明;
- 2. **本机有哪些已验证的副本?** 扫描 PATH、统一仓库、mise 安装目录和手工登记的位置;
- 3. **这次该用哪个绝对路径?** 返回 `path`、`version`、`verification` 和 `requirement`。
- **查询严格只读,不安装、不改 PATH、不猜版本。** 地图维护(`scan` / `update` / `add`)是单独动作;`setup` 默认预授权 agent 在 `find` 返回维护建议时自动执行定向 `update <tool>`,未执行 `setup` 时不预授权;`scan` / `add` / `install` 仍需用户确认。没有满足要求的副本时返回 `version_mismatch`,不降级;声明无法解释时返回 `requirement_unsupported`,交给版本管理器或人处理。与其他工具的区别和返回示例见[参考手册](docs/reference.md#和其他工具的区别)。
- ## 快速开始
- **要求**:Windows + Windows PowerShell 5.1 或 PowerShell 7 + Git。想用 MCP 接入时另需 Node.js 18+;地图本身不依赖 Node。
- 一次完成下载、项目接入并写入项目级 MCP 配置:
- ```powershell
- $project = (Get-Location).Path
- $d = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
- git clone --branch v2.1.0 --depth 1 https://github.com/haxsd/toolkit-map $d
- if ($LASTEXITCODE -ne 0) { throw '下载未完成。已有安装请按升级指南处理,不要覆盖。' }
- $ps = (Get-Process -Id $PID).Path
- & $ps -NoProfile -ExecutionPolicy Bypass -File "$d\scripts\quickstart.ps1" -Project $project -Mcp -WriteMcp
- ```
- 看退出码:`0` 全部完成;`2` 部分完成(规则已接入,MCP 未写成,例如没有 Node 18+ 或启动检查失败);`1` 项目接入失败。`-ExecutionPolicy Bypass` 只作用于该子进程,不修改用户或机器策略;组织策略拒绝时按组织流程申请,不要改注册表或组策略。
- 手动完成同样的步骤:
- ```powershell
- $project = (Get-Location).Path
- $installDir = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
- git clone --branch v2.1.0 --depth 1 https://github.com/haxsd/toolkit-map $installDir
- $map = Join-Path $installDir 'scripts\map.ps1'
- $ps = (Get-Process -Id $PID).Path
- function toolkit { & $ps -NoProfile -ExecutionPolicy Bypass -File $map @args }
- toolkit setup -Project $project -WhatIf -Json # 预览
- toolkit setup -Project $project # 建图并把规则写入 AGENTS.md
- toolkit doctor -Project $project -Json # 只读诊断
- toolkit find git -Project $project # 只读查询
- ```
- 已有安装见[升级步骤](docs/agent-integration.md#升级与刷新规则);没有 Git 或希望下载 ZIP 时走 [ZIP 接入](docs/agent-integration.md#没有-git-时从-zip-接入)。MCP 客户端可以直接调用地图工具,配置、协议与验收见 [MCP 接入](docs/mcp.md);规则位置、模板与生效验收见 [agent 接入](docs/agent-integration.md)。
- ## 安全边界
- - **查询只读**:`status` / `find` / `doctor` 不安装工具、不改 PATH、不写配置;`find` 不执行新候选、不写地图。
- - **维护与安装是显式动作**:`scan` / `update` / `add` 会写地图并可能探测本机候选程序;`install` 需要单独调用,建议先 `-WhatIf`。MCP 维护默认只预览,`confirm:true` 只是执行请求,仍需用户授权。
- - **不动已有环境**:不迁移已有工具、不改 PATH、不改全局执行策略,也不碰凭据。
- - **团队仓库**:接入规则和 MCP 配置含本机绝对路径,不要提交到共享仓库;每位成员本地生成。
- - 本机地图、工具、缓存和凭据不进入发布包;完整边界见[安全策略](docs/security-policy.md)。
- ## 文档
- [参考手册](docs/reference.md) · [契约冻结](docs/contract.md) · [MCP 接入](docs/mcp.md) · [2 分钟演示](docs/demo.md) · [agent 接入](docs/agent-integration.md) · [平台说明](docs/platform-notes.md) · [存储与大工具安装](docs/storage.md) · [故障排查](docs/troubleshooting.md) · [撤销与卸载](docs/uninstall.md) · [开发与贡献](docs/development.md) · [安全策略](docs/security-policy.md) · [更新记录](CHANGELOG.md)
- ## 常见问题
- - **没有项目声明时会选最新版吗?** 不会。顺序是 `-Version` > 项目声明 > 父目录/全局声明 > 系统默认;PATH 上是 Node 16 就返回 16,要特定版本请写声明或传 `-Version`。
- - **会搬走工具或改 PATH 吗?** 不会;已有副本留在原处,`install` 是单独的明确操作。
- - **必须用 mise 吗?** 不用;没有 mise 也能发现、登记和查询,需要完整管理器环境时再用。
- - **能撤销吗?** 可以移除接入规则、MCP 配置与技能链接,保留已有工具,见[撤销与卸载](docs/uninstall.md)。
- ## 贡献与许可
- 欢迎 Issue 和 PR:先看[开发与贡献](docs/development.md),Bug 与功能建议请用 [Issue 模板](https://github.com/haxsd/toolkit-map/issues/new/choose),尽量附上复现步骤与 `doctor -Bundle -Json` 输出(粘贴前隐去路径中的用户名)。
- 源码、协议、通用示例与配方使用 [MIT](LICENSE) 许可。
scripts/bootstrap.sh · Bundled script · 316 lines · 2 findings marked
- #!/usr/bin/env bash
- #
- # 一键把本机改造成"声明式工具链"模式:装好 mise、写入机器声明、配好 PATH。
- #
- # 与 scripts/bootstrap.ps1 是同一套设计的 Unix 实现。
- #
- # 用法:
- # ./bootstrap.sh --dry-run 只打印将要执行的改动
- # ./bootstrap.sh 实际执行
- # ./bootstrap.sh --no-rc 不修改 shell 启动文件
- # ./bootstrap.sh --skip-tools 只装 mise 和配置,不拉取运行时
- # ./bootstrap.sh --refresh-config 用模板覆盖已部署的全局声明(覆盖前先备份)
- #
- set -uo pipefail
- DRY_RUN=0
- NO_RC=0
- SKIP_TOOLS=0
- REFRESH_CONFIG=0
- TOOLS_ROOT=""
- # 模板刻意不放在 mise/ 目录下:mise 会把 <任意目录>/mise/config.toml 当成项目配置自动读取,
- # 放那里会让仓库本身被当成一个"未授权的 mise 项目"。
- CONFIG_SOURCE="$(cd "$(dirname "$0")/.." && pwd)/templates/mise-config.toml"
- while [ $# -gt 0 ]; do
- case "$1" in
- --dry-run) DRY_RUN=1; shift ;;
- --no-rc) NO_RC=1; shift ;;
- --skip-tools) SKIP_TOOLS=1; shift ;;
- --refresh-config) REFRESH_CONFIG=1; shift ;;
- --config) CONFIG_SOURCE="$2"; shift 2 ;;
- --tools-root) TOOLS_ROOT="$2"; shift 2 ;;
- -h|--help) sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
- *) echo "未知参数: $1" >&2; exit 2 ;;
- esac
- done
- # 规范根:非托管的手装运行时的落脚点,按 <工具>/<版本>/ 排列。
- # 优先级:命令行参数 > 环境变量 TOOLCHAIN_ROOT > 默认 ~/toolchains。
- [ -n "$TOOLS_ROOT" ] || TOOLS_ROOT="${TOOLCHAIN_ROOT:-$HOME/toolchains}"
- step() { printf '\n==> %s\n' "$1"; }
- ok() { printf ' [完成] %s\n' "$1"; }
- skip() { printf ' [跳过] %s\n' "$1"; }
- warn() { printf ' [注意] %s\n' "$1"; }
- plan() { printf ' [计划] %s\n' "$1"; }
- # 只在真正执行过之后才宣告完成;空运行模式下什么都不说,避免造成"已经改了"的错觉
- done_msg() { [ "$DRY_RUN" -eq 1 ] || ok "$1"; }
- # 执行一条命令;--dry-run 时只打印
- run_action() {
- local desc="$1"; shift
- if [ "$DRY_RUN" -eq 1 ]; then plan "$desc"; return 0; fi
- "$@"
- }
- MISE_DATA="${XDG_DATA_HOME:-$HOME/.local/share}/mise"
- MISE_SHIMS="$MISE_DATA/shims"
- MISE_CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/mise/config.toml"
- printf '\n 工具链引导脚本 bootstrap.sh\n'
- printf ' 目标:把本机改造成声明式工具链模式\n'
- [ "$DRY_RUN" -eq 1 ] && printf ' 模式:空运行(不会修改任何东西)\n'
- # ============================================================
- # 步骤 0:环境自检
- # ============================================================
- step '环境自检'
- ok "$(uname -s) $(uname -m)"
- PKG_MANAGERS=""
- for pm in brew apt dnf pacman zypper apk; do
- if command -v "$pm" >/dev/null 2>&1; then
- PKG_MANAGERS="$PKG_MANAGERS $pm"
- ok "找到包管理器: $pm"
- fi
- done
- # ============================================================
- # 步骤 1:安装 mise
- # ============================================================
- step '安装 mise'
- if command -v mise >/dev/null 2>&1; then
- skip "mise 已安装: $(mise --version 2>&1 | head -n1)(位置 $(command -v mise))"
- else
- installed=0
- # 官方推荐:单文件安装脚本,性能最好,且支持 mise self-update
- if [ "$installed" -eq 0 ]; then
- if [ "$DRY_RUN" -eq 1 ]; then
- plan '通过官方脚本安装 mise(curl -fsSL https://mise.run | sh)'
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 91 on GitHub
- else
- if curl -fsSL https://mise.run | sh; then
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 93 on GitHub
- ok 'mise 已安装到 ~/.local/bin/mise'
- else
- warn '官方脚本安装失败,继续尝试包管理器'
- fi
- fi
- installed=1
- fi
- if [ "$installed" -eq 0 ] && printf '%s' "$PKG_MANAGERS" | grep -q brew; then
- run_action '通过 Homebrew 安装 mise' brew install mise
- installed=1
- fi
- if [ "$installed" -eq 0 ]; then
- warn '请手工安装 mise,参考 https://mise.jdx.dev/installing-mise.html'
- [ "$DRY_RUN" -eq 0 ] && exit 1
- fi
- warn '安装完成后需要重开终端,或先 export PATH="$HOME/.local/bin:$PATH"'
- fi
- # ============================================================
- # 步骤 2:写入全局机器声明
- # ============================================================
- step '写入全局机器声明'
- if [ ! -f "$CONFIG_SOURCE" ]; then
- warn "找不到配置模板: $CONFIG_SOURCE"
- else
- ok "模板: $CONFIG_SOURCE"
- ok "目标: $MISE_CONFIG_FILE"
- # 取出 [tools] 段的键名。用 awk 而不是解析 TOML:这里只需要知道"声明了哪些工具",
- # 不关心数组、嵌套表这些细节,够用且零依赖。
- # 开头先剥掉可能存在的 UTF-8 BOM(PowerShell 5.1 的 Set-Content -Encoding utf8 会写 BOM,
- # 带 BOM 时 /^\[tools\]/ 匹配不上,会把所有键都误报成"模板独有")。
- tools_keys() {
- awk 'NR==1{sub(/^\xef\xbb\xbf/,"")} /^\[tools\]/{f=1;next} /^\[/{f=0} f && /^[A-Za-z0-9_.-]+[ \t]*=/{sub(/[ \t]*=.*/,"");print}' "$1" | sort -u
- }
- # 声明漂移检测:模板是"这台机器想要的状态",部署副本是"现在实际声明的状态"。
- # 两份文件之间没有任何同步机制,模板里新加的工具会永远装不上——这是最容易被
- # 忽视的一类失效,因为 census 只看部署副本,会报告一切正常。
- if [ -f "$MISE_CONFIG_FILE" ] && cmp -s "$CONFIG_SOURCE" "$MISE_CONFIG_FILE"; then
- skip '部署副本与模板一致,无需改写'
- elif [ -f "$MISE_CONFIG_FILE" ]; then
- warn '检测到漂移:部署的配置与模板不一致'
- tpl_keys="$(tools_keys "$CONFIG_SOURCE")"
- dep_keys="$(tools_keys "$MISE_CONFIG_FILE")"
- missing="$(comm -23 <(printf '%s\n' "$tpl_keys") <(printf '%s\n' "$dep_keys") | grep -v '^$' || true)"
- extra="$(comm -13 <(printf '%s\n' "$tpl_keys") <(printf '%s\n' "$dep_keys") | grep -v '^$' || true)"
- [ -n "$missing" ] && printf ' 模板有而部署副本没有: %s\n' "$(printf '%s' "$missing" | tr '\n' ' ')"
- [ -n "$extra" ] && printf ' 部署副本有而模板没有: %s\n' "$(printf '%s' "$extra" | tr '\n' ' ')"
- if [ -z "$missing$extra" ]; then
- printf ' [tools] 的键相同,但内容有差异(版本或注释不同)\n'
- fi
- if [ "$REFRESH_CONFIG" -eq 1 ]; then
- backup="$MISE_CONFIG_FILE.bak-$(date +%Y%m%d-%H%M%S)"
- run_action "备份到 $backup" cp "$MISE_CONFIG_FILE" "$backup"
- run_action "按模板写入 $MISE_CONFIG_FILE" cp "$CONFIG_SOURCE" "$MISE_CONFIG_FILE"
- done_msg '已按模板刷新(备份保留,可对比合并)'
- else
- skip '保持现状(要按模板覆盖请加 --refresh-config,覆盖前会自动备份)'
- fi
- elif [ "$DRY_RUN" -eq 1 ]; then
- plan "创建 $MISE_CONFIG_FILE 并写入模板内容"
- else
- mkdir -p "$(dirname "$MISE_CONFIG_FILE")"
- cp "$CONFIG_SOURCE" "$MISE_CONFIG_FILE"
- ok '机器声明已就位'
- fi
- fi
- # ============================================================
- # 步骤:建立规范根
- # ============================================================
- step '建立规范根'
- # 规范根是非托管运行时的落脚点。它刻意不进 PATH——PATH 里只应该有 mise 的
- # shims 那一个工具链条目,加多了就会回到"多个版本争同一个名字"的老问题。
- # 约定本身写在 AGENTS.md 规则 5 与 SKILL.md 里,census 的 [STRAY] 告警负责检查。
- ok "规范根: $TOOLS_ROOT"
- if [ -d "$TOOLS_ROOT" ]; then
- skip '目录已存在'
- else
- run_action "创建 $TOOLS_ROOT" mkdir -p "$TOOLS_ROOT"
- done_msg '已创建'
- fi
- if [ "$DRY_RUN" -eq 0 ]; then
- warn '今后手工安装的运行时请放在 <工具>/<版本>/ 子目录下(如 node/22.23.2)'
- warn '已经装在别处的运行时不要迁移——路径可能被项目配置写死,改成登记到声明文件'
- fi
- # ============================================================
- # 步骤 3:配置 PATH —— 全机只留一个工具链目录
- # ============================================================
- step '配置 PATH(核心步骤)'
- printf ' 原则:PATH 里只应该出现 mise 的 shims 目录这一个工具链条目,\n'
- printf ' 而不是每个运行时各自一条(/usr/local/opt/node、jdk/bin ...)。\n'
- case ":$PATH:" in
- *":$MISE_SHIMS:"*) skip "shims 目录已在 PATH 中: $MISE_SHIMS" ;;
- *) warn "shims 目录不在当前 PATH:$MISE_SHIMS"
- warn '配置 shell 激活后(下一步)mise 会自动把它加进去,不需要手工改 PATH' ;;
- esac
- printf '\n 以下 PATH 条目指向具体版本,属于"该收敛掉"的候选:\n'
- suspicious="$(printf '%s' "$PATH" | tr ':' '\n' | grep -E '/(node|python|jdk|jre|java|go|rust)[^/]*/(bin|versions)' || true)"
- if [ -z "$suspicious" ]; then
- ok '没有发现需要收敛的条目'
- else
- printf '%s\n' "$suspicious" | sed 's/^/ - /'
- warn '脚本不会自动删除它们。确认 mise 工作正常后,可以手工清理。'
- fi
- # ============================================================
- # 步骤 4:配置 shell 激活
- # ============================================================
- step '配置 shell 激活'
- if [ "$NO_RC" -eq 1 ]; then
- skip '按参数要求跳过(--no-rc)'
- else
- # 根据当前 shell 选择激活写法。
- # 全部都要带存在性判断:否则在 mise 还不可解析的会话里(PATH 尚未刷新的新终端、
- # 用户卸载了 mise)每次启动 shell 都会报 command not found。
- # 用 if 形式而不是 && 形式,避免在某些 rc 文件设了 set -e 时中途退出。
- case "${SHELL:-}" in
- */zsh)
- RC_FILE="${ZDOTDIR:-$HOME}/.zshrc"
- ACTIVATION='if command -v mise >/dev/null 2>&1; then eval "$(mise activate zsh)"; fi'
- ;;
- */bash)
- RC_FILE="$HOME/.bashrc"
- ACTIVATION='if command -v mise >/dev/null 2>&1; then eval "$(mise activate bash)"; fi'
- ;;
- */fish)
- RC_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish"
- ACTIVATION='if command -q mise; mise activate fish | source; end'
- ;;
- *)
- RC_FILE="$HOME/.profile"
- ACTIVATION='if command -v mise >/dev/null 2>&1; then eval "$(mise activate bash)"; fi'
- warn "无法识别 shell ($SHELL),将写入 $RC_FILE"
- ;;
- esac
- if [ -f "$RC_FILE" ] && grep -qF "$ACTIVATION" "$RC_FILE" 2>/dev/null; then
- skip "激活行已存在于 $RC_FILE"
- else
- if [ "$DRY_RUN" -eq 1 ]; then
- plan "向 $RC_FILE 追加激活行: $ACTIVATION"
- else
- mkdir -p "$(dirname "$RC_FILE")"
- {
- printf '\n# 由 runtime-census 的 bootstrap.sh 添加:让 mise 按项目声明自动切换运行时版本\n'
- printf '%s\n' "$ACTIVATION"
- } >> "$RC_FILE"
- ok "激活行已写入 $RC_FILE"
- warn '想撤销就删掉该文件里带 "runtime-census" 注释的那两行'
- fi
- fi
- fi
- # ============================================================
- # 步骤 5:拉取声明的运行时
- # ============================================================
- step '拉取声明的运行时'
- if [ "$SKIP_TOOLS" -eq 1 ]; then
- skip '按参数要求跳过(--skip-tools)'
- elif ! command -v mise >/dev/null 2>&1; then
- warn 'mise 还不在当前 PATH 里,无法执行 mise install'
- warn '请重开终端后手工执行: mise install'
- else
- # 空 [tools] 是"按需"形态(模板默认):这时 mise install 什么也不会做,
- # 说清楚比静默跳过好——否则使用者会以为"拉取过了"。
- if [ -f "$MISE_CONFIG_FILE" ] && declare -F tools_keys >/dev/null 2>&1 && [ -z "$(tools_keys "$MISE_CONFIG_FILE")" ]; then
- skip '机器声明里没有要常备的版本(按需模式)'
- printf ' 版本需求写在项目自己的 mise.toml / .tool-versions 里;进项目后执行\n'
- printf ' mise install(只拉那个项目声明的版本),或用 mise x <工具>@<版本> -- <命令>。\n'
- else
- run_action 'mise install(按机器声明拉取全部运行时)' mise install
- done_msg '运行时已拉取'
- fi
- fi
- # ============================================================
- # 步骤 6:自检
- # ============================================================
- step '自检'
- if command -v mise >/dev/null 2>&1; then
- mise doctor 2>&1 | sed 's/^/ /'
- printf '\n 当前 mise 管理的运行时:\n'
- mise ls 2>&1 | sed 's/^/ /'
- else
- warn 'mise 尚未在当前会话可用,跳过自检。重开终端后执行 mise doctor。'
- fi
- # ============================================================
- # 收尾
- # ============================================================
- cat <<'EOF'
- ======================================================================
- 完成。接下来的用法:
- 重开一个终端,然后:
- 盘点本机所有运行时(包括未被 mise 纳管的)
- ./scripts/census.sh
- 在项目里声明所需版本,然后一次性执行命令
- mise use node@22 # 写入项目 .tool-versions
- mise exec -- node -v # 零全局状态地激活一次
- 查看这台机器上所有可用版本
- mise ls # 已安装
- mise ls-remote node # 可安装
- ======================================================================
- EOF
- [ "$DRY_RUN" -eq 1 ] && printf ' 这是空运行。去掉 --dry-run 才会真正执行。\n'
- exit 0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.