mirror of
https://github.com/storytold/AniCraft.git
synced 2026-11-19 09:01:29 +01:00
111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
# The live control port
|
|
|
|
`anicraft --control <port>` opens the AniCraft window as usual and also listens on a port on this
|
|
computer, so an assistant (or a script) can edit the open document while you watch. Every edit
|
|
appears in the window at once and undoes with Ctrl+Z, like your own. The status bar says
|
|
"Remote control on (port N)" while it is open. ADR 0104 records the design.
|
|
|
|
Most people never speak this protocol themselves: AI assistants reach it through
|
|
`anicraft-cli mcp --bridge <port>` (see `docs/mcp.md`).
|
|
|
|
```sh
|
|
anicraft --control 9878 # 9878 by convention
|
|
ANICRAFT_CONTROL_PORT=9878 anicraft # the same; --control wins over the variable
|
|
```
|
|
|
|
## Transport
|
|
|
|
* TCP on `127.0.0.1` only.
|
|
* One JSON object per line (UTF-8, `\n`; a `\r` before it is ignored), each way.
|
|
* Connections stay open; requests on one connection are answered in order.
|
|
|
|
## Authentication
|
|
|
|
Each run makes a fresh token: 64 hex digits from the operating system's random numbers. The app
|
|
writes it to `control.json` in AniCraft's settings folder:
|
|
|
|
| System | File |
|
|
|---|---|
|
|
| Windows | `%APPDATA%\AniCraft\control.json` |
|
|
| macOS | `~/Library/Application Support/AniCraft/control.json` |
|
|
| Linux | `$XDG_CONFIG_HOME/anicraft/control.json` (default `~/.config/anicraft/`) |
|
|
|
|
```json
|
|
{"port": 9878, "token": "3f1c…", "pid": 12345, "version": "0.2.1"}
|
|
```
|
|
|
|
On macOS and Linux the file is readable only by you; on Windows the settings folder already is.
|
|
It is made new when AniCraft starts with `--control` (an older file, or a link left under its
|
|
name, is removed first and never written through) and removed when AniCraft closes. A program
|
|
running as you finds the token there, with nothing to copy into its settings.
|
|
|
|
A portable AniCraft keeps `control.json` in its own data folder, like its other settings. Tell
|
|
the bridge where that is with `ANICRAFT_CONTROL_FILE=<path to control.json>`.
|
|
|
|
A connection has 10 seconds to send its first request with the right token; after that it may
|
|
stay idle. At most 16 connections are open at once. The port closes with the window.
|
|
|
|
If `ANICRAFT_CONTROL_TOKEN` is set, it is the token instead (set it for both the app and the
|
|
client: CI, power users).
|
|
|
|
Every request carries `"token"`. A missing or wrong token gets an error and the connection
|
|
closes before anything runs.
|
|
|
|
## Requests and replies
|
|
|
|
```json
|
|
{"id": 1, "token": "…", "method": "hello"}
|
|
{"id": 1, "ok": true, "result": {"app": "AniCraft", "version": "0.2.1", "protocol": 1}}
|
|
```
|
|
|
|
`id` is any JSON value and comes back as it was. A reply is `{"id", "ok": true, "result"}` or
|
|
`{"id", "ok": false, "error": "message"}`.
|
|
|
|
| Method | Params | Result |
|
|
|---|---|---|
|
|
| `hello` | | `{app, version, protocol}` |
|
|
| `tools.list` | | the tools, exactly as MCP `tools/list` lists them (`docs/mcp.md`) |
|
|
| `tools.call` | `{name, arguments}` | exactly what MCP `tools/call` returns: `{content: […], isError}` |
|
|
|
|
`tools.call` runs the same code as the headless MCP server. A tool that fails (a command's error)
|
|
is a result with `"isError": true`; a malformed call (an unknown tool, a missing `name`) is an
|
|
`"ok": false` reply.
|
|
|
|
```json
|
|
{"id": 2, "token": "…", "method": "tools.call", "params": {"name": "anicraft_run", "arguments": {"command": "draw.rect", "params": {"x": 10, "y": 10, "w": 50, "h": 50}}}}
|
|
{"id": 2, "ok": true, "result": {"content": [{"type": "text", "text": "{\"frame\": 0, \"result\": {…}, \"revision\": 3, \"scene\": 0}"}], "isError": false}}
|
|
```
|
|
|
|
## When calls run
|
|
|
|
The window runs calls at the start of a frame, so an edit shows in that frame. It never takes
|
|
keyboard focus and doesn't need to be the front window. An edit made while the start screen is showing closes it, so you see
|
|
the document it changed.
|
|
|
|
While you are dragging (or a plug-in dialog is previewing), calls that could change the document
|
|
wait until you let go, so your drag and the assistant's edit stay separate undo steps. Calls that
|
|
only read run at once. If you were typing in a field, your change is kept as its own undo step
|
|
first. A call that waited 60 seconds is not run, and its reply says so.
|
|
|
|
Commands that would lose work or replace a file still need `"confirm": true` (ADR 0004).
|
|
|
|
## Limits
|
|
|
|
| | |
|
|
|---|---|
|
|
| Line length | 4 MiB; a longer line gets an error and the connection closes |
|
|
| Connections | 16 at once; another gets an error line and is closed |
|
|
| Waiting | 60 s per call |
|
|
| First line | must be a JSON object with a string `"method"`, or the connection closes (this also refuses a web page's request to localhost) |
|
|
|
|
## Trying it by hand
|
|
|
|
With AniCraft open with `--control 9878`, in PowerShell:
|
|
|
|
```powershell
|
|
$t = (Get-Content "$env:APPDATA\AniCraft\control.json" | ConvertFrom-Json).token
|
|
$c = New-Object Net.Sockets.TcpClient 127.0.0.1, 9878
|
|
$w = New-Object IO.StreamWriter $c.GetStream(); $r = New-Object IO.StreamReader $c.GetStream()
|
|
$w.WriteLine("{""id"":1,""token"":""$t"",""method"":""hello""}"); $w.Flush(); $r.ReadLine()
|
|
```
|