星数刚过千，vgpu 先给 Agent 修了间考场

说真的，先交代主角的体量。vercel-labs/vgpu，5 月 5 号创建，1,070 颗星，49 个 fork，版本 v0.3.1。放在这周聊的榜单语境里，这个数字排不上号。

但它的贡献者列表值得多看一眼。matiasngf，Matias Gonzalez，Vercel 员工，1,024 个 commits。第二名，claude，47 个 commits。仓库里躺着 .codex/environments 的环境配置和 .conductor 的编排设置，一个人类带着一队 Agent，四个月写出了八个包的 WebGPU 库。

一个人，一个 Claude。

更有意思的是它对「用户」的定义。README 六个卖点里有一条单独列着，Agent-ready，官网首页更是直接自称 the WebGPU library designed for agents。星数刚过千的库，凭什么说自己为 Agent 设计？拆开看，它把这句话落成了四层实打实的东西。

库的本体，小而硬

先把 WebGPU 库这部分讲清楚，不然「为 Agent 设计」就成了空中楼阁。

核心抽象只有一个，init() 返回唯一的 Gpu 上下文，其余所有入口函数 draw、effect、compute、frame、surface 都把它当第一个参数，没有隐藏全局状态。帧是显式的，frame(gpu, f => f.pass(target, effect))，一遍 pass 一次 clear 一次 draw，全部手动声明，不做隐式场景图。

最有辨识力的是类型化 WGSL 导入。.wgsl 文件像 TypeScript 模块一样 import 和 export，@vgpu/wgsl-std 提供 hash、noise、color 这些可复用声明，绑定名、类型和布局靠反射保持同步，不用手写声明也不用 codegen。多运行时是同构的，同一套 API 在浏览器、Node 无头（Dawn 后端）、确定性 mock 适配器三处跑同一份代码，测试永远不需要真 GPU。

整棵栈从 API 到 Agent 面摆开是这样。

左边是一个 API 带三个运行时加两层支撑，右边那条立柱是贯穿所有层级的 Agent 面，这个布局本身就是它的产品主张。

体积纪律是真纪律。一个完整全屏 effect 打包 25 KB gzipped，这条预算写进了 CI，超了直接红。老实讲，图形库敢把体积预算做成 CI 门槛的，我头一回见。

第一层，文档长成 Agent 能吃的样子

vgpu.sh 发布 agents.md（Agent 就绪清单）、llms.txt 和 llms-full.txt（全量文档导出）、OpenAPI 3.1 描述的 examples 发现 API，免 token 只读，外加一个无状态 MCP 端点挂在 /api/mcp。examples 的 artifacts 带 SHA-256，manifest 里明文要求 Agent 用前校验。

这些现在不少文档站都在跟，vgpu 做得早且全。真正下功夫的在 CLI。

npx vgpu docs cat getting-started.md 在终端里离线读文档，npx vgpu examples search raymarching 搜示例，npx vgpu examples pull <id> 把完整示例工程拉到本地，不用 clone 仓库。二十三个示例从渐变、黑洞 raymarching、FFT 海洋到 ONNX 跑 MNIST 和手势识别，全部可搜可拉。

还有个 vgpu doctor，诊断输出默认 JSON、退出码稳定、按 Debian、Fedora 还是通用 Linux 分别开处方。它有一篇专门的 ADR 解释设计原则，健康与否，由一次真实的 init 到渲染到回读决定，不靠探测环境变量猜。

第二层，给 Agent 修的考场

坦白讲，apps/agent-evals 是整个仓库最精彩的部分。它自己的 README 第一句就把姿态摆好了，这不是 benchmark，是一次观察。没有跨分支比分，没有排行榜。

考场机制长这样。先跑 pack-vgpu.mjs，把当前分支未发布的 vgpu 连同依赖闭包打成 tarball。这一步是精髓，README 里专门解释了为什么，如果给沙盒里的 Agent 一条 file: 链接直连 monorepo，它就能读到仓库源码，那是答案本身，而不是从发布面去发现这个库。Agent 必须像真实用户一样，从一个还没发布的包开始摸索。

然后起一个沙盒，装 tarball，进门先过 vgpu doctor 门禁。里面是一个中性编码 Agent，只有 bash、读写文件、glob、grep 这些基础能力，外加一个 view-image 工具让它真的能看见渲染出来的像素。每轮对话结束，hook 自动跑一遍任务验证，把整个工作区 tar 回快照目录。

