跳转到内容

React

@aidy-dev/react 把 aidy 渲染进你的产品:带对话的侧边栏(dock)、⌘K 搜索面板、审批卡片、表单、Markdown 帮助查看器,以及管理员使用的模型设置。它通过 @aidy-dev/client 与 aidy 通信。

终端窗口
npm install @aidy-dev/react @aidy-dev/client

创建一个 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。

写操作成功后,x-aidy.open 指定的页面会以 aidy.ui.open 事件送达;搜索结果和引用也带有 URL。aidy 把同源路径交给 onOpen,由你的路由切换页面而无需整页刷新。没有 onOpen 时,它直接设置 window.location。其他源的链接在新标签页打开。

  • 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() 读取所有评价。

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 内部使用。

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 save

ModelSettings 用于编辑模型链:服务商、模型、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,让两者保持一致。