内容基准：vgpu v0.4.0 ＋官方 CLI 参考、Examples API 与仓库 packages/vgpu 源码。本篇是 vgpu 系列第 3 篇：命令行把"文档、校验、示例、诊断"四件事收进一个随包工具。CLI 随 vgpu 包分发，无需单独安装，一律 npx vgpu <command>。

vgpu CLI 全命令，与"可信示例"工作流

0. 命令总览

命令	干什么	给谁用
`docs`	离线浏览随包文档（ls/cat/grep/find/path/symbols）	agent 与人
`check`	校验 + 反射一个 `.wgsl`，输出 JSON	编辑器/pre-commit/CI
`examples`	检索/查看/拉取官方示例源码（永不执行）	agent 与人
`mcp`	把 docs/examples 用 stdio 以 MCP 工具暴露	agent（详见第 2 篇）
`doctor`	端到端诊断本机能否无头渲染，输出 JSON 结论	装机第一步
`install-dawn`	下载并 sha256 校验 portable Dawn（Node 渲染后端）	Node 无头
`install-software-renderer`	下载并校验 portable CPU 渲染器	无 GPU 的 CI/服务器
`snapshot`	vgpu 自家 CI 的内部像素自测	仅库维护者

全局：--help/-h、--version/-v。

1. `docs`：离线文档即数据库

整份 API reference + guides 打包进 npm 包，docs 命令全部本地执行、离线可用。子命令：

子命令	作用	示例
`ls [path]`	浏览文档树	`vgpu docs ls /guides`
`cat <path\|symbol>`	打印某页/某符号	`vgpu docs cat getting-started.md`、`vgpu docs cat /@vgpu/core/Buffer.docs.md`
`find <query>`	按名找"下一该读哪页"	`vgpu docs find buffer`、`vgpu docs find "wgsl loader"`
`grep [-i] [--package <pkg>] <pattern>`	页内精确匹配 + 行号	`vgpu docs grep -i --package @vgpu/wgsl minify`
`path <symbol\|path>`	解析成可用的虚拟路径	`vgpu docs path Buffer`
`symbols`	列出已索引符号	`vgpu docs symbols`

find 的检索语义值得记（agent 用得最多）：查询词逐个词都要命中（AND），先查符号名/文档路径/标题/页面声明的关键词；只有这些都找不到才回退搜正文——所以散文式查询（如 typescript wgsl import）和错误码（如 VGPU-WGSL-PKG-NOTFOUND）都能定位到页。结果按相关度排序、上限 20 条，截断时末尾会告诉你藏了多少条（提示你加词缩小范围）。

使用建议（与官方 skill 一致）：陌生项目先 cat getting-started.md；找任务/符号用 find；查页内细节用 grep；改任何代码前把相关页 cat 通读一遍。

2. `check`：WGSL 的"编译器前端"校验

vgpu check <file.wgsl> 校验而不执行 shader。成功输出反射 JSON；失败报告错误并非零退出。可放进编辑器、pre-commit、CI。

npx vgpu check ./shaders/main.wgsl
npx vgpu check ./shaders/main.wgsl --require-validation
VGPU_VALIDATE=require npx vgpu check ./shaders/main.wgsl

device-backed 校验的行为：默认 "auto" 模式——本机有 WebGPU device 时，非法 WGSL 判失败；没有 device 时只告警一次但仍输出反射。CI 里想"没 GPU 就失败而不是悄悄降级"用 --require-validation（或设 VGPU_VALIDATE=require）。

JSON 契约不随机器变化：即便校验失败，check 也会把完整 payload（diagnostics、reflection、wgsl）打出来，失败记在 validation.error（含 code/message/fix?/where? 等）且 ok:false、退出码 1；validation 对象本身带 { mode, attempted, ok, skipped? } 说清到底做了什么。只有解析级失败（缺 import、模块声明了 bindings、非法的 VGPU_VALIDATE）才是硬错误——stderr 打一个错误对象、无 payload。

价值点：校验与反射合一——同一份 JSON 既告诉你"有没有错、错哪、怎么修"，也把绑定结构吐给下游（agent 就能据此写对 binding，不用手猜）。

3. `examples`：可信示例，只读、不执行

examples 从官方 gallery（https://vgpu.sh）检索/查看/拉取示例源码，任何情况下不执行拉下来的代码。官方明确写着 canonical agent invocation：npx vgpu examples ...。

用法概览：
  vgpu examples search <query> [--any] [--limit <n>] [--revision <sha256>] [--offline] [--pretty]
  vgpu examples show   <id>      [--revision <sha256>] [--offline] [--pretty]
  vgpu examples cat    <id> <path> [--revision <sha256>] [--offline] [--json]
  vgpu examples pull   <id> --out <dir> [--revision <sha256>] [--offline] [--force] [--pretty]
  vgpu examples cache path | clear

