@tbox-claw/bridge-sdk 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# @tbox-claw/bridge-sdk
+
+> TboxClaw 桌面端嵌入页面开发 SDK
+
+本包为嵌入在 TboxClaw 桌面应用中的三方页面提供 **TypeScript 类型定义** 和 **运行时工具函数**。三方页面通过 `window.tboxClawBridge` 与客户端进行安全通信。
+
+---
+
+## 安装
+
+```bash
+npm install @tbox-claw/bridge-sdk
+# 或
+pnpm add @tbox-claw/bridge-sdk
+# 或
+yarn add @tbox-claw/bridge-sdk
+```
+
+---
+
+## 快速开始
+
+```typescript
+import { getBridge, isTboxClawEnv } from '@tbox-claw/bridge-sdk';
+
+if (isTboxClawEnv()) {
+  const bridge = getBridge();
+
+  // 获取当前用户信息
+  const userResult = await bridge.getUserInfo();
+  if (userResult.ok) {
+    console.log('你好，', userResult.data.name);
+  }
+
+  // 获取客户端信息
+  const clientResult = await bridge.getClientInfo();
+  if (clientResult.ok) {
+    console.log('操作系统：', clientResult.data.platform);
+    console.log('客户端版本：', clientResult.data.clientVersion);
+  }
+}
+```
+
+---
+
+## Bridge API
+
+所有 Bridge API 返回统一的 `BridgeResponse<T>` 格式：
+
+```typescript
+interface BridgeResponse<T = unknown> {
+  ok: boolean;    // 调用是否成功
+  data?: T;       // 响应数据（ok=true 时存在）
+  error?: string; // 错误信息（ok=false 时存在）
+}
+```
+
+> **权限模型**：每个嵌入页面在服务端配置了允许调用的 API 白名单（`bridge.allowedApis`）。调用白名单之外的 API 会返回 `{ ok: false, error: 'API "xxx" not allowed for page "yyy"' }`。
+
+### 用户信息
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:--------------:|
+| [`getUserInfo()`](./docs/api/getUserInfo.md) | 获取当前登录用户信息（已脱敏） | `1.2.1` |
+
+### 应用设置
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:--------------:|
+| [`getSettings(keys)`](./docs/api/getSettings.md) | 读取应用设置（支持 `theme`、`language`） | `1.2.1` |
+
+### 客户端环境
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:--------------:|
+| [`getClientInfo()`](./docs/api/getClientInfo.md) | 获取操作系统、系统版本、客户端版本等环境信息 | `1.2.1` |
+
+### 系统通知
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:--------------:|
+| [`sendNotification(options)`](./docs/api/sendNotification.md) | 通过主应用发送系统通知 | `1.2.1` |
+
+
+### 对话消息
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:--------------:|
+| [`sendChatMessage(options)`](./docs/api/sendChatMessage.md) | 发送对话消息，等同于在 Chat 页面发送 | `1.2.1` |
+| [`getChatHistory(options?)`](./docs/api/getChatHistory.md) | 查询对话历史记录 | `1.2.1` |
+
+### 网关状态
+
+| API | 说明 | 最小客户端版本 |
+|-----|------|:--------------:|
+| [`getGatewayStatus()`](./docs/api/getGatewayStatus.md) | 查询 Gateway 运行状态，判断对话类 API 是否可用 | `1.2.1` |
+
+---
+
+## 工具函数
+
+SDK 提供以下工具函数，用于环境检测和安全调用，**不依赖客户端版本**。
+
+### `isTboxClawEnv(): boolean`
+
+判断当前页面是否运行在 TboxClaw 桌面端中（即 `window.tboxClawBridge` 是否可用）。
+
+```typescript
+import { isTboxClawEnv } from '@tbox-claw/bridge-sdk';
+
+if (isTboxClawEnv()) {
+  // 在 TboxClaw 中运行，Bridge API 可用
+} else {
+  // 独立运行，使用降级逻辑
+}
+```
+
+### `getBridge(): TboxClawBridge`
+
+获取 `window.tboxClawBridge` 实例。**如果不在 TboxClaw 环境中会抛出异常**。
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+const user = await bridge.getUserInfo();
+```
+
+### `safeBridgeCall<T>(apiFn, fallback): Promise<T>`
+
+安全调用 Bridge API。如果不在 TboxClaw 环境中或调用出错，返回 `fallback` 值。适用于需要同时支持独立运行和嵌入运行的页面。
+
+```typescript
+import { safeBridgeCall } from '@tbox-claw/bridge-sdk';
+
+const user = await safeBridgeCall(
+  (bridge) => bridge.getUserInfo(),
+  { ok: false, error: '不在 TboxClaw 环境中' },
+);
+```
+
+---
+
+## 双模式页面（独立运行 + 嵌入运行）
+
+如果你的页面需要同时支持作为独立 Web 应用和嵌入页面运行，推荐使用 `safeBridgeCall` 模式：
+
+```typescript
+import { safeBridgeCall, isTboxClawEnv } from '@tbox-claw/bridge-sdk';
+
+// 获取用户信息 — 在 TboxClaw 外自动降级
+const userResult = await safeBridgeCall(
+  (bridge) => bridge.getUserInfo(),
+  { ok: false, error: '非嵌入环境' },
+);
+
+if (userResult.ok) {
+  renderUserProfile(userResult.data);
+} else {
+  renderLoginForm();
+}
+
+// 按需渲染 TboxClaw 专属功能
+if (isTboxClawEnv()) {
+  showClientInfoPanel();
+}
+```
+
+---
+
+## TypeScript 支持
+
+SDK 内置完整的 TypeScript 类型声明。安装后 `window.tboxClawBridge` 会自动获得类型提示：
+
+```typescript
+// 无需额外配置 — window.tboxClawBridge 已自动声明类型
+const bridge = window.tboxClawBridge;
+const user = await bridge.getUserInfo(); // 完整类型推导
+```
+
+### 导出的类型
+
+```typescript
+import type {
+  TboxClawBridge,            // Bridge 接口定义
+  BridgeResponse,            // { ok, data?, error? }
+  UserInfo,                  // { userId, name, avatar }
+  ClientInfo,                // { platform, osVersion, clientVersion }
+  SendNotificationOptions,   // { title, body, silent? }
+  SendChatMessageOptions,    // { message, sessionKey? }
+  GetChatHistoryOptions,     // { sessionKey?, limit? }
+  ChatMessage,               // { role, content, timestamp?, id? }
+  GatewayStatusInfo,         // { state, ready }
+} from '@tbox-claw/bridge-sdk';
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,102 @@
+/** Bridge API unified response format */
+interface BridgeResponse<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+}
+/** User info (sanitized, no sensitive data) */
+interface UserInfo {
+    userId: string;
+    name: string;
+    avatar: string;
+    /** Login channel type (e.g. 'dingtalk', 'alipay') */
+    loginType?: string;
+    /** Extra user context from server */
+    extra?: Record<string, unknown>;
+}
+/** Client environment info */
+interface ClientInfo {
+    /** Operating system: 'darwin' | 'win32' | 'linux' */
+    platform: string;
+    /** OS version string (e.g. '24.3.0') */
+    osVersion: string;
+    /** Client application version (e.g. '1.2.0') */
+    clientVersion: string;
+}
+/** Options for sending a system notification */
+interface SendNotificationOptions {
+    /** Notification title */
+    title: string;
+    /** Notification body text */
+    body: string;
+    /** Whether to suppress the notification sound (default: false) */
+    silent?: boolean;
+}
+/** Options for sending a chat message */
+interface SendChatMessageOptions {
+    /** Message text content */
+    message: string;
+    /**
+     * Session identifier within this page, used to maintain separate conversations.
+     * Defaults to 'default'. The host app automatically prefixes it with the page ID
+     * to ensure full session isolation between pages (format: `embedded:{pageId}:{sessionKey}`).
+     */
+    sessionKey?: string;
+}
+/** Options for querying chat history */
+interface GetChatHistoryOptions {
+    /**
+     * Session identifier within this page. Defaults to 'default'.
+     * Must match the sessionKey used when sending messages.
+     */
+    sessionKey?: string;
+    /** Maximum number of messages to return (default: 50) */
+    limit?: number;
+}
+/** A single chat message returned from history */
+interface ChatMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system';
+    /** Message text content */
+    content: string;
+    /** Unix timestamp (seconds) */
+    timestamp?: number;
+    /** Message unique identifier */
+    id?: string;
+}
+/** Gateway runtime status */
+interface GatewayStatusInfo {
+    /** Current lifecycle state */
+    state: 'stopped' | 'starting' | 'running' | 'error' | 'reconnecting';
+    /** Whether the gateway is ready to accept requests */
+    ready: boolean;
+}
+
+/** TboxClaw Bridge interface definition */
+interface TboxClawBridge {
+    getUserInfo(): Promise<BridgeResponse<UserInfo>>;
+    getSettings(keys: string[]): Promise<BridgeResponse<Record<string, unknown>>>;
+    getClientInfo(): Promise<BridgeResponse<ClientInfo>>;
+    /** Send a system notification via the host application */
+    sendNotification(options: SendNotificationOptions): Promise<BridgeResponse<void>>;
+    /** Send a chat message, equivalent to typing in the Chat page */
+    sendChatMessage(options: SendChatMessageOptions): Promise<BridgeResponse<{
+        runId?: string;
+    }>>;
+    /** Query chat history for a given session */
+    getChatHistory(options?: GetChatHistoryOptions): Promise<BridgeResponse<ChatMessage[]>>;
+    /** Check whether the Gateway is running and ready */
+    getGatewayStatus(): Promise<BridgeResponse<GatewayStatusInfo>>;
+}
+
+/** Check if currently running inside TboxClaw embedded environment */
+declare function isTboxClawEnv(): boolean;
+/** Get the Bridge instance. Throws if not in embedded environment. */
+declare function getBridge(): TboxClawBridge;
+/**
+ * Safely call a Bridge API. Returns fallback value if not in embedded environment.
+ * Useful for pages that need to work both standalone and embedded.
+ */
+declare function safeBridgeCall<T>(apiFn: (bridge: TboxClawBridge) => Promise<T>, fallback: T): Promise<T>;
+
+export { type BridgeResponse, type ChatMessage, type ClientInfo, type GatewayStatusInfo, type GetChatHistoryOptions, type SendChatMessageOptions, type SendNotificationOptions, type TboxClawBridge, type UserInfo, getBridge, isTboxClawEnv, safeBridgeCall };

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/** Bridge API unified response format */
+interface BridgeResponse<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+}
+/** User info (sanitized, no sensitive data) */
+interface UserInfo {
+    userId: string;
+    name: string;
+    avatar: string;
+    /** Login channel type (e.g. 'dingtalk', 'alipay') */
+    loginType?: string;
+    /** Extra user context from server */
+    extra?: Record<string, unknown>;
+}
+/** Client environment info */
+interface ClientInfo {
+    /** Operating system: 'darwin' | 'win32' | 'linux' */
+    platform: string;
+    /** OS version string (e.g. '24.3.0') */
+    osVersion: string;
+    /** Client application version (e.g. '1.2.0') */
+    clientVersion: string;
+}
+/** Options for sending a system notification */
+interface SendNotificationOptions {
+    /** Notification title */
+    title: string;
+    /** Notification body text */
+    body: string;
+    /** Whether to suppress the notification sound (default: false) */
+    silent?: boolean;
+}
+/** Options for sending a chat message */
+interface SendChatMessageOptions {
+    /** Message text content */
+    message: string;
+    /**
+     * Session identifier within this page, used to maintain separate conversations.
+     * Defaults to 'default'. The host app automatically prefixes it with the page ID
+     * to ensure full session isolation between pages (format: `embedded:{pageId}:{sessionKey}`).
+     */
+    sessionKey?: string;
+}
+/** Options for querying chat history */
+interface GetChatHistoryOptions {
+    /**
+     * Session identifier within this page. Defaults to 'default'.
+     * Must match the sessionKey used when sending messages.
+     */
+    sessionKey?: string;
+    /** Maximum number of messages to return (default: 50) */
+    limit?: number;
+}
+/** A single chat message returned from history */
+interface ChatMessage {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system';
+    /** Message text content */
+    content: string;
+    /** Unix timestamp (seconds) */
+    timestamp?: number;
+    /** Message unique identifier */
+    id?: string;
+}
+/** Gateway runtime status */
+interface GatewayStatusInfo {
+    /** Current lifecycle state */
+    state: 'stopped' | 'starting' | 'running' | 'error' | 'reconnecting';
+    /** Whether the gateway is ready to accept requests */
+    ready: boolean;
+}
+
+/** TboxClaw Bridge interface definition */
+interface TboxClawBridge {
+    getUserInfo(): Promise<BridgeResponse<UserInfo>>;
+    getSettings(keys: string[]): Promise<BridgeResponse<Record<string, unknown>>>;
+    getClientInfo(): Promise<BridgeResponse<ClientInfo>>;
+    /** Send a system notification via the host application */
+    sendNotification(options: SendNotificationOptions): Promise<BridgeResponse<void>>;
+    /** Send a chat message, equivalent to typing in the Chat page */
+    sendChatMessage(options: SendChatMessageOptions): Promise<BridgeResponse<{
+        runId?: string;
+    }>>;
+    /** Query chat history for a given session */
+    getChatHistory(options?: GetChatHistoryOptions): Promise<BridgeResponse<ChatMessage[]>>;
+    /** Check whether the Gateway is running and ready */
+    getGatewayStatus(): Promise<BridgeResponse<GatewayStatusInfo>>;
+}
+
+/** Check if currently running inside TboxClaw embedded environment */
+declare function isTboxClawEnv(): boolean;
+/** Get the Bridge instance. Throws if not in embedded environment. */
+declare function getBridge(): TboxClawBridge;
+/**
+ * Safely call a Bridge API. Returns fallback value if not in embedded environment.
+ * Useful for pages that need to work both standalone and embedded.
+ */
+declare function safeBridgeCall<T>(apiFn: (bridge: TboxClawBridge) => Promise<T>, fallback: T): Promise<T>;
+
+export { type BridgeResponse, type ChatMessage, type ClientInfo, type GatewayStatusInfo, type GetChatHistoryOptions, type SendChatMessageOptions, type SendNotificationOptions, type TboxClawBridge, type UserInfo, getBridge, isTboxClawEnv, safeBridgeCall };

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getBridge: () => getBridge,
+  isTboxClawEnv: () => isTboxClawEnv,
+  safeBridgeCall: () => safeBridgeCall
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils.ts
+function isTboxClawEnv() {
+  return typeof window !== "undefined" && typeof window.tboxClawBridge !== "undefined";
+}
+function getBridge() {
+  if (!isTboxClawEnv()) {
+    throw new Error(
+      "tboxClawBridge is not available. This page must be embedded in the TboxClaw desktop app."
+    );
+  }
+  return window.tboxClawBridge;
+}
+async function safeBridgeCall(apiFn, fallback) {
+  if (!isTboxClawEnv()) return fallback;
+  try {
+    return await apiFn(window.tboxClawBridge);
+  } catch {
+    return fallback;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getBridge,
+  isTboxClawEnv,
+  safeBridgeCall
+});

