Русский · English · Español · 中文 · Português

«Espaço Agora» — API do agente

Esta página é para agentes de IA (e para as pessoas que os usam). Ela explica como um agente se conecta a uma página «Espaço Agora» ativa (known.html) no navegador de uma pessoa e o que ele pode fazer ali: tudo o que a interface faz — abrir qualquer objeto, mover a câmera, avançar o tempo, alternar camadas e filtros, modo astronauta, encontrar eclipses e desfiles de planetas, contar um roteiro com voz e legendas, exibir imagens próprias, gravar vídeo, ler erros. A renderização acontece no navegador da pessoa (WebGL na GPU dela); o agente envia comandos e recebe respostas e capturas de tela.

1. Pareamento

1. A pessoa abre o site e pressiona o botão redondo 🤖 (canto inferior direito, acima do astronauta) — a barra do agente se abre; «Ligar o agente» mostra um código (20 caracteres, ex.: r4fxjbjsxdy6ex3pf4hd). O código é a senha: quem o tem controla esta aba. 🤖 apenas oculta/mostra a barra, a conexão permanece; «Desconectar» na barra a desliga. A barra sempre tem 📂 (abrir um arquivo de roteiro ou salvar o exibido — também sem agente) e «MCP ↗» (esta página).
2. A pessoa entrega o código ao agente. O agente chama connect com ele.
3. Conexão permanente (opcional): na página — 📌 «Lembrar» na barra do agente (o código fica neste navegador, o site se conecta sozinho toda vez que abre); o agente — connect com save: true (código em ~/.orbit-agent.json, o MCP conecta ao iniciar). Depois disso, basta abrir o site. Para esquecer: desafixe 📌 e chame forget.
4. «Desconectar» na página (ou a saída do agente) encerra a sessão; a página então devolve camadas e interface ao estado anterior ao agente, para a música, a voz, as legendas, as imagens e os cenários, e remove locais de pouso (sites), desenhos e marcas (draw, mark, flybys), janelas de mídia e corpos próprios (spawn) — independentemente de onstop. A câmera, o tempo e a seleção também voltam (por padrão; onstop {restore: false} — manter o que o agente mostrou). Exceção: play / story run com detach: true — a apresentação toca até o fim e só então é revertida.

O som (voz, música) só começa depois que a pessoa clicou na página ao menos uma vez — regra do navegador. A voz vem desligada por padrão: a pessoa a liga com 🔊 na barra do agente (fica lembrado); as legendas são sempre exibidas.

Checklist da apresentação — faça sempre

[
  {"cmd":"onstop","args":{"restore":true}},        // primeiro passo: ao terminar, com Esc ou ✕ tudo volta
  {"cmd":"reset"},
  {"cmd":"view","args":{"on":["oplanets"]}},        // só as camadas necessárias: satélites, naves, órbitas, constelações desligados
  {"cmd":"hideUi","args":{"on":true,"labels":false}},
  {"cmd":"time","args":{"at":"<moment>","rate":0}}, // defina o tempo você mesmo; rate 0 — a iluminação não se desloca
  … voo (fly) …
  … a apresentação …
]

• Não confie nos padrões: defina camadas, tempo, câmera e interface explicitamente.
• Uma vista definida com view (ou o campo on de um roteiro) é mantida por show (keepView: false — as camadas do evento). fly, camera, sites, time não mexem nas camadas; galaxy, scene e ambient definem a própria vista — chame view de novo depois deles, se necessário.
• Depois da apresentação a cena deve ficar como antes: onstop {restore: true} mais a remoção das suas próprias coisas — sites {on: false}, flybys {on: false}, draw {clear: true}, image {clear: true}, media {close: true}. Quando o agente sai, elas são removidas de qualquer forma.
• Confira o quadro com screenshot antes de dizer à pessoa «olhe».
• A caption fica no canto inferior esquerdo: mantenha title curto, ponha textos longos em sub e text.
• Um passo com falha em play vai para logs (nível error), para play sem argumentos (lastError: {step, cmd, error}) e para o player como «⚠ passo N». Um comando desconhecido nos passos é um erro imediato, antes do início.

2. Transporte

Os dois lados se conectam a uma sala de retransmissão no mesmo site: wss://<site>/agent/<code>?r=agent (a página usa ?r=page). A sala encaminha mensagens entre os dois; nada é armazenado. Mensagens JSON:

agent → page   { "id": 1, "cmd": "go", "args": { "search": "?o=Mars" } }
page  → agent  { "id": 1, "ok": true, "result": … }   |   { "id": 1, "ok": false, "error": "…" }
room  → both   { "sys": "peer", "on": true|false }      (o outro lado entrou / saiu)
keepalive      envie { "sys": "ping" } a cada 30 s, a sala responde { "sys": "pong" }

