尧图网页设计 
Claw3D开发者指南代码地图、测试体系与贡献流程完整教程【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3DClaw3D 是一个为 AI 智能体打造的开源 3D 虚拟办公室基于 OpenClaw 网关构建让你能走进一个实时 3D 办公空间亲眼看到你的 AI 团队协作、开会、审查代码、执行任务。本指南是面向新手的 Claw3D 开发者指南带你快速看懂项目代码地图、跑通四层测试体系并按标准贡献流程提交你的第一个 PR。一、5 分钟认识 Claw3D我们贡献的是什么在动手改代码前先建立正确的心智模型官方文档 CODE_DOCUMENTATION.md 称之为 Repo Mental ModelOpenClaw负责智能体执行、会话、工具与运行时事件Claw3D负责可视化层、本地 Studio 设置、UI 工作流、3D 办公室渲染以及同源的 WebSocket/API 桥接原则涉及运行时权威状态如会话、任务、对话记录时以 Gateway 数据为准纯本地偏好则放进 Studio 设置。技术栈一览层面技术Web 应用Next.js 16 App Router React 19 TypeScript3D 办公室Three.js、React Three Fiber、Drei构建器/查看器Phaser单元测试Vitest端到端测试Playwright运行依赖Node.js 20 / npm 10无需数据库和 Docker新手必读的 5 份文档文档用途README.md安装与快速开始ARCHITECTURE.md系统边界与数据流CODE_DOCUMENTATION.md 实用代码地图、扩展点与上手顺序CONTRIBUTING.md本地工作流、测试与 PR 规范ROADMAP.md近期优先级适合找新手友好任务二、本地环境搭建5 步跑通开发服务器前置说明Claw3D 是纯 UI 仓库不会替你安装或构建 OpenClaw。若只想体验界面可直接用内置 Demo 网关见第 5 步。# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/cl/Claw3D claw3d cd claw3d # 2. 安装依赖 npm install # 3. 初始化环境变量 cp .env.example .env # 4. 启动开发服务器端口 3000 npm run dev然后打开http://localhost:3000在 Studio 中配置网关 URL 与 Token 即可。零依赖体验 Demo 模式不想装 OpenClaw运行npm run demo-gateway启动模拟网关含演示智能体、流式聊天与办公室在场状态再执行npm run dev在连接界面选择Demo backend指向ws://localhost:18789即可。三、代码地图速览5 个核心目录 3D 办公室架构理解目录结构是贡献代码的第一步。Claw3D 的目录划分非常清晰目录职责src/app/Next.js 路由入口与 API 路由尽量只做组合不堆业务逻辑src/features/垂直功能切片agents车队/聊天/审批、office办公室界面/构建器、retro-office3D 沉浸式运行时src/lib/跨功能共享的领域逻辑与适配器gateway、office、studio、skills、cron等server/自定义 Studio 服务器与 WebSocket 代理网关凭据保留在服务端tests/自动化测试unit回归主力 Playwright 端到端scripts/仓库工具脚本如claw3doctor诊断、开发服务器冒烟检查两套办公室技术栈别搞混 ⚠️这是贡献者最容易踩的坑官方文档明确列为 Contributor Footguns 之一沉浸式 3D 办公室/office由 React Three Fiber 驱动核心在 src/features/retro-office/RetroOffice3D.tsx 与 src/features/retro-office/core/navigation.ts构建器/编辑器/office/builder由 Phaser 驱动核心在 src/features/office/phaser/OfficeBuilderScene.ts 与 src/features/office/components/OfficePhaserCanvas.tsx。两者相关但不是同一套运行时动手修改前先确认你改的是哪一边。建议的新手阅读顺序CODE_DOCUMENTATION.md 给出了回报最快的 10 文件阅读路径前 5 个尤其值得先看src/app/office/page.tsx — 办公室路由的组合根src/features/office/screens/OfficeScreen.tsx — 办公室场景主入口src/features/agents/state/gatewayRuntimeEventHandler.ts — 运行时事件分类与路由src/features/agents/state/runtimeEventCoordinatorWorkflow.ts — reducer/副作用桥接src/lib/office/eventTriggers.ts — 由运行时事件派生办公室动画触发四、核心运行时链路数据如何从网关流向 3D 场景理解主链路后很多状态不更新的问题就能迎刃而解浏览器连接 Studio 的同源 WebSocket/api/gateway/wsserver/gateway-proxy.js 将连接代理到上游 OpenClaw Gatewaysrc/lib/gateway/GatewayClient.ts 接收运行时事件gatewayRuntimeEventHandler.ts对事件分类、路由运行时工作流模块规划状态更新与效果命令历史同步模块拉取权威chat.history兜底智能体 UI 与 3D 办公室共同消费最终状态。关键约定 办公室中的运动是派生出来的而非直接推给场景事件 → 触发器状态 → 场景动画状态buildOfficeAnimationState()→RetroOffice3D渲染。这样 3D 场景永远不需要关心底层传输细节。五、测试体系从 lint 到 e2e 的四层防线Claw3D 采用四层质量保障提交 PR 前请全部跑通命令作用说明npm run lintESLint 静态检查存在少量既有警告属正常现象npm run typecheckTypeScript 类型检查tsc --noEmit不产出文件npm run testVitest 单元测试配置见 vitest.config.ts基于 jsdom 环境覆盖tests/unit/**/*.test.tsnpm run e2ePlaywright 端到端测试需先执行npx playwright install测试与代码的对应关系tests/unit/ 下有 150 个测试文件改哪块代码就近看哪块测试改办公室意图解析 → 参考 tests/unit/deskDirectives.test.ts改事件触发器 → 参考 tests/unit/officeEventTriggers.test.ts改网关运行时事件 → 参考 tests/unit/gatewayRuntimeEventHandler.chat.test.ts改 3D 寻路 → 参考 tests/unit/navigation.astarFallback.test.ts⚠️ 两个实用提醒Vitest 默认进入 watch 模式CI 或一次性运行请加--run参数若改动触及生成的 UX 审计产物提交前先用npm run cleanup:ux-artifacts清理。六、贡献流程从 Issue 到 PR 的完整路径第一步找对任务用 ROADMAP.md 寻找新手友好的起点任务Bug、功能请求与问题走 GitHub Issues 模板Issue 请包含复现步骤、操作系统与 Node 版本、相关日志或截图。第二步动手前的三件事确认 OpenClaw 网关可本地运行本仓库只读~/.openclaw配置不构建网关通读 CODE_DOCUMENTATION.md 的代码地图架构敏感的改动先读最近的单元测试再改实现。第三步提交 PR 的核心规范根据 CONTRIBUTING.md一个合格的 PR 应当✅聚焦且小一个 PR 只做一个任务✅ 附上你运行的测试lint/typecheck/test/e2e清单✅ 尽可能链接相关 Issue✅如改动了网关行为必须显式说明✅ 用户可见行为或架构变化时同步更新文档✅ 涉及 AI 辅助编码时简要说明 AI 参与的部分。新手避坑清单 Gateway 是运行时状态的唯一真相来源——不要为会话、任务或对话记录发明平行的本地状态Studio 设置只放本地偏好连接信息、工位分配、UI 偏好且按工作区/网关隔离新增房间或行为触发时优先扩展 src/lib/office/deskDirectives.ts 中的OfficeIntentSnapshot而不是到处加一次性正则本仓库不是 OpenClaw——不要在这里修改上游 OpenClaw 源码。七、总结你的贡献路线图 ️到这里你已经具备了完整的贡献者知识用5 步搭建本地环境用5 个核心目录读懂代码地图用4 层测试保证质量再按PR 规范提交代码。建议路线先跑通 Demo 模式熟悉界面 → 按阅读顺序啃完前 5 个核心文件 → 在 ROADMAP.md 挑一个小任务 → 修改代码 补就近单元测试 → 跑通lint、typecheck、test→ 提交一个聚焦的小 PR。欢迎加入 Claw3D和 AI 智能体一起在这个 3D 办公室里创造价值【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3D创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Claw3D开发者指南：代码地图、测试体系与贡献流程完整教程
Claw3D开发者指南代码地图、测试体系与贡献流程完整教程【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3DClaw3D 是一个为 AI 智能体打造的开源 3D 虚拟办公室基于 OpenClaw 网关构建让你能走进一个实时 3D 办公空间亲眼看到你的 AI 团队协作、开会、审查代码、执行任务。本指南是面向新手的 Claw3D 开发者指南带你快速看懂项目代码地图、跑通四层测试体系并按标准贡献流程提交你的第一个 PR。一、5 分钟认识 Claw3D我们贡献的是什么在动手改代码前先建立正确的心智模型官方文档 CODE_DOCUMENTATION.md 称之为 Repo Mental ModelOpenClaw负责智能体执行、会话、工具与运行时事件Claw3D负责可视化层、本地 Studio 设置、UI 工作流、3D 办公室渲染以及同源的 WebSocket/API 桥接原则涉及运行时权威状态如会话、任务、对话记录时以 Gateway 数据为准纯本地偏好则放进 Studio 设置。技术栈一览层面技术Web 应用Next.js 16 App Router React 19 TypeScript3D 办公室Three.js、React Three Fiber、Drei构建器/查看器Phaser单元测试Vitest端到端测试Playwright运行依赖Node.js 20 / npm 10无需数据库和 Docker新手必读的 5 份文档文档用途README.md安装与快速开始ARCHITECTURE.md系统边界与数据流CODE_DOCUMENTATION.md 实用代码地图、扩展点与上手顺序CONTRIBUTING.md本地工作流、测试与 PR 规范ROADMAP.md近期优先级适合找新手友好任务二、本地环境搭建5 步跑通开发服务器前置说明Claw3D 是纯 UI 仓库不会替你安装或构建 OpenClaw。若只想体验界面可直接用内置 Demo 网关见第 5 步。# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/cl/Claw3D claw3d cd claw3d # 2. 安装依赖 npm install # 3. 初始化环境变量 cp .env.example .env # 4. 启动开发服务器端口 3000 npm run dev然后打开http://localhost:3000在 Studio 中配置网关 URL 与 Token 即可。零依赖体验 Demo 模式不想装 OpenClaw运行npm run demo-gateway启动模拟网关含演示智能体、流式聊天与办公室在场状态再执行npm run dev在连接界面选择Demo backend指向ws://localhost:18789即可。三、代码地图速览5 个核心目录 3D 办公室架构理解目录结构是贡献代码的第一步。Claw3D 的目录划分非常清晰目录职责src/app/Next.js 路由入口与 API 路由尽量只做组合不堆业务逻辑src/features/垂直功能切片agents车队/聊天/审批、office办公室界面/构建器、retro-office3D 沉浸式运行时src/lib/跨功能共享的领域逻辑与适配器gateway、office、studio、skills、cron等server/自定义 Studio 服务器与 WebSocket 代理网关凭据保留在服务端tests/自动化测试unit回归主力 Playwright 端到端scripts/仓库工具脚本如claw3doctor诊断、开发服务器冒烟检查两套办公室技术栈别搞混 ⚠️这是贡献者最容易踩的坑官方文档明确列为 Contributor Footguns 之一沉浸式 3D 办公室/office由 React Three Fiber 驱动核心在 src/features/retro-office/RetroOffice3D.tsx 与 src/features/retro-office/core/navigation.ts构建器/编辑器/office/builder由 Phaser 驱动核心在 src/features/office/phaser/OfficeBuilderScene.ts 与 src/features/office/components/OfficePhaserCanvas.tsx。两者相关但不是同一套运行时动手修改前先确认你改的是哪一边。建议的新手阅读顺序CODE_DOCUMENTATION.md 给出了回报最快的 10 文件阅读路径前 5 个尤其值得先看src/app/office/page.tsx — 办公室路由的组合根src/features/office/screens/OfficeScreen.tsx — 办公室场景主入口src/features/agents/state/gatewayRuntimeEventHandler.ts — 运行时事件分类与路由src/features/agents/state/runtimeEventCoordinatorWorkflow.ts — reducer/副作用桥接src/lib/office/eventTriggers.ts — 由运行时事件派生办公室动画触发四、核心运行时链路数据如何从网关流向 3D 场景理解主链路后很多状态不更新的问题就能迎刃而解浏览器连接 Studio 的同源 WebSocket/api/gateway/wsserver/gateway-proxy.js 将连接代理到上游 OpenClaw Gatewaysrc/lib/gateway/GatewayClient.ts 接收运行时事件gatewayRuntimeEventHandler.ts对事件分类、路由运行时工作流模块规划状态更新与效果命令历史同步模块拉取权威chat.history兜底智能体 UI 与 3D 办公室共同消费最终状态。关键约定 办公室中的运动是派生出来的而非直接推给场景事件 → 触发器状态 → 场景动画状态buildOfficeAnimationState()→RetroOffice3D渲染。这样 3D 场景永远不需要关心底层传输细节。五、测试体系从 lint 到 e2e 的四层防线Claw3D 采用四层质量保障提交 PR 前请全部跑通命令作用说明npm run lintESLint 静态检查存在少量既有警告属正常现象npm run typecheckTypeScript 类型检查tsc --noEmit不产出文件npm run testVitest 单元测试配置见 vitest.config.ts基于 jsdom 环境覆盖tests/unit/**/*.test.tsnpm run e2ePlaywright 端到端测试需先执行npx playwright install测试与代码的对应关系tests/unit/ 下有 150 个测试文件改哪块代码就近看哪块测试改办公室意图解析 → 参考 tests/unit/deskDirectives.test.ts改事件触发器 → 参考 tests/unit/officeEventTriggers.test.ts改网关运行时事件 → 参考 tests/unit/gatewayRuntimeEventHandler.chat.test.ts改 3D 寻路 → 参考 tests/unit/navigation.astarFallback.test.ts⚠️ 两个实用提醒Vitest 默认进入 watch 模式CI 或一次性运行请加--run参数若改动触及生成的 UX 审计产物提交前先用npm run cleanup:ux-artifacts清理。六、贡献流程从 Issue 到 PR 的完整路径第一步找对任务用 ROADMAP.md 寻找新手友好的起点任务Bug、功能请求与问题走 GitHub Issues 模板Issue 请包含复现步骤、操作系统与 Node 版本、相关日志或截图。第二步动手前的三件事确认 OpenClaw 网关可本地运行本仓库只读~/.openclaw配置不构建网关通读 CODE_DOCUMENTATION.md 的代码地图架构敏感的改动先读最近的单元测试再改实现。第三步提交 PR 的核心规范根据 CONTRIBUTING.md一个合格的 PR 应当✅聚焦且小一个 PR 只做一个任务✅ 附上你运行的测试lint/typecheck/test/e2e清单✅ 尽可能链接相关 Issue✅如改动了网关行为必须显式说明✅ 用户可见行为或架构变化时同步更新文档✅ 涉及 AI 辅助编码时简要说明 AI 参与的部分。新手避坑清单 Gateway 是运行时状态的唯一真相来源——不要为会话、任务或对话记录发明平行的本地状态Studio 设置只放本地偏好连接信息、工位分配、UI 偏好且按工作区/网关隔离新增房间或行为触发时优先扩展 src/lib/office/deskDirectives.ts 中的OfficeIntentSnapshot而不是到处加一次性正则本仓库不是 OpenClaw——不要在这里修改上游 OpenClaw 源码。七、总结你的贡献路线图 ️到这里你已经具备了完整的贡献者知识用5 步搭建本地环境用5 个核心目录读懂代码地图用4 层测试保证质量再按PR 规范提交代码。建议路线先跑通 Demo 模式熟悉界面 → 按阅读顺序啃完前 5 个核心文件 → 在 ROADMAP.md 挑一个小任务 → 修改代码 补就近单元测试 → 跑通lint、typecheck、test→ 提交一个聚焦的小 PR。欢迎加入 Claw3D和 AI 智能体一起在这个 3D 办公室里创造价值【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3D创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考