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功能
115 lines
6.8 KiB
Markdown
115 lines
6.8 KiB
Markdown
# 主应用：工具页 UI/UX
|
||
|
||
## 1. 页面定义
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 页面名称 | 工具 / MCP 工具管理 |
|
||
| 路由 | `/mcp` |
|
||
| 页面实现 | `app-instance/frontend/app/(app)/mcp/page.tsx` |
|
||
| 关键组件 | `MCPPage`、`Dialog`、`Tabs`、MCP 服务卡片、工具详情面板 |
|
||
| 核心任务 | 查看本地/在线 MCP 服务、新增服务、编辑服务、测试连接、删除服务、查看已发现工具 |
|
||
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |
|
||
|
||
## 2. 信息架构与组件层级
|
||
|
||
```text
|
||
AppShell
|
||
└── main.pt-16
|
||
└── /mcp
|
||
├── Page Header
|
||
│ ├── h1 Tools
|
||
│ ├── Refresh
|
||
│ └── Add tool server
|
||
├── Add / Edit MCP Dialog
|
||
│ ├── ID
|
||
│ ├── Tool timeout
|
||
│ ├── Connection mode tabs
|
||
│ │ ├── Remote MCP server
|
||
│ │ │ ├── URL
|
||
│ │ │ ├── Auth mode
|
||
│ │ │ ├── AuthZ permissions preview
|
||
│ │ │ └── Headers JSON
|
||
│ │ └── Install and launch
|
||
│ │ ├── Command
|
||
│ │ └── Arguments
|
||
│ └── Cancel / Save
|
||
├── Error Card
|
||
├── Tool kind tabs
|
||
│ ├── Local tools
|
||
│ └── Online tools
|
||
└── Content grid
|
||
├── MCP service list
|
||
│ ├── Selectable service content
|
||
│ └── Edit / Test / Delete
|
||
└── Tool details panel
|
||
├── Empty selection state
|
||
├── Empty tools state
|
||
└── Tool cards
|
||
```
|
||
|
||
## 3. 布局与响应式规则
|
||
|
||
- 页面外层使用 `max-w-6xl`，移动端内边距为 `16px`，桌面端为 `24px`。
|
||
- 移动端头部按钮自动换行，`Refresh` 和 `Add tool server` 均为 `44px` 高度。
|
||
- 内容区默认单列；`xl` 以上变为左侧 MCP 服务列表、右侧工具详情双栏。
|
||
- MCP 服务卡片的可选中区域和编辑/测试/删除按钮分离，避免卡片 role button 内嵌按钮。
|
||
- 移动端服务卡片头部改为纵向布局，徽章不会挤出右侧边界。
|
||
- 长 ID、URL、command、Audience、Scopes、last error 和工具描述都在容器内换行。
|
||
- 新增/编辑弹窗限制在当前视口内，内容可滚动，底部 Cancel/Save 保持可达。
|
||
- 页面主要按钮、Tab 和服务选择区域均满足 `44px` 触控目标。
|
||
|
||
## 4. 操作与 UX 逻辑
|
||
|
||
| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 刷新工具服务 | 点击 Refresh | 重新拉取 MCP servers、tools、AuthZ 状态 | 获取最新连接和工具发现状态 | 正常 |
|
||
| 切换本地/在线工具 | 点击 Local tools / Online tools | 切换服务列表，并清空右侧选中态 | 避免跨分类误看详情 | 正常 |
|
||
| 选择服务 | 点击服务卡片内容区域或键盘 Enter/Space | 卡片高亮，右侧显示对应工具 | 查看该 MCP 暴露的工具 | 正常 |
|
||
| 测试服务 | 点击 Test | 按钮显示 loading，成功后刷新状态 | 验证 MCP 当前可连接性 | 正常 |
|
||
| 新增远程服务 | 点击 Add tool server，填写 URL/Auth/Header，点击 Save | 校验 ID、URL、timeout、Headers JSON，成功后关闭弹窗并刷新 | 接入已部署 MCP 服务 | 正常 |
|
||
| 新增本地服务 | 弹窗中切换 Install and launch，填写 command/args，点击 Save | 校验 ID、command、timeout，成功后关闭弹窗并刷新 | 接入本地 stdio MCP 进程 | 正常 |
|
||
| 编辑服务 | 点击 Edit | 打开同一弹窗并带入原配置，保存后刷新 | 修改用户自定义 MCP 配置 | 正常 |
|
||
| 删除服务 | 点击 Delete，确认浏览器弹窗 | 确认后调用 delete，成功后取消选中并刷新 | 防止误删 MCP 配置 | 正常 |
|
||
| JSON 输入错误 | Headers JSON 非对象或语法错误 | 页面错误卡显示解析错误，弹窗保持打开 | 保留用户输入并指出修复方向 | 正常 |
|
||
| 加载失败 | servers 接口失败 | 显示错误卡，不阻断页面头部操作 | 明确异常原因并允许重新刷新 | 正常 |
|
||
|
||
## 5. 响应式测试矩阵
|
||
|
||
测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server `http://127.0.0.1:3080` 与生产实例 `terminaltest`；API 使用模拟数据，真实浏览器执行点击、输入、确认弹窗和截图。
|
||
|
||
| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 本地服务详情 | `390×844` | 无 | 0 | 可选择服务、查看工具详情、测试连接 |
|
||
| 在线服务详情 | `390×844` | 无 | 0 | 超长 ID、URL、Audience、错误信息未撑破页面 |
|
||
| 加载错误 | `390×844` | 无 | 0 | 错误卡可读，头部操作仍可见 |
|
||
| 在线服务详情 | `320×568` | 无 | 0 | 窄屏卡片徽章和长字符串均正常换行 |
|
||
| 在线服务详情 | `390×844` | 无 | 0 | 手机竖屏可完成查看与操作 |
|
||
| 在线服务详情 | `844×390` 横屏 | 无 | 0 | 横屏无页面级横向滚动 |
|
||
| 在线服务详情 | `768×1024` | 无 | 0 | 平板单列布局稳定 |
|
||
| 在线服务详情 | `1365×900` | 无 | 0 | 桌面双栏布局正常 |
|
||
|
||
### 关键量化证据
|
||
|
||
- 本地工具页 QA 自动化用例 `4 passed`。
|
||
- 部署到 `terminaltest` 后，同一套工具页 QA 自动化用例 `4 passed`。
|
||
- 覆盖服务选择、工具详情、Tab 切换、Test、Add、Edit、Delete confirm、Refresh、JSON 错误和加载错误。
|
||
- 实测 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
|
||
- 所有实测视口可见小触控目标数为 `0`。
|
||
|
||
## 6. 已修复问题
|
||
|
||
| 等级 | 问题 | 修复 |
|
||
| --- | --- | --- |
|
||
| P1 | `320px` 下在线服务卡片徽章、Audience 长字符串和错误信息横向越界 | 卡片头部移动端纵向布局，所有长字段加 `break-all/min-w-0` |
|
||
| P1 | 新增/编辑弹窗内容过高时 Save 按钮在移动端被挤出视口 | Dialog 限制 `max-height`、启用内部滚动，底部操作区 sticky |
|
||
| P1 | 删除 MCP 服务没有确认，误删风险高 | 删除前增加浏览器确认弹窗 |
|
||
| P2 | 服务卡片整体 `role=button` 内部嵌套 Edit/Test/Delete 按钮 | 改为内容区域可选中，操作按钮独立 |
|
||
| P2 | Refresh、Add、Local/Online tabs 和卡片操作按钮触控高度不足 | 统一提升到 `44px` |
|
||
| P2 | Headers JSON 错误只显示页面级错误，弹窗可能遮挡操作 | 错误卡可读，弹窗保持打开且操作按钮可达 |
|
||
|
||
## 7. 剩余观察项
|
||
|
||
- 本轮自动化使用模拟 MCP 与 AuthZ 数据；真实 MCP 连接超时、鉴权 403 和工具发现异常仍需在后续联测中观察。
|
||
- 当前删除使用浏览器原生确认弹窗，后续可统一为应用内确认 Dialog，以保持视觉一致性。
|