Uma conexão por papel (um novo agente com o mesmo código substitui o antigo, código de fechamento 4000 — não reconecte nesse caso). Mensagens de até 4 MB. Sites: https://space.bl2.ru, https://space.bl2.net (o mesmo site, ru/en por padrão).

3. Servidor MCP

Servidor MCP pronto (stdio): scripts/agent-mcp.mjs no repositório orbit-proto (Node ≥ 20, dependência ws). Cada comando abaixo é uma ferramenta de mesmo nome (hide_ui → comando da página hideUi), além de connect, disconnect, help (esta página como texto; lang: en). Arquivos: image recebe path, record salva em path, screenshot retorna uma imagem.

{ "mcpServers": { "orbit-space": { "command": "node", "args": ["scripts/agent-mcp.mjs"] } } }

Env: AGENT_SITE — site padrão, AGENT_CODE — conectar na inicialização.

Conexão sem o servidor MCP (agentes na nuvem)

• Muitos agentes rodam em sandboxes na nuvem cuja rede de saída é limitada a uma lista de permissões, então wss://space.bl2.ru pode ficar inacessível. Solução: abra o WebSocket de qualquer aba do navegador em space.bl2.ru (esta página de ajuda, por exemplo) e envie os comandos de lá. Teste de conexão: {"sys":"ping"} → {"sys":"pong"}.
• O agente sair = play para e a cena é revertida. Um agente com sessões curtas (as ferramentas de navegador permitem ~45 s por chamada) envia a apresentação com detach: true — play {steps, detach: true} ou story {action: 'run', story, detach: true} — e retorna na hora: a página toca a apresentação sozinha e reverte (com onstop) quando ela termina. Sem detach, mantenha o socket aberto até o cenário terminar.
• Dê a cada comando seu próprio timeout (digamos, 8 s): caso contrário, um comando sem resposta trava a chamada inteira.

// «iniciar e retornar» — do console de uma aba em space.bl2.ru (ou Node ≥ 22)
const code = '<code>', ws = new WebSocket(`wss://space.bl2.ru/agent/${code}?r=agent`);
let id = 0; const wait = new Map();
const cmd = (name, args = {}, ms = 8000) => new Promise((res, rej) => {
  const i = ++id, t = setTimeout(() => (wait.delete(i), rej(new Error('timeout ' + name))), ms);
  wait.set(i, (m) => (clearTimeout(t), m.ok ? res(m.result) : rej(new Error(m.error))));
  ws.send(JSON.stringify({ id: i, cmd: name, args }));
});
ws.onmessage = (e) => { const m = JSON.parse(e.data); if (!m.sys) wait.get(m.id)?.(m), wait.delete(m.id); };
ws.onopen = async () => {
  await cmd('onstop', { restore: true });
  await cmd('play', { detach: true, onError: 'skip', steps: [
    { cmd: 'reset' },
    { cmd: 'view', args: { on: ['oplanets'] } },
    { cmd: 'hideUi', args: { on: true, labels: false } },
    { cmd: 'fly', args: { name: 'Saturn', size: 0.5, lit: true }, wait: 6500 },
    { cmd: 'caption', args: { title: 'Saturn', sub: '1,4 bilhão de km do Sol' }, wait: 8000 },
  ] });
  ws.close(); // a apresentação continua sozinha e depois recoloca tudo no lugar
};

4. Comandos

Observação e estado

Vista, câmera, tempo, camadas

Eventos (calculados pela página, sem precisar de fórmulas)

Interface inteira

Contar um roteiro

Um ponto de entrada: WS, MCP, console, roteiro

Os comandos e a linguagem são os mesmos, venham de onde vierem: WebSocket de qualquer linguagem, MCP, o console da página (o botão >_ na barra do agente) ou um roteiro. Escreva um cenário inteiro e entregue a story, ou chame os comandos um a um. Novidade: exec {steps} — executa passos da linguagem agora (as variáveis persistem entre chamadas), expr {e} — avalia uma expressão, js {code, timeout} — JavaScript em sandbox (iframe isolado + Web Worker: sem DOM, cookies ou rede; dentro — await cmd(name, args), await expr('…'), log(), sleep(), return).

Console: fly Mars size=0.6 (um comando, a primeira palavra é o nome), um comando JSON, passos {…} / […], uma expressão = …, código js ….

Script base — Node.js:

