@kanyun-ai-infra/agenthub 1.9.0 → 1.11.0

package/README.md

@@ -25,7 +25,7 @@ npx rush-ai skill install @kanyun/agenthub-sdk
 ```
 
 skill 内容和这份 README 保持同步；改了 public API 时必须同步改 skill。公开方法与示例见
-[AgentHub API 与 SDK 文档](https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-methods)。剩下的正文是给人类读者的完整参考。
+[AgentHub API 与 SDK 文档](https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk)。剩下的正文是给人类读者的完整参考。
 
 ## 安装
 
@@ -37,8 +37,8 @@ pnpm add @kanyun-ai-infra/agenthub
 需要 Node 18+，因为 SDK 使用全局 `fetch`。
 
 如果调用方是 Java、Python 或 Shell（curl），请优先看
-<https://agenthub.zhenguanyu.com/docs/api-and-sdk/multi-language-examples>（Python / Java）
-或 <https://agenthub.zhenguanyu.com/docs/api-and-sdk#rest-flow>（curl）。
+<https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#multi-language>（Python / Java）
+或 <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#rest-flow>（curl）。
 
 ## 快速开始
 
@@ -108,6 +108,23 @@ const ready = await agenthub.sessions.wait(session.sessionId); // status === "re
 > 要额外给槽位绑一个 Environment，才有资源规格定制、canary 灰度、drift 检测、
 > 一键回滚这些能力：完整走一遍见下方「完整参考」里的发布闭环六幕示例。
 
+### 代表用户调用（仅第一方服务）
+
+服务到服务的场景（门户、后台任务等）可以用**第一方服务 token** 声明「代表某个用户」：
+给客户端传 `actAs`（用户 LDAP），此后该客户端发出的**每个**请求——JSON、multipart
+上传、SSE（首连与带 `Last-Event-ID` 的重连）——都带代表声明头。
+
+```ts
+const agenthub = new PilotPlatformClient({
+  token: process.env.PILOT_SERVICE_TOKEN, // 第一方服务 token（actor:delegate）
+  actAs: "zhangsan", // 代表 zhangsan 行事
+});
+```
+
+仅第一方服务 token 可用：其他 token 带它会得到 403 `ACT_AS_NOT_ALLOWED`（服务端开关
+未开：403 `ACT_AS_DISABLED`；值不是用户标识：400 `ACT_AS_INVALID`）。空串 / 纯空白在
+构造时即抛。`defaultHeaders` 或单次请求的 `headers` 里写同名头不能覆盖 `actAs`。
+
 ## 核心模型
 
 ```text
@@ -216,19 +233,20 @@ https://octopus.zhenguanyu.com/#/trace-explorer?env=<test|online>&time=<起-止,
 ## 完整参考
 
 下面这些内容日常写业务代码用不到，需要时查
