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

«Космос сейчас» — API для агентов

Эта страница — для ИИ-агентов (и их людей). Здесь описано, как агент подключается к живой странице «Космоса сейчас» (known.html) в браузере человека и что он там может: всё, что умеет интерфейс, — открыть любой объект, вести камеру, крутить время, включать слои и фильтры, режим космонавта, искать затмения и парады планет, рассказывать голосом с подписями, показывать свои картинки, писать видео, читать ошибки. Рисует браузер человека (WebGL на его видеокарте); агент шлёт команды и получает ответы и снимки.

1. Подключение

1. Человек открывает сайт и нажимает круглую кнопку 🤖 (справа внизу, над космонавтом) — открывается полоска агента; в ней «Включить агента» — появляется код (20 знаков, например r4fxjbjsxdy6ex3pf4hd). Код — это пропуск: у кого он есть, тот управляет этой вкладкой. 🤖 только прячет/показывает полоску, связь остаётся; выключить — «Отключить» в полоске. В полоске всегда есть 📂 (открыть файл сюжета или сохранить показанный — и без агента) и «MCP ↗» (эта справка).
2. Человек даёт код агенту. Агент вызывает connect с этим кодом.
3. Постоянное соединение (по желанию): на странице — 📌 «Помнить» в плашке агента (код хранится в этом браузере, сайт подключается сам при каждом открытии), агент — connect с save: true (код в файле ~/.orbit-agent.json, MCP подключается сам при запуске). Дальше достаточно открыть сайт. Забыть: снять 📌 и forget.
4. «Отключить» на странице (или уход агента) завершает сеанс: страница возвращает слои и интерфейс, как было до агента, глушит музыку и голос, убирает подписи, картинки, места посадок (sites), рисунки и метки (draw, mark, flybys), окна медиа, свои тела (spawn), останавливает сценарий и запись — независимо от onstop. Возвращаются и камера, время, выбор (по умолчанию; onstop {restore: false} — оставить, как показал агент). Исключение — play / story run с detach: true: показ доигрывает, откат — по его концу.

Звук (голос, музыка) — только после того, как человек хотя бы раз щёлкнул по странице: так требует браузер. Голос по умолчанию выключен: человек включает его сам — 🔊 в плашке агента (запоминается); подписи видны всегда.

Чек-лист показа — делай всегда

[
  {"cmd":"onstop","args":{"restore":true}},        // первым шагом: по концу, Esc или ✕ всё вернётся
  {"cmd":"reset"},
  {"cmd":"view","args":{"on":["oplanets"]}},        // только нужные слои: спутники, аппараты, орбиты, созвездия — выключены
  {"cmd":"hideUi","args":{"on":true,"labels":false}},
  {"cmd":"time","args":{"at":"<момент>","rate":0}}, // время задавай сам; rate 0 — свет не уедет
  … перелёт (fly) …
  … показ …
]

• Не полагайся на умолчания: слои, время, камеру и интерфейс задавай явно.
• Вид, заданный view (или полем on сюжета), show не сбрасывает (keepView: false — слои как у события). fly, camera, sites, time слоёв не трогают; galaxy, scene и ambient ставят свой вид — после них задай view снова, если нужно.
• После показа сцена должна быть как до него: onstop {restore: true} плюс сними своё — sites {on: false}, flybys {on: false}, draw {clear: true}, image {clear: true}, media {close: true}. При уходе агента это снимается и само.
• Кадр проверяй через screenshot, прежде чем сказать человеку «смотри».
• Подпись caption выводится внизу слева: держи title коротким, длинное переноси в sub и text.
• Ошибка шага в play — в logs (level error), в ответе play без аргументов (lastError: {step, cmd, error}) и в плеере «⚠ шаг N». Неизвестная команда в шагах — ошибка сразу, до запуска.

2. Связь

Обе стороны подключаются к комнате-ретранслятору на том же сайте: wss://<сайт>/agent/<код>?r=agent (страница — ?r=page). Комната пересылает сообщения между ними и ничего не хранит. Сообщения — JSON:

агент → страница   { "id": 1, "cmd": "go", "args": { "search": "?o=Mars" } }
страница → агент   { "id": 1, "ok": true, "result": … }   |   { "id": 1, "ok": false, "error": "…" }
комната → обоим    { "sys": "peer", "on": true|false }      (собеседник подключился / ушёл)
поддержание связи  { "sys": "ping" } раз в 30 с, комната отвечает { "sys": "pong" }

По одной связи на роль (новый агент с тем же кодом вытесняет старого, код закрытия 4000 — тогда не переподключаться). Сообщение — до 4 МБ. Сайты: https://space.bl2.ru, https://space.bl2.net (один сайт, язык по умолчанию — ru / en).

3. MCP-сервер

