v0.3.0 — 更安全、更快、两端一致的扫描

让 Windows 与 Unix 的扫描结果保持一致、首扫更快，同时让工具下载安装有可校验的安全保障。

• 扫描规则两端一致：告警与去重对齐，含空格的路径不再被拆开，.nvmrc / .node-version 也算项目声明，PowerShell 版本探测不再多启动一次进程且能取到版本。
• 首扫更快：先并行探测所有候选，新增 -Throttle（默认 min(8, CPU 数)，-Throttle 1 为原来的串行），地图内容与串行一致；探测超时在 PowerShell 7 下结束整棵进程树，Windows PowerShell 5.1 用 taskkill /T /F。
• 安装更安全：配方安装强制校验官方 SHA256，下载前依次取配方钉死值、GitHub 发布资产 digest 和上游校验文件；都取不到就不下载，显式 -Sha256 与官方值冲突会报错。adb 改用官方带版本号的包并钉死 SHA256，同时校验 Google 公布的 SHA-1。
• 版本判断更可靠：超长数字段不会再让查找或扫描抛异常；semver 与 Python 的预发布只在完整精确匹配时满足要求；默认候选排序按版本号数值，同号正式版优先于预发布。
• 安全与稳定修复：扫描与探测不再经由脚本型启动器间接执行 shim，解释器不安全时只登记路径、不执行；修复 PowerShell 7 在非 UTC 时区下每次查找都重新探测并重写地图；关闭进度条，Windows PowerShell 5.1 下载 portable 归档不再被拖慢。
• 检查覆盖 macOS：CI 新增 macOS 任务，用系统自带 bash 3.2 做语法检查并跑 smoke；同时补充 .sh 中 $VAR 后接非 ASCII 字符要写成 ${VAR} 的规则。

验证：Windows PowerShell 5.1 / 7、Linux PowerShell 7 与 macOS 的检查通过；CI 新增 windows-baseline 在真实 runner 上记录首扫基线，版本与下载契约测试单独运行。除上面列出的校验与规则变化外，工具发现与安装用法不变。

Windows 用户建议按 README 快速开始。没有 Git 时，下载本页 toolkit-map-v0.3.0.zip，按 ZIP 接入指南操作；SHA256SUMS.txt 用于校验发布包。

v0.2.3 — 首次使用与支持入口

让第一次接触 toolkit-map 的用户能看懂用途，按一条明确路线接入项目，并在出错时找到解决办法。

• 重排 README：直观场景、稳定版下载、单项目接入和可复制的 agent 验收提示。
• 新增故障排查、撤销接入与卸载指南，补齐 ZIP 安装和稳定版升级步骤。
• 新增中文 Bug / 功能请求表单与支持链接。
• 明确 Windows 完整功能、Unix 扫描边界，以及发现与自动安装的能力区别。

验证：Windows PowerShell 5.1 / 7 接入流程实测通过，PR 与主分支 CI 的 Windows / Ubuntu 检查通过。工具发现与安装核心行为不变；大工具仍仅在预计安装占用 ≥1 GB 时确认位置。

Windows 用户建议按 README 快速开始。没有 Git 时，下载本页 toolkit-map-v0.2.3.zip，按 ZIP 接入指南操作；SHA256SUMS.txt 用于校验发布包。

v0.2.2 — 声明与安装边界修复

本次修复项目声明、版本比较与 portable 安装边界，并完善新用户的 Windows 接入说明。

• 嵌套/点号 mise 工具表返回 requirement_unsupported，避免忽略项目要求后回退全局版本。
• 修复 <=22、>22、=22.23 等部分版本范围的边界。
• portable 工具在最终目录再次验证；失败回滚该次新建目录，不登记失败副本。
• 重复安装仓库内已有的合适已验证版本时直接复用。
• README、指南、技能、通用/MDC 模板与 setup 补充单次 PowerShell 宿主调用；无需修改全局执行策略。

升级后请刷新接入规则：文件接入重新执行 setup；Cursor 全局 User Rules 重新生成并替换旧标记块，然后新开会话验收。安装位置询问仍仅在预计安装占用 >=1 GB 时触发。

兼容范围：Windows PowerShell 5.1/7 支持完整地图；Unix 仍提供 census.sh 扫描内核。轻量读取器不解释完整 TOML/mise 环境语义。安装位置确认由 agent 规则处理，CLI 不自动估算或弹窗。

验证：本地 PowerShell 5.1 全套、PowerShell 7 项目/安装契约、Bash 冒烟/语法、两内核 JSON 一致性及隔离 MapFile 的真实机器 scan/find 通过。安装回归使用本地假归档，不下载真实第三方工具。

附件是 Git 跟踪的源码 ZIP 与 SHA256SUMS.txt，不含本机工具、地图、凭据或缓存。

v0.2.1 — agent 规则接入与大工具存储选择

v0.2.1 — agent 规则接入与大工具存储选择

• README 明确安装后还需接入前端规则，区分全局与项目使用，新增 Cursor、Codex、Claude Code 指南及可复制通用/MDC 模板。
• setup 生成的规则和技能增加大工具下载前的位置确认：仅预计安装占用 ≥1 GB 时询问；用户已有合适位置偏好时复用。
• 补齐 TOOLCHAIN_ROOT 的临时/持久配置、TEMP 暂存、mise/rustup 的独立存储与缓存边界。已有副本不自动迁移；CLI 本身仍不估算体积或交互询问。

升级后请刷新已接入的规则：文件接入重新执行 setup，Cursor 全局 UI 重新生成 preview 并粘贴。详情见 agent 接入指南 和 存储与大工具安装。

v0.2.0 — 项目感知与可信发现

更新记录

v0.2.0 — 项目感知与可信发现

