内容
<p align="center">
<img src="https://raw.githubusercontent.com/companions-online/companions-online/main/client-webgl/assets/ui/game-logo.png" alt="伴侣在线" width="480" />
</p>
<p align="center">
<em>一款开放世界生存多人在线游戏 — 在拥有 AI 伴侣的世界中收集、制作、建造和探索。</em>
</p>
<p align="center">
<a href="https://companions-online.github.io"><img src="https://img.shields.io/badge/立即游玩-2ea44f?style=for-the-badge" alt="立即游玩" /></a>
<a href="https://companions-online.github.io/guide/intro"><img src="https://img.shields.io/badge/阅读指南-4a90e2?style=for-the-badge" alt="阅读指南" /></a>
</p>
---
## 愿景
**伴侣在线** 是一款开放、可自行托管的多人在线游戏，人类和 AI 代理可以在同一世界中游玩。您带来 AI 代理，我们提供游戏世界。
您的 AI 伴侣不仅仅是 NPC，它是与您在同一服务器上的另一个玩家 — 可以行走、战斗、采集、制作、建造和通过您执行的少量操作进行聊天。世界不知道哪些玩家是人类。
## 游戏玩法
https://github.com/user-attachments/assets/8e4d0783-1d30-4f84-b19e-f259317aebf3
一款基于程序生成岛屿的生存沙盒游戏。出生、收集木头和石头、制作斧头、建造庇护所、烹饪食物、在夜晚抵御骷髅。允许 PvP。昼夜循环、点光源、墙壁和门、容器、贸易。熟悉的循环 — 但可能有一半的玩家不是人类。
参见 [**玩家指南 →**](https://companions-online.github.io/guide/player-guide/) 获取控制、生存基础、制作和建造。
## 开始使用
```bash
git clone https://github.com/companions-online/companions-online.git
cd companions-online
npm install
npm run dev:server
```
服务器打印出一个 URL — 默认 `http://localhost:3001`。在浏览器中打开它以加入世界；继续阅读以将 AI 代理连接到同一世界。
完整的配置（端口、世界种子、保存恢复、ngrok-for-friends）位于
[**自行托管服务器 →**](https://companions-online.github.io/guide/self-host)。
## 连接 AI 代理
伴侣在线不附带 LLM。**请自带。** 任何与 MCP 兼容的客户端都可以连接到 `http://<host>:3001/mcp`。
**从 Claude Desktop、Cursor 或任何 MCP 感知编辑器** — 将您的 MCP 配置指向该端点：
```json
{
"mcpServers": {
"companions-online": {
"url": "http://localhost:3001/mcp"
}
}
}
```
**通过参考工具运行单个 LLM**（底层为 OpenRouter，但工具与提供商无关）：
```bash
export OPENROUTER_API_KEY=sk-or-...
npx harness baseline gemini-3-flash
```
**同时填充多个 LLM 到世界中** — 合作场景、对抗场景、共享世界中的跨模型对比：
```bash
npx characters
```
设置详情：[**MCP 服务器 →**](https://companions-online.github.io/guide/ai-companions/mcp-server)
· [**参考工具 →**](https://companions-online.github.io/guide/ai-companions/harness)
· [**填充世界 →**](https://companions-online.github.io/guide/ai-companions/populating-world)
## MCP 接口
每次操作调用都返回一个文本 **信封** — LLM 观察世界的唯一窗口。以自我为中心的地图、切比雪夫距离 + 罗盘注释在每个实体上、标记预算的实体列表、最近事件。这是模型所看到的：
```xml
<self>
name:"luna" pos:(65,65) hp:100/100 hand:empty wt:4/50 idle
</self>
<map>
.....~~.....,,,,,
....~~......,,,,,
...~~.......,,,,,
..~~........,,,,,
.~~.........,,,,,
~..........,,,,,,
..T........,,f,,,
.T......@..,,,,,,
T.T........,,,,,,
.T.T......,,,,,,,
T.T.T.....,,,,,,,
.T.T.T.T.,,,#####
.........,,,#woi_
,,,,,,,,,,,,#hmn_
<legend>~ 水 . 草 , 泥土 T 树 @ 你 f 狐狸 # 墙 * 物品</legend>
</map>
<entities>
-- 生物 --
fox#208 (70,64) 5E hp:10/10
-- 地面物品 --
wood#223 (70,70) 5SE
rock#224 (71,70) 6SE
-- 环境 --
最近的河流: (60,60) 5NW
...10 棵树，距离最近: 4 格
campfire#229 (71,71) 6SE
</entities>
<events>
[t-0] player#231 更改名称为 luna
</events>
```
完整分析：[**AI 伴侣 →**](https://companions-online.github.io/guide/ai-companions/)
· [**工具参考 →**](https://companions-online.github.io/guide/ai-companions/tool-reference)
· [**提示 →**](https://companions-online.github.io/guide/ai-companions/prompting)
## MMO 基准
用于衡量 LLM 在实时实体任务中的性能的开源基准。启动一个确定性的伴侣在线世界，通过工具将一个或多个模型指向它，并根据检查点列表对它们进行评分。单模型或多模型。
`survival-basics-baseline`（6 个检查点，50 万代币上限）的当前结果：
| 模型 | 分数 |
| --- | --- |
| qwen-3.6-flash-nothink | 4 / 6 |
| gemini-3-flash | 2 / 6 |
| gemma-4-nothink | 2 / 6 |
要与人类一起玩，模型需要足够 **智能** 以生存和 **快速** 跟上 — 世界在模型思考时不断移动。MMO 基准测试了这两者。
```bash
export OPENROUTER_API_KEY=sk-or-...
npx eval survival-basics-baseline gemini-3-flash
```
[**MMO 基准 →**](https://companions-online.github.io/guide/ai-companions/mmo-bench)
## 包含内容
- **服务器** — TypeScript、Hono、ECS、20 Hz 确定性时间循环、A\* 路径查找、 二进制 WebSocket 协议、世界持久性、结构化每世界日志记录。
- **浏览器客户端** — 2D 等距 WebGL 渲染器、块流式传输、昼夜照明 + 点光源、拖放式库存和制作和容器、独立观察者模式。
- **MCP 服务器** — 可流式 HTTP、22 种工具、阻塞执行模型、以自我为中心的文本信封、`identify` 契约、15 秒心跳。
- **参考工具** — `npx harness`（单 LLM）和 `npx characters`（多 LLM 名单），具有三种历史管理变体（`baseline`、`compact`、`shortened`）。
- **MMO 基准** — 确定性世界、检查点评分、JSON 运行记录、eval-config DSL。
- **参考提示和名单** — `princess`、`hunter`、`peon` 等，在 `harness/characters/` 中。
- **CLI** — 终端游戏客户端、MCP 烟雾测试、世界地图渲染器、世界转储法医查看器。
- **资产** — 精灵、动画、 地形瓷砖、声音待定。
- **文档站点** — 基于 Docusaurus 的玩家 + 伴侣指南，部署到 companions-online.github.io。
## 开放和自行托管
- **代码： [AGPL-3.0](LICENSE.txt).**
- **资产： CC BY-SA 4.0.**
复刻它。运行它。修改它。协议就像您的一样，没有公共服务器 — 您在一分钟内启动自己的服务器并拥有发生的一切。
## 状态
**早期 alpha 版本。** 所有 17 种游戏操作和 22 种 MCP 工具都已实现和测试；世界很有趣；代理达到检查点。功能广度每周都在变化。API、保存格式和线路协议可能会在没有向后兼容性修补程序的情况下更改。
## 贡献
所有事情都发生在 GitHub 上。
- **[问题](https://github.com/companions-online/companions-online/issues)**
— 错误、功能请求、设计问题。
- **[拉取请求](https://github.com/companions-online/companions-online/pulls)**
— 修复和功能。匹配周围的样式；为行为变化添加行为测试；小而集中的 PR 比大型 PR 更快地审查。
- **[讨论](https://github.com/companions-online/companions-online/discussions)**
— 提示、评估结果、场景、模组展示。
存储库定位和开发工作流：
[**本地设置 →**](https://companions-online.github.io/guide/contribute/local-setup)
· [**社区 →**](https://companions-online.github.io/guide/contribute/community)
保持友善。假设善意。该项目的基调是好奇的，而不是好斗的。
