OpenAgentPack Kit
组件

Layout 整页布局

可复用的桌面侧栏、移动抽屉、页头、资源面板与内容区

Layout 负责整页结构与响应式交互:桌面常驻侧栏,小于 768px 时改为模态抽屉,右侧可挂资源面板。 组件不请求数据、不处理认证或路由,也不创建 Session。

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

copy-in 接入(组合示例还需 session-sidebar / agent-header;不自动安装 npm 依赖,需自装 @openagentpack/kit-sdk/hooks、@radix-ui/react-dialog,导入共享 theme.css,外层给明确高度如 h-dvh, 员工端外观经 data-kit-appearance="workspace" 启用):

pnpm kit:add layout
pnpm kit:add session-sidebar
pnpm kit:add agent-header

交给 coding agent 接入时使用 kit-components Skill。下方示例把会话目录、对话内容和 Agent 信息放入三个区域, 并用同一个开关控制桌面右栏和移动端资源面板。主题与渲染依赖见 组件总览。 完整数据接入见 三栏对话页示例,路由、身份和会话状态由调用方持有。

import { AgentHeader, Chat, Layout, SessionSidebar } from "@openagentpack/kit-chat-ui";
import type { AgentSummary, SessionSummary } from "@openagentpack/kit-sdk/protocol";
import { type ComponentProps, type ReactNode, useState } from "react";

export interface WorkspaceLayoutProps {
	agent: AgentSummary | null;
	sessions: SessionSummary[];
	sessionId: string | null;
	onSelect: (sessionId: string) => void;
	onCreate: () => void;
	onOpenUsage: () => void;
	account?: ReactNode;
	dialogs?: ReactNode;
	resources?: ReactNode;
	// 将选中会话的 Chat 作为 children 传入。
	children: ReactNode;
}

export function WorkspaceChat({
	chat,
	...layout
}: Omit<WorkspaceLayoutProps, "children"> & {
	chat: ComponentProps<typeof Chat>;
}) {
	return (
		<WorkspaceLayout {...layout}>
			<Chat {...chat} variant="workspace" scrollKey={layout.sessionId} />
		</WorkspaceLayout>
	);
}

// 路由、身份、会话状态和确认计划由调用方管理。
// 品牌、新建会话、目录、导航及账号区域由调用方组合,SessionSidebar 负责会话目录。
export function WorkspaceLayout(props: WorkspaceLayoutProps) {
	const [searchInput, setSearchInput] = useState("");
	const [asideOpen, setAsideOpen] = useState(true);
	return (
		<div className="h-dvh" data-kit-appearance="workspace">
			<Layout
				mobileTitle="工作台"
				sidebarLabel="导航"
				header={(menuToggle) => (
					<AgentHeader
						compact
						agent={props.agent}
						leading={menuToggle}
						actions={
							<button type="button" aria-expanded={asideOpen} onClick={() => setAsideOpen((open) => !open)}>
								资源
							</button>
						}
					/>
				)}
				sidebar={({ closeSidebar, closeButton }) => (
					<aside className="flex min-h-0 w-64 shrink-0 flex-col border-r border-[var(--kit-border-subtle)] bg-[var(--kit-bg-subtle)]">
						<div className="flex min-h-16 shrink-0 items-center gap-3 px-5 py-3">
							<span className="min-w-0 flex-1 truncate font-semibold">托管 Agent</span>
							{closeButton}
						</div>
						<button
							type="button"
							onClick={() => {
								closeSidebar();
								props.onCreate();
							}}
							className="mx-3 mb-1 min-h-10 shrink-0 rounded-[var(--kit-radius-sm)] border border-dashed border-[var(--kit-border)] px-3 text-sm text-[var(--kit-fg-muted)] transition-colors duration-[var(--kit-duration-fast)] ease-[var(--kit-ease-out)] motion-reduce:transition-none hover:border-[var(--kit-border)] hover:text-[var(--kit-fg)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--kit-focus)]"
						>
							新建会话
						</button>
						<SessionSidebar
							groups={
								props.agent
									? [
											{
												id: props.agent.slug,
												name: props.agent.display_name,
												sessions: props.sessions,
												initialized: true,
											},
										]
									: []
							}
							recent={{ sessions: props.sessions, initialized: true }}
							activeId={props.sessionId}
							searchInput={searchInput}
							onSearchInput={setSearchInput}
							onSelect={(session) => {
								closeSidebar();
								props.onSelect(session.session_id);
							}}
						/>
						<nav aria-label="工作台导航" className="shrink-0 px-3 py-1">
							<button
								type="button"
								onClick={() => {
									closeSidebar();
									props.onOpenUsage();
								}}
								className="min-h-10 w-full rounded-[var(--kit-radius-sm)] px-3 py-2 text-left hover:bg-[var(--kit-surface)] focus-visible:outline-2 focus-visible:outline-[var(--kit-focus)]"
							>
								我的用量
							</button>
						</nav>
						{props.account}
					</aside>
				)}
				asideLabel="Agent 资源"
				asideOpen={asideOpen}
				onAsideOpenChange={setAsideOpen}
				aside={({ closeButton }) => (
					<div className="min-h-0 flex-1 overflow-y-auto p-4">
						<div className="flex items-center justify-between gap-2">
							<h2 className="font-medium">Agent 信息</h2>
							{closeButton}
						</div>
						<p className="mt-2 wrap-anywhere">{props.agent?.display_name ?? "选择一个 Agent"}</p>
						{props.agent?.description ? (
							<p className="mt-1 wrap-anywhere text-sm text-[var(--kit-fg-muted)]">{props.agent.description}</p>
						) : null}
						{props.resources}
					</div>
				)}
				dialogs={props.dialogs}
			>
				{props.children}
			</Layout>
		</div>
	);
}

