@teamix-evo/skills 0.11.0 → 0.12.0

package/src/teamix-evo-design-opentrek/pages/list-page/patterns/card-list-opentrek.md

@@ -0,0 +1,739 @@
+# OpenTrek 卡片列表页业务规则
+
+> 路由自 [card-list.md](./card-list.md)
+> 本文件基于 OpenTrek DEV 平台实际页面截图沉淀，定义页面级组合规则。
+> 所有 UI 组件引用均指向 `packages/ui/src/components/`，开发时必须从该路径导入。
+> 卡片三件套规格详见 [_shared/item-card-spec.md](../_shared/item-card-spec.md)
+
+---
+
+## 1. 页面模式速查表
+
+| 模式 ID | 名称 | 典型页面 | 核心结构 |
+|---------|------|----------|----------|
+| **OT-CL-1** | Tab 导航卡片列表 | 评估器 / 知识库 / Skills Hub / 智能体 | Tabs + ActionToolbar + CardGrid + Pagination |
+| **OT-CL-2** | 复合卡片页面 | 记忆体 > 空间共用 | Breadcrumb + Tabs + FeatureCards + Alert + Table |
+| **OT-CL-3** | 简单卡片列表 | 记忆体（列表入口） | ActionToolbar + CardGrid（无 Pagination） |
+
+---
+
+## 2. OT-CL-1：Tab 导航卡片列表
+
+> 典型页面：评估器（空间评估器/内置评估器）、知识库（空间知识库/共享知识库）、Skills Hub（空间/共享/内置 Skills）、智能体（智能体开发/智能体模板）
+
+### 布局骨架
+
+```
+┌─ PageShell (components/page-shell) ──────────────────────────────────────┐
+│ sidebar: Sidebar (components/sidebar)                                     │
+│ children:                                                                 │
+│ ┌─ ContentCard (components/card → Card + CardContent) ──────────────┐   │
+│ │ PageHeader (components/page-header → PageHeader + PageHeaderHeading)│   │
+│ │   标题: "评估器" / "知识库" / "Skills Hub" / "智能体"                    │   │
+│ │                                                                    │   │
+│ │ Tabs (components/tabs → Tabs + TabsList[variant='line'] + TabsTrigger)│ │
+│ │   [空间评估器 | 内置评估器]                                            │   │
+│ │   [空间知识库 | 共享知识库]                                            │   │
+│ │   [空间Skills | 共享Skills | 内置Skills]                              │   │
+│ │   [智能体开发 | 智能体模板]                                            │   │
+│ │                                                                    │   │
+│ │ ActionToolbar (flex, nowrap):                                      │   │
+│ │   .left-actions:                                                   │   │
+│ │     Button (components/button, variant='default', color='primary')  │   │
+│ │       "+ 新建评估器" / "+ 创建知识库" / "安装Skill" / "+ 新建智能体"      │   │
+│ │     [Button (variant='outline')] "导入智能体" *可选                    │   │
+│ │     [Button (variant='outline')] "获取导入秘钥凭证" *可选               │   │
+│ │   .search-combo (SearchCombo, margin-left: 20px):                  │   │
+│ │     Input (components/input) placeholder="搜索评估器名称…"             │   │
+│ │   .right-tools:                                                    │   │
+│ │     [Select (components/select)] "全部 ▼" *可选                      │   │
+│ │                                                                    │   │
+│ │ FilterRow (*可选, 位于 ActionToolbar 下方):                          │   │
+│ │   方案A — ToggleGroup (components/toggle-group):                    │   │
+│ │     [全部] [大模型] [代码]                                             │   │
+│ │   方案B — Tag (components/tag → CheckableTag + CheckableTagGroup):  │   │
+│ │     [全部] [TrekAgent] [知识问答] [工作流] [角色对话] [高代码]            │   │
+│ │   方案C — 无独立筛选行，使用 Tabs 切换                                  │   │
+│ │                                                                    │   │
+│ │ CardGrid (CSS Grid, item-card-spec §2):                            │   │
+│ │   ┌─ItemCard─┐ ┌─ItemCard─┐ ┌─ItemCard─┐                          │   │
+│ │   │ Avatar   │ │ Avatar   │ │ Avatar   │  × N (3-4列)              │   │
+│ │   │ Title    │ │ Title    │ │ Title    │                          │   │
+│ │   │ Desc     │ │ Desc     │ │ Desc     │                          │   │
+│ │   │ Meta     │ │ Meta     │ │ Meta     │                          │   │
+│ │   └──────────┘ └──────────┘ └──────────┘                          │   │
+│ │                                                                    │   │
+│ │ Pagination (components/pagination):                                │   │
+│ │   共 4 条  每页显示: [12 ▼]  [‹] [1] [›]                            │   │
+│ └────────────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 页面级组件清单
+
+| 区域 | UI 组件库引用 | 用途 | 必需 |
+|------|--------------|------|------|
+| 页面框架 | `components/page-shell` → `PageShell` | L1 级页面壳，sidebar + children | ✅ |
+| 侧边导航 | `components/sidebar` → `Sidebar` + `SidebarContent` + `SidebarMenu` + `SidebarMenuItem` + `SidebarMenuButton` | 左侧导航菜单 | ✅ (TWO_COL) |
+| 白卡容器 | `components/card` → `Card` + `CardContent` | 内容区白色容器 | ✅ |
+| 页面标题 | `components/page-header` → `PageHeader` + `PageHeaderHeading` | 标题 18px/500 | ✅ |
+| Tab 切换 | `components/tabs` → `Tabs` + `TabsList`(variant='line') + `TabsTrigger` + `TabsContent` | 子视图切换 | ✅ |
+| 主操作按钮 | `components/button` → `Button`(variant='default', color='primary') | "+ 新建XXX" | ✅ |
+| 辅助按钮 | `components/button` → `Button`(variant='outline') | "导入"等 | 可选 |
+| 搜索输入 | `components/input` → `Input` | 搜索框 | ✅ |
+| 筛选标签 | `components/toggle-group` → `ToggleGroup` + `ToggleGroupItem` | 分类筛选 | 可选 |
+| 筛选标签 | `components/tag` → `CheckableTag` + `CheckableTagGroup` | 多分类筛选 | 可选 |
+| 下拉筛选 | `components/select` → `Select` + `SelectTrigger` + `SelectContent` + `SelectItem` | 下拉选择 "全部 ▼" | 可选 |
+| 卡片网格 | CSS Grid (item-card-spec §2) | 承载 ItemCard | ✅ |
+| 业务卡片 | `components/card` → `Card` + `CardHeader` + `CardTitle` + `CardDescription` + `CardContent` + `CardFooter` | 单个数据项 | ✅ |
+| 卡片头像 | `components/avatar` → `Avatar` + `AvatarFallback` | 首字母色块 / 图标 | ✅ |
+| 状态标签 | `components/tag` → `Tag`(variant='status') | 启用/禁用/正常/有风险 | 按业务 |
+| 版本标签 | `components/badge` → `Badge`(variant='secondary') | v1.0.0 等版本信息 | 按业务 |
+| 分类标签 | `components/tag` → `Tag`(palette='blue'/'green'/...) | 大模型/代码/文档/问答 等 | 按业务 |
+| 安全扫描 | `components/badge` → `Badge`(variant='outline') + icon | 安全 ✅ / 有风险 ⚠️ | 按业务 |
+| 安装状态 | `components/tag` → `Tag`(variant='status', status='success'/'default') | 已安装 / 未安装 / 有更新 | 按业务 |
+| 分页 | `components/pagination` → `Pagination` + `PaginationContent` + `PaginationItem` + `PaginationLink` + `PaginationPrevious` + `PaginationNext` | 底部分页控件 | ✅ |
+| 每页条数 | `components/select` → `Select` + `SelectTrigger` + `SelectItem` | "每页显示: 12 ▼" | ✅ |
+| 提示 | `components/tooltip` → `Tooltip` + `TooltipTrigger` + `TooltipContent` | 悬停说明 | 可选 |
+
+### ItemCard Slot 变体（按业务场景）
+
+**变体 A：简单信息卡片**（评估器）
+
+```
+┌─ ItemCard ──────────────────────────────┐
+│ [Avatar 32×32]  标题 (14px/500)          │  ← CardTitleRow
+│              描述文字 (12px, 1行截断)      │  ← CardDescriptionRow
+│ ──────────────────────────────────────── │
+│ [TypeTag]    🕐 2024-04-15 14:30        │  ← CardSupplementaryRow
+│                                          │
+│ [CardActionBar — hover-slidebar]         │  ← hover 时上滑显示
+└──────────────────────────────────────────┘
+```
+
+| Slot | 内容 | UI 组件库引用 |
+|------|------|--------------|
+| CardTitleRow | `Avatar`(colorHash) + `CardTitle`(14px) | `components/avatar` + `components/card` |
+| CardDescriptionRow | 描述 1 行 | `components/card` → `CardDescription` |
+| CardFieldRow | 无 | — |
+| CardSupplementaryRow | 类型 `Tag`(palette) + 更新时间 | `components/tag` |
+
+**变体 B：状态卡片**（知识库）
+
+```
+┌─ ItemCard ──────────────────────────────┐
+│ [Avatar 32×32]  标题 (14px/500)  [启用]  │  ← CardTitleRow + statusBadge
+│              描述文字 (12px, 1行截断)      │  ← CardDescriptionRow
+│ ──────────────────────────────────────── │
+│ 👤 shaoshi  📂 文档    🕐 2024-03-20    │  ← CardSupplementaryRow (3字段)
+│                                          │
+│ [CardActionBar — hover-slidebar]         │
+└──────────────────────────────────────────┘
+```
+
+| Slot | 内容 | UI 组件库引用 |
+|------|------|--------------|
+| CardTitleRow | `Avatar`(colorHash/icon) + `CardTitle` + `Tag`(variant='status') | `components/avatar` + `components/card` + `components/tag` |
+| CardDescriptionRow | 描述 1 行 | `components/card` → `CardDescription` |
+| CardSupplementaryRow | 创建人 + 类型 + 更新时间（3 字段） | 内联 span |
+
+**状态 Badge 映射**：
+
+| 业务状态 | `Tag` 属性 |
+|----------|-----------|
+| 启用 / 正常 / 已安装 | `variant='status'`, `status='success'` |
+| 禁用 | `variant='status'`, `status='default'` |
+| 有风险 | `variant='status'`, `status='warning'` |
+| 有更新 | `variant='status'`, `status='warning'`（橙色） |
+| 安全 | `Badge`(variant='outline') + ✅ 图标 |
+
+**变体 C：技能卡片**（Skills Hub — 空间Skills）
+
+```
+┌─ ItemCard ──────────────────────────────┐
+│ [Avatar 32×32]  标题 (14px/500)  v3.0.1  │  ← CardTitleRow + Badge(version)
+│              描述文字 (12px, 1行截断)      │  ← CardDescriptionRow
+│ 安装方式: 文件                             │  ← CardFieldRow (label:value)
+│ 安全扫描: ✅ 安全                          │  ← CardFieldRow (icon+label)
+│ ──────────────────────────────────────── │
+│ 📅 2026-04-21                            │  ← CardSupplementaryRow
+│                                          │
+│ [CardActionBar — hover-slidebar]         │
+└──────────────────────────────────────────┘
+```
+
+| Slot | 内容 | UI 组件库引用 |
+|------|------|--------------|
+| CardTitleRow | `Avatar`(colorHash) + `CardTitle` + `Badge`(variant='secondary', version) | `components/avatar` + `components/card` + `components/badge` |
+| CardDescriptionRow | 描述 1 行 | `components/card` → `CardDescription` |
+| CardFieldRow ×2 | 安装方式 + 安全扫描 | 内联 span |
+| CardSupplementaryRow | 创建时间 | 内联 span |
+
+**变体 D：技能卡片（多标签）**（Skills Hub — 共享/内置 Skills）
+
+```
+┌─ ItemCard ──────────────────────────────┐
+│ [Avatar 32×32]  标题 (14px/500)  v1.5.0  │  ← CardTitleRow + Badge(version)
+│              描述文字 (12px, 1行截断)      │  ← CardDescriptionRow
+│ [✅安全] [未安装]  [AI能力]                │  ← CardFieldRow (Badge+Tag row)
+│ ──────────────────────────────────────── │
+│ 📅 2026-04-18                            │  ← CardSupplementaryRow
+│                                          │
+│ [CardActionBar — hover-slidebar]         │
+└──────────────────────────────────────────┘
+```
+
+| Slot | 内容 | UI 组件库引用 |
+|------|------|--------------|
+| CardTitleRow | `Avatar` + `CardTitle` + `Badge`(variant='secondary', version) | `components/avatar` + `components/card` + `components/badge` |
+| CardDescriptionRow | 描述 1 行 | `components/card` → `CardDescription` |
+| CardFieldRow | Badge 行：安全扫描 + 安装状态 + 分类标签 | `components/badge` + `components/tag` |
+| CardSupplementaryRow | 创建时间 | 内联 span |
+
+**多标签行 Badge/Tag 映射**：
+
+| 信息 | 组件 | 属性 |
+|------|------|------|
+| 安全扫描 "安全" | `Badge` | `variant='outline'`, 绿色 ✅ 图标 + 文字 |
+| 安全扫描 "有风险" | `Badge` | `variant='outline'`, 橙色 ⚠️ 图标 + 文字 |
+| 安装状态 "已安装" | `Tag` | `variant='status'`, `status='success'` |
+| 安装状态 "未安装" | `Tag` | `variant='status'`, `status='default'` |
+| 安装状态 "有更新" | `Tag` | `variant='status'`, `status='warning'` |
+| 分类 "AI能力" / "数据处理" / "自动化" | `Tag` | `palette='blue'` / `'green'` / `'orange'` |
+
+**变体 E：智能体卡片**（智能体）
+
+```
+┌─ ItemCard ──────────────────────────────┐
+│ [Avatar 32×32]  标题 (14px/500)          │  ← CardTitleRow
+│              描述文字 (12px, 1行截断)      │  ← CardDescriptionRow
+│ ──────────────────────────────────────── │
+│ 👤 创建人: chengmu                       │  ← CardSupplementaryRow
+│ ✅ 创建类型: TrekAgent                   │  ← CardFieldRow
+│                                          │
+│ [CardActionBar — hover-slidebar]         │
+└──────────────────────────────────────────┘
+```
+
+| Slot | 内容 | UI 组件库引用 |
+|------|------|--------------|
+| CardTitleRow | `Avatar`(colorHash) + `CardTitle` | `components/avatar` + `components/card` |
+| CardDescriptionRow | 描述 1 行 | `components/card` → `CardDescription` |
+| CardFieldRow | 创建类型 | 内联 span |
+| CardSupplementaryRow | 创建人 | 内联 span |
+
+**变体 F：记忆体卡片**（记忆体列表入口）
+
+```
+┌─ ItemCard ──────────────────────────────┐
+│ [Icon 32×32]  标题 (14px/500)            │  ← CardTitleRow (统一脑形图标)
+│              描述文字 (12px, 1行截断)      │  ← CardDescriptionRow
+│ Code: m7R2kP9nQ1                        │  ← CardFieldRow (等宽字体)
+│ ──────────────────────────────────────── │
+│ 👤 shaoshi    📅 2026-04-21             │  ← CardSupplementaryRow
+│                                          │
+│ [CardActionBar — hover-slidebar]         │
+└──────────────────────────────────────────┘
+```
+
+| Slot | 内容 | UI 组件库引用 |
+|------|------|--------------|
+| CardTitleRow | 图标 + `CardTitle` | `components/avatar` → `Avatar` + `AvatarFallback` |
+| CardDescriptionRow | 描述 1 行 | `components/card` → `CardDescription` |
+| CardFieldRow | Code（等宽字体 `font-mono`） | 内联 span |
+| CardSupplementaryRow | 创建人 + 创建时间 | 内联 span |
+
+### Pagination 规格（OpenTrek 定制）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  共 4 条  每页显示: [12 ▼]     [‹] [1] [›]                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+| 区域 | UI 组件库引用 | 说明 |
+|------|--------------|------|
+| 总数文字 "共 4 条" | 内联 `span` | 左对齐 |
+| 每页条数选择器 | `components/select` → `Select` + `SelectTrigger`(size='sm') + `SelectContent` + `SelectItem` | 默认 12，可选 12/24/48 |
+| 翻页按钮 | `components/pagination` → `Pagination` + `PaginationContent` + `PaginationItem` + `PaginationPrevious` + `PaginationLink`(isActive) + `PaginationNext` | 右对齐 |
+
+---
+
+## 3. OT-CL-2：复合卡片页面（FeatureCard + Table）
+
+> 典型页面：记忆体 > 空间共用（记忆总览 Tab）
+
+### 布局骨架
+
+```
+┌─ PageShell (components/page-shell) ──────────────────────────────────────┐
+│ sidebar: Sidebar (components/sidebar)                                     │
+│ children:                                                                 │
+│ ┌─ ContentCard (components/card → Card + CardContent) ──────────────┐   │
+│ │ Breadcrumb (components/breadcrumb → Breadcrumb + BreadcrumbItem):  │   │
+│ │   记忆体 > 空间共用                                                  │   │
+│ │                                                                    │   │
+│ │ Tabs (components/tabs → Tabs + TabsList[variant='line'] + TabsTrigger):│
+│ │   [记忆总览*] [生成策略] [整理策略] [记忆动态]                           │   │
+│ │                                                                    │   │
+│ │ ┌── FeatureCardRow (4 张功能选择卡片) ────────────────────────────┐  │   │
+│ │ │ ┌─FeatureCard─┐ ┌─FeatureCard─┐ ┌─FeatureCard─┐ ┌─FeatureCard─┐ │  │   │
+│ │ │ │ [Icon] 常驻  │ │ [Icon] 检索  │ │ [Icon] 用户  │ │ [Icon] Skills│ │  │   │
+│ │ │ │ 记忆* ✓     │ │ 记忆        │ │ 记忆        │ │ 记忆         │ │  │   │
+│ │ │ │ 描述文字     │ │ 描述文字     │ │ 描述文字     │ │ 描述文字      │ │  │   │
+│ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │  │   │
+│ │ │  * selected = border: 2px solid var(--primary)               │  │   │
+│ │ └────────────────────────────────────────────────────────────────┘  │   │
+│ │                                                                    │   │
+│ │ Alert (components/alert → Alert, variant='info'):                  │   │
+│ │   ℹ️ 锁定的记忆不清理、不合井、不冻结。                                │   │
+│ │                                                                    │   │
+│ │ ActionToolbar:                                                     │   │
+│ │   .left-actions:                                                   │   │
+│ │     Button (variant='default', color='primary') "+ 添加记忆"        │   │
+│ │     Span "已配置 2 条"                                              │   │
+│ │   .right-tools:                                                    │   │
+│ │     Button (variant='outline') "转化为skill"                       │   │
+│ │                                                                    │   │
+│ │ DataTable (components/data-table):                                 │   │
+│ │   ☐ | 记忆code | 记忆内容 | 记忆状态 | 内容更新时间 | 操作             │   │
+│ │   ☐ | w1R4jK6m | 技术栈偏好… | ●正常  | 2026-03-28 | 编辑|冻结|锁定|删除│
+│ │   ☐ | y9P3xM7b | 沟通风格…  | ●正常  | 2026-04-01 | 编辑|冻结|锁定|删除│
+│ └────────────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### FeatureCard 规格
+
+> FeatureCard 是 ItemCard 的特殊变体，用于功能入口选择（如记忆类型分类）。与标准 ItemCard 不同，FeatureCard 横向排列 4 张，可点击选中，不含 CardActionBar。
+
+| 属性 | 值 | UI 组件库引用 |
+|------|-----|--------------|
+| layout | 4 列横向 Grid | CSS Grid: `grid-template-columns: repeat(4, 1fr)` |
+| gap | 16px | `gap: var(--card-gap, 16px)` |
+| padding | 16px 20px | `padding: 16px 20px` |
+| border (default) | `1px solid var(--gray-border)` | — |
+| border (selected) | `2px solid var(--primary)` | — |
+| borderRadius | `var(--radius-lg)` (12px) | — |
+| background | `var(--card)` | — |
+| cursor | pointer | — |
+| icon | 32×32 线框图标（非 Avatar 色块） | `components/avatar` → `Avatar` + `AvatarFallback` |
+| title | 14px / 500 / `var(--gray-primary)` | `components/typography` |
+| description | 12px / 400 / `var(--gray-tertiary)` / 1 行 | `components/typography` |
+| height | 自适应，约 80-100px | — |
+| hover | `border-color: var(--primary)` + `box-shadow: var(--shadow-sm)` | — |
+
+### Alert Info Banner 规格
+
+| 属性 | 值 | UI 组件库引用 |
+|------|-----|--------------|
+| variant | info（蓝色） | `components/alert` → `Alert` |
+| icon | ℹ️ info circle | — |
+| text | 12px / `var(--gray-secondary)` | — |
+| background | `hsl(var(--primary) / 0.05)` | — |
+| border | `1px solid hsl(var(--primary) / 0.2)` | — |
+| borderRadius | `var(--radius-md)` (8px) | — |
+| padding | 12px 16px | — |
+
+---
+
+## 4. OT-CL-3：简单卡片列表（无 Pagination）
+
+> 典型页面：记忆体（列表入口页，4 张卡片无分页）
+
+### 布局骨架
+
+```
+┌─ PageShell (components/page-shell) ──────────────────────────────────────┐
+│ sidebar: Sidebar (components/sidebar)                                     │
+│ children:                                                                 │
+│ ┌─ ContentCard (components/card → Card + CardContent) ──────────────┐   │
+│ │ PageHeader (components/page-header):                               │   │
+│ │   标题: "记忆体"                                                     │   │
+│ │                                                                    │   │
+│ │ ActionToolbar:                                                     │   │
+│ │   .left-actions:                                                   │   │
+│ │     Button (variant='default', color='primary') "+ 新建记忆体"      │   │
+│ │   .search-combo:                                                   │   │
+│ │     Input (components/input) placeholder="搜索记忆体名称"            │   │
+│ │   .right-tools:                                                    │   │
+│ │     Button (variant='outline') "对接三方Agent"                     │   │
+│ │                                                                    │   │
+│ │ CardGrid (CSS Grid, preset=standard, item-card-spec §2):          │   │
+│ │   ┌─ItemCard(F)─┐ ┌─ItemCard(F)─┐ ┌─ItemCard(F)─┐                │   │
+│ │   │ 版本备忘     │ │ 空间共用     │ │ 数据分析经验  │  × 4          │   │
+│ │   └────────────┘ └────────────┘ └────────────┘                   │   │
+│ │                                                                    │   │
+│ │ (* 无 Pagination — 数据量 ≤ 一页)                                  │   │
+│ └────────────────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Pagination 显隐规则
+
+| 条件 | Pagination | 说明 |
+|------|------------|------|
+| 数据量 ≤ 每页条数 | **隐藏** | 简单卡片列表（OT-CL-3）通常无分页 |
+| 数据量 > 每页条数 | **显示** | Tab 导航卡片列表（OT-CL-1）始终显示 |
+| 空数据 | **隐藏** | 使用 `components/empty` → `Empty` 替代 |
+
+---
+
+## 5. ActionToolbar 组合规则
+
+> 基于 `../_shared/search-combo-spec.md` 通用规则，本节补充 OpenTrek 页面中 ActionToolbar 的实际组合方式。
+
+### 5.1 DOM 结构
+
+```html
+<div class="action-toolbar" style="display:flex; flex-wrap:nowrap; gap:8px; align-items:center;">
+  <!-- 左侧主操作 -->
+  <div class="left-actions" style="display:flex; gap:8px;">
+    <Button variant="default" color="primary">+ 新建评估器</Button>
+    <!-- 可选辅助按钮 -->
+    <Button variant="outline">导入智能体</Button>
+  </div>
+
+  <!-- 搜索组合（与 left-actions 间距 20px） -->
+  <div class="search-combo" style="margin-left:12px;"> <!-- calc(20px - 8px) = 12px -->
+    <Input placeholder="搜索评估器名称…" />
+  </div>
+
+  <!-- 右侧工具 -->
+  <div class="right-tools" style="margin-left:auto; display:flex; gap:8px;">
+    <Select><SelectTrigger>全部 ▼</SelectTrigger></Select>
+    <!-- 或 Button -->
+    <Button variant="outline">对接三方Agent</Button>
+  </div>
+</div>
+```
+
+### 5.2 组件引用清单
+
+| 子组件 | UI 组件库引用 | 常见属性 |
+|--------|--------------|----------|
+| 主操作按钮 | `components/button` → `Button` | `variant='default'`, `color='primary'`, `shape='round'` |
+| 辅助操作按钮 | `components/button` → `Button` | `variant='outline'`, `shape='round'` |
+| 搜索输入框 | `components/input` → `Input` | `size='default'`, placeholder 动态 |
+| 下拉筛选 | `components/select` → `Select` + `SelectTrigger`(size='sm') + `SelectContent` + `SelectItem` | 用于 "全部 ▼" 下拉 |
+| 筛选标签组 | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 互斥分类筛选 |
+| 多选标签组 | `components/tag` → `CheckableTagGroup` + `CheckableTag` | 多选分类筛选 |
+| 溢出菜单 | `components/dropdown-menu` → `DropdownMenu` + `DropdownMenuTrigger` + `DropdownMenuContent` + `DropdownMenuItem` | 操作 >3 个时 |
+
+### 5.3 各页面 ActionToolbar 实例
+
+| 页面 | left-actions | search-combo | right-tools |
+|------|-------------|-------------|-------------|
+| 评估器 | `Button`("+ 新建评估器") | `Input`("搜索评估器名称…") | — |
+| 知识库 | `Button`("+ 创建知识库") | `Input`("搜索知识库名称…") | — |
+| Skills Hub (空间) | `Button`("安装Skill") | `Input`("搜索Skills名称…") | `Select`("全部 ▼") |
+| Skills Hub (共享) | — | `Input`("搜索Skills名称…") | — |
+| Skills Hub (内置) | — | `Input`("搜索Skills名称…") | `Select`("全部 ▼") |
+| 智能体 | `Button`("+ 新建智能体") + `Button`("导入智能体") + `Button`("获取导入秘钥凭证") | `Input`("按智能体名称筛选…") | — |
+| 记忆体 (列表) | `Button`("+ 新建记忆体") | `Input`("搜索记忆体名称") | `Button`("对接三方Agent") |
+| 记忆体 (总览) | `Button`("+ 添加记忆") + `Span`("已配置 2 条") | — | `Button`("转化为skill") |
+
+---
+
+## 6. FilterRow 筛选行规则
+
+> OpenTrek 中 FilterRow 有两种 UI 实现方案，按分类数量选择。
+
+### 6.1 方案选择矩阵
+
+| 分类数量 | 推荐方案 | UI 组件库引用 | 典型页面 |
+|----------|----------|--------------|----------|
+| 2-4 项 | **ToggleGroup** | `components/toggle-group` → `ToggleGroup`(type='single') + `ToggleGroupItem` | 评估器 |
+| 5-8 项 | **CheckableTagGroup** | `components/tag` → `CheckableTagGroup` + `CheckableTag` | 智能体 |
+| > 8 项 | **Select 下拉** | `components/select` → `Select` + `SelectTrigger` + `SelectContent` + `SelectItem` | — |
+
+### 6.2 ToggleGroup 方案（评估器示例）
+
+```html
+<ToggleGroup type="single" defaultValue="all" spacing={2}>
+  <ToggleGroupItem value="all">全部</ToggleGroupItem>
+  <ToggleGroupItem value="llm">大模型</ToggleGroupItem>
+  <ToggleGroupItem value="code">代码</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**样式**：
+- 选中项：`background: var(--primary); color: white`
+- 未选中项：`background: transparent; color: var(--gray-secondary); border: 1px solid var(--gray-border)`
+- 高度：28px
+- borderRadius：`var(--radius-md)` (6px)
+- padding：0 12px
+
+### 6.3 CheckableTagGroup 方案（智能体示例）
+
+```html
+<CheckableTagGroup
+  value={selectedFilters}
+  onChange={setSelectedFilters}
+  options={[
+    { label: '全部', value: 'all' },
+    { label: 'TrekAgent', value: 'trek' },
+    { label: '知识问答', value: 'qa' },
+    { label: '工作流', value: 'workflow' },
+    { label: '角色对话', value: 'role' },
+    { label: '高代码', value: 'code' }
+  ]}
+/>
+```
+
+**样式**：
+- 选中项：`background: hsl(var(--primary) / 0.1); color: var(--primary); border-color: var(--primary)`
+- 未选中项：`background: transparent; color: var(--gray-secondary); border: 1px solid var(--gray-border)`
+- 高度：28px
+- gap：8px
+
+### 6.4 FilterRow 位置规则
+
+| 位置 | 条件 | 说明 |
+|------|------|------|
+| ActionToolbar 下方独立行 | 筛选项 ≥ 3 且与 SearchCombo 独立 | 评估器、知识库、智能体 |
+| ActionToolbar 右侧内嵌 | 筛选项 ≤ 2 或作为 Select 下拉 | Skills Hub (内置) |
+
+---
+
+## 7. ItemCard 图标系统（Avatar 色块映射）
+
+> 基于截图沉淀的 Avatar 色块使用规则。所有图标均使用 `components/avatar` → `Avatar` + `AvatarFallback`。
+
+### 7.1 色块分配规则
+
+| 业务场景 | 颜色 | 内容 | UI 组件库引用 |
+|----------|------|------|--------------|
+| 评估器 — 大模型类 | 绿色 | 首字 "客"/"多" | `Avatar` + `AvatarFallback`(className='bg-success') |
+| 评估器 — 代码类 | 蓝色 | 首字 "代"/"知" | `Avatar` + `AvatarFallback`(className='bg-primary') |
+| 知识库 — 文档类 | 紫色 | 文件夹图标 | `Avatar` + `AvatarFallback`(className='bg-data-4') |
+| 知识库 — 数据类 | 蓝色 | 数据库图标 | `Avatar` + `AvatarFallback`(className='bg-primary') |
+| 知识库 — 图文类 | 蓝色 | 图片图标 | `Avatar` + `AvatarFallback`(className='bg-primary') |
+| 知识库 — 自定义 | 紫色 | 齿轮图标 | `Avatar` + `AvatarFallback`(className='bg-data-4') |
+| 知识库 — 问答类 | 绿色 | 文件夹图标 | `Avatar` + `AvatarFallback`(className='bg-success') |
+| 知识库 — 术语类 | 橙色 | 文档图标 | `Avatar` + `AvatarFallback`(className='bg-warning') |
+| Skills — 各类 | 紫/黄/橙/蓝/绿 | 首字 | `Avatar` + `AvatarFallback`(hash 到预设色) |
+| 智能体 — 各类 | 绿/橙/紫/黄/蓝 | 首字 | `Avatar` + `AvatarFallback`(hash 到预设色) |
+| 记忆体 — 统一 | 浅蓝底 + 蓝色线框 | 脑形图标 | `Avatar` + `AvatarFallback`(统一图标) |
+
+### 7.2 9 种预设色对照表
+
+| 序号 | className | 用途示例 |
+|------|-----------|----------|
+| 1 | `bg-primary` | 蓝色主色 — 代码/数据类 |
+| 2 | `bg-success` | 绿色 — 大模型/问答类 |
+| 3 | `bg-type-mcp` | 靛蓝色 |
+| 4 | `bg-warning` | 橙色 — 术语类/工具类 |
+| 5 | `bg-data-8` | 数据色8 |
+| 6 | `bg-data-1` | 数据色1 |
+| 7 | `bg-destructive` | 红色 — 警告/风险 |
+| 8 | `bg-brand-3` | 品牌色3 |
+| 9 | `bg-data-4` | 紫色 — 文档/自定义类 |
+
+> 当 avatar 字段为空时，使用 `name.charAt(0).toUpperCase()` hash 到上述 9 种预设色之一，保证相邻卡片尽量不重复。
+
+---
+
+## 8. 各页面截图 → 模式映射表
+
+> 快速索引：遇到某个 OpenTrek 页面时，直接查表找到对应模式与变体。
+
+| 页面 | Tab 结构 | 页面模式 | ActionToolbar 构成 | FilterRow | CardGrid preset | ItemCard 变体 | Pagination |
+|------|----------|----------|-------------------|-----------|----------------|--------------|------------|
+| 评估器 > 空间评估器 | 空间评估器 \| 内置评估器 | OT-CL-1 | 1 主按钮 + 搜索 | ToggleGroup(全部/大模型/代码) | standard (300px) | 变体 A（简单信息） | ✅ 12条/页 |
+| 知识库 > 空间知识库 | 空间知识库 \| 共享知识库 | OT-CL-1 | 1 主按钮 + 搜索 | CheckableTagGroup(全部/文档/数据表/图文/问答/术语/自定义) | standard (300px) | 变体 B（状态卡片） | ✅ 12条/页 |
+| Skills Hub > 空间Skills | 空间 \| 共享 \| 内置 | OT-CL-1 | 1 主按钮 + 搜索 | CheckableTagGroup(全部/文件/工具转化/工作流转化) | standard (300px) | 变体 C（技能卡片） | ✅ 12条/页 |
+| Skills Hub > 共享Skills | 空间 \| 共享 \| 内置 | OT-CL-1 | 搜索 | — | standard (300px) | 变体 D（多标签技能） | ✅ 12条/页 |
+| Skills Hub > 内置Skills | 空间 \| 共享 \| 内置 | OT-CL-1 | 搜索 | Select("全部 ▼") | standard (300px) | 变体 D（多标签技能） | ✅ 12条/页 |
+| 智能体 > 智能体开发 | 智能体开发 \| 智能体模板 | OT-CL-1 | 3 按钮 + 搜索 | CheckableTagGroup(全部/TrekAgent/知识问答/工作流/角色对话/高代码) | standard (300px) | 变体 E（智能体卡片） | ✅ 12条/页 |
+| 记忆体 (列表入口) | — | OT-CL-3 | 1 主按钮 + 搜索 + 1 右侧按钮 | — | standard (300px) | 变体 F（记忆体卡片） | ❌ |
+| 记忆体 > 空间共用 | 记忆总览 \| 生成策略 \| 整理策略 \| 记忆动态 | OT-CL-2 | 1 主按钮 + 计数 \| 1 右侧按钮 | — | — (FeatureCard + Table) | FeatureCard | ❌ |
+
+---
+
+## 9. 视觉稿标注参考（源自 OpenTrek 真实截图）
+
+> 以下数值从 8 张 OpenTrek 产品截图（智能体/Skills Hub/记忆体/知识库/评估器等页面）中精确提取，作为 AI 生成卡片页面时的像素级参照。
+
+### 9.1 CardGrid 真实间距
+
+| 属性 | 值 | token |
+|------|---|-------|
+| 列数（≥1400px 视窗） | 3 列 | auto-fill 自动计算 |
+| 列数（1080-1400px） | 2-3 列 | — |
+| 卡片水平间距 | 16px | `var(--card-gap)` |
+| 卡片垂直间距 | 16px | `var(--card-gap)` |
+| 容器（ContentCard）左右 padding | 20px | 分层 padding 模型 |
+| 容器（ContentCard）上下 padding | 20px | — |
+
+### 9.2 单张 ItemCard 精确尺寸
+
+| 属性 | 值 | token |
+|------|---|-------|
+| border | 1px solid | `var(--gray-border)` |
+| border-radius | 12px | `var(--radius-lg)` |
+| padding-x (左右) | 20px | — |
+| padding-top | 20px | — |
+| padding-bottom | 16px（预留 ActionBar 绝对定位空间） | — |
+| min-height (standard) | ~160px | 由内容撑开 |
+| background | white | `var(--card)` |
+
+### 9.3 CardTitleRow 标注（截图验证）
+
+```
+┌─ ItemCard ──────────────────────────────────────────────┐
+│  ┌──────┐  Title (14px/500)           [versionBadge]    │
+│  │ Icon │  subName (12px/400 gray)     right-aligned    │
+│  │32×32 │                                               │
+│  └──────┘                                               │
+│  ← 12px →                                               │
+│                                                         │
+```
+
+| 元素 | 规格 | 截图出处 |
+|------|------|----------|
+| icon → title 水平间距 | 12px | 全部 8 张 |
+| icon size (standard) | 32×32 | 智能体/Skills Hub/知识库 |
+| icon border-radius | 8px (`var(--input-radius)`) | 全部 |
+| title font | 14px / font-weight 500 | 全部 |
+| title color | `var(--gray-primary)` | 全部 |
+| **subName**（可选；英文标识如 "code-generator"） | 12px / 400 / `var(--gray-tertiary)` | Skills Hub (空间/共享/内置) |
+| subName margin-top | 2px（紧贴 title 下方） | Skills Hub |
+| **versionBadge**（可选；如 "v3.0.1"） | 12px / 500 / `var(--gray-secondary)` / **右对齐** | Skills Hub 空间Skills |
+| **statusBadge**（可选；如 "启用"/"禁用"） | 12px / borderless Tag / 紧跟 title 后 8px | 知识库 |
+| statusBadge "启用" | color: `var(--success)` / bg: `var(--success-bg)` | 知识库 |
+| statusBadge "禁用" | color: `var(--gray-tertiary)` / bg: `var(--gray-fill)` | 知识库 |
+
+### 9.4 CardDescriptionRow 标注
+
+| 属性 | 值 | 截图出处 |
+|------|---|----------|
+| prefix | "描述：" (inline, 同色) | 全部含描述的卡片 |
+| font-size | 12px | 全部 |
+| color | `var(--gray-tertiary)` | 全部 |
+| line-clamp | 1 (standard) / 2 (complex) | Skills Hub / 智能体 |
+| margin-top (from title area) | 12px | 全部 |
+
+### 9.5 CardFieldRow 标注
+
+| 属性 | 值 | 截图出处 |
+|------|---|----------|
+| format | "labelIcon + label：value" 或 "label：value" | 全部 |
+| label font | 12px / `var(--gray-tertiary)` | 全部 |
+| value font | 12px / `var(--gray-secondary)` | 全部 |
+| labelIcon size | 12-14px inline | Skills Hub (安装方式/安全扫描) |
+| row 间 gap | 4px | 全部多字段卡片 |
+| field 区距 description 区 | 8px | Skills Hub / 知识库 |
+
+#### 行内状态指示器（inline status indicator）
+
+> 出现在 CardFieldRow 的 value 位置，表达实时状态。
+
+| 状态值 | 样式 | icon | 截图出处 |
+|--------|------|------|----------|
+| "安全" | color: `var(--success)` | 🛡 shield-check (12px) | Skills Hub |
+| "有风险" | color: `var(--warning)` 或 `var(--destructive)` | ⚠ alert-triangle (12px) | Skills Hub |
+| "已安装" | color: `var(--success)` | ✓ check (12px) | Skills Hub 共享/内置 |
+| "有更新" | color: `var(--warning)` | ⊙ refresh-cw (12px) | Skills Hub 共享/内置 |
+| "未安装" | color: `var(--gray-tertiary)` | 无 icon | Skills Hub 共享 |
+
+```css
+.field-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  font-weight: 500;
+}
+.field-status--success { color: var(--success); }
+.field-status--warning { color: var(--warning); }
+.field-status--danger  { color: var(--destructive); }
+.field-status--muted   { color: var(--gray-tertiary); }
+```
+
+### 9.6 CardSupplementaryRow 标注
+
+| 属性 | 值 | 截图出处 |
+|------|---|----------|
+| icon (calendar/user) | 12px / `var(--gray-quaternary)` | 全部 |
+| label + value | 12px / `var(--gray-quaternary)` | 全部 |
+| format | "📅 创建时间：YYYY-MM-DD" 或 "👤 创建人：xxx" | 全部 |
+| margin-top (from last field) | 8px | 全部 |
+| 多 supplementary 同行时 | gap 16px (inline-flex) | 未观察到多行 |
+
+### 9.7 ActionToolbar ToggleGroup 筛选定位（截图验证）
+
+> 8 张截图中有 6 张含右侧 ToggleGroup 筛选。
+
+```
+┌─ ActionToolbar ───────────────────────────────────────────────────────────┐
+│ [+ 新建xx]  [导入]     [搜索框 🔍]          [全部|TrekAgent|知识问答|...]  │
+│ ← left-actions →  ← search-combo →         ← right-tools (ml-auto) →    │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+| 属性 | 值 | 截图出处 |
+|------|---|----------|
+| ToggleGroup 位置 | ActionToolbar 右侧 (margin-left: auto) | 智能体/Skills Hub/知识库/评估器 |
+| 选中态 | `color: var(--primary)` + 底部 2px 指示线 | 全部 |
+| 未选中态 | `color: var(--gray-secondary)` | 全部 |
+| 选项间距 | 无 gap（紧密排列，选中项带底部 border 区分） | 全部 |
+| font-size | 13px | 全部 |
+| 高度 | 32px (与搜索框同高) | 全部 |
+| 典型值 | "全部 \| TrekAgent \| 知识问答 \| 工作流 \| 角色对话 \| 高代码" | 智能体 |
+| 典型值 | "全部 \| 文档 \| 数据表 \| 图文 \| 问答 \| 术语 \| 自定义" | 知识库 |
+
+**组件引用**: 使用 `packages/ui/src/components/toggle-group`（ToggleGroup）实现，variant=`outline` 或自定义 tab-style。
+
+### 9.8 Pagination 布局标注（截图验证）
+
+> 仅评估器页面（图8）展示了 Pagination，其余页面数据量较多未显示底部。
+
+```
+┌─ Pagination ──────────────────────────────────────────────────┐
+│ 共 4 条  每页显示: [12 ∨]                       [‹] [1] [›]  │
+│ ← left (total + pageSize) →            ← right (navigator) → │
+└───────────────────────────────────────────────────────────────┘
+```
+
+| 属性 | 值 |
+|------|---|
+| 总数文本 | "共 N 条" / 12px / `var(--gray-tertiary)` |
+| 每页选择 | "每页显示: [12 ∨]" Select 组件 |
+| 导航器 | 上一页 [页码] 下一页，右对齐 |
+| 整体高度 | 40px |
+| 距 CardGrid 顶部间距 | 16px |
+
+**组件引用**: 使用 `packages/ui/src/components/pagination`（Pagination）+ `packages/ui/src/components/select`（Select，pageSize 选择）。
+
+### 9.9 页面级间距总结（上→下顺序）
+
+| 区域间 | 间距 | 说明 |
+|--------|------|------|
+| PageHeader → ActionToolbar | 16px | 标题到工具栏 |
+| ActionToolbar → CardGrid | 16px | 工具栏到卡片网格 |
+| CardGrid → Pagination | 16px | 最后一行卡片到分页 |
+| Pagination → ContentCard bottom | 20px | 底部留白 |
+| CardGrid 内部 gap | 16px × 16px | 行列等间距 |
+
+### 9.10 Avatar 色块系统标注（截图实证）
+
+> 8 张截图覆盖了 30+ 种不同卡片，avatar 色块系统如下：
+
+| 色系 | 代表字符 | 近似 hex | token 映射 |
+|------|----------|----------|-----------|
+| 紫色 | 财、法 | #7C5CFC | `var(--primary)` |
+| 红/粉 | 产、缺 | #F5597F | `var(--destructive)` 或 `var(--data-1)` |
+| 橙色 | 投、客 | #FF8C42 | `var(--warning)` |
+| 蓝色 | 合、自、日、代、文、网 | #3B82F6 | `var(--data-8)` |
+| 青/蓝绿 | 记忆体全系列 | #06B6D4 | `var(--data-4)` |
+| 绿色 | 回、自我、曙 | #22C55E | `var(--success)` |
+| 黄色 | 天 | #F59E0B | `var(--warning)` 变体 |
+| 灰/靛 | 票、T | #6B7280 | `var(--gray-secondary)` |
+| 深紫 | 绩、多 | #A855F7 | `var(--brand-3)` |
+
+**规则**：
+- 同一页面内可出现多种颜色（按首字 hash 分配）
+- icon 内文字：白色（#FFFFFF）、14px/600、首字母大写
+- icon 圆角：8px（`var(--input-radius)`）
+- glossy 光泽叠加层：参照 [item-card-spec.md §1.6](../_shared/item-card-spec.md#16-avatarpreset色块头像系统iconstyleavatar-且无图片时)