参与 Agentshire 开源开发:环境搭建、测试体系与贡献流程完整指南

原创2026-10-12 17:21:061,677 阅读

参与 Agentshire 开源开发:环境搭建、测试体系与贡献流程完整指南

Agentshire 是一个把 AI Agent 可视化为低多边形 3D 小镇公民的 OpenClaw/QClaw 插件——每个 Agent 都是会走路、聊天、协作的 NPC。本文为参与 Agentshire 开源开发的新手开发者编写,一次讲清环境搭建步骤、Vitest 测试体系、代码规范与 PR 贡献流程,读完即可跑通项目并提交你的第一个 Pull Request。

🏘️ 30 秒认识 Agentshire:三层架构一图读懂

Agentshire 的核心卖点很直观:你在浏览器里拥有一个"夏尔小镇",AI 管家 Agent 拆解任务、召唤居民公民、看他们走进办公室写代码、完成任务放烟花庆祝。整个系统分为三层,理解了这个分层,你就知道该往哪里提代码:

层 目录 运行环境 职责
插件层 src/plugin/ Node.js Hook 翻译、WebSocket 服务(端口 55211)、11 个 AI 工具、编辑器 HTTP API
桥接层 src/bridge/ 浏览器 AgentEvent → GameEvent 翻译、阶段状态机、A* 寻路
前端层 town-frontend/src/ 浏览器 Three.js 3D 渲染、NPC 系统、UI、地图编辑器、音频

Agentshire 3D 小镇办公室场景:低多边形 AI 公民 NPC 协作工作的游戏化办公空间

架构细节请阅读开发者指南 AGENTS.md,其中包含完整目录结构、数据流图和"常见改动入口"速查表——找改动位置时先看它,能少走一半弯路。

🛠️ 环境搭建:3 步跑通本地开发

前置条件检查清单

  • Node.js >= 18(含 npm)
  • OpenClaw >= 2026.3.7(可选;仅前端开发可跳过,完整联调需要)

完整前置要求见 CONTRIBUTING.md。

第 1 步:克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/ag/Agentshire
cd Agentshire

# 安装插件层依赖
npm install

# 安装并构建 3D 前端
cd town-frontend && npm install && npm run build

仓库内置了 KayKit + Kenney 的低多边形模型资产,基础功能无需额外下载资源包即可运行。

第 2 步:启动前端热更新开发服务器

cd town-frontend && npm run dev

Vite 开发服务器(配置见 vite.config.ts)默认监听 55210 端口,支持四个独立入口页:

页面 路径 说明
小镇主界面 index.html 3D 小镇 + 聊天
地图编辑器 editor.html 可视化拖拽建城
公民工坊 citizen-editor.html 角色创建与配置
编辑器预览 preview.html 游戏级预览窗口

改完代码保存即热更新,这是前端开发的主力模式。

第 3 步:联调完整插件(可选)

如果你要开发插件层或桥接层,用 link 方式安装到 OpenClaw 再启动 Gateway:

cd Agentshire && openclaw plugins install --link .
openclaw gateway

浏览器会自动打开小镇页面;若未自动打开,手动访问 http://localhost:55210?ws=ws://localhost:55211 即可。

Agentshire 地图编辑器使用的低多边形城市建筑与道具贴图图集,由 KayKit City Bits 资产构成

🧪 测试体系:双配置 Vitest,如何跑对命令

Agentshire 采用 Vitest 作为唯一测试框架,根目录与前端各有一份独立配置,命令别跑混:

# ① 插件层 + 桥接层测试(根目录执行)
npm test

# ② 前端测试(town-frontend 下执行)
cd town-frontend && npx vitest run

两个配置文件差异很小但要注意:

  • 根配置 vitest.config.ts:只匹配 src/**/__tests__/**/*.test.ts
  • 前端配置 vite.config.ts:include 了 src/**/*.test.ts 以及 ../src/bridge/**/*.test.ts,即前端会连带跑一遍桥接层测试

测试文件在哪里?分布速查表

目前共有 17 个测试文件,覆盖寻路、时钟、事件分发等核心逻辑:

