Starchild Auth

🔑 Starchild Auth SDK — 完整开发指南

Integrate Starchild OAuth login into any web application. The SDK handles OAuth popup flow, token refresh, unified StarchildAuthError, namespaced helpers (auth.chat / auth.credit …), and 60+ API methods for full Agent access.

版本策略

两套 semver 互不绑定：只改文档可只升 skill；只改实现必须升 package（skill 通常同步升 minor/patch 说明新能力）。

架构概览

第三方网站 (your-app.com)
    │
    ├─ StarchildAuth SDK (starchild-auth-sdk)
    │   ├─ auth.login()       → 弹出 starchild-web 授权页面
    │   ├─ auth.logout()      → go-api POST /v1/oauth/logout
    │   ├─ auth.bindAccount() → 跳转主站 Linked accounts 绑定正式账号
    │   └─ token refresh      → go-api POST /v1/oauth/refresh
    │
    ├─ API 调用 (chat scope)
    │   ├─ chat/stream      → clawd (SSE 流式响应)
    │   ├─ /api/clawd/*     → ai-agent (线程/消息)
    │   ├─ /api/cloud/*     → ai-agent (容器管理)
    │   └─ WebSocket        → clawd (文件同步/终端/指标)
    │
    ├─ Credits API (credit:read / credit:write)
    │   └─ https://credit.iamstarchild.com
    │       ├─ GET  /api/credits|charges|topups|usage/daily|pending|tx/{hash}
    │       ├─ POST /api/stripe/create-session | gift-cards/redeem | points/exchange
    │       ├─ GET/POST /api/kyc/* | /api/referral/* | /api/migration/reward/*
    │       └─ GET  /api/public/users/{id}/woo-bonus
    │
    └─ 用户信息
        └─ /v1/oauth/userinfo → ai-agent

应用注册与审核

注册流程

1. 在 iamstarchild.com → More → OAuth Apps → Create App
2. 填写信息：
   • Name (必填): 应用名称
   • Allowed Origin (必填): 第三方应用自己的页面 Origin（不是 starchild-web）。例：生产 https://your-app.com；本地 http://localhost:5173 / http://localhost:3333。只允许 origin（scheme://host[:port]，无路径/query/hash）；非 localhost 必须 https://。可配多个。不要把 http://localhost:6066 当成第三方 origin——6066 是主站 web 本地端口，已在服务端静态 CORS 中放行。
   • Scopes: 勾选需要的权限
   • System Prompt (可选): 自定义 Agent 行为
3. 仅选 profile → 自动通过，立即获得 Client ID
4. 选了 chat / credit:read / credit:write → 进入管理员审核，审核通过后才生成 Client ID

Scope 权限体系

注意: 容器删除操作对所有 OAuth token 均被拦截（返回 403）。这是服务端硬限制。

安装

npm / yarn / pnpm

npm install starchild-auth-sdk
# or: yarn add starchild-auth-sdk
# or: pnpm add starchild-auth-sdk

CDN (plain HTML)

<!-- UMD build — use with plain <script> tags -->
<script src="https://unpkg.com/starchild-auth-sdk/dist/starchild-auth.umd.cjs"></script>

<!-- China mirror -->
<script src="https://registry.npmmirror.com/starchild-auth-sdk/latest/files/dist/starchild-auth.umd.cjs"></script>

UMD 构建导出 window.StarchildAuth（构造函数本身，不是 namespace）。 ESM 构建 (starchild-auth.js) 用于 <script type="module"> 或 bundler。

初始化与登录

import { StarchildAuth } from 'starchild-auth-sdk'

const auth = new StarchildAuth({
  clientId: 'your-client-id',          // 必填
  scope: 'profile chat credit:read credit:write', // 空格分隔；需要 Credits 时加上 credit scopes
  // clawdApiBase: 'https://preview.iamstarchild.com', // chat/stream HTTP
  // clawdWsBase: 'wss://preview.iamstarchild.com',   // /ws/sync|terminal|metrics
  // creditApiBase: 'https://credit.iamstarchild.com', // 可选，默认生产域名

  // 登录成功回调（popup 或 autoLogin 恢复 session 时触发）
  onLogin: ({ accessToken, refreshToken, expiresIn, userInfo }) => {
    console.log('Logged in:', userInfo.agentName, 'guest=', userInfo.isGuest)
    // userInfo = { userInfoId, agentName, agentAvatar, isGuest }
  },

  onLogout: () => { /* 清除本地状态 */ },
  onTokenRefresh: (newToken) => { /* 更新本地 token */ },
  onTokenRefreshFailed: () => { /* session 过期 */ },

  // 可选配置
  autoLogin: true,          // 默认 true — 从 localStorage 恢复 session
  origin: 'https://iamstarchild.com',  // Starchild 站点
  refreshInterval: 720000,  // 自动刷新间隔 (ms)，默认 12 分钟
})