// node agent.mjs <código>   (Node ≥ 22 — WebSocket embutido)
const code = process.argv[2], ws = new WebSocket(`wss://space.bl2.ru/agent/${code}?r=agent`);
let id = 0; const wait = new Map();
const cmd = (name, args = {}) => new Promise((res, rej) => {
  const i = ++id; wait.set(i, { res, rej }); ws.send(JSON.stringify({ id: i, cmd: name, args }));
});
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.sys) return;                                   // peer / pong
  const w = wait.get(m.id); wait.delete(m.id);
  m.ok ? w.res(m.result) : w.rej(new Error(m.error));
};
setInterval(() => ws.send('{"sys":"ping"}'), 30000);
ws.onopen = async () => {
  await cmd('fly', { name: 'Mars', size: 0.6, lit: true });
  console.log(await cmd('expr', { e: "round(au(get('Mars','sun')),3)" }));
  await cmd('exec', { steps: [{ wait: "dist('camera','Mars') < 1e5 km" }, { cmd: 'caption', args: { title: 'Mars' } }] });
  process.exit(0);
};

Python:

# python agent.py <código>    (pip install websockets)
import asyncio, json, sys, websockets
async def main(code):
    async with websockets.connect(f"wss://space.bl2.ru/agent/{code}?r=agent") as ws:
        n = 0
        async def cmd(name, **args):
            nonlocal n; n += 1
            await ws.send(json.dumps({"id": n, "cmd": name, "args": args}))
            while True:
                m = json.loads(await ws.recv())
                if m.get("id") == n:
                    if not m["ok"]: raise RuntimeError(m["error"])
                    return m["result"]
        await cmd("fly", name="Saturn", size=0.6, lit=True)
        print(await cmd("expr", e="get('Saturn','moons')"))
asyncio.run(main(sys.argv[1]))

Linguagem de cenário v2

Versões: um roteiro sem v (ou v: 1) — passos e slides como acima; v: 2 — uma linguagem com condições. Uma nova versão do manipulador nunca altera as antigas.

{ "v": 2, "title": "…", "on": ["oplanets"], "vars": { "n": 0 }, "steps": [
  { "cmd": "fly", "args": { "name": "Mars", "size": 0.5, "lit": true } },
  { "wait": "dist('camera', 'Mars') < 50000 km", "timeout": 20 },
  { "set": { "n": "n + 1" } },
  { "if": "visible('Mars')", "then": [ { "cmd": "caption", "args": { "title": "Mars", "sub": "{round(au(dist('camera','Sun')),3)} UA do Sol" } } ] },
  { "repeat": 2, "do": [ { "wait": 1 } ] }
] }

Passos: {cmd, args, wait} (wait — ms ou uma expressão), {wait: expression | seconds, timeout}, {if, then, else}, {repeat: n | expression, do}, {set: {name: expression}}, {on: [...]}. Expressões — sem eval: números com unidades km au ly m, strings '…', variáveis, + - * / %, < > <= >= == !=, && || !; funções dist(a, b) ('camera' ou um corpo, km), visible(body), elapsed(), time(), camdist(), au(x), ly(x), round(x, d), abs min max. Propriedades na hora: get(body | 'camera', 'prop') — um corpo tem name, kind, radius, parent, moons, x y z, sun (km do Sol), earth, camera (km da câmera), center, visible; a câmera tem dist, yaw, pitch, fov, x y z, sun, center; sem prop — o objeto inteiro. O resultado de um comando em uma variável: {cmd, args, as: 'r'}, um campo — field(r, 'rows.0.text'), tamanho — count(x). Em strings de args — {expression}. Os erros vão para logs. A seguir: gatilhos (when/once/every) e um sandbox (spawn de corpos e modelos 3D). Funções próprias: {def: name, params, e} — em expressões, {def, params, steps} — como um passo {call, args, as}, {local}, {return}; em um roteiro — funcs. Mais funções: angle(a, b) — graus entre as direções a partir da câmera, edge(a, b) — quantos graus a aparece além do limbo de b, sin cos (graus), pow sqrt. wait: true em um comando — até ele terminar. Para cenas: fitdist(r[, margin]) — a distância a partir da qual um círculo de raio r km cabe na tela (lado menor; um corpo também tem day — período de rotação, s); satcount('all' | 'active' | 'debris' | 'rb' | 'dead') — objetos do catálogo ao redor da Terra; mstat(craft, 'launch' | 'km' | 'turns' | 'rmin' | 'rnow' | 'flybys') — números da missão a partir de sua trajetória, até hoje. As trajetórias de naves e os sobrevoos vêm da importação (scripts/fetch-missions.mjs, JPL Horizons, diária): uma nova nave na base recebe seus sobrevoos e números automaticamente; flybys {craft} desenha os pontos de sobrevoo em seu caminho. Mídia em cenas: media {url | file, title, x, y, w, h, volume, loop, start, id} — uma janela com áudio ou vídeo: um link de mp3/vídeo ou YouTube; file — um arquivo do computador da pessoa (o site não guarda arquivos: a pessoa o escolhe na janela e então ele toca offline); close: true fecha as janelas. Estado: remember {name} — salva a câmera, o tempo, a vista e a interface; recall {name} — traz de volta; onstop {restore: true} (em um arquivo de roteiro — o campo "onstop": "restore") — ao terminar, com Esc ou ✕, recoloca tudo como antes do início. Avise a pessoa: roteiros e a proteção de tela podem ser controlados por um controle remoto — um apresentador de slides (PageDown/PageUp, «.» ou B — tela preta), teclas de mídia de teclados, fones e TV boxes (próximo, anterior, pausa), um gamepad (D-pad ←/→, A — pausa, B — tela preta), setas do teclado, Space, Esc. Links diretos: ?ambient — a proteção de tela, ?ambient=<scene code from ☰> — começando por aquela cena (p. ex. ?ambient=landings:Moon:apollo), ?story=<id>&step=N ou &slide=N — um roteiro publicado a partir daquele ponto; o botão 🔗 no player copia um link para o que está tocando. O comando ambient {play: code} faz o mesmo a partir de um agente; reset zera câmera, tempo e vista antes de uma cena.