三个考题设计得很讲究。s2-gradient 要求从 Node 渲出一张 128×128 红到蓝的渐变图，评分就是对 PNG 逐像素判。n1-hero-shader 要求在 Next.js 首页写一个悬停拖尾着色器，评分由 harness 自己完成 build、起服务、模拟 hover，不信 Agent 的口供。view-image-smoke 最简单也最根本，让 Agent 说出指定图片里的两个颜色，验证的是 view-image 这个工具真的把像素递到了 Agent 眼前。

整间考场连挂科回路一起画出来，长这样。

从左到右是考题流转，虚线是挂科回路，改的永远是库和文档，不是 Agent 的提示词。

你想想看，这个考场测的是什么。不是模型智力，是库的可发现性。Agent 找不找得到 vgpu docs，渲染挂了会不会跑 vgpu doctor，getting-started 文档能不能在一次尝试里存活。考不及格，改的是文档和 API，不是提示词。

第三层，CI 里的 GPU 和没有 GPU 的 GPU

图形库的 CI 是老大难，云上 runner 没有显卡。vgpu 的解法分两路，.github/dawn 用 Docker 自己构建 Dawn，lavapipe-build.yml 把 Mesa 的 lavapipe 软件渲染器打成可移植产物，Linux x64 和 arm64 都有，还锚定了 glibc 2.31 的老主机 ABI 下限。示例渲染在 CI 里出真图、传 artifact、全量缩略图严格比对。

lavapipe 的分发把同意边界划得很硬，只有显式跑 npx vgpu install-software-renderer 才下载，npm install 和 doctor 永远不碰它。下载层做了 32 MiB 上限、双文件 tar 白名单、哈希锁定、缓存目录禁符号链接，CHANGELOG 里那句「加固后的安全复审是干净的」，看得出被审过。

挑刺时间

讲真，刺不少，而且大部分和它的年轻直接相关。

其实吧，最扎的一根是 issue #387，Surface.read() 在渲染任务外调用时静默返回一个全零缓冲区，而不是报验证错误。图形库最怕静默错误，全零像素流回 pipeline，下游代码会拿着假数据继续算。同类还有 #385，FFT 海洋示例在 Firefox 上直接不工作，WebGPU 的跨浏览器现实比宣传页残酷。#383，Windows 上 examples pull 失败。#384，docs find 打印出来的路径 cat 打不开。

API 稳定性要划重点。#320 的 vNext API 讨论挂着 25 条评论，typed options、unified frames、pipeline preparation 都在重做，v0.3 就在动第二套 API，早期采用者务必锁死版本号。还有一条描述与实现的落差要说破，仓库简介里的 neural networks 目前是示例级的 ONNX Runtime 互操作，MNIST、深度估计、手势识别三个例子，不是内置张量引擎，冲着 GPU 张量来的读者要降低预期。

最后是结构风险。一个人 1,024 个 commits，第二名是 claude 账号的 47，bus factor 不用算了。vercel-labs 是 Vercel 的实验场组织，实验场的意思是，做成了可能转正，做不成可能归档，用它接生产项目前先想清楚这句话。怎么说呢，星数和基建密度的反差，一半是远见，另一半就是这份单点风险。

生态位

vgpu 和 three.js 不是对手，昨天刚合进来的 three-tsl 示例就是证明，WGSL 模块可以直接挂成 three.js 的 TSL 节点，FFT 海洋提速 7.7 倍的那次优化也是顺着这条路做的。它的真实生态位在裸 WebGPU 和重型引擎之间，替你扛住 Dawn、lavapipe、绑定布局这些脏活，又不上场景图的税。

能带走什么

我一直觉得这个仓库值得收藏的原因，不是又一个图形库，是一份「Agent 第一类用户」的参考实现，可以叫它考场模式。

文档要能被机器消费，llms.txt 和 MCP 是新常态。诊断要能被机器执行，doctor 输出 JSON 和稳定退出码，比写一万字 troubleshooting 强。示例要能被机器取用，可搜可拉可校验。最关键的一步，把自己的库装进沙盒，让一个什么都不会的 Agent 从零学会用它，观察它卡在哪，然后改库。用户的下限就是产品的下限，当你的用户里有 Agent，下限测试就得让 Agent 来考。

这套迁移面极广。你写 SDK、写 CLI、写框架，问自己一句，一个从没见过文档的 Agent，能不能在一次对话里把我的东西跑起来。vgpu 把这道题做成了工程。

至于它自己，盯三件事，vNext API 落地后的破坏面，那颗静默全零的 read 什么时候改成大声报错，以及一个人的健康。实验场里长出来的好东西，最需要的是一支队伍。