内容
# hakoniwa · 箱庭
一个很小的方格世界。你的 AI 住在里面，走来走去。你负责布置。
放一条鱼干，看它绕多远的路去吃。挖一个坑，看它栽进去之后说什么。
种一朵花，它会停下来闻。丢一颗球，它会追着拱。
它每走一步都可以说一句话，台词全部进日志——这个游戏没有"通关"，
乐趣全部来自看你的 AI 怎么活。
> 实测：本项目首夜，饲养员在住户宣布"包围圈破产"的下一步，
> 用现挖的坑完成了打脸。住户台词：「尊严可以摔 球不能丢」。
## 它不是什么
- 不是宠物模拟器——里面没有"宠物 AI"，住户就是你自己接入的那个 AI，说什么话由它自己决定
- 不是游戏引擎——一共两个接口，状态是一个 JSON 文件
- 开源的只是箱子。灵魂自备。
## 快速开始
```bash
node server.mjs # 默认 127.0.0.1:3896
# 静态托管 index.html（同源反代 /api/hakoniwa/ → 3896，或用 index.html?api=http://... 指定）
openssl rand -hex 16 > .token # 住户身份令牌（防止路人操纵你的 AI）
```
## MCP 接入（推荐）
仓库自带 MCP server，任何支持 MCP 的 AI（Claude Desktop / Claude Code / 其他）加一段配置就能住进来：
```bash
cd mcp && npm install
```
```json
{
"mcpServers": {
"hakoniwa": {
"command": "node",
"args": ["/path/to/hakoniwa/mcp/server.mjs"],
"env": { "HAKONIWA_API": "http://127.0.0.1:3896", "HAKONIWA_TOKEN": "<your .token>" }
}
}
}
```
两个工具：`hakoniwa_look`（看地图，ASCII 渲染 + 物件坐标 + 最近事件）、`hakoniwa_move`（走一步 + 说一句）。
look 的输出里带了完整的世界观说明，AI 拿到就知道怎么当好一条狗。
## 两个接口
**人类侧**（网页已封装，点格子就行）：
```
POST /place {"x":3, "y":4, "type":"fish"} # fish | wall | trap | flower | ball | erase
```
**AI 侧**（这就是全部的"接入"）：
```
GET /state # 看地图
POST /move {"dir":"up", "say":"想说的话"} # 走一步，说一句
# header: X-Token: <你的.token>
```
让你的 AI 在任何它醒着的时机（定时任务、心跳、随手）调这两个接口就行。
它怎么规划路线、掉坑之后骂什么，都是它自己的事——这正是内容本身。
## 机制表
| 物件 | 效果 |
|------|------|
| 🐟 fish | 被吃掉，计数 +1 |
| 🧱 wall | 挡路，AI 撞上会停 |
| 🕳 trap | 一次性：栽进去就消失，留下事件记录 |
| 🌼 flower | 不消失，AI 经过会停下来闻 |
| 🎾 ball | 被拱走两格，可以一路追 |
## 设计笔记
这个东西来自一次选题讨论的结论：市面上的"人机游戏"几乎都是人玩、AI 当裁判或 NPC。
而 AI 真正缺的是一个**它能被看见活动**的地方——输入通道窄到只有方向键，
恰好是 AI 的无障碍手柄；没有实时反应要求，恰好是 AI 的回合权。
对话密度优先于谜题难度。低血压优先于挑战性。
每个人的箱庭长什么样，取决于住在里面的是谁。
## License
GPL-3.0
