13 KiB

Raw Blame History

AgentKit 组件库完整设计

基于全局 UI/UX 规范的组件库规划。覆盖：通用基础、状态反馈、表单、数据展示、导航、反馈层、业务复合、多维表格、日历、Dashboard。目标：消除跨页面重复样式，新增功能直接组装组件，不再手写 UI。

设计原则

薄封装 Ant Design Vue：不重造轮子，只统一 token、尺寸、圆角、间距。
组件只管外观，布局归页面：grid/flex 由调用方决定。
按域分组：components/ui/ 通用，components/bitable/、components/calendar/ 等业务域保持独立。
迁移渐进：旧页面不强制重写，新页面必须用组件库。

组件分层

components/
├── ui/                    # 通用基础（跨所有页面）
│   ├── primitives/        # 原子：Button/Icon/Tag/Badge/Avatar/Tooltip
│   ├── feedback/          # 状态：Empty/Loading/Error/Spin
│   ├── form/              # 表单：FormField/Input/Select/DatePicker/Switch/Checkbox/Radio/TextArea/SearchInput/FormSection
│   ├── data/              # 数据：DataTable/List/ListItem/Description/Timeline/Stat/CodeBlock
│   ├── navigation/        # 导航：Tabs/Breadcrumb/Pagination
│   └── overlay/           # 浮层：Drawer/Modal
├── layout/                # 应用级布局（已有：SideNav/AppLayout 等）
├── bitable/               # 多维表格域（已有）
├── calendar/              # 日历域（已有）
├── chat/                  # 聊天域（已有）
├── evolution/             # 自进化域（已有）
├── kb/                    # 知识库域（已有）
├── skills/                # 技能域（已有）
└── workflow/              # 工作流域（已有）

1. 通用基础（components/ui）

1.1 已实现

组件	文件	状态
`UiCard`	`UiCard.vue`	✅
`UiMetricCard`	`UiMetricCard.vue`	✅
`UiTrendBadge`	`UiTrendBadge.vue`	✅
`UiPageHeader`	`UiPageHeader.vue`	✅
`UiPageShell`	`UiPageShell.vue`	✅

1.2 原子组件（primitives）

UiButton

统一按钮高度（32/40px）、圆角（--radius-lg）、4 种类型。

Prop	类型	说明
`type`	`'primary' \| 'secondary' \| 'ghost' \| 'icon'`	按钮类型
`size`	`'sm' \| 'md' \| 'lg'`	高度 28/32/40px
`loading`	`boolean`	加载态
`disabled`	`boolean`	禁用
`icon`	`Component`	前置图标
`block`	`boolean`	撑满宽度

UiTag

pill 标签，语义色。

Prop	类型	说明
`type`	`'default' \| 'success' \| 'warning' \| 'error' \| 'info'`	语义色
`size`	`'sm' \| 'md'`	高度 20/24px
`closable`	`boolean`	可关闭

UiBadge

状态点（success/error/warning/processing/default）。

Prop	类型	说明
`status`	`'success' \| 'error' \| 'warning' \| 'processing' \| 'default'`	状态
`text`	`string`	文本
`dot`	`boolean`	仅圆点

UiAvatar

头像，支持文字/图片/图标回退。

Prop	类型	说明
`src`	`string`	图片地址
`text`	`string`	文字（取首字）
`icon`	`Component`	图标
`size`	`'sm' \| 'md' \| 'lg'`	24/32/40px
`color`	`string`	背景色（可选）

UiIcon

统一图标尺寸与颜色继承。

Prop	类型	说明
`icon`	`Component`	图标组件
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	12/14/16/20px

UiTooltip

封装 a-tooltip，统一主题色与延迟。

1.3 状态反馈（feedback）

UiEmpty

统一空状态（替代散落的 a-empty）。

Prop	类型	说明
`description`	`string`	说明文字
`image`	`'default' \| 'search' \| 'network'`	插画类型
插槽 `action`	—	操作按钮

UiLoading

骨架屏，从 bitable/LoadingState 提炼。

Prop	类型	说明
`variant`	`'skeleton' \| 'spin' \| 'dots'`	加载样式
`rows`	`number`	骨架行数
`title`	`boolean`	是否显示标题占位
`fullPage`	`boolean`	全屏遮罩

UiError

错误提示，从 bitable/ErrorState 提炼。

Prop	类型	说明
`type`	`'error' \| 'warning' \| 'info'`	类型
`message`	`string`	标题
`description`	`string`	详情
`retryable`	`boolean`	显示重试按钮
事件 `retry`	—	重试回调

UiSpin

局部加载旋转（卡片内、按钮内）。

1.4 表单（form）

UiFormField

表单项容器：label + control + hint + error。

Prop	类型	说明
`label`	`string`	标签
`required`	`boolean`	必填星号
`error`	`string`	错误信息
`hint`	`string`	辅助说明
插槽 `default`	—	控件

