# cortico-world-oni

Cortico World extension for **Oxygen Not Included** (《缺氧》), bridging game simulation to AI streamers and agents via the **OniMods MCP Server**.

Owner: `src/index.ts`  
契约: Cortico API v4 (`kind: world`)

---

## 概述 (Overview)

`cortico-world-oni` 将《缺氧》底层的物理仿真、殖民地数据与指令系统抽象为标准 Cortico World 契约：
- **虚拟文件系统式世界编辑**：通过类似读写文本文件的形式审阅局部地图、拓扑管线，并通过 `SEARCH/REPLACE` 补丁批量下达建造与挖掘任务；
- **殖民地宏观监控与警报**：轮询小人窒息、饥饿、受伤、高压等致命状态，并转化为即时事件流推入 Agent 决策回路；
- **游戏节奏控制**：支持动态暂停（速度 0）以供 AI 进行深度规划，并在规划完成后恢复游戏流速；
- **解说与情绪引导**：内置专属环境提示词（`ENV_PROMPT.md`），使 AI 主播在遇到突发灾难时能够及时且生动地进行直播解说。

---

## 核心工具 (Tools)

本扩展在加载后向 AI Agent 暴露 10+1 个与最新 OniMcp 严格对齐的高阶聚合工具：

| 工具名称 | Tags | 描述 |
|---|---|---|
| `oni_world_editor` | `act`, `read`, `write` | 虚拟文件系统接口。以文本/切片读取地图，并通过文本替换补丁规划挖掘与排线。 |
| `oni_colony_control` | `read`, `write`, `snapshot` | 监控殖民地体征（氧气、食物、电力、健康）、生存规划、日程、科技与诊断警报。 |
| `oni_building_control` | `act`, `write` | 建筑统一入口：规划、建筑蓝图与材料查询、管网自动连接与排布。 |
| `oni_navigation_control` | `act`, `read` | 空间导航统一入口：相机移动/缩放、图层遮罩切换、截图与游戏内智能指针提示。 |
| `oni_orders_control` | `act`, `write` | 下达区域指令：挖掘、清扫、擦水、管线切断、拆除、优先级调整 (1~9)。 |
| `oni_dupes_control` | `read`, `write` | 复制人管理：属性诊断、特质、技能树加点、分配床位与餐桌、日程排班。 |
| `oni_read_control` | `read` | 结构化查询世界网格、可复用区域数据、管线网络、温度/质量分布。 |
| `oni_search_control` | `read` | 全图智能搜索资源、建筑、小人或百科，直接返回 action-ready 的 `nextActions`。 |
| `oni_game_control` | `act`, `read` | 游戏运行控制：暂停 (0)、调速 (1~3)、即时存档与状态检查。 |
| `oni_server_control` | `read` | 检查游戏内 OniMcp 服务的连通性、工具清单、批处理与运行日志。 |
| `oni_coordinate_control` | `act`, `write` | 坐标辅助网关：当语义目标或指针无法表达时作为最后手段的绝对坐标通道。 |

---

## 安装与装载 (Installation)

在 Cortico 项目根目录或 `extensions/` 目录下，直接通过 GitHub 安装：

```bash
pnpm add -D github:vivy1024/cortico-world-oni
```

或在 `extensions/package.json` 中声明：

```json
{
  "dependencies": {
    "cortico-world-oni": "github:vivy1024/cortico-world-oni"
  }
}
```

随后运行 `pnpm install` 即可自动完成扩展挂载。

---

## 配置示例 (Configuration)

在部署目录（如 `deployments/yushu-live/config.json`）的 `worlds` 段中启用：

```jsonc
{
  "worlds": {
    "oni": {
      "enabled": true,
      "endpoint": "http://localhost:8788/mcp/",
      "pollIntervalSeconds": 3,
      "alertThreshold": "warning"
    }
  }
}
```

- `endpoint`：游戏内 OniMcp 模组开放的 HTTP MCP 端点（默认端口 `8788`）；
- `pollIntervalSeconds`：轮询殖民地警报与突发事件的间隔（秒）；
- `alertThreshold`：事件上报过滤级别（`info` / `warning` / `critical`）。

---

## 配套游戏模组 (Prerequisites)

本扩展依赖在《缺氧》游戏客户端中安装并运行 **OniMcp** (基于 OniMods 的 C# 模组)：
1. 将 `OniMcp.dll` 及模组配置部署至《缺氧》本地模组目录；
2. 启动游戏并加载存档，模组将自动在本地后台启动 `http://localhost:8788/mcp/` 服务；
3. Cortico 启动后将自动完成 MCP 握手并同步工具定义。若游戏尚未启动，扩展将以优雅降级模式等待重连。

---

## 开发与测试 (Development)

```bash
corepack pnpm install
pnpm test        # 运行 Vitest 单元测试
pnpm typecheck   # 运行 TypeScript 类型检查
```

在 Cortico 框架根目录下进行官方契约验证：
```bash
pnpm check:extension ../cortico-world-oni
```

---

## 许可证 (License)

[MIT](LICENSE)