@sophonsai/agent-embed-react 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,310 @@
-# Temporary Holding Version
+# @sophonsai/agent-embed-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 应用接入
+
+传入服务地址 `endpoint` 和 Agent 的应用接入 `token`；可选 `baseUrl` 默认是 `/e/v1/embed`。
+最终 iframe 地址是 `endpoint + baseUrl + '/' + encodeURIComponent(token)`。
+
+```tsx
+<AgentEmbed endpoint='https://agent.example.com' token='应用接入Token' style={{ height: 600 }} />
+```
+
+不再接收完整 `url`、旧 `initConfig`、Agent ID 或平台用户凭证。
+`threadId`、外观配置、实例命令和事件回调继续支持。
+
+## 安装
+
+```bash
+# npm
+npm install @sophonsai/agent-embed-react react
+
+# pnpm
+pnpm add @sophonsai/agent-embed-react react
+
+# yarn
+yarn add @sophonsai/agent-embed-react react
+
+# bun
+bun add @sophonsai/agent-embed-react react
+```
+
+## 本地 Playground
+
+在仓库根目录运行：
+
+```bash
+pnpm dev:agent-embed
+```
+
+命令会复用或启动 Extension 开发服务（3023），启动 Agent Embed Playground（4171），并自动打开浏览器。Playground 支持服务地址、嵌入路径、应用接入 Token、appearance、实例命令和 bridge 生命周期日志。
+
+## 快速开始
+
+```tsx
+import { useState } from 'react'
+import { AgentEmbed, type AgentAppearance, type AgentEmbedInstance } from '@sophonsai/agent-embed-react'
+
+export function ChatPage() {
+  const [agent, setAgent] = useState<AgentEmbedInstance | null>(null)
+  const [appearance, setAppearance] = useState<AgentAppearance>({
+    theme: { preset: 'glacier-blue' },
+    fontSize: 16,
+    header: {
+      historyButton: true,
+      newConversationButton: true,
+      themeSettingButton: false,
+    },
+  })
+
+  return (
+    <div style={{ height: 640 }}>
+      <AgentEmbed
+        className='agent-embed'
+        endpoint='https://agent.example.com'
+        token='应用接入Token'
+        appearance={appearance}
+        onThemeChange={(theme) => setAppearance((current) => ({ ...current, theme }))}
+        onFontSizeChange={(fontSize) => setAppearance((current) => ({ ...current, fontSize }))}
+        onInitError={({ code, message }) => console.error('初始化失败', code, message)}
+        onReady={setAgent}
+        onSettled={(result) => console.log('会话结束', result)}
+      />
+
+      <button type='button' disabled={!agent} onClick={() => agent?.sendMessage({ text: '你好' })}>
+        发送消息
+      </button>
+    </div>
+  )
+}
+```
+
+## 组件 Props
+
+`AgentEmbedProps` 继承 SDK 的 `CreateAgentEmbedOptions`，并增加 React 容器属性：
+
+| Prop                | 类型                    | 必填 | 说明                                  |
+| ------------------- | ----------------------- | ---- | ------------------------------------- |
+| `endpoint`          | `string`                | 是   | 服务地址                              |
+| `token`             | `string`                | 是   | Agent 应用接入凭证                    |
+| `baseUrl`           | `string`                | 否   | 嵌入路径，默认 `/e/v1/embed`          |
+| `threadId`          | `string`                | 否   | 初始会话 ID                           |
+| `runtime_variables` | `AgentRuntimeVariables` | 否   | 新会话绑定的运行时变量，值必须为 JSON |
+| `appearance`        | `AgentAppearance`       | 否   | 主题、字号和头部按钮配置              |
+| `onReady`           | `(instance) => void`    | 否   | 面板可用后返回操作实例                |
+| `onThemeChange`     | `(theme) => void`       | 否   | 用户在面板内切换主题时调用            |
+| `onFontSizeChange`  | `(fontSize) => void`    | 否   | 用户在面板内调整字号时调用            |
+| `onInitError`       | `(failure) => void`     | 否   | 初始化失败                            |
+| `className`         | `string`                | 否   | 应用于根 `div`                        |
+| `style`             | `CSSProperties`         | 否   | 应用于根 `div`，可用于设置高度        |
+
+此外可以传入 `AgentEvents` 中定义的所有会话事件，例如 `onToolCallStarted`、`onSuccess` 和 `onSettled`。
+
+## 初始化配置
+
+```tsx
+<AgentEmbed
+  endpoint='https://agent.example.com'
+  token='应用接入Token'
+  baseUrl='/e/v1/embed'
+  threadId='可选初始会话ID'
+/>
+```
+
+`baseUrl` 可以省略。初始化配置与回调只在挂载时读取；需要切换服务、token、会话或回调时，修改组件 `key` 重新挂载：
+
+```tsx
+<AgentEmbed key={`${endpoint}:${token}:${threadId}`} endpoint={endpoint} token={token} threadId={threadId} />
+```
+
+## 外观与受控状态
+
+`appearance` 的三个部分支持在挂载后动态更新：
+
+```ts
+type AgentAppearance = {
+  theme?: { preset: AgentEmbedThemePreset }
+  fontSize?: number
+  header?: {
+    historyButton?: boolean
+    newConversationButton?: boolean
+    themeSettingButton?: boolean
+  }
+}
+```
+
+`header.themeSettingButton` 默认值为 `false`，只有显式设置为 `true` 时才显示主题设置按钮。
+
+可用主题：
+
+可以使用 `AgentEmbedThemePreset` 枚举式常量设置主题：
+
+```tsx
+import { AgentEmbedThemePreset } from '@sophonsai/agent-embed-react'
+
+const appearance = {
+  theme: { preset: AgentEmbedThemePreset.GlacierBlue },
+}
+```
+
+| 主题名 | preset            | 类型     |
+| ------ | ----------------- | -------- |
+| 曜石紫 | `obsidian-violet` | 深色主题 |
+| 石墨青 | `graphite-cyan`   | 深色主题 |
+| 午夜靛 | `midnight-indigo` | 深色主题 |
+| 深海蓝 | `deep-ocean`      | 深色主题 |
+| 森野绿 | `forest-emerald`  | 深色主题 |
+| 影棚白 | `studio-white`    | 浅色主题 |
+| 珍珠紫 | `pearl-violet`    | 浅色主题 |
+| 冰川蓝 | `glacier-blue`    | 浅色主题 |
+| 暖杏色 | `warm-cream`      | 浅色主题 |
+| 薰衣草 | `lavender-mist`   | 浅色主题 |
+
+当 `appearance.theme` 或 `appearance.fontSize` 有值时，对应字段属于受控状态。面板内发生变化后，应在回调里更新 React state，否则下一次渲染仍会使用旧值：
+
+```tsx
+onThemeChange={(theme) =>
+  setAppearance((current) => ({ ...current, theme }))
+}
+onFontSizeChange={(fontSize) =>
+  setAppearance((current) => ({ ...current, fontSize }))
+}
+```
+
+`appearance.header` 的变化会自动同步到面板。把某个字段设为 `false` 会隐藏对应按钮；把整个配置改为 `undefined` 会撤销宿主控制。
+
+## 获取和使用实例
+
+面板初始化完成后，`onReady` 会收到 `AgentEmbedInstance`。在此之前，获取不到 `AgentEmbedInstance` 实例对象，无法操作面板执行行为。
+
+```tsx
+const [agent, setAgent] = useState<AgentEmbedInstance | null>(null)
+
+<AgentEmbed endpoint={endpoint} token={token} onReady={setAgent} />
+
+agent?.addInputQuery({
+  text: '请分析这段内容',
+  context: selectedText,
+})
+agent?.focusInput()
+```
+
+实例方法：
+
+| 方法                                | 说明                                        |
+| ----------------------------------- | ------------------------------------------- |
+| `sendMessage({ text })`             | 立即提交消息；生成期间调用会使用 steer 行为 |
+| `addInputQuery({ text, context? })` | 写入输入框和可选上下文，不立即提交          |
+| `abortResponse()`                   | 终止当前回复                                |
+| `openHistoryPanel()`                | 打开历史会话面板                            |
+| `openThemeSettingsPanel()`          | 打开主题设置面板                            |
+| `newConversation()`                 | 新建会话                                    |
+| `focusInput()`                      | 聚焦输入框                                  |
+| `scrollToBottom()`                  | 滚动到底部                                  |
+
+组件卸载后内部 client 会被销毁，之前保存的 instance 随之失效。建议在组件切换或卸载时同步清空外部保存的 instance。
+
+## 错误处理
+
+初始化失败通过结构化回调报告：
+
+```tsx
+<AgentEmbed
+  endpoint={endpoint}
+  token={token}
+  onInitError={({ code, message }) => {
+    // code: invalid_token | forbidden | agent_not_found | request_failed | frame_load_failed
+    console.error(code, message)
+  }}
+/>
+```
+
+面板初始化完成后才会调用 `onReady`。发生上述初始化失败时不会调用 `onReady`。
+
+## 会话事件
+
+下面是几个常见用法：
+
+```tsx
+<AgentEmbed
+  endpoint={endpoint}
+  token={token}
+  onSessionContextReady={(context) => {
+    console.log('会话 ID', context.threadId)
+  }}
+  onToolCallFailed={(event) => {
+    console.error(event.toolName, event.error)
+  }}
+  onSettled={(result) => {
+    console.log(result.status)
+  }}
+/>
+```
+
+全部运行事件回调如下：
+
+| 回调                        | 参数                                                            | 说明                                        |
+| --------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
+| `onConcurrentSend`          | 无                                                              | 回复生成期间再次发送消息                    |
+| `onEvent`                   | `AgentServerEvent`                                              | 接收原始服务端事件                          |
+| `onSessionContextReady`     | `AgentSessionContext`                                           | 会话上下文可用，包含 `threadId` 和 `turnId` |
+| `onToolCallCreated`         | `AgentToolCallCreatedEvent`, `AgentSessionEventContext`         | 创建一个工具调用                            |
+| `onToolApprovalRequested`   | `AgentToolApprovalRequestedEvent`, `AgentSessionEventContext`   | 一组工具调用需要确认                        |
+| `onToolCallStarted`         | `AgentToolCallStartedEvent`, `AgentSessionEventContext`         | 工具调用开始                                |
+| `onToolCallProgressUpdated` | `AgentToolCallProgressUpdatedEvent`, `AgentSessionEventContext` | 工具调用进度更新                            |
+| `onToolCallBackgrounded`    | `AgentToolCallBackgroundedEvent`, `AgentSessionEventContext`    | 工具调用转为后台执行                        |
+| `onToolCallSucceeded`       | `AgentToolCallSucceededEvent`, `AgentSessionEventContext`       | 工具调用成功                                |
+| `onToolCallFailed`          | `AgentToolCallFailedEvent`, `AgentSessionEventContext`          | 工具调用失败                                |
+| `onToolCallCancelled`       | `AgentToolCallCancelledEvent`, `AgentSessionEventContext`       | 工具调用取消                                |
+| `onClientActionRequest`     | `AgentClientActionRequestEvent`, `AgentSessionEventContext`     | 智能体请求宿主执行客户端动作                |
+| `onUserFeedbackConsumed`    | `AgentUserFeedbackConsumedEvent`, `AgentSessionEventContext`    | 用户反馈已被处理                            |
+| `onUserSteerConsumed`       | `AgentUserSteerConsumedEvent`, `AgentSessionEventContext`       | 用户 steer 指令已被处理                     |
+| `onUserSteerCancelled`      | `AgentUserSteerCancelledEvent`, `AgentSessionRunEventContext`   | 用户 steer 指令已取消                       |
+| `onUserInputSubmitted`      | `AgentUserInputSubmittedEvent`, `AgentSessionEventContext`      | 用户输入已提交                              |
+| `onSessionTurnStarted`      | `AgentSessionTurnStartedEvent`, `AgentSessionEventContext`      | Turn 开始执行                               |
+| `onSessionTurnSucceeded`    | `AgentSessionTurnSucceededEvent`, `AgentSessionEventContext`    | Turn 执行成功                               |
+| `onSessionTurnFailed`       | `AgentSessionTurnFailedEvent`, `AgentSessionEventContext`       | Turn 执行失败                               |
+| `onSessionTurnCancelled`    | `AgentSessionTurnCancelledEvent`, `AgentSessionEventContext`    | Turn 已取消                                 |
+| `onSessionRunStarted`       | `AgentSessionRunStartedEvent`, `AgentSessionRunEventContext`    | Run 已开始                                  |
+| `onSessionRunIdled`         | `AgentSessionRunIdledEvent`, `AgentSessionRunEventContext`      | Run 已空闲                                  |
+| `onSessionRunEnded`         | `AgentSessionRunEndedEvent`, `AgentSessionRunEventContext`      | Run 已结束                                  |
+| `onSystemMessageConsumed`   | `AgentSystemMessageConsumedEvent`, `AgentSessionEventContext`   | 系统消息已被处理                            |
+| `onSuccess`                 | `AgentSessionSuccess`                                           | 本轮会话成功结束                            |
+| `onError`                   | `AgentSessionFailure`                                           | 本轮会话失败                                |
+| `onCancelled`               | `AgentSessionCancelled`                                         | 本轮会话取消                                |
+| `onSettled`                 | `AgentSessionSettlement`                                        | 本轮会话以任意状态结束                      |
+
+所有相关类型都由本包重导出。
+
+## 布局说明
+
+组件根节点默认样式为：
+
+```css
+width: 100%;
+height: 100%;
+min-height: 0;
+```
+
+因此父容器必须提供高度：
+
+```tsx
+<main style={{ height: 'calc(100vh - 64px)' }}>
+  <AgentEmbed endpoint={endpoint} token={token} />
+</main>
+```
+
+也可以直接通过 `style` 设置最小高度：
+
+```tsx
+<AgentEmbed style={{ minHeight: 480 }} endpoint={endpoint} token={token} />
+```
+
+### 运行时变量
+
+`runtime_variables` 是可选的 JSON 对象，名称须与智能体声明的运行时变量一致。仅创建新会话时发送，已有会话沿用已绑定的变量；同一面板新建会话时复用初始化值。参数在初始化时生成快照，改变值需要重建面板。数据通过 iframe 消息传递，不写入接入 URL。
+
+```tsx
+<AgentEmbed endpoint={endpoint} token={token} runtime_variables={{ customer_id: 'customer-1' }} />
+```
+
+初始化错误使用 `onInitError`（Vue: `@init-error`），包含 `code` 和 `message`，同次初始化只触发一次。失败时 `whenReady()` reject，聊天运行错误继续通过 `onError`（Vue: `@error`）报告。

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+import { CSSProperties } from "react";
+import { CreateAgentEmbedOptions } from "@sophonsai/agent-embed-sdk";
+export * from "@sophonsai/agent-embed-sdk";
+//#region src/index.d.ts
+type AgentEmbedProps = CreateAgentEmbedOptions & {
+  className?: string;
+  style?: CSSProperties;
+};
+declare const AgentEmbed: {
+  (props: AgentEmbedProps): import("react").JSX.Element;
+  displayName: string;
+};
+//#endregion
+export { AgentEmbed, AgentEmbed as default, AgentEmbedProps };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;KAKY,kBAAkB;EAC5B;EACA,QAAQ;;cAGG;GAAqB,OAAA,kCAAe,IAAA"}

