@blade-hq/agent-client 2608.0.7-beta.0 → 2608.0.7-beta.1

package/README.md

@@ -2,11 +2,12 @@
 
 Blade Agent 的框架无关客户端。浏览器和 Node.js 都能用；用 Vue、Svelte 或自建 UI 的团队直接用这个包，React 团队一般用上层的 `@blade-hq/agent-react`。
 
-它做三件事：
+它做四件事：
 
 1. **实时会话**（`AgentSession`）：把 Socket.IO 协议、历史加载、流式合流、断线重连全部封装掉，你只面对"状态快照 + 动作 + 事件"。
 2. **登录**：`client.auth.login()` 弹窗授权，用户点一下"许可授权"就拿到访问令牌，不用手工复制粘贴。
 3. **REST**：类型化会话和模型目录（`client.sessions.*`、`client.models.list()`）。其他长尾接口对照 Swagger 用原生 `fetch` + `client.token` 调用。
+4. **部署端点**：从同源 `config.json` 读取其他 Blade 服务的公开地址，不根据主机名和固定端口猜测拓扑。
 
 ```bash
 npm install @blade-hq/agent-client
@@ -47,6 +48,27 @@ const client = new BladeClient({
 })
 ```
 
+## 部署端点
+
+Blade 平台前端需要跳转其他服务时，读取当前 origin 的公开配置：
+
+```ts
+import { loadPlatformEndpoints, resolveServiceUrl } from "@blade-hq/agent-client"
+
+const endpoints = await loadPlatformEndpoints()
+const hubUrl = resolveServiceUrl(endpoints, "hub", "/skills/42")
+if (hubUrl) window.open(hubUrl)
+```
+
+`loadPlatformEndpoints()` 请求 `config.json`，超过 3 秒、网络失败或配置非法时返回空配置；
+调用方应隐藏对应入口。文件只能放浏览器可访问的公开地址，不能写 Docker 服务名、令牌或
+其他内部配置。应用部署在子路径时，通过 `baseUrl` 显式传入部署根路径。
+`resolveServiceUrl()` 的 `path` 只接受服务内相对路径；绝对 URL、反斜杠和越出服务
+base path 的路径返回 `null`。
+
+公开类型为 `PlatformEndpoints`、`PlatformServiceName`、`LoadPlatformEndpointsOptions`；
+需要同步初始化时可直接使用 `EMPTY_PLATFORM_ENDPOINTS`。
+
 ## BladeClient
 
 ### 构造
@@ -56,7 +78,6 @@ new BladeClient({
   baseUrl: "https://blade.example.com", // 后端地址；同域部署可传 ""
   token: "sk-blade-xxx",                // 可选：PAT。不传则用 cookie 或 login()
   tokenStorage: "local",                // 可选：login() 的令牌存哪（"local" 默认 / "memory"）
-  streamTokens: false,                   // 可选：只接收完成态内容，不订阅逐 token 增量
 })
 ```
 
@@ -77,15 +98,6 @@ await client.auth.getProviders() // 服务端支持的登录方式
 
 `login()` 失败时的错误都带中文原因：弹窗被拦截、窗口被关闭、超时。
 
-令牌要留在自己的服务端时，浏览器只把授权回调拿到的一次性 code 交给后端，由后端换：
-
-```ts
-// ExchangeCodeParams -> ExchangeCodeResult
-const { access_token } = await client.auth.exchangeCode({ code, state, clientOrigin })
-```
-
-`clientOrigin` 要和发起授权时用的 origin 一致；服务端调用会自动补 `Origin` 头。
-
 ## 会话：client.sessions
 
 ### 实时对话（推荐入口）
@@ -134,80 +146,12 @@ Solution 和 Skill 都声明为 `{ path, content }[]` 文本文件；SDK 负责
 
 ```ts
 await client.sessions.listSessions()                  // 会话列表
