React
@aidy-dev/react 把 aidy 渲染进你的产品:带对话的侧边栏(dock)、⌘K 搜索面板、审批卡片、表单、Markdown 帮助查看器,以及管理员使用的模型设置。它通过 @aidy-dev/client 与 aidy 通信。
npm install @aidy-dev/react @aidy-dev/client配置 Provider
Section titled “配置 Provider”创建一个 client,用 AidyProvider 包住需要显示 aidy 的部分,并引入一次样式表。
import { createClient } from '@aidy-dev/client';import { AidyDock, AidyProvider, SearchPalette } from '@aidy-dev/react';import '@aidy-dev/react/styles.css';import { useMemo } from 'react';import { useNavigate } from 'react-router';
export function Shell({ children }: { children: React.ReactNode }) { const navigate = useNavigate(); const client = useMemo( () => createClient({ headers: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }), }), [], ); return ( <AidyProvider client={client} locale="zh-CN" theme="system" onOpen={navigate} upload={uploadToYourStorage} context={() => [{ description: 'The page the user is on', value: location.pathname }]} > {children} <AidyDock /> <SearchPalette /> </AidyProvider> );}createClient 的选项:
| 选项 | 含义 |
|---|---|
baseUrl |
aidy 挂载的位置:''(默认,当前页面的源)、一个源(https://console.example.com),或一个路径前缀(/assistant,即宿主的 basePath)。client 会自己加上 /aidy/v0,所以不要传 /aidy/v0。 |
headers |
每次请求前调用,例如加上用户的 Authorization。如果浏览器 cookie 已能认证用户,可以省略。 |
fetch |
自定义 fetch,用于测试。 |
AidyProvider 的属性:
| 属性 | 含义 |
|---|---|
client |
上面创建的 client。 |
locale |
任意 BCP 47 语言标签,默认 'en'。决定界面文案以及 aidy 元素的 lang(见文案与语言)。 |
strings |
Partial<Strings>:按键替换内置文案。 |
upload |
(file: File) => Promise<UploadedFile>({ url, mimeType, name? }):保存用户附加的文件,返回模型能获取的 URL。不提供时输入框不支持附件。 |
context |
() => { description, value }[]:用户正在看的内容。每次运行开始时调用(无论是新消息,还是回答审批或表单),作为该运行的 AG-UI context 发送。 |
theme |
'light'、'dark' 或 'system'(默认,跟随 prefers-color-scheme)。 |
onOpen |
显示产品页面。只会收到同源路径(/path?query#hash)。 |
Provider 会从 GET /aidy/v0/info 读取一次助手名称(createAidy({ name })、AIDY_NAME),并用在所有提到助手的文案里:侧边栏标题、“打开 {name}”、“给 {name} 发消息…”、“问 {name}”。在请求返回之前或请求失败时,名称为 Aidy。
用 onOpen 导航
Section titled “用 onOpen 导航”写操作成功后,x-aidy.open 指定的页面会以 aidy.ui.open 事件送达;搜索结果和引用也带有 URL。aidy 把同源路径交给 onOpen,由你的路由切换页面而无需整页刷新。没有 onOpen 时,它直接设置 window.location。其他源的链接在新标签页打开。
侧边栏与搜索面板
Section titled “侧边栏与搜索面板”AidyDock是侧边面板,包含启动按钮、对话和历史记录。⌘J(Ctrl+J)切换显示,Escape 关闭,在窄屏上占满整个屏幕。审批和表单直接显示在对话中。SearchPalette用 ⌘K(Ctrl+K)打开。它并行搜索所有搜索源,按类型分组展示。方向键移动,Enter 打开,最后一行把查询交给助手。
AidyDock 的属性:
| 属性 | 含义 |
|---|---|
open、onOpenChange |
受控地决定面板是否打开。 |
threadId、onThreadChange |
受控地决定显示哪个对话;null 表示新对话。 |
非受控时,侧边栏会把是否打开和当前对话记在 localStorage 的 aidy:dock:<client.baseUrl> 下(baseUrl 为空时用页面的源),挂载后恢复,因此刷新或切换页面后对话仍在。受控的值优先于记住的状态。存储被禁用或抛错时,它就不记。
SearchPalette 的属性:
| 属性 | 含义 |
|---|---|
open、onOpenChange |
受控地决定面板是否打开。 |
onAsk |
(query) => void:接收最后一行的查询。默认打开侧边栏,把查询作为新问题。 |
结果分组的标题来自结果的 type:strings={{ 'type.work_item': '工作项' }} 为它命名,没有对应文案的类型按可读形式显示(work_item → Work item)。
在自己的界面中用 useDock 打开侧边栏:
import { useDock } from '@aidy-dev/react';
function StopButton({ name }: { name: string }) { const dock = useDock(); return <button onClick={() => dock.ask(`stop ${name}`)}>Ask Aidy</button>;}useDock() 返回 { open, setOpen, ask };ask(query) 打开侧边栏,并以 query 开始一段新对话。
useSearchPalette() 返回 { isOpen, open(query?), close() },适合放在页头的搜索按钮上,或在没有 ⌘K 的手机上使用:
import { useSearchPalette } from '@aidy-dev/react';
function SearchButton() { const palette = useSearchPalette(); return <button onClick={() => palette.open()}>搜索</button>;}提供 upload 后,输入框带有附件按钮(可一次选多个文件),也接受拖到对话上的文件,以及粘贴到输入框的文件或图片。上传中的文件显示为缩略图(图片)或文件名标签,各带一个移除按钮;上传失败会给出提示,且不会随消息发送。消息可以只有附件、没有文字。已发送的图片显示为缩略图,文件显示为标签,点击都在新标签页打开。
import type { UploadedFile } from '@aidy-dev/react';
async function uploadToYourStorage(file: File): Promise<UploadedFile> { const body = new FormData(); body.append('file', file); const { url } = await fetch('/api/files', { method: 'POST', body }).then((r) => r.json()); return { url, mimeType: file.type, name: file.name }; // e.g. /files/f_123}文件需要用户凭据才能访问时,返回宿主上的路径(或宿主源下的 URL):aidy 会以用户身份获取它,并内联给视觉模型。其他 URL 原样交给服务商。见 AG-UI:用户消息和模型:视觉。
每条完成的回答都有赞和踩,通过 client.setFeedback 发送到 PUT …/feedback。点踩时可以选填评论。用户可以修改评价;发送失败只会显示一条提示。管理员用 client.listFeedback() 读取所有评价。
自建对话界面
Section titled “自建对话界面”AidyThread 在侧边栏之外渲染单个对话(属性为 threadId、onThreadCreated、initialMessage)。需要完全自定义布局时,使用 hooks 和底层组件:
import { answerApproval, answerForm } from '@aidy-dev/client';import { AidyForm, ApprovalCard, useThread } from '@aidy-dev/react';
function Interrupts({ threadId }: { threadId: string }) { const thread = useThread(threadId); return thread.state.interrupts.map((open) => open.kind === 'approval' ? ( <ApprovalCard key={open.id} interrupt={open} onAnswer={(approved) => thread.resume([answerApproval(open, approved)])} /> ) : open.kind === 'input' ? ( <AidyForm key={open.id} form={open.form} onSubmit={(answers) => thread.resume([answerForm(open, answers)])} /> ) : null, );}ApprovalCard展示操作的影响和冻结后的参数,审批过期(15 分钟)后自动禁用。answerApproval会回传argsHash,使审批绑定到用户看到的内容。详见审批。AidyForm先按表单规则校验答案,再调用onSubmit。详见表单。state.citations以{ n, hit }[]保存每条消息的引用;Markdown的citations属性把正文中的[n]链接到编号为n的引用,没有对应引用的编号保持纯文本。- 只用
@aidy-dev/client时,attachmentPart({ url, mimeType, name? })为已上传的文件构造图片或文档 part,供run(threadId, { message, context? })使用。
| Hook | 返回值 |
|---|---|
useThread(threadId) |
{ threadId, state, error, send, resume, cancel };回放并持续跟随对话事件。send 接受文本或 AG-UI content part。 |
useThreads() |
用户的对话列表,按时间倒序,提供 loadMore、reload 和 remove。 |
useSearch(query) |
联合搜索,防抖 150 ms。 |
useCatalog() |
当前用户可见的操作。 |
它们都必须在 AidyProvider 内部使用。
帮助查看器与模型设置
Section titled “帮助查看器与模型设置”import { HelpViewer, ModelSettings } from '@aidy-dev/react';
<HelpViewer url="/help/getting-started.md" />; // relative links and images resolve against it<ModelSettings />; // admin form for the model chain; needs aidy:admin to saveModelSettings 用于编辑模型链:服务商、模型、Base URL、API 密钥、temperature、最大输出 token 数以及是否支持图片。API 密钥只写不读:表单只显示是否已保存密钥,密钥栏留空则保留原有密钥。新增的行会得到 id model-N。代码中配置的模型(provider 为 custom)只读显示;保存会替换掉它们,表单会提示这一点。恢复默认会先请求确认,然后调用 client.resetSettings()(DELETE /aidy/v0/settings)并显示配置中的模型链。
每个组件,无论放在侧边栏里还是单独使用(AidyThread、SearchPalette、ModelSettings、HelpViewer),都带有 .aidy-root 的主题变量、data-aidy-theme 和 lang。样式会显式设置自己依赖的一切(列表、标题、链接、代码、表格、按钮、输入框),因此 Tailwind preflight 这类 CSS reset 不会改变它们。
所有颜色和尺寸都是 .aidy-root 上的 CSS 变量,在你的样式表中覆盖即可:
.aidy-root { --aidy-accent: #0f766e; --aidy-accent-fg: #ffffff; --aidy-accent-soft: #ccfbf1; --aidy-radius: 6px; --aidy-font: Inter, system-ui, sans-serif; --aidy-dock-width: 460px;}.aidy-root[data-aidy-theme="dark"] { --aidy-accent: #2dd4bf;}完整列表:--aidy-bg, --aidy-fg, --aidy-muted, --aidy-surface, --aidy-border, --aidy-accent, --aidy-accent-fg, --aidy-accent-soft, --aidy-danger, --aidy-danger-soft, --aidy-warning, --aidy-warning-soft, --aidy-success, --aidy-mark, --aidy-overlay, --aidy-shadow, --aidy-radius, --aidy-font, --aidy-mono, --aidy-dock-width. 使用 theme="system" 时,深色取值在 prefers-color-scheme: dark 下生效。
locale 可以是任意 BCP 47 语言标签。zh-CN 有自己的文案,其他标签都使用英文。locales 包含内置的文案表 locales.en 和 locales['zh-CN'],类型为 Strings。查找一条文案时依次查 strings、该语言的文案表、英文表,未知的键原样显示。
import { AidyProvider, type Strings } from '@aidy-dev/react';
const ja: Partial<Strings> = { send: '送信', 'type.work_item': '作業項目' };
<AidyProvider client={client} locale="ja" strings={ja}>…</AidyProvider>;文案中的 {name} 是 assistant 文案,它默认取自 /info 返回的名称,所以 strings={{ assistant: 'Copilot' }} 会在所有地方改掉助手的名字。type.<type> 键为搜索结果分组命名。
locale 只决定 aidy 自身的界面文案。助手的回复语言跟随用户:取决于身份中的 locale 和用户实际使用的语言。根据应用的语言设置选择 locale,让两者保持一致。