package/dist/index.mjs

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from "react";
+import { createAgentEmbed } from "@sophonsai/agent-embed-sdk";
+import { jsx } from "react/jsx-runtime";
+export * from "@sophonsai/agent-embed-sdk";
+//#region src/index.tsx
+const AgentEmbed = (props) => {
+	const hostRef = useRef(null);
+	const clientRef = useRef(null);
+	useEffect(() => {
+		const host = hostRef.current;
+		if (!host) return;
+		const { className: _className, style: _style, ...options } = props;
+		const client = createAgentEmbed(options);
+		clientRef.current = client;
+		client.mount(host).catch(() => void 0);
+		return () => {
+			client.destroy();
+			clientRef.current = null;
+		};
+	}, []);
+	useEffect(() => {
+		clientRef.current?.updateTheme(props.appearance?.theme);
+	}, [props.appearance?.theme]);
+	useEffect(() => {
+		clientRef.current?.updateFontSize(props.appearance?.fontSize);
+	}, [props.appearance?.fontSize]);
+	useEffect(() => {
+		clientRef.current?.updateHeader(props.appearance?.header);
+	}, [props.appearance?.header]);
+	return /* @__PURE__ */ jsx("div", {
+		ref: hostRef,
+		className: props.className,
+		style: {
+			width: "100%",
+			height: "100%",
+			minHeight: 0,
+			...props.style
+		}
+	});
+};
+AgentEmbed.displayName = "AgentEmbed";
+//#endregion
+export { AgentEmbed, AgentEmbed as default };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.tsx"],"sourcesContent":["import { useEffect, useRef, type CSSProperties } from 'react'\nimport { createAgentEmbed, type AgentEmbedClient, type CreateAgentEmbedOptions } from '@sophonsai/agent-embed-sdk'\n\nexport * from '@sophonsai/agent-embed-sdk'\n\nexport type AgentEmbedProps = CreateAgentEmbedOptions & {\n  className?: string\n  style?: CSSProperties\n}\n\nexport const AgentEmbed = (props: AgentEmbedProps) => {\n  const hostRef = useRef<HTMLDivElement>(null)\n  const clientRef = useRef<AgentEmbedClient>(null)\n\n  useEffect(() => {\n    const host = hostRef.current\n    if (!host) {\n      return\n    }\n    const { className: _className, style: _style, ...options } = props\n    const client = createAgentEmbed(options)\n    clientRef.current = client\n    void client.mount(host).catch(() => undefined)\n    return () => {\n      client.destroy()\n      clientRef.current = null\n    }\n    // Init values and callbacks are snapshotted when the client is created.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [])\n\n  useEffect(() => {\n    clientRef.current?.updateTheme(props.appearance?.theme)\n  }, [props.appearance?.theme])\n\n  useEffect(() => {\n    clientRef.current?.updateFontSize(props.appearance?.fontSize)\n  }, [props.appearance?.fontSize])\n\n  useEffect(() => {\n    clientRef.current?.updateHeader(props.appearance?.header)\n  }, [props.appearance?.header])\n\n  return (\n    <div\n      ref={hostRef}\n      className={props.className}\n      style={{ width: '100%', height: '100%', minHeight: 0, ...props.style } as CSSProperties}\n    />\n  )\n}\n\nAgentEmbed.displayName = 'AgentEmbed'\n\nexport default AgentEmbed\n"],"mappings":";;;;;AAUA,MAAa,cAAc,UAA2B;CACpD,MAAM,UAAU,OAAuB,IAAI;CAC3C,MAAM,YAAY,OAAyB,IAAI;CAE/C,gBAAgB;EACd,MAAM,OAAO,QAAQ;EACrB,IAAI,CAAC,MACH;EAEF,MAAM,EAAE,WAAW,YAAY,OAAO,QAAQ,GAAG,YAAY;EAC7D,MAAM,SAAS,iBAAiB,OAAO;EACvC,UAAU,UAAU;EACpB,OAAY,MAAM,IAAI,CAAC,CAAC,YAAY,KAAA,CAAS;EAC7C,aAAa;GACX,OAAO,QAAQ;GACf,UAAU,UAAU;EACtB;CAGF,GAAG,CAAC,CAAC;CAEL,gBAAgB;EACd,UAAU,SAAS,YAAY,MAAM,YAAY,KAAK;CACxD,GAAG,CAAC,MAAM,YAAY,KAAK,CAAC;CAE5B,gBAAgB;EACd,UAAU,SAAS,eAAe,MAAM,YAAY,QAAQ;CAC9D,GAAG,CAAC,MAAM,YAAY,QAAQ,CAAC;CAE/B,gBAAgB;EACd,UAAU,SAAS,aAAa,MAAM,YAAY,MAAM;CAC1D,GAAG,CAAC,MAAM,YAAY,MAAM,CAAC;CAE7B,OACE,oBAAC,OAAD;EACE,KAAK;EACL,WAAW,MAAM;EACjB,OAAO;GAAE,OAAO;GAAQ,QAAQ;GAAQ,WAAW;GAAG,GAAG,MAAM;EAAM;CACtE,CAAA;AAEL;AAEA,WAAW,cAAc"}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@sophonsai/agent-embed-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React adapter for Sophon Agent Embed.",
+  "type": "module",
+  "keywords": [
+    "sophonsai",
+    "agent",
+    "agent-embed",
+    "react"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@sophonsai/agent-embed-sdk": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^6.0.2",
+    "jsdom": "^27.4.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tsdown": "^0.22.14"
+  },
+  "scripts": {
+    "build": "tsdown src/index.tsx --format esm --dts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "example": "vite --config example/vite.config.ts"
+  }
 }