React App Kit

状态：Preview。 React 接入已经落地，可用于受控集成，但接口与样式行为仍可能变化。Mobile App Kit、统一 Host Bridge 和跨端 App Manifest 不包含在本页的可用性承诺中。

目标与适用场景

本页面向需要在现有 React 网站、SaaS、CRM 或门户中加入 Fellow 交互的外部开发者。完成后，你将得到一个使用短期用户 Token 的嵌入式对话界面。

如果只需要服务端或无界面调用，请直接使用 Client SDK。如果需要文件、窗口、剪贴板等设备能力，请另行评估 Host 集成。

边界

React 入口来自 @fellow.work/client/react，不是独立 Mobile 或 Host SDK。
App Kit 负责端侧交互；Gateway、Runtime、Connector 和 Console 各有独立职责。
@fellow.work/client 覆盖 Interaction，不包装全部 AIOS 管理 API。
Fellow 原生事件流是 StreamEvent SSE；React 层消费其交互语义，不改变 wire。
Desktop、Web、Mobile 是 Applications 的官方应用案例，不是 React App Kit 本身。

前置条件

一个 React 应用；
可访问的 Fellow Gateway；
在 Console 中创建的 Integration App；
一个可信后端，用于保存 fkey_… 并交换短期 Token；
正确配置的 allowed_origins。

1. 安装

npm install @fellow.work/client react react-dom

2. 在后端交换短期 Token

服务端 Client 持有 fkey_…。浏览器不得接触该密钥。

const { access_token } = await serverClient.createAccessToken({
  origin: 'https://your-app.com',
  external_user_id: userId,
});

只向已认证的前端会话返回短期 access_token。Gateway 地址应来自你的受信配置，不要接受浏览器任意指定。external_user_id 应来自你自己的可信用户身份，不应直接采用未经校验的浏览器输入。

import { FellowChatWidget } from '@fellow.work/client/react';

export function Assistant({
  token,
  apiBaseUrl,
}: {
  token: string;
  apiBaseUrl: string;
}) {
  return (
    <FellowChatWidget
      baseUrl={apiBaseUrl}
      accessToken={token}
    />
  );
}

Widget 默认使用 Shadow DOM 隔离样式，不需要导入 @fellow.work/client/ui.css。

页内面板可使用已提供的 Lite 组件：

import { FellowChatLite } from '@fellow.work/client/react';

<FellowChatLite
  baseUrl={apiBaseUrl}
  accessToken={token}
  styleIsolation
/>

4. 自定义界面

需要自定义布局时，可以从 FellowChat、useFellowConversation 或 headless Client 开始。Preview 阶段应以所安装版本导出的 TypeScript 类型为准，不要根据本文推断未列出的 Hook 参数、事件字段或恢复 API。

建议把以下状态显式呈现给用户：

Token 获取中与鉴权失败；
Run 进行中、成功、取消和错误；
增量内容与最终内容；
需要人工批准或拒绝的 Consent；
网络中断后的可恢复提示。

5. 安全、错误与恢复

fkey_… 只保存在服务端环境变量或密钥系统中。
allowed_origins 必须与浏览器 Origin 完全匹配，包括协议和端口。
多用户应用必须为可信的 external_user_id 建立隔离。
Token 交换失败时不要降级为向浏览器发送 API Key。
CORS 或 403 错误优先检查 Origin、Scope、App 状态和 Token 是否过期。
是否自动重连、如何去重以及 Consent 恢复，应按当前 Client SDK 版本和真实事件流测试，不能仅靠 UI 乐观假设。

6. Smoke Test

未登录用户无法从你的后端取得 Token。
页面能显示 Widget 或 Lite 面板。
发起消息后能持续渲染事件流直至终态。
刷新页面后，同一可信用户不会串到其他用户的 Thread。
Network 与构建产物中不存在 fkey_…。
错误和 Consent 状态不会被静默吞掉。

兼容说明

React App Kit 当前按 Preview 管理。升级 @fellow.work/client 前，应检查包导出类型、组件属性和事件处理，并在目标 Gateway 与浏览器矩阵上重新执行 smoke test。