MOSS-Live Voice Agent Runtime

终端                        你的服务（嵌 SDK）
 │  ① POST /v1/sessions ←── 你的后端签发（人设 / 模型 / 音色 / 工具白名单）
 │      ← {session_id, token, expires_at}
 │  ② WS /v1/realtime?token=…
 │      上行：16k s16le 单声道 PCM（二进制帧）
 │      下行：24k s16le PCM（二进制帧）+ JSON 事件（文本帧）
 │  ③ DELETE /v1/sessions/{id}（或 TTL 15min 自然过期）

codeup.aliyun.com/mosi/voice-agent-sdk

# 1) 跳过公共 proxy 和校验和库
go env -w GOPRIVATE=codeup.aliyun.com/mosi/*

# 2) 凭据（二选一）
git config --global url."git@codeup.aliyun.com:".insteadOf "https://codeup.aliyun.com/"
# 或写 ~/.netrc:  machine codeup.aliyun.com login <账号> password <个人访问令牌>

go get codeup.aliyun.com/mosi/voice-agent-sdk@v0.2.1

package main

import (
    "log"
    "os"
    "codeup.aliyun.com/mosi/voice-agent-sdk/agent"
)

func main() {
    a, err := agent.New(agent.Config{
        Dashscope: agent.Dashscope{
            APIKey: os.Getenv("DASHSCOPE_API_KEY"),
        },
        VADModel: "/opt/models/silero_vad.onnx",
        Persona:  "你是四月，说话简短自然，别念清单。",
        Events:   true,  // 把判定过程下发给终端（调试/埋点用）
    })
    if err != nil { log.Fatal(err) }
    log.Fatal(a.Serve(":8080"))
}

# 只要 VAD（最常见）
CGO_CFLAGS=-I/opt/onnxruntime/include CGO_LDFLAGS=-L/opt/onnxruntime/lib \
  go build -tags silero -o va-server ./cmd/server

# 连语义判停一起（可选，见「语义判停」一节）
CGO_CFLAGS=-I/opt/onnxruntime/include CGO_LDFLAGS=-L/opt/onnxruntime/lib \
  go build -tags smartturn,silero -o va-server ./cmd/server

# 运行时
export LD_LIBRARY_PATH=/opt/onnxruntime/lib

行了行了别说了        → 叫停（原子+原子+原子）
好了我知道了你别说了  → 叫停
你先停一下            → 叫停（「你」「先」是虚词）
停一下我想问个事      → 实词路，她该回答
你别停下来啊          → 反义，用户在喊接着说
好了吗 / 行了吗       → 疑问，用户在等回答
还行吧 / 还不错       → 评价，不是叫停

用户说：给我查一下 …（换气）… 上海的天气
        ↑ 语法上完整、尾巴是实词，只有模型知道后面还有宾语

type EndOfTurn interface {
    // 给最近 8 秒的 16k 单声道 s16le PCM，返回「说完了」的概率 [0,1]。
    Predict(pcm []byte) (float32, error)
}

# 必填
DASHSCOPE_API_KEY=sk-…
SILERO_VAD=/opt/models/silero_vad.onnx

# 上游端点与调音
DASHSCOPE_HTTP=      DASHSCOPE_WS=
LLM_MODEL=           LLM_MAX_TOKENS=      LLM_TEMPERATURE=
ASR_MODEL=           ASR_LANG=zh
TTS_MODEL=           TTS_VOICE=           TTS_INSTRUCTIONS=
TTS_RATE=            TTS_PITCH=           TTS_SSML=1

# 人设与对话
PERSONA=             TIMEZONE=Asia/Shanghai   MAX_HISTORY=20
SKILLS_DIR=          PRECACHE=1
SMART_TURN_MODEL=    # 语义判停（需 -tags smartturn）

# 搜索与工具
SEARCH=1             SEARCH_SITES=a.com,b.com   SEARCH_DAYS=7
SONG_DIR=            MUSIC_DIR=

# MCP 业务工具（不配 = 完全不接 MCP）
MCP_ENDPOINT=https://tools.you.com/mcp
MCP_ALLOW=get_order,refund   # 必填，默认拒绝
MCP_HEADERS=Authorization=Bearer xxx
MCP_TIMEOUT=5s

# MCP 放音频（配了 MEDIA_HOSTS 才开）
MEDIA_HOSTS=cdn.you.com      # 空 = 媒体能力整个关闭
MEDIA_MAX_BYTES=16777216     MEDIA_CACHE_BYTES=67108864
MEDIA_ALLOW_PRIVATE=         MEDIA_CACHE_IGNORE_QUERY=

# 承载面与安全
ADDR=:8080           MAX_CONNS=200        MAX_SESSIONS=10000
READ_TIMEOUT=90s     REQUIRE_SESSION=1    ADMIN_TOKEN=
ALLOW_ORIGINS=https://your.app

# 观测
EVENTS=1             LOG_TEXT=            DEV_PAGE=
OTLP_ENDPOINT=http://tempo:4318          OTEL_SERVICE_NAME=voice-agent

persona: 你是护理助手，说话慢一点，多确认。
llm_model: qwen3.7-flash
tts_voice: longxing_v3
max_history: 12
timezone: Asia/Shanghai
search: false
tools: [check_schedule]

type Toolbox interface {
    // Specs 是这一轮要交给模型的全部工具说明（允许每轮不同）。
    Specs() []ToolSpec
    // Invoke 执行一次调用，返回给模型看的结果文本。
    Invoke(ctx context.Context, call ToolCall) string
}

ctl, ok := voiceagent.MediaFromContext(ctx)
if !ok { return "播放功能当前不可用。" }
ctl.PlayPCM(voiceagent.KindSong, id, title, f) // f 的所有权移交 SDK

{"content": [
  {"type": "text", "text": "已开始唱《星夜》。回一句自然的话就行，别念歌词。"},
  {"type": "resource_link", "uri": "https://cdn.you.com/starnight.wav",
   "mimeType": "audio/wav", "title": "星夜"}
]}

type ASR interface {
    Feed(pcm []byte)
    // Commit 声明当前缓冲为一整句，触发定稿识别。
    // 返回【这次是不是真的发出去了】——缓冲里没有新音频时可以跳过，
    // 那时返回 false。
    Commit() bool
    Events() <-chan ASREvent
}

curl -X POST https://your.host/v1/sessions \
  -H 'Authorization: Bearer $ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"persona":"你是四月…","voice":"longxing_v3","tools":["sing_song"]}'

# ← {"session_id":"…","token":"…","expires_at":"2026-08-06T04:15:00Z"}

const pc1 = new RTCPeerConnection(), pc2 = new RTCPeerConnection();
pc1.onicecandidate = e => e.candidate && pc2.addIceCandidate(e.candidate);
pc2.onicecandidate = e => e.candidate && pc1.addIceCandidate(e.candidate);
pc2.ontrack = e => { audioEl.srcObject = e.streams[0]; };  // AEC 从这里看见它

const dest = playCtx.createMediaStreamDestination();
playNode.connect(dest);              // 不要 connect(playCtx.destination)
pc1.addTrack(dest.stream.getAudioTracks()[0], dest.stream);
// 再走 offer/answer，等 ontrack 到了才开始播

# base URL 就行，SDK 会补 /v1/traces
OTLP_ENDPOINT=http://tempo:4318
# 已经指到信号上的、或带网关前缀的，原样不动
OTLP_ENDPOINT=http://gw/otlp

OTEL_SERVICE_NAME=voice-agent-preview   # 不配默认 voice-agent

# ① 服务活着
curl -s https://your.host/healthz          # → ok

# ② 跑的确实是新二进制（healthz 分辨不出新旧）
curl -s https://your.host/version          # → <提交号> <构建时间>

# ③ 进程加载的就是刚换上去的那个文件
sha256sum /proc/$(pgrep -f your-server)/exe