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

«Espacio ahora» — API de agente

Esta página es para agentes de IA (y sus humanos). Explica cómo un agente se conecta a una página «Espacio ahora» en vivo (known.html) en el navegador de una persona y qué puede hacer allí: todo lo que puede hacer la interfaz — abrir cualquier objeto, mover la cámara, avanzar el tiempo, cambiar capas y filtros, modo astronauta, buscar eclipses y desfiles de planetas, contar una historia con voz y subtítulos, mostrar sus propias imágenes, grabar vídeo, leer errores. El renderizado ocurre en el navegador de la persona (WebGL en su GPU); el agente envía comandos y recibe respuestas y capturas de pantalla.

1. Emparejamiento

1. La persona abre el sitio y pulsa el botón redondo 🤖 (abajo a la derecha, encima del astronauta): se abre la barra del agente; «Encender el agente» muestra un código (20 caracteres, p. ej. r4fxjbjsxdy6ex3pf4hd). El código es el pase: quien lo tiene controla esta pestaña. 🤖 solo oculta/muestra la barra, la conexión se mantiene; «Desconectar» en la barra la apaga. La barra siempre tiene 📂 (abrir un archivo de historia o guardar la mostrada — también sin agente) y «MCP ↗» (esta página).
2. La persona da el código al agente. El agente llama a connect con él.
3. Conexión permanente (opcional): en la página — 📌 «Recordar» en la barra del agente (el código se queda en este navegador, el sitio se conecta solo cada vez que se abre); el agente — connect con save: true (código en ~/.orbit-agent.json, MCP se conecta al iniciar). Después, basta con abrir el sitio. Para olvidar: desactivar 📌 y llamar a forget.
4. «Desconectar» en la página (o la salida del agente) termina la sesión; entonces la página devuelve las capas y la interfaz a como estaban antes del agente, detiene la música, la voz, los subtítulos, las imágenes y los guiones, y elimina los sitios de aterrizaje (sites), los dibujos y las marcas (draw, mark, flybys), las ventanas multimedia y los cuerpos propios (spawn) — independientemente de onstop. La cámara, el tiempo y la selección también se restauran (por defecto; onstop {restore: false} — conservar lo que mostró el agente). Excepción: play / story run con detach: true — la presentación se reproduce hasta el final y luego se revierte.

El sonido (voz, música) solo empieza después de que la persona haya hecho clic en la página al menos una vez — regla del navegador. La voz está desactivada por defecto: la persona la activa con 🔊 en la barra del agente (se recuerda); los subtítulos siempre se muestran.

Lista de comprobación de la presentación — hazlo siempre

[
  {"cmd":"onstop","args":{"restore":true}},        // primer paso: al terminar, con Esc o ✕ todo vuelve
  {"cmd":"reset"},
  {"cmd":"view","args":{"on":["oplanets"]}},        // solo las capas necesarias: satélites, naves, órbitas, constelaciones apagados
  {"cmd":"hideUi","args":{"on":true,"labels":false}},
  {"cmd":"time","args":{"at":"<moment>","rate":0}}, // fija tú el tiempo; rate 0 — la iluminación no se desplazará
  … vuelo (fly) …
  … la presentación …
]

• No confíes en los valores por defecto: fija capas, tiempo, cámara e interfaz de forma explícita.
• Una vista fijada con view (o el campo on de una historia) la conserva show (keepView: false — las capas del evento). fly, camera, sites, time no tocan las capas; galaxy, scene y ambient fijan su propia vista — llama de nuevo a view después de ellos si hace falta.
• Tras la presentación la escena debe quedar como antes: onstop {restore: true} más eliminar tus propias cosas — sites {on: false}, flybys {on: false}, draw {clear: true}, image {clear: true}, media {close: true}. Cuando el agente se va, se eliminan igualmente.
• Comprueba el encuadre con screenshot antes de decirle a la persona «mira».
• El caption está abajo a la izquierda: mantén title corto, pon el texto largo en sub y text.
• Un paso fallido en play va a logs (nivel error), a play sin argumentos (lastError: {step, cmd, error}) y al reproductor como «⚠ paso N». Un comando desconocido en los pasos es un error inmediato, antes del inicio.

2. Transporte

Ambos lados se conectan a una sala de retransmisión en el mismo sitio: wss://<site>/agent/<code>?r=agent (la página usa ?r=page). La sala reenvía mensajes entre los dos; no se almacena nada. Mensajes 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 }      (el otro lado se unió / salió)
keepalive      envía { "sys": "ping" } cada 30 s, la sala responde { "sys": "pong" }

Una conexión por rol (un agente nuevo con el mismo código reemplaza al anterior, código de cierre 4000 — no te reconectes entonces). Mensajes de hasta 4 MB. Sitios: https://space.bl2.ru, https://space.bl2.net (el mismo sitio, ru/en por defecto).