package/dist/index.mjs

@@ -0,0 +1,25 @@
+// src/utils.ts
+function isTboxClawEnv() {
+  return typeof window !== "undefined" && typeof window.tboxClawBridge !== "undefined";
+}
+function getBridge() {
+  if (!isTboxClawEnv()) {
+    throw new Error(
+      "tboxClawBridge is not available. This page must be embedded in the TboxClaw desktop app."
+    );
+  }
+  return window.tboxClawBridge;
+}
+async function safeBridgeCall(apiFn, fallback) {
+  if (!isTboxClawEnv()) return fallback;
+  try {
+    return await apiFn(window.tboxClawBridge);
+  } catch {
+    return fallback;
+  }
+}
+export {
+  getBridge,
+  isTboxClawEnv,
+  safeBridgeCall
+};

package/docs/api/getChatHistory.md

@@ -0,0 +1,123 @@
+## getChatHistory(options?)
+
+查询当前页面的对话历史记录。返回指定会话中的消息列表。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 对话消息 |
+| **需要权限** | `getChatHistory` 需在页面 `bridge.allowedApis` 白名单中 |
+| **依赖** | 需要 Gateway 处于 `running` 状态 |
+
+---
+
+### 签名
+
+```typescript
+getChatHistory(options?: GetChatHistoryOptions): Promise<BridgeResponse<ChatMessage[]>>
+```
+
+### 参数
+
+**`GetChatHistoryOptions` 类型定义**：
+
+```typescript
+interface GetChatHistoryOptions {
+  /** 页面内的会话标识，默认 'default'。需与 sendChatMessage 使用的 sessionKey 一致。 */
+  sessionKey?: string;
+  /** 返回的最大消息数量，默认 50，上限 200 */
+  limit?: number;
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `sessionKey` | `string` | ❌ | 页面内的会话标识，默认 `'default'` |
+| `limit` | `number` | ❌ | 最大返回消息数，默认 `50`，上限 `200` |
+
+### 返回值
+
+`Promise<BridgeResponse<ChatMessage[]>>`
+
+**`ChatMessage` 类型定义**：
+
+```typescript
+interface ChatMessage {
+  /** 消息角色：'user' | 'assistant' | 'system' */
+  role: 'user' | 'assistant' | 'system';
+  /** 消息文本内容 */
+  content: string;
+  /** Unix 时间戳（秒） */
+  timestamp?: number;
+  /** 消息唯一标识 */
+  id?: string;
+}
+```
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+
+// 查询默认会话的历史记录
+const result = await bridge.getChatHistory();
+if (result.ok) {
+  for (const msg of result.data) {
+    console.log(`[${msg.role}] ${msg.content}`);
+  }
+}
+
+// 查询指定会话，限制返回 20 条
+const result2 = await bridge.getChatHistory({
+  sessionKey: 'analysis-task',
+  limit: 20,
+});
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `API "getChatHistory" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+| `Gateway is not available` | Gateway 服务未启动或不可用 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true,
+  "data": [
+    {
+      "role": "user",
+      "content": "帮我分析一下这个数据",
+      "timestamp": 1713700000,
+      "id": "msg-001"
+    },
+    {
+      "role": "assistant",
+      "content": "好的，我来帮你分析...",
+      "timestamp": 1713700005,
+      "id": "msg-002"
+    }
+  ]
+}
+```
+
+**成功（空历史）**：
+
+```json
+{
+  "ok": true,
+  "data": []
+}
+```
+
+### 注意事项
+
+- `sessionKey` 需与 `sendChatMessage` 中使用的一致，才能查到对应的历史记录。
+- 会话隔离机制同样适用：主应用会自动拼接 `pageId` 前缀，不同页面无法查看彼此的历史。
+- 如果 Gateway 尚未启动完成，调用会返回错误。建议先通过 `getGatewayStatus()` 确认 Gateway 状态。

package/docs/api/getClientInfo.md

@@ -0,0 +1,74 @@
+## getClientInfo()
+
+获取当前客户端的环境信息，包括操作系统、系统版本和客户端版本号。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 客户端环境 |
+| **需要权限** | `getClientInfo` 需在页面 `bridge.allowedApis` 白名单中 |
+
+---
+
+### 签名
+
+```typescript
+getClientInfo(): Promise<BridgeResponse<ClientInfo>>
+```
+
+### 参数
+
+无。
+
+### 返回值
+
+`Promise<BridgeResponse<ClientInfo>>`
+
+**`ClientInfo` 类型定义**：
+
+```typescript
+interface ClientInfo {
+  /** 操作系统：'darwin' | 'win32' | 'linux' */
+  platform: string;
+  /** 操作系统版本号，如 '24.3.0' */
+  osVersion: string;
+  /** 客户端应用版本号，如 '1.2.0' */
+  clientVersion: string;
+}
+```
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+const result = await bridge.getClientInfo();
+
+if (result.ok) {
+  console.log(result.data.platform);      // 'darwin' | 'win32' | 'linux'
+  console.log(result.data.osVersion);     // 如 '24.3.0'
+  console.log(result.data.clientVersion); // 如 '1.2.0'
+}
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `API "getClientInfo" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "platform": "darwin",
+    "osVersion": "24.3.0",
+    "clientVersion": "1.2.0"
+  }
+}
+```

package/docs/api/getGatewayStatus.md

@@ -0,0 +1,118 @@
+## getGatewayStatus()
+
+查询 Gateway 服务的运行状态。可用于在调用 `sendChatMessage` 或 `getChatHistory` 之前判断 Gateway 是否就绪，避免调用失败。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 网关状态 |
+| **需要权限** | `getGatewayStatus` 需在页面 `bridge.allowedApis` 白名单中 |
+
+---
+
+### 签名
+
+```typescript
+getGatewayStatus(): Promise<BridgeResponse<GatewayStatusInfo>>
+```
+
+### 参数
+
+无。
+
+### 返回值
+
+`Promise<BridgeResponse<GatewayStatusInfo>>`
+
+**`GatewayStatusInfo` 类型定义**：
+
+```typescript
+interface GatewayStatusInfo {
+  /** 当前生命周期状态 */
+  state: 'stopped' | 'starting' | 'running' | 'error' | 'reconnecting';
+  /** Gateway 是否已就绪，可以接受请求 */
+  ready: boolean;
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `state` | `string` | 生命周期状态，见下方状态说明 |
+| `ready` | `boolean` | 是否就绪（仅 `state === 'running'` 时为 `true`） |
+
+**状态说明**：
+
+| state | 说明 |
+|-------|------|
+| `stopped` | Gateway 未启动 |
+| `starting` | Gateway 正在启动中（通常需要 10-30 秒） |
+| `running` | Gateway 正常运行，可以接受请求 |
+| `error` | Gateway 启动失败或运行时出错 |
+| `reconnecting` | Gateway 正在尝试重新连接 |
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+
+// 检查 Gateway 是否就绪
+const status = await bridge.getGatewayStatus();
+if (status.ok && status.data.ready) {
+  // Gateway 已就绪，可以安全调用对话相关 API
+  await bridge.sendChatMessage({ message: '你好' });
+} else {
+  console.log('Gateway 状态:', status.data?.state);
+  // 可以提示用户等待或重试
+}
+```
+
+```typescript
+// 等待 Gateway 就绪的轮询示例
+async function waitForGateway(bridge, maxRetries = 10) {
+  for (let i = 0; i < maxRetries; i++) {
+    const status = await bridge.getGatewayStatus();
+    if (status.ok && status.data.ready) return true;
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  return false;
+}
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `API "getGatewayStatus" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+
+### 返回示例
+
+**成功（Gateway 运行中）**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "state": "running",
+    "ready": true
+  }
+}
+```
+
+**成功（Gateway 启动中）**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "state": "starting",
+    "ready": false
+  }
+}
+```
+
+### 注意事项
+
+- 此 API 始终返回成功（`ok: true`），即使 Gateway 未启动也会返回 `{ state: 'stopped', ready: false }`。
+- 建议在调用 `sendChatMessage` 或 `getChatHistory` 之前先调用此 API 确认 `ready === true`。

package/docs/api/getSettings.md

@@ -0,0 +1,70 @@
+## getSettings(keys)
+
+读取应用设置。仅返回白名单内的 key（当前支持：`theme`、`language`）。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 应用设置 |
+| **需要权限** | `getSettings` 需在页面 `bridge.allowedApis` 白名单中 |
+
+---
+
+### 签名
+
+```typescript
+getSettings(keys: string[]): Promise<BridgeResponse<Record<string, unknown>>>
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `keys` | `string[]` | 是 | 要读取的设置项名称数组 |
+
+**当前支持的 key**：
+
+| key | 类型 | 可选值 | 说明 |
+|-----|------|--------|------|
+| `theme` | `string` | `"light"` \| `"dark"` | 当前主题 |
+| `language` | `string` | `"zh"` \| `"en"` | 当前语言 |
+
+> 请求不在白名单内的 key 时，该 key 会被静默忽略，不会报错。
+
+### 返回值
+
+`Promise<BridgeResponse<Record<string, unknown>>>`
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+const result = await bridge.getSettings(['theme', 'language']);
+
+if (result.ok) {
+  console.log(result.data.theme);    // "light" | "dark"
+  console.log(result.data.language); // "zh" | "en"
+}
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `API "getSettings" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "theme": "dark",
+    "language": "zh"
+  }
+}
+```

