企业官网建设流程全解析

Mastra Agent Builder UI 验证指南：基于浏览器冒烟测试的 15 项界面核验清单

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本文是 Mastra 仓库中 Agent Builder 功能分支的 UI 冒烟测试操作指南（对应仓库文档 .claude/skills/builder-smoke-test/references/ui.md）。它面向需要在浏览器中逐项验证 Agent Builder 界面的开发者与 QA Agent，覆盖了外壳（Shell）加载、技能/智能体列表、AI 优先的创建流程、编辑/查看页、收藏交互、角色模拟（Impersonation）等核心路径，以及模型下拉、工作区下拉、Library 复制、Registry 按钮门控、来源徽标、移动端底部栏和滚动布局等扩展路径。读完本文，你将掌握一套可复现的分层 UI 验证方案：知道每条路由的预期行为、如何识别有意的设计不对称（而非误报为 Bug），以及如何正确记录⏭️跳过项。

验证环境与运行前提

在动手验证前，需要确认以下前置条件（与 SKILL.md 中的 Setup 部分一致）：

• 浏览器工具可用：文档要求使用 harness 装配的任意浏览器工具（Stagehand、Chrome MCP 等）。如果没有任何浏览器工具可用，用--skip-browser跳过本节，并在结果表中标记为⏭️。
• 服务已运行：开发服务器运行在localhost:4111。
• 预置数据：至少通过 API 创建 1 个 agent 和 1 个 skill 后再进行 UI 测试（也可复用已有的）。同时确保脚手架项目的 public 目录下有预置的公开 skills（供 Library 页面使用，参见 scripts/seed-multi-user.sh 中的smoke-seed-public-skill/smoke-seed-private-skill固定夹具）。
• API 基址约定：所有 curl 示例依赖$BASE环境变量，运行时先执行export BASE=http://localhost:4111/api。

整个验证过程分为两个层级：

• Core（步骤 1–8）：每次 UI 验证都必须执行。覆盖外壳加载、技能列表、技能创建入门、技能编辑页、智能体列表、智能体查看页、收藏切换、角色模拟菜单（仅 admin/owner）。
• Extended（步骤 9–15）：仅当提示明确要求完整 UI 覆盖，或代码变更触及这些界面时才执行。覆盖模型下拉、工作区下拉、Library 复制流程、注册表按钮门控、来源徽标、移动端底部栏一致性、可滚动列表布局。

若跳过某一步，须在结果表中用 ⏭️ 标记并给出一行理由（例如 "extended tier not requested"）。

1. Agent Builder 外壳（Shell）验证

导航到http://localhost:4111/agent-builder，核验以下断言：

• 页面加载无错误；
• 侧边栏可见主导航项：My agents、Skills、Favorites、Library；
• Infrastructure固定在侧边栏底部，与主导航组在视觉上分隔；
• 侧边栏没有Workspaces条目（单工作区布局）。

空项目注意事项：在完全没有 agent 和 skill 的全空项目上，/agent-builder当前会重定向到全页/agent-builder/agents/create入门页（无外壳、无侧边栏）。要验证本节，需先创建至少一个 agent——脚手架的weather-agent只是注册了，存储的 agent 数量初始为 0。一旦存在任一存储的 agent 或 skill，外壳即可渲染。

路由命名的坑：侧边栏的Favorites项导航到/agent-builder/favorite（单数），不是/favorites。复数 URL 未注册路由，会命中 React Router 404。这一点在源码中得到了印证：packages/playground/src/App.tsx 注册的是path: 'favorite'且从./pages/agent-builder/favorite导入组件。脚本化导航时请使用侧边栏链接或单数路径，不要自动补全成复数形式。

2. 技能列表页验证

导航到http://localhost:4111/agent-builder/skills：

• 标题为My skills，副标题为Skills you've created；
• 存在过滤输入框；
• 右上角有+ New skill按钮；
• 每行技能展示名称、描述（若有）以及星标按钮；
• 点击某行导航到/agent-builder/skills/<id>/edit（不是内联详情面板）；
• 规范详情路由为/agent-builder/skills/<id>/edit（所有者）与/agent-builder/skills/<id>/view（非所有者）。裸路径/agent-builder/skills/<id>会重定向到/edit——优先通过列表导航，因为重定向目标不依赖所有权。

3. 通过 UI 创建技能（AI 优先流程）

点击+ New skill，应落在/agent-builder/skills/create：

• 全页入门页渲染，提示语为What skill do you want to build?；
• 可见四个示例提示卡片（例如 Code reviewer、Doc summarizer、Onboarding tutor、Research notes——标签若有漂移需记录）；
• 底部有聊天输入框；
• 提交提示词后通过 API 创建技能，并导航到/agent-builder/skills/<new-id>/edit，提示词被转发到聊天编辑器；
• 没有手动创建对话框 / 没有 Name+Description 表单——该流程是 AI 优先的。