Готовый MCP-сервер (stdio): scripts/agent-mcp.mjs в репозитории orbit-proto (Node ≥ 20, зависимость ws). Каждая команда ниже — инструмент с тем же именем (hide_ui → команда страницы hideUi), плюс connect, disconnect, help (эта страница текстом; lang: ru | en). Файлы: image берёт path, record сохраняет в path, screenshot возвращает картинку.

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

Переменные: AGENT_SITE — сайт по умолчанию, AGENT_CODE — подключиться сразу, AGENT_LANG — язык справки.

Подключение без MCP-сервера (облачные агенты)

• Многие агенты работают в облачных песочницах, где исходящая сеть закрыта списком разрешённых сайтов, и wss://space.bl2.ru может быть недоступен. Обходной путь — открыть WebSocket из любой вкладки браузера на space.bl2.ru (например, этой справки) и слать команды оттуда. Проверка связи: {"sys":"ping"} → {"sys":"pong"}.
• Уход агента = остановка play и откат сцены. Агент с короткими сессиями (у инструментов браузера лимит ~45 с на вызов) отправляет показ с detach: true — play {steps, detach: true} или story {action: 'run', story, detach: true} — и сразу возвращается: страница доиграет показ сама, а откат (и onstop) сделает по его концу. Без detach держи сокет открытым до конца сценария.
• Каждой команде — свой таймаут (например, 8 с): иначе одна неотвеченная команда вешает весь вызов.

// «запустил и вернулся» — из консоли вкладки на space.bl2.ru (или Node ≥ 22)
const 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: 'Сатурн', sub: '1,4 млрд км от Солнца' }, wait: 8000 },
  ] });
  ws.close(); // показ доиграет сам и потом вернёт всё как было
};

4. Команды

Посмотреть и состояние

Вид, камера, время, слои

События (считает страница, формулы не нужны)

Весь интерфейс

Рассказ

Одна точка входа: WS, MCP, консоль, сюжет

Команды и язык одинаковы, откуда бы ни пришли: по WebSocket из любого языка, из MCP, из консоли страницы (кнопка >_ в полоске агента) или из сюжета. Можно написать готовый сценарий и отдать его story, а можно дёргать команды по одной. Новое: exec {steps} — выполнить шаги языка сразу (переменные живут между вызовами), expr {e} — посчитать выражение, js {code, timeout} — JavaScript в песочнице (изолированный iframe + Web Worker: без DOM, cookies и сети; внутри — await cmd(имя, args), await expr('…'), log(), sleep(), return).

Консоль: fly Марс size=0.6 (команда, первое слово — name), JSON-команда, шаги {…} / […], выражение = …, код js ….

Базовый скрипт — Node.js:

// node agent.mjs <код>   (Node ≥ 22 — WebSocket встроен)
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]))

Язык сценариев v2

Версии: сценарий без v (или v: 1) — шаги и слайды, как выше; v: 2 — язык с условиями. Новая версия обработчика старые не трогает.

{ "v": 2, "title": "…", "on": ["oplanets"], "vars": { "n": 0 }, "steps": [
  { "cmd": "fly", "args": { "name": "Марс", "size": 0.5, "lit": true } },
  { "wait": "dist('camera', 'Марс') < 50000 km", "timeout": 20 },
  { "set": { "n": "n + 1" } },
  { "if": "visible('Марс')", "then": [ { "cmd": "caption", "args": { "title": "Марс", "sub": "до Солнца {round(au(dist('camera','Солнце')),3)} а.е." } } ] },
  { "repeat": 2, "do": [ { "wait": 1 } ] }
] }

