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

「Space Now」— 智能体 API

本页面面向 AI 智能体（及其使用者）。它说明智能体如何连接到用户浏览器中正在运行的「Space Now」页面 (known.html)，以及能在其中做什么：界面能做的一切——打开任意天体、 飞行相机、拖动时间、切换图层和过滤器、宇航员模式、查找日食和行星连珠、配合语音和字幕讲故事、展示自己的图片、 录制视频、读取错误。渲染在用户的浏览器中完成（使用其 GPU 的 WebGL）；智能体只发送命令，并获得回复和截图。

1. 配对

1. 用户打开网站，点击圆形的 🤖 按钮（右下角，宇航员上方）——智能体栏展开；点击「开启智能体」会显示一个代码（20 个字符，例如 r4fxjbjsxdy6ex3pf4hd）。该代码就是通行证：持有者即可控制此标签页。🤖 只是隐藏/显示该栏，连接不会断开；栏中的「断开连接」会关闭连接。该栏始终有 📂（打开故事文件或保存当前显示的故事——没有智能体也可用）和「MCP ↗」（即本页）。
2. 用户把代码交给智能体。智能体用该代码调用 connect。
3. 永久连接（可选）：在页面上——智能体栏中的 📌「记住」（代码保存在此浏览器中，网站每次打开时自动连接）；在智能体端——使用 save: true 调用 connect（代码保存到 ~/.orbit-agent.json，MCP 启动时自动连接）。之后只需打开网站即可。要忘记：取消固定 📌 并调用 forget。
4. 页面上的「断开连接」（或智能体离开）会结束会话；随后页面会把图层和界面恢复到智能体介入之前的状态，停止音乐、语音、字幕、图片和脚本，并移除着陆点（sites）、绘图和标记 （draw、mark、flybys）、媒体窗口和自建天体（spawn）——与 onstop 无关。相机、时间和 选中项也会恢复（默认如此；onstop {restore: false} — 保留智能体展示的内容）。例外：带 detach: true 的 play / story run — 演示会播放到结束，然后回滚。

声音（语音、音乐）只有在用户至少点击过一次页面后才会启动——这是浏览器的规定。语音默认关闭：用户通过智能体栏中的 🔊 开启（会被记住）；字幕始终显示。

演示检查清单——务必照做

[
  {"cmd":"onstop","args":{"restore":true}},        // 第一步：结束、按 Esc 或 ✕ 时一切恢复原状
  {"cmd":"reset"},
  {"cmd":"view","args":{"on":["oplanets"]}},        // 只开需要的图层：卫星、航天器、轨道、星座一律关闭
  {"cmd":"hideUi","args":{"on":true,"labels":false}},
  {"cmd":"time","args":{"at":"<moment>","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（error 级别）、不带参数的 play（lastError: {step, cmd, error}），并在播放器中显示为「⚠ step N」。steps 中出现未知命令会在开始前立即报错。

2. 传输

双方都连接到同一网站上的中继房间：wss://<site>/agent/<code>?r=agent（页面使用 ?r=page）。房间在两端之间转发消息；不保存任何内容。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 }      (对端加入 / 离开)
keepalive      每 30 秒发送一次 { "sys": "ping" }，房间回复 { "sys": "pong" }

每个角色只允许一个连接（使用相同代码的新智能体会替换旧的，关闭码 4000 — 此时不要重连）。 消息最大 4 MB。站点：https://space.bl2.ru、https://space.bl2.net（同一网站，默认语言为 ru/en）。

3. MCP 服务器

现成的 MCP 服务器（stdio）：orbit-proto 仓库中的 scripts/agent-mcp.mjs（Node ≥ 20，依赖 ws）。 下面的每个命令都是同名工具（hide_ui → 页面命令 hideUi），另外还有 connect、 disconnect、help（本页的文本形式；lang: en）。文件：image 接受 path，record 保存 到 path，screenshot 返回图片。

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

环境变量：AGENT_SITE — 默认站点，AGENT_CODE — 启动时连接。

不使用 MCP 服务器的连接方式（云端智能体）

• 许多智能体运行在云沙箱中，出站网络仅限于白名单，因此 wss://space.bl2.ru 可能无法访问。变通办法：在 space.bl2.ru 的任意浏览器标签页（例如本帮助页）中打开 WebSocket，并从那里发送命令。连接检查：{"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 = '<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(); // 演示由页面自行播放，结束后再把一切恢复原状
};

4. 命令

查看与状态

视图、相机、时间、图层

事件（由页面计算，无需自备公式）

整个界面

讲故事

统一入口：WS、MCP、控制台、故事

无论命令来自哪里，命令和语言都是相同的：任意语言的 WebSocket、MCP、页面控制台（智能体栏中的 >_ 按钮）或故事。可以写好整个脚本交给 story，也可以逐条调用命令。新增：exec {steps} — 立即运行语言步骤（变量在多次调用之间保留），expr {e} — 求值表达式，js {code, timeout} — 沙箱中的 JavaScript（隔离的 iframe + Web Worker：没有 DOM、cookie 或网络；内部可用 await cmd(name, args)、await expr('…')、log()、sleep()、return）。

控制台：fly Mars size=0.6（一条命令，第一个词是名称）、JSON 命令、步骤 {…} / […]、表达式 = …、代码 js …。

基础脚本 — Node.js：

// node agent.mjs <code>   (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 <code>    (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": "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 } ] }
] }

