SuperAPI AI 工具集

iwsdk-project-setup

编程与开发

查看项目

更新于 11-17 00:31

技能介绍

该技能由 Navid Mirzaaghazadeh 制作,属于 iwsdk-webxr-skills,采用 MIT 许可。目标是把机器和项目调整到官方 iwsdk-* 技能所期望的状态:一个 IWSDK 1.x 的 manifest-first 项目、依赖已安装、Claude Code 已连接项目 MCP 服务器,并且 npx @iwsdk/cli dev status 报告 browserCommandReady: true。后续交接:构建功能交给 iwsdk-dev;在 Quest 上测试交给 iwsdk-quest-device-testing;0.4.x 项目(GLXF、Meta Spatial Editor)先交给 iwsdk-migrate-0-5。

基本规则:安装 Node、Playwright 浏览器、Android 平台工具或任何全局内容前先询问;未经同意不运行 npm i -g,也不编辑 ~/.claude。adapter sync 会写入项目配置(.mcp.json、.claude/settings.json),在已有仓库中运行前要说明。不要安装重复技能:每个脚手架已在 .claude/skills/ 内含 12 个官方技能(.agents/skills/ 有副本),此类项目只安装本库的 custom/ 和 extra 技能。始终使用带作用域的 npx @iwsdk/cli ...,作用域是安全边界。依赖标志前先用 --help 确认。该技能对照 1.0.1 验证(npm latest;1.1.0-rc.1 在 next 上并把 three 换为 super-three@0.185.0,仅在用户要求时使用)。Meta 站点上的 IWSDK 文档由 0.5.3 生成,展示无作用域 npx iwsdk、端口 5173、45 个 MCP 工具和两个 1.0.1 拒绝的 VR Glasses 配置键,应优先参考已安装包和 https://iwsdk.dev。

使用流程:第一步检查机器,node --version 需满足 >=20.19.0 <21 || >=22.12.0 <23 || >=24.0.0,并检查 npm 和 git;Node 版本不对时询问用户使用的版本管理器,不要替其选择。Android 平台工具和桌面 Chrome 目前可选,但头显测试需要。第二步把构想映射为标志:完全虚拟世界 --target vr;透视/真实房间内容 --target ar;桌面浏览器 3D --target browser;重力、碰撞、投掷 --physics;大空间行走/传送 --locomotion;拾取移动物体 --grabbing;真实墙面地面桌子锚点 --scene-understanding(仅 AR);在真实表面放置物体 --environment-raycast(仅 AR);每个布尔项都有 --no-… 形式;--yes 默认 TypeScript、git init、安装。若构想歧义会影响目标或功能,应询问。第三步脚手架,例如 npm create @iwsdk@latest my-game -- --yes --target vr --grabbing --physics --no-locomotion,或 npx @iwsdk/create@latest 同参数;已有非空仓库需 --force 并会覆盖冲突的生成文件。常用附加项:--no-install、--no-git、--language js、--skip-reference-warmup。生成内容包括 iwsdk.config.json(项目权威:场景、资产/组件模块、world.xr、功能、dev.emulator)、src/index.ts、src/assets.ts、src/components.ts、public/scenes/main.iwsdk.scene.json、public/ui/welcome.uikitml、AGENTS.md + CLAUDE.md、.claude/(12 技能、4 规则、agents/iwsdk-project-code-reviewer.md、settings.json)。功能改动应修改 iwsdk.config.json 而非重新脚手架,编辑会原地重启 Vite。

第四步安装并连接 Claude Code:cd my-game、npm install、npx @iwsdk/cli adapter sync --tools claude、adapter status、reference warmup、reference status。adapter sync 写入 .mcp.json,最多三个 stdio 服务器:iwsdk-runtime(@iwsdk/cli/dist/cli.js mcp stdio,1.0.1 中 55 个工具:xr_* 16、browser_* 6、scene_* 13 含 3 个实时运行时检查器、ecs_* 11、ui_* 3、asset_render_preview、runtime_* 5)、iwsdk-reference(@iwsdk/reference 入口,语义搜索、API 查询、组件/系统列表)、metavr(@meta-quest/metavr/bin.js mcp server,Quest 设备控制、Meta 文档搜索、3D 资产搜索)。它还会在 .claude/settings.json 添加 enabledMcpjsonServers 和窄化的 mcp__<server>__* 允许规则,并移除旧的 enableAllProjectMcpServers: true。之后重启 Claude Code 会话并用 /mcp 检查。MCP 工具缺失时可用 CLI 对应命令,如 npx @iwsdk/cli xr status、browser screenshot;npx @iwsdk/cli mcp inspect --tool <name> 打印模式。克隆他人仓库时 .mcp.json 等被 git 忽略,需重新 install、adapter sync 和 reference warmup。

