4. 接入聊天页面

开始前： 后台 8091 已启动，会话列表检查通过。本步目标： 在浏览器里使用现成聊天组件，前端只连接业务后台。

1. 选择框架并安装

React / Vue 二选一。在对应目录确认 vendor/sparktide-frontend-sdk-0.1.0.tgz 已放好，再安装：

React

cd frontend-react  # 从 tutorial 根目录进入
npm ci
npm run check
npm run dev

Vue

cd frontend-vue    # 从 tutorial 根目录进入
npm ci
npm run check
npm run dev

这里用 npm；依赖包也可以使用前端 SDK 安装中的 pnpm / Yarn 方式。React 和 Vue 项目共用 5173 端口，同时体验时请先停止其中一个。

2. 配置业务 API 地址

两个项目的 vite.config.mjs 已把浏览器的同源 /api/ai 代理到 http://127.0.0.1:8091：

import {defineConfig} from 'vite';
export default defineConfig({
  server: {proxy: {'/api/ai': 'http://127.0.0.1:8091'}}
});

这是开发代理。 生产需由自己的域名网关转发 /api/ai，Vite 打包不会带着代理上线。浏览器不配置底座 8080、appId、模型 Key 或平台令牌。

3. 使用 SDK 的 ChatPanel

完整入口文件已经包含登录输入与 ChatPanel，选择与你项目相符的一份阅读：

React

import {createRoot} from 'react-dom/client';
import {useState} from 'react';
import {createChatClient, type ChatClient} from '@sparktide/frontend-sdk';
import {ChatPanel} from '@sparktide/frontend-sdk/react';
import './style.css';
function App() {
  const [token, setToken] = useState('');
  const [client, setClient] = useState<ChatClient>();
  return <main><h1>我的第一个业务助手</h1>{client ? <>
    <button onClick={() => {setClient(undefined); setToken('');}}>退出本地登录</button>
    <ChatPanel client={client} label="业务助手"/>
  </> : <form onSubmit={event => {
    event.preventDefault();
    const businessToken = token.trim();
    if (businessToken) setClient(createChatClient({baseUrl:'/api/ai', token:() => businessToken}));
  }}>
    <label>本地业务登录令牌<input type="password" autoComplete="off" value={token}
      onChange={event => setToken(event.target.value)} required/></label>
    <p>使用 .local/browser-token.txt；平台管理员与 USER 凭据留在后台。</p>
    <button>连接助手</button>
  </form>}</main>;
}
createRoot(document.getElementById('app')!).render(<App/>);

Vue

import {createApp, defineComponent, h, shallowRef} from 'vue';
import {createChatClient, type ChatClient} from '@sparktide/frontend-sdk';
import {ChatPanel} from '@sparktide/frontend-sdk/vue';
import './style.css';
const App = defineComponent({setup() {
  const token = shallowRef('');
  const client = shallowRef<ChatClient>();
  return () => h('main', [h('h1','我的第一个业务助手'), client.value ? h('div', [
    h('button',{onClick:() => {client.value = undefined; token.value = '';}},'退出本地登录'),
    h(ChatPanel,{client:client.value,label:'业务助手'})
  ]) : h('form',{onSubmit:(event:Event) => {
    event.preventDefault();
    const businessToken = token.value.trim();
    if (businessToken) client.value = createChatClient({baseUrl:'/api/ai',token:() => businessToken});
  }},[
    h('label',['本地业务登录令牌',h('input',{type:'password',autocomplete:'off',required:true,
      value:token.value,onInput:(event:Event) => {token.value=(event.target as HTMLInputElement).value;}})]),
    h('p','使用 .local/browser-token.txt；平台管理员与 USER 凭据留在后台。'),
    h('button','连接助手')
  ])]);
}});
createApp(App).mount('#app');

关键是 createChatClient({baseUrl:'/api/ai',token:...}) 和对应框架的 ChatPanel。客户端在页面生命周期内保持稳定。组件封装会话列表、历史、发送、取消、危险操作确认、改名和删除，无需自写 fetch、事件解析或会话页面。

正式业务的 token 函数返回业务登录令牌。若用 Cookie 登录，见前端 SDK 的认证配置。自定义布局再读React 与 Vue 状态层。

检查点

打开 http://127.0.0.1:5173，把 .local/browser-token.txt 中的本地业务登录令牌填入“本地业务登录令牌”，点击“连接助手”。应看见“业务助手”、会话列表和消息输入框，首次列表为空。

此令牌只保存在当前页面内存，刷新后需要重新输入；平台 USER 和应用管理员令牌都保留在后台。如果连接失败，先确认第 3 步的会话列表请求通过，再检查 5173 的代理目标。