Клиент: начальный импорт кодовой базы

Основа — Horizon (MIT). История апстрима не переносится: этот репозиторий ведёт свою.
2026-10-29 22:04:28 +03:00
commit 874b6f20c2
3414 changed files with 1071219 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Agent control API
+
+How a program drives a running game: an AI agent through MCP, a script through `horizon-ctl`, a test through the
+control socket. Design and inventory: [agent-control.md](../agent-control.md); for players:
+[playhorizon.dev/docs/agents](https://playhorizon.dev/docs/agents).
+
+## Overview
+
+The game listens on a local control socket (a Unix socket, or localhost TCP with a token on Windows), takes one
+command per text line and answers one JSON line. `horizon-ctl` wraps it: it starts the game, sends commands and
+serves the same commands as MCP tools. The launcher's MCP server offers them too, as `game_<tool>`.
+
+| | Count |
+| --- | --- |
+| `horizon-ctl` commands | 96, in 8 groups (session, observe, move and look, act, screens and chat, multiplayer, world and cheats, scripting and benchmarks) |
+| MCP tools | 88 (8 commands are CLI only) |
+| Destructive commands (need `--confirm`) | 3 |
+| Command names the game's socket answers | about 160, test hooks included (`horizon-ctl help --game`) |
+
+## Guide
+
+1. Build `horizon-ctl` (`cargo build --profile fast -p horizon-client`), then
+   `horizon-ctl --socket $PWD/ctl.sock launch --world W --creative --wait --resources <prepared files>`.
+2. `horizon-ctl --socket … state`, `keys`, `turn`, `command`, `screenshot`, `quit`.
+3. For an agent: `horizon-ctl mcp`, or the launcher's `horizon-launcher mcp` with `agent-config` to connect a client
+   ([launcher-commands.md](../launcher-commands.md)).
+
+## Reference
+
+[horizon-ctl-commands.md](../horizon-ctl-commands.md), generated from the command table in
+`crates/horizon-client/src/bin/horizon-ctl/commands.rs`: every command, its MCP tool and its arguments.
+
+## Examples
+
+- `tools/agent_control_e2e.py`: starts a game and drives it end to end through `horizon-ctl` and MCP.
+- `tools/lan_e2e.py`: two games over LAN, both driven through their sockets.
+
+## Stability
+
+Preview ([stability.md](stability.md)). The commands in `horizon-ctl`'s table and their MCP tool names are what the
+API offers; the other commands the game's socket answers are test hooks and experimental.
+
+## Not there yet
+
+- **A version.** A `hello` command that answers the protocol version, the game's release and the features it has;
+  MCP `serverInfo` carries the same version; `horizon-ctl` refuses a game whose major it doesn't speak.
+- **Reply schemas.** Each command's reply described in the table (fields, types, units), so the reference documents
+  replies as well as arguments and MCP tools declare an output schema.
+- **Events as a stream.** `events --since` polls today; a subscription that pushes events as they happen.
+- **Test hooks apart.** The hooks only harnesses use move under their own prefix, out of the agent's tool list.
+- **Compatibility tests.** A transcript per protocol version: commands and the reply keys each must keep.
+
+## Changelog
+
+- Unversioned so far: the command table and the generated reference are the contract.