内容基准：vgpu v0.4.0 ＋本地仓库源码（含 skills/vgpu/SKILL.md、packages/vgpu/bin/vgpu.js）。本篇是 vgpu 系列第 1 篇，回答一个问题：一个库要"为 coding agent 而生"，到底该提供什么？

让 Agent 用 vgpu：指路 CLI、官方 Skill 与"版本纪律"

官方把 vgpu 称作 agent-first library。要理解这四个字，最直接的切入口是官方给 agent 的起点——三样东西，按"从轻到重"排：

机制	一句话	适用场景
指路 CLI	告诉 agent「`npx vgpu`」，它自己会打印"如何读自己"	任何一次随手的 agent 会话
Skill 路由器	`npx skills add vercel-labs/vgpu`，装一个不背 API、教你查文档的轻量 skill	agent 支持按描述自动加载 skill
MCP	hosted `https://vgpu.sh/api/mcp`（只读）或本地 `npx vgpu mcp`	agent 需要"检索文档 + 读/下示例"的结构化工具

三者共享同一条设计主线，也是全篇要反复强调的：

文档以"装在你项目里的那个 vgpu 包"为准，随包分发、离线可查；任何 skill / MCP / 网上文档都只是方便层，不是权威。 权威 = node_modules 里那份与你的代码同版本、同 Commit 的文档。

1. 指路 CLI：help 本身就是 agent 的入门

vgpu 裸命令的输出不是"帮助列表"，而是一份写给 agent 的自举指南。以下文本逐字摘自 v0.4.0 仓库 packages/vgpu/bin/vgpu.js 的 help 常量（即裸 npx vgpu 或 npx vgpu --help 打印的内容）：

## Read the docs
  npx vgpu docs cat getting-started.md    The guide for using the current API correctly
  npx vgpu docs find "<topic | symbol | VGPU-error-code>"
  npx vgpu docs cat <path>

## Validate shader code
  npx vgpu check <file.wgsl>              Validate and reflect a WGSL file as JSON
  npx vgpu check <file.wgsl> --require-validation
                                          Fail instead of skipping when no WebGPU device is available

## Working examples
  npx vgpu examples search "<topic>"
  npx vgpu examples pull <slug> --out <dir>

## Agent tools (MCP)
  npx vgpu mcp                           Serve docs and examples over stdio

## Node rendering environment
  npx vgpu doctor

注意第一句：它让你 先读 getting-started.md，而不是让你去网上翻文档。官方在 agent 页的原话是：

npx vgpu
That's the whole instruction. The command prints its own guide — starting with the agent get-started … plus the tools to explore and search every reference page, guide, and error code.

所以"接入"vgpu 的最朴素形态，就是在任务里给 agent 一句话。示例 prompt：

用 vgpu 给这个项目加一个 <效果>。
先跑 `npx vgpu`，按它输出的指引读对应文档（docs cat / find / grep），
再写代码，最后用 `npx vgpu check` 校验 .wgsl。

2. 官方 Skill：一个"版本中立的路由器"（重点拆解）

仓库里 skills/vgpu/SKILL.md 就是官方发布的那份 skill 的源码。先看它的自我描述（description 字段决定 agent 何时自动加载它）：

Build, debug, test, and optimize WebGPU projects using vgpu, its CLI, or @vgpu
packages. Use for vgpu API questions, WGSL workflows, browser or Node rendering,
integrations, testing, and performance work.

而它的 body 一开始就划定边界：

Treat the documentation bundled with the target project's installed vgpu package as the authority for that project. This skill is intentionally version-neutral: do not infer API shapes from the skill's Git revision, remembered APIs, the repository default branch, hosted docs, or a hosted MCP server when local package docs are available.

整份 SKILL.md 几乎没有一条"vgpu API 长什么样"的知识。它教的全是查证纪律。我把正文拆成四个机制点，这是整篇最值得抄的东西：

机制 A：先选对版本，再谈用法

skill 让 agent 从项目自己的包管理器里发现装的是哪个 vgpu，而不是 @latest 一把梭：

# 项目用了 pnpm
pnpm exec vgpu --version
# 项目用了 npm（--no 表示"不联网补装缺失命令"）
npm exec --no -- vgpu --version

它特意提醒：裸 npx vgpu / bunx vgpu 会悄悄下载缺失的包，所以只用来"发现本地版本"是危险的；npm 的 --offline 也不够（它会从缓存里补装）。

分支判断的完整逻辑：

情况	skill 让 agent 怎么做
有 manifest/lockfile 选中 vgpu，但本地没装	视为"依赖树不完整"；只读场景用 `npx -y vgpu@<选中版本> docs cat …`，不自行换版本
项目/用户都没选版本	才退化到显式稳定版 `npx -y vgpu@latest`
需要装新依赖	用项目包管理器装 `vgpu@latest`
prerelease	只有项目显式选中 `vgpu@next`/RC 才用；绝不拿 `@latest` 冒充

