Cherry Studio v2 Skill API 变更指南SKILL.md 元数据标签重命名为 sourceTags 的完整解读【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文是 Cherry Studio v2 重构中一项值得注意的 breaking change 解读Skill 元数据中的标签字段已由tags正式更名为sourceTags。文章面向正在基于 v2 Skill API 做二次开发的开发者、插件作者以及资源库Resource Library功能的使用者帮助读者理解字段重命名的动机、新的语义边界源元数据 vs 可编辑库标签、底层实现链路以及迁移影响。读完本文你将能准确区分sourceTags与资源库标签体系并能够在涉及 Skill 详情、API 数据消费或测试断言时正确处理这一字段。变更概览tags→sourceTags根据 变更记录本次变更的核心内容非常明确Skill metadata tags fromSKILL.mdare now exposed assourceTagsinstead oftagsin the v2 skill API.即在 v2 Skill API 中来源于SKILL.md文件的元数据标签不再以tags字段暴露而是统一以sourceTags字段暴露。这意味着任何依赖旧字段名读取 Skill 标签的调用方包括 IPC 调用、HTTP API 消费者、渲染层组件都必须同步调整字段引用。该变更归属于category: changedseverity: notice提示级别而非破坏性极强的 major change引入于 PR#14442变更日期为 2026-05-09。变更动机资源库标签语义的收拢本次重命名并非简单的字段换名其背后是资源库Resource Library标签体系语义的一次明确收拢。变更记录给出了两条关键依据资源库保留的用户管理库标签user-managed library tags仅用于 assistant助手Skill 详情页仍然展示元数据标签但将其视为来源元数据source metadata而非可编辑的库标签。换句话说在 v2 的语义设计中存在两类截然不同的标签概念来源是否用户可编辑适用对象sourceTags源元数据标签Skill 目录中的SKILL.md文件否只读展示Skill库标签user-managed library tags用户在资源库中自行管理是仅 assistant从渲染层源码可以印证这一设计意图。资源库 Hook 在将InstalledSkill构建为资源项时明确注释Skill metadata tags fromSKILL.mdlive onsourceTags; assistant organization in the resource library uses Group rows instead.这进一步说明资源库中 assistant 的组织依赖的是 Group分组行而 Skill 的sourceTags只是展示性的源元数据两者互不混淆。字段名从宽泛的tags改为语义明确的sourceTags正是为了在 API 层面消除这种歧义避免调用方误将 Skill 的源元数据当成可编辑的资源库标签来操作。API 与类型层面的变更细节共享类型定义在 共享类型文件 中InstalledSkillSchema已将字段定义为export const InstalledSkillSchema z.object({ id: z.string(), name: z.string(), description: z.string().nullable(), folderName: z.string(), source: z.string(), sourceUrl: z.string().nullable(), namespace: z.string().nullable(), author: z.string().nullable(), version: z.string().nullable(), sourceTags: z.array(z.string()).default([]), contentHash: z.string(), isGlobalEnabled: z.boolean(), isEnabled: z.boolean(), createdAt: z.iso.datetime(), updatedAt: z.iso.datetime() })几个值得注意的细节sourceTags的类型为z.array(z.string())即字符串数组带有.default([])兜底当某 Skill 的SKILL.md未声明任何标签时字段默认返回空数组避免下游出现undefined崩溃该文件同时声明了SkillCatalogEntry InstalledSkill { scope: system | builtin | local }说明所有作用域系统、内置、本地的 Skill 均沿用同一字段约定。HTTP API Schema在 Skills API Schema 中v2 数据 API 层的定义与共享类型保持一致export const InstalledSkillSchema z.strictObject({ id: z.string(), // ... /** Skill metadata tags from SKILL.md. */ sourceTags: z.array(z.string()), // ... })注意该 Schema 使用的是z.strictObject严格对象模式这意味着响应中只允许出现 schema 中声明的字段。旧版调用方若仍尝试读取tags字段将无法从该 schema 中解析到对应数据——这正是 breaking change 的实质体现。GET /skills与GET /skills/:skillId的响应体均为InstalledSkill因此两条端点返回的标签字段全部统一为sourceTags。源码实现链路从 SKILL.md 到 sourceTags要理解这个字段的完整生命周期需要沿解析 → 落库 → 映射 → 展示四个环节追踪源码。第一步安装/更新时解析 SKILL.md 元数据SkillService.ts 在 Skill 安装与更新流程中读取SKILL.md的元数据const tags metadata.tags ?? [] // 更新场景原地更新元数据保留 skill ID 与 agent_skills 关联行 agentGlobalSkillService.updateTx(tx, existing.id, { name: metadata.name, description: metadata.description ?? null, author: metadata.author ?? null, version: metadata.version ?? null, tags, contentHash, // ... }) // 全新安装场景写入数据库 agentGlobalSkillService.insertTx(tx, { name: metadata.name, // ... tags, contentHash })可以看出SKILL.md中的tags元数据在解析后写入数据库的tags列该列的物理命名保持tags不变字段重命名发生在对外 API 暴露层而非存储层。这是典型的存储与契约解耦做法内部表结构无需迁移仅调整对外契约。第二步数据库行 → API 对象的字段映射AgentGlobalSkillService.ts 中的rowToInstalledSkill完成了核心映射private rowToInstalledSkill(row: AgentGlobalSkillRow): InstalledSkill { return { id: row.id, name: row.name, // ... sourceTags: row.tags, // 数据库 tags 列 → API sourceTags 字段 contentHash: row.contentHash, isGlobalEnabled: row.isEnabled, isEnabled: false, // ... } }这就是整个变更最关键的一行代码row.tags内部存储名被映射为对外契约中的sourceTags。任何通过 v2 Skill APIIPC 或 HTTP获取到的 Skill 对象其标签字段名均为sourceTags。第三步渲染层消费与展示Skill 详情弹窗SkillDetailDialog.tsx 中读取const sourceTags skill.sourceTags ?? []并在详情头部将前 3 个标签以文本形式渲染与来源skill.source、作者skill.author并列展示。这些标签是纯展示性的源元数据不提供编辑入口。资源库列表useResourceLibrary.ts 在构建 Skill 资源项时不再把sourceTags当作可筛选、可编辑的库标签处理——assistant 的组织走 Group 行机制Skill 的标签仅作为旁置元数据。测试验证变更已被测试用例锁定该变更并非仅停留在类型层面仓库中的测试明确锁定了新的行为契约。在 SkillService.test.ts 中it(returns source metadata tags and does not expose user tags, async () { // ...mock 安装一个包含 tags: [source-ai] 的 SKILL.md expect(skill?.sourceTags).toEqual([source-ai]) expect(tags in (skill as object)).toBe(false) })这条测试同时断言了两件事正向断言sourceTags正确承载SKILL.md中的元数据标签[source-ai]负向断言Skill 对象上不再存在tags属性tags in skill false。测试用例以expect(tags in (skill as object)).toBe(false)的方式直接杜绝了旧字段名回归的可能为依赖方提供了明确的契约保障。同一文件中第 345 行附近还有类似的断言expect(tags in (result as object)).toBe(false)进一步覆盖了列表等聚合返回场景。用户影响与迁移方式变更记录明确指出nothing - automatic。即普通终端用户无需执行任何手动操作已安装 Skill 的标签数据在数据库中的tags列并未被删除只是对外暴露的字段名发生变化资源库界面中 Skill 详情页的标签展示逻辑已随代码同步更新用户看到的展示行为保持不变标签仍显示只是语义上明确为源元数据不存在需要用户手动迁移、备份或重建标签的操作。对于开发者而言唯一需要关注的是API 消费者若你的代码IPC 调用、HTTP 客户端、渲染层组件从 Skill 对象中读取标签请将字段引用从skill.tags改为skill.sourceTags类型使用者以InstalledSkill类型为入参的代码sourceTags默认值为[]读取时无需额外判空但写入或透传时应遵循字符串数组类型测试维护者如你的测试断言中仍出现tags字段需要同步更新并建议参照上述测试用例同时加入负向断言防止字段名回归。发布管理者注意事项作为severity: notice级别的变更发布管理者release manager在撰写 release notes 时仅当发行说明涉及资源库标签行为或 Skill 元数据字段时才需要提及本变更。换言之本变更属于静默兼容性质的契约调整普通功能性的 release notes 无需为它单独开篇幅只有在讨论标签语义、Skill 元数据结构或资源库组织方式时才应补充说明sourceTags的引入及其与库标签的语义区分避免用户将二者混淆。小结tags→sourceTags的重命名是 Cherry Studio v2 Skill API 在语义清晰化方面的一次收敛它将来源于 SKILL.md 的只读源元数据与资源库中用户可管理的库标签在 API 契约层面彻底区分开来。底层存储数据库tags列无需迁移用户无需任何操作但所有基于 v2 Skill API 消费标签数据的代码都应改用sourceTags并以测试断言锁定新契约。对开发者而言这既是一次字段名的简单调整也是对 Skill 元数据语义边界的明确认知升级。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考