-[AgentHub 文档站](https://agenthub.zhenguanyu.com/docs/api-and-sdk) 对应小节
+[AgentHub 文档站](https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk) 对应小节
 （这份 README 会随 npm 包分发到别的项目里，下面全部是可以直接点开的网址，不是仓库内相对路径）：
 
 | 你想找 | 链接 |
 | --- | --- |
-| 资源方法速查（projects / agents / stages / environments / sessions / files / profiles） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-methods> |
+| 资源方法速查（projects / agents / stages / environments / sessions / files / profiles） | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk> |
 | 记忆接口（写入 / 读回 / 确认 / 清空 / 策略）逐端点字段、outcome 与 REST 对照 | <https://agenthub.zhenguanyu.com/v1/docs/agent-memory#api> |
-| "发布 → 部署 → 晋级 → 灰度 → 回滚"完整六幕示例 | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#release-loop> |
-| Client 配置全部选项、获取 token | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-client-config> |
-| Runtime template 解析顺序 | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#runtime-template> |
-| Model 别名、Dry runs | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#model-dry-run> |
-| 调用方是 Java / Python（最后手段，官方只推荐这份 TS SDK） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk/multi-language-examples> |
-| 调用方是 Shell（curl） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#rest-flow> |
+| "部署 test → 晋级 production → 回滚"的 Stage 序列 | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#stages> |
+| Client 配置全部选项与错误类型 | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#client> |
+| 获取 token、地址与 Header | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#setup> |
+| Project 默认运行模板（`defaultRuntimeTemplateRefName`） | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#projects> |
+| Dry run（`agents.create` 只校验不落库） | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#agents> |
+| 调用方是 Java / Python（最后手段，官方只推荐这份 TS SDK） | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#multi-language> |
+| 调用方是 Shell（curl） | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk#rest-flow> |
 
 ## 错误
 
@@ -254,3 +272,45 @@ try {
   throw err;
 }
 ```
+
+
+## 实时语音（浏览器）
+
+从 `@kanyun-ai-infra/agenthub/realtime` 导入 `createRealtimeVoiceClient`。浏览器只持有短期通话票；接入方后端调用 `client.sessions.createVoiceTicket(sessionId, options?)` 换票，`options` 可传 `signal: AbortSignal`，返回 `{ ticket, gatewayUrl, expiresAt }`；前端使用返回的 `gatewayUrl`，`getTicket()` 仅返回其中的 `ticket` 字符串，不能把平台 token 放进前端。主入口不加载浏览器代码。转写 `role` 为 `user` 或 `assistant`。
+
+```ts
+import { createRealtimeVoiceClient } from "@kanyun-ai-infra/agenthub/realtime";
+
+const voice = createRealtimeVoiceClient({
+  gatewayUrl: "wss://your-voice-gateway.example/",
+  getTicket: async () => {
+    const response = await fetch("/api/voice-ticket", { method: "POST" });
+    if (!response.ok) throw new Error("无法取得通话票");
+    const { ticket } = await response.json();
+    return ticket;
+  },
+  onTranscript: ({ role, text, final, turnSeq, turnId }) => {
+    renderTranscript({ role, text, final, turnSeq, turnId });
+  },
+  onState: (state) => renderState(state), // listening / thinking / speaking
+  onTurnEnd: ({ turnSeq, turnId }) => finishTurn({ turnSeq, turnId }),
+  onError: ({ code, retryable }) => showVoiceError({ code, retryable }),
+});
+
+// 在点击等用户手势中调用；start 在网关 ready 后完成，失败时拒绝 Promise。
+startButton.onclick = () => { void voice.start().catch(() => {}); };
+interruptButton.onclick = () => voice.interrupt();
+stopButton.onclick = () => { void voice.stop(); };
+```
+
+示例中的 `/api/voice-ticket`、按钮与渲染函数由接入方提供。`getTicket()` 每次连接都返回新票（无填充的 base64url 字符串），票只放在 WebSocket 握手子协议中；`gatewayUrl` 使用 `wss:`，本地测试可用 `ws:`，不含查询串、片段或 URL 凭据。SDK 不记录票，也不传播取票回调或网关的原始异常文本。
+
+项目开启录音后，通话会被录音，保存 14 天；默认不录。接入页面应在开始前说明录音与保存期限。一期实时通话与文字回合上下文不互通。
+
+采集需要 HTTPS 安全上下文（本地 localhost 可用）与麦克风权限。SDK 使用 AudioWorklet 将音频转为 16 kHz 单声道 PCM16，每帧 20 ms；播放接收 24 kHz PCM16，按轮排队，收到打断即清空。页面 CSP 需允许 `blob:` AudioWorklet 模块。支持目标为桌面 Chrome / Edge / Safari、iOS Safari 和微信内置浏览器；需要宿主提供 `AudioContext`、`AudioWorklet` 与 `getUserMedia`，缺失时通过 `onError` 报错。小程序和 App 内 WebView 不在本期范围，具体设备仍需接入方验收。
+
+`stop()` 立即停止麦克风，发送本轮最终播放回执，再发 `end` 并关闭连接；Worklet 无响应时最多等待 200 ms，使用最后确认的播放统计。页面卸载同步清理。播放回执按 `turnSeq` 归属，`playedMs` 计实际渲染样本，不计排队音频；`firstPlayedAt` 是 Unix 毫秒，尚未播放时为 `null`。`turn_end` 表示业务回合收尾，不是音频 EOF。SDK 记住提前到达的回合终态，在播放排空时发送 final；迟到尾块沿用首次播放时刻并累加 playedMs，再补累计 final。记录保留最近 128 轮，尚在播放队列中的轮不会被淘汰。网关的文本截止不受晚回执影响，晚回执用于录音统计。
+
+断线或收到 `reconnecting` 时保留播放队列、暂停采集，换新票并带原 `callId` 重连。每通话最多自动接手 5 次，退避从 250 ms 增至 4 s；取票与 WebSocket upgrade 最多等待 10 s，open 后另等 ready 最多 30 s，音频初始化最多 30 s。WebSocket 握手已验票，SDK 立即处理下行消息；转写、状态回调与播放可能早于 start() 完成。ready 只控制麦克风上行和 start() 完成，interrupted 始终立即清空播放。`no_response` 仅以 `NO_RESPONSE` 可重试通知上报，不主动接手通话。无法恢复时释放资源并报不可重试错误，可由用户重新开始。主动 stop 后再次 start 是新通话。
+
+仓库内运行本地浏览器冒烟：`pnpm --filter @kanyun-ai-infra/agenthub run smoke:realtime`。该入口先按依赖顺序构建 SDK 及 contracts，再用本地假网关和无头 Chrome 验证采集、播放、打断、回执与停止；运行前需安装仓库依赖及 Chrome，不需要通话凭据。