第五步启动开发服务器:npm run dev(= iwsdk dev restart --open --foreground,有头并附着)、npx @iwsdk/cli dev up --ai-mode agent(无头、固定 800x800 视口)、--ai-mode collaborate(一个可见受管 Chromium 窗口含 Runtime/Editor)、dev status、dev logs --tail 100、dev down。有头/无头由开发者决定,重启前告知。等待 browserCommandReady: true 后再执行 browser、XR 或 ECS 命令。端口 8081 被占用时不会自动切换,需停止其他进程或改 server.port。HTTPS 默认开启,自签证书缓存在 .iwsdk/https,受管浏览器接受,头显显示一次性警告;iwsdkDev({ https: false }) 可关闭(此时 WebXR 仅 localhost 可用)。首次冒烟测试:npx @iwsdk/cli browser screenshot --output-file artifacts/first.png,然后 npx @iwsdk/cli xr enter 和 xr status。

第六步模拟器(IWER)设置,在 iwsdk.config.json → dev.emulator:device 默认 metaQuest3,也支持 metaQuest2、metaQuestPro、metaVRGlasses、oculusQuest1;activation 默认 localhost(可选 always 或 RegExp);userAgentException 默认 /OculusBrowser/;environment 默认 none(AR 脚手架用 living_room),可选 living_room、meeting_room、music_room、office_large、office_small;iwer 默认 true(false 表示不注入,适合纯浏览器应用);injectOnBuild 默认 false,商店构建保持 false。旁边的 dev.targetDevicePreview.gazeSimulation: "head"(1.0.1)在应用请求 gazeTracking 时为真实 Quest 会话添加头部定向测试注视源,仅开发服务器,且需保持 iwer 开启。

云和无头机器:受管浏览器是 Playwright Chromium,自动选择 GPU 或 SwiftShader,可用 IWSDK_GPU=auto|gpu|swiftshader 覆盖;SwiftShader 帧时间对性能无意义。Executable doesn't exist 错误时按项目解析的 Playwright 版本安装浏览器。长截图消耗上下文,可在 dev up 用 --screenshot-width 500 --screenshot-height 500。

向现有 Vite 应用添加 IWSDK:优先用相同目标脚手架临时项目并复制其 iwsdk.config.json、vite.config.ts、src/assets.ts、src/components.ts、.claude/ 和 AGENTS.md;运行时需要共享一个 Three.js 实例,依赖中 @iwsdk/core ^1.0.1、three npm:super-three@0.181.0,并有对应 overrides;从 @iwsdk/core 导入 Three.js 类,保持所有 @iwsdk/* 同版本。

副作用与隐私:脚手架把 @meta-quest/metavr 加为开发依赖。首次 npm install 前应告知用户:postinstall 会在项目外写入,从 securecdn.oculus.com 下载二进制到 ~/.metavr(或 $METAVR_HOME)并向 ~/.zshrc、~/.bash_profile/.bashrc 或 PowerShell 配置文件追加补全块;可用 METAVR_SKIP_DOWNLOAD=1 npm install 避免,或移除该包。遥测:安装后 @iwsdk/cli 和 Vite 插件通过 metavr 报告每次运行时工具调用(工具名、时长、固定失败码、会话 id),metavr 也有自身遥测;可用 npm exec metavr -- telemetry status / telemetry disable 管理;npm uninstall @meta-quest/metavr 可同时停止两者并移除 metavr MCP 服务器和设备工具(仍可直接用 adb),让用户选择。

故障排查涵盖:Node 不支持、端口占用、browser_not_launched、运行时命令超时(依次 xr status → 浏览器日志 → 浏览器重载 → dev restart)、Claude 中缺少 iwsdk-runtime 工具、参考工具要求 warmup、更新后 node_modules/.vite/deps 的费解错误(停服后 rm -rf 再启动)、"Only pmndrs/uikit components can be added as children"(重复 Three/UIKit 图,保留 resolve.dedupe)、npm 11.19 下 EALLOWSCRIPTS 安装失败(手动 npm install 并用 install-scripts 批准/拒绝相关脚本)、一台机器两个应用共用 8081(改第二个 server.port)、/mcp 显示两三个 metavr 服务器和重复 hz-* 技能(有人运行了 metavr init,应保留 adapter sync 条目和单一技能来源)。