何时使用

  • 员工端整页骨架:广场、用量、聊天页共用同一外壳与断点行为。
  • 需要移动抽屉的模态焦点、Escape 关闭与可视视口适配,不想自写。
  • 右侧资源面板:桌面停靠右列、移动全屏覆盖层,同一插槽两种形态。

代码演示

整页骨架

桌面常驻侧栏;手机预览经页头入口打开抽屉,可试会话导航、归档 / 删除确认与用量页。

Layout(导航、移动抽屉与确认操作)

侧栏开合不重建正文,输入草稿保持;确认弹窗经 dialogs 插槽渲染,抽屉打开时也在其焦点范围内。

API

Layout

属性说明类型默认值
sidebar桌面侧栏与移动抽屉共用的内容,同一时刻只挂载一份;缺省或 null 为纯内容布局ReactNode | (controls: LayoutSidebarControls) => ReactNode—
header自定义页头,把 menuToggle 接进页头操作位(如 AgentHeader.leading);通栏盖住内容区(含资源面板上方)(menuToggle: ReactNode) => ReactNode—
mobileTitle未提供 header 时移动端默认页头的标题ReactNode—
sidebarLabel抽屉的无障碍名称,同时用于打开 / 关闭入口文案string"导航菜单"
dialogs调用方持有的受控确认弹窗;抽屉打开时进入其焦点范围,跨断点仍可见,待确认状态不要只放进侧栏内部ReactNode—
aside右侧资源面板;桌面为页头之下的停靠右列(与正文同面白色),移动端为全屏覆盖层ReactNode | (controls: LayoutAsideControls) => ReactNode—
asideOpen面板受控开合;桌面收起时列宽过渡到 0,内容保持挂载并置 inertbooleantrue
asideLabel面板的无障碍名称,用于覆盖层标题与关闭按钮string"资源面板"
onAsideOpenChange面板关闭(Esc / 移动端关闭按钮 / 跨到移动断点)时回传;打开由调用方置位(open: boolean) => void—
fitViewport移动端随可视视口限高,软键盘弹出后收缩;宿主自管高度时关闭booleantrue
children主内容区(Chat、广场、用量页等)ReactNode必填

还接受标准 div 属性(className、data-* 等)。

render props 控件:sidebar 拿到 closeSidebar()(选择会话 / 新建 / 切页后先调用再执行业务动作) 与 closeButton(仅移动端,放进侧栏品牌区,不要嵌进其他按钮);aside 拿到 closeButton (仅移动端覆盖层注入,桌面开合只经页头的面板开关)。

主题变量(Design Token)

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

Token用途默认主题工作区主题
--kit-aside-width右侧面板停靠列宽,桌面开合宽度过渡的起点clamp(15rem, 22vw, 25rem)clamp(15rem, 22vw, 25rem)
--kit-bg外壳与移动面板底色(面板与正文同面白色)#ffffff#ffffff
--kit-bg-subtle侧栏与抽屉底色#f6f7fb#f7f7f7
--kit-border缺省移动页头描边#e3e6ef#e5e5e5
--kit-overlay抽屉遮罩rgb(0 0 0 / 40%)rgb(23 23 23 / 32%)
--kit-shadow抽屉与移动面板投影0 8px 28px rgb(16 19 34 / 8%)0 4px 20px rgb(23 23 23 / 6%), 0 1px 4px rgb(23 23 23 / 4%)
--kit-nav-active侧栏导航选中底色(本页演示 rail 使用)--kit-user-bubble(#eef0ff)#ececec

断点 768px 冻结在 useIsMobile;面板开合与入场消费 --kit-duration-base / --kit-ease-out / --kit-animate-panel-in;fitViewport 运行时注入 --kit-viewport-height(缺省 100dvh), Sender 等组件消费同一变量。宿主可在自己的层级覆盖 --kit-aside-width。更多主题配置见 组件总览。

本页目录