-await client.sessions.searchOwnedContent({ q: "项目报告" }) // 搜索自己的对话和文件名
 await client.sessions.getSession(id)                  // 会话详情
 await client.sessions.updateSession(id, { intent: "新标题" })
 await client.sessions.deleteSession(id)
 await client.sessions.getSessionTurns(id)             // 历史消息（投影格式，与实时流同构）
 ```
 
-### 会话回放（演示 / 彩排）
-
-拿一个已经聊完的会话当素材，重现当时的回复和工具调用，**完全不调用模型**。
-用来做演示和彩排：离线可跑、不花钱、不会临场翻车。
-
-**它不是把现有会话切成回放模式，而是派生一个新会话**，源会话原样不动：
-
-```ts
-// 1. 能不能拿它当素材（有并行子智能体、运行快照不完整的不行）
-const { supported, reason } = await client.sessions.getReplayPreview(sourceId)
-if (!supported) return show(reason)   // reason 可直接展示给用户
-
-// 2. 派生回放会话——这一步才是"进入回放"，返回的是一个全新的 session_id
-const { session_id: replayId } = await client.sessions.startReplaySession(sourceId)
-const fast = await client.sessions.startReplaySession(sourceId, 2)  // 或显式 1 | 2 | 5
-
-// 3. 连上它，一出生就带着 replay 状态
-const session = await client.sessions.connect(replayId)
-session.getState().replay
-// → { isReplay: true, speed: 5, sourceSessionId: sourceId }
-```
-
-不传倍速时用 `DEFAULT_REPLAY_SPEED`；所有创建入口都该用它，免得同一个源对话
-从不同入口开出来速度不一样。
-
-**连上之后不会自动播——它跟用户对台词**（下面的 `session` 都是第 3 步连上的**回放会话**）：
-
-```ts
-// 源会话当初第一句问的是"帮我查下当前目录"
-await session.send("帮我查下当前目录")   // 对得上：按倍速重现当时的回复和工具调用
-await session.send("今天天气怎么样")     // 对不上：抛 replayMismatch 等你决定（见下）
-```
-
-**回放中的状态和动作**都挂在会话上，和 `send()` 同级：
-
-```ts
-session.getState().replay      // { isReplay, speed, sourceSessionId } | null（不是回放会话）
-session.getState().viewerRole  // "viewer" 表示只读，改不动回放
-await session.setReplaySpeed(2)
-await session.exitReplay()     // 退出回放，之后的对话真的运行
-```
-
-改回放是 owner 专属（服务端 `PATCH` 走 owner 校验），只读身份下这两个动作是 no-op。
-
-`replay` 是 `SessionState` 的一部分，跟着快照订阅走——Vue 直接接 `shallowRef` 即可，
-不用自己拉状态：
-
-```ts
-const state = shallowRef(session.getState())   // session = connect(replayId) 的返回值
-session.subscribe(() => (state.value = session.getState()))
-// 模板里 state.value.replay?.isReplay / state.value.replay?.speed
-```
-
-连接会话时会一并拉好初始回放状态，所以第一帧就知道自己在不在回放。
-
-**输入冲突**：用户说的话和录制内容对不上时，服务端会推 `replayMismatch`，必须在事件里给出决定：
-
-```ts
-session.on("replayMismatch", ({ expectedMessage, actualMessage, respond }) => {
-  respond("keep_replay")      // 按录制内容继续
-  // respond("continue_replay")  // 从这里开始真的运行
-})
-```
-
-`replayMismatch` **只交给最先注册的处理器**；一个都没注册时默认 `continue_replay`
-（静默转为真实运行）。React 应用可直接用 `@blade-hq/agent-react` 的 `useReplay()`。
-
 ### 工作区文件
 
 ```ts
@@ -226,41 +170,13 @@ await chat.countFiles()                         // 递归统计，不含目录
 await chat.downloadFile("输出/简历.md", "简历.md") // 浏览器下载
 ```
 
-对符合评价条件的最新整体结果，可读取或更新当前用户的反馈：
-
-```ts
-const feedback = await client.sessions.listResultFeedback(id)
-await client.sessions.putResultFeedback(id, assistantEntryId, {
-  helpful: false,
-  reason: "incomplete",
-})
-```
-
-`ResultFeedbackReason` 是固定枚举；Server 会校验结果资格、写权限，并自行推导 Chat / 软件工厂场景和项目 ID。
-
 ### 模型目录
 
 ```ts
-const { default: defaultModel, models, baseUrl, defaultServiceModel } = await client.models.list()
-// models: Array<{ id, label, serviceModelId }>
-// baseUrl: 平台默认模型服务的 OpenAI 兼容地址，自建应用带用户令牌可直接调；
-//          各部署端口不同，别写死，老版本 Server 返回空串。
+const { default: defaultModel, models } = await client.models.list()
+// models: Array<{ id, label }>
 ```
 
-**建会话选模型用 `default` / `id`，直接调 `baseUrl` 用 `defaultServiceModel` / `serviceModelId`。**
-两套名字不通用：`id` 是平台内部标识，平台接了多个模型服务时形如
-`provider-xxx::deepseek-v4-flash`，拿它去调 `baseUrl` 只会得到「模型不存在」。
-`serviceModelId` 为空串表示这个模型不在 `baseUrl` 那个服务上，做模型选择器时按它过滤。
-
-```ts
-// 自己调模型服务
-const body = { model: defaultServiceModel, messages, stream: true }
-```
-
-`baseUrl` 是**服务端视角**的地址。平台常配成 `http://127.0.0.1:30000/v1`——从自己后端转发
-没问题，直接交给浏览器就指向用户自己的机器了。默认形态是后端透传（密钥本来也不该进浏览器），
-浏览器直连只适合这个地址对浏览器同样可达的场景。
-
 ## AgentSession
 
 一个会话的实时状态机。**状态归属实例**：同一页面建多个会话互不干扰。