search：按主题找（默认 top-20，--limit 最多 100；--any 放宽为任一关键词命中）。
show：看某个示例的 manifest 与文件清单。
cat：打印示例里单个文件（--json 结构化）。
pull：把整个示例复制进本地目录（--out 必填）。
cache path / clear：查/清已验证缓存。
--revision：pin 不可变 sha256 版本；--offline：断网只用之前验证过的缓存，结果带 lastVerifiedAt。

退出码（$? 即 agent 可判断的结果）：

码	含义
`0`	成功
`2`	`VGPU-EXAMPLES-USAGE`
`3`	`VGPU-EXAMPLES-NOT-FOUND`
`4`	`VGPU-EXAMPLES-NETWORK`
`5`	`VGPU-EXAMPLES-INTEGRITY` / 不兼容 API
`6`	`VGPU-EXAMPLES-DESTINATION-EXISTS`
`7`	`VGPU-EXAMPLES-FILESYSTEM`

4. `doctor` / `install-dawn` / `install-software-renderer`：Node 渲染环境三件套

npx vgpu doctor                     # 端到端：真渲染一帧，输出 JSON 结论
npx vgpu doctor --no-render         # 只做非渲染检查
npx vgpu doctor --pretty            # 人类可读版

doctor 健康退出 0，有问题非零，并在 JSON 里给出修复建议。任何新机器动手前先跑它。

install-dawn：下载并校验 portable Dawn 预编译（Node 无头渲染的后端）。--ignore-scripts/pnpm allow-list 禁用脚本时，下载会推迟到首次 init()，或手动跑它。
install-software-renderer：无 GPU 的 CI runner / 无头服务器装一个 portable CPU 渲染器。装好后 init() 自动兜底用；想强制走 CPU 用 init({ adapter: "software" })，想"必须真 GPU"用 init({ adapter: "hardware" })（没 GPU 就报错而不是静默降级）。
snapshot：仅 vgpu 自家 CI 用（VGPU_DOCKER_TEST=1 的 Docker GPU harness 里做像素回归）；验证你自己的机器请用 doctor。

5. 背后的 Examples API（写给机器的那一层）

examples 工作流背后的机器接口是个无 token、只读的版本化 API，MCP 与 CLI 复用的是同一套兼容性 + sha256 校验。关键事实：

发现：GET https://vgpu.sh/.well-known/vgpu-examples.json 列出契约与可变 latest 指针；完整 OpenAPI 3.1 在 /openapi.json。
不可变链：latest 指针 → 指向不可变 revision + index 的 sha256 摘要 → 按 indexUrl 跟进（别用未校验的值拼 revision URL）→ index 列出示例 → manifest 含 metadata + files[]（每文件带 artifact URL、大小、类型、sha256 摘要）。artifact 路径可含斜杠，照 manifest 返回的 url 走，别自己拼路径。
缓存/完整性：revision index/manifest/raw artifact 不可变，可缓存一年，都带 ETag；用下载内容前要自己校验各级 sha256。CLI 工作流会自动做这些校验。
方法/CORS：只支持 GET/HEAD/OPTIONS，其余 405；跨域无需凭证。
错误：稳定 JSON 信封 { "error": { "code": "VGPU-EXAMPLES-NOT-FOUND", "message": "Artifact not found" } }；404 重发现、405 方法不支持、500 是 VGPU-EXAMPLES-STORAGE（重试，别当成示例不存在）。

给 agent 的建议（官方原文）：优先用无状态只读的 MCP 端点 https://vgpu.sh/api/mcp；需要下载时用 npx vgpu mcp --project-from-cwd 或绝对 --output-dir。想手写 HTTP 就别了——npx vgpu examples … 把协议都包好了。

6. agent 视角：把四件事串成一个工作流

一条典型的"用 CLI 干活"链子（正好对应本系列第 1 篇的指路法）：

npx vgpu                        # ① 自举：打印"如何读自己"
npx vgpu docs find "<主题>"      # ② 定位该读哪页
npx vgpu docs cat <path>        # ③ 读透再写代码
npx vgpu examples pull <slug> --out ./demo   # ④ 拉一个可信示例当参照
npx vgpu check ./shaders/x.wgsl # ⑤ 写完就地校验
npx vgpu doctor                 # ⑥ (Node) 换机器先查环境

贯穿始终的安全属性：examples 永不执行代码，check 只校验不运行，下载走 sha256 校验——agent 可以放心地把"抄示例 / 校验 shader"交给 CLI 而不用担心在宿主上执行不可信代码。这个分工（文档在 CLI 里、示例有完整性校验、校验独立于执行）是我认为 vgpu 工具链最"agent-safe"的设计点。

参考与来源

官方 CLI 参考、Examples API
仓库 packages/vgpu/bin/vgpu.js 与 lib/docs、lib/examples
相关栏目：MCP 入门（docs/code）

0. 命令总览​

1. docs：离线文档即数据库​

2. check：WGSL 的"编译器前端"校验​

3. examples：可信示例，只读、不执行​

4. doctor / install-dawn / install-software-renderer：Node 渲染环境三件套​

5. 背后的 Examples API（写给机器的那一层）​

6. agent 视角：把四件事串成一个工作流​

参考与来源​