• 将机器清单与项目选择分开：find 每次读取当前或指定项目声明，支持 -Project / -Version，项目覆盖全局要求，版本缺失不降级。
• 在地图与两套扫描内核的探测链增加 shim 护栏，支持自定义目录，shim 永不作首选。
• 候选记录 verified/unverified/unavailable/skipped；普通零字节文件不再返回可用；版本探测读取 stdout/stderr、检查退出码并限制等待。
• 修复 PowerShell 7 scan 的宿主路径；PowerShell 专用探测禁用 profile。
• 稳定路径 ID，修复同版本 Prefer；重扫保留手工登记、备注和偏好；局部更新不刷新完整扫描年龄。
• 增加 setup / doctor，支持预览、规则备份、幂等接入；明确区分文件配置与实际 agent 行为。
• 统一地图动作 JSON 协议 v2、错误状态与退出码；v1 地图读取迁移，损坏/未知格式不覆盖。
• 加入进程更新锁、并发回归测试；工具别名/探测/安装配方集中在 tools.json，兼容 rg/ripgrep 的旧仓库目录。
• portable 安装验证实际版本，安装参数不能越出仓库；WhatIf 不联网；安装成功但无法发现文件会明确失败。
• CI 同时验证 PowerShell 5.1/7 的项目选择、接入、并发与扫描护栏，保留 Windows/Unix 扫描一致性检查。

升级说明：JSON 消费方应读取 schemaVersion: 2、ok、status、verification、requirement。默认查询更严格，旧版只有文件存在或版本提示的副本可能不再被选中。完整地图动作仍仅支持 Windows；Unix 保留扫描内核，map.sh 尚未实现。

v0.1.5 — 接入 Codex skill 发现

本版让 toolkit-map 可被 Codex 自动发现：\n\n- README 增加 Codex 用户级 skill 安装说明（~/.agents/skills/toolkit-map）\n- 继续保持本机地图与统一工具仓库不进入 GitHub\n- 根目录 SKILL.md 仍是唯一技能内容来源

v0.1.4 — 安装失败与地图写入加固

本次更新

• 检查 winget 的真实退出码：安装失败时返回非零，不再继续登记候选。
• map.json 与人类可读摘要改为临时文件写入后替换，降低中断导致半写入的风险。
• 扩展 map-smoke.ps1，覆盖 winget 失败、原子写入和临时文件清理。
• 稳定版安装说明更新到 v0.1.4。

本版本不包含任何本机地图、工具清单、统一工具仓库或硬编码本机路径。

v0.1.3 — 查找与安装边界加固

本次更新\n\n- 修复 find 返回地图中失效首选路径的问题：会复核候选，必要时现场修复并持久化。\n- find -Json 在缺失或修复场景下保持机器可读输出。\n- install 拒绝覆盖统一工具仓库中的已有版本目录。\n- portable 归档安装支持可选 -Sha256 校验。\n- 新增 tests/map-smoke.ps1，并接入 Windows CI。\n- 修正文档中的六个动作、稳定版安装方式和安装边界说明。\n\n本版本不包含任何本机地图、工具清单、统一工具仓库或硬编码本机路径。

v0.1.2 — 调用与安装流程边界修正

本版本把工具“调用”和“安装”彻底分开，并明确本机状态与 GitHub 仓库的边界。

重点变更：

• find 找不到工具时只做现场探测并报告缺失，不会自动安装。
• 只有明确执行 install，且确认本机没有副本时，才安装并登记。
• 明确 ~/.toolkit/map.json 与 ~/toolchains/ 是本机状态，不进入仓库。
• README、SKILL.md、参考手册和贡献指南与当前 portable、固定 URL、winget 安装路径保持一致。

发布前已通过 Windows 与 Ubuntu CI，以及本地文档、编码、Shell 语法、一致性和冒烟检查。

v0.1.1 — 文档体系与检查、JSON 契约修正、PATH_ORDER 语义收紧

v0.1.1 —— 文档体系与检查、JSON 契约修正、PATH_ORDER 语义收紧

新增

• docs/：参考手册、平台说明、贡献指南，各中英一份；README 精简为快速开始
• tests/check-docs.ps1 并接进 CI：防止只改了中英其中一份、或搬动文件后留下失效链接
• tests/verify-shell.ps1 从 scripts/ 移到 tests/（它是开发检查，不属于产品）

修正

• runtimes[].pattern 曾把内部中文标记（定向探测）直接写进 JSON，且不随 --lang 变化；
  机器可读字段混进本地化取值，非 UTF-8 locale 下无法匹配。改为经稳定键输出
  probe / deep-scan
• PATH_ORDER 之前只要解析到非 mise 副本就报警，于是 Windows 的 py 启动器（不受
  mise 管、mise 也不会生成 py.exe 的 shim、版本本来就满足声明）长期误报，而且按它
  自己给的建议改 PATH 也不会消失。现在只在解析到的版本确实不满足声明时才报
• census.sh 的 timings 字段名与单位都和 census.ps1 不同（seconds vs ms），而文档
  承诺的是毫秒；统一为 ms，并让 census.ps1 也在没有 --timing 时不填 timings
• 补上 bash 侧缺的记录字段：runtimes 的 root/pattern、conventions 的九个字段、
  resolution 的 allHits/stub。按文档写的消费者在 Unix 上原本会拿到 null
• 解析名单对齐为 python / python3 / py；去掉 pip——pip --version 报的是 pip 自己的
  版本，拿它跟“声明要求 python 3.12”比是范畴错误

契约

• 只负责“工具与版本”这一层，不接手应用环境诊断（端口、.env、依赖目录、执行位）
• 两份实现的 JSON 共享一份“文档化的核心”，不再要求逐字段完全一致；实现可以带自己
  的附加字段。唯一被强制的是机器可读标识符必须是稳定 ASCII