Token 生命周期

• Access Token: 15 分钟有效，自动每 12 分钟刷新；auth.getToken()
• Refresh Token: 7 天有效，存储在 localStorage 的 starchild_rt_{clientId} key 中；auth.getRefreshToken() 仅暴露内存中的同一值
• autoLogin: 页面加载时自动用 refresh token 恢复 session
• visibilitychange: 从后台切回时自动刷新 token

getRefreshToken() 安全模型

• Refresh token 本来就写在集成方 origin 的 localStorage（autoLogin 需要）；公开 getter 不扩大威胁面，只是可读内存副本。
• 优先让 SDK 自己刷新：refreshToken() / 定时 auto-refresh / visibility 刷新。
• 若你拷贝到自有存储：当作密码——禁止日志、禁止发给第三方后端、禁止放进 URL。
• 集成方 origin 上的 XSS 本来就能读 localStorage；用 CSP、避免 inline script 缓解。

Guest 账号与绑定正式登录方式

没有 loginAsGuest()。Guest 与正式账号走同一条 auth.login() 主站 popup 流程；用户在主站选择 continue-as-guest（或等价入口）时才会拿到 isGuest: true。第三方不要自建 guest 登录。

OAuth 登录可能返回 Guest（临时）账号（userInfo.isGuest === true）。Guest 可正常使用已授权 scope，但未绑定永久登录方式（Google / X / Email / Phone / Wallet）。

绑定必须在 Starchild 主站完成，第三方不要自建绑定页。SDK 提供跳转方法：

// 登录后检查是否为 Guest
const user = auth.getUserInfo()
// 或刷新：const user = await auth.fetchUserInfo()

if (auth.isGuest() || user?.isGuest) {
  // 打开主站 Account management → Linked accounts
  // URL: https://iamstarchild.com/?account_tab=linked-accounts
  const win = auth.bindAccount()
  if (!win) {
    // 弹窗/新标签被拦截时，可自行跳转
    window.location.href = auth.getBindAccountUrl()
  }
}

// 仅需要 URL（例如自己渲染按钮 href）
const bindUrl = auth.getBindAccountUrl()
// => `${origin}/?account_tab=linked-accounts`

主站打开后会根据 ?account_tab=linked-accounts 自动打开账号管理并切到 Linked accounts。用户完成绑定后，第三方应用下次 fetchUserInfo() / token refresh 后应看到 isGuest: false。

核心 API 调用模式

请求格式

所有 SDK 方法自动处理 token 注入。手动发送请求时：

const headers = {
  'Authorization': `Bearer ${accessToken}`,
  'Content-Type': 'application/json',
}

clawd 端点必须带 fly-force-instance-id：clawd（preview.iamstarchild.com）每个 Fly Machine 是单用户容器，容器归属（IDOR）检查要求请求落到当前用户容器，否则返回 403「Access denied: you do not own this resource」。OAuth access token 不含 containerId，SDK 会自动通过 GET /api/cloud/containers 解析并注入 fly-force-instance-id: <container_id> header；手动 curl 测 clawd 端点时需显式带该 header，否则会 403。

端点地址：

• ai-agent REST API: https://ai-api.iamstarchild.com（线程/消息/容器/技能等）
• clawd HTTP API: https://preview.iamstarchild.com（chat/stream、scheduled-jobs、models）
• Token 端点: https://go-api.iamstarchild.com/v1（go-api）

命名空间 API（兼容层）

Flat 方法全部保留。命名空间是 plan 303 风格的分组别名，二者等价：

await auth.sendMessage('hi')
await auth.chat.send('hi')          // alias

await auth.getCredits()
await auth.credit.getBalance()      // alias

await auth.listThreads()
await auth.threads.list()

Points 兑换、KYC、Referral 已对 OAuth 开放（需 credit:read / credit:write），不是主站专属。

场景一：发送消息并读取 SSE 流响应

这是最核心的交互模式。消息通过 SSE (Server-Sent Events) 流式返回。

SDK 方式

const stream: Response = await auth.sendMessage('Hello, analyze this data')

// SSE 是流式响应，需要逐块读取
const reader = stream.body!.getReader()
const decoder = new TextDecoder()
let buffer = ''

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  buffer += decoder.decode(value, { stream: true })
  const lines = buffer.split('\n')
  buffer = lines.pop() || ''  // 保留未完成的行

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6))
      // event.type 决定处理方式
      handleStreamEvent(event)
    }
  }
}

原生 fetch 方式（不使用 SDK）

// POST /chat/stream — SSE 流式聊天（clawd 端点）
const response = await fetch('https://preview.iamstarchild.com/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Hello, analyze this data',
    thread_id: threadId,    // 可选，不传则创建新 thread
  }),
})

