# HermesCraft

> 仓库地址：https://github.com/bigph00t/hermescraft
> 作者/组织：bigph00t
> 成熟度：beta
> 分析日期：2026-04-15

## 一句话总结
在 Minecraft 世界中创建具有独立记忆、身份和公平感知能力的 AI 伙伴/文明，每个角色本质上是一个完整的 Hermes Agent。

## 项目定位与架构
HermesCraft 让 AI agent 以 Minecraft 角色的形式存在于游戏世界中，支持单人伙伴、多 agent 文明、社区群体等多种模式。区别于传统 NPC 框架，每个角色拥有独立的 `HERMES_HOME`、session history 和自定义 SOUL prompt。

核心架构栈为：`Hermes Agent → Terminal + Tools → MC CLI → Bot/Server.js HTTP API → Mineflayer Bot → Minecraft World`。系统使用 Claude Sonnet 4 作为 LLM backbone，通过 HTTP API 与 Mineflayer bot 通信。

## 关键技术特性
- **Fair-play perception**：视线过滤、方向性声音提示（非精确坐标）、承认不确定性，避免全知行为
- **持久化身份**：每个 agent 拥有独立记忆、session、保存位置和 SOUL prompt
- **多运行模式**：Companion Mode（单伴侣）、Civilization Mode（多 agent 涌现行为）、Landfolk Mode（预设角色阵容）
- **社交系统**：公共聊天、私信、群组消息、偷听附近对话、玩家命令队列
- **具身能力**：移动、寻路、挖矿、合成、箱子交互、战斗全覆盖

## 设计亮点与创新
最大亮点是 "fair-play perception" 设计哲学——拒绝 x-ray 全知，选择具身化、公平化、持久化。ASCII 地图渲染和自然语言场景描述（`mc look` / `mc scene`）让 agent 像真正的玩家一样感知世界。7 角色的坠机幸存者文明模式展示了涌现行为的潜力。

## 局限性与风险
当前聚焦于早/中期生存和小规模社会行为，endgame 自主性尚未覆盖。自动化批量启动器和竞技场模式标记为 experimental。多 agent 场景的 LLM API 成本可能显著。依赖 Claude Sonnet 4 的 API 可用性。

## 与生态系统的关联
直接使用 Hermes CLI 作为每个角色的运行时，是 Hermes 在游戏 AI / embodied agent 领域的旗舰展示。与 Hermes 的 memory、skill、gateway 系统深度集成。