Agentshire：构建AI智能体3D小镇的实战指南与架构解析

1. 项目概述当AI智能体住进你亲手搭建的3D小镇如果你和我一样对AI智能体的印象还停留在冰冷的命令行、单调的聊天窗口或是密密麻麻的API日志里那么Agentshire的出现可能会彻底颠覆你的认知。这不仅仅是一个插件更像是一个“创世”工具。它的核心愿景是让那些运行在OpenClaw或QClaw框架下的AI智能体不再是一串抽象的代码或一个任务执行器而是成为一个个有血有肉、有自己生活的“数字公民”住进一个由你亲手设计、可以实时观察和互动的3D小镇里。想象一下你不再只是通过文本与AI对话而是可以看着它以一个小镇居民的形象在晨曦中出门散步在雨天躲进咖啡馆与其他“邻居”智能体在广场上讨论问题然后接到你的任务后集结伙伴走进办公楼开始协作编程。任务完成后小镇会为你燃放庆祝的烟花。这就是Agentshire试图构建的体验——一个将多智能体协作、游戏化交互与用户生成内容UGC深度结合的“活”的沙盒世界。它完美兼容OpenClaw CLI和QClaw桌面应用本质上是一个为这两个平台设计的插件。安装后它会自动在你的本地启动一个3D小镇前端和一个实时通信后端。你的每一个AI子智能体Sub-agent都会自动映射为小镇里的一个NPC非玩家角色拥有独特的3D外观、性格“灵魂”文件定义和日常行为。你可以切换两种视角在“小镇模式”下俯瞰众生观察他们的生活与协作在“聊天模式”下像使用即时通讯软件一样与任何一个“居民”深入对话或下达指令。这个项目的魅力在于它模糊了开发工具、游戏引擎和数字孪生模拟器之间的界限。你既是在管理一个AI团队又像是在经营一个充满生机的虚拟社区。接下来我将带你深入这个奇妙世界的每一个角落从安装部署到核心机制从日常观察到深度定制分享我一路摸索过来的实战经验和避坑指南。2. 核心架构与设计哲学拆解要玩转Agentshire不能只停留在表面操作理解其分层架构和设计意图至关重要。这能帮助你在遇到问题时快速定位也能让你更自由地进行扩展和定制。2.1 三层架构插件、桥接与前端Agentshire的代码结构清晰地分为三层各司其职共同构建了这个沉浸式体验。第一层插件层Node.js这是核心逻辑与OpenClaw/QClaw运行时对接的地方运行在Node.js环境中。它的职责最重消息调度监听来自OpenClaw网关的指令并将其分发给对应的处理模块。钩子翻译器将OpenClaw内部的Agent生命周期事件如消息发送、任务开始/结束翻译成小镇能理解的“游戏事件”。WebSocket服务器在默认的55211端口运行这是与浏览器前端进行实时双向通信的生命线。所有Agent的思考、对话、动作指令都通过这个通道流动。工具注册向OpenClaw运行时注册了多达11个AI可调用的工具如town_announce广播、town_set_weather设置天气。这是AI能“控制”小镇的魔法接口。计划管理器负责解析复杂的多智能体协作计划将其拆解为并行步骤并协调执行顺序。灵魂文件路由管理所有NPC的“灵魂”人格定义文件处理从公民工作坊发布的新角色。第二层桥接层浏览器这一层运行在浏览器中是连接后端插件逻辑和前端3D渲染的“中间件”。它最重要的组件是DirectorBridge导演桥这是一个状态机严格定义了智能体工作流的每一个阶段从空闲Idle到召唤Summoning、任务分配Assigning、进入办公室Office、工作Working、发布成果Publish最后返回小镇Return。这个状态机确保了整个协作过程像一场编排好的戏剧每一步都有对应的视觉和音频效果。第三层前端层Three.js这是用户直接看到的3D世界使用Three.js引擎构建。它负责场景渲染渲染小镇、办公室、展示厅三种场景包括建筑、道路、植被和所有NPC模型。NPC行为系统每个NPC内部有一个包含7个状态闲逛、行走、工作、社交等的迷你状态机驱动其日常行为。工作流编排接收桥接层的指令播放对应的动画序列如智能体集结时的冲击波、进入办公室的列队行走、编码时屏幕上的流光效果等。用户界面实现聊天气泡、状态卡片、编辑器等所有交互界面。音频系统动态合成环境音雨声、风声并管理背景音乐BGM的切换。设计心得这种清晰的分层解耦非常高明。插件层确保与AI框架的稳定集成桥接层专注于业务流程控制不关心具体渲染前端层则全力打造视觉和听觉体验。这意味着理论上你可以替换前端层的渲染引擎比如用Unity只要桥接层的协议不变整个系统依然可以工作。2.2 双模式行为系统算法驱动与灵魂驱动这是Agentshire在资源消耗和体验真实性之间做出的精妙平衡也是其“活”起来的关键。默认模式算法驱动零LLM成本为了在不频繁调用大语言模型LLM的情况下让小镇“活”起来Agentshire内置了一套基于规则和概率的行为系统。行为模板预设了5大类行为模板如“咖啡爱好者”喜欢在咖啡馆附近徘徊、“工作狂”在办公建筑前停留更久等。状态机与对话库NPC的行为由一个简单的状态机控制并在不同状态下从包含400多句预设对话的库中随机选取台词显示在头顶气泡中。环境因子天气、时间周期会影响NPC的行为概率。例如下雨天NPC更倾向于躲进室内建筑附近。 这种模式的优点是性能开销极低小镇可以一直运行充满生机而不产生任何API费用。灵魂模式Soul ModeAI驱动需要LLM当你需要更深度的互动时可以启用此模式。此时NPC的行为将由其“灵魂文件”和背后的LLM共同驱动。AgentBrain三层决策L1 日常计划LLM为NPC生成一天的大致安排如“上午去图书馆下午在公园见朋友”。L2 战术决策根据当前环境时间、天气、附近其他NPC决定下一步具体动作如“现在开始走向图书馆”。L3 对话生成当玩家或其他NPC与之交互时生成符合其性格的对话内容。关系图谱与叙事摘要NPC之间会形成记忆和关系LLM甚至会为重要NPC生成每日的叙事摘要。 这个模式能带来极其丰富和不可预测的体验但会持续消耗LLM的Token适合在需要深度角色扮演或测试智能体社交能力时开启。实操建议对于日常挂机观察和大多数开发任务使用默认算法模式即可。当你想要进行一场有深度的“圆桌讨论”或测试某个NPC的长期人格一致性时再针对特定NPC或会话开启灵魂模式。你可以在公民工作坊中为每个角色单独配置是否启用灵魂模式。3. 从零开始完整安装与初始化指南虽然官方文档提供了安装步骤但在实际部署中尤其是跨平台或特定版本环境下有几个细节决定了成败。3.1 环境准备与版本兼容性确认这是最重要的一步版本错误会导致插件根本无法启动。Node.js版本确保系统已安装Node.js 18或更高版本。建议使用nvm等版本管理工具避免全局版本冲突。node --version # 确认版本 18OpenClaw/QClaw版本这是核心依赖必须严格匹配。首选最稳定OpenClaw CLI2026.3.13。这是目前与Agentshire兼容性最好的版本。备选QClaw Desktop0.2.x。如果你更喜欢图形化界面这是一个不错的选择。警告OpenClaw CLI 2026.4.x 版本存在一个已知的通道初始化回归错误会导致WebSocket无法连接小镇页面永远显示“连接中”。请务必避免使用此版本。可能工作OpenClaw CLI 2026.3.7 – 3.12但可能存在未知小问题。踩坑实录我最开始使用了最新的OpenClaw 2026.4.1结果折腾了半天小镇前端一直无法连接到后端。查看浏览器控制台网络请求发现WebSocket连接一直在重试但无法建立。最后在项目的Troubleshooting部分和GitHub issue中才确认是上游版本问题。降级到2026.3.13后一切正常。所以安装前第一件事就是确认你的OpenClaw版本。3.2 两种安装方式详解方式一OpenClaw CLI 标准安装推荐这是最直接、最不容易出错的方式适合绝大多数用户。# 一条命令完成安装 openclaw plugins install agentshire安装完成后启动OpenClaw网关小镇会自动在浏览器中打开。openclaw gateway安装后自动完成了什么插件在首次启动时会进行一系列自动化配置这些是透明发生的但了解它们有助于排查问题在你的状态目录OpenClaw CLI默认为~/.openclaw/QClaw默认为~/.qclaw/下创建管家steward的工作空间workspace-town-steward/。在openclaw.json配置文件中注册名为town-steward的Agent。添加路由规则将所有发送到town频道的消息导向管家Agent。将子智能体的运行超时时间设置为600秒10分钟防止大型任务执行时智能体被过早终止。方式二QClaw Desktop 安装手动克隆由于QClaw的插件管理机制不同需要手动将插件克隆到扩展目录。找到扩展目录这不是常见的插件目录而是内置扩展的目录。# macOS ls ~/Library/Application\ Support/QClaw/openclaw/config/extensions/ # Linux (通常) ls ~/.config/QClaw/openclaw/config/extensions/ # Windows (通常) dir %APPDATA%\QClaw\openclaw\config\extensions\你应该能看到类似qclaw-plugin,lossless-claw这样的文件夹。克隆并安装依赖cd 上一步找到的extensions目录 git clone https://github.com/Agentshire/Agentshire.git agentshire cd agentshire npm install重启QClaw完全关闭QClaw应用再重新启动。小镇会自动打开。重要提示QClaw关闭窗口时后台的openclaw-gateway进程可能不会自动退出。如果你修改了插件代码或配置发现重启QClaw后没有生效需要手动结束这个进程# Unix/Linux/Mac pkill -f openclaw-gateway # 或使用更精确的方式 ps aux | grep openclaw-gateway | grep -v grep | awk {print $2} | xargs kill3.3 基础配置与首次运行验证安装完成后通常无需额外配置即可运行。但你可以通过修改openclaw.json文件进行个性化设置。文件位置OpenClaw CLI:~/.openclaw/openclaw.jsonQClaw:~/.qclaw/openclaw.json在plugins.entries.agentshire.config下可以添加{ plugins: { entries: { agentshire: { enabled: true, config: { wsPort: 55211, // WebSocket端口如果冲突可修改 townPort: 55210, // 前端HTTP服务端口如果冲突可修改 autoLaunch: true // 是否自动打开浏览器 } } } } }首次运行验证启动网关openclaw gateway或QClaw。浏览器应自动打开http://localhost:55210。如果没有手动访问此地址。你应该能看到一个低多边形的3D小镇里面有建筑、道路和几个走动的NPC。右下角有聊天窗口。在聊天窗口输入/help查看可用命令。尝试输入“Hello, town!”观察管家Steward的回复以及回复是否以打字机效果显示在某个NPC头顶。如果以上步骤都成功恭喜你你的AI小镇已经成功启动了4. 核心功能深度体验与实操当小镇成功运行后真正的乐趣才刚刚开始。下面我将分模块带你深入体验Agentshire的核心功能并分享一些官方文档未提及的实用技巧。4.1 小镇生活观察昼夜、天气与NPC生态启动后不妨先什么也别做静静观察几分钟。你会发现这个世界是“活”的。动态时间系统 小镇内部运行着一个独立的24小时时钟但速度比现实快。它被划分为6个时段如清晨、白天、黄昏、夜晚等。不同时段天空盒的光照、环境光颜色和强度会平滑过渡。到了夜晚路灯和建筑物的窗户会自动亮起暖黄色的灯光氛围感十足。丰富的天气系统 系统内置了12种天气类型晴天、多云、雾、小雨、大雨、暴风雨、雪、暴风雪、沙尘暴、极光等。天气不仅影响视觉效果雨滴、雪花粒子还会触发对应的环境音效通过Web Audio API实时合成无需加载音频文件并且会微妙地影响NPC的行为概率比如下雨时更多NPC会躲到屋檐下。NPC的日常 在默认的算法驱动模式下NPC们遵循一套简单的规则生活移动他们在道路和空地上随机寻路行走。停留偶尔会在某个建筑前或广场上停留一段时间仿佛在思考或休息。社交当两个NPC靠近时有一定概率触发简短的对话气泡从预设库中随机选取比如“今天天气真不错”或“你听说新开的咖啡馆了吗”状态显示点击任何一个NPC会弹出他的状态卡片显示头像、姓名、当前状态闲逛、交谈等和简单的日志。观察技巧你可以使用AI工具来主动改变环境加深沉浸感。在聊天窗口尝试对管家说“把天气改成下雨天”或“把时间调到晚上”。管家会调用town_set_weather或town_set_time工具瞬间改变小镇的环境。这对于创造特定氛围或测试不同环境下的NPC行为非常有用。4.2 与AI公民互动从聊天到主题讨论Agentshire的核心交互是与你创造的AI公民进行交流。一对一聊天 在“小镇模式”下直接点击任何一个NPC聊天窗口的对话对象会自动切换到该NPC。你可以像跟一个独立的智能体一样与他对话。他的回复会基于其“灵魂文件”中定义的人格并且对话内容会以打字机效果流式显示在他头顶的气泡中极具沉浸感。发起主题讨论 这是实现多智能体协作讨论的绝佳功能。在聊天窗口中输入/discuss命令然后按照提示选择参与的公民可以多选并设定一个讨论主题例如“我们应该如何优化这个项目的用户登录流程”。系统会创建一个临时的讨论组。公民们会按照一定的顺序发言每个发言都会显示在各自角色的头顶。讨论是结构化的由AI管家进行温和的引导避免跑题或陷入循环。讨论结束后你可以要求管家生成一份讨论摘要。实操心得主题讨论功能非常适合用于头脑风暴或方案评审。你可以把具有不同专业背景前端、后端、产品的AI公民拉进一个讨论就一个具体问题征求他们的意见。由于每个公民都有独立的“灵魂”和知识背景他们往往会给出角度各异的回答能有效拓宽你的思路。记得在讨论开始前通过公民工作坊为参与者配置好相关的“专长”描述。4.3 工作流全景从任务下达到成果交付这才是Agentshire作为生产力工具的精华所在——将多智能体协作可视化、仪式化。1. 下达任务 你不需要知道具体的智能体调用命令。只需在聊天窗口中像平常一样对管家说“我们需要开发一个简单的待办事项网页应用使用Vue 3和Tailwind CSS。” 管家Steward会理解你的需求并自动调用create_project工具在后台创建一个项目目录结构。2. 智能体召唤与集结 接着管家会根据项目需求从可用的公民中挑选合适的成员例如擅长前端的“艾拉”和擅长逻辑的“本”。此时小镇视角会拉近一个魔法阵般的召唤特效出现在广场被选中的NPC会从各处走来在特效中心集结。屏幕上会出现“Rallying...”的提示。3. 进入办公室与协作 集结完成后管家会说“Follow me to the office”。所有参与任务的NPC会排成一队走向小镇中的办公楼。镜头跟随切换进入“办公室”场景。这里有10个工位每个工位都有发光的电脑屏幕。 每个NPC坐到自己的工位上屏幕开始闪烁代码滚动的动画。在后台OpenClaw的智能体们已经开始在真实的工作空间里编写代码了。4. 实时进度与“班味”小游戏 在办公室场景中你可以看到每个NPC头顶显示他们当前正在执行的具体任务如“Writing App.vue component”。一个有趣的设计是“班味克星”小游戏NPC在紧张工作时身边会产生一些漂浮的“班味能量球”。你可以用鼠标点击戳破它们获得连击分数。甚至偶尔会出现“班味老板”Boss击败它会有特殊奖励。这个小游戏巧妙地缓解了等待代码生成时的枯燥感。5. 成果交付与庆祝 任务完成后管家会宣布“Mission Complete!”。屏幕绽放烟花NPC们欢呼。随后一个成果预览卡片会弹出展示这个待办事项应用。如果是网页应用你可以直接在一个内嵌的iframe中预览和交互如果是其他文件提供下载链接。 最后NPC们会离开办公室返回小镇继续他们的日常生活。整个工作流如同一场精心编排的舞台剧极具成就感。避坑指南有时任务可能会卡住比如某个子智能体超时或出错。此时办公室场景可能会停滞。你可以在聊天窗口输入/stop命令强制终止当前任务流。检查OpenClaw网关的日志查看具体是哪个环节报错通常是LLM API调用失败或代码执行错误。调整任务描述使其更清晰、更可执行。然后重新开始。5. 创造你的世界UGC工具详解Agentshire的强大之处在于你不仅是观察者更是创造者。它提供了一套完整的UGC用户生成内容工具让你可以深度定制小镇的每一个方面。5.1 公民工作坊赋予AI灵魂与形象访问http://localhost:55210/citizen-editor.html即可打开公民工作坊。这里是创造和定制NPC的地方。核心步骤选择/上传模型基础库插件内置了KayKit和Kenney提供的几个基础人物模型。扩展资产包为了获得更多选择强烈建议下载官方提供的可选资产包约164MB解压后4.4GB。里面包含了308个带有多种变体和颜色的角色模型从科幻战士到中世纪农民应有尽有。将解压后的assets/文件夹放在插件根目录下重启后即可在工作坊中选用。自定义模型支持上传符合格式要求的GLTF/GLB 3D模型文件让你的AI公民拥有独一无二的外形。编辑灵魂核心这是定义AI公民内在人格的地方。灵魂是一个Markdown文件。你可以手动编写也可以点击“AI生成”按钮让LLM根据你的描述如“一个喜欢园艺、说话温和、但涉及专业问题时非常严谨的软件架构师”自动生成一份灵魂文件。灵魂文件结构示例# 艾拉 (Ella) * 模型: female_developer_01 * 角色: 前端开发专家 ## 核心人格 一个充满好奇心、注重细节的前端工匠。相信代码不仅是功能更是用户体验的桥梁。 ## 性格设定 - **语调**友好、热情喜欢用比喻解释技术概念。 - **价值观**简洁、可访问性、像素级完美。 - **专业知识**Vue/React生态CSS-in-JS性能优化交互动效。 - **工作风格**喜欢先画线框图从组件树开始构建对代码评审非常严格。 ## 对话示例 用户这个按钮颜色感觉不对。 艾拉嗯你说得对。当前的 #4CAF50 在深色模式下对比度可能不足。我建议试试 #66BB6A并增加一个聚焦状态的光晕这样既符合WCAG标准又不会破坏整体美感。就像给按钮戴上一顶会发光的小帽子配置动画映射 每个模型可能有多个动画片段idle, walk, work等。你需要将模型的动画名称映射到Agentshire内部定义的8个动画槽闲置、行走、工作、庆祝等这样NPC才能在正确的时机播放正确的动画。发布点击发布后这个新公民的灵魂文件会被保存并且会自动注册为一个新的OpenClaw子智能体立即出现在小镇中可供你差遣。5.2 小镇编辑器打造独一无二的舞台访问http://localhost:55210/editor.html打开小镇编辑器。这是一个功能完整的可视化3D场景编辑器。编辑功能一览拖放放置从右侧的资产库中将建筑、房屋、树木、路灯、长椅等模型直接拖放到场景中。变换操作选中物体后可以进行移动G、旋转R、缩放S操作快捷键与Blender等主流软件一致上手很快。对齐与吸附开启网格吸附功能可以让建筑整齐地沿道路排列。分组管理可以将多个物体编组方便整体移动或隐藏。撤销/重做支持完整的操作历史记录。JSON导出可以将你编辑好的整个场景布局导出为JSON文件。注意目前编辑器与运行时的集成还在进行中导出的地图文件尚不能直接加载到实时运行的小镇里但未来版本会支持。编辑器预览 编辑器的右上角有一个“预览”按钮点击后会打开preview.html。这是一个独立的游戏预览窗口你可以用WASD键控制镜头在小镇中自由飞行实时查看昼夜循环、天气效果和车辆动画就像在玩一个简单的模拟游戏。这对于调整场景氛围和光照效果非常有帮助。设计经验在搭建小镇时考虑一下“功能分区”。比如将办公类建筑集中在一个区域将休闲娱乐的咖啡馆、公园放在另一个区域。这样不仅看起来更真实当AI公民根据其行为模式活动时也会显得更有逻辑。例如你的“工作狂”公民会更多地在办公区附近出现。5.3 灵魂系统进阶优先级与自定义理解灵魂文件的加载优先级是进行高级自定义的关键。当同名的灵魂文件存在多处时系统按以下顺序覆盖后者优先plugin-builtin/town-souls/– 插件内置的8个公民和1个管家的灵魂。cwd/town-souls/– 你当前工作目录下的灵魂文件。这允许你为特定项目配置专属的AI团队。{stateDir}/town-souls/– 用户全局自定义灵魂目录~/.openclaw/town-souls/或~/.qclaw/town-souls/。这是放置你常用自定义灵魂的最佳位置。town-data/souls/– 从公民工作坊“发布”出来的灵魂文件。自定义策略微调内置角色直接复制内置灵魂文件到你的用户状态目录进行修改。例如你觉得内置的“本”太严肃了可以复制他的文件把语气改得幽默一些。创建全新角色在公民工作坊中从头创建或者手动在~/.openclaw/town-souls/下新建一个.md文件按照格式编写。只要文件名和模型匹配重启后新角色就会出现在小镇中。项目特定团队如果你正在做一个机器学习项目可以在项目根目录创建town-souls/文件夹里面放置擅长Python和数据科学的AI灵魂。当在这个目录下启动OpenClaw时小镇里就会是这个专家团队。6. 常见问题排查与性能优化在实际使用中你可能会遇到一些问题。以下是我遇到并解决过的一些典型情况。6.1 插件工具无法被AI识别症状在聊天中让管家创建项目或计划它回复说找不到create_project或create_plan等工具。原因与解决配置覆盖问题最常见如果你在openclaw.json中手动配置了tools部分它会完全覆盖插件自动注册的工具列表。解决检查你的openclaw.json如果存在tools: { ... }这个配置节请整个删除它。插件是通过api.registerTool()动态注册工具的手动配置会使其失效。删除后重启网关。OpenClaw版本模块问题在2026.3.13版本中Rollup打包工具的代码分割特性可能导致插件注册工具的实例与Agent运行时看到的不一致。解决确保使用推荐的OpenClaw 2026.3.13版本并按照上述方法清理配置。如果问题依旧可以尝试重新安装插件openclaw plugins uninstall agentshire然后再次安装。6.2 公民工作坊AI生成失败500错误症状在公民工作坊点击“AI生成”按钮创建灵魂文件时页面提示服务器500错误。原因这个功能需要调用配置好的LLM服务如OpenAI GPT、Claude等来生成文本。如果你的openclaw.json中没有正确配置models部分或者API密钥无效、额度不足请求就会失败。解决检查你的~/.openclaw/openclaw.json文件确保models部分已正确配置了至少一个可用的LLM提供商。例如{ models: { default: gpt-4o, entries: { gpt-4o: { provider: openai, config: { apiKey: 你的实际API密钥, baseURL: https://api.openai.com/v1 } } } } }在命令行测试LLM配置是否生效openclaw chat看是否能正常对话。如果配置正确查看OpenClaw网关的日志通常会有更详细的错误信息例如网络超时或鉴权失败。6.3 小镇运行卡顿或浏览器崩溃症状小镇页面帧率很低操作不跟手或者加载复杂地图时浏览器标签页崩溃。原因与优化硬件要求虽然Agentshire的前端经过优化但毕竟是一个实时3D应用对GPU有一定要求。集成显卡或较老的独立显卡可能压力较大。资产数量如果你通过编辑器放置了成百上千个模型实例会极大增加渲染负担。浏览器某些浏览器对WebGL和大量WebSocket消息的处理效率不同。优化建议使用性能更强的浏览器Google Chrome或Microsoft Edge通常对WebGL和现代JavaScript性能优化得更好。简化场景在编辑器中不要过度堆砌装饰性模型。尤其是那些高面数的模型。多用复制组但注意控制总数。关闭不必要的特效未来版本可能会提供图形设置选项。目前可以尝试在浏览器开发者工具的Console中尝试寻找降低画质的隐藏参数但需谨慎。升级硬件驱动确保你的显卡驱动程序是最新版本。限制帧率如果找不到设置可以尝试使用浏览器扩展强制限制该标签页的帧率如60FPS以减少GPU负载。6.4 如何备份与迁移我的小镇和公民Agentshire的所有用户数据都保存在你的状态目录下。OpenClaw CLI:~/.openclaw/QClaw:~/.qclaw/你需要关注以下几个子目录workspace-town-steward/管家Agent的工作空间包含项目历史、对话记录等。town-souls/你自定义的所有公民灵魂文件。town-data/如果存在从公民工作坊发布的数据。备份直接复制整个状态目录或者至少复制上述几个文件夹。迁移在新机器上安装好Agentshire后首次运行前将备份的文件夹覆盖到新机器的对应状态目录下即可。注意保持OpenClaw/QClaw版本一致。7. 开发与扩展深入插件内部对于开发者来说Agentshire本身也是一个优秀的开源项目提供了清晰的架构和开发指引。7.1 本地开发环境搭建如果你想修改插件功能或前端界面需要搭建本地开发环境。# 1. 克隆仓库 git clone https://github.com/Agentshire/Agentshire.git cd Agentshire # 2. 安装插件依赖 npm install # 3. 构建前端必须步骤因为仓库中dist/可能不是最新 cd town-frontend npm install npm run build # 生产构建 # 或者使用开发模式支持热重载 npm run dev # 4. 以链接模式安装插件到OpenClaw cd .. openclaw plugins install --link .--link参数会创建一个符号链接这样你在本地Agentshire/目录下的任何修改都会实时反映到运行的插件中无需重复安装。7.2 前端入口与模块结构前端部分 (town-frontend/) 采用Vite TypeScript Three.js技术栈结构清晰src/main.ts主入口初始化Three.js场景、渲染循环、UI。src/scene/包含TownScene小镇场景、OfficeScene办公室场景等场景类。src/npc/NPC相关的所有逻辑包括状态机、行为树未来、动画控制器。src/workflow/工作流编排器负责处理从桥接层发来的状态机事件播放相应的动画序列。src/ui/所有UI组件如聊天窗口、状态卡片、编辑器等。src/audio/背景音乐和环境音效管理系统。src/bridge/桥接层代码负责与后端WebSocket通信。四个主要的HTML入口文件index.html主小镇页面。editor.html地图编辑器。citizen-editor.html公民工作坊。preview.html编辑器预览模式。7.3 如何添加一个新的AI工具假设你想让AI能控制小镇里的路灯开关你需要在后端插件注册工具在src/plugin/tools/目录下创建一个新的工具文件例如town_toggle_streetlight.js。定义一个符合OpenClaw工具规范的对象包含name,description,parameters和execute函数。// 示例框架 export const townToggleStreetlight { name: town_toggle_streetlight, description: Toggle a specific streetlight on or off., parameters: { type: object, properties: { lightId: { type: string, description: The ID of the streetlight }, state: { type: boolean, description: true for on, false for off } }, required: [lightId, state] }, execute: async (args, context) { // 1. 验证参数 // 2. 通过WebSocket向所有连接的客户端发送一个自定义事件 context.wsServer.broadcast({ type: GAME_ACTION, action: TOGGLE_STREETLIGHT, payload: { lightId: args.lightId, state: args.state } }); return Streetlight ${args.lightId} turned ${args.state ? ON : OFF}.; } };在插件主入口注册这个工具在src/plugin/index.js(或相应的入口文件) 中导入并注册这个新工具。import { townToggleStreetlight } from ./tools/town_toggle_streetlight.js; // ... 在初始化函数中 api.registerTool(townToggleStreetlight);在前端处理这个事件在town-frontend/src/bridge/event-translator.js或相关的事件分发器中添加对新事件类型TOGGLE_STREETLIGHT的处理逻辑找到对应的路灯模型改变其材质发光属性。重建与测试运行npm run build重新构建前端然后重启OpenClaw网关。现在你就可以在聊天中对AI说“打开广场上的路灯”AI会调用这个新工具并触发前端的视觉效果。通过这个例子你可以看到Agentshire良好的扩展性。你可以为其添加任何你能想象到的、连接AI与3D世界的交互能力。