4. 技能编辑页验证

位于/agent-builder/skills/<id>/edit（来自步骤 3 或点击列表行）：

• 头部：返回箭头 + 技能名称，页面为左右分栏工作区；
• 左栏：聊天编辑器（Refine your skill/Ask the agent to refine...）带Send按钮；
• 右栏：技能详情表单——Name、Description、Instructions；
• 没有显式的 Save 按钮——保存为自动保存（在表单附近寻找 saving/saved 指示器）；
• 页面某处可触达Delete skill按钮（通常在详情面板右下角）。若找不到，记为漂移；
• 可见性选择器：--auth off下不渲染（服务端强制 public）；--auth on下，在lg（≥1024px）及以上视口通过VisibilitySelectConnected渲染在页面头部操作组中；低于lg则移入移动端菜单（SkillBuilderMobileMenu的showSetVisibility）。如果桌面槽位看起来是空的，可通过调整视口或打开移动端菜单确认。

源码佐证：移动端菜单组件位于 packages/playground/src/domains/agent-builder/components/skill-edit/skill-builder-mobile-menu.tsx，其lg:hidden类确证了桌面/移动端的响应式切换逻辑——showSetVisibility为 true 时渲染Add to library/Remove from library项，showDelete为 true 时渲染删除项。

5. 智能体列表页验证

导航到http://localhost:4111/agent-builder（或/agents）：

• 标题为My agents，副标题为Agents you've created；
• 右上角有过滤输入框和+ New agent按钮；
• 每行智能体展示名称、描述（若有）以及星标按钮；
• 点击某行导航到/agent-builder/agents/<id>/view（不是/edit）。

有意的不对称：技能列表行去/edit，智能体列表行去/view。这是设计决策——若观察到反向行为，记录为漂移而非直接忽略。

6. 智能体查看页验证

位于/agent-builder/agents/<id>/view：

• 头部附近有View mode药丸徽标；
• 头部：返回箭头、智能体名称、View mode药丸（无刷新按钮）；
• 右上角操作组恰好包含Switch to Edit mode。在--auth off或--auth on下，查看页头部没有Add to library、Show configuration、Make public或Share按钮。智能体的 library/visibility 切换（auth-on、所有者）暴露在编辑页右栏，为Add to library（private 时）↔Remove from library（public 时）——点击它在private与public之间翻转visibility。当前构建（2026-05-28）中任何位置都没有独立的Show configuration按钮。头像位于侧边栏用户菜单中，不在此头部；
• 中部：智能体名称 + 描述，以及一行起始提示卡片（例如What can you do?/Show available tools/Suggest a task/Run a self-check）；
• 底部：Message your agent...聊天输入框——查看页即可运行智能体。

源码佐证：查看页顶栏实现在 packages/playground/src/domains/agent-builder/components/agent-view/view-top-bar.tsx。toggleLabel在 view 模式下渲染Switch to Edit mode，与文档断言一致；ownerActions槽位仅在lg及以上渲染（hidden lg:flex），移动端菜单走lg:hidden槽位。

7. 收藏交互（Star → Favorites）

命名沿革：该功能在stars → favorites重命名后更名为 Favorites。图标仍是星形，但底层状态是行上的favorited/favoriteCount对。

在技能列表页（--auth on下）：

• 点击技能行的星标图标；
• 星标切换为填充/激活态，favoriteCount增加 1；
• 再次点击取消收藏，星标切回轮廓/非激活态，favoriteCount减 1。

在智能体列表页（--auth on下）：同样的切换行为。

--auth off下的预期行为：行渲染星标按钮，但它是有意的 no-op——aria-label 为Sign in to star this {agent|skill}，点击无任何效果，favoriteCount保持0。这是预期行为，不要上报为 Bug。误导性的 "sign in" 标签存在是因为 auth off 时没有登录流程；如果观察到其他任何现象（toast、状态变化、计数变化），才记为漂移。

源码佐证：技能收藏按钮实现在 packages/playground/src/domains/agent-builder/components/skill-list/skill-favorite-button.tsx。未登录时disabledLabel = 'Sign in to star this skill'，onClick中if (!signedIn) return直接短路，确认了 auth-off 下的 no-op 行为；同时它通过useBuilderAgentFeatures().favorites门控——EEagent.favorites功能标志关闭时整个按钮不渲染。

8. 角色模拟（Role Impersonation，仅 admin/owner）

这是通过role-impersonation-context.tsx接线的纯 UI 功能——前端状态，没有后端角色覆盖头。仅在当前登录用户是admin或owner时运行本子集（否则菜单隐藏）。