3. Servidor MCP

Servidor MCP listo para usar (stdio): scripts/agent-mcp.mjs en el repositorio orbit-proto (Node ≥ 20, dependencia ws). Cada comando de abajo es una herramienta del mismo nombre (hide_ui → comando de página hideUi), más connect, disconnect, help (esta página como texto; lang: es). Archivos: image toma path, record guarda en path, screenshot devuelve una imagen.

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

Env: AGENT_SITE — sitio por defecto, AGENT_CODE — conectar al inicio.

Conexión sin el servidor MCP (agentes en la nube)

• Muchos agentes se ejecutan en sandboxes en la nube cuya red saliente está limitada a una lista de permitidos, por lo que wss://space.bl2.ru puede ser inalcanzable. Solución: abre el WebSocket desde cualquier pestaña del navegador en space.bl2.ru (esta página de ayuda, por ejemplo) y envía los comandos desde allí. Comprobación de conexión: {"sys":"ping"} → {"sys":"pong"}.
• La salida del agente = play se detiene y la escena se revierte. Un agente con sesiones cortas (las herramientas de navegador permiten ~45 s por llamada) envía la presentación con detach: true — play {steps, detach: true} o story {action: 'run', story, detach: true} — y vuelve de inmediato: la página reproduce la presentación por sí misma y se revierte (con onstop) al terminar. Sin detach mantén el socket abierto hasta que termine el guion.
• Da a cada comando su propio tiempo de espera (digamos 8 s): de lo contrario un comando sin respuesta cuelga toda la llamada.

// «iniciar y volver» — desde la consola de una pestaña en space.bl2.ru (o 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 billion km from the Sun' }, wait: 8000 },
  ] });
  ws.close(); // la presentación continúa sola y luego lo devuelve todo
};

4. Comandos

Observación y estado

Vista, cámara, tiempo, capas

Eventos (calculados por la página, sin necesidad de fórmulas)

Interfaz completa

Contar una historia

Un único punto de entrada: WS, MCP, consola, historia

Los comandos y el lenguaje son los mismos venga de donde venga: WebSocket desde cualquier lenguaje, MCP, la consola de la página (el botón >_ en la barra del agente) o una historia. Escribe un guion completo y dáselo a story, o llama a los comandos uno por uno. Novedad: exec {steps} — ejecutar pasos del lenguaje ahora (las variables persisten entre llamadas), expr {e} — evaluar una expresión, js {code, timeout} — JavaScript en un sandbox (iframe aislado + Web Worker: sin DOM, cookies ni red; dentro — await cmd(name, args), await expr('…'), log(), sleep(), return).

Consola: fly Mars size=0.6 (un comando, la primera palabra es el nombre), un comando JSON, pasos {…} / […], una expresión = …, código js ….

Guion base — Node.js:

// node agent.mjs <код>   (Node ≥ 22 — WebSocket integrado)
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 <код>    (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]))

Lenguaje de guiones v2

Versiones: una historia sin v (o v: 1) — pasos y diapositivas como arriba; v: 2 — un lenguaje con condiciones. Una nueva versión del manejador nunca cambia las antiguas.

{ "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)} AU from the Sun" } } ] },
  { "repeat": 2, "do": [ { "wait": 1 } ] }
] }

