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 BASEhttp://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、LibraryInfrastructure固定在侧边栏底部与主导航组在视觉上分隔侧边栏没有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 youve 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提示词被转发到聊天编辑器没有手动创建对话框 / 没有 NameDescription 表单——该流程是 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 youve 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 libraryprivate 时↔Remove from librarypublic 时——点击它在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 skillonClick中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拉取目标角色的权限字符串仅保存在前端 stateimpersonatedRole/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/ownerCreate 按钮New skill、New agent对member可见member 有stored-{skills,agents}:write对viewer隐藏或禁用直接导航/agent-builder/skills/create和/agent-builder/agents/createmember页面加载具备写权限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 skillidsmoke-seed-public-skillowneruser_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 falseBrowse 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、#16253Extended在 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产品问题与技能问题分列且每一条都要在本轮运行中实时复核而不是凭早前调用的记忆。完整核对清单ChecklistAgent 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考