目录 覆盖模块 示例
src/bridge/tests/ 事件翻译、A* 寻路、活动流、公民生成 RouteManager.test.ts
src/plugin/tests/ Hook 翻译、编辑器服务 hook-translator.test.ts
town-frontend/src/game/tests/ 游戏时钟、事件分发、场景切换、模式管理 GameClock.test.ts
town-frontend/src/data/tests/ 数据层(公民配置转视图等) publishedToTownView.test.ts
town-frontend/src/npc/ NPC 活动日志 ActivityJournal.test.ts

测试风格很轻量:用 describe/it 按功能点分组(如 GameClock.test.ts 中"时间流逝 / 6 时段切换 / 夜间加速 / 暂停恢复"),外部依赖用 vi.mock() 隔离(如 RouteManager.test.ts mock 掉寻路图数据)。给新功能加测试时,照抄就近文件的写法即可。

📏 提交 PR 前必读:代码规范与硬约束

项目用 TypeScript 且 strict: true(见 tsconfig.json、town-frontend/tsconfig.json),缩进统一 2 空格(.editorconfig 已固化)。以下是几条容易踩坑的架构级硬约束,摘自 AGENTS.md:

  1. 桥接层只发高层意图事件(如 workflow_*),不要发微操作,动画编排留在前端 workflow/
  2. NPC 动画一律走 transitionTo(state),禁止直接调 playAnim()
  3. 工位延迟释放——等前端 NPC 物理离场、回调 workstation_released 后才释放
  4. 前端用户可见文案必须走 i18n(src/i18n/),UI 颜色必须用品牌色板,规则详见 town-frontend/AGENTS.md

🚀 贡献流程:从建分支到合并 PR

完整贡献指南在 CONTRIBUTING.md,标准六步:

  1. Fork 仓库
  2. 建分支:git checkout -b feature/my-feature
  3. 改代码,如涉及行为逻辑,同步补充测试
  4. 跑测试:npm test 与前端测试都要绿
  5. 提交:commit message 说明改了什么、为什么
  6. 对 main 分支发起 Pull Request

填好 PR 模板,让评审更快通过

仓库内置 PR 模板 .github/PULL_REQUEST_TEMPLATE.md,会引导你勾选改动区域(Town / Chat / Workflow / Citizen Workshop / Town Editor / Mini-game / Plugin / Docs)并写清测试步骤——视觉类改动请附截图或录屏。

报告 Bug 也有模板

发现 bug 走 Issue 的 bug_report.yml 模板:OpenClaw 版本与 Node 版本必填,需附复现步骤;视觉类 bug 强烈建议带截图。功能建议用 feature_request.yml。

不只是写代码:欢迎这些方向的贡献

  • 游戏设计:游戏循环、成长系统、小镇节奏
  • 游戏美术:建筑、角色、道具、动画、UI、氛围(低多边形贴图图集风格参考下图)
  • 代码:Three.js 前端、Node.js 后端、编辑器集成、小游戏、协议
  • AI 工程:Soul 模式、NPC 大脑、长期记忆、多 Agent 编排
  • 内容:写一个 NPC 灵魂文件即可上车——复制 town-souls/SOUL_tpl.md 模板,定义名字、性格、专长与说话风格,放入 town-souls/ 就是新角色

Agentshire 公民工坊与地图编辑器使用的低多边形家具道具贴图图集,风格与小镇整体低多边形美术一致

✅ 上手路线图:新手第一周怎么安排

阶段 目标 关键命令 / 文件
第 1 天 环境跑通,小镇在浏览器里动起来 npm run dev,打开 index.html
第 2 天 通读 AGENTS.md,定位一个想改的模块 "Common Change Guide" 速查表
第 3–4 天 做一个小改动(如 i18n 文案、soul 文件) 跑 npm test + 前端测试
第 5 天 提交第一个 PR,附测试步骤 PR 模板勾选区域
持续 关注 ROADMAP.md 挑任务,看 CHANGELOG.md 了解版本演进 —

Agentshire 的版本节奏很快(当前版本 2026.4.15,MIT 协议),从"QClaw 兼容"到"双语文案"再到"话题讨论",Roadmap 上每个条目都可能成为你的第一张 Issue。小镇已经建好,就差一个新居民——现在就可以 git clone 开始动手了。

登录后查看全文
Agentshire