// 读取 SSE 流（同上）

SSE 事件类型

function handleStreamEvent(event: any) {
  switch (event.type) {
    case 'agent_start':
      console.log('Agent started, session:', event.session_key)
      // 保存 session_key 用于断线重连
      break
    case 'text_delta':
      process.stdout.write(event.text)  // 实时输出
      break
    case 'tool_use':
      console.log(`Using tool: ${event.tool_name}(${event.tool_input})`)
      break
    case 'tool_output':
      console.log('Tool result:', event.tool_output)
      break
    case 'agent_end':
      console.log('Done, reason:', event.stop_reason)
      break
    case 'error':
      console.error('Stream error:', event.message)
      break
  }
}

重连 SSE 流

当 SSE 连接断开（网络问题、页面切换等），用 session_key 重连：

// POST /chat/stream/reconnect?session_key=xxx&channel=web
const stream = await auth.reconnectStream(sessionKey)
// 读取方式同 sendMessage

场景二：管理对话线程

// 创建线程
const thread = await auth.createThread('My analysis')
// thread = { id: string, title: string, created_at: string, ... }

// 列出所有线程
const { threads } = await auth.listThreads()

// 获取线程消息
const { messages } = await auth.listMessages(thread.id, 50)  // 最近 50 条
// messages[0] = { id, role: 'user'|'assistant', content: [...], created_at }

// 搜索线程
const result = await auth.searchThreads('analysis')

// 删除线程
await auth.deleteThread(thread.id)

// 删除消息
await auth.deleteMessages(thread.id)

场景三：管理容器

容器是运行 Agent 的 Fly.io 虚拟机。

// 部署新容器
const container = await auth.deployContainer()
// container = { container_id, name, state, region, ... }

// 列出所有容器
const { containers } = await auth.listContainers()

// 获取容器状态
const status = await auth.getContainerStatus(container.container_id)
// status = { state: 'started'|'stopped'|'suspended'|..., ... }

// 启动/停止/重启
await auth.startContainer(container_id)
await auth.stopContainer(container_id)
await auth.restartContainer(container_id)

// 重命名
await auth.renameContainer(container_id, 'production-agent')

// 获取指标
const metrics = await auth.getContainerMetrics(container_id)
// metrics = { cpu: { series: [...] }, memory: { series: [...] }, disk: { series: [...] } }

// ⚠️ 删除容器 — OAuth token 无法执行（服务端返回 403）
// await auth.deleteContainer(container_id)  // 总是失败

场景四：WebSocket 连接

实时指标 (CPU/内存/磁盘)

const ws = auth.createMetricsWebSocket()

ws.onopen = () => console.log('Metrics connected')
ws.onmessage = (e) => {
  const { cpu_percent, memory_used_bytes, memory_total_bytes, disk_used_bytes } = JSON.parse(e.data)
  console.log(`CPU: ${cpu_percent}%, Mem: ${memory_used_bytes}/${memory_total_bytes}`)
}
ws.onclose = () => console.log('Disconnected — implement reconnection logic')

文件同步

const ws = auth.createSyncWebSocket()

ws.onopen = () => {
  // 订阅文件变更
  ws.send(JSON.stringify({
    type: 'sync:subscribe',
    payload: { paths: ['/src'] }
  }))
}

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data)
  switch (msg.type) {
    case 'sync:connected':
      console.log('Sync ready, session:', msg.payload.sessionId)
      break
    case 'file:created':
      console.log('New file:', msg.payload.path)
      break
    case 'file:updated':
      // msg.payload = { path, type: 'file'|'directory', triggeredBy: 'watcher'|'agent'|'user' }
      console.log('Changed:', msg.payload.path, 'by', msg.payload.triggeredBy)
      break
    case 'file:deleted':
      console.log('Deleted:', msg.payload.path)
      break
    case 'file:moved':
      console.log('Moved:', msg.payload.oldPath, '→', msg.payload.newPath)
      break
  }
}

终端

// sessionId 从 SSE chat stream 的 terminal:connected 事件获取
const ws = auth.createTerminalWebSocket(sessionId)

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data)
  switch (msg.type) {
    case 'connected':
      console.log('Terminal ready, session:', msg.sessionId)
      break
    case 'output':
      process.stdout.write(msg.data)
      break
    case 'error':
      console.error('Terminal error:', msg.message)
      break
  }
}

// 发送命令
ws.send(JSON.stringify({ type: 'input', data: 'ls -la\n' }))
// 调整终端大小
ws.send(JSON.stringify({ type: 'resize', cols: 120, rows: 40 }))

WebSocket 重连

浏览器 WebSocket 不支持自动重连，需要自行实现：

class WSReconnect {
  private ws: WebSocket | null = null
  private attempts = 0
  private maxAttempts = 5

