@blade-hq/agent-client 2610.0.0-beta.11 → 2610.0.0-beta.12

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
 
 ### 构造

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";

package/dist/index.js

@@ -4499,7 +4499,7 @@ function resolveAuthToken(options) {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.11" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.12" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {
@@ -4892,6 +4892,87 @@ function parseXhrHeaders(rawHeaders) {
   return headers;
 }
 
+// src/platform-endpoints.ts
+var PLATFORM_SERVICE_NAMES = [
+  "os",
+  "hub",
+  "agent",
+  "oauth",
+  "llmGateway",
+  "gitea"
+];
+var EMPTY_PLATFORM_ENDPOINTS = Object.freeze({
+  services: Object.freeze({})
+});
+function defaultDocumentBaseUrl() {
+  if (typeof document === "undefined") return void 0;
+  if (document.querySelector("base[href]")) return document.baseURI;
+  if (typeof location !== "undefined" && location.origin) return `${location.origin}/`;
+  return document.baseURI;
+}
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeServiceUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  if (value.includes("?") || value.includes("#")) return null;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.username || url.password || url.search || url.hash) return null;
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+function parsePlatformEndpoints(value) {
+  if (!isRecord6(value) || !isRecord6(value.services)) return null;
+  const services = {};
+  for (const name of PLATFORM_SERVICE_NAMES) {
+    if (!(name in value.services)) continue;
+    const url = normalizeServiceUrl(value.services[name]);
+    if (!url) return null;
+    services[name] = url;
+  }
+  return { services };
+}
+async function loadPlatformEndpoints(options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? defaultDocumentBaseUrl();
+  if (!fetchImpl || !baseUrl) return EMPTY_PLATFORM_ENDPOINTS;
+  const controller = new AbortController();
+  const timeout = globalThis.setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+  try {
+    const response = await fetchImpl(new URL("config.json", baseUrl), {
+      cache: "no-store",
+      credentials: "same-origin",
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) return EMPTY_PLATFORM_ENDPOINTS;
+    return parsePlatformEndpoints(await response.json()) ?? EMPTY_PLATFORM_ENDPOINTS;
+  } catch {
+    return EMPTY_PLATFORM_ENDPOINTS;
+  } finally {
+    globalThis.clearTimeout(timeout);
+  }
+}
+function resolveServiceUrl(endpoints, name, path = "") {
+  const baseUrl = endpoints.services[name];
+  if (!baseUrl) return null;
+  if (!path) return baseUrl;
+  const pathReference = path.trimStart();
+  if (path.includes("\\") || pathReference.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(pathReference)) {
+    return null;
+  }
+  const base = new URL(`${baseUrl}/`);
+  const target = new URL(path.replace(/^\/+/, ""), base);
+  if (target.origin !== base.origin || !target.pathname.startsWith(base.pathname)) {
+    return null;
+  }
+  return target.toString();
+}
+
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -4996,6 +5077,7 @@ export {
   BladeClient,
   ClientProjectionBuilder,
   DEFAULT_REPLAY_SPEED,
+  EMPTY_PLATFORM_ENDPOINTS,
   LayoutType,
   ModelsResource,
   SDK_NAME,
@@ -5021,8 +5103,10 @@ export {
   isHiddenInternalMessage,
   isInboundEnvelope,
   latestPostChatFollowup,
+  loadPlatformEndpoints,
   normalizeMessageContent,
   reconcileOptimisticUserTurns,
+  resolveServiceUrl,
   toReplaySnapshot,
   transformSlashCommand
 };