步骤：{cmd, args, wait}（wait — 毫秒或表达式）、{wait: expression | seconds, timeout}、{if, then, else}、{repeat: n | expression, do}、{set: {name: expression}}、{on: [...]}。表达式 — 不使用 eval：带单位的数字 km au ly m、字符串 '…'、变量、+ - * / %、< > <= >= == !=、&& || !；函数 dist(a, b)（'camera' 或某个天体，km）、visible(body)、elapsed()、time()、camdist()、au(x)、ly(x)、round(x, d)、abs min max。即时属性：get(body | 'camera', 'prop') — 天体有 name、kind、radius、parent、moons、x y z、sun（距太阳 km）、earth、camera（距相机 km）、center、visible；相机有 dist、yaw、pitch、fov、x y z、sun、center；不带 prop — 整个对象。把命令结果存入变量：{cmd, args, as: 'r'}，取字段 — field(r, 'rows.0.text')，大小 — count(x)。在 args 字符串中 — {expression}。错误进入 logs。后续计划：触发器（when/once/every）和沙箱（生成天体和 3D 模型）。自定义函数：{def: name, 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[, margin]) — 半径 r km 的圆恰好放进屏幕（取窄边）的距离（天体还有 day — 自转周期，秒）；satcount('all' | 'active' | 'debris' | 'rb' | 'dead') — 地球周围的星表天体；mstat(craft, '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 — 黑屏）、键盘方向键、Space、Esc。直达链接：?ambient — 屏保，?ambient=<scene code from ☰> — 从该场景开始（例如 ?ambient=landings:Moon:apollo），?story=<id>&step=N 或 &slide=N — 从该处开始播放已发布的故事；播放器中的 🔗 按钮会复制指向当前播放内容的链接。智能体可以用 ambient {play: code} 命令实现同样的效果；reset 在场景之前重置相机、时间和视图。

相机与运动

展示小天体（彗星、星际天体 — 在数千万 km 外看不见）：follow {name} 或 fly {name}，然后 mark {name, label: true} — 在该天体处显示闪烁的彩色标记（hideUi 下也可见；另有 color、speed），select {name} — 其路径高亮。移除：mark {remove: name} 或 mark {clear: true}、select {name: ''}；onstop 回滚和智能体离开时会自动移除标记。

缓动 ease — 类似 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: [steps], before_end: ms | after_begin: ms | when: "condition"} — 嵌套步骤与该命令同时运行。示例：绕地球运行，转向木卫一，飞向它：

[ {"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:"Mars"}, wait: 3800},
  {cmd:"camera", args:{yaw: …, pitch: …, dist: …, ms: 3000}, wait: 3200},   // 数值取自 body {name:"Mars"}
  {cmd:"say", args:{title:"Mars", sub:"228 million km · light takes 13 min", text:"…", audio:"mars.mp3"}, wait: "speech"}, // 语音由浏览器中的 Piper 提供（ru ruslan，en amy）；audio — 用现成的 mp3 代替
  …
]}

6. 资源

• 天体：太阳、8 颗行星及其卫星、矮行星、约 140 万颗小行星（按大小分组）、彗星、行星际航天器、 约 30 000 颗地球卫星（CelesTrak，每日更新）、3D 星座、含星云和星团的银河系模型、44 000 个星系（2MRS）。
• 名称支持俄语和英语（Марс / Mars）；位置为 J2000 赤道坐标，单位 km。
• 时间范围：任意日期（距今越远星历精度越低；卫星仅限星表前后 ±90 天）。
• 分享链接（?o=…&d=…&v=…&t=…）可让任何人打开相同的视图。

规则：页面只接受这些命令；不能跳转到其他网站，不涉及个人数据。请让用户始终保有控制权 — 他们可以随时点击「断开连接」。