steven_li
2c5205b06e
- 添加MinIO用户文件系统配置选项(BEAVER_MINIO_ROOT_USER等) - 更新外部连接器配置结构，包括BASE_URL和认证令牌设置 - 改进connector provider支持更多类型(official, feishu_bot等) - 实现Mistral模型推理模式支持reasoning_effort参数 - 增强外部连接器策略配置和运行时配置管理 - 添加connector bridge事件验证和安全保护机制 - 优化任务路由逻辑，区分simple_chat和new_task场景 - 更新初始技能工具提示配置，分离authoring admin功能
107 lines
6.0 KiB
Markdown
107 lines
6.0 KiB
Markdown
# 主应用：市场页 UI/UX
|
||
|
||
## 1. 页面定义
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 页面名称 | 技能市场 |
|
||
| 路由 | `/marketplace` |
|
||
| 页面实现 | `app-instance/frontend/app/(app)/marketplace/page.tsx` |
|
||
| 关键组件 | `MarketplacePage`、`SkillDetailView`、`Tabs`、`Card`、`Button`、`Input` |
|
||
| 核心任务 | 搜索 SkillHub 技能、排序筛选、打开详情、查看说明/文件/版本、安装或更新技能 |
|
||
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |
|
||
|
||
## 2. 信息架构与组件层级
|
||
|
||
```text
|
||
AppShell
|
||
└── main.pt-16
|
||
└── /marketplace
|
||
├── Page Header
|
||
│ ├── h1 Marketplace
|
||
│ └── 页面说明
|
||
├── Search Form
|
||
│ ├── 搜索输入框
|
||
│ └── Search
|
||
├── Error Card
|
||
├── Search Results
|
||
│ ├── Sort Buttons
|
||
│ ├── Starred only Filter
|
||
│ ├── Skill Button Cards
|
||
│ └── Pagination
|
||
└── Skill Detail
|
||
├── Back to search
|
||
├── Detail Header
|
||
│ ├── namespace/download/star/version badges
|
||
│ ├── title/summary
|
||
│ └── Install/Reinstall
|
||
├── Overview Tab
|
||
├── Files Tab
|
||
│ ├── file list
|
||
│ └── file preview
|
||
└── Versions Tab
|
||
└── version rows
|
||
```
|
||
|
||
## 3. 布局与响应式规则
|
||
|
||
- 页面外层使用 `max-w-7xl`，移动端内边距为 `16px`，桌面端为 `24px`。
|
||
- 搜索区在移动端垂直排列，桌面端输入框和 Search 按钮横向排列。
|
||
- 结果卡片使用真正的 `button` 语义，而不是仅给 Card 绑定 click，键盘和读屏器都能识别为可操作项。
|
||
- 技能名、namespace、版本号、文件路径、README markdown 和代码预览都允许在容器内断行。
|
||
- 详情页文件列表和文件预览在桌面端左右分栏，移动端垂直排列。
|
||
- Tabs、按钮、输入框和分页操作均满足 `44px` 触控目标。
|
||
- Markdown 中的长代码、表格和链接不会撑出页面；表格在内容区内横向滚动。
|
||
|
||
## 4. 操作与 UX 逻辑
|
||
|
||
| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 搜索技能 | 输入关键词后点击 Search 或提交表单 | 调用 SkillHub search，列表刷新 | 快速定位技能 | 正常 |
|
||
| 切换排序 | 点击 Relevance/Downloads/Newest | 当前排序按钮进入选中态并重新加载 | 支持按不同意图浏览 | 正常 |
|
||
| 只看收藏 | 点击 Starred only | 本地筛选 starCount 大于 0 的结果 | 聚焦已收藏技能 | 正常 |
|
||
| 打开技能详情 | 点击技能卡片按钮 | 加载 detail、version list、SKILL.md | 进入安装前审阅 | 正常 |
|
||
| 返回搜索 | 点击 Back to search | 清空详情状态并回到结果列表 | 提供明确退出路径 | 正常 |
|
||
| 切换说明/文件/版本 | 点击 tab | 同页切换内容区 | 让审阅信息分层 | 正常 |
|
||
| 打开文件 | Files tab 点击文件路径 | 加载并预览文件内容 | 审核技能代码或文档 | 正常 |
|
||
| 切换版本 | Versions tab 点击版本行 | 加载指定版本详情和 README | 安装前比较版本 | 正常 |
|
||
| 安装技能 | 点击 Install/Reinstall | 调用 install API，按钮 loading，成功后显示 installed | 完成技能接入 | 正常 |
|
||
| 加载/安装失败 | API 返回错误 | 显示错误卡片，文本断行 | 明确失败原因并保留当前上下文 | 正常 |
|
||
|
||
## 5. 响应式测试矩阵
|
||
|
||
测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server `http://127.0.0.1:3080` 与生产实例 `terminaltest`；API 使用模拟数据，真实浏览器执行点击、输入、详情打开、文件预览、安装和截图。
|
||
|
||
| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 搜索结果 + 详情 | `320×568` | 无 | 0 | 长 skill 名、namespace 和 summary 不撑破页面 |
|
||
| 搜索结果 + 详情 | `390×844` | 无 | 0 | 可搜索、打开详情、切换文件并安装 |
|
||
| 搜索结果 + 详情 | `844×390` 横屏 | 无 | 0 | 横屏内容可滚动，不产生页面级横向滚动 |
|
||
| 搜索结果 + 详情 | `768×1024` | 无 | 0 | 平板详情布局稳定 |
|
||
| 搜索结果 + 详情 | `1365×900` | 无 | 0 | 桌面分栏和卡片布局正常 |
|
||
|
||
### 关键量化证据
|
||
|
||
- 本地与 `terminaltest` 市场/配置组合 QA 自动化用例均 `4 passed`，其中覆盖市场流。
|
||
- 覆盖搜索、详情、文件 tab、长路径文件预览、安装请求和响应式。
|
||
- 实测 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
|
||
- 所有实测视口可见小触控目标数为 `0`。
|
||
- 本地截图保存在 `/tmp/beaver-market-settings-qa-local-shots`，生产截图保存在 `/tmp/beaver-market-settings-qa-prod-shots`。
|
||
|
||
## 6. 已修复问题
|
||
|
||
| 等级 | 问题 | 修复 |
|
||
| --- | --- | --- |
|
||
| P1 | 结果卡片只有 Card click，没有按钮语义，键盘和辅助技术不可稳定操作 | 改为真实 `button` 卡片 |
|
||
| P1 | 技能详情里的文件路径、版本号、markdown 代码块可能撑破移动端 | 增加 `min-w-0`、`break-all`、`break-words` 和 markdown 预览约束 |
|
||
| P2 | 页面缺少清晰 `h1`，市场页身份不明确 | 增加语义化标题和说明 |
|
||
| P2 | 搜索表单在窄屏可能挤压 | 移动端改为纵向布局 |
|
||
| P2 | Tabs 触控高度不足 44px | 基础 `TabsTrigger` 调整为 `44px` |
|
||
| P2 | 排序、筛选、返回、安装、分页等操作触控尺寸不统一 | 基础按钮和页面操作统一提升到 `44px` |
|
||
| P3 | 长 namespace 和版本 badge 只截断或可能撑宽 | 改为容器内断行 |
|
||
|
||
## 7. 剩余观察项
|
||
|
||
- 本轮使用模拟 SkillHub 数据；真实市场里若存在复杂 HTML/Markdown 表格或超大文件，仍需持续抽样检查。
|
||
- 当前安装成功后停留在详情页并更新 installed 状态，后续可考虑增加轻量 toast，增强成功反馈。
|