Skills Manager v1.38.0
发布日期：2026-09-08
递交范围：v1.37.1...v1.38.0
发布概览
- 从大仓库里装一个 skill，现在下载的是那个 skill，不是整个仓库。
用户可见更新
- 安装或更新来源指向单个 skill 目录时，改为只拉取那一个目录（partial clone + sparse-checkout）。从
anthropics/skills装mcp-builder，磁盘缓存从 15 MB 降到 472 KB。同一仓库的多个 skill 共用一份缓存，装第二个只花它自己那部分文件的代价。这条路上任何一环不成立——服务端不支持 partial clone、git 版本太老、子目录已被上游挪走、来源指向的是一整个技能文件夹而非单个 skill——都会退回完整检出，所以它只可能让安装更快，不会成为安装失败的原因。 - 配了代理不再让仓库缓存失效。此前缓存刷新把代理配置传给
git fetch的位置是 git 直接拒绝的，代理用户的刷新每次都失败，每次安装和更新都在从头重新克隆整个仓库。缓存建好之后再改代理，现在也能生效。 - 取消安装不再顺手丢掉一份健康的仓库缓存——此前这会让下一次安装重新下载全部内容。
- 仓库缓存现在有上限了。此前没有任何代码会删除缓存条目，所以每接触一个新仓库就永久多一份——一台正常使用的机器上是 48 个仓库、569 MB，最老的四个月没动过。超过 1 GB 时按最久未使用淘汰；被淘汰的仓库只有在再次安装或更新该 skill 时才会重新下载。正在被其他安装占用的仓库会跳过，不会被从底下删掉。
开发者与治理更新
clone_repo_ref_scoped成为唯一的克隆入口，只有调用方指明了单个 skill 目录时才走窄路径。不带 subpath 的预览、skills.sh 按 id 定位安装、resolve_skill_dir的全仓兜底，以及任何指向容器目录的 subpath，仍然从独立的缓存槽拿到完整目录树——需要搜索整个仓库的流程一行没动。- 窄路径的校验要求 subpath 本身是一个 skill，而不只是「里面装着 skill」。否则容器目录会通过校验，而
resolve_skill_dir的 locator 全仓搜索就落在一棵只有一个目录的树上——它不会干净地失败，而是可能解析到恰好在窄范围内的另一个 skill。 - 窄检出通过拷贝缓存来产出，而不是
git clone --local：从 partial clone 克隆会让源仓库去提供它自己没有的对象，git 直接以could not fetch <oid> from promisor remote中止。 sparse-checkout set对仓库里没有的路径是成功的，只是那个路径不存在而已，所以结果要先验证确实落到了一个 skill 才使用。subpath 一律不做「整理」再交给 git：unix 上结尾空格和反斜杠都是合法的目录名字符，改写它会把范围缩到隔壁目录并通过校验，而调用方读的是检出里没有的那个路径。- 缓存侧的
sparse-checkout、checkout和reset --hard在 partial clone 里都会去网络取 blob，因此它们带着与克隆相同的超时、取消旗标和当前代理配置。 - 交给调用方的安装检出，在离开本模块前会解除与 promisor 远端的关联，因此它不是 partial clone。这一步是让窄克隆不至于对以后每次改动都收税的关键：调用方会对这份检出直接跑
git，不解除的话，任何碰到未获取对象的命令都会悄悄变成一次可能挂住的网络往返。解除之后，缺失对象立刻报错——和之前的完整浅检出完全一样。准确的说法是「不会有命令背着调用方去取对象」，而不是「这个目录里跑什么都是本地的」：显式fetch/pull照样联网，只是当前没有调用方这么做。git 从三个设置中的任意一个都会注册 promisor 远端，所以三个都清掉；其中一个测试用真实的file://partial clone 断言结果，而不是断言设置的名字。
当前校验状态
- ✅ 跨平台构建通过（macOS Intel / macOS ARM / Windows x64 / Linux x64 / Linux ARM64）
- ✅ TypeScript typecheck 通过
English release notes
Release date: 2026-09-08
Commit range: v1.37.1...v1.38.0
Release Overview
- Installing one skill out of a large repository now downloads that skill, not the repository.
User-facing
- Installing or updating a skill whose source names one skill directory now fetches only that directory, using a partial clone and a sparse checkout. Installing
mcp-builderout ofanthropics/skillswent from 15 MB to 472 KB of cache on disk. Skills from the same repository share one cache, so the second one costs only its own files. Anything that can go wrong here — a server that refuses partial clones, a git too old to read the arguments the way we mean them, a subdirectory upstream has since moved, a source that names a folder of skills rather than one skill — falls back to the full checkout, so this can only make an install faster, never make it fail. - A configured proxy no longer defeats the repository cache. The cache refresh passed the proxy setting to
git fetchin a position git rejects outright, so for proxy users the refresh failed every time and every install and update re-cloned the whole repository from scratch. A proxy changed after a repository was first cached is now picked up too. - Cancelling an install no longer throws away a healthy repository cache, which used to make the next install download everything again.
- The repository cache is now bounded. Nothing ever deleted an entry before, so it grew by one checkout per repository forever — 569 MB across 48 repositories on an ordinary machine, the oldest untouched for four months. Above 1 GB the least recently used repositories are dropped; they are re-downloaded only if that skill is installed or updated again. A repository another install is working on is skipped, never deleted underneath it.
Developer & Governance
clone_repo_ref_scopedis the single clone entry point; the narrow path is taken only when the caller names one skill directory. Preview with no subpath, skills.sh locator installs,resolve_skill_dir's repo-wide fallback and any container subpath all still get a whole tree from a separate cache slot, so the flows that search a repository are untouched.- The narrow guard requires the subpath to be a skill, not merely to contain one. A container would otherwise pass while leaving
resolve_skill_dir's locator search on a one-directory tree, where it does not fail cleanly — it can resolve a different skill that happens to be in scope. - A narrow checkout is materialized by copying the cache, not by
git clone --local: cloning from a partial clone makes the source serve objects it does not have and aborts with "could not fetch from promisor remote". sparse-checkout setsucceeds on a path the repository does not have, simply leaving it absent, so the result is inspected for an actual skill before it is used. Subpaths are never tidied up before being handed to git: on unix a trailing space or a backslash is a legal part of a directory name, so rewriting one would narrow to a neighbour and pass the guard while the caller read a path the checkout lacks.- The cache-side
sparse-checkout,checkoutandreset --hardall fetch blobs over the network in a partial clone, so they carry the clone's timeout, cancel flag and current proxy. - An install checkout is detached from its promisor remote before it leaves this module, so it is not a partial clone. This is what keeps the narrow clone from taxing every future change: callers run plain
gitagainst the checkout, and without the detach any command reaching an unfetched object would silently become a network round trip that can hang. Detached, a missing object is an immediate error — exactly as in the shallow full checkout that came before. The precise claim is that nothing fetches behind a caller's back; an explicitfetchorpullagainst origin would still use the network, and no caller does that. Three settings can register a promisor remote, so all three are cleared, and one of the tests asserts the outcome over a realfile://partial clone rather than the names of the settings.
Current Verification
- ✅ Cross-platform build passed (macOS Intel / macOS ARM / Windows x64 / Linux x64 / Linux ARM64)
- ✅ TypeScript typecheck passed
完整变更：v1.37.1...v1.38.0