OpenAgentPack Kit
组件

Chat 与 Sender 组合

消息列表、流式中间态与输入框的在线预览

Chat 组合 MessageList 与 Sender,只认 props,不 fetch、不依赖 server。

import { Chat } from "@openagentpack/kit-chat-ui";

copy-in 接入(复制后 import 改为项目内路径):

pnpm kit:add chat

交给 coding agent 接入时使用 kit-components Skill;主题与渲染依赖见 组件总览。

何时使用

  • 需要「消息列表 + 输入框」标准组合:流式中间态、审批嵌入、欢迎态与滚动跟随一次到位。
  • 只要列表或只要输入框时,分别用 MessageList 与 Sender。

代码演示

预览使用本地模拟数据,不连接服务;演示面板内可查看源码与接入命令。

流式中间态与欢迎态

发送、停止、技能 chip 与欢迎态都可操作。

Chat(消息列表 + Sender + 流式)

多 Agent 对话

子 Agent 卡片、只读历史、分页与重试可操作;先输入草稿再开合卡片,观察草稿不变。

Chat(主子 Agent、历史分页与重试)

接入

示例放在已配置的 KitProvider 下,由 Layout 或宿主提供有界高度; 外层按主题约定设置 data-kit-appearance="workspace"。自建 Provider 的 useChat({ sessionId, provider }) 使用同一组 props。

import { Chat, type SenderSkill, ToolApprovalCard } from "@openagentpack/kit-chat-ui";
import { useChat } from "@openagentpack/kit-sdk/chat/hooks";
import { useState } from "react";

// 在已配置的 KitProvider 内渲染,并为 Layout 内容区设置有界高度。
// 接入自建后端时,同一组件也可使用 useChat({ sessionId, provider })。
export function SessionChat({ sessionId, skills }: { sessionId: string | null; skills?: SenderSkill[] }) {
	const chat = useChat(sessionId);
	const [error, setError] = useState<string | null>(null);
	const report = (cause: unknown) => setError(cause instanceof Error ? cause.message : "请求失败。");

	return (
		<div className="flex min-h-0 flex-1 flex-col" data-kit-appearance="workspace">
			{error || chat.streamError ? <p role="alert">{error ?? chat.streamError?.message}</p> : null}
			<Chat
				variant="workspace"
				messages={chat.messages}
				skills={skills}
				multiAgent={chat.multiAgent}
				scrollKey={sessionId}
				turnRunning={chat.turnRunning}
				canSend={chat.canSend}
				onSend={async (text, selectedSkills) => {
					setError(null);
					try {
						await chat.send(text, { skills: selectedSkills });
					} catch (cause) {
						report(cause);
						throw cause; // 让 Chat 在发送失败时保留草稿。
					}
				}}
				onStop={() => chat.stop().catch(report)}
				approvals={
					chat.approvals.length > 0
						? chat.approvals.map((approval) => (
								<ToolApprovalCard
									key={JSON.stringify([approval.batch_id, approval.call_id])}
									approval={approval}
									onDecision={chat.submitApproval}
									onRefresh={chat.refreshApprovals}
									onStop={() => void chat.stop().catch(report)}
								/>
							))
						: null
				}
			/>
		</div>
	);
}
  • 默认 Sender 的草稿在提交成功且未被改写时才清空,失败、等待审批或重连时保留;scrollKey 变化只重置滚动跟随、不重新挂载输入框,也不要给整个 Chat 加变化的 key。
  • onSend(text, selectedSkills) 接 chat.send(text, { skills: selectedSkills }),不要直接赋 chat.send(hook 第二参数是选项对象);技能候选来自当前 Agent 的 resources.skills, 未知技能按原文还原。
  • approvals 无审批时传 null;传空数组或始终存在的空 JSX 仍会显示「等待审批」提示。

多 Agent 对话