  connect(factory: () => WebSocket) {
    this.ws = factory()
    this.ws.onclose = () => {
      if (this.attempts < this.maxAttempts) {
        const delay = Math.min(1000 * 2 ** this.attempts, 30000)
        setTimeout(() => {
          this.attempts++
          this.connect(factory)
        }, delay)
      }
    }
    this.ws.onopen = () => { this.attempts = 0 }
  }
}

场景五：技能与媒体

// 浏览技能目录
const catalog = await auth.getSkillsCatalog()
// catalog = { official: [{ source, name, description, ... }], community: [...], installed: [...] }

// 搜索技能
const results = await auth.searchSkills('trading')

// 获取技能详情
const detail = await auth.getSkillDetail('official', 'orderly-trading')

// 上传图片
const image = await auth.uploadImage(base64data, 'image/png')
// image = { url: string, filename: string }

// 语音转文字
const text = await auth.transcribeAudio(audioBase64)
// text = { text: string }

// 文字转语音
const audio = await auth.synthesizeSpeech('Hello world')
// audio = { audio_base64: string, format: 'mp3' }

场景六：分享与反馈

// 创建对话分享
const share = await auth.createShare(threadId)
// share = { share_id: string, share_url: string }

const share = await auth.createShare(threadId, ['msg-1', 'msg-2'])  // 指定消息

// 列出分享
const { shares } = await auth.listShares()

// 删除分享
await auth.deleteShare(shareId)

// 复制分享
await auth.forkShare(shareId)

// 点赞/踩消息
await auth.rateMessage(messageId, 'like')
await auth.rateMessage(messageId, 'dislike', 'Not accurate')

// 取消反馈
await auth.deleteFeedback(messageId)

场景七：钱包与计费

// 获取投资组合
const portfolio = await auth.getPortfolio()
// portfolio = { total_value_usd, tokens: [...] }

// 列出钱包
const { wallets } = await auth.listWallets()

// 创建/删除钱包
const wallet = await auth.createWallet()
await auth.deleteWallet(walletAddress)

// Coinbase Onramp
const session = await auth.createOnrampSession({
  amount: '100',  // USD
  currency: 'USD',
})
// session = { url: string } — redirect user to this URL

场景八：Credits（余额 / 充值 / Points / KYC / Referral）

服务: starchild-credit-api
Base: creditApiBase，默认 https://credit.iamstarchild.com
鉴权: Authorization: Bearer <oauth_access_token>
Scope:

• credit:read — 所有 GET（余额、流水、pending、tx、points 余额、KYC 状态、referral 查询、migration 状态）
• credit:write — 写操作（Stripe 会话、礼品卡、points 兑换、KYC 写、referral bind、migration claim）；隐含 read

OAuth App 注册时需勾选对应 scope，审核通过后 token 才会带上。

开放范围：余额/流水、Stripe、礼品卡、Points 兑换、KYC、Referral、migration reward、WOO bonus（public）均已对 OAuth 开放；命名空间写法：auth.credit.*。

初始化

const auth = new StarchildAuth({
  clientId: 'your-client-id',
  scope: 'profile chat credit:read credit:write',
  // creditApiBase: 'https://credit.iamstarchild.com', // 默认值，本地可改
  onLogin: ({ userInfo }) => console.log(userInfo),
})

余额与流水（credit:read）

// 当前余额
const bal = await auth.getCredits()
// bal.credit_balance — 可用余额
// bal.pending_credit — 待入账
// bal.total_recharged / bal.total_used
// bal.daily_balance — 订阅日额度（若有）
// bal.container_id / bal.user_id

// 扣费记录（默认近 24h，可分页 + 时间窗）
const charges = await auth.getCreditCharges({
  page: 1,
  page_size: 20,
  start_time: '2026-01-01T00:00:00Z', // 可选 ISO8601
  end_time: '2026-01-31T23:59:59Z',
})
// charges.charges[]: { amount, api_type, balance_after, description, created_at, ... }
// charges.pagination: { page, page_size, has_more }
// charges.time_range: { start_time, end_time }

// 充值记录
const topups = await auth.getCreditTopups({ page: 1, page_size: 20 })
// topups.topups[]: { amount, chain, tx_hash, balance_after, created_at, ... }

// 每日用量
const usage = await auth.getCreditDailyUsage({ days: 7 })
// usage.daily[] / usage.by_api[]

// 待入账
const pending = await auth.getPendingCredit()
// pending.status === 'no_pending' | 'pending_sync' | (有 machine 时直接带 pending_credit)

// 轮询链上/支付 tx
const tx = await auth.getCreditTxStatus(txHash)
// 1) status==='not_detected' && !credited && !pending → 继续轮询
// 2) pending && !container_id → 已进 pending_credit，可停
// 3) pending && container_id → 等 flush，继续轮询
// 4) credited === true → 已入账，停

