Skip to content

[ISSUE #14997] fix(skill): keep SKILL.md indent and validate version - #15155

Merged
KomachiSion merged 1 commit into
alibaba:developfrom
saynoword:fix/frontmatter-serialization-problem
May 14, 2026
Merged

KomachiSion merged 1 commit into
alibaba:developfrom
saynoword:fix/frontmatter-serialization-problem

Conversation

@saynoword

Copy link
Copy Markdown
Contributor

Please do not create a Pull Request without creating an issue first.

What is the purpose of the change

Fix issue #14997: after uploading a SKILL.md with YAML frontmatter and downloading it back, nested keys lose their indentation and get promoted to top-level keys (e.g. metadata.version becomes a top-level version), breaking the YAML hierarchy. While investigating, also close a related inconsistency in the upload path: version values sourced from the SKILL.md frontmatter, the bundled _meta.json, or the targetVersion request parameter were never format-checked, so non-semver values like latest could silently land in storage — even though the same value supplied through resolveSpecifiedDraftVersion was already rejected.

Brief changelog

  • SkillRequestUtil#updateFrontmatterField now preserves the matched line's leading whitespace when rewriting, so nested keys are no longer promoted to top-level.
  • SkillOperationServiceImpl#resolveUploadVersion calls a new validateUploadVersionFormat helper before returning at every source (frontmatter version, metadata.version, _meta.json, targetVersion).
  • Invalid versions throw NacosApiException(INVALID_PARAM, PARAMETER_VALIDATE_ERROR); the error message identifies the source (SKILL.md frontmatter / _meta.json / targetVersion parameter) and includes the offending value.
  • Added 5 unit tests (3 in SkillRequestUtilTest covering nested indent preservation, nested value update, and top-level regression guard; 2 in SkillOperationServiceImplTest covering invalid frontmatter and invalid targetVersion rejection). Corrected the existing testUploadSkillFromZipUsesFrontmatterMetadataVersion to use a valid 1.0.0 instead of the malformed 1.0.

Verifying this change

  • mvn -pl ai test -Dtest=SkillRequestUtilTest — 28 tests pass (25 existing + 3 new)
  • mvn -pl ai test -Dtest=SkillOperationServiceImplTest — 66 tests pass (64 existing + 2 new)
  • mvn -pl ai spotless:check checkstyle:check — pass

Follow this checklist to help us incorporate your contribution quickly and easily:

  • Make sure there is a Github issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a Github issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue.
  • Format the pull request title like [ISSUE #123] Fix UnknownException when host config not exist. Each commit in the pull request should have a meaningful subject line and body.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Write necessary unit-test to verify your logic correction, more mock a little better when cross module dependency exist. If the new feature or significant change is committed, please remember to add integration-test in test module.
  • Run mvn -B clean package apache-rat:check spotbugs:check -DskipTests to make sure basic checks pass. Run mvn clean install -DskipITs to make sure unit-test pass. Run mvn clean test-compile failsafe:integration-test to make sure integration-test pass.

…ersion

When updating a YAML frontmatter field on upload/download round trip,
SkillRequestUtil#updateFrontmatterField now preserves the original
line's leading whitespace, so nested keys such as metadata.version are
no longer promoted to a top-level key (which previously corrupted the
SKILL.md structure reported in alibaba#14997).

Additionally, SkillOperationServiceImpl#resolveUploadVersion now
rejects version values that are not x.y.z or vN from any source
(SKILL.md frontmatter, _meta.json, or the targetVersion request
parameter). This closes the gap where invalid values like "latest"
sourced from frontmatter could silently land in storage while the
same value supplied via targetVersion was already rejected by
resolveSpecifiedDraftVersion.

Assisted-by: Claude Code
@github-actions

Copy link
Copy Markdown

Thanks for your this PR. 🙏
Please check again for your PR changes whether contains any usage/api/configuration change such as Add new API , Add new configuration, Change default value of configuration.
If so, please add or update documents(markdown type) in docs/next/ for repository nacos-group/nacos-group.github.io


感谢您提交的PR。 🙏
请再次查看您的PR内容,确认是否包含任何使用方式/API/配置参数的变更,如:新增API、新增配置参数、修改默认配置等操作。
如果是,请确保在提交之前,在仓库nacos-group/nacos-group.github.io中的docs/next/目录下添加或更新文档(markdown格式)。

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...a/com/alibaba/nacos/ai/utils/SkillRequestUtil.java 80.00% 0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

@KomachiSion KomachiSion added this to the 3.2.2 milestone May 14, 2026
@KomachiSion KomachiSion added kind/bug Category issues or prs related to bug. area/Skill labels May 14, 2026
@KomachiSion
KomachiSion merged commit e483ec0 into alibaba:develop May 14, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/Skill kind/bug Category issues or prs related to bug.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

v3.2.1 skill上传后下载,SKILL.md和之前不符,建议立即修复

3 participants