Câmera e movimento

Mostrar um corpo pequeno (um cometa, um objeto interestelar — invisível a dezenas de milhões de km): follow {name} ou fly {name}, depois mark {name, label: true} — um marcador multicolorido piscante no corpo (visível também com hideUi; também color, speed), select {name} — o caminho dele fica brilhante. Remover: mark {remove: name} ou mark {clear: true}, select {name: ''}; a reversão do onstop e a saída do agente removem as marcas sozinhas.

Suavização ease — como uma função de temporização CSS: linear, ease, ease-in, ease-out, ease-in-out, smooth, cubic-bezier(x1,y1,x2,y2) ou uma fórmula de t (0…1): 1-pow(1-t,2), t*t*t*(t*(6*t-15)+10).

Sobreposição: {cmd, args, then: [steps], before_end: ms | after_begin: ms | when: "condition"} — os passos aninhados rodam junto com o comando. Exemplo: orbitar a Terra, voltar-se para Io, voar até ela:

[ {"cmd": "fly", "args": {"name": "Earth", "size": 0.4, "rel": {"to": "sun", "deg": 0, "elev": 10}, "ms": 3000, "ease": "ease-in-out"}, "wait": true},
  {"cmd": "orbit", "args": {"speed": 60, "ms": 6000, "ease": "ease-in"},
   "when": "edge('Io','Earth') < 15", "then": [{"cmd": "look", "args": {"to": "Io", "ms": 1500}, "wait": true}], "wait": true},
  {"cmd": "fly", "args": {"name": "Io", "size": 0.15, "rel": {"to": "Jupiter", "deg": 180, "elev": 15}, "ms": 8000, "ease": "ease-out"}, "wait": true} ]

Sandbox, desenho, astronauta

Console da página — a tecla crase (ё no layout russo).

Como trabalhar

1. Leia esta página (help), faça connect com o código.
2. Peça dados à página: search / open (objetos), body (tamanhos, lado iluminado), where (posições), find (eventos), layers, state.
3. Prepare as ações a partir desses dados: um cenário play, ou um deck de slides que a pessoa percorre, ou buttons.
4. Execute; confira com screenshot e logs; ajuste.

5. Exemplo: «conte-me sobre os planetas»

connect {code}
layers → layer {key, visible:false} for everything except oplanets
music {theme: 0, volume: 0.4};  hide_ui {on: true}
play {steps: [
  {cmd:"fly", args:{name:"Mars"}, wait: 3800},
  {cmd:"camera", args:{yaw: …, pitch: …, dist: …, ms: 3000}, wait: 3200},   // valores de body {name:"Mars"}
  {cmd:"say", args:{title:"Mars", sub:"228 million km · light takes 13 min", text:"…", audio:"mars.mp3"}, wait: "speech"}, // a voz é Piper no navegador (ru ruslan, en amy); audio — um mp3 pronto no lugar dela
  …
]}

6. Recursos

• Corpos: Sol, 8 planetas com luas, planetas anões, ~1,4 M de asteroides (por grupos de tamanho), cometas, naves interplanetárias, ~30 000 satélites da Terra (CelesTrak, diário), constelações em 3D, modelo da Via Láctea com nebulosas e aglomerados, 44 000 galáxias (2MRS).
• Os nomes funcionam em russo e inglês (Марс / Mars); as posições são equatoriais J2000, km.
• Intervalo de tempo: qualquer data (as efemérides pioram longe de hoje; satélites só ±90 dias do catálogo).
• Links de compartilhamento (?o=…&d=…&v=…&t=…) abrem a mesma vista para qualquer pessoa.

Regras: a página aceita somente esses comandos; sem navegação para outros sites, sem dados pessoais. Mantenha a pessoa no controle — ela pode pressionar «Desconectar» a qualquer momento.