字段速查：CreditBalance（GET /api/credits）

Stripe 充值（credit:write）

const { url } = await auth.createStripeSession({
  amount_usd: 20,
  success_url: 'https://your-app.com/billing?ok=1',
  cancel_url: 'https://your-app.com/billing?cancel=1',
})
window.location.href = url
// 支付完成后可用 getCreditTxStatus / getCredits / getPendingCredit 确认到账

响应：{ url: string } — Stripe Checkout 地址。

礼品卡（credit:write）

const r = await auth.redeemGiftCard('GIFT-CODE-XXX')
// 或 auth.redeemGiftCard({ code: 'GIFT-CODE-XXX' })
// r.amount, r.credited_to: 'machine' | 'pending'
// r.new_balance / r.pending_credit

Points 兑换 Credits（read 查余额 / write 兑换）

const pts = await auth.getPointsExchangeBalance()
// pts.available_points, pts.exchange_rate, pts.exchanged_credits, ...

const ex = await auth.exchangePoints(
  { points: 1000 },
  crypto.randomUUID(), // 推荐传 Idempotency-Key，防重试双花
)
// 也可 auth.exchangePoints(1000, idemKey)
// ex.credits_received, ex.new_credit_balance, ex.idempotent?

KYC（points 大额兑换可能要求）

const kyc = await auth.getKycStatus()
// kyc.verified / kyc.exempt / kyc.exchanged_credits / kyc.threshold_credits

if (!kyc.verified && !kyc.exempt) {
  const intent = await auth.createKycSetupIntent()
  // intent.client_secret → 交给 Stripe.js / Payment Element 完成绑卡
  // 成功后:
  await auth.verifyKyc(intent.setup_intent_id)
}

Referral

const ref = await auth.getReferralStatus()
// ref.my_referral_code, ref.can_bind, ref.has_bound_inviter, ref.invited_by

if (ref.can_bind) {
  await auth.bindReferralCode('INVITE-CODE') // credit:write，仅一次
}

const invitees = await auth.getReferralInvitees()
// invitees.invitees[], invitees.total_bonus_earned, ...

Migration 奖励

const st = await auth.getMigrationRewardStatus()
if (st.eligible && !st.already_claimed) {
  const claim = await auth.claimMigrationReward() // credit:write
  // claim.amount, claim.credited_to, claim.new_balance
}

WOO Staking Bonus（公开接口）

const woo = await auth.getWooBonus() // 默认当前登录 userInfoId
// woo.bonus_percent, woo.max_staked_woo, woo.matched_wallet

字段速查：其它常用响应

CreditChargeItem / getCreditCharges

CreditTopupItem / getCreditTopups

CreditTxStatus / getCreditTxStatus

RedeemGiftCardResponse

PointsExchangeBalance / PointsExchangeResponse

KycStatus / KycVerifyResponse

ReferralStatus / ReferralInviteesResponse

MigrationRewardClaimResponse

WooBonusResponse

完整 TypeScript 定义与字段 JSDoc 见 SDK：starchild-auth-sdk/src/types.ts（构建后 dist/index.d.ts）。

Scope 不足时

服务端返回 403，body 类似：

{ "detail": "Insufficient scope: credit:read or credit:write is required." }

写接口缺 credit:write 时：

{ "detail": "Insufficient scope: credit:write is required for this operation." }

集成方应引导用户重新 login() 并申请完整 credit scopes，或在 OAuth App 控制台勾选后重新授权。

场景九：消息排队与注入（Agent 运行中发送新消息）

当 Agent 正在处理消息时（SSE 流未结束），用户可能发送新消息。这时不能直接调用 /chat/stream，而是将消息加入排队队列。

前端实现模式（参考 starchild-web）

// 1. 检查 Agent 是否正在运行
const isAgentActive = isStreaming || !!agentBackgroundRunning[threadId]

if (isAgentActive) {
  // 2. 消息加入本地队列（不立即发送到后端）
  const queuedId = `queued-${Date.now()}`
  dispatch(addToMessageQueue({
    threadId,
    message: {
      id: queuedId,
      content: message,
      images: images,      // 可选：base64 图片
      files: files,        // 可选：已上传文件引用
      quote: quoteOptions, // 可选：引用的消息
      status: 'pending',   // pending → sending → sent
      createdAt: Date.now(),
    },
  }))

  // 3. 显示 "当前消息已排队，Agent 完成后自动发送" 提示
  dispatch(updateQueuedMessageStatus({ threadId, messageId: queuedId, status: 'sending' }))

  // 4. 后端在 /chat/stream 完成后，检查 messageQueue
  //    取出 FIFO 的第一条，调用下一个 /chat/stream
} else {
  // Agent 空闲，直接发送
  await sendToChatStream(message, images, files)
}