打开用户菜单——选择器标签为PREVIEW AS ROLE（用户菜单中的节标题），每个角色是该标题下的独立菜单项：

• 选择器只提供与当前角色不同的角色。以 admin 登录时，你会看到Member和Viewer（没有Admin项——admin 是隐式基线）。这是有意的；
• 选择Viewer后：
  • 页面顶部出现模拟横幅，标明当前激活的角色；
  • 侧边栏折叠为 viewer 允许的条目（无 Create/Edit 操作项）；
  • Infrastructure侧边栏条目仍然可见——viewer 权限包含*:read，可匹配infrastructure:read。infra 页对 viewer 是只读的。这不是回归；
  • Create 按钮（如New skill、New agent）消失或渲染为禁用态；
  • 直接导航到只写路由（如/agent-builder/skills/create）在 UI 层被拦截；
• 选择Member后：
  • 横幅更新为 member；
  • 读 + 执行操作项可见；创建/编辑隐藏；
• 退出入口标签为Exit role preview（位于模拟横幅和角色列表下的用户菜单项中）。点击后恢复原始 admin UI。

重要：模拟是纯 UI 层面的。API 仍按真实登录角色应答。模拟 viewer 时用 curl 访问同一端点，仍会得到 admin 的响应。这是预期行为——在报告中如实记录，不要上报为 Bug。

源码佐证：角色模拟状态机实现在 packages/playground/src/domains/auth/context/role-impersonation-context.tsx，其文件头注释明确写着 "UI-only override — server calls still use real admin permissions"。实现通过useMutation调用fetchRolePermissionsRequest拉取目标角色的权限字符串，仅保存在前端 state（impersonatedRole/impersonatedPermissions）中；对应的横幅 UI 位于 packages/playground/src/domains/auth/components/impersonation-banner.tsx。

8b. 非 admin 运行下的 UI 一致性（Core，仅非 admin 运行）

当以--auth on --role member或--role viewer运行时，代替步骤 8 执行本节。步骤 8（角色模拟）仅限 admin——当登录用户非 admin 时，选择器隐藏、无可模拟对象。本节目标是记录非 admin 的真实 UI 表面，并确认它与 references/permissions.md 中的权限矩阵一致。任何与矩阵矛盾之处都是真 Bug；匹配则是预期。

• 侧边栏条目与用户实际权限匹配。My agents、Skills、Favorites、Library、Infrastructure全部对--auth on下的每个默认角色可见，因为每个都有*:read；
• 用户菜单不包含PREVIEW AS ROLE节（仅 admin/owner）；
• Create 按钮（New skill、New agent）对member可见（member 有stored-{skills,agents}:write）；对viewer隐藏或禁用；
• 直接导航/agent-builder/skills/create和/agent-builder/agents/create：
  • member：页面加载（具备写权限）；
  • viewer：重定向到列表页（通过canWrite守卫）；
• 在非当前用户拥有的公开技能上：
  • Copy按钮对member可见（有stored-skills:write）；对viewer隐藏；
  • Delete和Publish操作项对两者都隐藏（仅 admin 动词）；
• Infrastructure页对 member 和 viewer 都渲染（只读表面——部署形态数据，无机密）。

若观察到 viewer 渲染了只写 UI 操作项，记为真实产品问题；若观察到 member 未能渲染只读 UI 操作项，同样记录。

9. 模型下拉（Agent 创建/编辑，Extended）

导航到 agent 编辑页：

• 模型下拉可见；
• 只显示允许的 provider（来自 builder 模型策略）；
• 每个 provider 只显示允许的模型；
• 选择模型会更新 agent 配置。

示例验证：

• 若 builder 配置允许{ provider: 'openai' }（通配符），所有 OpenAI 模型都应出现；
• 若 builder 配置允许{ provider: 'anthropic', name: 'claude-opus-4-7' }，只应出现该特定模型。

模型策略的完整规则见 references/model-policy.md，对应过滤逻辑源码可参考 packages/playground/src/domains/agent-builder/hooks/use-builder-filtered-models.ts 与 packages/playground/src/domains/agent-builder/utils/is-model-not-allowed.ts。

10. 工作区下拉（Skill 编辑，Advanced 模式，Extended）

在技能编辑页查找Advanced mode开关。若存在：

• 切换 Advanced 模式会展开工作区下拉和一个文件树（SKILL.md、references/、scripts/、assets/）；
• Builder 工作区是自动选中的选项。

若当前构建中没有 Advanced mode 开关，记为漂移并跳过。

11. Library 页（非自己拥有的公开技能，Extended）

导航到http://localhost:4111/agent-builder/library：