package/docs/api/getUserInfo.md

@@ -0,0 +1,92 @@
+## getUserInfo()
+
+获取当前登录用户的信息（已脱敏，不包含 token 等敏感数据）。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 用户信息 |
+| **需要权限** | `getUserInfo` 需在页面 `bridge.allowedApis` 白名单中 |
+
+---
+
+### 签名
+
+```typescript
+getUserInfo(): Promise<BridgeResponse<UserInfo>>
+```
+
+### 参数
+
+无。
+
+### 返回值
+
+`Promise<BridgeResponse<UserInfo>>`
+
+**`UserInfo` 类型定义**：
+
+```typescript
+interface UserInfo {
+  /** 用户 ID */
+  userId: string;
+  /** 用户昵称 */
+  name: string;
+  /** 头像 URL */
+  avatar: string;
+  /** 登录渠道，>= 1.2.5 */
+  loginType?: string;
+  /** 服务端扩展信息，>= 1.2.5 */
+  extra?: Record<string, unknown>;
+}
+```
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+const result = await bridge.getUserInfo();
+
+if (result.ok) {
+  console.log(result.data.userId);    // 如 "12345"
+  console.log(result.data.name);      // 如 "张三"
+  console.log(result.data.avatar);    // 头像 URL
+  console.log(result.data.loginType); // 如 "dingtalk"（>= 1.2.5）
+  console.log(result.data.extra);     // 服务端扩展信息（>= 1.2.5）
+}
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `NOT_AUTHENTICATED` | 用户未登录 |
+| `API "getUserInfo" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "userId": "12345",
+    "name": "张三",
+    "avatar": "https://example.com/avatar.png",
+    "loginType": "dingtalk",
+    "extra": {}
+  }
+}
+```
+
+**失败（未登录）**：
+
+```json
+{
+  "ok": false,
+  "error": "NOT_AUTHENTICATED"
+}
+```

