参与 Agentshire 开源开发:环境搭建、测试体系与贡献流程完整指南
参与 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、地图编辑器、音频 |
架构细节请阅读开发者指南 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 即可。
🧪 测试体系:双配置 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:
- 桥接层只发高层意图事件(如
workflow_*),不要发微操作,动画编排留在前端workflow/ - NPC 动画一律走
transitionTo(state),禁止直接调playAnim() - 工位延迟释放——等前端 NPC 物理离场、回调
workstation_released后才释放 - 前端用户可见文案必须走 i18n(
src/i18n/),UI 颜色必须用品牌色板,规则详见 town-frontend/AGENTS.md
🚀 贡献流程:从建分支到合并 PR
完整贡献指南在 CONTRIBUTING.md,标准六步:
- Fork 仓库
- 建分支:
git checkout -b feature/my-feature - 改代码,如涉及行为逻辑,同步补充测试
- 跑测试:
npm test与前端测试都要绿 - 提交:commit message 说明改了什么、为什么
- 对
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/就是新角色
✅ 上手路线图:新手第一周怎么安排
| 阶段 | 目标 | 关键命令 / 文件 |
|---|---|---|
| 第 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 开始动手了。


