{"_id":"agentshire","_rev":"5-c47dc571e912e28afde603420dca3690","name":"agentshire","dist-tags":{"latest":"2026.4.15","test":"1.0.0"},"versions":{"2026.4.12":{"name":"agentshire","version":"2026.4.12","keywords":["openclaw","ai-agents","multi-agent","generative-agents","npc","threejs","3d","simulation","game","visualization","low-poly","typescript","open-source","level-editor","character-creator"],"author":{"name":"Agentshire Contributors"},"license":"MIT","_id":"agentshire@2026.4.12","maintainers":[{"name":"chnyujin","email":"chnyujin@gmail.com"}],"homepage":"https://github.com/Agentshire/Agentshire#readme","bugs":{"url":"https://github.com/Agentshire/Agentshire/issues"},"dist":{"shasum":"008cf75d7f524c968c6002c9f31101b71fb7e59d","tarball":"https://registry.npmjs.org/agentshire/-/agentshire-2026.4.12.tgz","fileCount":406,"integrity":"sha512-krh4c7w8/mqvdX59Wa9dBgCumLlzvfhVA/mG68OR9fOUucdWh77xMeaLjxtcLth/UFxqzkbzzQvAzr0RgE8ddQ==","signatures":[{"sig":"MEUCIB6Kd/hf69XRIS4MKgJ9ox1xS6BYMqmoQKEjzDe04005AiEAwOF/HKKeIMRAmo/HnE4Vatq71jhu4+qxE1HFDjxQsqo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28055151},"main":"./index.ts","type":"module","exports":{".":"./index.ts"},"gitHead":"c21c2d40b9042c05179249e12ec628184b4a31d5","scripts":{"test":"vitest run","build":"npm run build:town","dev:town":"cd town-frontend && npm run dev","build:town":"cd town-frontend && npm install && npm run build","postinstall":"echo '' && echo '  🏘️  Agentshire installed successfully!' && echo '' && echo '  Next: (re)start the OpenClaw Gateway to activate the plugin.' && echo '        The town will open automatically in your browser.' && echo ''"},"_npmUser":{"name":"chnyujin","email":"chnyujin@gmail.com"},"openclaw":{"channel":{"id":"agentshire","blurb":"Visualize your AI agents as NPCs in an interactive 3D low-poly town. Watch them work, chat, and collaborate in real-time.","label":"Agentshire","order":100,"docsPath":"/channels/agentshire","docsLabel":"agentshire","selectionLabel":"Agentshire (3D Visualization)"},"install":{"npmSpec":"agentshire","localPath":"extensions/agentshire","defaultChoice":"npm"},"extensions":["./index.ts"]},"repository":{"url":"git+https://github.com/Agentshire/Agentshire.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw/QClaw plugin for building a living 3D town with social NPCs, a map editor, and a character workshop.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.16.0","jsonrepair":"^3.13.3","@gltf-transform/core":"^4.3.0","@gltf-transform/functions":"^4.3.0","@gltf-transform/extensions":"^4.3.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.0","@types/ws":"^8.5.10","typescript":"^5.4.0"},"peerDependencies":{"openclaw":">= 2026.3.7"},"_npmOperationalInternal":{"tmp":"tmp/agentshire_2026.4.12_1776007419650_0.24613785320497916","host":"s3://npm-registry-packages-npm-production"}},"2026.4.13":{"name":"agentshire","version":"2026.4.13","keywords":["openclaw","ai-agents","multi-agent","generative-agents","npc","threejs","3d","simulation","game","visualization","low-poly","typescript","open-source","level-editor","character-creator"],"author":{"name":"Agentshire Contributors"},"license":"MIT","_id":"agentshire@2026.4.13","maintainers":[{"name":"chnyujin","email":"chnyujin@gmail.com"}],"homepage":"https://github.com/Agentshire/Agentshire#readme","bugs":{"url":"https://github.com/Agentshire/Agentshire/issues"},"dist":{"shasum":"bb3525ce78d581d05cc8314404d95848cbefb68f","tarball":"https://registry.npmjs.org/agentshire/-/agentshire-2026.4.13.tgz","fileCount":406,"integrity":"sha512-yI5+iwSHL36AdijXxGsrSjgh5KodGFBQgT13orDjotF2rlAaegFsdfSKZX1N6lZgh4oYOaYTL6yYzEpyDyWAHg==","signatures":[{"sig":"MEQCIFIc1G8A23VqVpDHpSwViWvbLr/7y/bwb/28Q4fEHzMIAiABqjGlnHTmYbsgovxBesp61kw2eQPtVmZs21YIDtIFew==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28055245},"main":"./index.ts","type":"module","exports":{".":"./index.ts"},"gitHead":"3b5b5c34d19f10c911c1beb920115de04d0d99cf","scripts":{"test":"vitest run","build":"npm run build:town","dev:town":"cd town-frontend && npm run dev","build:town":"cd town-frontend && npm install && npm run build","postinstall":"echo '' && echo '  🏘️  Agentshire installed successfully!' && echo '' && echo '  Next: (re)start the OpenClaw Gateway to activate the plugin.' && echo '        The town will open automatically in your browser.' && echo ''"},"_npmUser":{"name":"chnyujin","email":"chnyujin@gmail.com"},"openclaw":{"channel":{"id":"agentshire","blurb":"Visualize your AI agents as NPCs in an interactive 3D low-poly town. Watch them work, chat, and collaborate in real-time.","label":"Agentshire","order":100,"docsPath":"/channels/agentshire","docsLabel":"agentshire","selectionLabel":"Agentshire (3D Visualization)"},"install":{"npmSpec":"agentshire","localPath":"extensions/agentshire","defaultChoice":"npm"},"extensions":["./index.ts"]},"repository":{"url":"git+https://github.com/Agentshire/Agentshire.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw/QClaw plugin for building a living 3D town with social NPCs, a map editor, and a character workshop.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.16.0","jsonrepair":"^3.13.3","@gltf-transform/core":"^4.3.0","@gltf-transform/functions":"^4.3.0","@gltf-transform/extensions":"^4.3.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.0","@types/ws":"^8.5.10","typescript":"^5.4.0"},"peerDependencies":{"openclaw":">= 2026.3.7"},"peerDependenciesMeta":{"openclaw":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/agentshire_2026.4.13_1776008258060_0.5847134774443994","host":"s3://npm-registry-packages-npm-production"}},"2026.4.14":{"name":"agentshire","version":"2026.4.14","keywords":["openclaw","ai-agents","multi-agent","generative-agents","npc","threejs","3d","simulation","game","visualization","low-poly","typescript","open-source","level-editor","character-creator"],"author":{"name":"Agentshire Contributors"},"license":"MIT","_id":"agentshire@2026.4.14","maintainers":[{"name":"chnyujin","email":"chnyujin@gmail.com"}],"homepage":"https://github.com/Agentshire/Agentshire#readme","bugs":{"url":"https://github.com/Agentshire/Agentshire/issues"},"dist":{"shasum":"fc00098fdc42a8ce5f9df50784ff556ce31bdff5","tarball":"https://registry.npmjs.org/agentshire/-/agentshire-2026.4.14.tgz","fileCount":406,"integrity":"sha512-63VSYzm6KrRY+w7YF45ccQxDbk1eU8dxx8CJTvsLEaYIbRuDcVYCvZKC6IhxEUYdn7PaNVDpsDdaPz6fjxByEg==","signatures":[{"sig":"MEUCIBbXrla0HI70/st+qSvp5sxuI+gE5YvY4wKbWpnPlZLoAiEAthHf6k9+jNkFbq5GjLK6o0RdZB8IOELNSB50XztrXbM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28055519},"main":"./index.ts","type":"module","exports":{".":"./index.ts"},"gitHead":"995097ee39f442fd8e4e8fed0052860b2ef25919","scripts":{"test":"vitest run","build":"npm run build:town","dev:town":"cd town-frontend && npm run dev","build:town":"cd town-frontend && npm install && npm run build","postinstall":"echo '' && echo '  🏘️  Agentshire installed successfully!' && echo '' && echo '  Next: (re)start the OpenClaw Gateway to activate the plugin.' && echo '        The town will open automatically in your browser.' && echo ''"},"_npmUser":{"name":"chnyujin","email":"chnyujin@gmail.com"},"openclaw":{"channel":{"id":"agentshire","blurb":"Visualize your AI agents as NPCs in an interactive 3D low-poly town. Watch them work, chat, and collaborate in real-time.","label":"Agentshire","order":100,"docsPath":"/channels/agentshire","docsLabel":"agentshire","selectionLabel":"Agentshire (3D Visualization)"},"install":{"npmSpec":"agentshire","localPath":"extensions/agentshire","defaultChoice":"npm"},"extensions":["./index.ts"]},"repository":{"url":"git+https://github.com/Agentshire/Agentshire.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw/QClaw plugin for building a living 3D town with social NPCs, a map editor, and a character workshop.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.16.0","jsonrepair":"^3.13.3","@gltf-transform/core":"^4.3.0","@gltf-transform/functions":"^4.3.0","@gltf-transform/extensions":"^4.3.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.0","@types/ws":"^8.5.10","typescript":"^5.4.0"},"peerDependencies":{"openclaw":">= 2026.3.7"},"peerDependenciesMeta":{"openclaw":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/agentshire_2026.4.14_1776008879012_0.5053367753208191","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"agentshire","version":"1.0.0","keywords":["openclaw","ai-agents","multi-agent","generative-agents","npc","threejs","3d","simulation","game","visualization","low-poly","typescript","open-source","level-editor","character-creator"],"author":{"name":"Agentshire Contributors"},"license":"MIT","_id":"agentshire@1.0.0","maintainers":[{"name":"chnyujin","email":"chnyujin@gmail.com"}],"homepage":"https://github.com/Agentshire/Agentshire#readme","bugs":{"url":"https://github.com/Agentshire/Agentshire/issues"},"dist":{"shasum":"3bc5e07242d97a718d13562b5ad5a3e38d945994","tarball":"https://registry.npmjs.org/agentshire/-/agentshire-1.0.0.tgz","fileCount":406,"integrity":"sha512-YPZ1bSjkS6hXRP2RZ5m1B84JPJQweO0bMu1+h8AqE9LwU6G+sbJqdC5ERG4uJZe30I1reVQw8ffRQijwUZdrMA==","signatures":[{"sig":"MEUCIDOHKLzXpszK022VTzzB23ZWRTKCTKHdaJgKNDhu7cLVAiEAinL1KwANHMb9aocxXei1QQLUMc3QfyfDJLmkek/vuP0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28055434},"main":"./index.ts","type":"module","exports":{".":"./index.ts"},"gitHead":"2a2eb7727dffd924bdc82c1437247e23afa449f0","scripts":{"test":"vitest run","build":"npm run build:town","dev:town":"cd town-frontend && npm run dev","build:town":"cd town-frontend && npm install && npm run build","postinstall":"echo '' && echo '  🏘️  Agentshire installed successfully!' && echo '' && echo '  Next: (re)start the OpenClaw Gateway to activate the plugin.' && echo '        The town will open automatically in your browser.' && echo ''"},"_npmUser":{"name":"chnyujin","email":"chnyujin@gmail.com"},"openclaw":{"channel":{"id":"agentshire","blurb":"Visualize your AI agents as NPCs in an interactive 3D low-poly town. Watch them work, chat, and collaborate in real-time.","label":"Agentshire","order":100,"docsPath":"/channels/agentshire","docsLabel":"agentshire","selectionLabel":"Agentshire (3D Visualization)"},"install":{"npmSpec":"agentshire","localPath":"extensions/agentshire","defaultChoice":"npm"},"extensions":["./index.ts"]},"repository":{"url":"git+https://github.com/Agentshire/Agentshire.git","type":"git"},"_npmVersion":"11.12.1","description":"OpenClaw/QClaw plugin for building a living 3D town with social NPCs, a map editor, and a character workshop.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.16.0","jsonrepair":"^3.13.3","@gltf-transform/core":"^4.3.0","@gltf-transform/functions":"^4.3.0","@gltf-transform/extensions":"^4.3.0"},"_hasShrinkwrap":false,"readmeFilename":"README.zh-CN.md","devDependencies":{"vitest":"^4.1.0","@types/ws":"^8.5.10","typescript":"^5.4.0"},"peerDependencies":{"openclaw":">= 2026.3.7"},"peerDependenciesMeta":{"openclaw":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/agentshire_1.0.0_1776009585105_0.3030538954652351","host":"s3://npm-registry-packages-npm-production"}},"2026.4.15":{"name":"agentshire","version":"2026.4.15","description":"OpenClaw/QClaw plugin for building a living 3D town with social NPCs, a map editor, and a character workshop.","main":"./index.ts","exports":{".":"./index.ts"},"type":"module","license":"MIT","author":{"name":"Agentshire Contributors"},"homepage":"https://github.com/Agentshire/Agentshire#readme","repository":{"type":"git","url":"git+https://github.com/Agentshire/Agentshire.git"},"bugs":{"url":"https://github.com/Agentshire/Agentshire/issues"},"keywords":["openclaw","ai-agents","multi-agent","generative-agents","npc","threejs","3d","simulation","game","visualization","low-poly","typescript","open-source","level-editor","character-creator"],"scripts":{"build:town":"cd town-frontend && npm install && npm run build","build":"npm run build:town","dev:town":"cd town-frontend && npm run dev","postinstall":"echo '' && echo '  🏘️  Agentshire installed successfully!' && echo '' && echo '  Next: (re)start the OpenClaw Gateway to activate the plugin.' && echo '        The town will open automatically in your browser.' && echo ''","test":"vitest run"},"dependencies":{"@gltf-transform/core":"^4.3.0","@gltf-transform/extensions":"^4.3.0","@gltf-transform/functions":"^4.3.0","jsonrepair":"^3.13.3","ws":"^8.16.0"},"peerDependencies":{"openclaw":">= 2026.3.7"},"peerDependenciesMeta":{"openclaw":{"optional":true}},"devDependencies":{"@types/ws":"^8.5.10","typescript":"^5.4.0","vitest":"^4.1.0"},"openclaw":{"extensions":["./index.ts"],"channel":{"id":"agentshire","label":"Agentshire","selectionLabel":"Agentshire (3D Visualization)","docsPath":"/channels/agentshire","docsLabel":"agentshire","blurb":"Visualize your AI agents as NPCs in an interactive 3D low-poly town. Watch them work, chat, and collaborate in real-time.","order":100},"install":{"npmSpec":"agentshire","localPath":"extensions/agentshire","defaultChoice":"npm"}},"gitHead":"167ef61d46695f7f305fb4c6d1076d4a30541946","_id":"agentshire@2026.4.15","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-I/+bnslIDgpeg8giwc/RjqxiQGpHi789oJX2uTiyQcTlH6c0gm1/PvKd7wDtFrJOMtgOpCkSLP9tvQeJKGwuWA==","shasum":"dddce10b54f4cb0caee3ae0ab4a9f9219471d3c9","tarball":"https://registry.npmjs.org/agentshire/-/agentshire-2026.4.15.tgz","fileCount":406,"unpackedSize":28055438,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCEYWGlLLZxB8SdcqARv7wGnpK6KNX57aJeFLQjFCOnJgIgIlcSq836eX4rrh5Db7PbflJpaW46Ao/bXA+0+s+LQG8="}]},"_npmUser":{"name":"chnyujin","email":"chnyujin@gmail.com"},"directories":{},"maintainers":[{"name":"chnyujin","email":"chnyujin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentshire_2026.4.15_1776010982440_0.13243664289236934"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-12T15:23:39.543Z","modified":"2026-04-12T16:23:03.230Z","2026.4.12":"2026-04-12T15:23:40.210Z","2026.4.13":"2026-04-12T15:37:38.596Z","2026.4.14":"2026-04-12T15:47:59.631Z","1.0.0":"2026-04-12T15:59:45.891Z","2026.4.15":"2026-04-12T16:23:03.107Z"},"bugs":{"url":"https://github.com/Agentshire/Agentshire/issues"},"author":{"name":"Agentshire Contributors"},"license":"MIT","homepage":"https://github.com/Agentshire/Agentshire#readme","keywords":["openclaw","ai-agents","multi-agent","generative-agents","npc","threejs","3d","simulation","game","visualization","low-poly","typescript","open-source","level-editor","character-creator"],"repository":{"type":"git","url":"git+https://github.com/Agentshire/Agentshire.git"},"description":"OpenClaw/QClaw plugin for building a living 3D town with social NPCs, a map editor, and a character workshop.","maintainers":[{"name":"chnyujin","email":"chnyujin@gmail.com"}],"readme":"# Agentshire — 夏尔小镇\n\n[English](README.md) | 中文\n\n> **Agentshire — 让你的 OpenClaw/QClaw Agent 住进你亲手搭建的3D游戏小镇，而不是ChatBox。**\n\nAgentshire 是一个支持OpenClaw/QClaw的插件，让 AI Agent 变成 3D 游戏小镇里活生生的 NPC——你可以观看、对话、也可以亲手改造这个世界。它融合了生活模拟与 UGC 工具：天气系统、昼夜循环、NPC 自主社交、地图编辑器、角色工坊。\n\n**同时支持 OpenClaw CLI 和 [QClaw](https://qclaw.cn) 桌面端。**\n\n**[查看完整愿景](VISION.md)** | **[查看路线图](ROADMAP.md)**\n\n> **⚠️ 兼容性说明**\n>\n> | 平台 | 版本 | 状态 |\n> |---|---|---|\n> | **OpenClaw CLI** | 2026.3.13 | ✅ 推荐 |\n> | **QClaw 桌面端** | 0.2.x | ✅ 支持 |\n> | OpenClaw CLI | 2026.3.7 – 3.12 | ⚠️ 可能兼容 |\n> | OpenClaw CLI | 2026.4.x+ | ❌ 暂不支持 — Channel 初始化存在回归问题 |\n>\n> 版本相关问题请查看[故障排除](#故障排除)。\n\n---\n\n## 眼见为实\n\n> **📺 [观看完整 Demo 视频](https://www.youtube.com/watch?v=R6YXvkkwo9I)**\n\n**一座小镇，不是仪表盘。**\n\nhttps://github.com/user-attachments/assets/c888d2ef-dcba-4caa-b0af-9b5f3e3b1365\n\n**造你的居民——选模型，赋灵魂，看他活过来。**\n\nhttps://github.com/user-attachments/assets/b9697432-b3ba-4e23-85fe-4c0b5c35a1b9\n\n**造你的小镇——拖拽搭建，一键预览。**\n\nhttps://github.com/user-attachments/assets/3328aa6c-3432-4f71-abfd-91aea4db15df\n\n**每个居民都有自己的想法。**\n\nhttps://github.com/user-attachments/assets/720a63fc-863c-483c-bfdf-5e07e82c6f0e\n\n**下达任务，居民集结。**\n\nhttps://github.com/user-attachments/assets/1983f60b-aaf6-4adc-b46c-5612e4ba4c83\n\n**干太久？班味 Boss 来了。消灭它。**\n\nhttps://github.com/user-attachments/assets/9be946e0-9ecf-42de-b793-a5d7ebe55612\n\n**任务完成。烟花庆祝。成品交付。**\n\nhttps://github.com/user-attachments/assets/fa6563ae-e78b-49b1-ae7b-8a8a96738341\n\n---\n\n## 功能特性\n\n### 双模式界面\n\n- **Town 模式** — 3D 低多边形小镇，实时观看 NPC 生活、工作、协作、庆祝\n- **Chat 模式** — IM 风格聊天界面，左侧 Agent 列表（管家 + 居民，在线状态），右侧消息流，支持文本/图片多模态、聊天历史（游标分页）、命令系统（`/new` `/help` `/stop`）\n- **顶部导航栏** — Town / Chat 一键切换，右上角快捷菜单（居民管理 / 小镇改造 / 技能商店 / 设置）\n- **双语界面** — 完整中英文界面，自动检测或手动切换\n\n### 核心\n\n- **Agent = NPC** — 每个子 Agent 自动变成小镇里的 3D 居民，有名字、有形象、有人格\n- **电影级工作流** — 召唤 → 集结 → 分配 → 进办公室 → 编码 → 庆祝 → 返回小镇，全程动画编排\n- **实时对话气泡** — AI 的回复以打字机效果显示在 NPC 头顶，支持流式更新和分页\n- **多 Agent 协作** — 管家自动拆解任务、分步骤并行 spawn 子 Agent，支持文件边界校验\n- **零配置** — 安装插件，启动 Gateway，小镇自动运行\n\n### 小镇生活\n\n- **昼夜循环** — 24 小时时钟系统（6 个时段）、实时光照变化、路灯/窗灯自动开关\n- **12 种天气** — 晴/阴/雾/小雨/大雨/暴风/雪/暴雪/沙尘暴/极光…每天随机日主题，时段间平滑过渡\n- **程序合成环境音** — 雨声、风声、鸟鸣、蟋蟀、交通噪声、雷声——全部零音频文件，Web Audio API 实时合成\n- **4 轨 BGM** — day / dusk / night / work 四首背景音乐，按天气、时段、场景自动切换，3.5 秒交叉淡化\n- **NPC 日常行为（双模式）** — 默认算法驱动：DailyBehavior 状态机 + 5 种行为模板（按专业匹配） + 400+ 条预设台词社交，零 LLM 开销；开启灵魂模式后切换为 AI 驱动：AgentBrain 三层决策（L1 日计划 / L2 战术 / L3 对话）+ LLM 深度多轮对话 + 关系图谱 + 每日叙事摘要\n- **居民独立聊天** — 点击居民 NPC 直接发起对话，消息路由到居民自己的独立 Agent 会话\n- **话题讨论** — 发起多居民参与的群组话题讨论，支持结构化轮流发言和 AI 主持\n- **班味消除小游戏** — NPC 工作时头顶生成\"班味团子\"，点击消除！含 combo 连击、Boss 战、NPC 压力系统，可扩展更多玩法\n\n### UGC 工具\n\n- **居民工坊** — 创建和配置居民角色：选择/上传 3D 模型、编辑灵魂人设（支持 AI 一键生成）、配置动画映射（8 槽位）、发布为独立 Agent\n- **小镇编辑器** — 可视化拖拽编辑地图：放置建筑/道路/道具/灯光，支持组合、对齐、撤销、导入导出（已支持导出 JSON，与小镇接入开发中）\n- **编辑器预览** — 一键打开游戏级预览窗口（WASD 控制 + 完整昼夜天气 + 车辆动画 + 音频）\n- **灵魂系统** — 每个 NPC 有一份 Markdown 人设文件，定义性格、说话风格、专长和工作方式\n\n### 交互与视觉\n\n- **交互式 3D** — 点击 NPC 查看状态卡片（头像/人格/工作日志/thinking 流/TODO），拖拽视角，滚轮缩放\n- **三场景切换** — 小镇（日常生活）/ 办公室（工作）/ 展示厅（开发中），带淡入淡出过渡和 NPC 迁移\n- **丰富的 VFX** — 召唤冲击波、完成烟花、错误闪电、人格变换魔法阵、思考光环、搜索雷达、部署彩纸…\n- **10 工位办公室** — 每个工位有独立显示器（实时代码动画），NPC 进场/工作/离场全流程编排\n- **交付物预览** — 项目完成后弹出交付物卡片，支持图片（lightbox 放大）、视频、音频预览和下载，游戏/网站类直接 iframe 启动\n- **AI 工具控制** — Agent 可以通过工具主动控制小镇（广播消息、生成 NPC、触发特效、设置时间/天气）\n- **断线重连** — WebSocket 断线自动指数退避重连，工作状态自动恢复\n\n---\n\n## 环境要求\n\n- [OpenClaw](https://github.com/openclaw/openclaw) **2026.3.13** 或 [QClaw](https://qclaw.cn) **0.2.x**\n- Node.js >= 18（QClaw 用户无需安装）\n\n---\n\n## 快速安装\n\n```bash\nopenclaw plugins install agentshire\n```\n\n就这样。重启 Gateway，小镇会自动在浏览器打开。\n\n### 备选：Link 安装（开发用）\n\n```bash\ngit clone https://github.com/Agentshire/Agentshire.git\ncd Agentshire && npm install\nopenclaw plugins install --link .\n```\n\n> 前端已**预编译**（`town-frontend/dist/`），无需 build。开发者可用 `npm run build:town` 重新构建。\n\n### 首次启动时插件自动配置\n\n1. 在状态目录下创建管家工作区（`workspace-town-steward/`）\n2. 在 `openclaw.json` 中注册 `town-steward` Agent\n3. 添加路由规则，将小镇频道的消息路由到管家\n4. 设置 `subagents.runTimeoutSeconds: 600` — 子 Agent 运行超时 10 分钟，防止提前终止\n\n> 状态目录自动检测：OpenClaw CLI 为 `~/.openclaw/`，QClaw 为 `~/.qclaw/`。\n\n> **重要**：请勿在 `openclaw.json` 中手动添加 `tools` 配置段。插件通过 `api.registerTool()` 注册工具。手动添加 `tools.allow` 列表会覆盖插件注册的工具，导致 Agent 无法使用。\n\n### 更新\n\n```bash\nopenclaw plugins install agentshire\n```\n\nLink 安装用户：`cd Agentshire && git pull && npm install`。\n\n然后重启 Gateway（或重启 QClaw）。\n\n---\n\n## 使用方式\n\n1. 完成[快速安装](#快速安装)\n2. 启动（或重启）OpenClaw Gateway：\n   ```bash\n   openclaw gateway\n   ```\n3. 小镇会自动在浏览器中打开\n4. 在浏览器中对话——所有 Agent 活动会自动映射到小镇中\n\n> **提示**：如果浏览器没有自动打开，手动访问：\n> `http://localhost:55210?ws=ws://localhost:55211`\n\n\n### 居民工坊\n\n访问 `http://localhost:55210/citizen-editor.html` 打开居民工坊，创建和配置你的 NPC 团队。\n\n### 小镇编辑器\n\n访问 `http://localhost:55210/editor.html` 打开小镇编辑器，可视化编辑地图布局。\n\n### 配置（可选）\n\n在你的 `openclaw.json` 中自定义端口和行为（OpenClaw CLI 为 `~/.openclaw/openclaw.json`，QClaw 为 `~/.qclaw/openclaw.json`）：\n\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"agentshire\": {\n        \"enabled\": true,\n        \"config\": {\n          \"wsPort\": 55211,\n          \"townPort\": 55210,\n          \"autoLaunch\": true\n        }\n      }\n    }\n  }\n}\n```\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `wsPort` | 55211 | WebSocket 端口（插件与前端实时通信） |\n| `townPort` | 55210 | HTTP 端口（前端静态资源 + 编辑器 API） |\n| `autoLaunch` | true | 启动时自动在浏览器中打开小镇 |\n\n### AI 可用工具\n\n| 工具名 | 说明 |\n|--------|------|\n| `town_announce` | 在小镇广播消息 |\n| `town_spawn_npc` | 生成新 NPC |\n| `town_effect` | 触发视觉特效（庆祝/烟花/光圈等） |\n| `town_set_time` | 控制游戏时钟（设置时间） |\n| `town_set_weather` | 控制天气（12 种天气可选） |\n| `town_status` | 查看小镇当前状态 |\n| `register_project` | 注册简单项目（单 Agent 或管家独立完成） |\n| `create_project` | 创建多 Agent 项目目录 |\n| `create_task` | 创建单次委派任务目录 |\n| `create_plan` | 创建协作计划（分步骤并行执行，需先 `create_project` 或 `create_task`） |\n| `next_step` | 查询计划进度，获取下一步指令 |\n| `mission_complete` | 统一完成处理 — 自动判断触发庆祝结束或仅发交付物卡片 |\n\n---\n\n## 灵魂系统\n\n每个 NPC 都有独立的**灵魂文件**（Markdown），定义了角色的性格、说话风格、专长和工作方式。\n\n灵魂文件格式：以 `# 角色名` 开头的 Markdown 文件，可包含元数据（模型 id、性别、岗位）、人设核心、性格详细设定、对话示例等。内容会作为 system prompt 注入 Agent。\n\n**搜索优先级**（后者覆盖前者）：\n\n1. `插件内置/town-souls/` — 预设灵魂（8 个居民 + 管家）\n2. `当前工作目录/town-souls/` — 项目级灵魂\n3. `{状态目录}/town-souls/` — 用户自定义灵魂（`~/.openclaw/` 或 `~/.qclaw/`）\n4. `town-data/souls/` — 居民工坊发布的灵魂\n\n你可以：\n- 在居民工坊中 **AI 一键生成**灵魂文件\n- 修改内置灵魂文件来调整角色性格\n- 在状态目录的 `town-souls/` 下放置自定义灵魂来覆盖预设\n- 创建全新的灵魂文件来定义新角色\n\n---\n\n## 架构概览\n\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                      OpenClaw Runtime                    │\n│                                                          │\n│  Gateway ─── Agent Sessions ─── Hook System ─── LLM      │\n└──────┬────────────────────────────┬──────────────────────┘\n       │ dispatch                   │ hook callback\n       ▼                            ▼\n┌──────────────────────────────────────────────────────────┐\n│  Plugin Layer (Node.js)                     src/plugin/  │\n│                                                          │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │\n│  │ channel  │  │  hook-   │  │ws-server │  │  tools   │  │\n│  │ dispatch │  │translator│  │ WS:55211 │  │ 11 tools │  │\n│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │\n│  │  plan-   │  │ editor-  │  │ citizen- │  │llm-proxy │  │\n│  │ manager  │  │  serve   │  │  router  │  │ 2 concur │  │\n│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │\n└──────┬───────────────┬───────────────────────────────────┘\n       │ WS :55211     │ HTTP :55210\n       │ AgentEvent    │ Editor API\n       ▼               ▼\n┌──────────────────────────────────────────────────────────┐\n│  Bridge Layer (Browser)                     src/bridge/  │\n│                                                          │\n│  ┌────────────────────────────────────────────────────┐  │\n│  │ DirectorBridge — Phase State Machine               │  │\n│  │ idle→summoning→assigning→office→working→publish→ret│  │\n│  └────────────────────────────────────────────────────┘  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │\n│  │  Event-  │  │  Route-  │  │ Citizen- │  │implicit- │  │\n│  │Transltor │  │ Manager  │  │ Manager  │  │  chat    │  │\n│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │\n└──────┬────────────────────────────────────────────┬──────┘\n       │ GameEvent (65)                 GameAction  │\n       ▼                                (14)        ▲\n┌──────────────────────────────────────────────────────────┐\n│  Frontend Layer (Three.js)          town-frontend/src/   │\n│                                                          │\n│  ┌────────────────────────────────────────────────────┐  │\n│  │ MainScene ── EventDispatcher ── update() loop      │  │\n│  └────────────────────────────────────────────────────┘  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │\n│  │workflow/ │  │  npc/    │  │   ui/    │  │  audio/  │  │\n│  │Choreogr  │  │ NPC 7-SM │  │ChatBubbl │  │ BGM+Amb  │  │\n│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │\n│  │ scene/   │  │ editor/  │  │ engine/  │  │  data/   │  │\n│  │Town/Offc │  │Workshop  │  │ Render   │  │ Protocol │  │\n│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │\n└──────────────────────────────────────────────────────────┘\n```\n> 开发者架构指南见 [AGENTS.md](AGENTS.md)。\n\n---\n\n## 开发\n\n```bash\n# 克隆仓库后\ncd agentshire\n\n# 构建小镇前端\ncd town-frontend && npm install && npm run build\n\n# 开发模式（前端热更新）\ncd town-frontend && npm run dev\n\n# 运行测试\nnpm test                              # 插件 + 桥接层\ncd town-frontend && npx vitest run    # 前端\n```\n\n前端有 4 个入口页面：\n\n| 页面 | URL | 说明 |\n|------|-----|------|\n| 小镇主页 | `index.html` | 3D 小镇 + 聊天 |\n| 小镇编辑器 | `editor.html` | 地图可视化编辑 |\n| 居民工坊 | `citizen-editor.html` | 角色创建和配置 |\n| 编辑器预览 | `preview.html` | 游戏级预览窗口 |\n\n> 开发者架构指南见 [AGENTS.md](AGENTS.md)。\n\n---\n\n## 扩展资产包（可选）\n\n基础功能**不需要额外下载**——小镇、办公室、NPC 使用的内置模型（KayKit + Kenney）已包含在仓库中。\n\n如果你需要以下高级功能，可以下载扩展资产包：\n\n- **居民工坊 Library 角色**（308 个角色模型，多种变体和配色）\n- **编辑器 Cartoon City 资产**（建筑、车辆、道路、公园等数百个模型）\n\n### 下载方式\n\n1. 从 [GitHub Releases (v0.1.0)](https://github.com/Agentshire/Agentshire/releases/tag/v0.1.0) 下载 `agentshire-assets.7z`（约 164MB，解压后约 4.4GB）\n2. 解压到插件根目录：\n   ```bash\n   cd /path/to/agentshire\n   7z x agentshire-assets.7z\n   ```\n3. 确保目录结构为：\n\n```\nagentshire/\n├── assets/\n│   ├── Characters_1/    ← Library 角色模型 + 共享动画\n│   └── Map_1/           ← Cartoon City 编辑器资产\n├── src/\n├── town-frontend/\n└── ...\n```\n\n不下载资产包时：游戏正常运行，编辑器基础资产可用，居民工坊仅显示内置和自定义模型。\n\n> 资产来源和许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。\n\n---\n\n## 故障排除\n\n### Agent 无法识别插件工具\n\n**现象**：管家 Agent 无法找到 `create_project`、`create_plan` 等插件工具。\n\n**原因**：OpenClaw 2026.3.13 中 Rollup 代码分割会创建独立的模块实例，导致 `api.registerTool()` 注册的工具对 Agent 运行时不可见。此外，`openclaw.json` 中手动添加的 `tools` 配置段会覆盖插件注册的工具。\n\n**解决**：\n1. 删除 `openclaw.json` 中的整个 `tools` 配置段（如果有）\n2. 重启 Gateway\n\n### QClaw：插件更新后仍运行旧代码\n\n**原因**：关闭 QClaw 窗口不会停止后台 `openclaw-gateway` 进程。\n\n**解决**：重启前先杀掉 gateway：`ps aux | grep openclaw-gateway | grep -v grep | awk '{print $2}' | xargs kill`\n\n### OpenClaw 2026.4.x 上 Channel 不启动\n\n**现象**：插件加载成功但 WebSocket 连接未建立，小镇页面一直显示\"连接中…\"。\n\n**原因**：OpenClaw 2026.4.x 在外部插件的 Channel 初始化流程中存在回归 Bug，`defineChannelPluginEntry` 生命周期未被正确调用。\n\n**解决**：降级到 OpenClaw 2026.3.13。这是已知的上游问题。\n\n### 角色工坊\"AI 生成\"返回 500 错误\n\n**现象**：在角色工坊中点击\"AI 生成\"失败。\n\n**原因**：灵魂生成接口需要 `openclaw.json` 中配置有效的 LLM 提供商。如果未配置或 API Key 无效，请求会失败。\n\n**解决**：确保 `openclaw.json` 中有有效的 `models` 配置，详见 [OpenClaw 文档](https://github.com/openclaw/openclaw)。\n\n---\n\n## 为什么叫 Agentshire\n\n**Agentshire** 这个名字的灵感来自《指环王》里的**夏尔（Shire）**。\n\n夏尔最打动人的地方，从来不是宏大的史诗感，而是它的宁静、日常、缓慢、丰饶，与那种\"这里适合好好生活\"的感觉。是田野、小路、窗灯、饭香、邻里、散步、闲谈——一种不需要时刻战斗、时刻加速的存在状态。\n\n今天很多 AI 产品对未来的想象，总是赛博朋克的、高压的、极度加速的。Agent 活在 dashboard 里，活在日志/接口里，却不像真正生活在某个地方。\n\n但我想象的是另一种未来——一个更安静的未来，一个更温柔的界面。让智能体不只是被调用、被驱动、被消费，而是可以真正\"住下来\"的地方。\n\n**如果智能体会越来越进入我们的生活，那么它们也应该拥有一个像\"家\"一样的地方。**\n\n不是冰冷的机房，不是永远待命的控制台，而是一个有道路、有广场、有咖啡馆、有日常节奏的游戏小镇。\n\nAI 的未来不一定非要长得像未来战场。它也可以像一个让人愿意住进去、也愿意让自己的 Agent 住进去的地方。\n\n---\n\n## 愿景与路线图\n\n> 团队不住在仪表盘里。团队住在一座小镇里。  \n> 当孤岛连成大陆，小镇就长成了世界。\n\n| 阶段 | 方向 | 状态 |\n|------|------|------|\n| **一座小镇** | 3D 可视化、工作流编排、灵魂系统、居民工坊、双模式界面 | ✅ 已实现 |\n| **让小镇稳定运行** | QClaw + OpenClaw 兼容、双语 i18n、话题讨论、npm 发布 | 🔥 当前重点 |\n| **让小镇活起来** | 编辑器打通、生活模拟（衣食住行玩）、成长体系、手机版 | 📋 下一步 |\n| **连成世界** | 小镇联邦协议、跨镇 NPC 互访、技能交换、世界事件 | 🌍 远期愿景 |\n\n详见 **[VISION.md](VISION.md)** 和 **[ROADMAP.md](ROADMAP.md)**。\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.zh-CN.md"}