Skill
kit-components
覆盖全部公开组件的中文 Skill,包含 Props、子组件、组合示例和调用方责任
kit-components 指导 coding agent 使用 @openagentpack/kit-chat-ui 搭建页面。
覆盖范围以包的公开导出为准,包含所有已实现组件、静态子组件与兼容别名,不只覆盖
copy-in registry 的顶层条目。内部实现组件不作为独立公开 API。
覆盖范围
| 分类 | 已覆盖的公开组件 |
|---|---|
| 通用 | Message、MessageList、MessageAnchorRail、MessageListSkeleton、SessionList、AgentHeader |
| 唤醒 | Prompts |
| 表达 | Sender、Sender.Header、SenderHeader、Attachments、Attachments.FileCard、AttachmentFileCard、Suggestion、SkillGlyph |
| 反馈 | Actions、Actions.Copy、ActionsCopy、Actions.Feedback、ActionsFeedback、FileCard、CodeHighlighter、Mermaid |
| 富内容与审批 | Markdown、ReasoningBlock、ToolCallCard、ArtifactCard、ToolApprovalCard、ToolApprovalGroup |
| 页面组合与辅助交互 | Layout、Chat、SessionSidebar、StatusIndicator、EmptyState、ErrorState、ConfirmDialog、ThreadPanel、SubAgentPanel、Tooltip、Menu、MenuTrigger、MenuContent、MenuItem |
| 广场与用量 | PlazaCard、CategoryTabs、MeterBar、ActivityHeatmap |
API 参考为每个组件说明用途、导入方式、Props / Ref、最小示例与组合位置。静态子组件和 独立导出别名会指向同一份 API,避免两套说明漂移。生成检查同时核对公开导出与索引; 新增组件漏接入或已删除组件残留在参考中都会报错。
Skill 会指导什么
- 根据需求选择现有组件,按 registry 依赖复制源码,并接入 Tailwind 与
theme.css。 - 组合
Sender和Attachments处理文件选择、粘贴、上传状态与删除;上传逻辑由调用方传入。 - 使用
MessageList展示ChatMessage,按稳定分片 id 渲染累计快照更新,处理思考、工具与文件。 - 通过
Actions、FileCard、CodeHighlighter、Mermaid提供回答反馈和富内容展示。 - 组合完整对话页。用
Layout.sidebar放会话列表,主区放Chat,Layout.aside放 Agent 信息和资源。参考 布局示例 和 完整数据接入。 - 组合广场分类、Agent 卡片、配额进度与活跃热力图;请求与跳转由调用方负责。
消息转换规则由 Provider 定义,Chat 保存重建后的消息,组件只消费 props。只使用 UI 时也能
传入调用方构造的 ChatMessage;消息更新、身份和执行状态由调用方负责,不要求调用 SDK。
组件提供交互与展示。会话订阅和发送由 use-kit-chat 指导接入; 下载与上传请求留在调用方,上传成功也不等于文件已经挂载到 Session。 默认 Kit Server 的附件挂载时机见 Attachments。
组合示例
下面的示例与 Skill 使用同一份源文件,可以直接交给 coding agent 参考。
import {
type AttachmentItem,
Attachments,
type AttachmentsRef,
Sender,
type SenderRef,
type SenderSelection,
type SenderSkill,
SkillGlyph,
Suggestion,
} from "@openagentpack/kit-chat-ui";
import { skillInputTokens } from "@openagentpack/kit-sdk/protocol";
import { useEffect, useRef, useState } from "react";
interface UploadedAttachment extends AttachmentItem {
fileId?: string;
}
export interface AttachmentSenderProps {
uploadFile: (file: File) => Promise<{ file_id: string }>;
// 在应用回调中处理会话挂载,上传只得到文件引用。
onSubmit: (text: string, fileIds: string[], skills?: string[]) => Promise<void>;
skills?: SenderSkill[];
onStop: () => void;
canSend: boolean;
turnRunning: boolean;
}
const maxCount = 8;
export function AttachmentSender({
uploadFile,
onSubmit,
onStop,
canSend,
turnRunning,
skills,
}: AttachmentSenderProps) {
const [draft, setDraft] = useState("");
const [selection, setSelection] = useState<SenderSelection>({ start: 0, end: 0 });
const sender = useRef<SenderRef>(null);
const [files, setFiles] = useState<UploadedAttachment[]>([]);
const [open, setOpen] = useState(false);
const [submitting, setSubmitting] = useState(false);
const [error, setError] = useState<string | null>(null);
const attachments = useRef<AttachmentsRef>(null);
const currentFiles = useRef(files);
const mounted = useRef(false);
const sending = useRef(false);
useEffect(() => {
mounted.current = true;
return () => {
mounted.current = false;
};
}, []);
const updateFiles = (update: (previous: UploadedAttachment[]) => UploadedAttachment[]) => {
if (!mounted.current) return;
currentFiles.current = update(currentFiles.current);
setFiles(currentFiles.current);
};
const selectFiles = (selected: File[]) => {
if (turnRunning || sending.current) return;
const accepted = selected.slice(0, Math.max(0, maxCount - currentFiles.current.length));
const uploads = accepted.map((file) => ({
file,
item: {
uid: crypto.randomUUID(),
name: file.name,
size: file.size,
type: file.type,
status: "uploading" as const,
},
}));
updateFiles((previous) => [...previous, ...uploads.map(({ item }) => item)]);
setOpen(true);
setError(null);
for (const { file, item } of uploads) {
// 让应用上传函数抛出的同步异常也进入失败处理。
void Promise.resolve()
.then(() => uploadFile(file))
.then(
(result) =>
updateFiles((previous) =>
previous.map((entry) =>
entry.uid === item.uid
? { ...entry, fileId: result.file_id, status: "done", description: "已就绪" }
: entry,
),
),
() =>
updateFiles((previous) =>
previous.map((entry) =>
entry.uid === item.uid
? { ...entry, status: "error", description: "上传失败,请移除后重新选择。" }
: entry,
),
),
);
}
};
const submit = async (text: string, selectedSkills?: string[]) => {
const selected = currentFiles.current;
if (
!canSend ||
turnRunning ||
sending.current ||
!text.trim() ||
selected.some((file) => file.status !== "done" || !file.fileId)
) {
return;
}
sending.current = true;
setSubmitting(true);
setError(null);
try {
await onSubmit(
text.trim(),
selected.flatMap((file) => (file.fileId ? [file.fileId] : [])),
selectedSkills,
);
if (!mounted.current) return;
setDraft((current) => (current === text ? "" : current));
const submitted = new Set(selected.map((file) => file.uid));
updateFiles((previous) => previous.filter((file) => !submitted.has(file.uid)));
} catch {
if (mounted.current) setError("发送失败,已保留草稿和文件。");
} finally {
sending.current = false;
if (mounted.current) setSubmitting(false);
}
};
const filesBlocked = files.some((file) => file.status !== "done" || !file.fileId);
const skillNames = skills?.map((skill) => skill.name) ?? [];
return (
<div className="flex flex-col gap-2" data-kit-appearance="workspace">
<Suggestion
block
items={(skills ?? []).map((skill) => ({
value: skill.name,
label: skill.name,
description: skill.description,
icon: <SkillGlyph className="size-4" />,
}))}
value={draft}
caret={selection.end}
trigger="/"
filter={(item, query) =>
item.value.toLowerCase().startsWith(query.toLowerCase()) &&
!skillInputTokens(draft, skillNames).includes(item.value)
}
onSelect={(_, item, context) => {
if (!context) return;
const end = draft[context.end] === " " ? context.end + 1 : context.end;
sender.current?.replaceRange(context.start, end, `/${item.value} `);
}}
>
{({ onKeyDown, inputProps }) => (
<Sender
ref={sender}
onSelectionChange={setSelection}
onKeyDown={onKeyDown}
inputProps={inputProps}
variant="workspace"
value={draft}
skills={skills}
onChange={setDraft}
placeholder="输入消息或粘贴文件"
loading={turnRunning}
submitDisabled={!canSend || submitting || filesBlocked}
onSubmit={(text, selectedSkills) => void submit(text, selectedSkills)}
onCancel={onStop}
onPasteFile={selectFiles}
header={
<Sender.Header title="附件" open={open} onOpenChange={setOpen}>
<Attachments
ref={attachments}
items={files}
maxCount={maxCount}
disabled={turnRunning || submitting}
onSelectFiles={selectFiles}
onRemove={(item) => updateFiles((previous) => previous.filter((file) => file.uid !== item.uid))}
placeholder={(type) => ({
title: type === "drop" ? "松开以添加文件" : "选择文件",
description: type === "inline" ? "选择、粘贴或拖放文件" : undefined,
})}
/>
</Sender.Header>
}
prefix={
<button
type="button"
disabled={turnRunning || submitting}
onClick={() => {
if (open) attachments.current?.select();
else setOpen(true);
}}
>
添加文件
</button>
}
suffix={(_origin, { components }) =>
turnRunning ? (
<components.LoadingButton>停止</components.LoadingButton>
) : (
<components.SendButton>{submitting ? "发送中" : "发送"}</components.SendButton>
)
}
footer={({ components }) => <components.ClearButton>清空输入</components.ClearButton>}
/>
)}
</Suggestion>
{error ? <p role="alert">{error}</p> : null}
</div>
);
}其他可编译示例覆盖通用与页面组合、 富内容与反馈、 提示集与快捷指令以及 工具审批。
示例任务
Use kit-components to compose a chat page with MessageList, Sender, and Attachments.
Use caller-provided upload and download callbacks, show tool approval requests,
and preserve stable fragment IDs when snapshots change.组件的交互预览、copy-in 命令与中文 API 说明见组件总览。