/chat/stream 请求体格式（完整）

{
  "message": "Hello, analyze this data",
  "thread_id": "thread-uuid",
  "channel": "web",
  "message_id": "queued-1234567890",
  "model": "claude-3-5-sonnet-20241022",
  "images": [
    {
      "base64_data": "...",
      "media_type": "image/png"
    }
  ],
  "files": [
    {
      "name": "data.csv",
      "workspace_path": "/workspace/data.csv",
      "mime_type": "text/csv",
      "size": 1024
    }
  ],
  "quote": {
    "source_message_id": "msg-abc123",
    "quoted_text": "The original message text...",
    "source_role": "user"
  }
}

/chat/stream 响应流程

POST /chat/stream → SSE 连接建立
  ← event: agent_start    { session_key: "sess-xxx" }
  ← event: text_delta     { text: "I'll analyze..." }
  ← event: tool_use       { tool_name: "read_file", tool_input: {...} }
  ← event: tool_output    { tool_output: "file content..." }
  ← event: text_delta     { text: "Based on the data..." }
  ← event: agent_end      { stop_reason: "end_turn" }
SSE 连接关闭
→ 后端检查 messageQueue[threadId]
→ 如果有排队消息 → 自动开始下一个 /chat/stream

SSE 事件类型详解

/chat/runs/cancel 取消运行

// POST /chat/runs/cancel?thread_id=xxx
await auth.cancelRun(threadId)
// 这会中断当前正在运行的 SSE 流
// SSE 连接会收到 agent_end 或 agent:interrupted 事件后关闭

/chat/stream/reconnect 断线重连

当 SSE 连接意外断开（网络问题、页面切换），用 session_key 重连：

// POST /chat/stream/reconnect?session_key=sess-xxx&channel=web
const stream = await auth.reconnectStream(sessionKey)

// reconnect 返回的 SSE 事件格式相同
// 它会从中断点继续推送剩余的事件
// 如果 Agent 已完成，会立即收到 agent_end

场景十：Agent 集成（直接 token 注入）

Agent 可以在没有浏览器 popup 的情况下使用 SDK：

import { StarchildAuth } from 'starchild-auth-sdk'

// Agent 从环境变量或 OAuth 回调获取 token
const accessToken = process.env.STARCHILD_TOKEN!

const auth = new StarchildAuth({
  clientId: process.env.CLIENT_ID!,
  scope: 'profile chat',
  autoLogin: false,  // 不弹出浏览器窗口
  onLogin: () => {},
})

// 注入 token（绕过 popup 流程）
;(auth as any)._accessToken = accessToken

// 现在可以调用所有方法
const threads = await auth.listThreads()
const message = await auth.sendMessage('Summarize my threads')

场景十一：推荐 Chat UI 组件集成

Auth SDK 是纯 API 层（无 UI 组件）。以下推荐两个开源 React Chat 组件库，并给出与 SDK SSE 流对接的完整适配器代码，帮助第三方应用快速搭建 ChatGPT 风格的对话界面。

官方文档：

• assistant-ui: https://www.assistant-ui.com/docs/runtimes/custom/local-runtime
• MUI X Chat: https://mui.com/x/react-chat/backend/adapters/

选型对比

共享：SSE 流解析 helper

两个适配器都需要解析 SDK sendMessage() 返回的 SSE Response。提取为共享函数：

// lib/starchild-sse.ts
import type { SSEEvent } from 'starchild-auth-sdk'

/**
 * Parse Starchild SSE Response into an async iterable of events.
 * Stops early if the abort signal fires.
 *
 * SDK sendMessage() returns a raw Response whose body is an SSE stream.
 * Each line starting with "data: " contains a JSON event:
 *   agent_start | text_delta | tool_use | tool_output | agent_end | error
 */
export async function* parseStarchildSSE(
  response: Response,
  signal?: AbortSignal,
): AsyncGenerator<SSEEvent> {
  if (!response.ok) {
    const body = await response.text().catch(() => '')
    throw new Error(`Chat API ${response.status}: ${body.slice(0, 200)}`)
  }
  const reader = response.body!.getReader()
  const decoder = new TextDecoder()
  let buffer = ''

  while (true) {
    if (signal?.aborted) {
      reader.cancel()
      break
    }
    const { done, value } = await reader.read()
    if (done) break

    buffer += decoder.decode(value, { stream: true })
    const lines = buffer.split('\n')
    buffer = lines.pop() || ''

    for (const line of lines) {
      if (!line.startsWith('data: ')) continue
      try {
        yield JSON.parse(line.slice(6)) as SSEEvent
      } catch {
        // Skip malformed JSON lines
      }
    }
  }
}

方案 A：assistant-ui（推荐）

安装