传入 multiAgent={chat.multiAgent},契约见 ChatMultiAgent。执行中的子 Agent 自动展开、完成后收起,也可手动开合;历史经 loadThreadEvents(id, { more }) 翻页、 { retry: true } 重试,无历史查询能力时明确提示。子 Agent 无独立输入与审批入口,主输入区的 停止按钮停止整个主会话。资源面板可另接 SubAgentPanel。

自定义输入区

附件、快捷指令或自定义提交策略通过 sender 插槽接入,完整组合见 Sender 附件示例 与 Suggestion。 自定义 Sender 传 variant="workspace",并连接 value、onChange、onSubmit、 loading={chat.turnRunning}、submitDisabled={!chat.canSend} 与 onCancel={chat.stop}; 此时 Chat 不再接管输入区,但仍需传 turnRunning 供等待首帧指示。

Props

属性类型默认值说明
messagesChatMessage[]必填主 Agent 消息,传给 MessageList
multiAgentChatMultiAgent—直接传入 useChat().multiAgent,在消息流中展示子 Agent 卡片、只读历史、分页与重试
turnRunningbooleanfalse默认 Sender 是否显示停止按钮
sendingbooleanfalse发送请求在途(含新建会话):乐观气泡出现前列表尾显示「发送中…」指示,回合开始后归「生成中…」
canSendbooleantrue是否允许提交;设 false 仍可编辑草稿
composerDisabledbooleanfalse禁用默认输入区,例如配额耗尽;已有生成仍可停止。自定义 sender 需自行传入 disabled
approvalsReactNode—主 Agent 当前待办审批卡,内嵌到消息流末尾;输入区上方只留精简等待提示
onSend(text: string, skills?: string[]) => void | Promise<void>—默认 Sender 提交文本和派生技能名;成功后清理未被改写的草稿
onStop() => void | Promise<void>—默认 Sender 的停止回调
onArtifactDownload(fileId: string) => void—文件下载回调
onArtifactOpen(fileId: string, contentType?: string) => void—文件名称的预览回调;与下载入口独立
skillsSenderSkill[]—当前 Agent 的技能候选,传给默认 Sender 与消息列表;自定义 sender 需另行传入
virtualizebooleantrue长会话分窗渲染开关,透传 MessageList
onCopy(text: string) => void | Promise<void>浏览器剪贴板回答复制能力,透传到 MessageList;Web 体验页接入本地宿主能力
emptyReactNode—消息为空时的占位(欢迎态);输入区保持挂载,消息出现后退出
scrollKeystring | null—逻辑会话标识;变化时恢复滚底跟随
senderReactNode—替换默认 Sender
anchorRailbooleanfalse主会话右缘显示回合锚点栏;规则见 MessageList 回合锚点栏
variant"default" | "workspace""default"workspace 用 --kit-chat-width 居中阅读宽度对齐消息、审批与输入区

同一会话中向上阅读历史会暂停跟随,回到底部、scrollKey 变化或消息清空后恢复;关闭自动跟随时 直接组合 MessageList autoScroll={false} 与 Sender。

主题变量(Design Token)

引入 @openagentpack/kit-chat-ui/theme.css 后使用以下冻结 token。下表列出亮色值, 暗色由 data-kit-theme="dark" 使用对应色板。

Token用途默认主题工作区主题
--kit-chat-widthworkspace 阅读宽度:消息、审批提示与输入区共用同一居中宽度48rem48rem
--kit-warning-fg「等待审批」精简提示文字与呼吸点#b45309#805917
--kit-border-subtle默认布局中输入区的上边界线(workspace 布局无边框)var(--kit-border)#ececec

「等待审批」提示走 --kit-text-label 文字档位;输入区底部留白用 --kit-space-3 / --kit-space-6 与移动端安全区取较大值。消息与输入区本体(气泡、分片、 工具卡、附件、技能 chip)的 token 分别见 MessageList、 Message 与 Sender;更多主题配置见 组件总览。

本页目录