@@ -277,8 +193,6 @@ chat.getState()
 //   mode,            "planning" | "executing" | null
 //   connection,      连接状态："connected" | "connecting" | "reconnecting" | "disconnected"
 //   errorMessage,    最近一次运行错误
-//   replay,          回放状态：{ isReplay, speed, sourceSessionId } | null
-//   viewerRole,      "owner" | "viewer" | null（只读身份改不动会话）
 //   turns, askAnswers, agentLoops, activeCompaction   进阶字段
 // }
 
@@ -473,29 +387,6 @@ function Message({ message }: { message: ChatMessage }) {
 }
 ```
 
-### 让用户挑一个技能来做事
-
-自己实现技能选择器时，用 `transformSlashCommand` 把选中的技能翻译成智能体能执行的一段话：
-
-```ts
-import { transformSlashCommand, type SkillMentionAvailability } from "@blade-hq/agent-client"
-
-transformSlashCommand("org/data-analysis", "分析这份季度报表")
-// "请使用 org/data-analysis skill 完成任务\n分析这份季度报表"
-```
-
-第三个参数说明这个技能眼下能不能直接用。技能装没装、加载没加载，用户不需要知道，但智能体需要——传进来之后它会被翻译成对应的 CLI 步骤：
-
-```ts
-// Blade Hub 上已安装、但当前会话还没加载：要求先 use
-transformSlashCommand(skillId, prompt, { local: false, installed: true })
-
-// Blade Hub 上还没安装：要求先 install 再 use
-transformSlashCommand(skillId, prompt, { local: false, installed: false })
-```
-
-不传第三个参数时按本地已有处理，和不带这个参数的老用法结果一致。
-
 ## 常见问题
 
 | 现象 | 原因与解法 |
@@ -516,11 +407,10 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 - **SDK 身份**：`SDK_NAME`、`SDK_VERSION`
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
-- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`GlobalSearchResult`、`GlobalSearchResultItem`、`GlobalSearchConversationResult`、`GlobalSearchFileResult`、`SessionHistory`、`SessionContextStats`、`ResultFeedback`、`ResultFeedbackReason`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
-- **会话回放**：`ReplayState`、`ReplaySpeed`、`ReplayPreview`、`ReplaySnapshot`、`toReplaySnapshot`、`DEFAULT_REPLAY_SPEED`
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`SessionHistory`、`SessionContextStats`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
 - **会话状态机**：`SessionHub`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
 - **页面协作**：`EmbeddedChat`、`EmbeddedChatOptions`、`CommandHandler`、`CommandEnvelope`、`InboundAction`、`InboundEnvelope`、`isCommandEnvelope`、`isInboundEnvelope`
-- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`PostChatFollowup`、`FinalArtifact`、`latestPostChatFollowup`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
 - **Solution / 任务协议**：`Solution`、`SolutionAppField`、`SolutionAppState`、`SolutionAppUiConfig`、`SolutionRef`、`PublishedSolutionRef`、`ExistingSolutionRef`、`PreparedSolution`、`PreparedSolutionAsset`、`LayoutType`、`BizRole`、`TaskStatus`、`BackgroundTask`、`BackgroundTaskStopResult`
 - **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
-- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`
+- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`

package/dist/blade-client.d.ts

@@ -23,8 +23,6 @@ export interface BladeClientOptions {
     tokenStorage?: TokenStorageMode;
     fetchImpl?: typeof fetch;
     onRefreshSuccess?: () => void | Promise<void>;
-    /** 是否订阅逐 token 增量，默认 true。关闭后仍接收完整消息和语义事件。 */
-    streamTokens?: boolean;
 }
 export declare class BladeClient {
     private refreshPromise;

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { BladeClient } from "./blade-client";
 export type { BladeClientOptions, UploadProgress } from "./blade-client";
 export { BladeApiError } from "./rest";
 export type { LoginOptions, LoginResult, TokenStorageMode } from "./auth-login";
+export { EMPTY_PLATFORM_ENDPOINTS, loadPlatformEndpoints, resolveServiceUrl, } from "./platform-endpoints";
+export type { LoadPlatformEndpointsOptions, PlatformEndpoints, PlatformServiceName, } from "./platform-endpoints";
 export { SDK_NAME, SDK_VERSION } from "./version";
 export { AgentSession } from "./session/agent-session";
 export type { AttachAppOptions, SendOptions } from "./session/agent-session";
@@ -9,32 +11,30 @@ export { SessionHub } from "./session/hub";
 export type { AgentSessionEvents, AgentSessionEventName } from "./session/events";
 export { SessionSetupError } from "./session/definition";
 export type { SessionConfig, SessionDefinition, SessionSetupStage, SkillDefinition, TextFile, SolutionDefinition, } from "./session/definition";
-export { createInitialSessionState, reconcileOptimisticUserTurns, toReplaySnapshot, } from "./session/state";
-export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, ReplaySnapshot, SessionState, } from "./session/state";
+export { createInitialSessionState } from "./session/state";
+export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, SessionState, } from "./session/state";
 export { connectEmbedded } from "./commands/embedded";
 export type { EmbeddedChat, EmbeddedChatOptions } from "./commands/embedded";
 export type { CommandHandler } from "./commands/registry";
 export type { CommandEnvelope, InboundAction, InboundEnvelope } from "./commands/protocol";
 export { isCommandEnvelope, isInboundEnvelope } from "./commands/protocol";
-export type { AuthResource, ExchangeCodeParams, ExchangeCodeResult, ProvidersResponse, UserInfo, } from "./resources/auth";
+export type { AuthResource, ProvidersResponse, UserInfo } from "./resources/auth";
 export type { HeadlessResource } from "./resources/headless";
 export { ModelsResource } from "./resources/models";
 export type { ModelCatalog, ModelOption } from "./resources/models";
 export type { SessionsResource } from "./resources/sessions";
-export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, GlobalSearchConversationResult, GlobalSearchFileResult, GlobalSearchResult, GlobalSearchResultItem, ResultFeedback, ResultFeedbackReason, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
+export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
 export type { ArchivedFileInfo, ArchivedToolCallInfo, ChatMessage, CompactionInfo, FileContentPart, ImageUrlContentPart, MemoryRefInfo, MessageContent, MessageContentPart, TextContentPart, ToolBridgeContent, ToolCallInfo, } from "./schemas/message";
 export { buildMessageContent, contentPreview, extractTextAttachments, getFileParts, getImageParts, getTextContent, groupMessagesByLoop, isHiddenInternalMessage, normalizeMessageContent, transformSlashCommand, } from "./schemas/message-utils";
-export type { ParsedTextAttachment, ParsedTextContext, SkillMentionAvailability, } from "./schemas/message-utils";
-export type { ContentBlock, FinalArtifact, MemoryRef, PatchEnvelope, PostChatFollowup, TurnProjection, } from "./schemas/projection";
-export { latestPostChatFollowup } from "./schemas/projection-utils";
-export { DEFAULT_REPLAY_SPEED } from "./schemas/session";
+export type { ParsedTextAttachment, ParsedTextContext } from "./schemas/message-utils";
+export type { ContentBlock, MemoryRef, PatchEnvelope, TurnProjection } from "./schemas/projection";
 export { SessionInfo, SessionStatus } from "./schemas/session";
-export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, ReplayPreview, ReplaySpeed, ReplayState, SessionDetail, SessionPortMapping, PublishedSolutionRef, TemplateId, } from "./schemas/session";
+export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, SessionDetail, SessionPortMapping, PublishedSolutionRef, TemplateId, } from "./schemas/session";
 export { LayoutType } from "./schemas/solution";
 export type { BizRole, Solution, SolutionAppField, SolutionAppState, SolutionAppUiConfig, } from "./schemas/solution";
 export { Task, TaskStatus } from "./schemas/task";
 export type { BackgroundTask, BackgroundTaskStopResult } from "./schemas/background";
-export { acceptedPostChatFollowupCompletesLatestRun, ClientProjectionBuilder } from "./shared/projection";
+export { ClientProjectionBuilder } from "./shared/projection";
 export type { RawEvent } from "./shared/projection";
 export { createSocket } from "./socket";
 export type { CreateSocketOptions, TypedSocket } from "./socket";