# 推荐使用 pnpm（更快、磁盘占用更小）；yarn / bun 亦可
pnpm add @assistant-ui/react
# 或: yarn add @assistant-ui/react
# 或: npm install @assistant-ui/react

# 脚手架生成 Thread 组件（shadcn / Tailwind 风格）
npx assistant-ui init
npx assistant-ui add thread

ChatModelAdapter 实现

assistant-ui 的 LocalRuntime 只需实现一个 ChatModelAdapter.run() 函数（async * generator）。在循环中 yield 累积内容（每次替换上一次，不是 delta）：

// runtime/starchild-adapter.ts
import type { ChatModelAdapter } from '@assistant-ui/react'
import { StarchildAuth } from 'starchild-auth-sdk'
import { parseStarchildSSE } from '@/lib/starchild-sse'

/**
 * Create an assistant-ui ChatModelAdapter backed by Starchild Auth SDK.
 * The auth instance is initialized in the Provider and passed in.
 */
export function createStarchildAdapter(auth: StarchildAuth): ChatModelAdapter {
  return {
    async *run({ messages, abortSignal, unstable_threadId }) {
      // 1. Extract last user message text
      const lastUser = [...messages].reverse().find(m => m.role === 'user')
      const text = lastUser?.content
        .filter(c => c.type === 'text')
        .map(c => c.text)
        .join('\n') ?? ''

      if (!text) {
        yield { content: [{ type: 'text', text: '' }] }
        return
      }

      // 2. Call SDK sendMessage — returns SSE Response
      //    threadId: continue existing thread, or omit to create new
      const response = await auth.sendMessage(text, {
        threadId: unstable_threadId,
      })

      // 3. Parse SSE stream and yield cumulative content
      let fullText = ''
      const toolCalls = new Map<string, any>()

      for await (const event of parseStarchildSSE(response, abortSignal)) {
        switch (event.type) {
          case 'agent_start':
            // event.session_key — save for reconnect if needed
            break

          case 'text_delta':
            fullText += event.text
            yield {
              content: [
                ...(fullText ? [{ type: 'text' as const, text: fullText }] : []),
                ...Array.from(toolCalls.values()),
              ],
            }
            break

          case 'tool_use': {
            // Accumulate tool calls outside the loop (per assistant-ui best practice)
            const id = event.tool_use_id || crypto.randomUUID()
            toolCalls.set(id, {
              type: 'tool-call' as const,
              toolCallId: id,
              toolName: event.tool_name,
              args: event.tool_input,
              argsText: JSON.stringify(event.tool_input),
            })
            yield {
              content: [
                ...(fullText ? [{ type: 'text' as const, text: fullText }] : []),
                ...Array.from(toolCalls.values()),
              ],
            }
            break
          }

          case 'tool_output': {
            // Update the matching tool call with its result.
            // IMPORTANT: create a new object (not mutate) so React detects the change.
            const id = event.tool_use_id
            if (id && toolCalls.has(id)) {
              const existing = toolCalls.get(id)
              toolCalls.set(id, { ...existing, result: event.tool_output })
              yield {
                content: [
                  ...(fullText ? [{ type: 'text' as const, text: fullText }] : []),
                  ...Array.from(toolCalls.values()),
                ],
              }
            }
            break
          }

          case 'agent_end':
            // Stream complete — final yield already done above
            break

          case 'error':
            throw new Error(event.message)

          case 'agent:interrupted':
            // User cancelled or timeout — stop yielding
            break
        }
      }

      // Ensure at least one yield with content
      if (!fullText && toolCalls.size === 0) {
        yield { content: [{ type: 'text', text: '' }] }
      }
    },
  }
}

RuntimeProvider 组装

// runtime/StarchildRuntimeProvider.tsx
'use client'
import type { ReactNode } from 'react'
import {
  AssistantRuntimeProvider,
  useLocalRuntime,
} from '@assistant-ui/react'
import { StarchildAuth } from 'starchild-auth-sdk'
import { createStarchildAdapter } from './starchild-adapter'

// Singleton auth instance — SDK handles token refresh internally
const auth = new StarchildAuth({
  clientId: process.env.NEXT_PUBLIC_STARCHILD_CLIENT_ID!,
  scope: 'profile chat',
  onLogin: ({ userInfo }) => console.log('Logged in:', userInfo.agentName),
  onTokenRefreshFailed: () => {
    // Session expired — redirect to login or show login button
    window.location.reload()
  },
})

export function StarchildRuntimeProvider({
  children,
}: Readonly<{ children: ReactNode }>) {
  const runtime = useLocalRuntime(createStarchildAdapter(auth))
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  )
}

多线程列表（可选）

如需左侧线程列表（类似 ChatGPT 侧边栏），实现 RemoteThreadListAdapter 并传入 useLocalRuntime 的 adapters.threadList。