Шаги: {cmd, args, wait} (wait — мс или выражение), {wait: выражение | секунды, timeout}, {if, then, else}, {repeat: n | выражение, do}, {set: {имя: выражение}}, {on: [...]}. Выражения — без eval: числа с единицами km au ly m, строки '…', переменные, + - * / %, < > <= >= == !=, && || !; функции dist(a, b) ('camera' или тело, км), visible(тело), elapsed(), time(), camdist(), au(x), ly(x), round(x, d), abs min max. Свойства на лету: get(тело | 'camera', 'свойство') — у тела name, kind, radius, parent, moons, x y z, sun (км от Солнца), earth, camera (км от камеры), center, visible; у камеры dist, yaw, pitch, fov, x y z, sun, center; без свойства — весь объект. Результат команды — в переменную: {cmd, args, as: 'r'}, поле — field(r, 'rows.0.text'), размер — count(x). В строках args — {выражение}. Ошибки — в logs. Дальше: триггеры (when/once/every) и песочница (spawn тел и 3D-моделей). Свои функции: {def: имя, params, e} — в выражениях, {def, params, steps} — шагом {call, args, as}, {local}, {return}; в сюжете — funcs. Ещё функции: angle(a, b) — градусы между направлениями из камеры, edge(a, b) — на сколько градусов a видно за краем диска b, sin cos (градусы), pow sqrt. wait: true у команды — пока она доиграет. Для сцен: fitdist(r[, запас]) — с какого расстояния круг радиуса r км целиком в экране (по узкой стороне; у тела есть day — сутки, с); satcount('all' | 'active' | 'debris' | 'rb' | 'dead') — объекты каталога у Земли; mstat(аппарат, 'launch' | 'km' | 'turns' | 'rmin' | 'rnow' | 'flybys') — числа миссии из её траектории на сегодня. Траектории аппаратов и их пролёты — из импорта (scripts/fetch-missions.mjs, JPL Horizons, раз в сутки): новый аппарат в базе получает пролёты и числа сам; flybys {craft} — точки пролётов на пути. Медиа в сценах: media {url | file, title, x, y, w, h, volume, loop, start, id} — окно со звуком или видео: ссылка на mp3/видео или YouTube; file — файл с компьютера человека (сайт файлы не хранит: человек выбирает его в окне, дальше — без сети); close: true — закрыть окна. Состояние: remember {name} — запомнить камеру, время, вид и интерфейс; recall {name} — вернуть; onstop {restore: true} (в файле сюжета — поле "onstop": "restore") — при конце, Esc или ✕ вернуть всё как до запуска. Подскажи человеку: сюжет и заставку можно вести с пульта — кликер презентаций (PageDown/PageUp, «.» или B — чёрный экран), медиакнопки клавиатуры, наушников и ТВ-приставки (следующий, предыдущий, пауза), геймпад (крестик ←/→, A — пауза, B — чёрный экран), с клавиатуры — стрелки, пробел, Esc. Прямые ссылки: ?ambient — заставка, ?ambient=<код сцены из ☰> — с этой сцены (например ?ambient=landings:Moon:apollo), ?story=<id>&step=N или &slide=N — опубликованный сюжет с пункта; кнопка 🔗 в плеере копирует ссылку на то, что играет. Команда ambient {play: код} — то же из агента; reset — сброс камеры, времени и вида перед сценой.

Камера и движение

Показать маленькое тело (комету, межзвёздный объект — с десятков миллионов км его не видно): follow {name} или fly {name}, затем mark {name, label: true} — мигающий разноцветный маркер у тела (виден и при hideUi; ещё color, speed), select {name} — его путь ярко. Снять: mark {remove: name} или mark {clear: true}, select {name: ''}; при откате onstop и уходе агента маркеры снимаются сами.

Плавность ease — как timing function в CSS: linear, ease, ease-in, ease-out, ease-in-out, smooth, cubic-bezier(x1,y1,x2,y2) или формула от t (0…1): 1-pow(1-t,2), t*t*t*(t*(6*t-15)+10).

Внахлёст: {cmd, args, then: [шаги], before_end: мс | after_begin: мс | when: "условие"} — вложенные шаги идут одновременно с командой. Пример: облёт Земли, разворот на Ио, перелёт к ней:

[ {"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} ]

Песочница, графика, космонавт

Консоль страницы — клавиша ё.

Как работать

1. Прочитать эту страницу (help), connect с кодом.
2. Спросить у страницы данные: search / open (объекты), body (размеры, освещённая сторона), where (положения), find (события), layers, state.
3. По этим данным подготовить действия: один сценарий play, или презентацию deck, которую человек листает сам, или свои buttons.
4. Запустить; проверить по screenshot и logs; поправить.

5. Пример: «расскажи мне про планеты»

connect {code}
layers → layer {key, visible:false} для всего, кроме oplanets
music {theme: 0, volume: 0.4};  hide_ui {on: true}
play {steps: [
  {cmd:"fly", args:{name:"Марс"}, wait: 3800},
  {cmd:"camera", args:{yaw: …, pitch: …, dist: …, ms: 3000}, wait: 3200},   // значения — из body {name:"Марс"}
  {cmd:"say", args:{title:"Марс", sub:"228 млн км · свет идёт 13 минут", text:"…", audio:"mars.mp3"}, wait: "speech"}, // голос — Piper в браузере (ru ruslan, en amy); audio — готовый mp3 вместо него
  …
]}

6. Ресурсы

• Тела: Солнце, 8 планет с лунами, карликовые планеты, ~1.4 млн астероидов (группами по размеру), кометы, межпланетные аппараты, ~30 000 спутников Земли (CelesTrak, раз в сутки), созвездия в объёме, модель Млечного Пути с туманностями и скоплениями, 44 000 галактик (2MRS).
• Имена — по-русски и по-английски (Марс / Mars); координаты — экватор J2000, км.
• Время — любая дата (вдали от сегодня эфемериды грубее; спутники — только ±90 дней от каталога).
• Ссылки на вид (?o=…&d=…&v=…&t=…) открывают то же самое у любого.

Правила: страница принимает только эти команды; никаких переходов на другие сайты и личных данных. Управление — у человека: он может нажать «Отключить» в любой момент.