package/docs/api/sendChatMessage.md

@@ -0,0 +1,104 @@
+## sendChatMessage(options)
+
+发送对话消息，功能等同于在 Chat 页面输入并发送。嵌入页面可通过此 API 与 AI Agent 进行对话交互。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 对话消息 |
+| **需要权限** | `sendChatMessage` 需在页面 `bridge.allowedApis` 白名单中 |
+
+---
+
+### 签名
+
+```typescript
+sendChatMessage(options: SendChatMessageOptions): Promise<BridgeResponse<{ runId?: string }>>
+```
+
+### 参数
+
+**`SendChatMessageOptions` 类型定义**：
+
+```typescript
+interface SendChatMessageOptions {
+  /** 消息文本内容 */
+  message: string;
+  /**
+   * 页面内的会话标识，用于区分同一页面内的多个独立对话。
+   * 省略时默认为 'default'。
+   */
+  sessionKey?: string;
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `message` | `string` | ✅ | 消息文本内容，不能为空 |
+| `sessionKey` | `string` | ❌ | 页面内的会话标识，默认 `'default'` |
+
+### 返回值
+
+`Promise<BridgeResponse<{ runId?: string }>>`
+
+成功时 `data` 中包含本次对话运行的 `runId`，可用于后续追踪对话状态。
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+
+// 使用默认会话发送消息
+const result = await bridge.sendChatMessage({
+  message: '帮我分析一下这个数据',
+});
+
+if (result.ok) {
+  console.log('消息已发送，runId:', result.data?.runId);
+} else {
+  console.error('发送失败:', result.error);
+}
+
+// 同一页面内使用不同的会话（用于多轮独立对话场景）
+const result2 = await bridge.sendChatMessage({
+  message: '这是另一个独立对话',
+  sessionKey: 'analysis-task',
+});
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `API "sendChatMessage" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+| `options must include a non-empty "message" (string)` | 消息内容为空或类型错误 |
+| `Gateway is not available` | Gateway 服务未启动或不可用 |
+| `Gateway RPC failed: chat.send` | Gateway 处理消息时发生错误 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+  }
+}
+```
+
+**失败（Gateway 不可用）**：
+
+```json
+{
+  "ok": false,
+  "error": "Gateway is not available"
+}
+```
+
+### 注意事项
+
+- 如果 Gateway 尚未启动完成（通常需要 10-30 秒），调用会返回错误。

package/docs/api/sendNotification.md

@@ -0,0 +1,94 @@
+## sendNotification(options)
+
+通过主应用发送系统级桌面通知。嵌入页面可借助此 API 向用户推送操作系统原生通知。
+
+| 属性 | 值 |
+|------|-----|
+| **最小客户端版本** | `1.2.1` |
+| **分类** | 系统通知 |
+| **需要权限** | `sendNotification` 需在页面 `bridge.allowedApis` 白名单中 |
+
+---
+
+### 签名
+
+```typescript
+sendNotification(options: SendNotificationOptions): Promise<BridgeResponse<void>>
+```
+
+### 参数
+
+**`SendNotificationOptions` 类型定义**：
+
+```typescript
+interface SendNotificationOptions {
+  /** 通知标题 */
+  title: string;
+  /** 通知正文内容 */
+  body: string;
+  /** 是否静音（不播放提示音），默认 false */
+  silent?: boolean;
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `title` | `string` | ✅ | 通知标题 |
+| `body` | `string` | ✅ | 通知正文内容 |
+| `silent` | `boolean` | ❌ | 是否静音，默认 `false` |
+
+### 返回值
+
+`Promise<BridgeResponse<void>>`
+
+成功时返回 `{ ok: true }`，不包含 `data` 字段。
+
+### 示例
+
+```typescript
+import { getBridge } from '@tbox-claw/bridge-sdk';
+
+const bridge = getBridge();
+const result = await bridge.sendNotification({
+  title: '任务完成',
+  body: '你的数据已处理完毕',
+  silent: false,
+});
+
+if (result.ok) {
+  console.log('通知已发送');
+} else {
+  console.error('发送失败:', result.error);
+}
+```
+
+### 错误场景
+
+| error | 说明 |
+|-------|------|
+| `API "sendNotification" not allowed for page "xxx"` | 页面未配置该 API 的调用权限 |
+| `options must include "title" (string) and "body" (string)` | 参数缺失或类型错误 |
+
+### 返回示例
+
+**成功**：
+
+```json
+{
+  "ok": true
+}
+```
+
+**失败（参数错误）**：
+
+```json
+{
+  "ok": false,
+  "error": "options must include \"title\" (string) and \"body\" (string)"
+}
+```
+
+### 注意事项
+
+- 通知是否实际显示取决于操作系统的通知权限设置。如果用户关闭了应用的通知权限，调用仍会返回成功，但通知不会显示。
+- macOS 和 Windows 的通知样式由操作系统决定，应用无法自定义外观。

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tbox-claw/bridge-sdk",
+  "version": "1.0.0",
+  "description": "Bridge SDK for developing embedded pages in TboxClaw desktop app",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "tbox",
+    "claw",
+    "bridge",
+    "sdk",
+    "electron",
+    "embedded-page"
+  ],
+  "license": "MIT"
+}