⚠️ 接口验证提醒：RemoteThreadListAdapter 的方法签名可能随 assistant-ui 版本变化。以下示例基于公开文档的常见模式，集成前请务必查阅最新文档：https://www.assistant-ui.com/docs/runtimes/concepts/threads

import { useLocalRuntime } from '@assistant-ui/react'
import type { RemoteThreadListAdapter } from '@assistant-ui/react'

// Thread list adapter — bridges SDK thread API to assistant-ui sidebar
const threadListAdapter: RemoteThreadListAdapter = {
  // Called on mount — load thread list from SDK
  async getThreads() {
    const { threads } = await auth.listThreads()
    return threads.map(t => ({
      id: t.thread_id,
      title: t.title || 'New Chat',
      createdAt: t.created_at ? new Date(t.created_at) : new Date(),
    }))
  },

  // Called when user clicks a thread in the sidebar
  async switchToThread(threadId: string) {
    // assistant-ui will call this to switch the active thread.
    // Messages are loaded separately via the adapter's run() or initialMessages.
    // If you need to pre-load history, use auth.listMessages(threadId)
    // and pass them as initialMessages to the runtime.
  },

  // Called when user creates a new thread
  async createThread() {
    const thread = await auth.createThread()
    return { id: thread.thread_id }
  },

  // Called when user deletes a thread
  async deleteThread(threadId: string) {
    await auth.deleteThread(threadId)
  },
}

// In provider:
const runtime = useLocalRuntime(createStarchildAdapter(auth), {
  adapters: { threadList: threadListAdapter },
})

页面中使用

// app/chat/page.tsx
import { Thread } from '@/components/assistant-ui/thread'
import { StarchildRuntimeProvider } from '@/runtime/StarchildRuntimeProvider'

export default function ChatPage() {
  return (
    <StarchildRuntimeProvider>
      <Thread />
    </StarchildRuntimeProvider>
  )
}

方案 B：MUI X Chat

仅推荐给已在用 MUI Material 主题的项目。@mui/x-chat 会强制带入 @mui/material + @emotion/* 依赖树，非 MUI 项目引入成本高。

安装

# 推荐使用 pnpm（更快、磁盘占用更小）；yarn / bun 亦可
pnpm add @mui/x-chat @mui/material @emotion/react @emotion/styled
# 或: yarn add @mui/x-chat @mui/material @emotion/react @emotion/styled
# 或: npm install @mui/x-chat @mui/material @emotion/react @emotion/styled

ChatAdapter 实现

MUI X Chat 的 ChatAdapter.sendMessage() 必须返回 Promise<ReadableStream<ChatMessageChunk>>。需要将 SDK 的 SSE 流转换为 MUI 的 chunk 协议（start → text-start → text-delta → text-end → finish）：

// adapters/starchild-mui-adapter.ts
import type { ChatAdapter, ChatMessageChunk } from '@mui/x-chat/headless'
import { StarchildAuth } from 'starchild-auth-sdk'
import { parseStarchildSSE } from '@/lib/starchild-sse'

// Module-level state for reconnect / cancel
let lastSessionKey = ''
let currentThreadId = ''

export function createStarchildMuiAdapter(auth: StarchildAuth): ChatAdapter {
  return {
    async sendMessage({ message, signal }) {
      // Extract text from user message.
      // ChatMessage.content type varies by MUI version — handle both
      // string and structured content arrays defensively.
      const text = typeof message.content === 'string'
        ? message.content
        : Array.isArray(message.content)
            ? (message.content as Array<{ type: string; text?: string }>)
                .filter(c => c.type === 'text' && c.text)
                .map(c => c.text!)
                .join('\n')
            : String(message.content ?? '')

      // Call SDK sendMessage — returns SSE Response
      const response = await auth.sendMessage(text, {
        threadId: currentThreadId || undefined,
      })

      const messageId = crypto.randomUUID()
      const textId = crypto.randomUUID()

      // Transform SSE → MUI ReadableStream<ChatMessageChunk>
      return new ReadableStream<ChatMessageChunk>({
        async start(controller) {
          controller.enqueue({ type: 'start', messageId })

          let textStarted = false
          try {
            for await (const event of parseStarchildSSE(response, signal)) {
              switch (event.type) {
                case 'agent_start':
                  lastSessionKey = event.session_key
                  if (event.thread_id) currentThreadId = event.thread_id
                  break

                case 'text_delta':
                  if (!textStarted) {
                    controller.enqueue({ type: 'text-start', id: textId })
                    textStarted = true
                  }
                  controller.enqueue({
                    type: 'text-delta',
                    id: textId,
                    delta: event.text,
                  })
                  break

                case 'tool_use': {
                  // ⚠️ Tool-call chunk types are MUI-version-specific.
                  // The names below follow the MUI X Chat streaming protocol
                  // convention but may differ — always verify aga

…(truncated)