UiInput

统一输入框（40px 高、--radius-md、focus 边框）。

Prop	类型	说明
`modelValue`	`string`	值
`placeholder`	`string`	—
`size`	`'sm' \| 'md'`	32/40px
`disabled`	`boolean`	—
`prefix` / `suffix`	插槽	前/后置

UiTextArea

多行输入，自适应高度。

Prop	类型	说明
`modelValue`	`string`	—
`rows`	`number`	默认 3
`autoSize`	`boolean`	自适应
`maxLength`	`number`	—

UiSelect

封装 a-select，统一样式与清空/搜索行为。

Prop	类型	说明
`modelValue`	`any`	—
`options`	`{ label, value }[]`	—
`placeholder`	`string`	—
`multiple`	`boolean`	多选
`searchable`	`boolean`	可搜索
`clearable`	`boolean`	可清空

UiDatePicker / UiDateRangePicker

日期/日期范围选择，统一格式与主题。

Prop	类型	说明
`modelValue`	`Dayjs \| string`	—
`showTime`	`boolean`	含时间
`format`	`string`	显示格式

UiSwitch

开关。

UiCheckbox / UiCheckboxGroup

复选框与组。

UiRadio / UiRadioGroup

单选框与组。

UiSearchInput

搜索输入框（带搜索图标、清空、防抖）。

Prop	类型	说明
`modelValue`	`string`	—
`placeholder`	`string`	—
`debounce`	`number`	防抖 ms（默认 300）
事件 `search`	—	搜索回调

UiFormSection

表单分组卡片（标题 + 内容区）。

Prop	类型	说明
`title`	`string`	分组标题
`description`	`string`	说明

1.5 数据展示（data）

UiDataTable

封装 a-table，统一行高、表头、边框、空状态、分页。

Prop	类型	说明
`columns`	`Column[]`	—
`dataSource`	`T[]`	—
`loading`	`boolean`	—
`pagination`	`false \| PaginationConfig`	—
`rowKey`	`string \| Function`	—
插槽 `empty`	—	自定义空状态

多维表格继续使用 BitableGrid（更高定制），普通 CRUD 表用 UiDataTable。

UiList / UiListItem

垂直列表容器与项。

Prop (UiList)	类型	说明
`bordered`	`boolean`	分隔线
`hoverable`	`boolean`	hover 高亮

Prop (UiListItem)	类型	说明
`avatar`	插槽	头像位
`title`	插槽	标题
`description`	插槽	描述
`extra`	插槽	右侧操作

UiDescription

描述列表（key-value 对齐布局）。

Prop	类型	说明
`columns`	`number`	列数（默认 2）
`items`	`{ label, value }[]`	—
`bordered`	`boolean`	边框样式

UiTimeline

时间线（从 evolution/ExperienceTimeline 提炼）。

Prop	类型	说明
`items`	`TimelineItem[]`	—

interface TimelineItem {
  color?: 'success' | 'error' | 'warning' | 'default'
  title: string
  description?: string
  timestamp?: string
}

UiStat

统计数值（比 MetricCard 轻，无卡片容器）。

Prop	类型	说明
`label`	`string`	—
`value`	`string \| number`	—
`prefix` / `suffix`	`string`	—

UiCodeBlock

代码块（带复制按钮、语言标签）。

Prop	类型	说明
`code`	`string`	—
`language`	`string`	—
`showCopy`	`boolean`	—

UiTabs

封装 a-tabs，统一下划线样式与间距。

Prop	类型	说明
`items`	`{ key, label, icon? }[]`	—
`v-model`	`string`	当前 key
`position`	`'top' \| 'left'`	—

UiBreadcrumb

面包屑。

Prop	类型	说明
`items`	`{ title, to? }[]`	—

UiPagination

分页（封装 a-pagination）。

1.7 浮层（overlay）

UiDrawer

封装 a-drawer，统一宽度（480/720）、圆角、header 样式。

Prop	类型	说明
`open`	`boolean`	—
`title`	`string`	—
`width`	`number`	默认 480
`placement`	`'right' \| 'left'`	—
事件 `close`	—	—

UiModal

封装 a-modal，统一样式。

Prop	类型	说明
`open`	`boolean`	—
`title`	`string`	—
`width`	`number`	默认 520
`loading`	`boolean`	确认按钮加载
事件 `ok` / `cancel`	—	—

2. 业务复合组件

2.1 UiToolbar

列表/表格顶部工具栏：搜索 + 筛选 + 操作按钮。

Prop/插槽	说明
插槽 `search`	搜索框位
插槽 `filters`	筛选器位
插槽 `actions`	右侧操作按钮

2.2 UiFilterBar

水平筛选条（多个 UiSelect 组合）。

2.3 UiDetailDrawer

详情侧抽屉模板：title + description + tabs/content。

