Mastra Agent Builder Skill Registry 全流程实战skills.sh 安装与 Library Copy 溯源机制【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇技术指南围绕 Mastra 仓库中 Agent Builder 的 Skill Registry技能注册表机制展开完整讲解两条获取外部技能的路径skills.sh 外部注册表的浏览/搜索/预览/安装以及Library 公共技能库的 Copy复制流程。读者将掌握builder.registries.skillsSh.enabled配置开关的生效规则、全部 registry API 的请求/响应契约含搜索分页、预览 frontmatter 剥离、安装冲突 409、metadata.origin溯源 schema 的设计以及如何通过seed-multi-user.sh在没有第二个账户的前提下验证多用户 Copy 流程。本文以仓库中的 registry.md 为骨架结合 builder-registry.ts、stored-skills.ts 等服务端源码进行纵深印证是 Agent Builder 分支 QA 与二次开发的第一手资料。一、Skill Registry 机制总览两条外部技能获取路径在 Mastra Agent Builder 中除了自己创作技能用户可以通过两条路径获取不属于自己创作集合outside your own authored set的技能外部注册表External registry——当前仅支持skills.sh通过builder.registries.skillsSh.enabled开关选择性开启。开启后可浏览、搜索 skills.sh 上的技能并安装为存储技能stored skill安装产物带metadata.origin { type: skills-sh, ... }溯源标记。Library Copy公共库复制——任何已认证用户都可以复制一条自己不拥有、但为 public 的存储技能。复制结果是一条全新的私有存储技能带metadata.origin { type: library-copy, sourceSkillId, sourceAuthorId, copiedAt }溯源标记。两条路径的共同点是所有产物最终都落到存储技能stored skills体系并统一通过metadata.origin记录从哪来前端据此渲染来源徽标origin badge、提供Open existing等交互。溯源 schema 定义在 stored-skills.ts 的skillOriginSchemadiscriminated union按type字段区分skills-sh与library-copy。二、核心数据契约与配置开关2.1 服务端路由清单Source of truthRegistry 功能对应的路由全部挂在/editor/builder/registries前缀下方法路径作用GET/editor/builder/registries列出所有已知注册表及其启用状态GET/editor/builder/registries/:id/search?q...代理搜索请求到注册表GET/editor/builder/registries/:id/popular获取注册表热门技能列表GET/editor/builder/registries/:id/preview?owner...repo...path...预览单个技能的 SKILL.md 渲染内容POST/editor/builder/registries/:id/install从注册表拉取技能文件树并持久化为新的存储技能对应的权限要求为列表/搜索/热门/预览需要stored-skills:read安装需要stored-skills:write见 builder-registry.ts 中各路由的requiresPermission声明。2.2 配置开关与默认行为启用开关builder.registries.skillsSh.enabled默认false。脚手架项目的默认状态scaffolded 项目默认registries未设置skills.sh 默认禁用。在此配置下UI 中的注册表入口被隐藏且/editor/builder/registries/skills-sh/*所有子路由一律返回404。服务端硬门控handler 中的requireEnabledRegistry会在注册表未知或未启用时抛出404 {message: Registry not found}——这是刻意设计未开启的注册表面向调用方完全不可探测no surface leak for OFF registries见 builder-registry.ts 顶部注释与requireEnabledRegistry实现。列表的语义即使禁用GET /editor/builder/registries仍会返回该注册表条目只是enabled: false例如[{ id: skills-sh, enabled: false }]目的是让前端能渲染已注册但不可用的空状态。resolveRegistries的实现揭示了启用的判断路径通过mastra.getEditor()解析 Builder再调用builder.getRegistries?.()最终判定registries?.skillsSh?.enabled true若 Builder 缺失或无法解析则兜底返回enabled: false。2.3 metadata.origin 溯源 Schemaschema定义在 stored-skills.tsskillOriginSchema以type为判别字段// type: skills-sh { type: skills-sh, owner, repo, skillName, installedAt /* ISO-8601 */ } // type: library-copy { type: library-copy, sourceSkillId, sourceSkillName, sourceAuthorId?, copiedAt /* ISO-8601 */ }持久化时挂在metadata.origin键下源码常量SKILL_ORIGIN_METADATA_KEY origin。配套提供readSkillOrigin(metadata)校验并读取直接创作的技能返回null与buildOriginMetadata(origin)生成 create body 用的 metadata 补丁。三、skills.sh 外部注册表从列表到安装的完整 API 流程以下步骤假设skillsSh.enabled true即在src/mastra/index.ts中显式配置并重启服务后。若未启用先运行步骤 1 确认禁用路径行为再把步骤 2–5 标记为⏭️ skills.sh disabled继续——只有显式启用后才执行完整注册表走查。所有 curl 基于$BASE通常为http://localhost:4111/api与jq输出。步骤 1注册表列表Registries listcurl -s $BASE/editor/builder/registries | jq .启用时预期[{ id: skills-sh, enabled: true, label: ... }]。禁用时预期条目仍在但为[{ id: skills-sh, enabled: false }]——注册表被列出但不可调用对其执行 search/popular/preview/install 一律返回404Registry not found。schema层面builder-registry.tsbuilderRegistryEntrySchema固定id: z.literal(skills-sh)含enabled: boolean与label: string响应外壳为{ registries: [...] }。步骤 2搜索Searchcurl -s $BASE/editor/builder/registries/skills-sh/search?qreact | jq .skills | length常见关键词应返回 200 且至少一条结果。每条结果包含id、name、installs、topSource四个字段对应服务端SkillsShSkillSummary类型见 skills-sh-shared.ts。搜索还支持limit查询参数builderRegistrySearchQuerySchema规定其为整数、范围 1–100、默认 10。服务端通过AbortController设置10 秒超时SEARCH_TIMEOUT_MS上游请求为GET {SKILLS_SH_API_URL}/api/skills?query...pageSize...上游非 2xx 时抛 502。步骤 3热门Popularcurl -s $BASE/editor/builder/registries/skills-sh/popular | jq .skills | length应返回 200 与热门列表。分页参数limit1–100默认 10与offset默认 0且 schema 用.refine强制offset必须是limit的倍数否则 400上游按limit分页见builderRegistryPopularQuerySchema。服务端将 offset 换算为page floor(offset/limit) 1请求/api/skills/top。步骤 4预览Preview从搜索/热门结果中挑一个技能。预览以 GitHub 坐标作为查询参数owner、repo、pathpath即仓库内的技能名schema 为builderRegistryPreviewQuerySchema见 builder-registry.ts。curl -s $BASE/editor/builder/registries/skills-sh/preview?ownerOWNERrepoREPOpathSKILLNAME | jq .预期返回name、description、instructionsfrontmatter 已被剥离与files树。校验点instructions不以---开头证明 YAML frontmatter 已去除。实现层面预览由previewSkillsSh代理到上游/api/skills/{owner}/{repo}/{skillName}/content取响应中的instructions或raw字段上游 404 转本地 404其余错误转 502超时 10 秒。步骤 5安装Install安装请求体为{ owner, repo, skillName, visibility? }schema 为builderRegistryInstallBodySchema。visibility可选private/public行为与标准存储技能创建流程一致调用方已认证时默认private。curl -s -X POST $BASE/editor/builder/registries/skills-sh/install \ -H Content-Type: application/json \ -d { owner: OWNER, repo: REPO, skillName: SKILLNAME } | jq .预期返回 200/201 与{ storedSkillId, name, filesWritten }。随后GET /stored/skills/storedSkillId应显示metadata.origin.type skills-sh。metadata.origin.owner、repo、skillName、installedAt均在。instructions不以---开头。务必记录INSTALLED_SKILL_ID storedSkillId供后续清理使用。安装链路的源码细节builder-registry.tsfetchSkillFiles(owner, repo, skillName)拉取完整文件树30 秒超时找不到技能返回 404Could not find skill ... in owner/repoassertSafeSkillName校验技能名仅允许字母数字、连字符、下划线且以字母数字开头buildFileTree将扁平文件列表转为存储技能所需的树结构每个路径先经assertSafeFilePath防路径穿越校验拒绝绝对路径与./..段见 skills-sh-shared.tsparseSkillSnapshot本地解析SKILL.md的 frontmatter抽取name/description正文第二个---之后作为instructions——避免把 YAML 元数据塞进 Agent 提示词无 frontmatter 时回退name skillId、description Imported from {owner}/{repo}id toSlug(resolvedName)随后用skillStore.getById(id)做碰撞检测作者与可见性决策authorId getCallerAuthorId(requestContext)有调用方 → 默认 private无调用方auth off→ 强制 public落库skillStore.createmetadata.origin写入{ type: skills-sh, owner, repo, skillName }installedAt由创建流程补充。步骤 6冲突Collision对同一技能重复执行安装curl -s -o /tmp/install-err.json -w %{http_code}\n \ -X POST $BASE/editor/builder/registries/skills-sh/install \ -H Content-Type: application/json \ -d { owner: OWNER, repo: REPO, skillName: SKILLNAME } cat /tmp/install-err.json | jq .预期409 Conflict。错误载荷中包含existingSkillId实际为cause: { storedSkillId: id }UI 用它实现Open existing跳转而不是静默覆盖已有技能。步骤 7UI 浏览对话框Browse dialog导航到/agent-builder/skillsBrowse registry 按钮仅当注册表启用时可见由useBuilderRegistries前端 hook 门控点击后打开包含 search popular 两个标签页的对话框选中技能后显示预览面板markdown 渲染点击 Install 创建新存储技能对话框关闭、列表刷新发生冲突时 toast 提供 Open existing点击跳转到已存在的存储技能。步骤 8技能列表上的来源徽标Origin badge在/agent-builder/skills已安装技能显示来源徽标skills.sh 图标或 skills.sh 字样悬停/点击徽标可跳转到来源。四、Library Copy 流程客户端复制的多用户闭环核心设计没有专用的 copy 端点。Library 的 Copy 是前端行为UI 读取源技能字段以常规POST /stored/skills创建新记录并在metadata.origin中写入{ type: library-copy, sourceSkillId, sourceAuthorId, copiedAt }。不要去服务端搜索/copy路由——验证方式是检查结果记录的 origin 元数据。该动作走标准创建路径受stored-skills:write权限门控查看页的 Copy 按钮使用同一检查canCopy !rbacEnabled || hasPermission(stored-skills:write)。脚手架项目授予 member 该权限因此 admin 与 member 都能看到并执行 Copyviewer 看不到按钮在 viewer 角色下将 Copy 步骤标记为n/a — role lacks stored-skills:write。4.1 前置条件多用户数据Setup noteLibrary Copy 要求存在至少一条由其他用户拥有的 public 技能供当前用户复制。全新脚手架没有这种数据三种方案推荐服务端至少启动过一次后运行bash .claude/skills/builder-smoke-test/scripts/seed-multi-user.sh。脚本向 libsql 写入由伪用户user_seed_other拥有的smoke-seed-public-skillpublic与smoke-seed-private-skillprivate使下方所有检查项无需第二个 WorkOS 账户即可执行。第二账户以另一个 WorkOS 用户登录、发布 public 技能再切回测试用户执行 Copy。跳过--auth off模式下所有 API 创建技能都归属同一个null作者Copy 入口不会自然出现未 seed 且无第二账户时将相关步骤标记为n/a — multi-user data not available不要标记为失败。seed-multi-user.sh的实现要点seed-multi-user.sh直接调用sqlite3CLI 操作磁盘上的src/mastra/public/mastra.dblibsql 运行时 DB 路径无 Node 依赖幂等重跑时先PRAGMA foreign_keys OFF删除既有 seed 行再重插因 schema 中mastra_skills.activeVersionId与mastra_skill_versions.id存在自引用外键每条技能插入一行 version 记录保证 UI 有内容可渲染支持--dir path参数与BUILDER_SMOKE_TEST_DIR环境变量定位项目目录运行前需mastra_skills表已存在即服务端至少启动过一次。步骤 9Library 页面列出公共技能导航到/agent-builder/library至少展示一条由当前用户以外作者创作的 public 技能无则按上方 setup note 备注跳过页面上所有技能均为 public 且作者非当前用户。步骤 10复制一条公共技能点击非自己创作的技能详情对话框以只读模式打开Copy 按钮可见对非 owner 的 public 技能它取代了 Edit点击 Copy 弹出命名对话框默认名称为source-name-copy提交后创建一条新的私有存储技能toast 确认点击它跳转到新技能。步骤 11通过 API 验证 origin 元数据curl -s $BASE/stored/skills/copiedSkillId | jq .metadata.origintype为library-copysourceSkillId与源技能一致sourceAuthorId与源作者一致copiedAt是 ISO 时间戳。步骤 12副本的来源徽标在/agent-builder/skills复制出的技能显示 copied 徽标tooltip 为 Copied from 。步骤 13名称冲突不重命名地再次复制同一源技能同名的第二次复制返回409UI 提示用户另取新名。五、清理Cleanupcurl -s -X DELETE $BASE/stored/skills/$INSTALLED_SKILL_ID | jq . # 删除上面创建的任何 library 副本删除通过标准存储技能 DELETE 路由执行脚手架整体是自包含的一次性目录重建 scaffold 即可回到干净状态。六、完整检查清单Checklistskills.sh 注册表Registries list 反映启用开关enabled flagSearch 返回结果Popular 返回结果Preview 剥离 frontmatterInstall 以metadata.origin.type skills-sh持久化重复安装返回 409 且带existingSkillIdUI Browse 按钮由注册表启用状态门控已安装技能渲染来源徽标Library CopyLibrary 页面展示非本人拥有的 public 技能非 owner 可见 Copy 按钮Copy 产生带library-copyorigin 的私有技能复制技能渲染 origin 徽标名称冲突返回 409七、边界情况与故障定位速查现象原因与定位404 Registry not found注册表未启用或 ID 未知。检查builder.registries.skillsSh.enabled是否在src/mastra/index.ts中显式配置并重启服务resolveRegistries仅认enabled true列表显示enabled: false注册表被列出但不可调用属预期行为UI 隐藏入口安装返回 409技能 ID由name经toSlug派生已存在cause.storedSkillId供前端深链搜索/热门 502skills.sh 上游非 2xx10 秒超时触发AbortControllerabortCopy 按钮不出现当前角色缺少stored-skills:writeviewer或库中没有非本人的 public 技能auth off 的null作者场景安装返回 400技能名不合法assertSafeSkillName或文件路径穿越assertSafeFilePath八、关联文档与源码索引本文骨架registry.md上层技能说明与执行流程SKILL.md--test registry、--scope skills等参数用法见其中参数表注册表路由实现builder-registry.ts注册表请求/响应 schemabuilder-registry.tsorigin 溯源 schema 与存储技能 schemastored-skills.tsskills.sh 上游代理与安全校验超时、路径穿越防护skills-sh-shared.ts多用户 seed 脚本seed-multi-user.sh【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考