Pasos: {cmd, args, wait} (wait — ms o una expresión), {wait: expression | seconds, timeout}, {if, then, else}, {repeat: n | expression, do}, {set: {name: expression}}, {on: [...]}. Expresiones — sin eval: números con unidades km au ly m, cadenas '…', variables, + - * / %, < > <= >= == !=, && || !; funciones dist(a, b) ('camera' o un cuerpo, km), visible(body), elapsed(), time(), camdist(), au(x), ly(x), round(x, d), abs min max. Propiedades al vuelo: get(body | 'camera', 'prop') — un cuerpo tiene name, kind, radius, parent, moons, x y z, sun (km desde el Sol), earth, camera (km desde la cámara), center, visible; la cámara tiene dist, yaw, pitch, fov, x y z, sun, center; sin prop — el objeto completo. El resultado de un comando a una variable: {cmd, args, as: 'r'}, un campo — field(r, 'rows.0.text'), tamaño — count(x). En las cadenas de args — {expression}. Los errores van a logs. Próximamente: disparadores (when/once/every) y un sandbox (cuerpos propios y modelos 3D). Funciones propias: {def: name, params, e} — en expresiones, {def, params, steps} — como un paso {call, args, as}, {local}, {return}; en una historia — funcs. Más funciones: angle(a, b) — grados entre direcciones desde la cámara, edge(a, b) — cuántos grados sobresale a por el limbo de b, sin cos (grados), pow sqrt. wait: true en un comando — hasta que termine. Para escenas: fitdist(r[, margin]) — la distancia desde la que un círculo de radio r km cabe en la pantalla (lado estrecho; un cuerpo también tiene day — periodo de rotación, s); satcount('all' | 'active' | 'debris' | 'rb' | 'dead') — objetos del catálogo alrededor de la Tierra; mstat(craft, 'launch' | 'km' | 'turns' | 'rmin' | 'rnow' | 'flybys') — cifras de una misión según su trayectoria, a fecha de hoy. Las trayectorias de naves y los sobrevuelos vienen de la importación (scripts/fetch-missions.mjs, JPL Horizons, diaria): una nave nueva en la base obtiene sus sobrevuelos y cifras automáticamente; flybys {craft} dibuja los puntos de sobrevuelo en su trayectoria. Multimedia en escenas: media {url | file, title, x, y, w, h, volume, loop, start, id} — una ventana con audio o vídeo: un enlace mp3/vídeo o YouTube; file — un archivo del ordenador de la persona (el sitio no almacena archivos: la persona lo elige en la ventana, luego se reproduce sin conexión); close: true cierra las ventanas. Estado: remember {name} — guardar la cámara, el tiempo, la vista y la interfaz; recall {name} — recuperarlo; onstop {restore: true} (en un archivo de historia — el campo "onstop": "restore") — al terminar, con Esc o ✕ todo vuelve a como estaba antes del inicio. Díselo a la persona: las historias y el salvapantallas se pueden manejar con un mando a distancia — un puntero de presentaciones (PageDown/PageUp, «.» o B — pantalla negra), teclas multimedia de teclados, auriculares y TV boxes (siguiente, anterior, pausa), un gamepad (cruceta ←/→, A — pausa, B — pantalla negra), flechas del teclado, Space, Esc. Enlaces directos: ?ambient — el salvapantallas, ?ambient=<scene code from ☰> — empezando por esa escena (p. ej. ?ambient=landings:Moon:apollo), ?story=<id>&step=N o &slide=N — una historia publicada desde ese punto; el botón 🔗 del reproductor copia un enlace a lo que se está reproduciendo. El comando ambient {play: code} hace lo mismo desde un agente; reset restablece cámara, tiempo y vista antes de una escena.

Cámara y movimiento

Mostrar un cuerpo pequeño (un cometa, un objeto interestelar — invisible desde decenas de millones de km): follow {name} o fly {name}, luego mark {name, label: true} — un marcador multicolor parpadeante en el cuerpo (visible también con hideUi; también color, speed), select {name} — su trayectoria brillante. Quitar: mark {remove: name} o mark {clear: true}, select {name: ''}; la reversión de onstop y la salida del agente eliminan las marcas por sí solas.

Suavizado ease — como una función de temporización CSS: linear, ease, ease-in, ease-out, ease-in-out, smooth, cubic-bezier(x1,y1,x2,y2) o una fórmula de t (0…1): 1-pow(1-t,2), t*t*t*(t*(6*t-15)+10).

Solapamiento: {cmd, args, then: [steps], before_end: ms | after_begin: ms | when: "condition"} — los pasos anidados se ejecutan junto con el comando. Ejemplo: orbitar la Tierra, girar hacia Ío, volar hasta él:

[ {"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, dibujo, astronauta

Consola de la página — la tecla de acento grave (ё en la distribución rusa).

Cómo trabajar

1. Lee esta página (help), connect con el código.
2. Pide datos a la página: search / open (objetos), body (tamaños, lado iluminado), where (posiciones), find (eventos), layers, state.
3. Prepara las acciones a partir de esos datos: un guion play, o un deck de diapositivas que la persona recorre, o buttons.
4. Ejecútalo; comprueba con screenshot y logs; ajusta.

5. Ejemplo: «cuéntame sobre los 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"}, // la voz es Piper en el navegador (ru ruslan, en amy); audio — un mp3 ya hecho en su lugar
  …
]}

6. Recursos

• Cuerpos: el Sol, 8 planetas con lunas, planetas enanos, ~1,4 M de asteroides (por grupos de tamaño), cometas, naves interplanetarias, ~30 000 satélites terrestres (CelesTrak, diario), constelaciones en 3D, modelo de la Vía Láctea con nebulosas y cúmulos, 44 000 galaxias (2MRS).
• Los nombres funcionan en ruso e inglés (Марс / Mars); las posiciones son ecuatoriales J2000, km.
• Rango de tiempo: cualquier fecha (las efemérides se degradan lejos de hoy; los satélites solo ±90 días respecto al catálogo).
• Los enlaces para compartir (?o=…&d=…&v=…&t=…) abren la misma vista para cualquiera.

Reglas: la página acepta solo estos comandos; sin navegación a otros sitios, sin datos personales. Mantén a la persona al control — puede pulsar «Desconectar» en cualquier momento.