This commit is contained in:
小妍儿 ✨ 2026-11-03 02:33:01 +00:00 • committed by GitHub
commit b63fd28852
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
39 changed files with 634 additions and 131 deletions

View file

@ -37,6 +37,20 @@ skillhub publish ./my-skill --namespace myspace
skillhub sync pull --namespace myspace
```
## Presentation metadata for published packages
Add optional `metadata.short-description` (up to 200 characters) and `metadata.overview` (Markdown, up to 20,000 characters) to `SKILL.md` frontmatter. The former is the card/search summary; the latter is the detail-page overview. Neither changes the original required `description`, slug, or archive contents. If absent, summary uses `description` and the detail view uses README.md then SKILL.md. CLI publication reads these package keys directly; it does not need web-only multipart fields. Custom web values belong to version snapshots, not the package.
```yaml
---
name: my-skill
description: When to use this skill
metadata:
short-description: Brief card text
overview: "# Detailed overview"
---
```
## 🌐 Registry Configuration
The active registry is resolved in the following priority order:

View file

@ -69,7 +69,7 @@ WHERE (visibility = 'PUBLIC')
| title | varchar(256) | |
| summary | varchar(512) | |
| keywords | varchar(512) | |
| search_text | text | `displayName`、`slug`、`summary`,以及 frontmatter 中除 `name` / `description` / `version` 外的字段展开结果 |
| search_text | text | `displayName`、`slug`、有效简短描述、原始包 `description`,以及 frontmatter 中除 `name` / `description` / `version` 与仅用于详情的 `metadata.overview` 外的字段展开结果 |
| visibility | enum | 冗余,避免搜索时 join |
| status | enum | |
| updated_at | datetime | |

View file

@ -44,8 +44,9 @@ description: When to use # 必需,1-2 句话
- 网页发布 multipart 可选字段 `displayName` 在 trim 后非空时优先于包内展示名,最长 200 字符;空白回退包内字段。该覆盖值保存在版本元数据快照,原始 frontmatter 和文件内容不改写;下载 ZIP 沿用现有重新打包机制,压缩包二进制可能不同。CLI 不填写此字段时继续使用包内规则。
- 网页上传后通过鉴权只读 `POST /api/web/skills/package-preview`(也提供 `/api/v1/skills/package-preview`)读取 `name/displayName/description/version`;此步骤不保存包、不创建技能或启动扫描,正式提交仍执行完整校验。
- 上述类型和长度限制在新上传解析时检查。读取历史版本快照时,非字符串或超长的旧 `display-name` 回退到该版本的 `name`,原始 frontmatter 保留,避免阻塞审核、提升或版本撤回。
- `description` 映射为 `skill.summary`
- frontmatter 完整解析结果存入 `skill_version.parsed_metadata_json`
- `metadata.short-description` 可选,作为卡片、列表和搜索摘要,去除首尾空白后最多 200 个字符;缺失时回退到原始 `description`。`metadata.overview` 可选,为详情页 Markdown 概览,最多 20,000 个字符;缺失时详情页按 README.md → SKILL.md 回退。
- 网页发布 multipart 可选字段 `shortDescription`、`overview` 和 `resetPresentation`;网页显式值优先于包内元数据,`resetPresentation=true` 清除自定义覆盖并禁止本次继承。两边均未提供展示值时,仅继承提交时当前已发布版本的自定义覆盖,并在快照记录 `presentationInheritedFrom`;不继承旧版包内默认值。值随版本快照保存,原始包文件不变。待审核版本不更新公开摘要,审核通过后才生效。
- 有效 short description 映射为 `skill.summary`;原始 `description` 仍加入搜索文本。frontmatter 完整解析结果存入 `skill_version.parsed_metadata_json`。
平台扩展字段(可选,`x-astron-` 前缀):

View file

@ -91,7 +91,7 @@ Status: contract reference with documented implementation exception
- `PENDING_REVIEW -> PUBLISHED`
- review task 标记为 `APPROVED`
- `Skill.latestVersionId` 指向该版本
- skill 展示元数据从发布版本刷新
- skill 展示元数据从发布版本刷新,摘要采用该版本有效 `short-description`(自定义覆盖优先,其次包内值,再退回 `description`);`overview` 仅在选中版本详情展示。提交时的自定义继承冻结在版本快照,审核期间不随其他版本发布而变化。
### 4.3 审核拒绝

View file

@ -20,7 +20,7 @@
{"name":"skillVersionCompareRoute","path":"/space/$namespace/$slug/compare","declaration":{"file":"web/src/app/router.tsx","line":374},"implementation":{"file":"web/src/pages/skill-version-compare.tsx","line":22,"export":"SkillVersionComparePage"},"guarded":false,"roleProtected":false},
{"name":"dashboardRoute","path":"dashboard","declaration":{"file":"web/src/app/router.tsx","line":384},"implementation":{"file":"web/src/pages/dashboard.tsx","line":98,"export":"DashboardPage"},"guarded":true,"roleProtected":false},
{"name":"dashboardSkillsRoute","path":"dashboard/skills","declaration":{"file":"web/src/app/router.tsx","line":391},"implementation":{"file":"web/src/pages/dashboard/my-skills.tsx","line":46,"export":"MySkillsPage"},"guarded":true,"roleProtected":false},
{"name":"dashboardPublishRoute","path":"dashboard/publish","declaration":{"file":"web/src/app/router.tsx","line":404},"implementation":{"file":"web/src/pages/dashboard/publish.tsx","line":41,"export":"PublishPage"},"guarded":true,"roleProtected":false},
{"name":"dashboardPublishRoute","path":"dashboard/publish","declaration":{"file":"web/src/app/router.tsx","line":404},"implementation":{"file":"web/src/pages/dashboard/publish.tsx","line":42,"export":"PublishPage"},"guarded":true,"roleProtected":false},
{"name":"dashboardSuiteCreateRoute","path":"dashboard/suites/new","declaration":{"file":"web/src/app/router.tsx","line":430},"implementation":{"file":"web/src/pages/dashboard/suite-editor.tsx","line":716,"export":"SuiteCreatePage"},"guarded":true,"roleProtected":false},
{"name":"dashboardSuitesRoute","path":"dashboard/suites","declaration":{"file":"web/src/app/router.tsx","line":437},"implementation":{"file":"web/src/pages/dashboard/my-suites.tsx","line":21,"export":"MySuitesPage"},"guarded":true,"roleProtected":false},
{"name":"dashboardSuiteManagementRoute","path":"dashboard/suites/$namespace/$slug","declaration":{"file":"web/src/app/router.tsx","line":447},"implementation":{"file":"web/src/pages/dashboard/suite-management.tsx","line":31,"export":"SuiteManagementPage"},"guarded":true,"roleProtected":false},
@ -645,21 +645,21 @@
{"file":"web/src/pages/dashboard/promotions.tsx","line":439,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["promotion.revocation.history"]},
{"file":"web/src/pages/dashboard/promotions.tsx","line":440,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["promotion.approved.tab"]},
{"file":"web/src/pages/dashboard/promotions.tsx","line":441,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["promotion.rejected.tab"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":265,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.publish.namespace.interact"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":269,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.namespace.clear"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":271,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.namespace.select"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":283,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.publish.visibility.interact"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":287,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.visibility.public"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":288,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.visibility.namespace"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":289,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.visibility.private"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":297,"host":"UploadZone","prop":"analyticsId","event":"click+keydown+change+drop","ids":["skill.package.select"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":297,"host":"UploadZone","prop":"folderAnalyticsId","event":"change","ids":["skill.package.folder.select"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":297,"host":"UploadZone","prop":"pickerAnalyticsId","event":"click","ids":["skill.package.folder.open"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":312,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.package.remove"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":343,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.package.preview.retry"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":355,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.avatar.save","skill.publish.request"],"conditional":true},
{"file":"web/src/pages/dashboard/publish.tsx","line":365,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.publish.confirm"],"conditional":true},
{"file":"web/src/pages/dashboard/publish.tsx","line":365,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.publish.cancel"],"conditional":true},
{"file":"web/src/pages/dashboard/publish.tsx","line":285,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.publish.namespace.interact"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":289,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.namespace.clear"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":291,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.namespace.select"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":303,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.publish.visibility.interact"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":307,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.visibility.public"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":308,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.visibility.namespace"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":309,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.publish.visibility.private"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":317,"host":"UploadZone","prop":"analyticsId","event":"click+keydown+change+drop","ids":["skill.package.select"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":317,"host":"UploadZone","prop":"folderAnalyticsId","event":"change","ids":["skill.package.folder.select"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":317,"host":"UploadZone","prop":"pickerAnalyticsId","event":"click","ids":["skill.package.folder.open"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":332,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.package.remove"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":363,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.package.preview.retry"]},
{"file":"web/src/pages/dashboard/publish.tsx","line":393,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.avatar.save","skill.publish.request"],"conditional":true},
{"file":"web/src/pages/dashboard/publish.tsx","line":403,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.publish.confirm"],"conditional":true},
{"file":"web/src/pages/dashboard/publish.tsx","line":403,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.publish.cancel"],"conditional":true},
{"file":"web/src/pages/dashboard/reports.tsx","line":131,"host":"button","prop":"data-analytics-id","event":"click","ids":["skill.detail.open"]},
{"file":"web/src/pages/dashboard/reports.tsx","line":151,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.dismiss.request"]},
{"file":"web/src/pages/dashboard/reports.tsx","line":159,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.resolve.request"]},
@ -821,79 +821,79 @@
{"file":"web/src/pages/settings/profile.tsx","line":215,"host":"form","prop":"data-analytics-id","event":"submit","ids":["account.profile.save"]},
{"file":"web/src/pages/settings/profile.tsx","line":261,"host":"Button","prop":"data-analytics-id","event":"click","ids":["account.profile.cancel"]},
{"file":"web/src/pages/settings/security.tsx","line":96,"host":"form","prop":"data-analytics-id","event":"submit","ids":["account.password.save"]},
{"file":"web/src/pages/skill-detail.tsx","line":831,"host":"Button","prop":"data-analytics-id","event":"click","ids":["auth.login.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":867,"host":"div","prop":"data-analytics-id","event":"structural","ids":["skill.detail.render"]},
{"file":"web/src/pages/skill-detail.tsx","line":872,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.detail.back"]},
{"file":"web/src/pages/skill-detail.tsx","line":923,"host":"CopyButton","prop":"analyticsId","event":"click","ids":["skill.coordinate.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":945,"host":"Link","prop":"data-analytics-id","event":"click","ids":["search.label.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":985,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["skill.overview.tab"]},
{"file":"web/src/pages/skill-detail.tsx","line":986,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["skill.files.tab"]},
{"file":"web/src/pages/skill-detail.tsx","line":987,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["skill.versions.tab"]},
{"file":"web/src/pages/skill-detail.tsx","line":1015,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.overview.toggle"]},
{"file":"web/src/pages/skill-detail.tsx","line":1058,"host":"FileTree","prop":"analyticsId","event":"click","ids":["skill.file.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1097,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.comparison.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1104,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.rerelease.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1114,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.version.delete"]},
{"file":"web/src/pages/skill-detail.tsx","line":1123,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.review.withdraw"]},
{"file":"web/src/pages/skill-detail.tsx","line":1132,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.version.publish"]},
{"file":"web/src/pages/skill-detail.tsx","line":1141,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.review.submit"]},
{"file":"web/src/pages/skill-detail.tsx","line":1178,"host":"button","prop":"data-analytics-id","event":"click","ids":["skill.browser.toggle"]},
{"file":"web/src/pages/skill-detail.tsx","line":1200,"host":"FileTree","prop":"analyticsId","event":"click","ids":["skill.file.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1253,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.create.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1291,"host":"Link","prop":"data-analytics-id","event":"click","ids":["suite.detail.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1318,"host":"Link","prop":"data-analytics-id","event":"click","ids":["skill.related.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1373,"host":"InstallCommand","prop":"analyticsId","event":"click","ids":["skill.command.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":1373,"host":"InstallCommand","prop":"skillhubAnalyticsId","event":"click","ids":["skill.command.skillhub.select"]},
{"file":"web/src/pages/skill-detail.tsx","line":1373,"host":"InstallCommand","prop":"clawhubAnalyticsId","event":"click","ids":["skill.command.clawhub.select"]},
{"file":"web/src/pages/skill-detail.tsx","line":1413,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.review.withdraw"]},
{"file":"web/src/pages/skill-detail.tsx","line":1423,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.download.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1442,"host":"InstallForAgentButton","prop":"analyticsId","event":"click","ids":["skill.prompt.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":1514,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.unarchive.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1518,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.archive.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1523,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.delete.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1555,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.promotion.version.interact"]},
{"file":"web/src/pages/skill-detail.tsx","line":1560,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.promotion.version"]},
{"file":"web/src/pages/skill-detail.tsx","line":1569,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.promotion.create.request","skill.promotion.update.request"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1582,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1586,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.direct"]},
{"file":"web/src/pages/skill-detail.tsx","line":1621,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.hide.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1625,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.unhide.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1631,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.version.yank"]},
{"file":"web/src/pages/skill-detail.tsx","line":1641,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["report.create.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1661,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.create.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1664,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.create.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1671,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.promotion.create.confirm","skill.promotion.update.confirm"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1671,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.promotion.create.cancel","skill.promotion.update.cancel"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1690,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.revocation.direct.cancel","skill.revocation.request.cancel"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1703,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.direct.cancel","skill.revocation.request.cancel"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1704,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.direct.submit","skill.revocation.request.submit"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1711,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.archive.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1711,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.archive.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1720,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.unarchive.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1720,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.unarchive.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1729,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.delete.continue"]},
{"file":"web/src/pages/skill-detail.tsx","line":1729,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.delete.continue.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1748,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.delete.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1764,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.delete.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1767,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.delete.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1778,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.version.delete.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1778,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.version.delete.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1792,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.review.withdraw.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1792,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.review.withdraw.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1816,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.rerelease.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1836,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.rerelease.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1839,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.rerelease.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1846,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.rerelease.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1846,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.rerelease.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1867,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.version.publish.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1867,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.version.publish.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1880,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.review.submit.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1880,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.review.submit.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1902,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.comparison.close"]},
{"file":"web/src/pages/skill-detail.tsx","line":1967,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.comparison.close"]},
{"file":"web/src/pages/skill-detail.tsx","line":1981,"host":"FilePreviewDialog","prop":"closeAnalyticsId","event":"click","ids":["skill.file.close"]},
{"file":"web/src/pages/skill-detail.tsx","line":1981,"host":"FilePreviewDialog","prop":"downloadAnalyticsId","event":"click","ids":["skill.file.download"]},
{"file":"web/src/pages/skill-detail.tsx","line":1981,"host":"FilePreviewDialog","prop":"copyAnalyticsId","event":"click","ids":["skill.file.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":832,"host":"Button","prop":"data-analytics-id","event":"click","ids":["auth.login.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":868,"host":"div","prop":"data-analytics-id","event":"structural","ids":["skill.detail.render"]},
{"file":"web/src/pages/skill-detail.tsx","line":873,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.detail.back"]},
{"file":"web/src/pages/skill-detail.tsx","line":924,"host":"CopyButton","prop":"analyticsId","event":"click","ids":["skill.coordinate.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":946,"host":"Link","prop":"data-analytics-id","event":"click","ids":["search.label.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":986,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["skill.overview.tab"]},
{"file":"web/src/pages/skill-detail.tsx","line":987,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["skill.files.tab"]},
{"file":"web/src/pages/skill-detail.tsx","line":988,"host":"TabsTrigger","prop":"data-analytics-id","event":"click","ids":["skill.versions.tab"]},
{"file":"web/src/pages/skill-detail.tsx","line":1022,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.overview.toggle"]},
{"file":"web/src/pages/skill-detail.tsx","line":1065,"host":"FileTree","prop":"analyticsId","event":"click","ids":["skill.file.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1104,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.comparison.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1111,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.rerelease.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1121,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.version.delete"]},
{"file":"web/src/pages/skill-detail.tsx","line":1130,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.review.withdraw"]},
{"file":"web/src/pages/skill-detail.tsx","line":1139,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.version.publish"]},
{"file":"web/src/pages/skill-detail.tsx","line":1148,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.review.submit"]},
{"file":"web/src/pages/skill-detail.tsx","line":1185,"host":"button","prop":"data-analytics-id","event":"click","ids":["skill.browser.toggle"]},
{"file":"web/src/pages/skill-detail.tsx","line":1207,"host":"FileTree","prop":"analyticsId","event":"click","ids":["skill.file.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1260,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.create.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1298,"host":"Link","prop":"data-analytics-id","event":"click","ids":["suite.detail.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1325,"host":"Link","prop":"data-analytics-id","event":"click","ids":["skill.related.open"]},
{"file":"web/src/pages/skill-detail.tsx","line":1380,"host":"InstallCommand","prop":"analyticsId","event":"click","ids":["skill.command.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":1380,"host":"InstallCommand","prop":"skillhubAnalyticsId","event":"click","ids":["skill.command.skillhub.select"]},
{"file":"web/src/pages/skill-detail.tsx","line":1380,"host":"InstallCommand","prop":"clawhubAnalyticsId","event":"click","ids":["skill.command.clawhub.select"]},
{"file":"web/src/pages/skill-detail.tsx","line":1420,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.review.withdraw"]},
{"file":"web/src/pages/skill-detail.tsx","line":1430,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.download.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1449,"host":"InstallForAgentButton","prop":"analyticsId","event":"click","ids":["skill.prompt.copy"]},
{"file":"web/src/pages/skill-detail.tsx","line":1521,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.unarchive.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1525,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.archive.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1530,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.delete.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1562,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.promotion.version.interact"]},
{"file":"web/src/pages/skill-detail.tsx","line":1567,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.promotion.version"]},
{"file":"web/src/pages/skill-detail.tsx","line":1576,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.promotion.create.request","skill.promotion.update.request"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1589,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1593,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.direct"]},
{"file":"web/src/pages/skill-detail.tsx","line":1628,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.hide.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1632,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.unhide.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1638,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.version.yank"]},
{"file":"web/src/pages/skill-detail.tsx","line":1648,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["report.create.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1668,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.create.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1671,"host":"Button","prop":"data-analytics-id","event":"click","ids":["report.create.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1678,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.promotion.create.confirm","skill.promotion.update.confirm"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1678,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.promotion.create.cancel","skill.promotion.update.cancel"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1697,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.revocation.direct.cancel","skill.revocation.request.cancel"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1710,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.direct.cancel","skill.revocation.request.cancel"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1711,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.revocation.direct.submit","skill.revocation.request.submit"],"conditional":true},
{"file":"web/src/pages/skill-detail.tsx","line":1718,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.archive.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1718,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.archive.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1727,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.unarchive.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1727,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.unarchive.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1736,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.delete.continue"]},
{"file":"web/src/pages/skill-detail.tsx","line":1736,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.delete.continue.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1755,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.delete.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1771,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.delete.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1774,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.delete.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1785,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.version.delete.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1785,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.version.delete.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1799,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.review.withdraw.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1799,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.review.withdraw.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1823,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.rerelease.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1843,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.rerelease.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1846,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.rerelease.request"]},
{"file":"web/src/pages/skill-detail.tsx","line":1853,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.rerelease.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1853,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.rerelease.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1874,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.version.publish.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1874,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.version.publish.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1887,"host":"ConfirmDialog","prop":"confirmAnalyticsId","event":"click","ids":["skill.review.submit.confirm"]},
{"file":"web/src/pages/skill-detail.tsx","line":1887,"host":"ConfirmDialog","prop":"cancelAnalyticsId","event":"click","ids":["skill.review.submit.cancel"]},
{"file":"web/src/pages/skill-detail.tsx","line":1909,"host":"DialogContent","prop":"closeAnalyticsId","event":"click","ids":["skill.comparison.close"]},
{"file":"web/src/pages/skill-detail.tsx","line":1974,"host":"Button","prop":"data-analytics-id","event":"click","ids":["skill.comparison.close"]},
{"file":"web/src/pages/skill-detail.tsx","line":1988,"host":"FilePreviewDialog","prop":"closeAnalyticsId","event":"click","ids":["skill.file.close"]},
{"file":"web/src/pages/skill-detail.tsx","line":1988,"host":"FilePreviewDialog","prop":"downloadAnalyticsId","event":"click","ids":["skill.file.download"]},
{"file":"web/src/pages/skill-detail.tsx","line":1988,"host":"FilePreviewDialog","prop":"copyAnalyticsId","event":"click","ids":["skill.file.copy"]},
{"file":"web/src/pages/skill-version-compare.tsx","line":160,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.comparison.base.interact"]},
{"file":"web/src/pages/skill-version-compare.tsx","line":165,"host":"SelectItem","prop":"data-analytics-id","event":"radix-item-intent","ids":["skill.comparison.base"]},
{"file":"web/src/pages/skill-version-compare.tsx","line":187,"host":"SelectTrigger","prop":"data-analytics-id","event":"click+keydown-intent","ids":["skill.comparison.head.interact"]},

View file

@ -0,0 +1,7 @@
# Design
- Parse `metadata.short-description` and `metadata.overview` from SKILL.md, with limits of 200 and 20,000 characters.
- Accept multipart `shortDescription`, `overview`, and `resetPresentation`; web values override package metadata and are stored in `parsedMetadataJson` as `shortDescriptionOverride`, `overviewOverride`, and `presentationInheritedFrom`.
- Keep the existing display-name/version snapshot model and publish/review/rollback lifecycle. Pending versions never update the Skill container summary.
- The effective short description feeds `skill.summary`; search also retains the original package description in `search_text`. Overview is detail-only and falls back to README then SKILL.md in the existing documentation reader.
- Web package preview supplies defaults without editing the uploaded archive. Generated API types remain authoritative.

View file

@ -0,0 +1,10 @@
# Add skill presentation fields
## Why
Skill packages currently expose only one description and cannot provide a concise card summary plus a richer detail overview without modifying package files.
## Scope
Add optional short description and Markdown overview to web and CLI-compatible publish metadata. Values are version snapshots, preserve package files, and use package metadata/default documentation when omitted. Public content changes only when the version publishes.
## Non-goals
No upload-free editing, database migration, i18n variants, or dedicated presentation file.

View file

@ -0,0 +1,23 @@
# Requirements
## Presentation metadata
The system MUST accept optional `metadata.short-description` and `metadata.overview` in SKILL.md. The short description MUST be at most 200 characters and the overview at most 20,000 characters.
## Web publish precedence
A web-provided value MUST override the package value for that submitted version. The archive MUST remain unchanged. Reset MUST remove the custom override so the package/default resolution applies.
## Lifecycle isolation
A pending version MUST NOT replace the currently published title, summary, or overview. Published metadata MUST be restored by rollback/yank using the selected published version snapshot.
## Search and detail
The effective short description MUST be used as the public summary. The original package description MUST remain searchable. The detailed overview MUST NOT be indexed and MUST fall back to README.md then SKILL.md when no explicit/package overview exists.
## Scenarios
- Given package metadata and web values, when previewing, the form is prefilled from package defaults and explicit edits win.
- Given a pending update, when it is submitted, public summary remains unchanged until publication.
- Given reset, when the version publishes, it uses package defaults and later default versions read their own package defaults.

View file

@ -0,0 +1,10 @@
# Tasks
- [x] Add SKILL.md metadata parsing and validation.
- [x] Add multipart publish fields and package-preview defaults.
- [x] Snapshot presentation fields in parsed metadata and update effective published summary.
- [x] Preserve original description in search text and keep pending updates isolated.
- [x] Add web short-description and Markdown-overview inputs.
- [x] Add full inheritance/restore-default/rollback acceptance coverage (published-only frozen inheritance, reset/default-not-copied, yank rollback, approval, promotion, and rerelease).
- [x] Regenerate OpenAPI types and update CLI usage documentation.
- [x] Add detail-page overview projection and View SKILL.md entry.

View file

@ -83,6 +83,9 @@ public class SkillPublishController extends BaseApiController {
@RequestParam(value = "avatarUploadId", required = false) String avatarUploadId,
@RequestParam(value = "expectedSlug", required = false) String expectedSlug,
@RequestParam(value = "displayName", required = false) String displayName,
@RequestParam(value = "shortDescription", required = false) String shortDescription,
@RequestParam(value = "overview", required = false) String overview,
@RequestParam(value = "resetPresentation", defaultValue = "false") boolean resetPresentation,
@AuthenticationPrincipal PlatformPrincipal principal, HttpServletRequest request) throws IOException {
SkillVisibility skillVisibility = SkillVisibility.valueOf(visibility.toUpperCase());
@ -110,7 +113,8 @@ public class SkillPublishController extends BaseApiController {
principal.userId(),
skillVisibility,
principal.platformRoles(),
confirmWarnings, avatarAction, avatarUploadId, expectedSlug, displayName, AuditRequestContext.from(request)
confirmWarnings, avatarAction, avatarUploadId, expectedSlug, displayName,
shortDescription, overview, resetPresentation, AuditRequestContext.from(request)
);
PublishResponse response = new PublishResponse(

View file

@ -4,10 +4,16 @@ import com.fasterxml.jackson.annotation.JsonInclude;
import com.iflytek.skillhub.domain.skill.validation.SkillExamplesSummary.Status;
/** Package defaults only: preview never creates a skill or changes its files. */
public record SkillPackagePreviewResponse(String name, String displayName, String description, String version,
public record SkillPackagePreviewResponse(String name, String displayName, String description, String shortDescription,
String overview, String version,
@JsonInclude(JsonInclude.Include.NON_NULL) Status examplesStatus,
@JsonInclude(JsonInclude.Include.NON_NULL) Integer examplesCount) {
public SkillPackagePreviewResponse(String name, String displayName, String description, String version,
Status examplesStatus, Integer examplesCount) {
this(name, displayName, description, description, null, version, examplesStatus, examplesCount);
}
public SkillPackagePreviewResponse(String name, String displayName, String description, String version) {
this(name, displayName, description, version, null, null);
this(name, displayName, description, description, null, version, null, null);
}
}

View file

@ -31,7 +31,8 @@ public class SkillPackagePreviewService {
.orElseThrow(() -> new DomainBadRequestException("error.skill.publish.skillMd.notFound"));
SkillMetadata metadata = parser.parse(new String(skillMd.content(), StandardCharsets.UTF_8));
SkillExamplesSummary examples = SkillExamplesSummary.recognize(entries);
return new SkillPackagePreviewResponse(metadata.name(), metadata.displayName(), metadata.description(), metadata.version(),
return new SkillPackagePreviewResponse(metadata.name(), metadata.displayName(), metadata.description(),
metadata.shortDescription(), metadata.overview(), metadata.version(),
examples.status(), examples.count());
}
}

View file

@ -42,13 +42,14 @@ public class SkillPublishAppService {
SkillVisibility visibility, Set<String> roles, boolean confirmWarnings, AvatarAction action,
String uploadId, String expectedSlug, AuditRequestContext context) {
return publish(namespace, entries, actor, visibility, roles, confirmWarnings, action,
uploadId, expectedSlug, null, context);
uploadId, expectedSlug, null, null, null, false, context);
}
@Transactional
public SkillPublishService.PublishResult publish(String namespace, List<PackageEntry> entries, String actor,
SkillVisibility visibility, Set<String> roles, boolean confirmWarnings, AvatarAction action,
String uploadId, String expectedSlug, String displayName, AuditRequestContext context) {
String uploadId, String expectedSlug, String displayName, String shortDescription,
String overview, boolean resetPresentation, AuditRequestContext context) {
if (action == AvatarAction.REPLACE && (uploadId == null || uploadId.isBlank())
|| action != AvatarAction.REPLACE && uploadId != null && !uploadId.isBlank()) {
throw new DomainBadRequestException("error.skill.avatar.invalidUpload");
@ -64,9 +65,13 @@ public class SkillPublishAppService {
uploads.validateReference(namespace, targetSlug, actor, uploadId);
}
}
SkillPublishService.PublishResult result = displayName == null || displayName.isBlank()
? publications.publishFromEntries(namespace, entries, actor, visibility, roles, confirmWarnings)
: publications.publishFromEntries(namespace, entries, actor, visibility, roles, confirmWarnings, displayName);
SkillPublishService.PublishResult result = (shortDescription == null || shortDescription.isBlank())
&& (overview == null || overview.isBlank()) && !resetPresentation
? (displayName == null || displayName.isBlank()
? publications.publishFromEntries(namespace, entries, actor, visibility, roles, confirmWarnings)
: publications.publishFromEntries(namespace, entries, actor, visibility, roles, confirmWarnings, displayName))
: publications.publishFromEntries(namespace, entries, actor, visibility, roles, confirmWarnings, displayName,
shortDescription, overview, resetPresentation);
var review = reviews.findBySkillVersionIdAndStatus(
result.version().getId(), ReviewTaskStatus.PENDING).orElse(null);
if (action == AvatarAction.REPLACE) {

View file

@ -320,7 +320,7 @@ public class PromotionService {
try {
SkillMetadata metadata = objectMapper.readValue(metadataJson, SkillMetadata.class);
target.setDisplayName(metadata.displayName());
target.setSummary(metadata.description());
target.setSummary(metadata.shortDescription());
} catch (Exception e) {
throw new IllegalStateException("Failed to deserialize skill metadata", e);
}

View file

@ -467,7 +467,7 @@ public class ReviewService {
try {
SkillMetadata metadata = objectMapper.readValue(metadataJson, SkillMetadata.class);
skill.setDisplayName(metadata.displayName());
skill.setSummary(metadata.description());
skill.setSummary(metadata.shortDescription());
} catch (Exception e) {
throw new IllegalStateException("Failed to deserialize skill metadata", e);
}

View file

@ -9,10 +9,35 @@ public record SkillMetadata(
String version,
String body,
Map<String, Object> frontmatter,
String displayNameOverride
String displayNameOverride,
String shortDescriptionOverride,
String overviewOverride,
String presentationInheritedFrom
) {
public SkillMetadata(String name, String description, String version, String body, Map<String, Object> frontmatter) {
this(name, description, version, body, frontmatter, null);
this(name, description, version, body, frontmatter, null, null, null, null);
}
public SkillMetadata(String name, String description, String version, String body, Map<String, Object> frontmatter,
String displayNameOverride) {
this(name, description, version, body, frontmatter, displayNameOverride, null, null, null);
}
public SkillMetadata withPresentation(String shortDescription, String overview, String inheritedFrom) {
String shortValue = normalize(shortDescription);
String overviewValue = normalize(overview);
if (shortValue != null && shortValue.length() > 200) {
throw new DomainBadRequestException("error.skill.shortDescription.tooLong", 200);
}
if (overviewValue != null && overviewValue.length() > 20000) {
throw new DomainBadRequestException("error.skill.overview.tooLong", 20000);
}
return new SkillMetadata(name, description, version, body, frontmatter, displayNameOverride,
shortValue, overviewValue, inheritedFrom);
}
private static String normalize(String value) {
return value == null || value.strip().isEmpty() ? null : value.strip();
}
/** Explicit portal input is validated before it becomes part of the version snapshot. */
@ -26,6 +51,24 @@ public record SkillMetadata(
override == null || override.isEmpty() ? null : override);
}
public String shortDescription() {
return shortDescriptionOverride != null ? shortDescriptionOverride
: nestedText(frontmatter, "short-description", description);
}
public String overview() {
String packageOverview = nestedText(frontmatter, "overview", null);
return overviewOverride != null ? overviewOverride : (packageOverview != null ? packageOverview : body);
}
private static String nestedText(Map<String, Object> values, String key, String fallback) {
if (values != null && values.get("metadata") instanceof Map<?, ?> metadata
&& metadata.get(key) instanceof String text && !text.strip().isEmpty()) {
return text.strip();
}
return fallback;
}
/** Human-readable label; unsupported legacy snapshot values fall back to the package name. */
public String displayName() {
if (displayNameOverride != null && !displayNameOverride.isBlank()

View file

@ -60,6 +60,14 @@ public class SkillMetadataParser {
}
validateDisplayName(frontmatter);
String shortDescription = extractNestedOptionalField(frontmatter, "metadata", "short-description");
String overview = extractNestedOptionalField(frontmatter, "metadata", "overview");
if (shortDescription != null && shortDescription.length() > 200) {
throw new DomainBadRequestException("error.skill.metadata.shortDescription.tooLong", 200);
}
if (overview != null && overview.length() > 20000) {
throw new DomainBadRequestException("error.skill.metadata.overview.tooLong", 20000);
}
return new SkillMetadata(name, description, version, body, frontmatter);
}

View file

@ -388,7 +388,7 @@ public class SkillGovernanceService {
try {
SkillMetadata metadata = objectMapper.readValue(metadataJson, SkillMetadata.class);
skill.setDisplayName(metadata.displayName());
skill.setSummary(metadata.description());
skill.setSummary(metadata.shortDescription());
} catch (Exception e) {
throw new IllegalStateException("Failed to deserialize skill metadata", e);
}

View file

@ -192,7 +192,7 @@ public class SkillLifecycleProjectionService {
version.getStatus().name(),
version.getParsedMetadataJson(),
metadata == null ? null : metadata.displayName(),
metadata == null ? null : metadata.description(),
metadata == null ? null : metadata.shortDescription(),
version.getGithubSyncRevision()
);
}

View file

@ -336,8 +336,17 @@ public class SkillPublishService {
String namespaceSlug, List<PackageEntry> entries, String publisherId,
SkillVisibility visibility, Set<String> platformRoles, boolean confirmWarnings,
String displayName) {
return publishFromEntries(namespaceSlug, entries, publisherId, visibility, platformRoles, confirmWarnings,
displayName, null, null, false);
}
@Transactional
public PublishResult publishFromEntries(
String namespaceSlug, List<PackageEntry> entries, String publisherId,
SkillVisibility visibility, Set<String> platformRoles, boolean confirmWarnings,
String displayName, String shortDescription, String overview, boolean resetPresentation) {
return publishFromEntriesInternal(namespaceSlug, entries, publisherId, visibility, platformRoles,
confirmWarnings, false, false, null, null, displayName);
confirmWarnings, false, false, null, null, displayName, shortDescription, overview, resetPresentation);
}
/** Publishes a validated GitHub package into the dedicated sync review queue. */
@ -450,10 +459,31 @@ public class SkillPublishService {
true,
null,
null,
displayNameOverrideForRerelease(publishedVersion)
displayNameOverrideForRerelease(publishedVersion),
presentationOverrideForRerelease(publishedVersion, "shortDescriptionOverride"),
presentationOverrideForRerelease(publishedVersion, "overviewOverride"),
presentationOverrideForRerelease(publishedVersion, "shortDescriptionOverride") == null
&& presentationOverrideForRerelease(publishedVersion, "overviewOverride") == null
);
}
private boolean hasPackagePresentation(SkillMetadata metadata) {
if (metadata.frontmatter() == null || !(metadata.frontmatter().get("metadata") instanceof Map<?, ?> values)) {
return false;
}
return values.get("short-description") instanceof String shortText && !shortText.isBlank()
|| values.get("overview") instanceof String overviewText && !overviewText.isBlank();
}
private String presentationOverrideForRerelease(SkillVersion source, String field) {
if (source.getParsedMetadataJson() == null) return null;
try {
return objectMapper.readTree(source.getParsedMetadataJson()).path(field).textValue();
} catch (java.io.IOException ignored) {
return null;
}
}
private String displayNameOverrideForRerelease(SkillVersion source) {
if (source.getParsedMetadataJson() == null) {
return null;
@ -499,6 +529,17 @@ public class SkillPublishService {
SkillVisibility visibility, Set<String> platformRoles, boolean confirmWarnings,
boolean forceAutoPublish, boolean bypassMembershipCheck,
BundlePublicationTarget bundleTarget, GithubSyncPublicationTarget syncTarget, String displayName) {
return publishFromEntriesInternal(namespaceSlug, entries, publisherId, visibility, platformRoles,
confirmWarnings, forceAutoPublish, bypassMembershipCheck, bundleTarget, syncTarget, displayName,
null, null, false);
}
private PublishResult publishFromEntriesInternal(
String namespaceSlug, List<PackageEntry> entries, String publisherId,
SkillVisibility visibility, Set<String> platformRoles, boolean confirmWarnings,
boolean forceAutoPublish, boolean bypassMembershipCheck,
BundlePublicationTarget bundleTarget, GithubSyncPublicationTarget syncTarget, String displayName,
String shortDescription, String overview, boolean resetPresentation) {
// 1. Find namespace by slug
Namespace namespace = namespaceRepository.findBySlug(namespaceSlug)
@ -538,6 +579,8 @@ public class SkillPublishService {
String skillMdContent = new String(skillMd.content());
SkillMetadata metadata = skillMetadataParser.parse(skillMdContent).withDisplayNameOverride(displayName);
metadata = metadata.withPresentation(resetPresentation ? null : shortDescription,
resetPresentation ? null : overview, null);
String upstreamVersion = syncTarget == null ? null : metadata.version();
if (syncTarget != null) {
// A reverted upstream package is a new review target after an intervening update.
@ -545,10 +588,13 @@ public class SkillPublishService {
String syncVersion = "0.0.0-g" + syncTarget.contentSha256().substring(0, 40)
+ "-" + syncTarget.ingestionId().toString().replace("-", "").substring(0, 16);
metadata = new SkillMetadata(metadata.name(), metadata.description(), syncVersion,
metadata.body(), metadata.frontmatter());
metadata.body(), metadata.frontmatter(), metadata.displayNameOverride(),
metadata.shortDescriptionOverride(), metadata.overviewOverride(), null);
} else if (metadata.version() == null || metadata.version().isBlank()) {
String autoVersion = AUTO_VERSION_FORMATTER.format(currentTime());
metadata = new SkillMetadata(metadata.name(), metadata.description(), autoVersion, metadata.body(), metadata.frontmatter(), metadata.displayNameOverride());
metadata = new SkillMetadata(metadata.name(), metadata.description(), autoVersion,
metadata.body(), metadata.frontmatter(), metadata.displayNameOverride(),
metadata.shortDescriptionOverride(), metadata.overviewOverride(), null);
}
String skillSlug = SlugValidator.slugify(metadata.name());
if (bundleTarget != null
@ -646,6 +692,32 @@ public class SkillPublishService {
newSkill = bundleTarget.expectedSkillId() == null;
}
if (!newSkill && skill.getLatestVersionId() != null && !resetPresentation
&& shortDescription == null && overview == null && !hasPackagePresentation(metadata)) {
SkillVersion published = skillVersionRepository.findBySkillIdAndStatus(
skill.getId(), SkillVersionStatus.PUBLISHED).stream()
.max(java.util.Comparator.comparing(SkillVersion::getPublishedAt,
java.util.Comparator.nullsLast(java.util.Comparator.naturalOrder()))
.thenComparing(SkillVersion::getCreatedAt,
java.util.Comparator.nullsLast(java.util.Comparator.naturalOrder()))
.thenComparing(SkillVersion::getId,
java.util.Comparator.nullsLast(java.util.Comparator.naturalOrder())))
.orElse(null);
if (published != null && published.getParsedMetadataJson() != null) {
try {
SkillMetadata previous = objectMapper.readerFor(SkillMetadata.class)
.without(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.readValue(published.getParsedMetadataJson());
if (previous.shortDescriptionOverride() != null || previous.overviewOverride() != null) {
metadata = metadata.withPresentation(previous.shortDescriptionOverride(),
previous.overviewOverride(), published.getVersion());
}
} catch (java.io.IOException e) {
throw new IllegalStateException("Failed to deserialize published skill metadata", e);
}
}
}
if (visibilityService != null) {
visibilityService.lockedSkill(skill.getId());
visibilityService.assertNoPendingVisibility(skill.getId());
@ -886,7 +958,7 @@ public class SkillPublishService {
// A pending update must not replace the currently published title or summary.
if (autoPublish || visibility == SkillVisibility.PRIVATE || skill.getLatestVersionId() == null) {
skill.setDisplayName(metadata.displayName());
skill.setSummary(metadata.description());
skill.setSummary(metadata.shortDescription());
}
if (syncTarget != null) {
skill.assignGithubSyncOwnership(publisherId);
@ -1150,6 +1222,9 @@ public class SkillPublishService {
parsedMetadata.put("body", metadata.body());
parsedMetadata.put("frontmatter", metadata.frontmatter());
parsedMetadata.put("displayNameOverride", metadata.displayNameOverride());
parsedMetadata.put("shortDescriptionOverride", metadata.shortDescriptionOverride());
parsedMetadata.put("overviewOverride", metadata.overviewOverride());
parsedMetadata.put("presentationInheritedFrom", metadata.presentationInheritedFrom());
if (syncTarget != null) {
parsedMetadata.put("upstreamVersion", upstreamVersion);
parsedMetadata.put("githubContentSha256", syncTarget.contentSha256());

View file

@ -672,7 +672,9 @@ class PromotionServiceTest {
Skill sourceSkill = createSourceSkill();
SkillVersion sourceVersion = createPublishedVersion();
sourceSkill.setLatestVersionId(999L);
sourceVersion.setParsedMetadataJson(selectedVersionMetadata(hasDisplayName));
sourceVersion.setParsedMetadataJson(selectedVersionMetadata(hasDisplayName)
.replace("\"description\":\"Old version summary\"",
"\"description\":\"Old version summary\",\"shortDescriptionOverride\":\"Selected custom summary\",\"overviewOverride\":\"# Selected overview\""));
when(promotionRequestRepository.findById(PROMOTION_ID))
.thenReturn(Optional.of(pr), Optional.of(approvedRequest));
@ -699,7 +701,10 @@ class PromotionServiceTest {
verify(skillRepository, times(2)).save(skillCaptor.capture());
Skill newSkill = skillCaptor.getAllValues().get(0);
assertEquals(hasDisplayName ? "旧版标题" : "包内标题", newSkill.getDisplayName());
assertEquals("Old version summary", newSkill.getSummary());
assertEquals("Selected custom summary", newSkill.getSummary());
ArgumentCaptor<SkillVersion> versionCaptor = ArgumentCaptor.forClass(SkillVersion.class);
verify(skillVersionRepository).save(versionCaptor.capture());
assertEquals(sourceVersion.getParsedMetadataJson(), versionCaptor.getValue().getParsedMetadataJson());
assertEquals(NEW_VERSION_ID, newSkill.getLatestVersionId());
}

View file

@ -304,7 +304,8 @@ class ReviewServiceTest {
assertDoesNotThrow(() -> sv.setParsedMetadataJson(objectMapper.writeValueAsString(
new SkillMetadata("Approved Name", "Approved Summary", "1.0.0", "Body",
hasDisplayName ? Map.of("metadata", Map.of("display-name", "包内标题")) : Map.of(),
hasDisplayName ? "已审核的中文标题" : null)
hasDisplayName ? "已审核的中文标题" : null,
"Approved custom summary", "# Approved overview", null)
)));
when(reviewTaskRepository.findById(REVIEW_TASK_ID)).thenReturn(Optional.of(task));
@ -333,7 +334,9 @@ class ReviewServiceTest {
assertEquals(SKILL_VERSION_ID, skill.getLatestVersionId());
assertEquals(hasDisplayName ? "已审核的中文标题" : "Approved Name", skill.getDisplayName());
assertEquals("my-skill", skill.getSlug());
assertEquals("Approved Summary", skill.getSummary());
assertEquals("Approved custom summary", skill.getSummary());
assertEquals("# Approved overview", assertDoesNotThrow(() ->
objectMapper.readTree(sv.getParsedMetadataJson())).path("overviewOverride").asText());
assertEquals(REVIEWER_ID, skill.getUpdatedBy());
verify(eventPublisher).publishEvent(any(SkillPublishedEvent.class));
verify(governanceNotificationService).notifyUser(eq(USER_ID), eq("REVIEW"), eq("REVIEW_TASK"), eq(REVIEW_TASK_ID), eq("Review approved"), any());

View file

@ -11,6 +11,31 @@ class SkillMetadataParserTest {
private final SkillMetadataParser parser = new SkillMetadataParser();
@Test
void presentationOverridesAndPackageDefaultsRemainDistinct() {
SkillMetadata source = parser.parse("---\nname: my-skill\ndescription: Original\nmetadata:\n short-description: Package short\n overview: Package overview\n---\nBody");
assertEquals("Package short", source.shortDescription());
assertEquals("Package overview", source.overview());
assertNull(source.shortDescriptionOverride());
assertNull(source.overviewOverride());
assertEquals("Original", source.withPresentation(null, null, null).description());
SkillMetadata reset = source.withPresentation("Web short", "Web overview", null)
.withPresentation(null, null, null);
assertNull(reset.shortDescriptionOverride());
assertNull(reset.overviewOverride());
assertEquals("Package short", reset.shortDescription());
assertEquals("Package overview", reset.overview());
SkillMetadata custom = source.withPresentation(" Web short ", " # Web overview ", null);
assertEquals("Web short", custom.shortDescription());
assertEquals("# Web overview", custom.overview());
assertEquals(source.frontmatter(), custom.frontmatter());
assertThrows(DomainBadRequestException.class,
() -> source.withPresentation("x".repeat(201), null, null));
assertThrows(DomainBadRequestException.class,
() -> source.withPresentation(null, "x".repeat(20001), null));
}
@Test
void platformOverrideIsVersionedWithoutChangingFrontmatter() throws Exception {
SkillMetadata source = parser.parse("---\nname: my-skill\ndescription: Test\nmetadata:\n display-name: 包内标题\n---\nBody");

View file

@ -297,6 +297,8 @@ class SkillGovernanceServiceTest {
fallback.setParsedMetadataJson(new ObjectMapper().writeValueAsString(Map.of(
"name", "example-skill",
"description", "Published summary from v1",
"shortDescriptionOverride", "Restored custom summary",
"overviewOverride", "# Restored overview",
"displayNameOverride", displayNameCase.equals("override") ? "网页旧版标题" : "",
"frontmatter", switch (displayNameCase) {
case "custom" -> Map.of("metadata", Map.of("display-name", "示例技能一"));
@ -321,7 +323,9 @@ class SkillGovernanceServiceTest {
assertThat(skill.getLatestVersionId()).isEqualTo(11L);
assertThat(skill.getDisplayName()).isEqualTo(displayNameCase.equals("override") ? "网页旧版标题" : displayNameCase.equals("custom") ? "示例技能一" : "example-skill");
assertThat(skill.getSummary()).isEqualTo("Published summary from v1");
assertThat(skill.getSummary()).isEqualTo("Restored custom summary");
assertThat(new ObjectMapper().readTree(fallback.getParsedMetadataJson()).path("overviewOverride").asText())
.isEqualTo("# Restored overview");
verify(skillRepository).save(skill);
}

View file

@ -118,6 +118,80 @@ class SkillPublishServiceTest {
}
}
@Test
void inheritsOnlyPublishedCustomPresentationAndFreezesSnapshot() throws Exception {
String content = "---\nname: test-skill\ndescription: New default\nversion: 2.0.0\n---\nBody";
PackageEntry entry = new PackageEntry("SKILL.md", content.getBytes(StandardCharsets.UTF_8),
content.length(), "text/markdown");
List<PackageEntry> entries = List.of(entry);
Namespace namespace = new Namespace("test-ns", "Test NS", "owner");
setId(namespace, 1L);
Skill skill = new Skill(1L, "test-skill", "owner", SkillVisibility.PUBLIC);
setId(skill, 1L);
skill.setSummary("Published custom");
skill.setLatestVersionId(11L);
SkillVersion previous = new SkillVersion(1L, "1.0.0", "owner");
setId(previous, 11L);
previous.setStatus(SkillVersionStatus.PUBLISHED);
previous.setParsedMetadataJson(objectMapper.writeValueAsString(Map.of(
"name", "test-skill", "description", "Old default", "version", "1.0.0",
"body", "Body", "frontmatter", Map.of(),
"shortDescriptionOverride", "Published custom", "overviewOverride", "# Custom overview",
"complianceSnapshot", Map.of("status", "PASS"))));
when(namespaceRepository.findBySlug("test-ns")).thenReturn(Optional.of(namespace));
when(namespaceMemberRepository.findByNamespaceIdAndUserId(1L, "owner"))
.thenReturn(Optional.of(mock(NamespaceMember.class)));
when(skillPackageValidator.validate(entries)).thenReturn(ValidationResult.pass());
when(skillMetadataParser.parse(content)).thenReturn(new SkillMetadata("test-skill", "New default", "2.0.0", "Body", Map.of()));
when(prePublishValidator.validate(any())).thenReturn(ValidationResult.pass());
when(skillRepository.findByNamespaceIdAndSlug(1L, "test-skill")).thenReturn(List.of(skill));
when(skillRepository.findByNamespaceIdAndSlugAndOwnerId(1L, "test-skill", "owner")).thenReturn(Optional.of(skill));
when(skillVersionRepository.findBySkillIdAndStatus(1L, SkillVersionStatus.PUBLISHED)).thenReturn(List.of(previous));
when(skillVersionRepository.save(any(SkillVersion.class))).thenAnswer(call -> {
SkillVersion version = call.getArgument(0);
if (version.getId() == null) setId(version, 12L);
return version;
});
SkillVersion pending = service.publishFromEntries("test-ns", entries, "owner", SkillVisibility.PUBLIC,
Set.of(), true, null, null, null, false).version();
assertEquals("Published custom", skill.getSummary());
assertEquals(SkillVersionStatus.PENDING_REVIEW, pending.getStatus());
JsonNode snapshot = objectMapper.readTree(pending.getParsedMetadataJson());
assertEquals("1.0.0", snapshot.path("presentationInheritedFrom").asText());
assertEquals("Published custom", snapshot.path("shortDescriptionOverride").asText());
assertEquals("# Custom overview", snapshot.path("overviewOverride").asText());
assertEquals("New default", snapshot.path("description").asText());
SkillVersion reset = service.publishFromEntries("test-ns", entries, "owner", SkillVisibility.PUBLIC,
Set.of(), true, null, null, null, true).version();
JsonNode resetSnapshot = objectMapper.readTree(reset.getParsedMetadataJson());
assertTrue(resetSnapshot.path("shortDescriptionOverride").isNull());
assertTrue(resetSnapshot.path("overviewOverride").isNull());
assertTrue(resetSnapshot.path("presentationInheritedFrom").isNull());
SkillMetadata restored = objectMapper.readerFor(SkillMetadata.class)
.without(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.readValue(reset.getParsedMetadataJson());
assertEquals("New default", restored.shortDescription());
assertEquals("Body", restored.overview());
assertEquals("Published custom", skill.getSummary());
previous.setParsedMetadataJson(objectMapper.writeValueAsString(
new SkillMetadata("test-skill", "Old default", "1.0.0", "Body", Map.of())));
SkillVersion defaults = service.publishFromEntries("test-ns", entries, "owner", SkillVisibility.PUBLIC,
Set.of(), true, null, null, null, false).version();
JsonNode defaultSnapshot = objectMapper.readTree(defaults.getParsedMetadataJson());
assertTrue(defaultSnapshot.path("shortDescriptionOverride").isNull());
assertTrue(defaultSnapshot.path("presentationInheritedFrom").isNull());
SkillVersion publishedReset = service.publishFromEntries("test-ns", entries, "owner", SkillVisibility.PUBLIC,
Set.of("SUPER_ADMIN"), true, null, null, null, true).version();
assertEquals(SkillVersionStatus.PUBLISHED, publishedReset.getStatus());
assertEquals("New default", skill.getSummary());
assertEquals("Body", objectMapper.readerFor(SkillMetadata.class)
.without(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
.<SkillMetadata>readValue(publishedReset.getParsedMetadataJson()).overview());
}
@Test
void testPublishFromEntries_Success() throws Exception {
// Arrange
@ -1025,13 +1099,14 @@ class SkillPublishServiceTest {
setId(skill, 11L);
skill.setDisplayName("Demo Skill");
skill.setSummary("Original summary");
skill.setLatestVersionId(21L);
Namespace namespace = new Namespace("global", "Global", "owner");
setId(namespace, 1L);
SkillVersion sourceVersion = new SkillVersion(skill.getId(), "1.2.3", publisherId);
setId(sourceVersion, 21L);
sourceVersion.setStatus(SkillVersionStatus.PUBLISHED);
sourceVersion.setParsedMetadataJson("{\"displayNameOverride\":\"原网页标题\"}");
sourceVersion.setParsedMetadataJson("{\"displayNameOverride\":\"原网页标题\",\"shortDescriptionOverride\":\"Custom summary\",\"overviewOverride\":\"# Custom overview\"}");
sourceVersion.setPublishedAt(Instant.parse("2026-03-15T10:00:00Z"));
String sourceSkillMd = """
@ -1062,6 +1137,8 @@ class SkillPublishServiceTest {
when(skillFileRepository.findByVersionId(sourceVersion.getId())).thenReturn(List.of(skillMdFile, readmeFile));
when(objectStorageService.getObject(skillMdFile.getStorageKey())).thenReturn(new java.io.ByteArrayInputStream(sourceSkillMd.getBytes(StandardCharsets.UTF_8)));
when(objectStorageService.getObject(readmeFile.getStorageKey())).thenReturn(new java.io.ByteArrayInputStream(readmeBytes));
when(skillRepository.findByNamespaceIdAndSlugAndOwnerId(1L, "demo-skill", publisherId))
.thenReturn(Optional.of(skill));
when(skillPackageValidator.validate(anyList())).thenReturn(ValidationResult.pass());
when(skillMetadataParser.parse(anyString())).thenReturn(rereleaseMetadata);
when(prePublishValidator.validate(any())).thenReturn(ValidationResult.pass());
@ -1085,6 +1162,9 @@ class SkillPublishServiceTest {
assertEquals("1.2.4", result.version().getVersion());
assertEquals("原网页标题", objectMapper.readTree(result.version().getParsedMetadataJson()).path("displayNameOverride").asText());
assertEquals("Custom summary", objectMapper.readTree(result.version().getParsedMetadataJson()).path("shortDescriptionOverride").asText());
assertEquals("# Custom overview", objectMapper.readTree(result.version().getParsedMetadataJson()).path("overviewOverride").asText());
assertEquals("Original summary", skill.getSummary(), "Pending rerelease must not change the public summary");
// Rerelease for PUBLIC skill should go to PENDING_REVIEW (respecting visibility rules)
assertEquals(SkillVersionStatus.PENDING_REVIEW, result.version().getStatus());
// Review task should be created for PUBLIC skill

View file

@ -123,13 +123,19 @@ public class PostgresSearchRebuildService implements SearchRebuildService {
private SearchIndexPayload buildSearchPayload(Skill skill) {
List<String> searchParts = new ArrayList<>();
addPart(searchParts, skill.getSlug());
addPart(searchParts, skill.getDisplayName());
addPart(searchParts, skill.getSummary());
Set<String> keywords = new TreeSet<>();
resolveLatestVersion(skill)
.map(this::extractParsedMetadata)
.ifPresent(metadata -> {
appendFrontmatter(asMap(metadata.get("frontmatter")), keywords, searchParts);
addPart(searchParts, String.valueOf(metadata.get("description")));
Map<String, Object> frontmatter = new LinkedHashMap<>(asMap(metadata.get("frontmatter")));
Map<String, Object> packageMetadata = new LinkedHashMap<>(asMap(frontmatter.get("metadata")));
packageMetadata.remove("overview");
frontmatter.put("metadata", packageMetadata);
appendFrontmatter(frontmatter, keywords, searchParts);
appendComplianceSnapshot(
asMap(metadata.get(ComplianceMetadataService.SNAPSHOT_FIELD_NAME)),
keywords,

View file

@ -31,6 +31,31 @@ import static org.mockito.Mockito.when;
class PostgresSearchRebuildServiceTest {
@Test
void rebuildBySkill_indexesEffectiveSummaryAndOriginalDescriptionButNotOverview() {
SkillRepository skills = mock(SkillRepository.class);
NamespaceRepository namespaces = mock(NamespaceRepository.class);
SkillVersionRepository versions = mock(SkillVersionRepository.class);
SearchIndexService index = mock(SearchIndexService.class);
Skill skill = new Skill(7L, "slug", "owner", SkillVisibility.PUBLIC);
skill.setDisplayName("Custom title");
skill.setSummary("Custom short");
skill.setLatestVersionId(99L);
SkillVersion version = new SkillVersion(1L, "1.0.0", "owner");
version.setParsedMetadataJson("""
{"description":"Original package description","frontmatter":
{"metadata":{"overview":"Private detail-only text"}}}
""");
when(skills.findById(7L)).thenReturn(Optional.of(skill));
when(namespaces.findById(7L)).thenReturn(Optional.of(new Namespace("team", "Team", "owner")));
when(versions.findById(99L)).thenReturn(Optional.of(version));
newService(skills, namespaces, versions, index).rebuildBySkill(7L);
ArgumentCaptor<SkillSearchDocument> captor = ArgumentCaptor.forClass(SkillSearchDocument.class);
verify(index).index(captor.capture());
assertThat(captor.getValue().searchText()).contains("Custom title", "Custom short", "Original package description")
.doesNotContain("Private detail-only text");
}
@Test
void rebuildBySkill_shouldIndexFrontmatterFieldsAndKeywordsWithoutBody() {
SkillRepository skillRepository = mock(SkillRepository.class);

View file

@ -8187,6 +8187,8 @@ export interface components {
name?: string;
displayName?: string;
description?: string;
shortDescription?: string;
overview?: string;
version?: string;
/** @enum {string} */
examplesStatus?: "ready" | "none" | "invalid";
@ -15503,6 +15505,9 @@ export interface operations {
avatarUploadId?: string;
expectedSlug?: string;
displayName?: string;
shortDescription?: string;
overview?: string;
resetPresentation?: boolean;
};
header?: never;
path: {
@ -15539,6 +15544,9 @@ export interface operations {
avatarUploadId?: string;
expectedSlug?: string;
displayName?: string;
shortDescription?: string;
overview?: string;
resetPresentation?: boolean;
};
header?: never;
path: {

View file

@ -1450,6 +1450,7 @@
"accessDeniedDesc": "You don't have permission to view this skill",
"tabReadme": "README",
"tabOverview": "Overview",
"viewSkillMd": "View SKILL.md",
"tabFiles": "Files",
"tabVersions": "Versions",
"noReadme": "No README",
@ -2235,6 +2236,10 @@
"displayName": "Display name",
"displayNamePlaceholder": "For example: Meeting notes assistant",
"displayNameHelp": "Up to 200 characters. Defaults to the package title. Changes follow this version’s review and do not alter the identifier or package files. Leave blank to use the package title.",
"shortDescription": "Short description",
"overview": "Detailed overview (Markdown)",
"presentationInheritance": "Without web or package presentation values, custom values from published version {{version}} are inherited when submitted.",
"resetPresentation": "Restore package defaults (do not inherit)",
"readingPackage": "Reading package metadata…",
"examplesReady": "Recognized {{count}} task examples across all languages.",
"examplesNone": "No task examples provided. Publishing and use remain available.",

View file

@ -1728,6 +1728,7 @@
"accessDeniedDesc": "이 스킬을 볼 권한이 없습니다",
"tabReadme": "README",
"tabOverview": "개요",
"viewSkillMd": "SKILL.md 보기",
"tabFiles": "파일",
"tabVersions": "버전",
"noReadme": "README 없음",
@ -2516,6 +2517,10 @@
"displayName": "표시 이름",
"displayNamePlaceholder": "예: 회의록 도우미",
"displayNameHelp": "최대 200자이며 기본값은 패키지 제목입니다. 변경 사항은 이 버전의 검토를 따르며 식별자나 패키지 파일을 변경하지 않습니다. 비워 두면 패키지 제목을 사용합니다.",
"shortDescription": "짧은 설명",
"overview": "상세 개요 (Markdown)",
"presentationInheritance": "웹과 패키지에 값이 없으면 제출 시 게시된 버전 {{version}}의 사용자 지정 값을 상속합니다.",
"resetPresentation": "패키지 기본값으로 복원 (상속 안 함)",
"readingPackage": "패키지 메타데이터를 읽는 중…",
"examplesReady": "전체 언어에서 작업 예제 {{count}}개를 인식했습니다.",
"examplesNone": "제공된 작업 예제가 없습니다. 게시와 사용은 계속 가능합니다.",

View file

@ -1515,6 +1515,7 @@
"accessDeniedDesc": "У вас нет прав на просмотр этого скилла",
"tabReadme": "README",
"tabOverview": "Обзор",
"viewSkillMd": "Открыть SKILL.md",
"tabFiles": "Файлы",
"tabVersions": "Версии",
"noReadme": "Нет README",
@ -2224,6 +2225,10 @@
"displayName": "Отображаемое имя",
"displayNamePlaceholder": "Например: Помощник для протоколов встреч",
"displayNameHelp": "До 200 символов. По умолчанию — имя из пакета. Изменения проходят проверку версии и не меняют идентификатор или файлы пакета. Пустое поле означает имя из пакета.",
"shortDescription": "Краткое описание",
"overview": "Подробный обзор (Markdown)",
"presentationInheritance": "Если значения не указаны на сайте и в пакете, при отправке наследуются пользовательские значения опубликованной версии {{version}}.",
"resetPresentation": "Вернуть значения пакета (без наследования)",
"readingPackage": "Чтение метаданных пакета…",
"examplesReady": "Распознано примеров задач на всех языках: {{count}}.",
"examplesNone": "Примеры задач не предоставлены. Публикация и использование доступны.",

View file

@ -1450,6 +1450,7 @@
"accessDeniedDesc": "您没有权限查看该技能",
"tabReadme": "README",
"tabOverview": "概览",
"viewSkillMd": "查看 SKILL.md",
"tabFiles": "文件",
"tabVersions": "版本",
"noReadme": "暂无 README",
@ -2234,6 +2235,10 @@
"displayName": "显示名称",
"displayNamePlaceholder": "例如:会议纪要助手",
"displayNameHelp": "支持中文,最多 200 个字符。默认读取包内名称;修改后随本次版本审核,不改变技能标识或包内文件。留空则使用包内名称。",
"shortDescription": "简短描述",
"overview": "详细概览(Markdown)",
"presentationInheritance": "本次未填写网页或包内展示值时,将在提交时继承已发布版本 {{version}} 的自定义值。",
"resetPresentation": "恢复包内默认值(不继承)",
"readingPackage": "正在读取技能包信息…",
"examplesReady": "已识别 {{count}} 条使用案例(包含全部语种)。",
"examplesNone": "未提供使用案例,可正常发布和使用。",

View file

@ -5,13 +5,15 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
const preview = vi.hoisted(() => vi.fn())
const publish = vi.hoisted(() => vi.fn())
vi.mock('@tanstack/react-router', () => ({ useNavigate: () => vi.fn(), useSearch: () => ({ namespace: 'team-ai' }) }))
const searchParams = vi.hoisted(() => ({ value: { namespace: 'team-ai', updateSkill: undefined as string | undefined } }))
vi.mock('@tanstack/react-router', () => ({ useNavigate: () => vi.fn(), useSearch: () => searchParams.value }))
vi.mock('react-i18next', async () => ({ ...await vi.importActual<typeof import('react-i18next')>('react-i18next'), useTranslation: () => ({ t: (key: string) => key }) }))
vi.mock('@/shared/hooks/use-skill-queries', () => ({ useSkillDetail: () => ({ data: undefined }), previewSkillPackage: preview, usePublishSkill: () => ({ mutateAsync: publish, isPending: false }) }))
vi.mock('@/shared/hooks/use-namespace-queries', () => ({ useMyNamespaces: () => ({ data: [{ id: 1, slug: 'team-ai', displayName: 'Team' }], isLoading: false }) }))
vi.mock('@/features/publish/upload-zone', () => ({ UploadZone: ({ onFileSelect }: { onFileSelect: (file: File) => void }) => <input aria-label="package" type="file" onChange={e => { if (e.target.files?.[0]) onFileSelect(e.target.files[0]) }} /> }))
vi.mock('@/features/skill/skill-avatar-editor', () => ({ KEEP_AVATAR: { action: 'KEEP', ready: true }, SkillAvatarEditor: () => null }))
vi.mock('@/features/skill/skill-avatar-manager', () => ({ SkillAvatarManager: () => null }))
vi.mock('@/api/client', async (importOriginal) => ({ ...await importOriginal<typeof import('@/api/client')>(), skillAvatarApi: { status: vi.fn().mockResolvedValue({ action: 'KEEP' }) } }))
vi.mock('@/shared/lib/navigate-after-overlays', () => ({ navigateAfterOverlays: (action: () => void) => action() }))
vi.mock('@/shared/lib/toast', () => ({ toast: { success: vi.fn(), error: vi.fn() } }))
import { PublishPage } from './publish'
@ -27,7 +29,44 @@ function select(name: string) {
const metadata = (name: string) => ({ name: 'stable-slug', displayName: name, version: '1.0.0', description: 'summary' })
afterEach(cleanup)
beforeEach(() => { preview.mockReset(); publish.mockReset(); publish.mockResolvedValue({ namespace: 'team-ai', slug: 'stable-slug', version: '1.0.0', status: 'PENDING_REVIEW' }) })
beforeEach(() => { searchParams.value.updateSkill = undefined; preview.mockReset(); publish.mockReset(); publish.mockResolvedValue({ namespace: 'team-ai', slug: 'stable-slug', version: '1.0.0', status: 'PENDING_REVIEW' }) })
describe('web presentation publishing', () => {
it('prefills package presentation without sending unedited defaults', async () => {
preview.mockResolvedValue({ ...metadata('Package title'), shortDescription: 'Package short', overview: '# Package overview' })
mount(); select('presentation.zip')
await waitFor(() => expect((screen.getByLabelText('publish.shortDescription') as HTMLInputElement).value).toBe('Package short'))
expect((screen.getByLabelText('publish.overview') as HTMLTextAreaElement).value).toBe('# Package overview')
fireEvent.click(screen.getByRole('button', { name: 'publish.confirm' }))
await waitFor(() => expect(publish).toHaveBeenCalledWith(expect.objectContaining({
shortDescription: undefined, overview: undefined, resetPresentation: false,
})))
})
it('sends edited presentation and reset intent independently of form defaults', async () => {
preview.mockResolvedValue({ ...metadata('Package title'), shortDescription: 'Package short', overview: '# Package overview' })
mount(); select('presentation.zip')
await waitFor(() => expect((screen.getByLabelText('publish.shortDescription') as HTMLInputElement).value).toBe('Package short'))
fireEvent.change(screen.getByLabelText('publish.shortDescription'), { target: { value: 'Web short' } })
fireEvent.change(screen.getByLabelText('publish.overview'), { target: { value: '# Web overview' } })
fireEvent.click(screen.getByRole('button', { name: 'publish.confirm' }))
await waitFor(() => expect(publish).toHaveBeenCalledWith(expect.objectContaining({
shortDescription: 'Web short', overview: '# Web overview', resetPresentation: false,
})))
})
it('sends reset without re-sending edited fields', async () => {
searchParams.value.updateSkill = 'stable-slug'
preview.mockResolvedValue({ ...metadata('Package title'), shortDescription: 'Package short', overview: '# Package overview' })
mount(); select('presentation.zip')
await waitFor(() => expect((screen.getByLabelText('publish.shortDescription') as HTMLInputElement).value).toBe('Package short'))
fireEvent.change(screen.getByLabelText('publish.shortDescription'), { target: { value: 'Discard me' } })
fireEvent.click(screen.getByRole('checkbox', { name: 'publish.resetPresentation' }))
fireEvent.click(screen.getByRole('button', { name: 'publish.confirm' }))
await waitFor(() => expect(publish).toHaveBeenCalledWith(expect.objectContaining({
shortDescription: undefined, overview: undefined, resetPresentation: true,
})))
})
})
describe('web display name publishing', () => {
it('prefills from the package and sends the explicit edited name with the original file', async () => {

View file

@ -22,6 +22,7 @@ import {
normalizeSelectValue,
} from '@/shared/ui/select'
import { Input } from '@/shared/ui/input'
import { Textarea } from '@/shared/ui/textarea'
import { Label } from '@/shared/ui/label'
import { Card } from '@/shared/ui/card'
import { SkillAvatarEditor, KEEP_AVATAR, type AvatarEdit } from '@/features/skill/skill-avatar-editor'
@ -52,7 +53,12 @@ export function PublishPage() {
const previewId = useId()
const [fileRevision, setFileRevision] = useState(0)
const [displayName, setDisplayName] = useState('')
const [shortDescription, setShortDescription] = useState('')
const [overview, setOverview] = useState('')
const [resetPresentation, setResetPresentation] = useState(false)
const displayNameEdited = useRef(false)
const shortDescriptionEdited = useRef(false)
const overviewEdited = useRef(false)
const [selectedFile, setSelectedFile] = useState<File | null>(null)
const [namespaceSlug, setNamespaceSlug] = useState<string>(prefill.namespace)
const [visibility, setVisibility] = useState<string>(prefill.visibility)
@ -75,6 +81,12 @@ export function PublishPage() {
if (packagePreview.data && !displayNameEdited.current) {
setDisplayName(packagePreview.data.displayName ?? packagePreview.data.name ?? '')
}
if (packagePreview.data && !shortDescriptionEdited.current) {
setShortDescription(packagePreview.data.shortDescription ?? packagePreview.data.description ?? '')
}
if (packagePreview.data && !overviewEdited.current) {
setOverview(packagePreview.data.overview ?? '')
}
}, [packagePreview.data])
const avatarTarget = useQuery({ queryKey: ['skill-avatar', namespaceSlug, updateSlug], queryFn: () => skillAvatarApi.status(namespaceSlug, updateSlug), enabled: !!namespaceSlug && !!updateSlug })
const avatarUnavailable = !!updateSlug && (avatarTarget.isLoading || avatarTarget.isError)
@ -100,6 +112,11 @@ export function PublishPage() {
const handleFileSelect = (file: File | null) => {
setSelectedFile(file)
shortDescriptionEdited.current = false
overviewEdited.current = false
setShortDescription('')
setOverview('')
setResetPresentation(false)
setFileRevision(value => value + 1)
setPrecheckWarnings([])
setWarningDialogOpen(false)
@ -148,6 +165,9 @@ export function PublishPage() {
avatarUploadId: avatarEdit.uploadId,
expectedSlug: updateSlug || undefined,
displayName,
shortDescription: resetPresentation ? undefined : shortDescriptionEdited.current ? shortDescription : undefined,
overview: resetPresentation ? undefined : overviewEdited.current ? overview : undefined,
resetPresentation,
})
setPrecheckWarnings([])
setWarningDialogOpen(false)
@ -348,6 +368,24 @@ export function PublishPage() {
{selectedFile && packagePreview.data?.examplesStatus === 'invalid' && <p role="status" className="text-xs text-muted-foreground">{t('publish.examplesInvalid')}</p>}
</div>
<div className="space-y-2">
<Label htmlFor="skill-short-description">{t('publish.shortDescription')}</Label>
{isUpdate && updateTarget?.publishedVersion?.version && !resetPresentation && (
<p className="text-sm text-muted-foreground">{t('publish.presentationInheritance', { version: updateTarget.publishedVersion.version })}</p>
)}
{isUpdate && <label className="flex items-center gap-2 text-sm">
<input type="checkbox" checked={resetPresentation} onChange={event => setResetPresentation(event.target.checked)} />
{t('publish.resetPresentation')}
</label>}
<Input id="skill-short-description" maxLength={200} value={shortDescription} disabled={ownerReadOnly || isBusy || !selectedFile}
onChange={event => { shortDescriptionEdited.current = true; setShortDescription(event.target.value) }} />
</div>
<div className="space-y-2">
<Label htmlFor="skill-overview">{t('publish.overview')}</Label>
<Textarea id="skill-overview" maxLength={20000} rows={8} value={overview} disabled={ownerReadOnly || isBusy || !selectedFile}
onChange={event => { overviewEdited.current = true; setOverview(event.target.value) }} />
</div>
<SkillAvatarEditor key={`${namespaceSlug}/${updateSlug}`} name={search.updateName ?? updateSlug} currentUrl={avatarTarget.data?.avatarUrl} canRemove={!!updateSlug} disabled={ownerReadOnly || isBusy || avatarUnavailable} onChange={setAvatarEdit} />
{updateSlug && <SkillAvatarManager namespace={namespaceSlug} slug={updateSlug} disabled={ownerReadOnly || isBusy} />}
{avatarTarget.isError && <p role="alert" className="text-sm text-destructive">{t('skillAvatar.failed')}</p>}

View file

@ -19,6 +19,7 @@ const useSkillVersionsMock = vi.fn()
const useSkillFilesMock = vi.fn()
const useSkillReadmeMock = vi.fn()
const useSkillFileMock = vi.fn()
const useSkillVersionDetailMock = vi.fn()
const usePromotionSourceStateMock = vi.fn()
const submitPromotionMock = vi.fn()
const submitRevocationMock = vi.fn()
@ -208,7 +209,7 @@ vi.mock('@/shared/hooks/use-skill-queries', () => ({
useAttachSkillLabel: () => ({ mutate: vi.fn(), isPending: false }),
useDetachSkillLabel: () => ({ mutate: vi.fn(), isPending: false }),
useSkillVersions: (...args: unknown[]) => useSkillVersionsMock(...args),
useSkillVersionDetail: () => ({ data: undefined }),
useSkillVersionDetail: (...args: unknown[]) => useSkillVersionDetailMock(...args),
useSkillFiles: (...args: unknown[]) => useSkillFilesMock(...args),
useSkillReadme: (...args: unknown[]) => useSkillReadmeMock(...args),
useSkillFile: (...args: unknown[]) => useSkillFileMock(...args),
@ -301,6 +302,8 @@ describe('SkillDetailPage', () => {
useSkillFilesMock.mockReset()
useSkillReadmeMock.mockReset()
useSkillFileMock.mockReset()
useSkillVersionDetailMock.mockReset()
useSkillVersionDetailMock.mockReturnValue({ data: undefined })
toastMocks.success.mockReset()
toastMocks.error.mockReset()
hasRoleMock.mockImplementation((role: string) => role === 'USER')
@ -1013,6 +1016,19 @@ describe('SkillDetailPage', () => {
expect(html).toContain('leading-snug')
})
it('renders the selected snapshot overview and opens the packaged SKILL.md separately', () => {
useSkillVersionDetailMock.mockReturnValue({ data: { parsedMetadataJson: JSON.stringify({
name: 'demo-skill', description: 'Original description', shortDescriptionOverride: 'Selected summary',
overviewOverride: '# Selected overview',
}) } })
useSkillFilesMock.mockReturnValue({ data: [createSkillFile('README.md'), createSkillFile('SKILL.md')] })
render(<SkillDetailPage />)
expect(screen.getByText('markdown:# Selected overview')).toBeTruthy()
expect(screen.queryByText('markdown:# Demo')).toBeNull()
fireEvent.click(screen.getByRole('button', { name: 'skillDetail.viewSkillMd' }))
expect(screen.getByRole('dialog').textContent).toContain('preview:SKILL.md')
})
it('opens a file preview when overview markdown relative link matches a package file', () => {
useSkillFilesMock.mockReturnValue({
data: [

View file

@ -205,7 +205,7 @@ export function SkillDetailPage() {
const selectedMetadata = selectedVersion === ownerPreviewVersion?.version ? ownerPreviewVersion
: selectedVersion === publishedVersion?.version ? publishedVersion
: selectedVersion === headlineVersion?.version ? headlineVersion : null
const { data: selectedVersionDetail } = useSkillVersionDetail(qns, qslug, selectedVersion, skillReady && !selectedMetadata)
const { data: selectedVersionDetail } = useSkillVersionDetail(qns, qslug, selectedVersion, skillReady)
const historicalMetadata = getVersionPresentation(selectedVersionDetail?.parsedMetadataJson)
const selectedDisplayName = selectedMetadata?.displayName ?? historicalMetadata.displayName ?? skill?.displayName
const selectedSummary = selectedMetadata?.summary ?? historicalMetadata.summary ?? skill?.summary
@ -214,6 +214,7 @@ export function SkillDetailPage() {
const { data: files } = useSkillFiles(qns, qslug, selectedVersion, skillReady)
const documentationPath = resolveDocumentationFilePath(files)
const { data: readme, error: readmeError } = useSkillReadme(qns, qslug, selectedVersion, documentationPath, skillReady)
const renderedDocumentation = historicalMetadata.overview ?? readme
const { data: previewContent, isLoading: isLoadingPreview, error: previewError } = useSkillFile(
qns,
qslug,
@ -988,9 +989,15 @@ export function SkillDetailPage() {
</TabsList>
<TabsContent value="readme" className="mt-6">
{readme ? (
{files?.find(file => file.filePath === 'SKILL.md') && (
<Button type="button" variant="outline" className="mb-4" onClick={() => {
const skillFile = files.find(file => file.filePath === 'SKILL.md')
if (skillFile) handleFileClick(createPackageFilePreviewNode(skillFile))
}}>{t('skillDetail.viewSkillMd')}</Button>
)}
{renderedDocumentation ? (
<Card className="p-8 space-y-4">
{documentationPath ? (
{!historicalMetadata.overview && documentationPath ? (
<div className="text-xs uppercase tracking-[0.2em] text-muted-foreground">
{t('skillDetail.documentationSource', { path: documentationPath })}
</div>
@ -1004,7 +1011,7 @@ export function SkillDetailPage() {
style={!isOverviewExpanded && isOverviewCollapsible ? { maxHeight: `${overviewMaxHeight}px` } : undefined}
>
<div ref={overviewContentRef}>
<MarkdownRenderer content={readme} onLinkClick={handleOverviewLinkClick} />
<MarkdownRenderer content={renderedDocumentation} onLinkClick={handleOverviewLinkClick} />
</div>
{!isOverviewExpanded && isOverviewCollapsible ? (
<div className="pointer-events-none absolute inset-x-0 bottom-0 h-28 bg-gradient-to-t from-card via-card/95 to-transparent" />

View file

@ -45,7 +45,7 @@ async function getSkillDocumentation(namespace: string, slug: string, version: s
return fetchText(`${WEB_API_PREFIX}/skills/${cleanNamespace}/${encodeURIComponent(slug)}/versions/${encodeURIComponent(version)}/file?path=${encodeURIComponent(path)}`)
}
async function publishSkill(params: { namespace: string; file: File; visibility: string; confirmWarnings?: boolean; avatarAction?: 'KEEP' | 'REPLACE' | 'REMOVE'; avatarUploadId?: string; expectedSlug?: string; displayName?: string }): Promise<PublishResult> {
async function publishSkill(params: { namespace: string; file: File; visibility: string; confirmWarnings?: boolean; avatarAction?: 'KEEP' | 'REPLACE' | 'REMOVE'; avatarUploadId?: string; expectedSlug?: string; displayName?: string; shortDescription?: string; overview?: string; resetPresentation?: boolean }): Promise<PublishResult> {
const cleanNamespace = params.namespace.startsWith('@') ? params.namespace.slice(1) : params.namespace
const formData = new FormData()
formData.append('file', params.file)
@ -54,7 +54,10 @@ async function publishSkill(params: { namespace: string; file: File; visibility:
formData.append('avatarAction', params.avatarAction ?? 'KEEP')
if (params.avatarUploadId) formData.append('avatarUploadId', params.avatarUploadId)
if (params.expectedSlug) formData.append('expectedSlug', params.expectedSlug)
if (params.displayName?.trim()) formData.append('displayName', params.displayName.trim())
if (params.displayName !== undefined) formData.append('displayName', params.displayName)
if (params.shortDescription !== undefined) formData.append('shortDescription', params.shortDescription)
if (params.overview !== undefined) formData.append('overview', params.overview)
if (params.resetPresentation) formData.append('resetPresentation', 'true')
return fetchJson<PublishResult>(`${WEB_API_PREFIX}/skills/${cleanNamespace}/publish`, {
method: 'POST',

View file

@ -2,6 +2,15 @@ import { describe, expect, it } from 'vitest'
import { getVersionPresentation } from './version-presentation'
describe('historical version presentation', () => {
it('reads package defaults without treating them as overrides', () => {
expect(getVersionPresentation(JSON.stringify({
name: 'slug', description: 'Original', frontmatter: { metadata: { 'short-description': 'Package short', overview: '# Package overview' } },
}))).toEqual({ displayName: 'slug', summary: 'Package short', overview: '# Package overview' })
expect(getVersionPresentation(JSON.stringify({
name: 'slug', description: 'New default', shortDescriptionOverride: 'Frozen custom', overviewOverride: '# Frozen',
presentationInheritedFrom: '1.0.0', frontmatter: {},
}))).toEqual({ displayName: 'slug', summary: 'Frozen custom', overview: '# Frozen' })
})
it('uses the explicit version override before original package metadata', () => {
expect(getVersionPresentation(JSON.stringify({ name: 'slug', description: '旧版摘要', displayNameOverride: ' 网页名 ', frontmatter: { metadata: { 'display-name': '包内名' } } })))
.toEqual({ displayName: '网页名', summary: '旧版摘要' })

View file

@ -1,5 +1,5 @@
/** Read legacy version snapshots without rewriting the package or trusting arbitrary JSON. */
export function getVersionPresentation(snapshot?: string): { displayName?: string; summary?: string } {
export function getVersionPresentation(snapshot?: string): { displayName?: string; summary?: string; overview?: string } {
if (!snapshot) return {}
try {
const value: unknown = JSON.parse(snapshot)
@ -8,7 +8,15 @@ export function getVersionPresentation(snapshot?: string): { displayName?: strin
const metadata = isObject(frontmatter.metadata) ? frontmatter.metadata : {}
const displayName = validName(value.displayNameOverride) ?? validName(metadata['display-name'])
?? (typeof value.name === 'string' ? value.name : undefined)
return { displayName, summary: typeof value.description === 'string' ? value.description : undefined }
const overview = typeof value.overviewOverride === 'string' && value.overviewOverride.trim().length > 0
? value.overviewOverride.trim()
: typeof metadata.overview === 'string' && metadata.overview.trim().length > 0 ? metadata.overview.trim() : undefined
const summary = typeof value.shortDescriptionOverride === 'string' && value.shortDescriptionOverride.trim().length > 0
? value.shortDescriptionOverride.trim()
: typeof metadata['short-description'] === 'string' && metadata['short-description'].trim().length > 0
? metadata['short-description'].trim()
: typeof value.description === 'string' ? value.description : undefined
return overview ? { displayName, summary, overview } : { displayName, summary }
} catch {
return {}
}