为什么这条很重要：skill 快照式的写法最怕"我把 v0.3 的 API 记成 v0.4"；把版本选择写进流程，等于让 agent 每次先对齐 lockfile 再说话。

机制 B：路由到"随包文档"再动手

skill 建议的动作序列（都在本机跑，随包文档离线）：

pnpm exec vgpu docs --help                 # 让"装的那个版本"自己定义有哪些命令
pnpm exec vgpu docs ls                     # 浏览文档树
pnpm exec vgpu docs cat getting-started.md # 陌生项目从入门读起
pnpm exec vgpu docs find "<主题 / 符号 / error code>"
pnpm exec vgpu docs grep -i "<词>"
pnpm exec vgpu docs cat "<path 或 symbol>" # 改代码前 cat 每一份相关页

它给 agent 的选路口诀：find 找"该读哪一页"（查符号名/路径/标题/关键词，实在不行才搜正文），grep 找"页内的具体细节"，cat 把要改的代码对应页面通读。

机制 C：MCP 也要"版本匹配"

skill 特别强调：要用 MCP 查资料，就通过项目本地的 vgpu mcp 起服务，这样 MCP 暴露的是同一份随包语料；而 hosted MCP 只是"当前稳定版"的便利层，永远不是某个被钉在旧版本的项目该信的权威。

机制 D：没见过的 API = 报告，不臆造

如果随包文档里没有某个 API 或工作流，skill 要求 agent：不要发明、不要默默切版本——报告不匹配，并且只有用户授权才允许换版本。这比"编一个差不多的 API 骗过去"诚实得多，也是库方主动防幻觉的设计。

小结：它其实是一份"元指令"

对比一下多数库的 skill：把 API 文档打包快照进 skill 正文——省事，但会过期、会和用户的版本错位。vgpu 的 skill 反过来：知识留在随包文档里，skill 只教 agent「怎么选版本、怎么查、查到再说」。这套"版本纪律"本质是 把 lockfile 思想延伸到文档——是我认为这个库对"如何给 agent 做开发工具"最值得抄的一个模式。

3. 在本博客（Claude Code 环境）里实际怎么用

如果你正在一个装了 vgpu 的项目里用 Claude Code，两种姿势：

姿势一：不装任何东西，纯靠指路。 任务里直接写 先跑 npx vgpu 并按指引读随包 docs。Claude Code 会执行命令、读输出、docs cat 对应页面再写代码——CLI 即接口。

姿势二：装官方 skill。 若你的 agent 支持按描述自动加载 skill（Claude 系的 Skill 机制即可），执行：

npx skills add vercel-labs/vgpu

安装命令没有分支钉死（skill 自己声明的"no branch pin"），版本纪律由 skill 正文运行时保证，而不是靠安装时锁 Git revision。装好后，会话里一出现 WebGPU/WGSL/vgpu 相关问题，skill 就会被其 description 命中并接管"先查哪个版本、再读哪页"的流程。

备注：本仓库自己的 .claude/skills 里也有一个"123"发布 skill，格式同为 SKILL.md+frontmatter（name/description）——可见 SKILL 这种"按需加载的指令包"正在成为库方给 agent 交付能力的通用格式。

4. 可抄清单：做"agent-first 库"时你会需要的

文档随包 + CLI 可查：让 docs ls/cat/find/grep 在无网环境也能工作，是 agent 可靠性的地基；
裸命令自举：your-lib 打印"如何读自己"，比任何 README 都更贴近 agent 的执行现场；
Skill 保持 version-neutral：教查证，别背快照；版本选择写进流程；
为"版本匹配"预留接口：hosted 服务永远只是便利层，本地/随包才是权威；
未知即报告：宁可让 agent 说"文档里没有"，也不要让它在幻觉上继续写。

下一篇 MCP 用法展开 hosted vs local 的接入细节；再下一篇 CLI 与示例把命令行与可信示例机制讲透。

参考与来源

官方文档 Agents 页、CLI 参考、MCP 参考
仓库 skills/vgpu/SKILL.md、packages/vgpu/bin/vgpu.js
相关栏目：MCP 入门（docs/code）

1. 指路 CLI：help 本身就是 agent 的入门​

2. 官方 Skill：一个"版本中立的路由器"（重点拆解）​

机制 A：先选对版本，再谈用法​

机制 B：路由到"随包文档"再动手​

机制 C：MCP 也要"版本匹配"​

机制 D：没见过的 API = 报告，不臆造​

小结：它其实是一份"元指令"​

3. 在本博客（Claude Code 环境）里实际怎么用​

4. 可抄清单：做"agent-first 库"时你会需要的​

参考与来源​