2.4 UiCrudPage

CRUD 页面骨架：Toolbar + DataTable + CreateModal + EditDrawer。

ponytail: 这个组件较重，仅当 3+ 页面模式一致时才抽取，避免过度封装。

3. 业务域组件（已有，需对齐规范）

3.1 多维表格（bitable/）

已有：BitableGrid、各 Cell Editor/Display、LoadingState、ErrorState、RecordDetailDrawer、FieldManagePanel 等。

对齐动作：

LoadingState → 提升为 UiLoading（bitable 内部改用 UiLoading）
ErrorState → 提升为 UiError
其余保留在 bitable/ 目录（业务专用）

3.2 日历（calendar/）

已有：CalendarGrid、ListView、CardView、EventEditor、CalendarDrawer。

对齐动作：

ListView 中的 list-view__toolbar / __empty 改用 UiToolbar / UiEmpty
EventEditor 中的表单项改用 UiFormField

3.3 聊天（chat/）

已有：ChatInput、ChatMessage、各 Message 子组件。

对齐动作：

ChatInput 内部样式对齐 token
MessageShell 边距对齐 --space-3

3.4 自进化（evolution/）

已有：DashboardOverview、MetricsChart、各 Panel。

对齐动作：

DashboardOverview 的 overview-card 改用 UiMetricCard
各 Panel 的 __header / __empty 对齐 UiCard / UiEmpty

3.5 知识库（kb/）

已有：SearchTest、KBSettings、DocumentUpload。

对齐动作：表单改用 UiFormField，列表改用 UiList。

3.6 技能（skills/）

已有：SkillCard、SkillDetail。

对齐动作：SkillCard 内部颜色硬编码改 token。

3.7 终端（terminal/）

已有：TerminalEmulator、TerminalPanel、WhitelistManager。

对齐动作：WhitelistManager 的表格改用 UiDataTable。

4. 实施路线

第一批（通用高频，立即实现）

UiEmpty / UiLoading / UiError / UiSpin
UiButton / UiTag / UiBadge
UiFormField / UiInput / UiTextArea / UiSelect / UiSearchInput
UiDrawer / UiModal

第二批（数据展示）

UiDataTable / UiList / UiListItem / UiDescription
UiTimeline / UiStat / UiCodeBlock
UiTabs / UiBreadcrumb / UiPagination

第三批（原子补充）

UiIcon / UiAvatar / UiTooltip
UiDatePicker / UiSwitch / UiCheckbox / UiRadio
UiFormSection

第四批（业务复合）

UiToolbar / UiFilterBar
UiDetailDrawer
UiCrudPage（视实际复用度决定是否抽取）

第五批（域对齐）

bitable LoadingState/ErrorState → UiLoading/UiError
evolution DashboardOverview → UiMetricCard
calendar ListView 工具栏 → UiToolbar
skills SkillCard → token 化
terminal WhitelistManager → UiDataTable

5. 使用约定

新页面必须用组件库：Code Review 检查清单第 2 条。
旧页面渐进迁移：修改时顺手替换，不专门重构。
组件不满足需求时：先在组件库扩展 prop/插槽，不要在页面内另写。
业务专用组件留在业务目录：只有跨 2+ 域复用的才提升到 components/ui/。

13 KiB Raw Blame History Unescape Escape

AgentKit 组件库完整设计

设计原则

组件分层

1. 通用基础（components/ui）

1.1 已实现

1.2 原子组件（primitives）

UiButton

UiTag

UiBadge

UiAvatar

UiIcon

UiTooltip

1.3 状态反馈（feedback）

UiEmpty

UiLoading

UiError

UiSpin

1.4 表单（form）

UiFormField

UiInput

UiTextArea

UiSelect

UiDatePicker / UiDateRangePicker

UiSwitch

UiCheckbox / UiCheckboxGroup

UiRadio / UiRadioGroup

UiSearchInput

UiFormSection

1.5 数据展示（data）

UiDataTable

UiList / UiListItem

UiDescription

UiTimeline

UiStat

UiCodeBlock

1.6 导航（navigation）

UiTabs

UiBreadcrumb

UiPagination

1.7 浮层（overlay）

UiDrawer

UiModal

2. 业务复合组件

2.1 UiToolbar

2.2 UiFilterBar

2.3 UiDetailDrawer

2.4 UiCrudPage

3. 业务域组件（已有，需对齐规范）

3.1 多维表格（bitable/）

3.2 日历（calendar/）

3.3 聊天（chat/）

3.4 自进化（evolution/）

3.5 知识库（kb/）

3.6 技能（skills/）

3.7 终端（terminal/）

4. 实施路线

第一批（通用高频，立即实现）

第二批（数据展示）

第三批（原子补充）

第四批（业务复合）

第五批（域对齐）

5. 使用约定

13 KiB

Raw Blame History