Skip to content
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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/haxsd--toolkit-map/badge.svg)](/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
  1. ---
  2. name: toolkit-map
  3. description: "AI agent 的本机工具发现与选择层:调用工具前查询绝对路径、项目要求和验证状态;查询只读,find 返回维护建议,setup 预授权后 agent 可自动定向 update,scan/install 仍确认。避免把 PATH 解析当机器盘点,避免重复安装或改全局环境。"
  4. ---
  5. # toolkit-map
  6. 先根据本 SKILL.md 的实际位置定位 `scripts/map.ps1`,使用它的绝对路径。**不要把 `./scripts/map.ps1` 当成用户当前项目下的文件**。
  7. 安装技能不会自动写入前端的全局规则。希望在各项目持续遵守本流程时,将简短调用规则接入前端支持的全局指令;仅单个项目使用时可运行 `setup -Project <目录>`。接入位置、可复制模板和生效验收见 [agent 接入指南](docs/agent-integration.md)。
  8. 客户端支持 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);规则文件仍可作为回退,两者可以同时启用。
  9. `find` 只读:不执行新候选、不写地图;只读发现的新候选保持未验证。结果里的 `maintenance` 会说明地图是否过期、有没有待验证候选、建议动作和 `autoAllowed`。`setup` 默认预授权定向 `update`;未执行 `setup` 不预授权,`-NoAutoUpdate` 可关闭;`scan` / `add` / `install` 仍确认。团队共享仓库不要提交含本机绝对路径的规则块或 MCP 配置。
  10. **有 MCP 工具时,不要再用 shell 执行 `map.ps1` 做同样的查询**;直接用 MCP 工具。只有 MCP 不可用时,才按下面的脚本流程回退。这样既少一层参数拼接,也避免每次查询都经过宿主终端。
  11. ## 调用流程
  12. Windows 策略禁止直接执行脚本时,用当前 PowerShell 宿主以 `-NoProfile -ExecutionPolicy Bypass -File <地图脚本绝对路径> <动作与参数>` 单次调用;不修改全局执行策略,遵循组织组策略。
  13. 1. 执行 `<地图脚本绝对路径> status -Json`。没有地图时,取得用户同意后用 `setup` / `scan` 建图;地图过旧或候选变化时,优先按 `find` 返回的 `maintenance` 处理。PATH 因会话不同而变化时先确认实际影响,不必反复重扫。
  14. 2. 执行 `<地图脚本绝对路径> find <工具> -Project <当前项目目录> -Json`。`find` 只读:不执行新候选、不写地图;新候选保持未验证,并出现在 `maintenance.pending` 里。
  15. 3. 检查退出码、`ok`、`status`、`requirement`、`verification`。同时检查 `maintenance`:`required` 必须先处理,`recommended` 可先维护再执行。
  16. 4. 若 `maintenance.actions` 里的定向 `update <tool>` 为 `autoAllowed:true`,直接执行并重试一次 `find`;`scan` / `add` / `install` 或 `autoAllowed:false` 时只确认一次。不要因为地图旧就每次全量重扫。
  17. 5. 项目需要环境变量或配套工具时,通过已登记的 mise 执行 `mise exec -- <命令>`。
  18. `find` 只读当前地图与项目声明;地图没有可用候选时不会执行新候选,也不会写地图。只读发现的新候选保持未验证,需要维护动作验证后才可能被选中。失败只说明当前地图没有可用候选,不代表全盘不存在,也不授权自动安装。`maintenance.autoAllowed` 只授权定向 `update`,不授权 `scan` / `add` / `install`。
  19. ## 安装流程
  20. 先查地图和现场;只有明确需要时另行执行 `install <工具>@<版本>`。先用 `-WhatIf -Json` 查看计划。已有其他版本不代表项目要求的版本已满足。
  21. 下载前说明预计下载量、展开后的安装占用、实际目标目录及暂存/缓存位置,检查相关盘的可用空间。**仅预计安装占用 ≥1 GB 时询问位置**,下载包大小不触发询问;先问用户使用当前位置还是其他绝对目录,等回答再下载。体积未知时先核实估算;Rust、Android SDK 等预计达到门槛的工具即使精确体积未知也先确认。用户已有明确位置偏好且空间足够时复用,不重复询问;用户指定的门槛优先。
  22. `-WhatIf` 不联网、不估算包体积;大小来自官方资产元数据/说明,未知就报告未知。`TOOLCHAIN_ROOT` 控制 portable 仓库,`TEMP` 控制安装暂存;管理器的数据和缓存目录另行配置。临时环境变量只在当前会话生效,持久化位置偏好需用户明确选择,不自动移动已有安装。详见 [存储与大工具安装](docs/storage.md)。
  23. portable 工具落在 `~/toolchains/<工具>/<版本>/`;`-Via winget` 由包管理器决定安装位置。已有副本用 `add` 登记,不搬路径、不改全局 PATH。不安装 venv/site-packages/node_modules 等应用依赖到工具仓库。
  24. ## 动作
  25. | 动作 | 用途 |
  26. |---|---|
  27. | `setup -Project <目录> [-WhatIf] [-AutoUpdate|-NoAutoUpdate]` | 首次建图并接入项目 AGENTS.md;写入维护策略(默认预授权定向 update);已有文件先备份;`-RulesFile` 可指定文件 |
  28. | `doctor -Project <目录>` | 只读验证地图、宿主与接入文件;不证明模型行为 |
  29. | `scan` | 完整扫描,保留手工副本、备注和偏好 |
  30. | `status` | 完整扫描年龄、局部更新时间和 PATH 变化 |
  31. | `find <工具> [-Project <目录>] [-Version <要求>]` | 只读选择;不执行新候选、不写地图;返回 `maintenance`(地图年龄、待验证候选、建议动作、`autoAllowed`);不满足时失败,不降级 |
  32. | `add <工具> -Path <绝对路径> [-Note <文本>] [-Prefer]` | 登记已有文件;保存路径偏好 |
  33. | `update [工具]` | 重探条目,不刷新完整扫描时间;`find.maintenance.autoAllowed` 为 true 时可由 agent 自动执行 |
  34. | `install <工具>@<版本> [-WhatIf]` | 明确安装,可用 `-Url` / `-Sha256` 或 `-Via winget` |
  35. 所有动作支持 `-Json`;stdout 一个对象,协议 `schemaVersion: 2`。`ok:false` 时必须处理 `status`:`map_missing`、`map_corrupt`、`not_found`、`no_usable_candidate`、`version_mismatch`、`requirement_unsupported`、`map_busy` 等。
  36. ## 首选与护栏
  37. 项目要求 > 显式偏好 > 已验证副本的默认排序;`-Version` 可以显式覆盖项目要求。shim 永不作首选,IDE / 编辑器自带运行时和 conda env 默认不参选。`find` 不再支持 `-AllowUnverified`;`-AllowIdeHost` 只能在用户明确需要时使用,不能为了让查询成功而自行添加。
  38. 不执行 shim 探测版本;不把存在等同可用;不把未知要求判成满足。用 `source` 区分仓库、管理器、系统、手工和宿主副本。地图是索引,仓库是存放位置。
  39. ## 支持范围
  40. 完整地图动作仅限 Windows PowerShell 5.1/7;Unix 目前只有 census.sh 扫描内核。复杂 mise 配置交给管理器,不猜测其含义。
  41. 向用户报告时区分:项目要求什么、机器发现哪些副本、当前命令解析到谁。发现范围和验证状态都必须保留。
  42. 首次使用见 [README](README.md#快速开始);遇到问题见 [故障排查](docs/troubleshooting.md),撤销见 [卸载指南](docs/uninstall.md)。不把本机环境告警或 doctor 待处理项误报为安装失败。
README.md · README · 87 lines
  1. <div align="center">
  2. # toolkit-map
  3. **让 AI 编程助手先查工具、再动手:发现本机已装副本,按项目要求选对版本,只返回可验证的绝对路径。**
  4. [![CI](https://github.com/haxsd/toolkit-map/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/haxsd/toolkit-map/actions/workflows/ci.yml)
  5. [![Release](https://img.shields.io/github/v/release/haxsd/toolkit-map)](https://github.com/haxsd/toolkit-map/releases/latest)
  6. [![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  7. [![Windows](https://img.shields.io/badge/Windows-PowerShell%205.1%20%2F%207-blue)](docs/platform-notes.md)
  8. 简体中文 · [English](README-EN.md) · [快速开始](#快速开始) · [参考手册](docs/reference.md) · [agent 接入](docs/agent-integration.md) · [更新记录](CHANGELOG.md)
  9. </div>
  10. ![toolkit-map 的工作方式:项目要求 + 本机副本 → toolkit-map find → 可验证的绝对路径](docs/assets/how-it-works.zh.png)
  11. ## 解决的问题
  12. AI 编程助手执行 `node`、`python`、`git` 时通常直接走 PATH:PATH 上是 Node 16,项目声明要求 Node 22;机器上装着多份副本,agent 不知道选哪个;`node --version` 只说明 PATH 解析到谁,不说明这个项目需要谁。
  13. toolkit-map 在调用前回答三件事:
  14. 1. **项目要求什么版本?** 读取 `mise.toml`、`.tool-versions`、`.nvmrc`、Node `engines` 等常见声明;
  15. 2. **本机有哪些已验证的副本?** 扫描 PATH、统一仓库、mise 安装目录和手工登记的位置;
  16. 3. **这次该用哪个绝对路径?** 返回 `path`、`version`、`verification` 和 `requirement`。
  17. **查询严格只读,不安装、不改 PATH、不猜版本。** 地图维护(`scan` / `update` / `add`)是单独动作;`setup` 默认预授权 agent 在 `find` 返回维护建议时自动执行定向 `update <tool>`,未执行 `setup` 时不预授权;`scan` / `add` / `install` 仍需用户确认。没有满足要求的副本时返回 `version_mismatch`,不降级;声明无法解释时返回 `requirement_unsupported`,交给版本管理器或人处理。与其他工具的区别和返回示例见[参考手册](docs/reference.md#和其他工具的区别)。
  18. ## 快速开始
  19. **要求**:Windows + Windows PowerShell 5.1 或 PowerShell 7 + Git。想用 MCP 接入时另需 Node.js 18+;地图本身不依赖 Node。
  20. 一次完成下载、项目接入并写入项目级 MCP 配置:
  21. ```powershell
  22. $project = (Get-Location).Path
  23. $d = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
  24. git clone --branch v2.1.0 --depth 1 https://github.com/haxsd/toolkit-map $d
  25. if ($LASTEXITCODE -ne 0) { throw '下载未完成。已有安装请按升级指南处理,不要覆盖。' }
  26. $ps = (Get-Process -Id $PID).Path
  27. & $ps -NoProfile -ExecutionPolicy Bypass -File "$d\scripts\quickstart.ps1" -Project $project -Mcp -WriteMcp
  28. ```
  29. 看退出码:`0` 全部完成;`2` 部分完成(规则已接入,MCP 未写成,例如没有 Node 18+ 或启动检查失败);`1` 项目接入失败。`-ExecutionPolicy Bypass` 只作用于该子进程,不修改用户或机器策略;组织策略拒绝时按组织流程申请,不要改注册表或组策略。
  30. 手动完成同样的步骤:
  31. ```powershell
  32. $project = (Get-Location).Path
  33. $installDir = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
  34. git clone --branch v2.1.0 --depth 1 https://github.com/haxsd/toolkit-map $installDir
  35. $map = Join-Path $installDir 'scripts\map.ps1'
  36. $ps = (Get-Process -Id $PID).Path
  37. function toolkit { & $ps -NoProfile -ExecutionPolicy Bypass -File $map @args }
  38. toolkit setup -Project $project -WhatIf -Json # 预览
  39. toolkit setup -Project $project # 建图并把规则写入 AGENTS.md
  40. toolkit doctor -Project $project -Json # 只读诊断
  41. toolkit find git -Project $project # 只读查询
  42. ```
  43. 已有安装见[升级步骤](docs/agent-integration.md#升级与刷新规则);没有 Git 或希望下载 ZIP 时走 [ZIP 接入](docs/agent-integration.md#没有-git-时从-zip-接入)。MCP 客户端可以直接调用地图工具,配置、协议与验收见 [MCP 接入](docs/mcp.md);规则位置、模板与生效验收见 [agent 接入](docs/agent-integration.md)。
  44. ## 安全边界
  45. - **查询只读**:`status` / `find` / `doctor` 不安装工具、不改 PATH、不写配置;`find` 不执行新候选、不写地图。
  46. - **维护与安装是显式动作**:`scan` / `update` / `add` 会写地图并可能探测本机候选程序;`install` 需要单独调用,建议先 `-WhatIf`。MCP 维护默认只预览,`confirm:true` 只是执行请求,仍需用户授权。
  47. - **不动已有环境**:不迁移已有工具、不改 PATH、不改全局执行策略,也不碰凭据。
  48. - **团队仓库**:接入规则和 MCP 配置含本机绝对路径,不要提交到共享仓库;每位成员本地生成。
  49. - 本机地图、工具、缓存和凭据不进入发布包;完整边界见[安全策略](docs/security-policy.md)。
  50. ## 文档
  51. [参考手册](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)
  52. ## 常见问题
  53. - **没有项目声明时会选最新版吗?** 不会。顺序是 `-Version` > 项目声明 > 父目录/全局声明 > 系统默认;PATH 上是 Node 16 就返回 16,要特定版本请写声明或传 `-Version`。
  54. - **会搬走工具或改 PATH 吗?** 不会;已有副本留在原处,`install` 是单独的明确操作。
  55. - **必须用 mise 吗?** 不用;没有 mise 也能发现、登记和查询,需要完整管理器环境时再用。
  56. - **能撤销吗?** 可以移除接入规则、MCP 配置与技能链接,保留已有工具,见[撤销与卸载](docs/uninstall.md)。
  57. ## 贡献与许可
  58. 欢迎 Issue 和 PR:先看[开发与贡献](docs/development.md),Bug 与功能建议请用 [Issue 模板](https://github.com/haxsd/toolkit-map/issues/new/choose),尽量附上复现步骤与 `doctor -Bundle -Json` 输出(粘贴前隐去路径中的用户名)。
  59. 源码、协议、通用示例与配方使用 [MIT](LICENSE) 许可。
scripts/bootstrap.sh · Bundled script · 316 lines · 2 findings marked
  1. #!/usr/bin/env bash
  2. #
  3. # 一键把本机改造成"声明式工具链"模式:装好 mise、写入机器声明、配好 PATH。
  4. #
  5. # 与 scripts/bootstrap.ps1 是同一套设计的 Unix 实现。
  6. #
  7. # 用法:
  8. # ./bootstrap.sh --dry-run 只打印将要执行的改动
  9. # ./bootstrap.sh 实际执行
  10. # ./bootstrap.sh --no-rc 不修改 shell 启动文件
  11. # ./bootstrap.sh --skip-tools 只装 mise 和配置,不拉取运行时
  12. # ./bootstrap.sh --refresh-config 用模板覆盖已部署的全局声明(覆盖前先备份)
  13. #
  14. set -uo pipefail
  15. DRY_RUN=0
  16. NO_RC=0
  17. SKIP_TOOLS=0
  18. REFRESH_CONFIG=0
  19. TOOLS_ROOT=""
  20. # 模板刻意不放在 mise/ 目录下:mise 会把 <任意目录>/mise/config.toml 当成项目配置自动读取,
  21. # 放那里会让仓库本身被当成一个"未授权的 mise 项目"。
  22. CONFIG_SOURCE="$(cd "$(dirname "$0")/.." && pwd)/templates/mise-config.toml"
  23. while [ $# -gt 0 ]; do
  24. case "$1" in
  25. --dry-run) DRY_RUN=1; shift ;;
  26. --no-rc) NO_RC=1; shift ;;
  27. --skip-tools) SKIP_TOOLS=1; shift ;;
  28. --refresh-config) REFRESH_CONFIG=1; shift ;;
  29. --config) CONFIG_SOURCE="$2"; shift 2 ;;
  30. --tools-root) TOOLS_ROOT="$2"; shift 2 ;;
  31. -h|--help) sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
  32. *) echo "未知参数: $1" >&2; exit 2 ;;
  33. esac
  34. done
  35. # 规范根:非托管的手装运行时的落脚点,按 <工具>/<版本>/ 排列。
  36. # 优先级:命令行参数 > 环境变量 TOOLCHAIN_ROOT > 默认 ~/toolchains。
  37. [ -n "$TOOLS_ROOT" ] || TOOLS_ROOT="${TOOLCHAIN_ROOT:-$HOME/toolchains}"
  38. step() { printf '\n==> %s\n' "$1"; }
  39. ok() { printf ' [完成] %s\n' "$1"; }
  40. skip() { printf ' [跳过] %s\n' "$1"; }
  41. warn() { printf ' [注意] %s\n' "$1"; }
  42. plan() { printf ' [计划] %s\n' "$1"; }
  43. # 只在真正执行过之后才宣告完成;空运行模式下什么都不说,避免造成"已经改了"的错觉
  44. done_msg() { [ "$DRY_RUN" -eq 1 ] || ok "$1"; }
  45. # 执行一条命令;--dry-run 时只打印
  46. run_action() {
  47. local desc="$1"; shift
  48. if [ "$DRY_RUN" -eq 1 ]; then plan "$desc"; return 0; fi
  49. "$@"
  50. }
  51. MISE_DATA="${XDG_DATA_HOME:-$HOME/.local/share}/mise"
  52. MISE_SHIMS="$MISE_DATA/shims"
  53. MISE_CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/mise/config.toml"
  54. printf '\n 工具链引导脚本 bootstrap.sh\n'
  55. printf ' 目标:把本机改造成声明式工具链模式\n'
  56. [ "$DRY_RUN" -eq 1 ] && printf ' 模式:空运行(不会修改任何东西)\n'
  57. # ============================================================
  58. # 步骤 0:环境自检
  59. # ============================================================
  60. step '环境自检'
  61. ok "$(uname -s) $(uname -m)"
  62. PKG_MANAGERS=""
  63. for pm in brew apt dnf pacman zypper apk; do
  64. if command -v "$pm" >/dev/null 2>&1; then
  65. PKG_MANAGERS="$PKG_MANAGERS $pm"
  66. ok "找到包管理器: $pm"
  67. fi
  68. done
  69. # ============================================================
  70. # 步骤 1:安装 mise
  71. # ============================================================
  72. step '安装 mise'
  73. if command -v mise >/dev/null 2>&1; then
  74. skip "mise 已安装: $(mise --version 2>&1 | head -n1)(位置 $(command -v mise))"
  75. else
  76. installed=0
  77. # 官方推荐:单文件安装脚本,性能最好,且支持 mise self-update
  78. if [ "$installed" -eq 0 ]; then
  79. if [ "$DRY_RUN" -eq 1 ]; then
  80. 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
  81. else
  82. 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
  83. ok 'mise 已安装到 ~/.local/bin/mise'
  84. else
  85. warn '官方脚本安装失败,继续尝试包管理器'
  86. fi
  87. fi
  88. installed=1
  89. fi
  90. if [ "$installed" -eq 0 ] && printf '%s' "$PKG_MANAGERS" | grep -q brew; then
  91. run_action '通过 Homebrew 安装 mise' brew install mise
  92. installed=1
  93. fi
  94. if [ "$installed" -eq 0 ]; then
  95. warn '请手工安装 mise,参考 https://mise.jdx.dev/installing-mise.html'
  96. [ "$DRY_RUN" -eq 0 ] && exit 1
  97. fi
  98. warn '安装完成后需要重开终端,或先 export PATH="$HOME/.local/bin:$PATH"'
  99. fi
  100. # ============================================================
  101. # 步骤 2:写入全局机器声明
  102. # ============================================================
  103. step '写入全局机器声明'
  104. if [ ! -f "$CONFIG_SOURCE" ]; then
  105. warn "找不到配置模板: $CONFIG_SOURCE"
  106. else
  107. ok "模板: $CONFIG_SOURCE"
  108. ok "目标: $MISE_CONFIG_FILE"
  109. # 取出 [tools] 段的键名。用 awk 而不是解析 TOML:这里只需要知道"声明了哪些工具",
  110. # 不关心数组、嵌套表这些细节,够用且零依赖。
  111. # 开头先剥掉可能存在的 UTF-8 BOM(PowerShell 5.1 的 Set-Content -Encoding utf8 会写 BOM,
  112. # 带 BOM 时 /^\[tools\]/ 匹配不上,会把所有键都误报成"模板独有")。
  113. tools_keys() {
  114. 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
  115. }
  116. # 声明漂移检测:模板是"这台机器想要的状态",部署副本是"现在实际声明的状态"。
  117. # 两份文件之间没有任何同步机制,模板里新加的工具会永远装不上——这是最容易被
  118. # 忽视的一类失效,因为 census 只看部署副本,会报告一切正常。
  119. if [ -f "$MISE_CONFIG_FILE" ] && cmp -s "$CONFIG_SOURCE" "$MISE_CONFIG_FILE"; then
  120. skip '部署副本与模板一致,无需改写'
  121. elif [ -f "$MISE_CONFIG_FILE" ]; then
  122. warn '检测到漂移:部署的配置与模板不一致'
  123. tpl_keys="$(tools_keys "$CONFIG_SOURCE")"
  124. dep_keys="$(tools_keys "$MISE_CONFIG_FILE")"
  125. missing="$(comm -23 <(printf '%s\n' "$tpl_keys") <(printf '%s\n' "$dep_keys") | grep -v '^$' || true)"
  126. extra="$(comm -13 <(printf '%s\n' "$tpl_keys") <(printf '%s\n' "$dep_keys") | grep -v '^$' || true)"
  127. [ -n "$missing" ] && printf ' 模板有而部署副本没有: %s\n' "$(printf '%s' "$missing" | tr '\n' ' ')"
  128. [ -n "$extra" ] && printf ' 部署副本有而模板没有: %s\n' "$(printf '%s' "$extra" | tr '\n' ' ')"
  129. if [ -z "$missing$extra" ]; then
  130. printf ' [tools] 的键相同,但内容有差异(版本或注释不同)\n'
  131. fi
  132. if [ "$REFRESH_CONFIG" -eq 1 ]; then
  133. backup="$MISE_CONFIG_FILE.bak-$(date +%Y%m%d-%H%M%S)"
  134. run_action "备份到 $backup" cp "$MISE_CONFIG_FILE" "$backup"
  135. run_action "按模板写入 $MISE_CONFIG_FILE" cp "$CONFIG_SOURCE" "$MISE_CONFIG_FILE"
  136. done_msg '已按模板刷新(备份保留,可对比合并)'
  137. else
  138. skip '保持现状(要按模板覆盖请加 --refresh-config,覆盖前会自动备份)'
  139. fi
  140. elif [ "$DRY_RUN" -eq 1 ]; then
  141. plan "创建 $MISE_CONFIG_FILE 并写入模板内容"
  142. else
  143. mkdir -p "$(dirname "$MISE_CONFIG_FILE")"
  144. cp "$CONFIG_SOURCE" "$MISE_CONFIG_FILE"
  145. ok '机器声明已就位'
  146. fi
  147. fi
  148. # ============================================================
  149. # 步骤:建立规范根
  150. # ============================================================
  151. step '建立规范根'
  152. # 规范根是非托管运行时的落脚点。它刻意不进 PATH——PATH 里只应该有 mise 的
  153. # shims 那一个工具链条目,加多了就会回到"多个版本争同一个名字"的老问题。
  154. # 约定本身写在 AGENTS.md 规则 5 与 SKILL.md 里,census 的 [STRAY] 告警负责检查。
  155. ok "规范根: $TOOLS_ROOT"
  156. if [ -d "$TOOLS_ROOT" ]; then
  157. skip '目录已存在'
  158. else
  159. run_action "创建 $TOOLS_ROOT" mkdir -p "$TOOLS_ROOT"
  160. done_msg '已创建'
  161. fi
  162. if [ "$DRY_RUN" -eq 0 ]; then
  163. warn '今后手工安装的运行时请放在 <工具>/<版本>/ 子目录下(如 node/22.23.2)'
  164. warn '已经装在别处的运行时不要迁移——路径可能被项目配置写死,改成登记到声明文件'
  165. fi
  166. # ============================================================
  167. # 步骤 3:配置 PATH —— 全机只留一个工具链目录
  168. # ============================================================
  169. step '配置 PATH(核心步骤)'
  170. printf ' 原则:PATH 里只应该出现 mise 的 shims 目录这一个工具链条目,\n'
  171. printf ' 而不是每个运行时各自一条(/usr/local/opt/node、jdk/bin ...)。\n'
  172. case ":$PATH:" in
  173. *":$MISE_SHIMS:"*) skip "shims 目录已在 PATH 中: $MISE_SHIMS" ;;
  174. *) warn "shims 目录不在当前 PATH:$MISE_SHIMS"
  175. warn '配置 shell 激活后(下一步)mise 会自动把它加进去,不需要手工改 PATH' ;;
  176. esac
  177. printf '\n 以下 PATH 条目指向具体版本,属于"该收敛掉"的候选:\n'
  178. suspicious="$(printf '%s' "$PATH" | tr ':' '\n' | grep -E '/(node|python|jdk|jre|java|go|rust)[^/]*/(bin|versions)' || true)"
  179. if [ -z "$suspicious" ]; then
  180. ok '没有发现需要收敛的条目'
  181. else
  182. printf '%s\n' "$suspicious" | sed 's/^/ - /'
  183. warn '脚本不会自动删除它们。确认 mise 工作正常后,可以手工清理。'
  184. fi
  185. # ============================================================
  186. # 步骤 4:配置 shell 激活
  187. # ============================================================
  188. step '配置 shell 激活'
  189. if [ "$NO_RC" -eq 1 ]; then
  190. skip '按参数要求跳过(--no-rc)'
  191. else
  192. # 根据当前 shell 选择激活写法。
  193. # 全部都要带存在性判断:否则在 mise 还不可解析的会话里(PATH 尚未刷新的新终端、
  194. # 用户卸载了 mise)每次启动 shell 都会报 command not found。
  195. # 用 if 形式而不是 && 形式,避免在某些 rc 文件设了 set -e 时中途退出。
  196. case "${SHELL:-}" in
  197. */zsh)
  198. RC_FILE="${ZDOTDIR:-$HOME}/.zshrc"
  199. ACTIVATION='if command -v mise >/dev/null 2>&1; then eval "$(mise activate zsh)"; fi'
  200. ;;
  201. */bash)
  202. RC_FILE="$HOME/.bashrc"
  203. ACTIVATION='if command -v mise >/dev/null 2>&1; then eval "$(mise activate bash)"; fi'
  204. ;;
  205. */fish)
  206. RC_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/fish/config.fish"
  207. ACTIVATION='if command -q mise; mise activate fish | source; end'
  208. ;;
  209. *)
  210. RC_FILE="$HOME/.profile"
  211. ACTIVATION='if command -v mise >/dev/null 2>&1; then eval "$(mise activate bash)"; fi'
  212. warn "无法识别 shell ($SHELL),将写入 $RC_FILE"
  213. ;;
  214. esac
  215. if [ -f "$RC_FILE" ] && grep -qF "$ACTIVATION" "$RC_FILE" 2>/dev/null; then
  216. skip "激活行已存在于 $RC_FILE"
  217. else
  218. if [ "$DRY_RUN" -eq 1 ]; then
  219. plan "向 $RC_FILE 追加激活行: $ACTIVATION"
  220. else
  221. mkdir -p "$(dirname "$RC_FILE")"
  222. {
  223. printf '\n# 由 runtime-census 的 bootstrap.sh 添加:让 mise 按项目声明自动切换运行时版本\n'
  224. printf '%s\n' "$ACTIVATION"
  225. } >> "$RC_FILE"
  226. ok "激活行已写入 $RC_FILE"
  227. warn '想撤销就删掉该文件里带 "runtime-census" 注释的那两行'
  228. fi
  229. fi
  230. fi
  231. # ============================================================
  232. # 步骤 5:拉取声明的运行时
  233. # ============================================================
  234. step '拉取声明的运行时'
  235. if [ "$SKIP_TOOLS" -eq 1 ]; then
  236. skip '按参数要求跳过(--skip-tools)'
  237. elif ! command -v mise >/dev/null 2>&1; then
  238. warn 'mise 还不在当前 PATH 里,无法执行 mise install'
  239. warn '请重开终端后手工执行: mise install'
  240. else
  241. # 空 [tools] 是"按需"形态(模板默认):这时 mise install 什么也不会做,
  242. # 说清楚比静默跳过好——否则使用者会以为"拉取过了"。
  243. if [ -f "$MISE_CONFIG_FILE" ] && declare -F tools_keys >/dev/null 2>&1 && [ -z "$(tools_keys "$MISE_CONFIG_FILE")" ]; then
  244. skip '机器声明里没有要常备的版本(按需模式)'
  245. printf ' 版本需求写在项目自己的 mise.toml / .tool-versions 里;进项目后执行\n'
  246. printf ' mise install(只拉那个项目声明的版本),或用 mise x <工具>@<版本> -- <命令>。\n'
  247. else
  248. run_action 'mise install(按机器声明拉取全部运行时)' mise install
  249. done_msg '运行时已拉取'
  250. fi
  251. fi
  252. # ============================================================
  253. # 步骤 6:自检
  254. # ============================================================
  255. step '自检'
  256. if command -v mise >/dev/null 2>&1; then
  257. mise doctor 2>&1 | sed 's/^/ /'
  258. printf '\n 当前 mise 管理的运行时:\n'
  259. mise ls 2>&1 | sed 's/^/ /'
  260. else
  261. warn 'mise 尚未在当前会话可用,跳过自检。重开终端后执行 mise doctor。'
  262. fi
  263. # ============================================================
  264. # 收尾
  265. # ============================================================
  266. cat <<'EOF'
  267. ======================================================================
  268. 完成。接下来的用法:
  269. 重开一个终端,然后:
  270. 盘点本机所有运行时(包括未被 mise 纳管的)
  271. ./scripts/census.sh
  272. 在项目里声明所需版本,然后一次性执行命令
  273. mise use node@22 # 写入项目 .tool-versions
  274. mise exec -- node -v # 零全局状态地激活一次
  275. 查看这台机器上所有可用版本
  276. mise ls # 已安装
  277. mise ls-remote node # 可安装
  278. ======================================================================
  279. EOF
  280. [ "$DRY_RUN" -eq 1 ] && printf ' 这是空运行。去掉 --dry-run 才会真正执行。\n'
  281. exit 0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.