• 标题Library，副标题Agents shared with the team library；
• 存在 Agents/Skills 标签页切换；
• 在 Skills 标签页，预置公开技能Seeded public skill（idsmoke-seed-public-skill，owneruser_seed_other）出现。私有伴生技能smoke-seed-private-skill不得对非所有者出现在此处。规范夹具见 scripts/seed-multi-user.sh；
• --auth on下，点击非自己拥有的行应导航到/agent-builder/skills/<id>/view（只读）。--auth off下所有人按所有者处理，导航落在/edit——记录实际观察到的路径；
• --auth on下，查看页对任何其他用户拥有的公开技能提供Copy to my skills操作；提交后创建私有副本，origin 徽标为copied。截至 2026-05-28，该操作项尚未接入 Agents 标签页（私有 agent 显示Mark an agent as Public to share it with the team library而非 Copy CTA，即使正在查看他人的公开 agent）——记录缺失为已知漂移；
• --auth off下，Library 页列出所有存储实体（visibility 被强制为 public），但Copy to my skills/Copy to my agents操作被隐藏（没有可归属的 caller）。不要在 auth off 下断言 Copy 行为。

12. Registry 浏览按钮门控（Extended）

仍在/agent-builder/skills：

• 若builder.registries.skillsSh.enabled = false：Browse registry按钮在空状态和顶部区域都隐藏；
• 若enabled = true：按钮显示为Browse registry（通用），打开 registry 对话框。

（完整 registry 流程见 references/registry.md。）

13. 技能列表上的来源徽标（Extended）

• 从 skills.sh 安装的技能显示skills.sh徽标；
• 从 Library 复制的技能显示copied徽标，带 tooltipCopied from <source>；
• 直接创作的技能不显示来源徽标。

14. 移动端底部栏一致性（Extended）

将浏览器缩放到移动宽度（或使用设备切换）：

• 底部栏显示与桌面侧边栏相同的主条目（Agents、Skills、Favorites、Library、Infrastructure——Infrastructure 对所有默认角色只读，因为载荷是部署形态、无机密）；
• 点击每项导航到对应路由，对应标签页处于激活态。

源码佐证：移动端底部栏组件为 packages/playground/src/domains/agent-builder/layouts/agent-builder-mobile-bottom-bar.tsx，桌面侧边栏为 packages/playground/src/domains/agent-builder/layouts/agent-builder-sidebar.tsx——两组条目保持同源，方便验证一致性。

15. 可滚动列表（#16252、#16253，Extended）

在 Agents 和 Skills 列表页：

• 长列表相对布局的其余部分独立滚动；
• 详情面板（如有）滑入时列不塌陷；
• 列表与详情/编辑页之间的导航动画流畅（无布局跳动）。

清理与结果记录

清理

若技能是通过 UI 创建的：

# 删除 UI 创建的技能 curl -s $BASE/stored/skills | jq '.skills[] | select(.name == "UI Smoke Skill") | .id' # 然后用返回的 ID 执行 DELETE

更通用的清理策略（来自 SKILL.md）：停止:4111上的 dev server，然后按需复用或重置$PROJECT_DIR。mastra dev启动时通过 dotenv 加载$PROJECT_DIR/.env并无条件覆盖process.env（见 packages/cli/src/commands/dev/dev.ts），因此切换 auth 模式应重新运行脚手架，而不是手改.env。

结果表

UI 验证的结果应并入总报告（格式见 SKILL.md 的 "Result reporting"），产品问题与技能问题分列，且每一条都要在本轮运行中实时复核，而不是凭早前调用的记忆。

完整核对清单（Checklist）

• Agent Builder 外壳加载，侧边栏正确
• 技能列表页渲染；行导航到/skills/<id>/edit
• 技能创建流程是/skills/create的全页 AI 优先入门
• 技能编辑页是聊天+表单分栏工作区；存在 Delete skill 操作
• 智能体列表页渲染；行导航到/agents/<id>/view
• 智能体查看页渲染 View mode 徽标 + 聊天输入 + 起始提示
• 星标切换在技能和智能体列表上都可用
• 角色模拟菜单可用（仅 admin/owner）
• 模型下拉遵循 builder 策略
• 工作区下拉 / Advanced mode 行为与运行构建一致
• Library 页展示团队公开技能（非所有者可只读查看、可复制）
• Registry 按钮按配置门控
• 来源徽标正确（skills.sh / copied / 无）
• 移动端底部栏与桌面侧边栏条目一致
• 长列表独立滚动、无布局跳动

按此清单逐项执行并如实记录，即可完成一次可复现、可审计的 Agent Builder UI 冒烟测试——既能发现真实回归，也不会把有意的设计决策误报成缺陷。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra