星图

基于 WebGL 与 Hipparcos I/239 恒星目录的沉浸式星空示例，展示 StepFun Realtime API ToolCall 能力。

Screen.Recording.2026-08-04.at.25-30s.mp4

能力

• 按上海默认经纬度和当前时间计算地平线上方可见恒星
• 展示可见星座连线与标签
• 通过鼠标/触控拖动移动视角，滚轮缩放
• 移动端支持重力感应视角
• 预留 window.starMap 接口，便于后续接入语音控制镜头与时间

运行

npm install
npm run build:data
npm run dev

语音控制接口预留

浏览器控制台或后续语音层可直接调用：

window.starMap.setObserver({ latitude: 31.2304, longitude: 121.4737, label: "上海" });
window.starMap.setTime(new Date());
window.starMap.useLiveTime();
window.starMap.setCameraPose({ yaw: 45, pitch: 24, fov: 52 });
window.starMap.moveCameraBy(12, -6);
window.starMap.resetCamera();
window.starMap.projectNow();

Realtime Voice Agent

页面左下角可开启 Realtime Voice Agent。首次打开时填写 Endpoint 和 API Key；默认 Endpoint 为 wss://api.stepfun.com/v1/realtime。配置保存于浏览器 localStorage，之后可 直接开始或通过钥匙按钮修改 API Key。

开启后允许浏览器麦克风权限，即可直接说出想看的星座，例如「带我看看猎户座」、 “Show me Orion” 或「北斗在哪」。

完整的工具 schema 和参数说明见文末“Tool-call 与页面功能”。

Realtime API 对接细节

页面使用浏览器原生 WebSocket 连接 Realtime API，默认 Endpoint 为：

wss://api.stepfun.com/v1/realtime

连接时将模型作为 query 参数传入，当前固定使用 stepaudio-2.5-realtime。API Key 不放在 URL 中，而是通过 OpenAI Realtime 风格的 WebSocket subprotocol 传递：

new WebSocket(endpoint + "?model=stepaudio-2.5-realtime", [
  "realtime",
  "openai-insecure-api-key." + apiKey,
  "openai-beta.realtime-v1",
]);

Endpoint 和 API Key 保存在浏览器 localStorage 的以下键中：

star-map.realtime-endpoint
star-map.realtime-api-key
star-map.realtime-web-search

联网搜索可在语音助手配置浮层中选择；开启时，前端会在 session.update.tools 中追加 { type: "web_search" }。

连接建立后发送 session.update。会话配置包括 audio/text modalities、pcm16 音频格式、 server VAD、elegantgentle-female 音色，以及页面工具。session.update 不配置 input_audio_transcription 或 tool_choice，由服务端默认行为处理。

最小的 session.update 结构如下（instructions 使用下一节的提示词）：

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    instructions,
    voice: "elegantgentle-female",
    modalities: ["audio", "text"],
    input_audio_format: "pcm16",
    output_audio_format: "pcm16",
    turn_detection: {
      type: "server_vad",
      threshold: 0.5,
      prefix_padding_ms: 300,
      silence_duration_ms: 500,
    },
    tools: [
      ...STAR_MAP_TOOLS,
      // 可选：{ type: "web_search" }
    ],
  },
}));

提示词

页面实际使用的 session.instructions 要点如下。接入其他页面时可以直接复用，再替换 其中的页面能力描述：

你是一个星图讲解助手。用户提到、询问或要求观看任意星座时，必须调用
focus_constellation 工具，并将用户说出的星座名称原样作为 query 传入；不要自行猜测
或回复说页面不支持。用户要求转动、抬高、压低、拉近或拉远镜头时，调用 adjust_camera，
参数单位是 degrees（度），不是弧度，每次使用 5-15 度的小幅相对调整。用户要求换城市
或观测地点时，调用 set_observer_location；地点会改变星座的方位、高度角和是否在地平线上方。
用户询问屏幕中有什么、现在看到哪些星座或需要根据当前画面讲解时，必须先调用
get_visible_constellations。工具返回 altitude_degrees 和 horizon_status；below_horizon
表示星座中心在地平线下，不要说成当前可见。工具完成后，用简洁中文做不超过两句话的观星讲解。

工具调用时必须严格输出：
<|CALL_START|>function
工具名
参数JSON<|CALL_END|>
参数必须是合法 JSON，参数名必须与工具定义完全一致。不得编造工具结果；在工具返回前
不能假装已经知道答案；需要实时信息时不得凭记忆或猜测。工具失败时直接口语化说明。

页面还会把全部 88 个 IAU 标准星座和支持的观测城市目录追加到提示词末尾，避免模型 对偏门星座或地点进行猜测；目录由 src/realtime/tools.ts 中的 CONSTELLATION_CATALOG_PROMPT 和 LOCATION_CATALOG_PROMPT 生成。

音频链路

• AudioWorklet 获取麦克风输入，并转换成 24 kHz mono PCM16。
• 音频先在 AudioWorklet 中缓存为 20 ms（480 samples）一段，再编码成 base64， 通过 input_audio_buffer.append 发送。
• 服务端返回 response.audio.delta（PCM16）；前端按 AudioContext 时间线排队播放， 当前按 24 kHz 解码。
• input_audio_buffer.speech_started / speech_stopped 事件会同步到左下角语音胶囊。

Tool-call 与页面功能

Realtime 会话默认开放以下四个 function tools；配置中打开联网搜索时，再追加 { type: "web_search" }：

[
  {
    type: "function",
    function: {
      name: "focus_constellation",
      description: "将镜头平滑聚焦到指定星座，并触发短暂高亮。",
      parameters: {
        type: "object",
        properties: {
          query: { type: "string", description: "中文名、英文/拉丁名、IAU 三字母或常用别名" },
        },
        required: ["query"],
        additionalProperties: false,
      },
    },
  },
  {
    type: "function",
    function: {
      name: "adjust_camera",
      description: "相对调整当前镜头；所有角度单位为 degrees。",
      parameters: {
        type: "object",
        properties: {
          yaw_degrees: { type: "number", description: "水平相对转动，-45 到 45；正值向右" },
          pitch_degrees: { type: "number", description: "垂直相对转动，-30 到 30；正值抬头" },
          fov_degrees: { type: "number", description: "视场角变化，-20 到 20；负值拉近" },
        },
        additionalProperties: false,
      },
    },
  },
  {
    type: "function",
    function: {
      name: "set_observer_location",
      description: "切换观测城市并重新计算星座方位、高度角和地平线状态。",
      parameters: {
        type: "object",
        properties: { location: { type: "string", description: "支持城市的中文名、英文名或 id" } },
        required: ["location"],
        additionalProperties: false,
      },
    },
  },
  {
    type: "function",
    function: {
      name: "get_visible_constellations",
      description: "查询当前相机视野中的星座及其位置、方位和地平线状态。",
      parameters: { type: "object", properties: {}, additionalProperties: false },
    },
  },
]